@tempoxyz/id 0.0.0-pr-187.sha-eed04d3

package/src/api/lib/KeySigner.ts

@@ -0,0 +1,393 @@
+/**
+ * Signs an app's key authorization as the owner of the user's Tempo Account. The key acts for the
+ * account that it names, else the app's selected account, else the user's oldest. An owner with a
+ * server signer, such as a Privy wallet, signs on the server. A passkey signs only in the browser,
+ * on the approval page: {@link challenge} issues the key's digest as the passkey's challenge, and
+ * {@link sign} verifies the assertion over it. Elsewhere its account refuses the key with
+ * `webauthn_required`.
+ * @module
+ */
+import type { Context } from 'hono'
+import type { KeyAuthorization as ox_KeyAuthorization } from 'ox/tempo'
+import { env } from 'void/env'
+import { Authentication } from 'webauthx/server'
+import * as z from 'zod'
+import * as Authorize from '../../internal/Authorize.js'
+import type { Env } from '../../internal/Env.js'
+import * as ErrorResponse from '../../internal/ErrorResponse.js'
+import * as Log from '../../internal/Log.js'
+import * as KeyAuthorization from '../../internal/KeyAuthorization.js'
+import type * as Owner from '../../internal/Owner.js'
+import * as Passkey from '../../internal/Passkey.js'
+import * as TempoAccount from '../../internal/TempoAccount.js'
+import * as Timing from '../../internal/Timing.js'
+import * as AccountStep from './AccountStep.js'
+import { db } from './Database.js'
+
+export namespace schema {
+  /** Why approval cannot sign a key, as {@link preview} returns it. */
+  export const refusal = z
+    .enum(['foreign_account', 'no_account', 'passkey', 'unavailable'])
+    .meta({
+      description:
+        "Why approval cannot sign the key: the key names an account that is not the user's (`foreign_account`), the user holds no account and none can be created (`no_account`), a passkey that this page cannot use owns the account (`passkey`), or the accounts could not be read (`unavailable`). Absent when approval can sign it.",
+      examples: ['passkey'],
+    })
+}
+
+/**
+ * Issues the digest of `key` as the challenge of a signature by `owner`'s passkey, for the user with
+ * `userId`, and returns the request options for `navigator.credentials.get()`. The options name only
+ * that passkey, and require user verification.
+ */
+export async function challenge(
+  c: Timing.measure.Context,
+  options: challenge.Options,
+) {
+  const { account, clientId, key, owner, userId } = options
+  // `resolve` returns a passkey owner only with its credential.
+  const credential = owner.credential!
+  const digest = KeyAuthorization.digest({ key })
+  await Timing.measure(
+    c,
+    Passkey.requestSignature(db, {
+      account,
+      clientId,
+      credential,
+      digest,
+      userId,
+    }),
+    'Passkey.requestSignature',
+  )
+  return Authentication.getOptions({
+    challenge: digest,
+    credentialId: credential.id,
+    rpId: credential.rpId,
+    userVerification: 'required',
+  }).options
+}
+
+export declare namespace challenge {
+  type Options = {
+    /** The account that the key acts for. */
+    account: `0x${string}`
+    /** The client ID of the app that requests the key. */
+    clientId: string
+    /** The key authorization whose digest the passkey signs. */
+    key: KeyAuthorization.Key
+    /** The account's passkey owner, as `resolve` returns it with `passkey`. */
+    owner: Owner.Owner
+    /** The signed-in user's ID. */
+    userId: string
+  }
+}
+
+/**
+ * Returns what an approval page shows of a key before the user decides: the account that approval
+ * signs for, and why approval cannot sign it, if it cannot. A key that names a foreign account also
+ * returns its refusal as `foreign`. The owners' lookup can call every realm's
+ * Privy app, so it counts against the user's `ACCOUNT_LIMIT`, as `GET /v1/account` does. A spent
+ * limit or a failed read, such as during a Privy outage, returns `unavailable`. A user who holds no
+ * account can approve when the app's first realm creates one on approval.
+ */
+export async function preview(c: Context<Env>, options: preview.Options) {
+  const { clientId, sessionId, userId } = options
+  const signing = await (async () => {
+    const outcome = await Timing.measure(
+      c,
+      c.env.ACCOUNT_LIMIT.limit({ key: userId }),
+      'ratelimit.limit',
+    )
+    if (!outcome.success) return undefined
+    return await Timing.measure(
+      c,
+      resolve(c, {
+        account: options.account,
+        clientId,
+        cookie: c.req.header('cookie'),
+        // The approval page runs the passkey step.
+        passkey: true,
+        sessionId,
+        userId,
+      }),
+      'KeySigner.resolve',
+    ).catch((error: unknown) => {
+      Log.warn(c, {
+        error,
+        fields: { clientId },
+        message: 'An approval held a key whose account owners failed to load.',
+      })
+      return undefined
+    })
+  })()
+
+  // A user who holds no account receives the first one on approval, when the app's first realm can
+  // create it.
+  const creates =
+    signing instanceof Authorize.RejectedError
+      ? await Timing.measure(
+          c,
+          AccountStep.creates(c, { clientId }),
+          'AccountStep.creates',
+        )
+      : false
+  const account = (() => {
+    if (!signing) return options.account
+    if (signing instanceof KeyAuthorization.WebAuthnRequiredError)
+      return signing.response.meta?.account as `0x${string}` | undefined
+    if (signing instanceof ErrorResponse.ResponseError) return options.account
+    return signing.account
+  })()
+  const refusal = ((): z.output<typeof schema.refusal> | undefined => {
+    if (!signing) return 'unavailable'
+    if (signing instanceof TempoAccount.ForeignAccountError)
+      return 'foreign_account'
+    // A passkey signs only at its own relying party, which may not cover this page.
+    if (signing instanceof KeyAuthorization.WebAuthnRequiredError)
+      return 'passkey'
+    if (signing instanceof Authorize.RejectedError && !creates)
+      return 'no_account'
+    return undefined
+  })()
+  return {
+    account,
+    foreign:
+      signing instanceof TempoAccount.ForeignAccountError ? signing : undefined,
+    refusal,
+  }
+}
+
+export declare namespace preview {
+  type Options = {
+    /** The account that the key names, if any. */
+    account?: `0x${string}` | undefined
+    /** The client ID of the app that requests the key. */
+    clientId: string
+    /** The ID of the signed-in session, which bounds the account step's selection. */
+    sessionId: string
+    /** The signed-in user's ID. */
+    userId: string
+  }
+}
+
+/**
+ * Returns the account that the key acts for and its owner: the account that `account` names, else
+ * the one that the `Cookie` header selects for the app within the session, else the user's oldest
+ * in the app's realms. With `create`, a user who holds no account and names none first receives a
+ * Privy-owned account, as `POST /v1/account` creates it. Returns a refusal when `account` is not the
+ * user's, when the user holds no account, or when a passkey owns the account.
+ */
+export async function resolve(
+  c: Timing.measure.Context,
+  options: resolve.Options,
+): Promise<resolve.ReturnType | ErrorResponse.Instance<typeof resolve.errors>> {
+  const { clientId, cookie, sessionId, userId } = options
+  // A named account is one the user already holds, so its request creates none.
+  const owners =
+    options.create && !options.account
+      ? await Timing.measure(
+          c,
+          AccountStep.create(c, { clientId, userId }),
+          'AccountStep.create',
+        )
+      : await Timing.measure(
+          c,
+          AccountStep.held(c, { clientId, userId }),
+          'AccountStep.held',
+        )
+  const listed = owners.map(TempoAccount.serialize)
+
+  const named = options.account
+  const selected = named
+    ? undefined
+    : AccountStep.find(
+        listed,
+        AccountStep.selected({ clientId, cookie, sessionId }),
+      )?.address
+  // A user who chose no account, and holds several, signs only on a page that shows the account.
+  if (options.single && !named && !selected && listed.length > 1)
+    return new Authorize.RejectedError({
+      description:
+        "Several Tempo Accounts: the user holds more than one account in the app's realms and chose none. Choose the account on the account step, or name it in `key_authorization.account`.",
+    })
+  const account = (() => {
+    if (named) return AccountStep.find(listed, named)?.address
+    return selected ?? listed[0]?.address
+  })()
+  if (named && !account)
+    return new TempoAccount.ForeignAccountError({
+      account: named,
+      field: 'key_authorization.account',
+    })
+  const owner = account
+    ? owners.find(
+        (entry) =>
+          TempoAccount.serialize(entry).address.toLowerCase() ===
+          account.toLowerCase(),
+      )
+    : undefined
+  if (!account || !owner)
+    return new Authorize.RejectedError({
+      description: options.create
+        ? "No Tempo Account: the user holds no account in the app's realms, and the app's first realm has no Privy app to create one. Authorize without `key_authorization`."
+        : "No Tempo Account: the user holds no account in the app's realms, so no owner signs the key. Create the account with `POST /v1/account`, or authorize without `key_authorization`.",
+    })
+  // A passkey signs only in the browser, on a page that shows the key, at its relying party.
+  if (!owner.signer && !(options.passkey && signsHere(owner)))
+    return new KeyAuthorization.WebAuthnRequiredError({ account })
+  return { account, owner }
+}
+
+export namespace resolve {
+  export type Options = {
+    /** The account that the request names, if any. */
+    account?: `0x${string}` | undefined
+    /** The client ID of the app that requests the key. */
+    clientId: string
+    /** The request's `Cookie` header, which holds the account step's selection. */
+    cookie: string | undefined
+    /**
+     * Whether a user who holds no account and names none receives a first account. Only an explicit
+     * approval on Tempo ID's own page sets it. Defaults to `false`.
+     */
+    create?: boolean | undefined
+    /**
+     * Whether the caller signs with a passkey in the browser, as the approval page does. A passkey
+     * owner whose relying party covers Tempo ID's origin then resolves, in place of
+     * `webauthn_required`. Defaults to `false`.
+     */
+    passkey?: boolean | undefined
+    /** The ID of the signed-in session, which bounds the selection. */
+    sessionId: string
+    /**
+     * Whether a user who names no account, selected none, and holds several is refused, in place of
+     * the oldest account. A grant that shows no account sets it. Defaults to `false`.
+     */
+    single?: boolean | undefined
+    /** The signed-in user's ID. */
+    userId: string
+  }
+
+  export type ReturnType = {
+    /** The account that the key acts for. */
+    account: `0x${string}`
+    /** The account's owner, which signs the key. */
+    owner: Owner.Owner
+  }
+
+  /** The refusals `resolve` returns. Its return type admits no other. */
+  export const errors = [
+    ...AccountStep.create.errors,
+    ...AccountStep.held.errors,
+    Authorize.RejectedError,
+    KeyAuthorization.WebAuthnRequiredError,
+    TempoAccount.ForeignAccountError,
+  ] as const
+}
+
+/**
+ * Signs `key` as `owner`, the owner of `account`, and returns the signed authorization in the node's
+ * RPC format. A passkey owner signs with `assertion`, over the challenge that {@link challenge}
+ * issued for the same user, app, account, passkey, and key. Returns
+ * `KeyAuthorization.WebAuthnRequiredError` for a passkey owner without an assertion, and
+ * `Passkey.WebAuthnRejectedError` for an assertion that does not verify.
+ */
+export async function sign(
+  c: Context<Env>,
+  options: sign.Options,
+): Promise<sign.ReturnType | ErrorResponse.Instance<typeof sign.errors>> {
+  const { account, assertion, key, owner } = options
+  if (!owner.signer) {
+    if (!assertion || !owner.credential)
+      return new KeyAuthorization.WebAuthnRequiredError({ account })
+    const credential = owner.credential
+    // The challenge is spent before any other check, so a refused assertion cannot be tried again.
+    const challenge = await Timing.measure(
+      c,
+      Passkey.takeSignature(db, {
+        account,
+        authenticatorData: assertion.metadata.authenticatorData,
+        clientId: options.clientId,
+        clientDataJSON: assertion.metadata.clientDataJSON,
+        credentialId: assertion.id,
+        expiry: key.expiry,
+        signature: assertion.signature,
+        userId: options.userId,
+        verify: (challenge) =>
+          challenge.account === account.toLowerCase() &&
+          challenge.clientId === options.clientId &&
+          challenge.credential.id === credential.id &&
+          challenge.credential.publicKey === credential.publicKey &&
+          assertion.id === credential.id &&
+          // The repeated request names the key that the passkey signs, so its signature reaches
+          // only a request for that key.
+          challenge.digest === KeyAuthorization.digest({ key }) &&
+          Passkey.verify(assertion, {
+            challenge: challenge.digest,
+            origin: new URL(env.URL).origin,
+            publicKey: credential.publicKey,
+            rpId: credential.rpId,
+          }),
+      }),
+      'Passkey.takeSignature',
+    )
+    if (!challenge) return new Passkey.WebAuthnRejectedError()
+    return await Timing.measure(
+      c,
+      KeyAuthorization.signWithAssertion(assertion, {
+        key,
+        publicKey: credential.publicKey,
+      }),
+      'KeyAuthorization.signWithAssertion',
+    )
+  }
+
+  const signer = await Timing.measure(
+    c,
+    owner.signer(c, { auth: c.var.auth }),
+    'Owner.signer',
+  )
+  return await Timing.measure(
+    c,
+    KeyAuthorization.sign(signer, { key }),
+    'KeyAuthorization.sign',
+  )
+}
+
+export namespace sign {
+  export type Options = {
+    /** The account that the key acts for. */
+    account: `0x${string}`
+    /** The passkey's assertion over the challenge of {@link challenge}, for a passkey owner. */
+    assertion?: Passkey.Assertion | undefined
+    /** The client ID of the app that requests the key. */
+    clientId: string
+    /** The key authorization to sign, which the flow's checks accept. */
+    key: KeyAuthorization.Key
+    /** The account's owner. */
+    owner: Owner.Owner
+    /** The signed-in user's ID. */
+    userId: string
+  }
+
+  /** The signed authorization, in the node's RPC format. */
+  export type ReturnType = ox_KeyAuthorization.Rpc
+
+  /** The refusals `sign` returns. Its return type admits no other. */
+  export const errors = [
+    KeyAuthorization.WebAuthnRequiredError,
+    Passkey.WebAuthnRejectedError,
+  ] as const
+}
+
+/**
+ * Returns whether `owner`'s passkey signs at Tempo ID's origin: its relying party ID is the host of
+ * that origin or a registrable suffix of it, as WebAuthn requires.
+ */
+function signsHere(owner: Owner.Owner) {
+  if (!owner.credential) return false
+  return (
+    Passkey.relyingParty([owner.realm], { origin: env.URL })?.rpId ===
+    owner.credential.rpId
+  )
+}

package/src/api/lib/PasskeyLink.ts

@@ -0,0 +1,162 @@
+/**
+ * The link cookie, which holds a verified wallet.tempo passkey without an email until an emailed
+ * code names its user. Only the code sign-in that sends back the email step's nonce, with an
+ * assertion of the same passkey, links it. A cookie left in a shared browser thus links nothing for
+ * the next person.
+ * @module
+ */
+import type { Context } from 'hono'
+import { deleteCookie, getCookie, setCookie } from 'hono/cookie'
+import { Base64, Hex } from 'ox'
+import { env } from 'void/env'
+import type { Env } from '../../internal/Env.js'
+import * as Passkey from '../../internal/Passkey.js'
+import * as Timing from '../../internal/Timing.js'
+import type * as Wallet from '../../internal/Wallet.js'
+
+/** Workers' `crypto.subtle`, whose `timingSafeEqual` the project's Node types leave out. */
+type Subtle = SubtleCrypto & {
+  timingSafeEqual(a: ArrayBuffer, b: ArrayBuffer): boolean
+}
+
+/** The cookie's name, which the `__Host-` prefix pins to the host that set it with `Path=/`. */
+const name = 'tempo-id-passkey-link'
+
+/** The prefix that `hono/cookie` adds, `__Host-`. */
+const prefix = 'host'
+
+/**
+ * Returns the deferred passkey that the link cookie holds for `nonce`, or `undefined` when there is
+ * none, or the cookie or the nonce does not match. The cookie stays until `release`, so a failed
+ * write can retry.
+ */
+export async function claim(c: Context<Env>, options: claim.Options) {
+  const sealed = getCookie(c, name, prefix)
+  if (!sealed) return undefined
+
+  const link = await Timing.measure(
+    c,
+    Passkey.unseal(sealed, {
+      host: new URL(c.req.url).host,
+      secret: env.SECRET,
+    }),
+    'Passkey.unseal',
+  )
+  if (!link) return undefined
+
+  // The nonce is a secret, so it is compared in constant time, through hashes of equal length.
+  const [expected, received] = await Timing.measure(
+    c,
+    Promise.all(
+      [link.nonce, options.nonce].map((value) =>
+        crypto.subtle.digest('SHA-256', new TextEncoder().encode(value)),
+      ),
+    ),
+    'crypto.digest',
+  )
+  return (crypto.subtle as Subtle).timingSafeEqual(expected!, received!)
+    ? link
+    : undefined
+}
+
+export declare namespace claim {
+  type Options = {
+    /** The nonce from the email step, which the code sign-in sent back. */
+    nonce: string
+  }
+}
+
+/**
+ * Seals a verified wallet.tempo passkey in the link cookie for 5 minutes, and returns the nonce
+ * that the email step carries.
+ */
+export async function defer(c: Context<Env>, options: defer.Options) {
+  const nonce = Base64.fromBytes(crypto.getRandomValues(new Uint8Array(32)), {
+    pad: false,
+    url: true,
+  })
+  const sealed = await Timing.measure(
+    c,
+    Passkey.seal(
+      {
+        address: options.credential.address,
+        createdAt: options.credential.createdAt,
+        expiresAt: Math.floor(Date.now() / 1000) + Passkey.linkLifetime,
+        host: new URL(c.req.url).host,
+        id: options.id,
+        nonce,
+        publicKey: options.credential.publicKey,
+        rpId: options.rpId,
+      },
+      { secret: env.SECRET },
+    ),
+    'Passkey.seal',
+  )
+  setCookie(c, name, sealed, {
+    httpOnly: true,
+    maxAge: Passkey.linkLifetime,
+    path: '/',
+    prefix,
+    sameSite: 'Lax',
+    secure: true,
+  })
+  return nonce
+}
+
+export declare namespace defer {
+  type Options = {
+    /** The passkey that wallet.tempo returned, which the assertion verified. */
+    credential: Wallet.Credential
+    /** The credential ID, base64url. */
+    id: string
+    /** The relying party the challenge was issued for. */
+    rpId: string
+  }
+}
+
+/**
+ * Returns the SHA-256 digest of the email step's `nonce`, as hex. A challenge for the link stores
+ * the digest, since the nonce is a secret.
+ */
+export async function digest(options: digest.Options) {
+  const bytes = await crypto.subtle.digest(
+    'SHA-256',
+    new TextEncoder().encode(options.nonce),
+  )
+  return Hex.fromBytes(new Uint8Array(bytes))
+}
+
+export declare namespace digest {
+  type Options = {
+    /** The nonce from the email step. */
+    nonce: string
+  }
+}
+
+/**
+ * Returns whether the challenge digest `expected` is the digest of `nonce`, compared in constant
+ * time.
+ */
+export async function matches(options: matches.Options) {
+  if (!options.expected) return false
+  const received = await digest({ nonce: options.nonce })
+  if (received.length !== options.expected.length) return false
+  return (crypto.subtle as Subtle).timingSafeEqual(
+    Hex.toBytes(received as Hex.Hex).buffer as ArrayBuffer,
+    Hex.toBytes(options.expected as Hex.Hex).buffer as ArrayBuffer,
+  )
+}
+
+export declare namespace matches {
+  type Options = {
+    /** The digest that the challenge stores, or `undefined` for a sign-in challenge. */
+    expected: string | undefined
+    /** The nonce that the code sign-in sent back. */
+    nonce: string
+  }
+}
+
+/** Clears the link cookie. */
+export function release(c: Context<Env>) {
+  deleteCookie(c, name, { path: '/', prefix, secure: true })
+}

package/src/api/lib/Session.ts

@@ -0,0 +1,34 @@
+/**
+ * Reads the request's session, and forwards the cookie that Better Auth reissues when it extends the
+ * session, so the browser keeps the session as long as the database does.
+ * @module
+ */
+import type * as Hono from 'hono'
+import type { Env } from '../../internal/Env.js'
+import * as Timing from '../../internal/Timing.js'
+
+/**
+ * Returns the request's session, or `null` without one. Better Auth extends a session that is older
+ * than a day, and the extended cookie goes on the response.
+ */
+export async function get(c: get.Context) {
+  const result = await Timing.measure(
+    c,
+    c.var.auth.api.getSession({
+      headers: c.req.raw.headers,
+      returnHeaders: true,
+    }),
+    'auth.getSession',
+  )
+  for (const cookie of result.headers.getSetCookie())
+    c.header('set-cookie', cookie, { append: true })
+  return result.response
+}
+
+export declare namespace get {
+  /** A context that carries the request's Better Auth instance and timing, such as a page loader's. */
+  type Context = Pick<Hono.Context<Env>, 'header' | 'req'> & {
+    /** The request's variables. */
+    var: Pick<Env['Variables'], 'auth' | 'timing'>
+  }
+}