@tempoxyz/id 0.0.0-stage → 0.0.1

package/src/internal/RequestId.ts

@@ -0,0 +1,118 @@
+/**
+ * Request IDs for the Worker. Each request takes the Ray ID Cloudflare assigned it, or a random UUID
+ * without one, and never an ID the client sent. The ID goes out in `X-Request-Id` on every response
+ * and as `request_id` in every OAuth error body, so apps can quote it. `Log` records it with each
+ * entry, and `Timing` with each request's line.
+ * @module
+ */
+import type { Context } from 'hono'
+import { createMiddleware } from 'hono/factory'
+import { requestId } from 'hono/request-id'
+import type { Env } from './Env.js'
+import * as Timing from './Timing.js'
+
+/** The codes of a refusal's OAuth error body, which `Timing` logs with the request. */
+export type Refusal = {
+  /** The OAuth `error` code. */
+  error?: string | undefined
+  /** The refusal's `reason`. */
+  reason?: string | undefined
+}
+
+/** The response header that carries the request ID. */
+export const header = 'X-Request-Id'
+
+/**
+ * Assigns the request ID, and returns it in {@link header} and error bodies. An error body's codes
+ * go in `c.var.refusal`. Register it right after `Timing.middleware`, before any other middleware.
+ */
+export function middleware() {
+  // `headerName: ''` ignores any `X-Request-Id` the client sends, so logs only hold IDs the Worker
+  // chose. It also stops `requestId` from setting the header, which happens below instead.
+  const assign = requestId({ generator, headerName: '' })
+
+  return createMiddleware<Env>(async (c, next) => {
+    await assign(c, next)
+
+    const id = c.var.requestId
+    const response = c.res
+    const body = failed(response)
+      ? await Timing.measure(c, read(response), 'response.json')
+      : undefined
+    if (body) c.set('refusal', annotate(c, { body, id }))
+    c.header(header, id)
+  })
+}
+
+/**
+ * Replaces the response with its OAuth error `body` plus `request_id`, and returns the body's
+ * `error` and `reason` codes.
+ */
+function annotate(c: Context<Env>, options: annotate.Options): Refusal {
+  const response = c.res
+  c.res = new Response(
+    JSON.stringify({ ...options.body, request_id: options.id }),
+    {
+      headers: response.headers,
+      status: response.status,
+      statusText: response.statusText,
+    },
+  )
+  // Hono copies the old response's headers onto the new one, including a stale length.
+  c.header('content-length', undefined)
+
+  // Proxied bodies can hold anything, so only code-shaped values reach the log.
+  return {
+    error: code(options.body.error),
+    reason: code(options.body.reason),
+  }
+}
+
+declare namespace annotate {
+  type Options = {
+    /** The OAuth error body. */
+    body: Record<string, unknown>
+    /** The request ID. */
+    id: string
+  }
+}
+
+/** Returns `value` when it is a short snake-case code, such as an OAuth `error` or a `reason`. */
+function code(value: unknown) {
+  return typeof value === 'string' && /^[a-z_]{1,64}$/.test(value)
+    ? value
+    : undefined
+}
+
+/** Whether `response` is a JSON error response, which may hold an OAuth error body. */
+function failed(response: Response) {
+  return (
+    response.status >= 400 &&
+    !!response.headers.get('content-type')?.startsWith('application/json')
+  )
+}
+
+/**
+ * The Ray ID when the request carries a well-formed one, or a random UUID. Cloudflare sets `cf-ray`
+ * on every request it delivers, replacing any value the client sent.
+ */
+function generator(c: Context) {
+  const ray = c.req.header('cf-ray')
+  return ray && /^[\da-f]{16}(?:-[A-Z]{3})?$/.test(ray)
+    ? ray
+    : crypto.randomUUID()
+}
+
+/** Whether `value` is a plain JSON object. */
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/** Reads a copy of `response`'s body as an OAuth error, with a string `error`. */
+async function read(response: Response) {
+  const body: unknown = await response
+    .clone()
+    .json()
+    .catch(() => undefined)
+  return isRecord(body) && typeof body.error === 'string' ? body : undefined
+}

package/src/internal/SignInGrant.ts

@@ -0,0 +1,175 @@
+/**
+ * Records the grants of keys that the sign-in page showed. A sign-in that continues an app's
+ * authorization request with a key grants the key, and spends the request, so a replayed request
+ * grants nothing, and the sign-in page shows no key for it. A sign-in that reaches the account step
+ * holds its grant for the session until the user chooses an account. Each record lives in Better
+ * Auth's `verification` table.
+ * @module
+ */
+import { and, eq, gt } from 'drizzle-orm'
+import { Bytes, Hash, Hex } from 'ox'
+import * as z from 'zod'
+import * as Schema from '../app/db/schema.js'
+import type * as Realm from './Realm.js'
+import * as Verification from './Verification.js'
+
+/** How long a held grant waits for the account step, in seconds. */
+const heldLifetime = 10 * 60
+
+/** The prefix of a held grant's `verification` identifier. */
+const heldPrefix = 'sign-in-grant-held:'
+
+/**
+ * How long a spent request stays recorded when its query names no expiry, in seconds. Better Auth's
+ * signed queries expire sooner.
+ */
+const spentLifetime = 60 * 60
+
+/** The prefix of a spent request's `verification` identifier. */
+const spentPrefix = 'sign-in-grant-spent:'
+
+namespace schema {
+  // The assertion of a sign-in with key signature stays opaque here. The route that takes it
+  // validates it again.
+  export const held = z.object({
+    assertion: z.unknown().optional(),
+    witness: z.templateLiteral(['0x', z.string()]).optional(),
+  })
+}
+
+/**
+ * Holds the grant of the request `query` for the session with `sessionId`, until the user chooses
+ * an account on the account step. A sign-in with key signature holds its assertion and witness too.
+ */
+export async function hold(db: Realm.Database, options: hold.Options) {
+  await db.insert(Schema.verification).values({
+    expiresAt: new Date(Date.now() + heldLifetime * 1000),
+    id: crypto.randomUUID(),
+    identifier: heldIdentifier(options),
+    value: JSON.stringify(
+      schema.held.parse({
+        assertion: options.keySignature?.assertion,
+        witness: options.keySignature?.witness,
+      }),
+    ),
+  })
+}
+
+export declare namespace hold {
+  type Options = {
+    /** The assertion and witness of the sign-in with key signature, if the sign-in was one. */
+    keySignature?:
+      | {
+          /** The passkey's assertion, as the sign-in received it. */
+          assertion: unknown
+          /** The witness that the key's digest binds. */
+          witness: Hex.Hex
+        }
+      | undefined
+    /** The authorization request, as Better Auth signed it for the account step. */
+    query: URLSearchParams
+    /** The ID of the session that the sign-in created. */
+    sessionId: string
+  }
+}
+
+/**
+ * Returns the identity of an app's authorization request in `query`: the SHA-256 digest of its
+ * client ID, redirect URI, `state`, `code_challenge`, `key_authorization`, `challenge`, and `scope`,
+ * as hex. Better Auth signs the query again for each page that it sends the browser to, and keeps
+ * these parameters. A request that changes any of them, such as one that adds a challenge, has
+ * another identity, so it takes no grant of the first.
+ */
+function identity(query: URLSearchParams) {
+  const parts = [
+    'client_id',
+    'redirect_uri',
+    'state',
+    'code_challenge',
+    'key_authorization',
+    'challenge',
+    'scope',
+  ].map((name) => query.get(name) ?? '')
+  return Hex.fromBytes(Hash.sha256(Bytes.fromString(JSON.stringify(parts))))
+}
+
+/**
+ * Records the request `query` as spent by a sign-in, until its query expires, and returns whether
+ * this call spent it. A request that a sign-in spent before returns `false`, and grants nothing.
+ */
+export async function spend(db: Realm.Database, options: spend.Options) {
+  const identifier = spentPrefix + identity(options.query)
+  const expires = Number(options.query.get('exp'))
+  const expiresAt = new Date(
+    Number.isSafeInteger(expires) && expires > 0
+      ? expires * 1000
+      : Date.now() + spentLifetime * 1000,
+  )
+  // Concurrent sign-ins of one request claim one identifier, so only the first records it.
+  return await Verification.claim(db, { expiresAt, identifier, value: '{}' })
+}
+
+export declare namespace spend {
+  type Options = {
+    /** The authorization request, whose `exp` bounds the record. */
+    query: URLSearchParams
+  }
+}
+
+/** Returns whether a sign-in already spent the request `query`, which then grants nothing. */
+export async function spent(db: Realm.Database, options: spent.Options) {
+  const [row] = await db
+    .select({ id: Schema.verification.id })
+    .from(Schema.verification)
+    .where(
+      and(
+        eq(
+          Schema.verification.identifier,
+          spentPrefix + identity(options.query),
+        ),
+        gt(Schema.verification.expiresAt, new Date()),
+      ),
+    )
+    .limit(1)
+  return row !== undefined
+}
+
+export declare namespace spent {
+  type Options = {
+    /** The authorization request, as Better Auth signed it for the sign-in page. */
+    query: URLSearchParams
+  }
+}
+
+/**
+ * Deletes and returns the grant that a sign-in held for the request `query` and the session with
+ * `sessionId`, or `undefined` when none waits. One statement deletes and returns the row, so two
+ * concurrent account steps cannot both take it.
+ */
+export async function take(db: Realm.Database, options: take.Options) {
+  const [row] = await db
+    .delete(Schema.verification)
+    .where(
+      and(
+        eq(Schema.verification.identifier, heldIdentifier(options)),
+        gt(Schema.verification.expiresAt, new Date()),
+      ),
+    )
+    .returning({ value: Schema.verification.value })
+  if (!row) return undefined
+  return schema.held.parse(JSON.parse(row.value))
+}
+
+export declare namespace take {
+  type Options = {
+    /** The authorization request, as Better Auth signed it after the account step. */
+    query: URLSearchParams
+    /** The ID of the signed-in session. */
+    sessionId: string
+  }
+}
+
+/** Returns the `verification` identifier of the grant held for a request and a session. */
+function heldIdentifier(options: take.Options) {
+  return `${heldPrefix}${identity(options.query)}:${options.sessionId}`
+}

package/src/internal/SigningKey.ts

@@ -0,0 +1,319 @@
+/**
+ * The keys that sign Tempo ID's tokens: the JWT plugin's key options, and the rotation that
+ * `tempo-id admin rotate-key` runs on the `jwks` table. A rotation writes the row that the plugin
+ * writes when it creates a key, with Better Auth's key generation and encryption.
+ * @module
+ */
+import type { GenericEndpointContext } from '@better-auth/core'
+import { getCurrentAdapter } from '@better-auth/core/context'
+import { symmetricDecrypt, symmetricEncrypt } from 'better-auth/crypto'
+import { generateExportedKeyPair, type Jwk } from 'better-auth/plugins/jwt'
+import { count, desc, eq, gt, isNull, or, sql } from 'drizzle-orm'
+import { decodeProtectedHeader } from 'jose'
+import * as Schema from '../app/db/schema.js'
+import type * as Cache from './Cache.js'
+import type * as Realm from './Realm.js'
+
+/**
+ * As many keys as the JWT plugin reads are live or in their grace period, so the plugin would not
+ * read a new key.
+ */
+export class FullError extends Error {
+  override readonly name = 'SigningKey.FullError'
+
+  constructor() {
+    super(
+      `Too many signing keys: ${capacity} keys are live or in their 30-day grace period. Rotate again once the oldest grace period ends.`,
+    )
+  }
+}
+
+/** The table holds no signing key yet, so a rotation has no key to retire. */
+export class MissingError extends Error {
+  override readonly name = 'SigningKey.MissingError'
+
+  constructor() {
+    super(
+      'No signing key exists. Tempo ID creates the first key when it signs its first token.',
+    )
+  }
+}
+
+/** The secret does not decrypt the current signing key, so the Worker could not use a new one. */
+export class SecretError extends Error {
+  override readonly name = 'SigningKey.SecretError'
+
+  constructor() {
+    super(
+      "Invalid SECRET: it does not decrypt the current signing key. Set SECRET to the deployment's SECRET variable.",
+    )
+  }
+}
+
+/**
+ * Seconds that `GET /oauth2/jwks` serves a key after it stops signing, so verifiers accept the tokens
+ * that it signed before. This is Better Auth's default, 30 days.
+ */
+export const gracePeriod = 60 * 60 * 24 * 30
+
+/**
+ * Seconds between a rotation and the first token that the new key signs. `GET /oauth2/jwks` serves
+ * the new key at once, and a verifier caches the response for 60 seconds at most. So a verifier that
+ * caches the key set, with a refetch cooldown such as jose's 30 seconds, holds the key before any
+ * token names it.
+ */
+export const publication = 5 * 60
+
+/**
+ * The most keys that the JWT plugin reads: Better Auth's default limit on a read. A rotation keeps
+ * the live keys and the keys in their grace period within it.
+ */
+export const capacity = 100
+
+/** The JWT plugin's `jwks` options. RS256, since Privy and the existing verifiers accept it. */
+export const jwks = {
+  gracePeriod,
+  jwksPath: '/oauth2/jwks',
+  keyPairConfig: { alg: 'RS256' as const, modulusLength: 2048 },
+}
+
+/**
+ * The JWT plugin's read of the `jwks` table: every live key, and every key in its grace period.
+ * Better Auth's own read returns any 100 rows, and a rotation backdates each new key's `createdAt`,
+ * so neither row order nor creation time can pick the keys once retired rows build up.
+ */
+export function adapter(options: adapter.Options = {}) {
+  return {
+    getJwks: async (ctx: GenericEndpointContext) => {
+      // `GET /oauth2/jwks` serves every committed key at once, such as a first key that another
+      // isolate created at the same time, so a verifier that refetches for an unknown `kid` finds it.
+      if (ctx.path === jwks.jwksPath) return await readJwks(ctx)
+      // A new key signs only after the publication delay, and the entry lives a fifth of it, so
+      // the old key stops signing well before the rotation's `signsFrom`, though a read starts
+      // before the rotation commits. An empty table stays uncached, since the plugin then creates
+      // the first key.
+      if (!options.cache) return await readJwks(ctx)
+      return [
+        ...(await options.cache.get(() => readJwks(ctx), ['signingKey.jwks'], {
+          keep: (keys) => keys.length > 0,
+          ttl: (publication / 5) * 1000,
+        })),
+      ]
+    },
+  }
+}
+
+export declare namespace adapter {
+  type Options = {
+    /**
+     * The isolate's cache of configuration rows, which holds the keys still encrypted. Absent, each
+     * read reads the database.
+     */
+    cache?: Cache.Cache | undefined
+  }
+}
+
+/**
+ * Returns the public key that an ID token hint names in its `kid` header, as a key set, retired keys
+ * included, past the grace period too. Logout verifies the hint against it, since a session can
+ * outlast the grace period of the key that signed its ID token. A hint without a `kid`, or with an
+ * unknown one, returns an empty set. Tokens that grant access verify only against the keys that
+ * `GET /oauth2/jwks` serves.
+ */
+export async function hintKeys(
+  db: Realm.Database,
+  options: hintKeys.Options,
+): Promise<hintKeys.ReturnType> {
+  // The header is read before the signature is checked, so a forged hint costs one indexed read.
+  const kid = (() => {
+    try {
+      return decodeProtectedHeader(options.hint).kid
+    } catch {
+      return undefined
+    }
+  })()
+  if (!kid) return { keys: [] }
+
+  const rows = await db
+    .select()
+    .from(Schema.jwks)
+    .where(eq(Schema.jwks.id, kid))
+    .limit(1)
+  return {
+    keys: rows.map((row) => ({
+      ...(JSON.parse(row.publicKey) as JsonWebKey),
+      alg: row.alg ?? jwks.keyPairConfig.alg,
+      kid: row.id,
+    })),
+  }
+}
+
+export declare namespace hintKeys {
+  type Options = {
+    /** The ID token hint, whose `kid` header names its signing key. */
+    hint: string
+  }
+
+  type ReturnType = {
+    /** Each public key, with its ID as `kid`. */
+    keys: (JsonWebKey & {
+      /** The key's ID, which each token that it signed names as `kid`. */
+      kid: string
+    })[]
+  }
+}
+
+/**
+ * Adds a new signing key, which signs every token after the {@link publication} delay, and retires
+ * every earlier key that is still live at the end of that delay. `GET /oauth2/jwks` serves the new key
+ * at once, and serves each retired key until its grace period ends.
+ *
+ * Throws `MissingError` when no key exists, `SecretError` when `secret` does not decrypt the current
+ * key, and `FullError` when `capacity` keys are live or in their grace period.
+ */
+export async function rotate(
+  db: Realm.Database,
+  options: rotate.Options,
+): Promise<rotate.ReturnType> {
+  const { secret } = options
+
+  return await db.transaction(async (tx) => {
+    // Serializes rotations, and keeps the Worker from creating a key between the read and the writes.
+    // Reads proceed, so the Worker signs with the current key until the commit.
+    await tx.execute(sql`lock table ${Schema.jwks} in share row exclusive mode`)
+
+    // The database's clock, which every deployment shares, so a skewed clock on the machine that
+    // runs the command cannot end the publication delay early. `clock_timestamp()` reads it after the
+    // lock, where `now()` would return the transaction's start and count the wait for the lock.
+    const [clock] = await tx
+      .select({
+        now: sql<number>`(extract(epoch from clock_timestamp()) * 1000)::float8`,
+      })
+      .from(Schema.jwks)
+      .limit(1)
+    if (!clock) throw new MissingError()
+    const now = new Date(Number(clock.now))
+    const signsFrom = new Date(now.getTime() + publication * 1000)
+    const live = await tx
+      .select()
+      .from(Schema.jwks)
+      .where(or(isNull(Schema.jwks.expiresAt), gt(Schema.jwks.expiresAt, now)))
+      .orderBy(desc(Schema.jwks.createdAt))
+    const [current] = live
+    const oldest = live.at(-1)
+    if (!current || !oldest) throw new MissingError()
+
+    // A key encrypted with another secret would fail every signature, so the rotation checks first.
+    const decrypted = await symmetricDecrypt({
+      data: JSON.parse(current.privateKey) as string,
+      key: secret,
+    }).catch(() => undefined)
+    if (decrypted === undefined) throw new SecretError()
+
+    // The read returns at most `capacity` rows, and a rotated key sorts last, so one more would hide it.
+    // The Worker applies the grace cutoff by its own clock, so the count also includes the keys whose
+    // grace period ended up to `publication` seconds ago, in case that clock is behind the database's.
+    const [served] = await tx
+      .select({ count: count() })
+      .from(Schema.jwks)
+      .where(
+        or(
+          isNull(Schema.jwks.expiresAt),
+          gt(
+            Schema.jwks.expiresAt,
+            new Date(now.getTime() - (gracePeriod + publication) * 1000),
+          ),
+        ),
+      )
+    if (served!.count >= capacity) throw new FullError()
+
+    const pair = await generateExportedKeyPair({ jwks })
+    const [key] = await tx
+      .insert(Schema.jwks)
+      .values({
+        alg: pair.alg,
+        // Better Auth signs with the live key of the latest `createdAt`. A `createdAt` before every
+        // live key's keeps the new key from signing until the earlier keys expire at `signsFrom`.
+        createdAt: new Date(oldest.createdAt.getTime() - 1),
+        id: crypto.randomUUID(),
+        // The JWT plugin stores the encrypted key as a JSON string.
+        privateKey: JSON.stringify(
+          await symmetricEncrypt({
+            data: JSON.stringify(pair.privateWebKey),
+            key: secret,
+          }),
+        ),
+        publicKey: JSON.stringify(pair.publicWebKey),
+      })
+      .returning({ id: Schema.jwks.id })
+
+    // A key that an earlier rotation already retires keeps its earlier expiry.
+    const retired = live.map((entry) => ({
+      expiresAt:
+        entry.expiresAt && entry.expiresAt < signsFrom
+          ? entry.expiresAt
+          : signsFrom,
+      id: entry.id,
+    }))
+    for (const entry of retired)
+      await tx
+        .update(Schema.jwks)
+        .set({ expiresAt: entry.expiresAt })
+        .where(eq(Schema.jwks.id, entry.id))
+
+    return {
+      key: { id: key!.id, signsFrom },
+      retired: retired.map((entry) => ({
+        id: entry.id,
+        servedUntil: new Date(entry.expiresAt.getTime() + gracePeriod * 1000),
+        signsUntil: entry.expiresAt,
+      })),
+    }
+  })
+}
+
+export declare namespace rotate {
+  type Options = {
+    /** The deployment's `SECRET` variable, which encrypts each private key. */
+    secret: string
+  }
+
+  type ReturnType = {
+    /** The new signing key. */
+    key: {
+      /** The key's ID, which each token names as `kid`. */
+      id: string
+      /** When the key signs its first token, after the publication delay. */
+      signsFrom: Date
+    }
+    /** The keys that the rotation retires, newest first. */
+    retired: readonly {
+      /** The key's ID. */
+      id: string
+      /** When `GET /oauth2/jwks` stops serving the key. */
+      servedUntil: Date
+      /** When the key signs its last token. */
+      signsUntil: Date
+    }[]
+  }
+}
+
+/** Reads every live key, and every key in its grace period, past the cache. */
+async function readJwks(ctx: GenericEndpointContext) {
+  return await (
+    await getCurrentAdapter(ctx.context.adapter)
+  ).findMany<Jwk>({
+    limit: capacity,
+    model: 'jwks',
+    sortBy: { direction: 'desc', field: 'createdAt' },
+    where: [
+      { connector: 'OR', field: 'expiresAt', value: null },
+      {
+        connector: 'OR',
+        field: 'expiresAt',
+        operator: 'gt',
+        value: new Date(Date.now() - gracePeriod * 1000),
+      },
+    ],
+  })
+}