Create Impact Assessment for login to external website EPIC

theblockstalk commented 1 year ago

Definition of done

Impact assessment created for EPIC

How to create an impact assessment

theblockstalk commented 1 year ago

New: Tonomy Communication service

repo with nestjs server service which sets up websockets connections to DIDs and allows them to send messages to each other

service API:

/* any client with a DID can request to create a connection, which sets up a websocket connection
 * authorization is done by verifying a VC with the origin of the client, signed by the DID
 * creates a structure in memory that links the DIDUrl of the authorizer, with the websocket
 * 
 * @params authoriation - a VC signed by the DID that wants to connect. VC payload only contains origin of the client
 */
login(authorization: AuthorizationMessage)

/* receives a message in an existing authorized websocket connection
 * validates the Message (VC)
 * uses the VC.sub property to determine the recipient
 * if there is a websocket channel for the recipient (a DID URL) then send the message in that channel, otherwise drop the message and send a error back to the client
 */
relayMessage(message: Message)

Question? what happens if someone sets up an unauthorized websocket connection???

we should create a middleware class/function that validates Messages (see SDK Message class below)

Tonomy Contracts

QUESTION: should we support MFA with BOTH pin and fingerprint, or just either or none? then we need to have a new permission pinorbiometric

Tonomy ID SDK

npmjs

publish SDK
needs to include a .css bundle that can be used to create styles "Login with Tonomy ID button"
- available https://unpkg.com/@tonomy/sdk/dist/tonomy.min.css from the published SDK package

/docs Readthedocs

instructions to add Tonomy ID button to website

implementations

Update: User class

// constructor needs to inject new Communication object
constructor(_keyManager: KeyManager, storageFactory: StorageFactory)

// new static function to check if user is already logged into website (by checking if keys exist in storage) and if so creates User object. If keys in storage are invalid will delete them.
User.loginFromStorage(): Promise<User>

// UPDATE
// to use VC instead of did-jwt with `vc` property as payload (medium priority)
verifyLoginJWT() onRedirectLogin() verifyRequests() onPressLogin()

New class: Communication

/* - sets up connection to key manager, and lets it know which key (which should not require a challenge) to sign messages with
 * e.g. for Tonomy ID, this will use KeyManagerLevel.LOCAL
 */
Communication(keyManager: KeyManager, keyLevel: KeyManagerLevel)

/* connects to the Tonomy Communication server, authenticates with it's DID
 * subscribes to any messages that are sent by `sendMessage` by providing a callback function executed every time a message is received
 * should send a read receipt when messages are received
 * @returns true if successful
 */ 
login(authorization: AuthorizationMessage): Promise<boolean>

/* sends a message to another DID
 * create a Message object from the message argument
 * the message is used as the `vc` property of a VC signed by the User's key
 */
sendMessage(recipient: didUrl, message: object): Promise<{status: 'recieved' | 'sent' | 'receivedRecipient'}>

// function that adds a new subscriber, which is called every time a message is received
subscribeMessage(subscriber: Subscriber)

// unsubscribes a function from the receiving a message
unsubscribeMessage(subscriber: Subscriber) 

type Subscriber: (message: Message) => Promise<void>

New class: Message

/* Creates a new Message object, containing a VC signed by the Signer
 * the message argument is used as the `vc` parameter of the VC
 */
Message(message: object, signer: Signer)

// Creates a Message object from a jwt string
from(jwt: string): Message

// Returns the sender of the message (iss property of the signed VC)
getSender(): didUrl

// Returns the recipient of the message (sub property of the signed VC)
getRecipient(): didUrl

// Returns the original unsigned payload
getPayload(): object

// Returns the message type (ignores VerifiableCredential type). This is used to determine what kind of message it is (login request, login request confirmation etc...) so the client can choose what to do with it
getType(): string

/* Verifies the VC. True if valid
 * this is setup to resolve did:antelope and did:jwk DIDs
 */
verify(): Promise<boolean>

Tonomy ID Demo

Screens

/* UPDATE
 * (on load) implement `User.loginFromStorage()`
 * implement `user.logout()` and add button to call this, so that we can test the . DESIGN task?
 */
HomeScreen()

/* UPDATE
 * handle errors from the URL
 */
CallbackScreen()

Tonomy ID Login

Navigation based on connection callback

/* Handles messages received from Tonomy Communication, from Tonomy ID
 * calls Message.geType() to figure out what to do with it
 * if message type = login request confirmation
 * - redirect user back to external website. send success or failure flag
*/
communicationCallback(sender: didUrl, message: Message): Promise<void>

Screens

/* NEW
 * screen that tells user they need to take action on their phone
 * 
 */
WaitingForUserActionScreen()

/* UPDATE
 * call `Connection.connect()` with a did:jwk to setup connection to Tonomy Communication
 */
QRCodeScan()

Tonomy ID

QUESTION: should we support MFA with BOTH pin and fingerprint, or just either or none?

Update: Navigation based on login request with callback. Make a new service?

// UPDATE
// when app starts, if user is logged in, calls `user.communication.connect()` with callback function (below)
App()

/* Handles messages received from Tonomy Communication
 * calls Message.geType() to figure out what to do with it
- if message type = login request
  - if use has Tonomy ID app open, navigate user to the login request screen
  - if not, create a local push notification that when clicked will take the user to the login request screen
*/
communicationCallback(sender: didUrl, message: Message): Promise<void>

Screens

/* UPDATE
 * check if the request asks for a PIN challenge and if so than navigate to PIN screen after consent accepted
 * if it asks for PIN and Biometric, then nativate the PIN with flag to navigate to Biometric after
 * if the request Biometric challenge then navigate to Biometric
 * if no request for challenge, call App.loginwithapp() with local authorization
 * 
 * if user cancels, then Communication.sendMessage() with message that user cancelled, navigate back to UserHome screen
 * check if the user already gave consent and if so, navigate to next challenge or login
 * 
 * If the app is not registered, show an error and redirect user back to UserHome, send error message to Login website
 */
SSOLoginContainer()

/* NEW
 * if accepted and no Biometric requested, call App.loginwithapp() with PIN authorization
 * if accepted and Biometric requested, navigate to biometric
 * if user presses back, send back to SSOLoginScreen
 */
PINChallengeContainer()

/* NEW
 * if accepted and no PIN requested, call App.loginwithapp() with biometric authorization
 * if accepted and PIN requested, navigate to biometricandpin
 * if user presses back, send back to SSOLoginScreen or PINChallengeScreen
 */
BiometricChallengeContainer()

theblockstalk commented 1 year ago

Did NOT handle edge cases as this seems quite enough already. Suggest move to separate epic

kamitor commented 1 year ago

Rebal should get points for this; 50 -50

Tonomy-Foundation / Tonomy-ID-Management