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

package/src/internal/TempoAccount.ts

@@ -0,0 +1,342 @@
+/**
+ * Each user's Tempo Accounts: configurable accounts (TIP-1107), each in one realm and owned by one
+ * key. Each kind in {@link kinds}, such as Privy wallets and linked wallet.tempo passkeys, lists the
+ * keys of its kind, and a kind that creates keys creates a user's first account. Configurable
+ * accounts are on no Tempo chain yet, so the owner acts as the account until they ship.
+ * @module
+ */
+import { and, eq, inArray } from 'drizzle-orm'
+import { AccountConfig } from 'viem/tempo'
+import { z } from 'zod'
+import * as Schema from '../app/db/schema.js'
+import * as ErrorResponse from './ErrorResponse.js'
+import * as Owner from './Owner.js'
+import * as Passkey from './owners/Passkey.js'
+import * as Privy from './owners/Privy.js'
+import * as Secp256k1 from './owners/Secp256k1.js'
+import type * as Realm from './Realm.js'
+import * as Timing from './Timing.js'
+
+/** The request names a Tempo Account that is not one of the user's in the app's realms. */
+export class ForeignAccountError extends ErrorResponse.define(
+  'foreign_account',
+) {
+  override readonly name = 'TempoAccount.ForeignAccountError'
+
+  constructor(options: ForeignAccountError.Options) {
+    super({
+      error_description: `Access denied to Tempo Account ${options.account}. Name one of the user's accounts in the app's realms.`,
+      field: options.field ?? 'account',
+      meta: { account: options.account },
+    })
+  }
+}
+
+export declare namespace ForeignAccountError {
+  type Options = {
+    /** The address that the request named. */
+    account: string
+    /** The request field that named the address. Defaults to `account`. */
+    field?: string | undefined
+  }
+}
+
+/**
+ * The kinds of owner keys, in the order that breaks a tie in creation time: a passkey comes before a
+ * Privy wallet created in the same second, and a Privy wallet before a secp256k1 key. The first kind
+ * that creates keys in a realm creates a user's first account there, so a realm with a Privy app
+ * creates Privy wallets even where it also holds secp256k1 owners.
+ */
+export const kinds = [Passkey.owner, Privy.owner, Secp256k1.owner] as const
+
+/** A user's Tempo Account, as the API returns it. */
+export type TempoAccount = z.output<typeof schema.tempoAccount>
+
+/** The owner type in the API, such as `privy`, `secp256k1`, or `webAuthn`. */
+export type Type = (typeof kinds)[number]['type']
+
+/** Zod schemas for Tempo Accounts as the API returns them. */
+export namespace schema {
+  const address = z
+    .templateLiteral(['0x', z.string().regex(/^[0-9a-fA-F]{40}$/)])
+    .meta({
+      description: 'A 20-byte address.',
+      examples: ['0x8C3b5d0e2A4f6B1c9D7e3F5a0B2c4D6e8F1a3B5c'],
+    })
+
+  /** A realm, with its display name. */
+  export const realm = z
+    .object({
+      id: z.string().meta({
+        description: 'The realm ID, such as `default` or `tempo-cash`.',
+        examples: ['tempo-cash'],
+      }),
+      name: z.string().meta({
+        description: 'The realm display name, such as `Tempo Cash`.',
+        examples: ['Tempo Cash'],
+      }),
+    })
+    .meta({
+      description:
+        'A realm, which holds Tempo Accounts. An app reaches only the accounts of its realms.',
+      id: 'Realm',
+    })
+
+  /** A Tempo Account, with its configuration and its realm. */
+  export const tempoAccount = z
+    .object({
+      address: address.meta({
+        description:
+          'The account address. Until configurable accounts ship, the owner acts as the account.',
+        examples: ['0x8C3b5d0e2A4f6B1c9D7e3F5a0B2c4D6e8F1a3B5c'],
+      }),
+      config: z
+        .object({
+          owners: z
+            .array(
+              z
+                .object({
+                  owner: address.meta({
+                    description: 'The address of the owner key.',
+                    examples: ['0x8C3b5d0e2A4f6B1c9D7e3F5a0B2c4D6e8F1a3B5c'],
+                  }),
+                  type: z.enum(kinds.map((kind) => kind.type)).meta({
+                    description:
+                      'Who holds the owner key: a Privy wallet (`privy`), a key that Tempo ID holds in development (`secp256k1`), or a passkey (`webAuthn`), which signs only in the browser.',
+                    examples: ['webAuthn'],
+                  }),
+                  weight: z.number().meta({
+                    description:
+                      "The owner's signing weight, which counts toward `threshold`.",
+                    examples: [1],
+                  }),
+                })
+                .meta({ description: 'One key that signs for the account.' }),
+            )
+            .readonly()
+            .meta({ description: 'The keys that sign for the account.' }),
+          salt: z.templateLiteral(['0x', z.string()]).meta({
+            description:
+              'The 32-byte salt that the account address derives from, as hex.',
+            examples: [`0x${'0'.repeat(64)}`],
+          }),
+          threshold: z.number().meta({
+            description:
+              'The total owner weight that a signature needs to act for the account.',
+            examples: [1],
+          }),
+          version: z.templateLiteral(['0x', z.string()]).meta({
+            description: 'The configuration version, as a hex quantity.',
+            examples: ['0x0'],
+          }),
+        })
+        .meta({
+          description:
+            'The account configuration (TIP-1107): its owners, salt, threshold, and version.',
+        }),
+      realm,
+    })
+    .meta({
+      description:
+        'A configurable Tempo Account (TIP-1107) and its configuration.',
+      id: 'TempoAccount',
+    })
+}
+
+/**
+ * Returns the keys that own the user's Tempo Accounts in `realms`, as {@link held} does, and creates
+ * one in the first realm for a user with none, when a kind creates keys in that realm. A user with a
+ * linked owner key, such as a wallet.tempo passkey, receives none. Concurrent calls, through apps
+ * whose realms overlap, and a link at the same time create one account. No database connection
+ * stays open while a kind creates the key.
+ */
+export async function create(
+  c: Timing.measure.Context,
+  options: create.Options,
+): Promise<readonly Owner.Owner<Type>[]> {
+  const { db, realms, userId } = options
+  const loaded = await Timing.measure(c, load(c, options), 'TempoAccount.load')
+
+  const held = await Timing.measure(
+    c,
+    owners(c, { db, loaded }),
+    'TempoAccount.owners',
+  )
+  if (held.length > 0) return held
+
+  const creator = (realm: Realm.Realm) => {
+    for (const entry of loaded) {
+      const fn = entry.create?.(realm)
+      if (fn) return fn
+    }
+    return undefined
+  }
+  const realm = realms[0]
+  if (!realm || !creator(realm)) return []
+
+  // A short transaction under the user's lock picks the realm, so the kind's calls after it hold no
+  // database connection. A claim in these realms, from a request through an app whose realms
+  // overlap them, wins over the first realm. A linked key that a kind stored before the claim wins
+  // over both. A link after the claim adds the linked key's account beside the created one.
+  const target = await db.transaction(async (tx) => {
+    await Timing.measure(c, Owner.lock(tx, { userId }), 'db.account.lock')
+    const claims = await Timing.measure(
+      c,
+      tx
+        .select({ realmId: Schema.firstAccounts.realmId })
+        .from(Schema.firstAccounts)
+        .where(
+          and(
+            eq(Schema.firstAccounts.userId, userId),
+            inArray(
+              Schema.firstAccounts.realmId,
+              realms.map((entry) => entry.id),
+            ),
+          ),
+        ),
+      'db.account.claims',
+    )
+    const claimed = realms.find(
+      (entry) =>
+        claims.some((claim) => claim.realmId === entry.id) && creator(entry),
+    )
+    if (claimed) return { realm: claimed }
+
+    const linked = await Timing.measure(
+      c,
+      owners(c, {
+        db: tx,
+        loaded: loaded.filter((entry) => !entry.create),
+      }),
+      'TempoAccount.linked',
+    )
+    if (linked.length > 0) return { linked }
+
+    await Timing.measure(
+      c,
+      tx
+        .insert(Schema.firstAccounts)
+        .values({ realmId: realm.id, userId })
+        .onConflictDoNothing(),
+      'db.account.claim',
+    )
+    return { realm }
+  })
+  if ('linked' in target) return target.linked
+
+  const owner = await Timing.measure(
+    c,
+    creator(target.realm)!(c),
+    'TempoAccount.createOwner',
+  )
+  return [owner]
+}
+
+export namespace create {
+  export type Options = list.Options
+
+  /** The refusals `create` throws, which `ErrorResponse.handle` responds with: each kind's failures. */
+  export const errors = [
+    ...Passkey.owner.errors,
+    ...Privy.owner.errors,
+    ...Secp256k1.owner.errors,
+  ] as const
+}
+
+/**
+ * Returns the keys that own the user's Tempo Accounts in `realms`, oldest first, and creates none.
+ * Each kind reads its keys in parallel.
+ */
+export async function held(
+  c: Timing.measure.Context,
+  options: held.Options,
+): Promise<readonly Owner.Owner<Type>[]> {
+  const loaded = await Timing.measure(c, load(c, options), 'TempoAccount.load')
+  return await Timing.measure(
+    c,
+    owners(c, { db: options.db, loaded }),
+    'TempoAccount.owners',
+  )
+}
+
+export namespace held {
+  export type Options = list.Options
+
+  /** The refusals `held` throws, which `ErrorResponse.handle` responds with: each kind's failures. */
+  export const errors = create.errors
+}
+
+/**
+ * Returns the user's Tempo Accounts in `realms`, oldest first, as the API returns them, and creates
+ * none. Their owners are those that {@link held} returns.
+ */
+export async function list(
+  c: Timing.measure.Context,
+  options: list.Options,
+): Promise<readonly TempoAccount[]> {
+  const owned = await Timing.measure(c, held(c, options), 'TempoAccount.held')
+  return owned.map(serialize)
+}
+
+export namespace list {
+  export type Options = {
+    /** The database. */
+    db: Realm.Database
+    /** The deployment variables that the kinds read. */
+    env: Owner.Env
+    /** The realms that the request reaches, in order. The first holds a user's first account. */
+    realms: readonly Realm.Realm[]
+    /** The user's ID. */
+    userId: string
+  }
+
+  /** The refusals `list` throws, which `ErrorResponse.handle` responds with: each kind's failures. */
+  export const errors = create.errors
+}
+
+/** Loads every kind in {@link kinds} for `realms`, in parallel, in the order of {@link kinds}. */
+async function load(c: Timing.measure.Context, options: list.Options) {
+  return await Promise.all(
+    kinds.map((kind): Promise<Owner.Kind.Loaded<Type>> =>
+      kind.load(c, options),
+    ),
+  )
+}
+
+/**
+ * Returns the keys that `loaded` lists, oldest first, and creates none. The kinds are read in
+ * parallel, and an earlier kind wins a tie.
+ */
+async function owners(
+  c: Timing.measure.Context,
+  options: owners.Options,
+): Promise<readonly Owner.Owner<Type>[]> {
+  const { db } = options
+  const lists = await Promise.all(
+    options.loaded.map((entry) => entry.list(c, { db })),
+  )
+  return Owner.merge(lists)
+}
+
+declare namespace owners {
+  type Options = {
+    /** The database or transaction to read. */
+    db: Realm.Database
+    /** The loaded kinds to list, in the order of {@link kinds}. */
+    loaded: readonly Owner.Kind.Loaded<Type>[]
+  }
+}
+
+/** Returns the Tempo Account that `owner` owns, as the API returns it. */
+export function serialize(owner: Owner.Owner): TempoAccount {
+  const config = AccountConfig.toRpc(owner.account.config)
+  return schema.tempoAccount.parse({
+    // The owner acts as the account until TIP-1107 is live, then `account.address`.
+    address: owner.account.owners[0]!.address,
+    config: {
+      ...config,
+      owners: config.owners.map((entry) => ({ ...entry, type: owner.type })),
+    },
+    realm: { id: owner.realm.id, name: owner.realm.name },
+  })
+}

package/src/internal/TestInbox.ts

@@ -0,0 +1,51 @@
+/**
+ * Selects the sign-in codes that a deployment sends to its test inbox instead of emailing them. A
+ * preview sets `TEST_EMAIL_DOMAIN` and binds `TEST_INBOX`, so the end-to-end suite reads the codes of
+ * its test addresses, while every other address still receives email. Only domains that RFC 2606
+ * reserves qualify, so no deployment can divert a real address.
+ * @module
+ */
+
+/** The domains that a test inbox can receive, which RFC 2606 reserves, so no real address uses them. */
+export const domains = ['example.com', 'example.net', 'example.org'] as const
+
+/** A domain that a test inbox can receive. */
+export type Domain = (typeof domains)[number]
+
+/** A message to a test inbox, in the shape of Void's development inbox. */
+export type Message = {
+  /** The subject line. */
+  subject: string
+  /** The plain-text body. */
+  text: string
+  /** The recipients. */
+  to: readonly {
+    /** The recipient's address. */
+    email: string
+  }[]
+}
+
+/** The test inbox's `Capture` entrypoint, which a deployment binds as `TEST_INBOX`. */
+export type Service = {
+  /** Stores `message`. */
+  capture(message: Message): Promise<void>
+}
+
+/**
+ * Returns whether `email` belongs at the test inbox: `domain` is one of {@link domains}, and the
+ * address's domain is exactly `domain`. Returns `false` when `domain` is absent.
+ */
+export function matches(options: matches.Options) {
+  const { domain, email } = options
+  if (!domain || !domains.some((entry) => entry === domain)) return false
+  return email.toLowerCase().endsWith(`@${domain}`)
+}
+
+export declare namespace matches {
+  type Options = {
+    /** The deployment's `TEST_EMAIL_DOMAIN`, or `undefined` when it sets none. */
+    domain?: string | undefined
+    /** The recipient's address. */
+    email: string
+  }
+}

package/src/internal/Timing.ts

@@ -0,0 +1,158 @@
+/**
+ * Request timings: how long each call that a request awaits takes. The calls range from Tempo ID's
+ * own steps to the Better Auth, database, and email calls inside them. The middleware sends them in
+ * a `Server-Timing` header, which browser developer tools show beside each request. Outside the Vite
+ * dev server, it also logs them with `Log.info`. Workers advance the clock only across I/O, so a span
+ * measures the I/O it awaits, and computation reads as zero.
+ * @module
+ */
+import { createMiddleware } from 'hono/factory'
+import type { Env } from './Env.js'
+import * as Log from './Log.js'
+
+/** One awaited call. */
+export type Span = {
+  /** When the call settled, in the request's sequence of opens and settles. Pending spans hold `Infinity`. */
+  closed: number
+  /**
+   * What the header shows beside the span, such as an in-process call's path. Logs leave it out,
+   * since a path can carry a device's user code.
+   */
+  description?: string | undefined
+  /** How long the call took, in milliseconds. */
+  duration: number
+  /**
+   * `service.operation` for a call to another service, such as `db.session.get`, or
+   * `Module.function` for a step of Tempo ID's own, such as `Session.get`.
+   */
+  name: string
+  /** When the call's span opened, in the request's sequence of opens and settles. */
+  opened: number
+  /** When the call started, in milliseconds after the request did. */
+  start: number
+}
+
+/** A request's timings, which {@link middleware} creates and {@link measure} appends to. */
+export type Timing = {
+  /** How many spans opened or settled so far, which orders spans that start at the same instant. */
+  events: number
+  /** The request's spans, in the order they opened. A span still pending has a zero duration. */
+  spans: Span[]
+  /** When the request started, from `performance.now()`. */
+  start: number
+}
+
+/**
+ * Awaits `promise` as the span `name`, and returns its result. A rejection is timed too, then
+ * rethrown. Concurrent spans may share a name. The header shows `description` beside the span, and
+ * logs leave it out.
+ */
+export async function measure<promise extends PromiseLike<unknown>>(
+  c: measure.Context,
+  promise: promise,
+  name: string,
+  description?: string,
+): Promise<Awaited<promise>> {
+  const timing = c.var.timing
+  const start = performance.now()
+  const span: Span = {
+    closed: Infinity,
+    ...(description ? { description } : {}),
+    duration: 0,
+    name,
+    opened: timing.events++,
+    start: start - timing.start,
+  }
+  timing.spans.push(span)
+  try {
+    return await promise
+  } finally {
+    span.closed = timing.events++
+    span.duration = performance.now() - start
+  }
+}
+
+export declare namespace measure {
+  /** A context that carries the request's timing, such as a route's or a page loader's. */
+  type Context = {
+    /** The request's variables. */
+    var: Pick<Env['Variables'], 'timing'>
+  }
+}
+
+/**
+ * Times the request. Once the response is ready, it appends a `Server-Timing` header with the
+ * request's `total` and each span. Outside the Vite dev server, it also logs the same timings. A
+ * streamed page's `total` ends when its headers are ready.
+ */
+export const middleware = createMiddleware<Env>(async (c, next) => {
+  const timing: Timing = { events: 0, spans: [], start: performance.now() }
+  c.set('timing', timing)
+  await next()
+
+  const total = performance.now() - timing.start
+  const spans = order(timing.spans)
+  c.res.headers.append(
+    'server-timing',
+    [`total;dur=${round(total)}`, ...spans.map(serialize)].join(', '),
+  )
+
+  // The dev server prints every entry to the terminal, and the header carries the same spans.
+  if (Log.dev()) return
+
+  // Without the context, `Log` leaves the request's path out, since callers control it and it can
+  // carry a user code. The route pattern stands in, and pages without a route share `/*`.
+  Log.info({
+    fields: {
+      duration: round(total),
+      errorCode: c.var.refusal?.error,
+      method: c.req.method,
+      reason: c.var.refusal?.reason,
+      requestId: c.var.requestId,
+      route: Log.route(c),
+      spans: spans
+        .map(
+          (span) =>
+            `${span.name};dur=${round(span.duration)};start=${round(span.start)}`,
+        )
+        .join(', '),
+      status: c.res.status,
+    },
+    message: 'The Worker timed a request.',
+  })
+})
+
+/**
+ * Orders spans with each step before the calls inside it. The order reads only the sequence of
+ * opens and settles, since the clock can advance between the span of a call and the span of its
+ * step. Spans that open with no settle between them all overlap. Of those, the one that settles
+ * last encloses the others, since a step's promise is created before the step's span opens. Spans
+ * that open after a settle come after.
+ */
+function order(spans: readonly Span[]) {
+  // `spans` holds the spans in the order they opened, so each event before a span that is not an
+  // earlier span's open is a settle.
+  return spans
+    .map((span, index) => ({ settles: span.opened - index, span }))
+    .toSorted((a, b) => {
+      if (a.settles !== b.settles) return a.settles - b.settles
+      // Pending spans hold `Infinity`, which subtraction cannot compare.
+      if (a.span.closed !== b.span.closed)
+        return a.span.closed > b.span.closed ? -1 : 1
+      return a.span.opened - b.span.opened
+    })
+    .map((entry) => entry.span)
+}
+
+/** Rounds milliseconds to one decimal. */
+function round(milliseconds: number) {
+  return Math.round(milliseconds * 10) / 10
+}
+
+/** Serializes a span as a `Server-Timing` metric. */
+function serialize(span: Span) {
+  const metric = `${span.name};dur=${round(span.duration)}`
+  if (!span.description) return metric
+  // The description is a quoted string, which escapes quotes and backslashes.
+  return `${metric};desc="${span.description.replace(/["\\]/g, '\\$&')}"`
+}

package/src/internal/Validation.ts

@@ -0,0 +1,52 @@
+/** Turns a failed request validation into an `invalid_field` refusal that names each field. @module */
+import * as ErrorResponse from './ErrorResponse.js'
+
+/** A field is missing or malformed. Names each field the issues refused, with what it expects. `field` is the first. */
+export class InvalidFieldError extends ErrorResponse.define('invalid_field') {
+  override readonly name = 'Validation.InvalidFieldError'
+
+  constructor(options: InvalidFieldError.Options) {
+    const { issues } = options
+    super({
+      error_description: `Invalid request. ${issues
+        .map(
+          (issue) =>
+            `${path(issue) ? `\`${path(issue)}\`` : 'Body'}: ${issue.message}.`,
+        )
+        .join(' ')}`,
+      field: issues[0] && path(issues[0]) ? path(issues[0]) : undefined,
+    })
+  }
+}
+
+export declare namespace InvalidFieldError {
+  type Options = {
+    /** The issues validation reported. */
+    issues: readonly Issue[]
+  }
+
+  /** A Standard Schema issue, as Zod and Hono's validators report it. */
+  type Issue = {
+    /** The validator's description of the problem. */
+    message: string
+    /** The segments from the input's root to the refused value. Absent for the root itself. */
+    path?:
+      | readonly (
+          | PropertyKey
+          | {
+              /** The segment's property key. */
+              key: PropertyKey
+            }
+        )[]
+      | undefined
+  }
+}
+
+/** The dotted path of the field `issue` refused. */
+function path(issue: InvalidFieldError.Issue) {
+  return (issue.path ?? [])
+    .map((segment) =>
+      typeof segment === 'object' ? String(segment.key) : String(segment),
+    )
+    .join('.')
+}

package/src/internal/Wallet.ts

@@ -0,0 +1,62 @@
+/**
+ * Reads wallet.tempo's passkeys through the optional `WALLET` service binding to its `Credentials`
+ * entrypoint. Tempo ID never reads wallet.tempo's stores, and validates what the binding returns.
+ * @module
+ */
+import { Address, PublicKey } from 'ox'
+import { z } from 'zod'
+
+/** The part of wallet.tempo's `Credentials` entrypoint that Tempo ID calls. */
+export type Service = {
+  /** Returns the passkey with `credentialId`, or `undefined` when wallet.tempo stores none. */
+  credential(options: { credentialId: string }): Promise<unknown>
+}
+
+/** A passkey that wallet.tempo stores. */
+export type Credential = z.output<typeof schema.credential>
+
+namespace schema {
+  export const credential = z.object({
+    address: z.string().regex(/^0x[0-9a-fA-F]{40}$/),
+    createdAt: z.number().int().min(0).max(8.64e15).nullable(),
+    email: z.email().nullable(),
+    publicKey: z.templateLiteral([
+      '0x04',
+      z.string().regex(/^[0-9a-fA-F]{128}$/),
+    ]),
+  })
+}
+
+/**
+ * Returns the passkey `id` that wallet.tempo stores, with its account's address, creation time in
+ * milliseconds, and verified email. Returns `undefined` when wallet.tempo does not store it,
+ * returns another shape, or names an address that its public key does not derive.
+ */
+export async function credential(wallet: Service, options: credential.Options) {
+  const result = schema.credential.safeParse(
+    await wallet.credential({ credentialId: options.id }),
+  )
+  if (!result.success) return undefined
+
+  // The stored address must be the account the public key owns, whatever wallet.tempo returns.
+  const derived = (() => {
+    try {
+      return Address.fromPublicKey(PublicKey.fromHex(result.data.publicKey))
+    } catch {
+      return undefined
+    }
+  })()
+  if (
+    !derived ||
+    !Address.isEqual(derived, result.data.address as Address.Address)
+  )
+    return undefined
+  return result.data
+}
+
+export declare namespace credential {
+  type Options = {
+    /** The credential ID, base64url. */
+    id: string
+  }
+}