Uport library breaking change
The next version 1.5.3 of our Uport mobile app introduces two important changes (one of them breaking), with accompanying changes to the libraries developers use to connect with their users’ Uport app.
In this post I will briefly explain the changes we’re making as well as what you should do if you are writing apps using Uport.
Encrypted Push Notifications
As people are starting to roll out production applications using Uport, we had to improve both the reliability of our push notification support as well as encrypt messages being passed along.
For more details see our article Adventures in “Decentralized” Push Notifications.
To support encrypted push notifications, you must upgrade uport-connect@next and/or uport@next depending on which library is your primary way of connecting to uport.
The new app will be backwards compatible with older libraries for sending push notifications for the time being. However the benefits of upgrading are very real, including much more stable and secure push notifications than with the old app.
JWT timestamp changes
We use JWTs (RFC 7519 JSON Web Tokens) to communicate in a secure manner between apps and the Uport mobile app. These are used for everything from logging in and verifying identity information to authenticating to servers.
When we originally implemented JWTs we made a mistake with the format of standard JWT timestamps. Timestamps are used in JWTs for iat (issued at) and exp (expires at) fields. The JWT spec requires them to be NumericDate.
A JSON numeric value representing the number of seconds from 1970–01–01T00:00:00Z UTC until the specified UTC date/time, ignoring leap seconds.
We mistakenly interpreted those as milliseconds, as that is what javascript and other libraries default to. A colleague pointed this out and we realized the mistake. So, how do you fix a serious bug like this?
We considered how important it was to change this, but we are strong believers in standards and want other people to write libraries connecting to Uport in languages that we don't currently support. By not following this standard, developers will be unable to do so.
Unfortunately we were unable to make it fully backwards compatible, but we believe it's best to fix the error early. So the rule is that version 1.5.3 of the mobile app will be able to consume and produce both seconds (the new correct way) as well as milliseconds (the old incorrect way).
The new versions of the libraries can consume both methods, but only produce JWT's using the new seconds format. The libraries are integrated in websites and other mobile apps and initiate the login process, which is why we can't sense if the mobile app is a new or old version before creating the JWT.
When should I upgrade?
There are a few different cases. See where you fit as a developer:
Do you have existing users that you can’t expect to upgrade overnight?
Wait for a few weeks to upgrade the libraries in your app, until you can be reasonably sure people have upgraded. The new app is backwards compatible with the existing libraries.
Important demo/Talk/Hackathon/POC in the upcoming weeks?
Don’t upgrade the libraries unless you need the new features, such as more stable and encrypted push notifications.
Currently developing
You should upgrade your libraries when you have access to the new App, so you can start using the new features.
Uport Mobile App
The new app will likely reach iOS users on the Apple App Store and Android users on the Google Play Store before November 1st.
Uport libraries
The uport npm libraries uport@0.6.0-alpha-4 and uport-connect@0.7.0-alpha-1 both support the new encryption libraries and can also be installed using their respective next tags.
Uport-connect
Most developers use uport-connect to integrate in their browser front end. If you installed uport-connect before you can install both the correct libraries using the @next tag
npm:
npm install uport-connect@nextYarn:
yarn add uport-connect@nextYou can also change the entry for uport-connect in your package.json like this:
"uport-connect": "next",Uport
Most developers use uport-connect to integrate in their browser front end. If you installed uport-connect before, you can install both the correct libraries using the @next tag
npm:
npm install uport@nextYarn:
yarn add uport@nextYou can also change the entry for uport in your package.json like this:
"uport-connect": "next",
