@tempoxyz/id 0.0.0-stage → 0.0.1

package/src/internal/Timing.ts

@@ -0,0 +1,172 @@
+/**
+ * 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. The header also marks the first request
+ * of an isolate, which can wait for the isolate to start, outside every span.
+ * @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
+}
+
+/**
+ * Whether the isolate served a request before. The flag holds no request data, and only the header
+ * of the isolate's first request reads it as `false`.
+ */
+let served = false
+
+/**
+ * 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`, the `cold` metric on the isolate's first request, 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 cold = !served
+  served = true
+  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)}`,
+      ...(cold ? ['cold'] : []),
+      ...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/Verification.ts

@@ -0,0 +1,58 @@
+/**
+ * Writes the single-use records that Tempo ID keeps in Better Auth's `verification` table, such as a
+ * spent request or a pending key challenge. One statement checks and writes each record.
+ * @module
+ */
+import { and, gt, inArray, lte, sql } from 'drizzle-orm'
+import * as Schema from '../app/db/schema.js'
+import type * as Realm from './Realm.js'
+
+/**
+ * Stores a record with `identifier` and `value` until `expiresAt`, unless an unexpired record holds
+ * `identifier` or one of `others`, and returns whether it stored the record. The record's ID is its
+ * identifier, so two concurrent claims of one identifier conflict on the primary key, and only one
+ * stores it. A claim replaces an expired record under the same ID. The check also reads records
+ * with another ID, such as random ones, but a record with another ID that commits during the
+ * statement can escape the check. A caller that writes those concurrently holds a lock around the
+ * claim.
+ */
+export async function claim(db: Realm.Database, options: claim.Options) {
+  const { expiresAt, identifier, others = [], value } = options
+  const now = new Date()
+  const unspent = db
+    .select({ id: Schema.verification.id })
+    .from(Schema.verification)
+    .where(
+      and(
+        inArray(Schema.verification.identifier, [identifier, ...others]),
+        gt(Schema.verification.expiresAt, now),
+      ),
+    )
+  const [row] = await db
+    .insert(Schema.verification)
+    // An insert from a query lists every column in the table's order: `created_at`, `expires_at`,
+    // `id`, `identifier`, `updated_at`, and `value`. Timestamps are UTC, as the columns store them.
+    .select(
+      sql`select ${now.toISOString()}::timestamp, ${expiresAt.toISOString()}::timestamp, ${identifier}, ${identifier}, ${now.toISOString()}::timestamp, ${value} where not exists (${unspent})`,
+    )
+    .onConflictDoUpdate({
+      set: { createdAt: now, expiresAt, updatedAt: now, value },
+      setWhere: lte(Schema.verification.expiresAt, now),
+      target: Schema.verification.id,
+    })
+    .returning({ id: Schema.verification.id })
+  return row !== undefined
+}
+
+export declare namespace claim {
+  type Options = {
+    /** When the record expires. */
+    expiresAt: Date
+    /** The record's identifier, which is also its ID. */
+    identifier: string
+    /** Other identifiers whose unexpired record also prevents the claim. Default: none. */
+    others?: readonly string[] | undefined
+    /** The record's value, a JSON string. */
+    value: string
+  }
+}

package/src/internal/Wallet.ts

@@ -0,0 +1,101 @@
+/**
+ * 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>
+  /** Returns the passkeys of the accounts whose verified email is `email`, oldest first, each with its ID. */
+  credentials(options: { email: string }): Promise<unknown>
+}
+
+/** A passkey that wallet.tempo stores. */
+export type Credential = z.output<typeof schema.credential>
+
+/** A passkey that wallet.tempo stores, with its credential ID, as {@link credentials} returns it. */
+export type Listed = Credential & {
+  /** The credential ID, base64url. */
+  credentialId: string
+}
+
+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}$/),
+    ]),
+  })
+
+  export const listed = z.array(
+    credential.extend({
+      credentialId: z.string().regex(/^[A-Za-z0-9_-]{1,1366}$/),
+    }),
+  )
+}
+
+/**
+ * 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 || !derives(result.data)) return undefined
+  return result.data
+}
+
+export declare namespace credential {
+  type Options = {
+    /** The credential ID, base64url. */
+    id: string
+  }
+}
+
+/**
+ * Returns the passkeys that wallet.tempo stores for the accounts whose verified email is `email`,
+ * oldest first. Call it only with the email of a signed-in user, whose sign-in proved it, so the list
+ * reveals nothing to another person. An entry that names an address its public key does not derive
+ * is left out, and a list of another shape is empty.
+ */
+export async function credentials(
+  wallet: Service,
+  options: credentials.Options,
+): Promise<readonly Listed[]> {
+  const result = schema.listed.safeParse(
+    await wallet.credentials({ email: options.email }),
+  )
+  if (!result.success) return []
+  return result.data.filter(derives)
+}
+
+export declare namespace credentials {
+  type Options = {
+    /** The signed-in user's verified email. */
+    email: string
+  }
+}
+
+/** Returns whether `credential`'s public key derives its address, whatever wallet.tempo returns. */
+function derives(credential: Credential) {
+  const derived = (() => {
+    try {
+      return Address.fromPublicKey(PublicKey.fromHex(credential.publicKey))
+    } catch {
+      return undefined
+    }
+  })()
+  return (
+    derived !== undefined &&
+    Address.isEqual(derived, credential.address as Address.Address)
+  )
+}

package/src/internal/owners/Passkey.ts

@@ -0,0 +1,76 @@
+/**
+ * Linked wallet.tempo passkeys, and passkeys that users register, as owner keys, which
+ * `TempoAccount.kinds` lists. Passkey sign-in, links, and registration live in `Passkey.ts`.
+ * @module
+ */
+import { and, asc, eq, inArray, isNotNull } from 'drizzle-orm'
+import type { Hex } from 'ox'
+import { Account } from 'viem/tempo'
+import * as Schema from '../../app/db/schema.js'
+import * as Owner from '../Owner.js'
+
+/**
+ * Linked wallet.tempo passkeys, and passkeys that users register, as owner keys. Each owns the
+ * account at the address that its public key derives, in each realm whose relying party the passkey
+ * belongs to. A sign-in passkey, whose row holds no address, owns no account. A
+ * passkey signs only in the browser, and an account's creation creates none.
+ */
+export const owner = Owner.kind({
+  errors: [],
+  load(_c, options) {
+    const { userId } = options
+    const realms = options.realms.filter((realm) => realm.passkeys)
+
+    return Promise.resolve({
+      async list(_c, options) {
+        if (realms.length === 0) return []
+
+        const keys = await options.db
+          .select()
+          .from(Schema.keys)
+          .where(
+            and(
+              eq(Schema.keys.userId, userId),
+              // A sign-in passkey holds no address, so it owns no account.
+              isNotNull(Schema.keys.address),
+              inArray(
+                Schema.keys.rpId,
+                realms.map((realm) => realm.passkeys!.rpId),
+              ),
+            ),
+          )
+          .orderBy(asc(Schema.keys.createdAt), asc(Schema.keys.id))
+
+        return keys.flatMap((key) =>
+          realms
+            .filter((realm) => realm.passkeys!.rpId === key.rpId)
+            .map((realm) =>
+              Owner.from({
+                account: Account.fromConfig({
+                  owners: [
+                    Account.fromWebAuthnP256(
+                      { id: key.id, publicKey: key.publicKey as Hex.Hex },
+                      { rpId: key.rpId },
+                    ),
+                  ],
+                }),
+                createdAt: key.createdAt,
+                credential: {
+                  id: key.id,
+                  publicKey: key.publicKey as Hex.Hex,
+                  rpId: key.rpId,
+                },
+                // `wallet` is the earlier name of the `tempo-wallet` source, until a migration
+                // renames it, so both are wallet.tempo passkeys that linked.
+                linked: ['tempo-wallet', 'wallet'].includes(key.source),
+                realm,
+                signer: undefined,
+                type: 'webAuthn',
+              }),
+            ),
+        )
+      },
+    })
+  },
+  type: 'webAuthn',
+})

package/src/internal/owners/Privy.ts

@@ -0,0 +1,82 @@
+/**
+ * Privy wallets as owner keys, which `TempoAccount.kinds` lists. The Privy client, its wallets, and
+ * its tokens live in `Privy.ts`.
+ * @module
+ */
+import * as ErrorResponse from '../ErrorResponse.js'
+import * as Owner from '../Owner.js'
+import * as Privy from '../Privy.js'
+import * as Realm from '../Realm.js'
+import * as Timing from '../Timing.js'
+
+/**
+ * Privy wallets as owner keys. A realm's Privy app holds the user's wallets in the realm, and creates
+ * the user's first wallet there. A wallet signs on the server with a token that only Privy trusts.
+ */
+export const owner = Owner.kind({
+  errors: ErrorResponse.fromUpstream.errors,
+  async load(c, options) {
+    const { db, env, realms, userId } = options
+    const apps = await Timing.measure(
+      c,
+      Realm.privyApps(c, { db, realms, secret: env.SECRET }),
+      'Realm.privyApps',
+    )
+
+    const toOwner = (
+      app: Privy.App,
+      realm: Realm.Realm,
+      wallet: Privy.Wallet,
+    ) =>
+      Owner.from({
+        account: Privy.toAccount({ app, wallet }),
+        createdAt: wallet.createdAt,
+        linked: false,
+        realm,
+        async signer(c, options) {
+          const jwt = await Timing.measure(
+            c,
+            Privy.token(options.auth, {
+              app,
+              privateKey: env.PRIVY_JWT_PRIVATE_KEY,
+              userId,
+            }),
+            'Privy.token',
+          )
+          return Privy.toAccount({ app, token: jwt, wallet }).owners[0]!
+        },
+        type: 'privy',
+      })
+
+    return {
+      create(realm) {
+        const app = apps.get(realm.id)
+        if (!app) return undefined
+        return async (c) => {
+          const wallet = await Timing.measure(
+            c,
+            Privy.firstWallet(c, { app, userId }),
+            'Privy.firstWallet',
+          )
+          return toOwner(app, realm, wallet)
+        }
+      },
+      async list(c) {
+        const lists = await Promise.all(
+          realms.map(async (realm) => {
+            const app = apps.get(realm.id)
+            if (!app) return []
+            const wallets = await Timing.measure(
+              c,
+              Privy.listWallets(c, { app, userId }),
+              'Privy.listWallets',
+            )
+            return wallets.map((wallet) => toOwner(app, realm, wallet))
+          }),
+        )
+        return Owner.merge(lists)
+      },
+    }
+  },
+  type: 'privy',
+})

package/src/internal/owners/Secp256k1.ts

@@ -0,0 +1,139 @@
+/**
+ * Secp256k1 owner keys that Tempo ID creates, holds, and signs with itself, in the place of a Privy
+ * wallet, for the suites and local development. Each user holds at most one in each realm that
+ * `realm_secp256k1` names, and its row holds the private key encrypted with `SECRET`. A production
+ * realm never turns them on, since the key stays in Tempo ID's database.
+ * @module
+ */
+import { symmetricDecrypt, symmetricEncrypt } from 'better-auth/crypto'
+import { and, asc, eq, inArray } from 'drizzle-orm'
+import type { Hex } from 'ox'
+import {
+  generatePrivateKey,
+  privateKeyToAccount,
+  toAccount,
+} from 'viem/accounts'
+import { Account } from 'viem/tempo'
+import * as Schema from '../../app/db/schema.js'
+import * as Owner from '../Owner.js'
+import type * as Realm from '../Realm.js'
+import * as Timing from '../Timing.js'
+
+/** The account of a listed owner signs nothing. Only the owner's `signer` signs. */
+export class SignerRequiredError extends Error {
+  override readonly name = 'Secp256k1.SignerRequiredError'
+
+  constructor() {
+    super(
+      "The account of a secp256k1 owner signs nothing. Sign with the owner's signer.",
+    )
+  }
+}
+
+/**
+ * Secp256k1 keys as owner keys. In each realm that holds them, the kind creates the user's first key
+ * and signs with it on the server.
+ */
+export const owner = Owner.kind({
+  errors: [],
+  load(_c, options) {
+    const { env, userId } = options
+    const realms = options.realms.filter((realm) => realm.secp256k1)
+
+    const toOwner = (row: Row, realm: Realm.Realm) =>
+      Owner.from({
+        account: Account.fromConfig({ owners: [unsigned(row.address)] }),
+        createdAt: row.createdAt,
+        linked: false,
+        realm,
+        async signer() {
+          const privateKey = await symmetricDecrypt({
+            data: row.privateKey,
+            key: env.SECRET,
+          })
+          return privateKeyToAccount(privateKey as Hex.Hex)
+        },
+        type: 'secp256k1',
+      })
+
+    return Promise.resolve({
+      create(realm) {
+        if (!realms.some((entry) => entry.id === realm.id)) return undefined
+        return async (c) => {
+          const privateKey = generatePrivateKey()
+          // A concurrent create for the same user and realm keeps the first key, and both return it.
+          // The update on conflict writes the stored user ID again, so the statement returns the row.
+          const [row] = await Timing.measure(
+            c,
+            options.db
+              .insert(Schema.secp256k1Owners)
+              .values({
+                address: privateKeyToAccount(privateKey).address,
+                privateKey: await symmetricEncrypt({
+                  data: privateKey,
+                  key: env.SECRET,
+                }),
+                realmId: realm.id,
+                userId,
+              })
+              .onConflictDoUpdate({
+                set: { userId },
+                target: [
+                  Schema.secp256k1Owners.userId,
+                  Schema.secp256k1Owners.realmId,
+                ],
+              })
+              .returning(),
+            'db.secp256k1Owner.insert',
+          )
+          return toOwner(row!, realm)
+        }
+      },
+      async list(c, options) {
+        if (realms.length === 0) return []
+
+        const rows = await Timing.measure(
+          c,
+          options.db
+            .select()
+            .from(Schema.secp256k1Owners)
+            .where(
+              and(
+                eq(Schema.secp256k1Owners.userId, userId),
+                inArray(
+                  Schema.secp256k1Owners.realmId,
+                  realms.map((realm) => realm.id),
+                ),
+              ),
+            )
+            .orderBy(
+              asc(Schema.secp256k1Owners.createdAt),
+              asc(Schema.secp256k1Owners.realmId),
+            ),
+          'db.secp256k1Owner.list',
+        )
+        return rows.map((row) =>
+          toOwner(
+            row,
+            realms.find((realm) => realm.id === row.realmId)!,
+          ),
+        )
+      },
+    })
+  },
+  type: 'secp256k1',
+})
+
+/** A row of `secp256k1_owners`. */
+type Row = typeof Schema.secp256k1Owners.$inferSelect
+
+/** Returns a Viem account for `address` that signs nothing, as a listed owner's account. */
+function unsigned(address: string) {
+  const refuse = () => Promise.reject(new SignerRequiredError())
+  return toAccount({
+    address: address as Hex.Hex,
+    signMessage: refuse,
+    signTransaction: refuse,
+    signTypedData: refuse,
+  })
+}