Attestation.sign

Signs attestation claims as a compact JWS with EdDSA over Ed25519. Use it in an issuer service after you check a fact about the subject, such as control of a phone number.

Usage

import * as Attestation from 'mppx/extensions/identity/attestation'
 
declare const privateKey: CryptoKey // Ed25519
 
const now = Math.floor(Date.now() / 1000)
 
const attestation = await Attestation.sign(
  {
    aud: 'https://api.example.com',
    exp: now + 3600,
    iat: now,
    iss: 'https://issuer.example.com',
    jti: crypto.randomUUID(),
    sub: '+14155550123',
    type: 'phone',
  },
  { key: privateKey, keyId: 'NzbLsXh8uDCcd-6MNwXF4W_7noWXFZAfHkxZsRGC9Xs' },
)

Publish the public key at <issuer>/.well-known/jwks.json as an OKP key with crv: 'Ed25519', kid, and x, so Attestation.Jwks.resolver finds it. See Build your own protocol.

Return type

Promise<string>: base64url(header).base64url(claims).base64url(signature), with header { alg: 'EdDSA', kid, typ: 'mpp-attestation+jwt' }. Servers reject tokens longer than 8192 characters.

Parameters

claims

• Type: Attestation.Claims

Signed as given; sign doesn't validate them. Attestation.verify requires:

• aud: origin of the API the attestation is for, such as https://api.example.com
• exp, iat: expiry and issued-at times, as non-negative integer Unix seconds
• iss: issuer URL, matching the URL servers trust
• jti (optional): string attestation ID
• sub: nonempty attested subject, such as an email address or phone number
• type: attestation type, such as email or phone

options.key

• Type: CryptoKey

Ed25519 private key.

options.keyId

• Type: string

Key ID for the JWS kid header. Use the RFC 7638 thumbprint of the public key in your JSON Web Key Set.