VIP-03-0080: Using JSON Web Tokens (JWTs) With AVM Accounts

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "JSON Web Token (JWT) Header",
  "type": "object",
  "properties": {
    "alg": {
      "description": "Defines the cryptographic algorithm used to create the JWS",
      "type": "string"
    },
    "crv": {
      "description": "Defines the subtype, or the name of the curve used by the cryptographic algorithm",
      "type": "string"
    },
    "kty": {
      "description": "Defines the cryptographic algorithm family the cryptographic algorithm belongs to",
      "type": "string"
    },
    "typ": {
      "description": "Defines the media type of the JWT",
      "type": "string"
    },
    "x": {
      "description": "The public key of the AVM account and is used to verify that the JWS has been signed with the correct private key of an AVM account",
      "type": "string"
    }
  },
  "required": [
    "alg",
    "crv",
    "x"
  ]
}

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "JSON Web Token (JWT) Payload",
  "type": "object",
  "properties": {
    "aud": {
      "description": "Defines the intended recipient(s) of the JWT",
      "anyOf": [
        {
          "type": "string"
        },
        {
          "format": "uri",
          "type": "string"
        },
        {
          "type": "array",
          "items": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "format": "uri",
                "type": "string"
              }
            ]
          }
        }
      ]
    },
    "exp": {
      "description": "Defines the date/time the JWT expires",
      "type": "number"
    },
    "iat": {
      "description": "Defines the date/time this JWT the issued",
      "type": "number"
    },
    "iss": {
      "description": "Defines the entity that issued the JWT",
      "oneOf": [
        {
          "type": "string"
        },
        {
          "format": "uri",
          "type": "string"
        }
      ]
    },
    "jti": {
      "description": "A unique identifier for the JWT that is used to prevent the same JWT being replayed",
      "type": "string"
    },
    "nbf": {
      "description": "Defines the date/time after which the JWT becomes valid",
      "type": "number"
    },
    "sub": {
      "description": "Defines the subject of the JWT",
      "type": "string"
    }
  }
}

{
  "alg": "EdDSA",
  "crv": "Ed25519",
  "kty": "OKP",
  "typ": "JWT",
  "x": "FrMUY1-U6zLa5xz3r0RUmILVwqyIY30HX4JWEXTN2grk9Djs"
}

{
  "aud": "https://api.awesome.com",
  "exp": 1707782400,
  "iat": 1707696000,
  "iss": "https://dapp.awesome.com",
  "jti": "22080a89-a283-48e7-96c5-87f17ce7a850",
  "nbf": 1707739200,
  "sub": "C2ZRIY27STVTFWXHDT326RCUTCBNLQVMRBRX2B27QJLBC5GN3IFOJ5BY5Q"
}

import { decodeAddress, mnemonicToSecretKey } from 'algosdk';
import { sign } from 'tweetnacl';

// get the address and private key from the 25-word mnemonic seed phrase
const { addr, sk } = mnemonicToSecretKey('outside ancient world angry income move street brother patrol exist pet act banner quiz analyst gym build action dwarf direct castle coin fault absorb symptom');
const encodedPublicKey: string = Buffer.from(decodeAddress(addr).publicKey).toString('base64url');
const header: string = JSON.stringify({
  alg: 'EdDSA',
  crv: 'Ed25519',
  kty: 'OKP',
  typ: 'JWT',
  x: encodedPublicKey, // 7Ad4Xw3aG1dDLbcI5In9O7Pehd9xodPMvD0dHHTxXnE
});
const payload: string = JSON.stringify({
  aud: 'https://api.awesome.com',
  exp: 1707782400,
  iat: 1707696000,
  iss: 'https://dapp.awesome.com',
  jti: '22080a89-a283-48e7-96c5-87f17ce7a850',
  nbf: 1707739200,
  sub: addr, // 5QDXQXYN3INVOQZNW4EOJCP5HOZ55BO7OGQ5HTF4HUORY5HRLZYYLIY7MU
});
const encodedHeader: string = Buffer.from(header).toString('base64url');
const encodedPayload: string = Buffer.from(payload).toString('base64url');
const signature: Uint8Array = sign.detached(
  new TextEncoder().encode(`${encodedHeader}.${encodedPayload}`),
  sk, // sign with the avm account's private key
);
const encodedSignature: string = Buffer.from(signature).toString('base64url');

console.log(`json web token: ${encodedHeader}.${encodedPayload}.${encodedSignature}`);
/*
json web token: eyJhbGciOiJFZERTQSIsImNydiI6IkVkMjU1MTkiLCJrdHkiOiJPS1AiLCJ0eXAiOiJKV1QiLCJ4IjoiN0FkNFh3M2FHMWRETGJjSTVJbjlPN1BlaGQ5eG9kUE12RDBkSEhUeFhuRSJ9.eyJhdWQiOlsiaHR0cHM6Ly9hcGkuYXdlc29tZS5jb20iXSwiZXhwIjoiMjAyNC0wMi0xM1QwMDowMDowMFoiLCJqdGkiOiIyMjA4MGE4OS1hMjgzLTQ4ZTctOTZjNS04N2YxN2NlN2E4NTAiLCJpYXQiOiIyMDI0LTAyLTEyVDAwOjAwOjAwWiIsImlzcyI6Imh0dHBzOi8vZGFwcC5hd2Vzb21lLmNvbSIsIm5iZiI6IjIwMjQtMDItMTJUMTI6MDA6MDBaIiwic3ViIjoiNVFEWFFYWU4zSU5WT1FaTlc0RU9KQ1A1SE9aNTVCTzdPR1E1SFRGNEhVT1JZNUhSTFpZWUxJWTdNVSJ9.5S2MHI8LPC2cy5yv3ISNgulaEhpVk22JKyNxKi2J_uuqWCMacHgs27RuVlQbyipFlbc7z0p3AiRtxFcK8j-FCw
 */

import { decodeAddress, mnemonicToSecretKey } from 'algosdk';
import { sign } from 'tweetnacl';

const [encodedHeader, encodedPayload, encodedSignature] = jwt.split('.');
const decodedHeader: Uint8Array = Buffer.from(encodedHeader, 'base64url');
const decodedSignature: Uint8Array = Buffer.from(encodedSignature, 'base64url');
const { x } = JSON.parse(decodedHeader.toString()); // get the "x" parameter; the public key, from the header
const decodedPublicKey: Uint8Array = Buffer.from(x, 'base64url');
const isVerified: boolean = sign.detached.verify(
  new TextEncoder().encode(`${encodedHeader}.${encodedPayload}`), // re-create the jose header that was signed using the token's encoded header and payload
  decodedSignature,
  decodedPublicKey,
);

console.log('is verified: ', isVerified);
/*
is verified: true
 */

package main

import (
  "encoding/base64"
  "encoding/json"
  "fmt"
  "github.com/algorand/go-algorand-sdk/v2/crypto"
  "github.com/algorand/go-algorand-sdk/v2/mnemonic"
  "golang.org/x/crypto/ed25519"
  "log"
  "time"
)

type Header struct {
  Algorithm string `json:"alg"`
  Curve     string `json:"crv,omitempty"`
  KeyType   string `json:"kty,omitempty"`
  Type      string `json:"typ,omitempty"`
  PublicKey string `json:"x"`
}
type RegisteredClaims struct {
  Audience  []string  `json:"aud,omitempty"`
  ExpiresAt time.Time `json:"exp,omitempty"`
  ID        string    `json:"jti,omitempty"`
  IssuedAt  time.Time `json:"iat,omitempty"`
  Issuer    string    `json:"iss,omitempty"`
  NotBefore time.Time `json:"nbf,omitempty"`
  Subject   string    `json:"sub,omitempty"`
}

func main() string {
  // get the address and private key from the 25-word mnemonic seed phrase
  privateKey, err := mnemonic.ToPrivateKey("outside ancient world angry income move street brother patrol exist pet act banner quiz analyst gym build action dwarf direct castle coin fault absorb symptom")
  if err != nil {
   log.Fatal(err)
  }

  account, err := crypto.AccountFromPrivateKey(privateKey)
  if err != nil {
    log.Fatal(err)
  }

  address := account.Address.String()

  // encode the public in base64 url safe
  encodedPublicKey := base64.RawURLEncoding.EncodeToString(privateKey.Public().(ed25519.PublicKey))

  header, err := json.Marshal(Header{
    Algorithm: "EdDSA",
    Curve:     "Ed25519",
    KeyType:   "OKP",
    Type:      "JWT",
    PublicKey: encodedPublicKey,
  })
  if err != nil {
    log.Fatal(err)
  }

  // encode the header in base64 url safe
  encodedHeader := base64.RawURLEncoding.EncodeToString(header)

  payload, err := json.Marshal(RegisteredClaims{
    Audience:  []string{"https://api.awesome.com"},
    ExpiresAt: time.Unix(1707782400, 0),
    ID:        "22080a89-a283-48e7-96c5-87f17ce7a850",
    IssuedAt:  time.Unix(1707696000, 0),
    Issuer:    "https://dapp.awesome.com",
    NotBefore: time.Unix(1707739200, 0),
    Subject:   address, // 5QDXQXYN3INVOQZNW4EOJCP5HOZ55BO7OGQ5HTF4HUORY5HRLZYYLIY7MU
  })
  if err != nil {
    log.Fatal(err)
  }

  // encode the payload in base64 url safe
  encodedPayload := base64.RawURLEncoding.EncodeToString(payload)

  signature := ed25519.Sign(
    privateKey, // sign with the avm account's private key
    []byte(fmt.Sprintf("%s.%s", encodedHeader, encodedPayload)),
  )

  // encode the signature in base64 url safe
  encodedSignature := base64.RawURLEncoding.EncodeToString(signature)

  token := fmt.Sprintf("%s.%s.%s", encodedHeader, encodedPayload, encodedSignature)

  fmt.Println(fmt.Sprintf("json web token: %s", token))

  /*
    json web token: eyJhbGciOiJFZERTQSIsImNydiI6IkVkMjU1MTkiLCJrdHkiOiJPS1AiLCJ0eXAiOiJKV1QiLCJ4IjoiN0FkNFh3M2FHMWRETGJjSTVJbjlPN1BlaGQ5eG9kUE12RDBkSEhUeFhuRSJ9.eyJhdWQiOlsiaHR0cHM6Ly9hcGkuYXdlc29tZS5jb20iXSwiZXhwIjoiMjAyNC0wMi0xM1QwMDowMDowMFoiLCJqdGkiOiIyMjA4MGE4OS1hMjgzLTQ4ZTctOTZjNS04N2YxN2NlN2E4NTAiLCJpYXQiOiIyMDI0LTAyLTEyVDAwOjAwOjAwWiIsImlzcyI6Imh0dHBzOi8vZGFwcC5hd2Vzb21lLmNvbSIsIm5iZiI6IjIwMjQtMDItMTJUMTI6MDA6MDBaIiwic3ViIjoiNVFEWFFYWU4zSU5WT1FaTlc0RU9KQ1A1SE9aNTVCTzdPR1E1SFRGNEhVT1JZNUhSTFpZWUxJWTdNVSJ9.5S2MHI8LPC2cy5yv3ISNgulaEhpVk22JKyNxKi2J_uuqWCMacHgs27RuVlQbyipFlbc7z0p3AiRtxFcK8j-FCw
  */
}

package main

import (
  "encoding/base64"
  "encoding/json"
  "fmt"
  // ...
  "github.com/algorand/go-algorand-sdk/v2/types"
  "golang.org/x/crypto/ed25519"
  "log"
  "strings"
)

type Header struct {
  Algorithm string `json:"alg"`
  Curve     string `json:"crv,omitempty"`
  KeyType   string `json:"kty,omitempty"`
  Type      string `json:"typ,omitempty"`
  PublicKey string `json:"x"`
}
// ...

func main() {
  // ...

  isVerified := verify(address, token)

  fmt.Println(fmt.Sprintf("is verified: %t", isVerified))
  /*
    is verified: true
  */
}

func verify(address string, token string) bool {
  var decodedHeaderAddress types.Address
  var header Header

  tokenParts := strings.Split(token, ".")
  decodedHeader, err := base64.RawURLEncoding.DecodeString(tokenParts[0])
  if err != nil {
    log.Fatal(err)
  }
  decodedSignature, err := base64.RawURLEncoding.DecodeString(tokenParts[2])
  if err != nil {
    log.Fatal(err)
  }
  err = json.Unmarshal(decodedHeader, &header)
  if err != nil {
    log.Fatal(err)
  }
  decodedPublicKey, err := base64.RawURLEncoding.DecodeString(header.PublicKey) // get the raw public key; the "x" parameter, from the header
  if err != nil {
    log.Fatal(err)
  }

  // get the address from the header's public key
  copy(decodedHeaderAddress[:], decodedPublicKey)

  // ensure the address in the header matches an address you specify (e.g. this could be a user of your platform)
  if address != decodedHeaderAddress.String() {
    fmt.Println(fmt.Sprintf("json invalid expected address '%s' but received '%s'", address, decodedHeaderAddress))

    return false
  }

  return ed25519.Verify(
    decodedPublicKey,
    []byte(fmt.Sprintf("%s.%s", tokenParts[0], tokenParts[1])), // re-create the jose header that was signed using the header and payload
    decodedSignature,
  )
}