Skip to content

Latest commit

 

History

History
241 lines (202 loc) · 7.24 KB

ARCHITECTURE.md

File metadata and controls

241 lines (202 loc) · 7.24 KB
Raw

Overview

Components

  • Nest.js (Microservices/REST API)
  • Redis (Events/WebSockets)
  • MongoDB (SessionStore/Users)

This service uses FIDO2 REST API endpoints for credential creation and assertions.

FIDO2 Endpoints

Two main components, Assertion and Attestation. The purposed liquid extension is used to sign the FIDO2 responses with a different key pair and allow remote authentication

Liquid FIDO2 Extension

// Authenticator Create Response
interface LiquidClientAttestationExtensionResults {
  liquid: {
    type: string; // Currently only "algorand" supported
    address: string; // Wallet Address
    signature: string; // Base64URL Encoded Signature
    requestId?: string // Optional Request ID , authenticate a remote user simaltaneously
    device?: string // Optional Device Name
  }
}
// Authenticator Get Response
interface LiquidClientAssertionExtensionResults {
  liquid: {
    requestId?: string; // Optional Request ID
  }
}

// Selector Options
interface LiquidExtensionOptions {
  liquid: boolean;
}

POST /attestation/request

Returns the credential creation options supported by the service. It accepts the standard PublicKeyCreateOptions as the body. The response can be passed to an available authenticator which will generate the credentials.

The request must enable the liquid extension in order to sign the response.

BODY

{
  "username": "2SPDE6XLJNXFTOO7OIGNRNKSEDOHJWVD3HBSEAPHONZQ4IQEYOGYTP6LXA",
  "displayName": "Liquid Auth User",
  "authenticatorSelection": {
    "userVerification": "required"
  },
  "extensions": {
    "liquid": true
  }
}

Example CredentialCreateOptions Response

{
  "challenge": "35JYpoXGnM4s8IICakWSLllcXy3Z_lc3AaLSl872qXM",
  "rp": {
    "name": "Algorand Foundation FIDO2 Server",
    "id": "catfish-pro-wolf.ngrok-free.app"
  },
  "user": {
    "id": "2SPDE6XLJNXFTOO7OIGNRNKSEDOHJWVD3HBSEAPHONZQ4IQEYOGYTP6LXA",
    "name": "2SPDE6XLJNXFTOO7OIGNRNKSEDOHJWVD3HBSEAPHONZQ4IQEYOGYTP6LXA",
    "displayName": "2SPDE6XLJNXFTOO7OIGNRNKSEDOHJWVD3HBSEAPHONZQ4IQEYOGYTP6LXA"
  },
  "pubKeyCredParams": [
    {
      "type": "public-key",
      "alg": -7
    },
    {
      "type": "public-key",
      "alg": -257
    }
  ],
  "timeout": 1800000,
  "attestation": "none",
  "excludeCredentials": [],
  "authenticatorSelection": {
    "userVerification": "required"
  },
  "extensions": {
    "liquid": true
  }
}

POST /attestation/response

Receives the PublicKeyCredential result from the authenticator and validates the credential signature. body uses base64URL encoding for keys.

The authenticator must include the liquid extension in the response with the signature and address. This will associate the credential with the wallet address and the credential can be used for future assertions without the need for signing with the wallet keys

BODY

{
  "id": "AYMPi2Rbhcnu2gSHOO1TNvzDJ38iU00rrlCqyH874XCIEoIotRc7eVRFpx0TvsQurg7BAnXy5KnWdKC8LeWs0k0",
  "type": "public-key",
  "rawId": "AYMPi2Rbhcnu2gSHOO1TNvzDJ38iU00rrlCqyH874XCIEoIotRc7eVRFpx0TvsQurg7BAnXy5KnWdKC8LeWs0k0",
  "clientExtensionResults": {
    "liquid": {
      "type": "algorand",
      "requestId": "019097ff-bb8c-7c42-9700-f11b9446fad7",
      "address": "2SPDE6XLJNXFTOO7OIGNRNKSEDOHJWVD3HBSEAPHONZQ4IQEYOGYTP6LXA",
      "signature": "QY31mdH8AwpJ9p4pCXBO2iA5WdU-BjG52xEtJNuSJNHJIaJ10uzqk3FdR0fvYVfb_rzXTuWn4k1PFFeg-vpEDw",
      "device": "Pixel 8 Pro"
    }
  },
  "response": {
    "clientDataJSON": "eyJ0eXBlIjoid2ViYXV0aG4uY3JlYXRlIiwiY2hhbGxlbmdlIjoiMzVKWXBvWEduTTRzOElJQ2FrV1NMbGxjWHkzWl9sYzNBYUxTbDg3MnFYTSIsIm9yaWdpbiI6ImFuZHJvaWQ6YXBrLWtleS1oYXNoOlI4eE83cmxRV2FXTDRCbEZ5Z3B0V1JiNXFjS1dkZmp6WklhU1JpdDlYVnciLCJhbmRyb2lkUGFja2FnZU5hbWUiOiJmb3VuZGF0aW9uLmFsZ29yYW5kLmRlbW8ifQ",
    "attestationObject": "o2NmbXRkbm9uZWdhdHRTdG10oGhhdXRoRGF0YVjFlpPmT7RcYTDeFJdKhDtiKwzb05n-ojlcqqYw5SomXZBFAAAAAAAAAAAAAAAAAAAAAAAAAAAAQQGDD4tkW4XJ7toEhzjtUzb8wyd_IlNNK65Qqsh_O-FwiBKCKLUXO3lURacdE77ELq4OwQJ18uSp1nSgvC3lrNJNpQECAyYgASFYIB2dcp3wanhReRhgRIpJCUfRSwkCvyE9OdvEL_NlncSJIlggkSIz7h7O5nrAXGJrkCOmeolChSc09eHzniCFLFxaKH0"
  },
  "device": "Pixel 8 Pro"
}

POST /assertion/request/:credId

Request a PublicKeyGetCredentialOptions from the service. This differs slightly from the FIDO2 API conformance in order to limit allowed credentials.

BODY (Optional)

{
  "authenticatorSelection": {
    "userVerification": "required"
  },
  "extensions": {
    "liquid": true
  }
}

Example Response

{
  "challenge": "0TXu4G4iu3sbAQopheoPe_CpnLJOB-QlIUvwFBC317Q",
  "allowCredentials": [
    {
      "id": "AYMPi2Rbhcnu2gSHOO1TNvzDJ38iU00rrlCqyH874XCIEoIotRc7eVRFpx0TvsQurg7BAnXy5KnWdKC8LeWs0k0",
      "type": "public-key"
    }
  ],
  "timeout": 1800000,
  "userVerification": "required",
  "rpId": "catfish-pro-wolf.ngrok-free.app",
  "extensions": {
    "liquid": true
  }
}

POST /assertion/response

Base64URL encoded response from the authenticator. Optionally add a requestId to also authenticate a remote session

BODY

 {
  "id": "AYMPi2Rbhcnu2gSHOO1TNvzDJ38iU00rrlCqyH874XCIEoIotRc7eVRFpx0TvsQurg7BAnXy5KnWdKC8LeWs0k0",
  "type": "public-key",
  "rawId": "AYMPi2Rbhcnu2gSHOO1TNvzDJ38iU00rrlCqyH874XCIEoIotRc7eVRFpx0TvsQurg7BAnXy5KnWdKC8LeWs0k0",
  "clientExtensionResults": {
    "liquid": {
      "requestId": "019097ff-bb8d-75d8-b950-33de977c2d3f"
    }
  },
  "response": {
    "clientDataJSON": "eyJ0eXBlIjoid2ViYXV0aG4uZ2V0IiwiY2hhbGxlbmdlIjoiMFRYdTRHNGl1M3NiQVFvcGhlb1BlX0NwbkxKT0ItUWxJVXZ3RkJDMzE3USIsIm9yaWdpbiI6ImFuZHJvaWQ6YXBrLWtleS1oYXNoOlI4eE83cmxRV2FXTDRCbEZ5Z3B0V1JiNXFjS1dkZmp6WklhU1JpdDlYVnciLCJhbmRyb2lkUGFja2FnZU5hbWUiOiJmb3VuZGF0aW9uLmFsZ29yYW5kLmRlbW8ifQ",
    "authenticatorData": "lpPmT7RcYTDeFJdKhDtiKwzb05n-ojlcqqYw5SomXZAFAAAAAQ",
    "signature": "MEUCIQDcV2y6ub3Qh8pyTCCLdWKRH_cmR2xlFuNy1Fn1QsSUygIgTZh9b6mB77C-aQrBj7Evb8u3S4j3vjlnSPAKcR7Kld4"
  }
}

Example Response

{
  "id": "M6RT4iT5FkNDM2i57MXzBhLDt9zl2CrLt2p4Ar03t2Q",
  "wallet": "2SPDE6XLJNXFTOO7OIGNRNKSEDOHJWVD3HBSEAPHONZQ4IQEYOGYTP6LXA",
  "credentials": [
    {
      "device": "Pixel 8 Pro",
      "publicKey": "pQECAyYgASFYIB2dcp3wanhReRhgRIpJCUfRSwkCvyE9OdvEL_NlncSJIlggkSIz7h7O5nrAXGJrkCOmeolChSc09eHzniCFLFxaKH0",
      "credId": "AYMPi2Rbhcnu2gSHOO1TNvzDJ38iU00rrlCqyH874XCIEoIotRc7eVRFpx0TvsQurg7BAnXy5KnWdKC8LeWs0k0",
      "prevCounter": 0
    }
  ]
}

Signaling Service

The signaling service is used to establish a WebRTC connection between the wallet and the website.

Events

microservice:auth

Emits to the event bus when a client attests or asserts a credential with a requestId.

wss:link

Submit a request to link the current client to a remote wallet. The server will acknowledge the request when the microservice:auth event is received.

const response: LinkMessage = await client.link(requestId)

wss:offer-description | wss:answer-description

Wait for the server to emit an offer or answer description to the client.

const response: string = await client.signal('offer' | 'answer')

wss:offer-candidate | wss:answer-candidate

Emits the offer or answer ICE Candidates to connected clients.

client.peerClient.onicecandidate=(event)=>{
  client.socket.emit('offer-candidate', event.candidate.toJSON())
}