@tempoxyz/id 0.0.0-stage → 0.0.1

package/src/api/lib/AccountStep.ts

@@ -0,0 +1,485 @@
+/**
+ * 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, or
+ * by a digest of a third-party app's 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 { eq } from 'drizzle-orm'
+import type { Context } from 'hono'
+import { env } from 'void/env'
+import { parse, serialize } from 'hono/utils/cookie'
+import { Base64, Bytes, Hash } from 'ox'
+import { z } from 'zod'
+import * as Schema from '../../app/db/schema.js'
+import * as Apps from '../../internal/Apps.js'
+import * as Cache from '../../internal/Cache.js'
+import type { Env } from '../../internal/Env.js'
+import * as Log from '../../internal/Log.js'
+import type * as Owner from '../../internal/Owner.js'
+import * as Privy from '../../internal/Privy.js'
+import * as RateLimit from '../../internal/RateLimit.js'
+import * as Realm from '../../internal/Realm.js'
+import * as TempoAccount from '../../internal/TempoAccount.js'
+import * as Timing from '../../internal/Timing.js'
+import * as Configure from './Configure.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: Owner.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 ID of the chain of the app's key. On a chain whose accounts are configurable, each account
+     * is listed at its address there. Absent, each key acts as its account.
+     */
+    chainId?: number | undefined
+    /** 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 whether the first account of a user with `email`, in the realms of the app with
+ * `clientId`, waits for the upgrade of a wallet.tempo passkey of the email, as {@link create} reads
+ * it. A failed lookup waits, as it does there.
+ */
+export async function awaitsUpgrade(
+  c: Context<Env>,
+  options: awaitsUpgrade.Options,
+) {
+  const reached = await Timing.measure(
+    c,
+    realms(c, options),
+    'AccountStep.realms',
+  )
+  return await Timing.measure(
+    c,
+    Configure.awaitsUpgrade(c, {
+      email: options.email,
+      realms: reached,
+      userId: options.userId,
+    }),
+    'Configure.awaitsUpgrade',
+  )
+}
+
+export declare namespace awaitsUpgrade {
+  type Options = {
+    /** The app's client ID. */
+    clientId: string
+    /** The signed-in user's verified email. */
+    email: string
+    /** The signed-in user's ID. */
+    userId: string
+  }
+}
+
+/** 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: Context<Env>, options: create.Options) {
+  const reached = await Timing.measure(
+    c,
+    realms(c, options),
+    'AccountStep.realms',
+  )
+  const accountOptions = {
+    chainId: options.chainId,
+    db,
+    env,
+    realms: reached,
+    userId: options.userId,
+  }
+
+  // A wallet.tempo passkey of the user's email becomes their account through its upgrade, so the
+  // request creates no cloud wallet beside it, as a sign-in does. The email is read only where the
+  // lookup runs.
+  const email = await (async () => {
+    if (options.email !== undefined) return options.email
+    if (!Configure.looksUpUpgrade(c, { realms: reached })) return undefined
+    const [row] = await Timing.measure(
+      c,
+      db
+        .select({ email: Schema.user.email })
+        .from(Schema.user)
+        .where(eq(Schema.user.id, options.userId)),
+      'db.user.get',
+    )
+    return row?.email
+  })()
+  const waits =
+    email !== undefined &&
+    (await Timing.measure(
+      c,
+      Configure.awaitsUpgrade(c, {
+        email,
+        realms: reached,
+        userId: options.userId,
+      }),
+      'Configure.awaitsUpgrade',
+    ))
+  if (waits)
+    return await Timing.measure(
+      c,
+      TempoAccount.held(c, accountOptions),
+      'TempoAccount.held',
+    )
+  return await Timing.measure(
+    c,
+    TempoAccount.create(c, accountOptions),
+    'TempoAccount.create',
+  )
+}
+
+export namespace create {
+  export type Options = accounts.Options & {
+    /** The user's verified email, when the caller holds it. Absent, the call reads it. */
+    email?: string | undefined
+  }
+
+  /** 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 counter is read
+  // without `RateLimit.check`, so an authorization that skips the step carries no refusal headers.
+  const admitted = await RateLimit.count(c, {
+    binding: 'ACCOUNT_LIMIT',
+    key: options.userId,
+  })
+  if (!admitted) 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 ID of the chain of the app's key, where each account is listed at its address. Absent, each key acts as its account. */
+    chainId?: number | undefined
+    /** 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: Owner.Context, options: held.Options) {
+  const reached = await Timing.measure(
+    c,
+    realms(c, options),
+    'AccountStep.realms',
+  )
+  return await Timing.measure(
+    c,
+    TempoAccount.held(c, {
+      chainId: options.chainId,
+      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)]
+}
+
+/**
+ * Reads the user's Privy users in the realms of the app with `clientId` into the request's
+ * `Privy.Users`, so a later read of the user's accounts in the request calls Privy no more. A sign-in
+ * starts it beside the session's creation. A failed read keeps nothing, and the later read calls
+ * Privy again and refuses with its failure, so the call never throws.
+ */
+export async function prefetch(c: Context<Env>, options: prefetch.Options) {
+  const { clientId, userId } = options
+  try {
+    // The reads count against the user's `ACCOUNT_LIMIT` once with the request's later reads, so a
+    // user past the limit receives none.
+    const admitted = await RateLimit.count(c, {
+      binding: 'ACCOUNT_LIMIT',
+      key: userId,
+    })
+    if (!admitted) return
+    const reached = await Timing.measure(
+      c,
+      realms(c, { clientId }),
+      'AccountStep.realms',
+    )
+    const apps = await Timing.measure(
+      c,
+      Realm.privyApps(c, { db, realms: reached, secret: env.SECRET }),
+      'Realm.privyApps',
+    )
+    await Promise.all(
+      [...apps.values()].map((app) =>
+        Timing.measure(
+          c,
+          Privy.listWallets(c, { app, userId }),
+          'Privy.listWallets',
+        ),
+      ),
+    )
+  } catch (error) {
+    Log.warn(c, {
+      error,
+      message: "A sign-in failed to read the user's Privy users ahead.",
+    })
+  }
+}
+
+export declare namespace prefetch {
+  type Options = {
+    /** The app's client ID. */
+    clientId: string
+    /** The signed-in user's ID. */
+    userId: string
+  }
+}
+
+/**
+ * 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 app = key(options.clientId)
+  const { [app]: _, ...rest } = read(options)
+  const value = JSON.stringify({
+    apps: {
+      ...Object.fromEntries(Object.entries(rest).slice(1 - limit)),
+      [app]: 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)
+  const app = key(options.clientId)
+  return Object.hasOwn(apps, app) ? apps[app] : 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
+  }
+}
+
+/**
+ * Returns the cookie's key for the app with `clientId`: the client ID of a first-party app, or a
+ * digest of a third-party app's client ID, a URL of any length that would overflow the cookie.
+ */
+function key(clientId: string) {
+  if (!Apps.thirdParty(clientId)) return clientId
+  const digest = Hash.sha256(Bytes.fromString(clientId))
+  return `cimd:${Base64.fromBytes(digest.slice(0, 16), { pad: false, url: true })}`
+}
+
+/**
+ * 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,
+    Cache.read(c, () => Realm.forApp(db, { clientId: options.clientId }), [
+      'realm.forApp',
+      options.clientId,
+    ]),
+    'Realm.forApp',
+  )
+  return await Timing.measure(
+    c,
+    Realm.withDefaults(c, { 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,164 @@
+/**
+ * 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 Apps from '../../internal/Apps.js'
+import * as Authorize from '../../internal/Authorize.js'
+import * as core_Auth from '../../internal/Auth.js'
+import * as CodeEmail from '../../internal/CodeEmail.js'
+import type { Env } from '../../internal/Env.js'
+import * as ErrorResponse from '../../internal/ErrorResponse.js'
+import * as PendingKey from '../../internal/PendingKey.js'
+import * as Privy from '../../internal/Privy.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.
+      // A key names its chain, where each account is listed at its address there, so the step reads
+      // the accounts that a selection names.
+      accountStep: (options) => {
+        if (c.var.accountChosen) return Promise.resolve(false)
+        const key = Authorize.fromQuery(options.query)
+        return Timing.measure(
+          c,
+          AccountStep.due(c, {
+            chainId:
+              key && !(key instanceof ErrorResponse.ResponseError)
+                ? Number(key.chainId)
+                : undefined,
+            clientId: options.clientId,
+            cookie: options.headers.get('cookie'),
+            sessionId: options.sessionId,
+            userId: options.userId,
+          }),
+          'AccountStep.due',
+        )
+      },
+      baseURL: env.URL,
+      cache: c.var.cache,
+      db,
+      metadataFetch: Apps.fetchMetadata(c.env.CLIENT_METADATA),
+      pendingKey: (options) =>
+        Timing.measure(
+          c,
+          PendingKey.take(Database.db, options),
+          'PendingKey.take',
+        ),
+      secret: env.SECRET,
+      sendCode: (options) => sendCode(c, options),
+      sessionCreated: (session) =>
+        c.set('newSession', {
+          session: { id: session.id },
+          user: { id: session.userId },
+        }),
+      signUpDomains: signUpDomains(),
+      userCreated: (user) => Privy.created(c, { userId: user.id }),
+      waitUntil: (promise) => c.executionCtx.waitUntil(promise),
+    }),
+  )
+}
+
+/** Returns the lowercase domains of `SIGN_UP_DOMAINS`, or nothing when the deployment sets none. */
+export function signUpDomains() {
+  const domains = (env.SIGN_UP_DOMAINS ?? '')
+    .split(',')
+    .map((domain) => domain.trim().toLowerCase())
+    .filter(Boolean)
+  return domains.length > 0 ? domains : undefined
+}
+
+/**
+ * Emails a sign-in code to an address, with a text part and an HTML part, 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. The test inbox receives the text part
+ * only.
+ *
+ * @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) {
+  // No log line records the message, since its subject and body hold the code.
+  const message = CodeEmail.render({ code: options.code })
+
+  const inbox = c.env.TEST_INBOX
+  if (
+    inbox &&
+    TestInbox.matches({ domain: env.TEST_EMAIL_DOMAIN, email: options.email })
+  ) {
+    await Timing.measure(
+      c,
+      inbox.capture({
+        subject: message.subject,
+        text: message.text,
+        to: [{ email: options.email }],
+      }),
+      'inbox.capture',
+    )
+    return
+  }
+
+  const result = await Timing.measure(
+    c,
+    sendEmail({
+      attachments: [message.logo],
+      html: message.html,
+      subject: message.subject,
+      text: message.text,
+      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
+}