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

package/src/api/health.ts

@@ -0,0 +1,72 @@
+/** The health probe, which reports the Worker version that responded. @module */
+import { Hono } from 'hono'
+import * as z from 'zod'
+import type { Env } from '../internal/Env.js'
+import * as OpenApi from '../internal/OpenApi.js'
+
+/** The Worker version that Cloudflare's version metadata binding reports. */
+type Version = {
+  /** The version's ID, as `wrangler deploy` prints it. */
+  id: string
+  /** The version's tag, or empty when it has none. */
+  tag: string
+}
+
+// Void types `c.env` from this global interface. `void.config.ts` declares the binding.
+declare global {
+  interface VoidGeneratedEnvBindings {
+    /** The Worker version that serves the request. */
+    readonly CF_VERSION_METADATA: Version
+  }
+}
+
+namespace schema {
+  export namespace health {
+    export const response = z.object({
+      ok: z.literal(true).meta({ description: 'Always `true`.' }),
+      version: z
+        .object({
+          id: z.string().meta({
+            description: "The version's ID, as `wrangler deploy` prints it.",
+            examples: ['a5f3c2e1-7b4d-4e8a-9c6f-2d1b0e3a4c5f'],
+          }),
+          tag: z.string().meta({
+            description: "The version's tag, or empty when it has none.",
+            examples: ['v1.4.0'],
+          }),
+        })
+        .meta({
+          description: 'The deployed Worker version that served the request.',
+        }),
+    })
+  }
+}
+
+/** The health probe. */
+export const health = new Hono<
+  Env & {
+    /** The bindings the probe reads. */
+    Bindings: Pick<VoidGeneratedEnvBindings, 'CF_VERSION_METADATA'>
+  }
+>()
+  // Infrastructure probes call an unversioned path, which no app calls. It returns the version that
+  // served the request, so a deploy can be verified by its ID or tag.
+  .get(
+    '/health',
+    OpenApi.describeRoute({
+      description:
+        'Responds while the Worker is up, with the version that served the request.',
+      responses: OpenApi.responses({
+        success: {
+          description: 'The Worker is up.',
+          schema: schema.health.response,
+        },
+      }),
+      tags: ['Health'],
+    }),
+    (c) => {
+      const { id, tag } = c.env.CF_VERSION_METADATA
+      c.header('cache-control', 'no-store')
+      return c.json({ ok: true as const, version: { id, tag } }, 200)
+    },
+  )

package/src/api/lib/AccountStep.ts

@@ -0,0 +1,335 @@
+/**
+ * The account step: a user with more than one Tempo Account in an app's realms selects the one the
+ * app uses. The `__Host-tempo-id-account` cookie holds the selection for each app, by client ID,
+ * with the ID of the session that made it. The cookie's `__Host-` prefix pins it to Tempo ID's
+ * host. A selection counts only within that session, and only while it names one of the signed-in
+ * user's accounts in the app's realms, so every sign-out and session expiry ends it.
+ * @module
+ */
+import type { Context } from 'hono'
+import { env } from 'void/env'
+import { parse, serialize } from 'hono/utils/cookie'
+import { z } from 'zod'
+import type { Env } from '../../internal/Env.js'
+import * as Log from '../../internal/Log.js'
+import * as Realm from '../../internal/Realm.js'
+import * as TempoAccount from '../../internal/TempoAccount.js'
+import * as Timing from '../../internal/Timing.js'
+import { db } from './Database.js'
+
+/** The selection cookie. */
+export const cookie = '__Host-tempo-id-account'
+
+/** How many apps' selections the cookie keeps. A selection for another app drops the oldest. */
+const limit = 16
+
+/**
+ * How long the cookie lasts, in seconds: 400 days, the most that browsers keep a cookie. The
+ * session's ID bounds each selection, so a session that Better Auth extends keeps its selections.
+ */
+const maxAge = 400 * 24 * 60 * 60
+
+namespace schema {
+  export const value = z.object({
+    apps: z.record(z.string(), z.string()),
+    session: z.string(),
+  })
+}
+
+/**
+ * Returns the Tempo Accounts that the user holds in the realms of the app with `clientId`, oldest
+ * first. The step creates no account, so a user with none receives an empty list.
+ */
+export async function accounts(
+  c: Timing.measure.Context,
+  options: accounts.Options,
+) {
+  const owned = await Timing.measure(c, held(c, options), 'AccountStep.held')
+  return owned.map(TempoAccount.serialize)
+}
+
+export namespace accounts {
+  export type Options = {
+    /** The app's client ID. */
+    clientId: string
+    /** The user's ID. */
+    userId: string
+  }
+
+  /** The refusals `accounts` throws, which `ErrorResponse.handle` responds with: Privy's failures. */
+  export const errors = TempoAccount.held.errors
+}
+
+/** Returns the `Set-Cookie` value that clears every app's selection, as sign-out does. */
+export function clear() {
+  return serialize(cookie, '', {
+    httpOnly: true,
+    maxAge: 0,
+    path: '/',
+    sameSite: 'Lax',
+    secure: true,
+  })
+}
+
+/**
+ * Returns the keys that own the Tempo Accounts that the user holds in the realms of the app with
+ * `clientId`, as {@link held} does, and creates an account in the first realm for a user with
+ * none, as `POST /v1/account` does through `TempoAccount.create`.
+ */
+export async function create(
+  c: Timing.measure.Context,
+  options: create.Options,
+) {
+  const reached = await Timing.measure(
+    c,
+    realms(c, options),
+    'AccountStep.realms',
+  )
+  return await Timing.measure(
+    c,
+    TempoAccount.create(c, {
+      db,
+      env,
+      realms: reached,
+      userId: options.userId,
+    }),
+    'TempoAccount.create',
+  )
+}
+
+export namespace create {
+  export type Options = accounts.Options
+
+  /** The refusals `create` throws, which `ErrorResponse.handle` responds with: Privy's failures. */
+  export const errors = TempoAccount.create.errors
+}
+
+/**
+ * Returns whether {@link create} can create a first account for a user of the app with `clientId`
+ * who holds none: the first of the app's realms has a Privy app, or holds secp256k1 owners.
+ */
+export async function creates(
+  c: Timing.measure.Context,
+  options: creates.Options,
+) {
+  const reached = await Timing.measure(
+    c,
+    realms(c, options),
+    'AccountStep.realms',
+  )
+  const first = reached[0]
+  return first !== undefined && (first.privy !== undefined || first.secp256k1)
+}
+
+export declare namespace creates {
+  type Options = {
+    /** The app's client ID. */
+    clientId: string
+  }
+}
+
+/**
+ * Returns whether the authorization of the app with `clientId` needs the account step: the user
+ * holds more than one account in the app's realms, and the `Cookie` header selects none of them
+ * for the session. The read counts against the user's `ACCOUNT_LIMIT`, as `GET /v1/account` does.
+ * When the limit is spent, or the accounts cannot be read, such as during a Privy outage, it
+ * returns `false`, so the authorization continues without the step.
+ */
+export async function due(c: Context<Env>, options: due.Options) {
+  // Each read can call every realm's Privy app, whose quota every user shares. The limiter is
+  // called directly, so an authorization that skips the step carries no refusal headers.
+  const outcome = await Timing.measure(
+    c,
+    c.env.ACCOUNT_LIMIT.limit({ key: options.userId }),
+    'ratelimit.limit',
+  )
+  if (!outcome.success) return false
+
+  const list = await Timing.measure(
+    c,
+    accounts(c, options),
+    'AccountStep.accounts',
+  ).catch((error: unknown) => {
+    Log.warn(c, {
+      error,
+      fields: { clientId: options.clientId },
+      message:
+        'The account step skipped an authorization whose accounts failed to load.',
+    })
+    return []
+  })
+  if (list.length <= 1) return false
+  return !find(list, selected(options))
+}
+
+export declare namespace due {
+  type Options = {
+    /** The app's client ID. */
+    clientId: string
+    /** The request's `Cookie` header, if any. */
+    cookie: string | null | undefined
+    /** The ID of the signed-in session. */
+    sessionId: string
+    /** The user's ID. */
+    userId: string
+  }
+}
+
+/** Returns the account in `list` at `address`, ignoring case, or `undefined`. */
+export function find(
+  list: readonly TempoAccount.TempoAccount[],
+  address: string | undefined,
+) {
+  if (!address) return undefined
+  return list.find(
+    (account) => account.address.toLowerCase() === address.toLowerCase(),
+  )
+}
+
+/**
+ * Returns the keys that own the Tempo Accounts that the user holds in the realms of the app with
+ * `clientId`, oldest first, as {@link accounts} lists them. It creates no account. A Privy owner
+ * can sign for its account.
+ */
+export async function held(c: Timing.measure.Context, options: held.Options) {
+  const reached = await Timing.measure(
+    c,
+    realms(c, options),
+    'AccountStep.realms',
+  )
+  return await Timing.measure(
+    c,
+    TempoAccount.held(c, {
+      db,
+      env,
+      realms: reached,
+      userId: options.userId,
+    }),
+    'TempoAccount.held',
+  )
+}
+
+export namespace held {
+  export type Options = accounts.Options
+
+  /** The refusals `held` throws, which `ErrorResponse.handle` responds with: Privy's failures. */
+  export const errors = TempoAccount.held.errors
+}
+
+/**
+ * Returns `list` with the account that the `Cookie` header selects for the app with `clientId`
+ * within the session first, and the others in their order. Without a selection in `list`, it
+ * returns `list` as it is.
+ */
+export function order(
+  list: readonly TempoAccount.TempoAccount[],
+  options: selected.Options,
+) {
+  const account = find(list, selected(options))
+  if (!account) return list
+  return [account, ...list.filter((entry) => entry !== account)]
+}
+
+/**
+ * Returns the `Cookie` header with the selection of `account` for the app with `clientId`, and the
+ * `Set-Cookie` value that stores it. The session's earlier selections stay, up to {@link limit}
+ * apps, and another session's selections drop.
+ */
+export function select(options: select.Options) {
+  const pairs = (options.cookie ?? '')
+    .split(';')
+    .map((pair) => pair.trim())
+    .filter((pair) => pair && !pair.startsWith(`${cookie}=`))
+  const { [options.clientId]: _, ...rest } = read(options)
+  const value = JSON.stringify({
+    apps: {
+      ...Object.fromEntries(Object.entries(rest).slice(1 - limit)),
+      [options.clientId]: options.account,
+    },
+    session: options.sessionId,
+  })
+  return {
+    header: [...pairs, `${cookie}=${encodeURIComponent(value)}`].join('; '),
+    setCookie: serialize(cookie, value, {
+      httpOnly: true,
+      maxAge,
+      path: '/',
+      sameSite: 'Lax',
+      secure: true,
+    }),
+  }
+}
+
+export declare namespace select {
+  type Options = {
+    /** The selected account's address. */
+    account: string
+    /** The app's client ID. */
+    clientId: string
+    /** The request's `Cookie` header, if any. */
+    cookie: string | null | undefined
+    /** The ID of the signed-in session. */
+    sessionId: string
+  }
+}
+
+/**
+ * Returns the address that the `Cookie` header selects for the app with `clientId` within the
+ * session, if any.
+ */
+export function selected(options: selected.Options) {
+  const apps = read(options)
+  return Object.hasOwn(apps, options.clientId)
+    ? apps[options.clientId]
+    : undefined
+}
+
+export declare namespace selected {
+  type Options = {
+    /** The app's client ID. */
+    clientId: string
+    /** The request's `Cookie` header, if any. */
+    cookie: string | null | undefined
+    /** The ID of the signed-in session. */
+    sessionId: string
+  }
+}
+
+/**
+ * Reads the session's selections, by client ID. A missing or unreadable cookie, or one from another
+ * session, holds none.
+ */
+function read(
+  options: Pick<selected.Options, 'cookie' | 'sessionId'>,
+): Record<string, string> {
+  const value = parse(options.cookie ?? '', cookie)[cookie]
+  if (!value) return {}
+  try {
+    const parsed = schema.value.safeParse(JSON.parse(value))
+    if (!parsed.success || parsed.data.session !== options.sessionId) return {}
+    return parsed.data.apps
+  } catch {
+    return {}
+  }
+}
+
+/** Returns the realms of the app with `clientId`, in order, with their default relying parties. */
+async function realms(c: Timing.measure.Context, options: realms.Options) {
+  const stored = await Timing.measure(
+    c,
+    Realm.forApp(db, { clientId: options.clientId }),
+    'Realm.forApp',
+  )
+  return await Timing.measure(
+    c,
+    Realm.withDefaults(db, { origin: env.URL, realms: stored }),
+    'Realm.withDefaults',
+  )
+}
+
+declare namespace realms {
+  type Options = {
+    /** The app's client ID. */
+    clientId: string
+  }
+}

package/src/api/lib/Auth.ts

@@ -0,0 +1,134 @@
+/**
+ * Creates the request's Better Auth instance from Void's database, env, and email, and sets it on
+ * `c.var.auth` for the routes and pages.
+ * @module
+ */
+import { betterAuth } from 'better-auth'
+import type { Context } from 'hono'
+import { createMiddleware } from 'hono/factory'
+import { db } from 'void/db'
+import { sendEmail } from 'void/email'
+import { env } from 'void/env'
+import * as core_Auth from '../../internal/Auth.js'
+import type { Env } from '../../internal/Env.js'
+import * as ErrorResponse from '../../internal/ErrorResponse.js'
+import * as PendingKey from '../../internal/PendingKey.js'
+import * as TestInbox from '../../internal/TestInbox.js'
+import * as Timing from '../../internal/Timing.js'
+import * as AccountStep from './AccountStep.js'
+import * as Database from './Database.js'
+
+/** The email service does not deliver to the address, such as one outside the verified destinations. */
+export class UndeliverableError extends Error {
+  override readonly name = 'Auth.UndeliverableError'
+}
+
+/**
+ * Sets `c.var.auth`. The instance lives for one request, since its background sends join that
+ * request's `waitUntil`.
+ */
+export const middleware = createMiddleware<Env>(async (c, next) => {
+  c.set('auth', create(c))
+  await next()
+})
+
+/** Returns a Better Auth instance for the request `c`. */
+export function create(c: Context<Env>): core_Auth.Instance {
+  return betterAuth(
+    core_Auth.options({
+      // A request that already chose the account, such as `POST /v1/authorize`, needs no account step.
+      accountStep: (options) =>
+        c.var.accountChosen
+          ? Promise.resolve(false)
+          : Timing.measure(
+              c,
+              AccountStep.due(c, {
+                clientId: options.clientId,
+                cookie: options.headers.get('cookie'),
+                sessionId: options.sessionId,
+                userId: options.userId,
+              }),
+              'AccountStep.due',
+            ),
+      baseURL: env.URL,
+      db,
+      google: google(),
+      pendingKey: (options) =>
+        Timing.measure(
+          c,
+          PendingKey.take(Database.db, options),
+          'PendingKey.take',
+        ),
+      secret: env.SECRET,
+      sendCode: (options) => sendCode(c, options),
+      waitUntil: (promise) => c.executionCtx.waitUntil(promise),
+    }),
+  )
+}
+
+/** Returns Google's OAuth client from the env, or nothing when the deployment sets none. */
+export function google() {
+  const { GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET } = env
+  if (!GOOGLE_CLIENT_ID || !GOOGLE_CLIENT_SECRET) return undefined
+  return { clientId: GOOGLE_CLIENT_ID, clientSecret: GOOGLE_CLIENT_SECRET }
+}
+
+/**
+ * Emails a sign-in code to an address, and resolves once the email service accepts it. An address
+ * under `TEST_EMAIL_DOMAIN` goes to the `TEST_INBOX` binding instead, when the deployment sets both,
+ * as a preview does.
+ *
+ * @throws {ErrorResponse.RateLimitedError} When the email service's rate limit or quota refuses the
+ * message.
+ * @throws {UndeliverableError} When the email service does not deliver to the address.
+ * @throws {Error} When the email service or the test inbox refuses the message for another reason.
+ */
+export async function sendCode(c: Context<Env>, options: sendCode.Options) {
+  const message = {
+    subject: 'Your Tempo ID sign-in code',
+    text: `Your sign-in code is ${options.code}. It expires in 10 minutes.`,
+  }
+
+  const inbox = c.env.TEST_INBOX
+  if (
+    inbox &&
+    TestInbox.matches({ domain: env.TEST_EMAIL_DOMAIN, email: options.email })
+  ) {
+    await Timing.measure(
+      c,
+      inbox.capture({ ...message, to: [{ email: options.email }] }),
+      'inbox.capture',
+    )
+    return
+  }
+
+  const result = await Timing.measure(
+    c,
+    sendEmail({ ...message, to: options.email }),
+    'email.send',
+  )
+  if (result.ok) return
+
+  const code = 'error' in result ? result.error.code : undefined
+  if (code === 'QUOTA_EXCEEDED') throw new ErrorResponse.RateLimitedError()
+  // The message names no address, which can hold personal data.
+  if (code === 'UNVERIFIED_DESTINATION')
+    throw new UndeliverableError(
+      'The email service does not deliver to the address.',
+    )
+  throw new Error(`Sending the sign-in code failed: ${code ?? 'delivery'}.`)
+}
+
+export declare namespace sendCode {
+  type Options = {
+    /** The 6-digit code. */
+    code: string
+    /** The address to email. */
+    email: string
+  }
+}
+
+export namespace sendCode {
+  /** The refusal `sendCode` throws. */
+  export const errors = [ErrorResponse.RateLimitedError] as const
+}