@tempoxyz/id 0.0.0-stage → 0.0.1

package/src/api/lib/Headless.ts

@@ -0,0 +1,616 @@
+/**
+ * Runs an app's headless authorization for a signed-in session: the code or tokens, with the key
+ * authorization that the account's owner signs. `POST /v1/authorize` runs it, and so does a digest
+ * sign-in: a passkey sign-in from an app's page whose challenge was the key's digest, with that
+ * assertion as the passkey's signature.
+ * @module
+ */
+import type { Context } from 'hono'
+import type { Hex } from 'ox'
+import { Base64, Bytes, Hash } from 'ox'
+import { env } from 'void/env'
+import * as z from 'zod'
+import * as Apps from '../../internal/Apps.js'
+import * as Authorize from '../../internal/Authorize.js'
+import * as ConfigurableAccount from '../../internal/ConfigurableAccount.js'
+import type { Env } from '../../internal/Env.js'
+import * as ErrorResponse from '../../internal/ErrorResponse.js'
+import * as Log from '../../internal/Log.js'
+import * as Owner from '../../internal/Owner.js'
+import * as Passkey from '../../internal/Passkey.js'
+import * as RateLimit from '../../internal/RateLimit.js'
+import * as Timing from '../../internal/Timing.js'
+import * as AccountStep from './AccountStep.js'
+import { db } from './Database.js'
+import * as KeySigner from './KeySigner.js'
+import * as SignInConsent from './SignInConsent.js'
+
+/**
+ * The response header that marks a refusal of the authorization of a sign-in with key signature,
+ * which comes after the sign-in created the session. Its value is `true`.
+ */
+export const signedInHeader = 'Tempo-Id-Signed-In'
+
+/** The request options of the passkey step, as `KeySigner.challenge` returns them. */
+type StepOptions = Awaited<ReturnType<typeof KeySigner.challenge>>
+
+/** Unpadded URL-safe Base64, as PKCE encodes verifiers and challenges. */
+const base64url = { pad: false, url: true } as const
+
+/** Better Auth's authorization result, which names the redirect with the code. */
+const redirectResult = z.object({ url: z.string().min(1) })
+
+/**
+ * Returns the enabled app with `clientId`, or `undefined` when no enabled app has it. A write from
+ * a first-party app's page takes the app that `Cors.firstParty` read for this request, and any
+ * other request reads it with `Apps.get`, so a disabled app is refused at once.
+ */
+export async function app(c: Context<Env>, options: app.Options) {
+  const { clientId } = options
+  const matched = c.var.firstParty?.find((entry) => entry.clientId === clientId)
+  if (matched) return matched
+  return await Timing.measure(
+    c,
+    Apps.get(db, { clientId, enabled: true }).catch((error: unknown) => {
+      if (error instanceof Apps.NotFoundError) return undefined
+      throw error
+    }),
+    'Apps.get',
+  )
+}
+
+export declare namespace app {
+  type Options = {
+    /** The client ID that the request names. */
+    clientId: string
+  }
+}
+
+/**
+ * Returns why Tempo ID refuses the headless request of `app`'s page before any sign-in or
+ * authorization, or `undefined`: `Authorize.check`'s refusals, and tokens for an app that holds a
+ * client secret. Every refusal depends only on the app and the request, so a sign-in that carries
+ * the request checks it before it spends the code.
+ */
+export function check(
+  request: Authorize.Request,
+  options: check.Options,
+): ErrorResponse.Instance<typeof check.errors> | undefined {
+  return (
+    Authorize.check(request, options) ??
+    refusesTokens(request, { secret: Boolean(options.app?.secret) })
+  )
+}
+
+export namespace check {
+  export type Options = Authorize.check.Options
+
+  /** The refusals `check` returns. Its return type admits no other. */
+  export const errors = [
+    ...Authorize.check.errors,
+    Authorize.RejectedError,
+  ] as const
+}
+
+/**
+ * Authorizes the app of `request` for `session`, and returns the response of `POST /v1/authorize`.
+ * The caller checks the request with `Authorize.check` first. A spent rate limit returns its
+ * response. With `keySignature`, the passkey that signed the sign-in signs the key of an account
+ * that it owns. With `create`, a user who holds no account receives a first one, as
+ * `POST /v1/account` creates it. With `passkey`, a passkey that owns the account signs the key on
+ * the app's page: the request without an assertion returns the passkey step, and the repeated
+ * request with the assertion signs the key.
+ */
+export async function authorize(
+  c: Context<Env>,
+  options: authorize.Options,
+): Promise<
+  | authorize.ReturnType
+  | authorize.Step
+  | ErrorResponse.Instance<typeof authorize.errors>
+  | NonNullable<Awaited<ReturnType<typeof RateLimit.check>>>
+> {
+  const { headers, keySignature, passkey, request, session } = options
+  const create = options.create ?? Boolean(keySignature)
+  const clientId = request.client_id
+  const cookie = headers.get('cookie') ?? undefined
+
+  const refused = refusesTokens(request, { secret: options.secret })
+  if (refused) return refused
+
+  // Counted per user once the request can authorize, so no other caller spends the user's quota. A
+  // key that can create the first account, as `POST /v1/account` does, counts there too: one that
+  // names no account.
+  const requested = request.key_authorization
+  const limited = await Timing.measure(
+    c,
+    RateLimit.check(c, {
+      limits: [
+        { binding: 'AUTHORIZE_LIMIT', key: session.user.id },
+        ...(create && requested && !requested.account
+          ? [{ binding: 'ACCOUNT_LIMIT' as const, key: session.user.id }]
+          : []),
+      ],
+    }),
+    'RateLimit.check',
+  )
+  if (limited) return limited
+
+  // A key needs the owner of its account, to sign it. With `create`, a user who holds no account
+  // receives a first one, so the app's page needs no `POST /v1/account` before the request.
+  const signing = requested
+    ? await Timing.measure(
+        c,
+        KeySigner.resolve(c, {
+          account: requested.account,
+          chainId: requested.chainId,
+          clientId,
+          cookie,
+          create,
+          email: session.user.email,
+          // The app's page runs the passkey's ceremony, at the redirect URI's origin that
+          // `Authorize.check` accepted as the request's `Origin`.
+          page: passkey ? new URL(request.redirect_uri).origin : undefined,
+          passkey: Boolean(passkey),
+          sessionId: session.session.id,
+          signInCredential: keySignature?.assertion.id,
+          // Only a passkey that signs in this request signs the key as its own account. Without
+          // one, the account keeps `upgrade_required`, which names the wait.
+          skipUpgrade: request.skip_upgrade && Boolean(keySignature || passkey),
+          userId: session.user.id,
+        }),
+        'KeySigner.resolve',
+      )
+    : undefined
+  if (signing instanceof ErrorResponse.ResponseError) return signing
+
+  // A sign-in with key signature signs only for the account that its own passkey owns. Its digest
+  // binds the sign-in's witness, so the key carries that witness. A configurable account's owners
+  // sign its digest, which the sign-in's assertion does not sign.
+  const tapped =
+    keySignature &&
+    signing &&
+    !Owner.configured(signing.owner) &&
+    signing.owner.credential?.id === keySignature.assertion.id
+      ? keySignature
+      : undefined
+  const key =
+    requested && tapped ? { ...requested, witness: tapped.witness } : requested
+
+  // A passkey signs only in the browser, so the app's page signs the key's digest and repeats the
+  // request. The step returns the key's expiry, which the repeated request sends, since a default
+  // expiry would change the digest.
+  if (key && signing && !signing.owner.signer && !tapped && !passkey?.assertion)
+    return {
+      expiry: key.expiry,
+      options: await Timing.measure(
+        c,
+        KeySigner.challenge(c, {
+          account: signing.account,
+          clientId,
+          key,
+          owner: signing.owner,
+          userId: session.user.id,
+        }),
+        'KeySigner.challenge',
+      ),
+    }
+
+  // Without a key, the accounts only pick the selection, so a Privy outage skips it, as the account
+  // step does.
+  const account = await (async () => {
+    if (signing) return signing.account
+    const listed = await Timing.measure(
+      c,
+      AccountStep.accounts(c, {
+        chainId:
+          requested?.chainId === undefined
+            ? undefined
+            : Number(requested.chainId),
+        clientId,
+        userId: session.user.id,
+      }),
+      'AccountStep.accounts',
+    ).catch((error: unknown) => {
+      Log.warn(c, {
+        error,
+        fields: { clientId },
+        message:
+          'The headless authorization skipped an account selection whose accounts failed to load.',
+      })
+      return []
+    })
+    const selected = AccountStep.selected({
+      clientId,
+      cookie,
+      sessionId: session.session.id,
+    })
+    return AccountStep.find(listed, selected)?.address ?? listed[0]?.address
+  })()
+
+  // The in-process authorization reads the account, so the account step passes. Only an account
+  // that the key names, or that the passkey of the sign-in with key signature owns, becomes the
+  // app's account for later requests.
+  const selection = account
+    ? AccountStep.select({
+        account: account.toLowerCase(),
+        clientId,
+        cookie,
+        sessionId: session.session.id,
+      })
+    : undefined
+  const authorizeHeaders = new Headers(headers)
+  if (selection) authorizeHeaders.set('cookie', selection.header)
+  // The route read the accounts and chose one, so the account step reads them no second time.
+  c.set('accountChosen', true)
+
+  // Without the app's challenge, Tempo ID holds the verifier and redeems the code itself.
+  const verifier = request.code_challenge
+    ? undefined
+    : Base64.fromBytes(Bytes.random(32), base64url)
+  const query = {
+    client_id: clientId,
+    code_challenge:
+      request.code_challenge ??
+      Base64.fromBytes(Hash.sha256(Bytes.fromString(verifier!)), base64url),
+    code_challenge_method: 'S256',
+    redirect_uri: request.redirect_uri,
+    // In-process calls skip `withResource`, so each names the one audience that APIs verify.
+    resource: env.URL,
+    response_type: 'code',
+    scope: request.scope ?? 'openid',
+    ...(request.state ? { state: request.state } : {}),
+  }
+  const url = new URL('/oauth2/authorize', env.URL)
+  url.search = new URLSearchParams(query).toString()
+  // Better Auth returns the redirect as JSON for a request that accepts it.
+  authorizeHeaders.set('accept', 'application/json')
+  const authorized = await Timing.measure(
+    c,
+    c.var.auth.api.oauth2Authorize({
+      asResponse: false,
+      // A `GET` request reads `query`. The endpoint types a body for its `POST` form.
+      body: {},
+      headers: authorizeHeaders,
+      query,
+      request: new Request(url, { headers: authorizeHeaders }),
+    }),
+    'auth.oauth2Authorize',
+  )
+  const location = redirectResult.safeParse(authorized)
+  const redirect = location.success
+    ? URL.parse(location.data.url, env.URL)
+    : null
+  // A request that needs the approval page, or that Better Auth refuses, returns no code. Better
+  // Auth sets its `code` in place of a registered one, and appends its `error` to the registered
+  // URI's query, which may hold its own.
+  const registered = new URL(request.redirect_uri).searchParams
+  const code = redirect?.searchParams.get('code')
+  if (
+    !redirect ||
+    !code ||
+    redirect.searchParams.getAll('error').length >
+      registered.getAll('error').length ||
+    !`${redirect.origin}${redirect.pathname}`.startsWith(
+      new URL(request.redirect_uri).origin,
+    )
+  )
+    return new Authorize.RejectedError({
+      description:
+        "Authorization refused: the app's request needs the user's approval, which no page shows here. Authorize through a redirect, or register the app to skip consent.",
+    })
+
+  // The owner signs only once the authorization returns a code, so a refused request signs nothing.
+  // The code's redemption runs beside the signature, since neither reads the other. A refused
+  // signature returns no tokens.
+  const [signature, redemption] = await Promise.allSettled([
+    key && signing
+      ? Timing.measure(
+          c,
+          KeySigner.sign(c, {
+            account: signing.account,
+            assertion: tapped?.assertion ?? passkey?.assertion,
+            // The sign-in already spent its own challenge, which was the key's digest.
+            challenge: tapped ? 'sign-in' : 'stored',
+            clientId,
+            key,
+            origin:
+              tapped?.origin ??
+              (passkey ? new URL(request.redirect_uri).origin : undefined),
+            owner: signing.owner,
+            userId: session.user.id,
+          }),
+          'KeySigner.sign',
+        )
+      : undefined,
+    verifier
+      ? Timing.measure(
+          c,
+          c.var.auth.api.oauth2Token({
+            body: {
+              client_id: clientId,
+              code,
+              code_verifier: verifier,
+              grant_type: 'authorization_code',
+              redirect_uri: request.redirect_uri,
+              resource: env.URL,
+            },
+            headers: new Headers({
+              'content-type': 'application/x-www-form-urlencoded',
+            }),
+          }),
+          'auth.oauth2Token',
+        )
+      : undefined,
+  ])
+  if (signature.status === 'rejected') throw signature.reason
+  const signed = signature.value
+  if (signed instanceof ErrorResponse.ResponseError) return signed
+
+  // A linked wallet.tempo passkey's account that is not configurable on a flagged chain signed only
+  // because the request skipped its upgrade.
+  const upgrade =
+    signed &&
+    signing?.owner.linked &&
+    !signing.owner.configurable &&
+    ConfigurableAccount.on({ chainId: Number(requested!.chainId), env })
+  const result = {
+    ...(account && signed ? { account, key_authorization: signed } : {}),
+    ...(request.state ? { state: request.state } : {}),
+    ...(upgrade ? { upgrade_available: true as const } : {}),
+  }
+  // The account that the key names, or that the passkey of the sign-in with key signature owns,
+  // stays the app's account for later requests in the session.
+  if (selection && (requested?.account || tapped))
+    c.header('set-cookie', selection.setCookie, { append: true })
+  c.header('cache-control', 'no-store')
+  if (!verifier) return { ...result, code }
+
+  if (redemption.status === 'rejected') throw redemption.reason
+  return {
+    ...result,
+    tokens: Authorize.schema.tokens.parse(redemption.value),
+  }
+}
+
+export namespace authorize {
+  export type Options = {
+    /**
+     * Whether a user who holds no account, and whose key names none, receives a first one. Defaults
+     * to `true` with `keySignature`, and to `false` without it.
+     */
+    create?: boolean | undefined
+    /** The request headers, with the cookie of the signed-in session. */
+    headers: Headers
+    /** A passkey sign-in whose assertion signed the key's digest, if any. */
+    keySignature?: KeySignature | undefined
+    /**
+     * Whether the app's page signs the key with the passkey that owns the account, and the
+     * passkey's assertion over the step's options once the page holds it. Absent, a passkey-owned
+     * account refuses the key with `webauthn_required`.
+     */
+    passkey?: { assertion?: Passkey.Assertion | undefined } | undefined
+    /** The headless request, which `Authorize.check` accepted. */
+    request: Authorize.Request
+    /** Whether the app holds a client secret. */
+    secret: boolean
+    /** The signed-in session, with the user's email when the caller holds it. */
+    session: {
+      session: { id: string }
+      user: { email?: string | undefined; id: string }
+    }
+  }
+
+  /** The authorization: a code or tokens, with the signed key and its account. */
+  export type ReturnType = {
+    /** The account that the key acts for, with a signed key. */
+    account?: `0x${string}` | undefined
+    /** The authorization code, for a request with a `code_challenge`. */
+    code?: string | undefined
+    /** The signed key authorization, for a request with a key. */
+    key_authorization?: KeySigner.sign.ReturnType | undefined
+    /** The request's `state`, unchanged. */
+    state?: string | undefined
+    /** The tokens, for a request without a `code_challenge`. */
+    tokens?: z.output<typeof Authorize.schema.tokens> | undefined
+    /** Present when the request skipped the upgrade that the key's account waits for. */
+    upgrade_available?: true | undefined
+  }
+
+  /** The passkey step, which the app's page signs before it repeats the request. */
+  export type Step = {
+    /** The key's expiry in Unix seconds, which the repeated request sends. */
+    expiry: number
+    /** The options for `navigator.credentials.get()`, whose challenge is the key's digest. */
+    options: StepOptions
+  }
+
+  /** The refusals `authorize` returns. Its return type admits no other. */
+  export const errors = [
+    ...KeySigner.resolve.errors,
+    ...KeySigner.sign.errors,
+    Authorize.RejectedError,
+  ] as const
+}
+
+/** A passkey sign-in from an app's page whose challenge was the digest of the request's key. */
+export type KeySignature = {
+  /** The passkey's assertion, which signed the sign-in and the key's digest. */
+  assertion: Passkey.Assertion
+  /** The origin of the app's page, which the assertion reports. */
+  origin: string
+  /** The witness that the key's digest binds. */
+  witness: Hex.Hex
+}
+
+/**
+ * Runs the headless authorization that an emailed-code sign-in on an app's page carried, for the
+ * user whom the sign-in just signed in. The caller checks the request with `Authorize.check` before
+ * the code, so a refused request spends no code. A user who holds no account receives a first one,
+ * as `POST /v1/account` creates it. With `passkey`, a passkey-owned account returns the passkey
+ * step, which `POST /v1/authorize` completes. A spent rate limit returns its response.
+ */
+export async function afterCode(
+  c: Context<Env>,
+  options: afterCode.Options,
+): Promise<
+  | authorize.ReturnType
+  | authorize.Step
+  | ErrorResponse.Instance<typeof afterCode.errors>
+  | NonNullable<Awaited<ReturnType<typeof RateLimit.check>>>
+> {
+  const { app, email, passkey, request, setCookie } = options
+  // The sign-in created the session in this request, so the session needs no read.
+  const session = c.var.newSession
+  if (!session) throw new Error('The sign-in session is missing.')
+  return await Timing.measure(
+    c,
+    authorize(c, {
+      create: true,
+      headers: SignInConsent.sessionHeaders(c, { setCookie }),
+      // The code signs the key with no assertion, so the page's passkey signs it at
+      // `POST /v1/authorize`.
+      passkey: passkey ? {} : undefined,
+      request,
+      secret: Boolean(app.secret),
+      session: { ...session, user: { ...session.user, email } },
+    }),
+    'Headless.authorize',
+  )
+}
+
+export namespace afterCode {
+  export type Options = {
+    /** The app of the request, which `Authorize.check` accepted. */
+    app: Pick<Apps.App, 'secret'>
+    /** The email address that the code verified. */
+    email: string
+    /** Whether a passkey-owned account returns the passkey step, in place of `webauthn_required`. */
+    passkey?: boolean | undefined
+    /** The headless request, which `Authorize.check` accepted. */
+    request: Authorize.Request
+    /** The `Set-Cookie` headers of the sign-in, which carry the new session. */
+    setCookie: readonly string[]
+  }
+
+  /** The refusals `afterCode` returns. Its return type admits no other. */
+  export const errors = authorize.errors
+}
+
+/**
+ * Runs the headless authorization that a key challenge of an app's page stored, for the user
+ * whom the sign-in just signed in. The request is checked again, since time passed since the options.
+ * The passkey's assertion signs the key of an account that it owns, and a server signer, such as a
+ * Privy wallet, signs any other account's key. Another passkey's account refuses it with
+ * `webauthn_required`. A spent rate limit returns its response.
+ */
+export async function keySignature(
+  c: Context<Env>,
+  options: keySignature.Options,
+): Promise<
+  | authorize.ReturnType
+  | ErrorResponse.Instance<typeof keySignature.errors>
+  | NonNullable<Awaited<ReturnType<typeof RateLimit.check>>>
+> {
+  const { assertion, challenge, email, setCookie } = options
+  const request = Authorize.schema.request.parse(challenge.authorize)
+  const found = await Timing.measure(
+    c,
+    app(c, { clientId: request.client_id }),
+    'Headless.app',
+  )
+  const refused = Authorize.check(request, {
+    app: found,
+    origin: c.req.header('origin'),
+  })
+  if (refused) return refused
+
+  const headers = SignInConsent.sessionHeaders(c, { setCookie })
+  // The sign-in created the session in this request, so the session needs no read.
+  const session = c.var.newSession
+  if (!session) throw new Error('The sign-in session is missing.')
+  const result = await Timing.measure(
+    c,
+    authorize(c, {
+      headers,
+      keySignature:
+        challenge.witness && challenge.origin
+          ? { assertion, origin: challenge.origin, witness: challenge.witness }
+          : undefined,
+      request,
+      secret: Boolean(found!.secret),
+      session: { ...session, user: { ...session.user, email } },
+    }),
+    'Headless.authorize',
+  )
+  // Only a request with `passkey` returns the passkey step.
+  if ('options' in result) throw new Error('The passkey step is unexpected.')
+  return result
+}
+
+export namespace keySignature {
+  export type Options = {
+    /** The assertion that signed the user in, over the challenge. */
+    assertion: Passkey.Assertion
+    /** The spent key challenge, which stores the request. */
+    challenge: Passkey.Challenge
+    /** The signed-in user's email, when the sign-in holds it. */
+    email?: string | undefined
+    /** The `Set-Cookie` headers of the sign-in, which carry the new session. */
+    setCookie: readonly string[]
+  }
+
+  /** The refusals `keySignature` returns. Its return type admits no other. */
+  export const errors = [
+    ...Authorize.check.errors,
+    ...authorize.errors,
+  ] as const
+}
+
+/**
+ * Records the assertion of a key challenge of an app's page as spent until its key expires, once
+ * the assertion verified, and returns whether it was unspent. Returns `false` once the key expired,
+ * and `true` for any other challenge, whose digest no request can repeat.
+ */
+export async function spend(c: Timing.measure.Context, options: spend.Options) {
+  const { assertion, challenge } = options
+  if (challenge.authorize === undefined) return true
+  const request = Authorize.schema.request.parse(challenge.authorize)
+  // A request without a key has a random challenge, which no request repeats.
+  if (!request.key_authorization) return true
+  // An expired key reaches the chain no more, so its assertion signs in no one.
+  if (request.key_authorization.expiry <= Date.now() / 1000) return false
+  return await Timing.measure(
+    c,
+    Passkey.spendSignIn(db, {
+      authenticatorData: assertion.metadata.authenticatorData,
+      expiry: request.key_authorization.expiry,
+      signature: assertion.signature,
+    }),
+    'Passkey.spendSignIn',
+  )
+}
+
+export declare namespace spend {
+  type Options = {
+    /** The verified assertion. */
+    assertion: Passkey.Assertion
+    /** The spent challenge, as `Passkey.take` returns it. */
+    challenge: Passkey.Challenge
+  }
+}
+
+/**
+ * Returns the refusal of a request for tokens from an app that holds a client secret, whose backend
+ * redeems a code with the secret, which a page never holds.
+ */
+function refusesTokens(
+  request: Authorize.Request,
+  options: { secret: boolean },
+) {
+  if (request.code_challenge || !options.secret) return undefined
+  return new Authorize.RejectedError({
+    description:
+      'Tokens refused: the app holds a client secret, so its backend redeems a code. Send `code_challenge`, then redeem the code with the secret.',
+  })
+}

package/src/api/lib/IsolateCache.ts

@@ -0,0 +1,28 @@
+/**
+ * Sets `c.var.cache`, the handler's cache of configuration rows, on every request, as
+ * `src/internal/Cache.ts` describes.
+ * @module
+ */
+import { createMiddleware } from 'hono/factory'
+import { env } from 'void/env'
+import * as Cache from '../../internal/Cache.js'
+import type { Env } from '../../internal/Env.js'
+
+/**
+ * The isolate's cache when no `CACHE` binding names one, as in `vp dev`, which the first request
+ * creates, since its lifetime comes from the env. It holds no user data and no request's I/O.
+ */
+let fallback: Cache.Cache | undefined
+
+/**
+ * Sets `c.var.cache` to the `CACHE` binding that `App.create` passes, or to the isolate's own. The
+ * root app mounts it before CORS, whose first-party check reads it.
+ */
+export const middleware = createMiddleware<Env>(async (c, next) => {
+  c.set(
+    'cache',
+    c.env.CACHE ??
+      (fallback ??= Cache.create({ ttl: (env.CONFIG_CACHE_TTL ?? 30) * 1000 })),
+  )
+  await next()
+})