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

package/src/internal/Limits.ts

@@ -0,0 +1,39 @@
+/**
+ * The Workers rate limits that the app reads, by binding name. `void.config.ts` and `tempo-id init`
+ * declare a binding for each, and `RateLimit` reports each in `RateLimit-Policy`. The module imports
+ * nothing, since Void loads `void.config.ts` in Node.
+ * @module
+ */
+
+/**
+ * Each rate limit by its binding name. Each limit counts per Cloudflare location over `period`
+ * seconds, and a binding cannot report its own configuration, so the app reads it here.
+ */
+export const limits = {
+  /** Account reads per signed-in user, each of which can read every Privy app of the app's realms. */
+  ACCOUNT_LIMIT: { limit: 60, namespace: '1007', period: 60 },
+  /** Headless authorizations per signed-in user. */
+  AUTHORIZE_LIMIT: { limit: 60, namespace: '1001', period: 60 },
+  /** Device code requests per IP address. */
+  DEVICE_LIMIT: { limit: 10, namespace: '1002', period: 60 },
+  /** Code sends per email address. */
+  SIGN_IN_CODE_LIMIT: { limit: 5, namespace: '1003', period: 60 },
+  /** Code sends, code verifications, and redirects to a provider together, per IP address. */
+  SIGN_IN_IP_LIMIT: { limit: 100, namespace: '1004', period: 60 },
+  /**
+   * Token requests per app with a client secret, counted only once the request's secret matches, so
+   * a caller cannot spend another app's quota by naming its client ID.
+   */
+  TOKEN_APP_LIMIT: { limit: 600, namespace: '1008', period: 60 },
+  /** Token requests per IP address. */
+  TOKEN_LIMIT: { limit: 300, namespace: '1006', period: 60 },
+} as const
+
+/** A rate limit's binding name, such as `TOKEN_LIMIT`. */
+export type Limit = keyof typeof limits
+
+/**
+ * The limits that a deployment's Wrangler config can lack, since they came after the config. A
+ * missing binding skips such a limit, and fails the request for any other limit.
+ */
+export const optional: readonly Limit[] = ['TOKEN_APP_LIMIT']

package/src/internal/Log.ts

@@ -0,0 +1,178 @@
+/**
+ * Structured logs for the Worker. Each entry is one object on the console at its level, which
+ * Workers Logs indexes by field. An entry holds a fixed message and chosen fields. It also holds the
+ * request's ID, method, and route when a context is given, and an error's name, message, and stack
+ * frames. Headers, bodies, query strings, path parameters, and other error properties never reach a
+ * log. The Vite dev server prints each entry as one condensed line instead of an object.
+ * @module
+ */
+import type { Context } from 'hono'
+import * as LogLine from './LogLine.js'
+
+/** What a log entry records. */
+export type Options = {
+  /** The error behind the entry. */
+  error?: unknown
+  /** Extra fields to index, such as an app's client ID. Never secrets, tokens, or personal data. */
+  fields?: Record<string, boolean | number | string | undefined> | undefined
+  /** A fixed sentence naming what happened. Occurrences group by it, so it never interpolates values. */
+  message: string
+}
+
+/**
+ * Returns whether the module runs on the Vite dev server, which sets `import.meta.env.DEV`. A build
+ * replaces the expression, and a runtime without Vite leaves `import.meta.env` undefined.
+ */
+export function dev() {
+  return (import.meta as Meta).env?.DEV === true
+}
+
+/**
+ * Logs an unexpected failure. Pass the context of the request being served, or only the options
+ * outside a request, such as in a cron trigger.
+ */
+export function error(c: Context, options: Options): void
+export function error(options: Options): void
+export function error(...parameters: [Context, Options] | [Options]) {
+  console.error(print(entry(...parameters), { level: 'error' }))
+}
+
+/**
+ * Logs a routine event worth keeping, such as a configuration change. Pass the context of the
+ * request being served, or only the options outside a request.
+ */
+export function info(c: Context, options: Options): void
+export function info(options: Options): void
+export function info(...parameters: [Context, Options] | [Options]) {
+  console.info(print(entry(...parameters), { level: 'info' }))
+}
+
+/**
+ * Returns the pattern of the first matched route without a wildcard, such as
+ * `/v1/device/requests/:code`, which hides path parameters like a user code. A request that no
+ * such route matches returns `/*`, since its path is the caller's and can carry a code. Such a
+ * request can be a page, a path that no route declares, or a method that a route does not accept.
+ */
+export function route(c: Context) {
+  // The `hono/route` helper reads a symbol of its own Hono copy, and the Vite dev server loads Void's
+  // Hono as another copy. The request's own getter works with either.
+  return (
+    c.req.matchedRoutes.find((entry) => !entry.path.includes('*'))?.path ?? '/*'
+  )
+}
+
+/**
+ * Logs a recoverable problem that needs attention but did not fail the request. Pass the context of
+ * the request being served, or only the options outside a request.
+ */
+export function warn(c: Context, options: Options): void
+export function warn(options: Options): void
+export function warn(...parameters: [Context, Options] | [Options]) {
+  console.warn(print(entry(...parameters), { level: 'warn' }))
+}
+
+/** The part of `import.meta` that Vite fills. */
+type Meta = ImportMeta & {
+  /** The variables Vite defines. Absent outside Vite. */
+  env?:
+    | {
+        /** Whether the module runs on the Vite dev server. */
+        DEV?: boolean | undefined
+      }
+    | undefined
+}
+
+/** Returns an object without its `undefined` properties. */
+function compact(value: Record<string, unknown>) {
+  return Object.fromEntries(
+    Object.entries(value).filter((pair) => pair[1] !== undefined),
+  )
+}
+
+/** The parts of an error that are safe to log, with its causes up to three deep. */
+function describe(
+  error: unknown,
+  options: describe.Options = { depth: 0 },
+): Record<string, unknown> {
+  // A thrown value that is not an `Error` can be anything, including a secret.
+  if (!(error instanceof Error)) return { name: 'NonError', type: typeof error }
+
+  // Viem and ox put request arguments, which can hold ID tokens and proofs, in `message`, and a
+  // summary in `shortMessage`. Drizzle puts a failed query's parameters, which can hold an email
+  // address or a code, in `message`, and the query alone in `query`. The stack repeats the message,
+  // so only its frames are kept.
+  const message = (() => {
+    const shortMessage = read(error, { key: 'shortMessage' })
+    if (typeof shortMessage === 'string') return shortMessage
+    const query = read(error, { key: 'query' })
+    if (
+      typeof query === 'string' &&
+      Array.isArray(Reflect.get(error, 'params'))
+    )
+      return `Failed query: ${query}`
+    return error.message
+  })()
+  const status = read(error, { key: 'status' })
+  return compact({
+    cause:
+      error.cause !== undefined && options.depth < 3
+        ? describe(error.cause, { depth: options.depth + 1 })
+        : undefined,
+    code: read(error, { key: 'code' }),
+    message,
+    name: error.name,
+    stack: error.stack
+      ?.split('\n')
+      .filter((line) => /^\s+at /.test(line))
+      .map((line) => line.trim())
+      .join('\n'),
+    status: typeof status === 'number' ? status : undefined,
+  })
+}
+
+declare namespace describe {
+  type Options = {
+    /** How many causes deep this error is. */
+    depth: number
+  }
+}
+
+/** Builds the logged object, leaving out absent fields. */
+function entry(...parameters: [Context, Options] | [Options]) {
+  const [c, options] =
+    parameters.length === 2 ? parameters : [undefined, parameters[0]]
+  const { error, fields, message } = options
+  return compact({
+    // Fields come first, so they never replace the entry's own keys.
+    ...fields,
+    error: error === undefined ? undefined : describe(error),
+    message,
+    request: c
+      ? compact({
+          id: c.get('requestId'),
+          method: c.req.method,
+          path: route(c),
+        })
+      : undefined,
+  })
+}
+
+/**
+ * Returns the entry as the console receives it. The entry is an object, which Workers Logs indexes
+ * by field. On the Vite dev server, it is one condensed line, since that terminal prints objects
+ * across many lines.
+ */
+function print(
+  value: Record<string, unknown>,
+  options: LogLine.format.Options,
+) {
+  return dev() ? LogLine.format(value, options) : value
+}
+
+/** Reads an error property when it is a string or number. */
+function read(error: Error, options: { key: string }) {
+  const value: unknown = Reflect.get(error, options.key)
+  return typeof value === 'string' || typeof value === 'number'
+    ? value
+    : undefined
+}

package/src/internal/LogLine.ts

@@ -0,0 +1,87 @@
+/**
+ * Prints `Log` entries as condensed lines on the Vite dev server, whose terminal spreads an object
+ * across many lines. Deployed Workers and the tests run the production build, which logs objects.
+ * @module
+ */
+
+/** Each level's label and ANSI color in the dev server's lines. */
+const levels = {
+  error: { color: 31, label: 'ERROR' },
+  info: { color: 32, label: ' INFO' },
+  warn: { color: 33, label: ' WARN' },
+} as const
+
+/**
+ * Flattens nested objects into `[key, value]` pairs with dotted keys, such as `request.id`, in the
+ * entry's order.
+ */
+function flatten(
+  value: object,
+  options: flatten.Options = { prefix: '' },
+): [string, unknown][] {
+  return Object.entries(value).flatMap((pair): [string, unknown][] => {
+    const key = `${options.prefix}${pair[0]}`
+    const item: unknown = pair[1]
+    if (typeof item === 'object' && item !== null && !Array.isArray(item))
+      return flatten(item, { prefix: `${key}.` })
+    return [[key, item]]
+  })
+}
+
+declare namespace flatten {
+  type Options = {
+    /** The dotted path of the object being flattened, such as `error.cause.`. */
+    prefix: string
+  }
+}
+
+/**
+ * Formats a log entry as one line in the style of Rust's `tracing`: the time, the colored level, the
+ * message, then each field as `key=value`. Stack frames follow on indented lines.
+ */
+export function format(
+  value: Record<string, unknown>,
+  options: format.Options,
+) {
+  const { message, ...fields } = value
+  const level = levels[options.level]
+  const pairs = flatten(fields)
+
+  const head = [
+    `\x1b[2m${new Date().toISOString().slice(11, 23)}\x1b[0m`,
+    `\x1b[1;${level.color}m${level.label}\x1b[0m`,
+    `\x1b[1m${String(message)}\x1b[0m`,
+    ...pairs
+      .filter((pair) => !pair[0].endsWith('stack'))
+      .map(
+        (pair) => `\x1b[3m${pair[0]}\x1b[0m\x1b[2m=\x1b[0m${quote(pair[1])}`,
+      ),
+  ].join(' ')
+  const frames = pairs
+    .filter((pair) => pair[0].endsWith('stack'))
+    .flatMap((pair) => String(pair[1]).split('\n'))
+    // Paths start at `src/` or `node_modules/`, without the checkout or pnpm's store directory.
+    .map((frame) =>
+      frame
+        .replace(
+          /\/node_modules\/\.pnpm\/[^/]+\/node_modules\//,
+          '/node_modules/',
+        )
+        .replace(/\((?:\/[^()]*?)?\/((?:node_modules|src)\/[^()]*)\)/, '($1)'),
+    )
+    .map((frame) => `\x1b[2m    ${frame}\x1b[0m`)
+  return [head, ...frames].join('\n')
+}
+
+export declare namespace format {
+  type Options = {
+    /** The entry's level. */
+    level: keyof typeof levels
+  }
+}
+
+/** Quotes a field's value when it holds whitespace, a quote, or `=`, so each pair stays one token. */
+function quote(value: unknown) {
+  const text = String(value)
+  return /[\s"=]/.test(text) || text === '' ? JSON.stringify(text) : text
+}

package/src/internal/Logout.ts

@@ -0,0 +1,336 @@
+/**
+ * RP-initiated logout ([OpenID Connect RP-Initiated Logout 1.0](https://openid.net/specs/openid-connect-rpinitiated-1_0.html)):
+ * the checks on an app's ID token hint and post-logout redirect URI, and the revocation of the apps'
+ * refresh tokens when the session ends. Tempo ID verifies the hint against its own signing keys in
+ * process.
+ * @module
+ */
+import { symmetricDecrypt, symmetricEncrypt } from 'better-auth/crypto'
+import { and, eq, isNull } from 'drizzle-orm'
+import type { JSONWebKeySet } from 'jose'
+import { compactVerify, createLocalJWKSet } from 'jose'
+import { Hex } from 'ox'
+import * as z from 'zod'
+import * as Schema from '../app/db/schema.js'
+import * as ErrorResponse from './ErrorResponse.js'
+import type * as Realm from './Realm.js'
+
+/** How long a sealed logout request stays valid, in seconds. */
+const continuationTtl = 60
+
+namespace schema {
+  /** The parameters of a logout request that `seal` carries from a form POST to the GET. */
+  export const continuation = z.object({
+    client_id: z.string().optional(),
+    expiresAt: z.number(),
+    id_token_hint: z.string(),
+    post_logout_redirect_uri: z.string().optional(),
+    state: z.string().optional(),
+  })
+}
+
+/** The ID token hint is not an ID token that Tempo ID signed for the app. */
+export class HintInvalidError extends ErrorResponse.define(
+  'invalid_id_token_hint',
+) {
+  override readonly name = 'Logout.HintInvalidError'
+
+  constructor() {
+    super({
+      error_description:
+        'Invalid id_token_hint: it is not an ID token that this issuer signed for the app. Send the ID token that the app received at sign-in.',
+      field: 'id_token_hint',
+    })
+  }
+}
+
+/** The app that the hint names may not end the session. */
+export class NotPermittedError extends ErrorResponse.define(
+  'logout_not_permitted',
+) {
+  override readonly name = 'Logout.NotPermittedError'
+
+  constructor(options: NotPermittedError.Options) {
+    super({
+      error_description: `Logout not permitted: the app ${options.clientId} may not end the session. Register the app for logout, then retry.`,
+      meta: { client_id: options.clientId },
+    })
+  }
+}
+
+export declare namespace NotPermittedError {
+  type Options = {
+    /** The client ID of the app that the hint names. */
+    clientId: string
+  }
+}
+
+/** The post-logout redirect URI is not one that the app registered. */
+export class RedirectNotPermittedError extends ErrorResponse.define(
+  'post_logout_redirect_not_permitted',
+) {
+  override readonly name = 'Logout.RedirectNotPermittedError'
+
+  constructor(options: RedirectNotPermittedError.Options) {
+    super({
+      error_description: `Invalid post_logout_redirect_uri: ${options.uri} is not registered for the app. Use one of its post-logout redirect URIs, or leave it out.`,
+      field: 'post_logout_redirect_uri',
+      meta: { post_logout_redirect_uri: options.uri },
+    })
+  }
+}
+
+export declare namespace RedirectNotPermittedError {
+  type Options = {
+    /** The refused post-logout redirect URI. */
+    uri: string
+  }
+}
+
+/**
+ * Checks a logout request: the hint's signature, issuer, and app, then the app's registration and the
+ * post-logout redirect URI. Returns the session to end and the URI to redirect to, or the refusal.
+ */
+export async function check(
+  db: Realm.Database,
+  options: check.Options,
+): Promise<check.ReturnType | ErrorResponse.Instance<typeof check.errors>> {
+  const hint = await verify(options)
+  if (hint instanceof HintInvalidError) return hint
+
+  const [client] = await db
+    .select({
+      disabled: Schema.oauthClient.disabled,
+      enableEndSession: Schema.oauthClient.enableEndSession,
+      postLogoutRedirectUris: Schema.oauthClient.postLogoutRedirectUris,
+    })
+    .from(Schema.oauthClient)
+    .where(eq(Schema.oauthClient.clientId, hint.clientId))
+  if (!client || client.disabled || !client.enableEndSession)
+    return new NotPermittedError({ clientId: hint.clientId })
+
+  const redirect = (() => {
+    const uri = options.postLogoutRedirectUri
+    if (uri === undefined) return undefined
+    // RP-Initiated Logout §3 compares the URI exactly, as the authorization endpoint does.
+    if (!(client.postLogoutRedirectUris ?? []).includes(uri))
+      return new RedirectNotPermittedError({ uri })
+    const url = new URL(uri)
+    if (options.state !== undefined)
+      url.searchParams.set('state', options.state)
+    return url.href
+  })()
+  if (redirect instanceof RedirectNotPermittedError) return redirect
+
+  return { redirect, sessionId: hint.sessionId }
+}
+
+export namespace check {
+  /** The refusals `check` returns. */
+  export const errors = [
+    HintInvalidError,
+    NotPermittedError,
+    RedirectNotPermittedError,
+  ] as const
+}
+
+export declare namespace check {
+  type Options = verify.Options & {
+    /** Where the app asks the browser to go after logout. Absent for no redirect. */
+    postLogoutRedirectUri?: string | undefined
+    /** The value that the redirect carries back to the app as `state`. */
+    state?: string | undefined
+  }
+
+  type ReturnType = {
+    /** The post-logout redirect URI with `state`, or absent when the request names none. */
+    redirect: string | undefined
+    /** The ID of the session that the hint names. */
+    sessionId: string
+  }
+}
+
+/**
+ * Throws when the session with `sessionId` still exists. Better Auth's sign-out logs a failed delete
+ * and returns as if it succeeded, so logout checks the row before it reports success.
+ */
+export async function assertEnded(
+  db: Realm.Database,
+  options: assertEnded.Options,
+) {
+  const [row] = await db
+    .select({ id: Schema.session.id })
+    .from(Schema.session)
+    .where(eq(Schema.session.id, options.sessionId))
+  if (row) throw new Error('The session still exists after sign-out.')
+}
+
+export declare namespace assertEnded {
+  type Options = {
+    /** The ID of the session that sign-out ended. */
+    sessionId: string
+  }
+}
+
+/**
+ * Encrypts the parameters of a logout request with a key derived from `secret`, for the URL that a
+ * form POST continues at. It expires after a minute, and cannot be read or forged without the
+ * secret.
+ */
+export async function seal(parameters: seal.Parameters, options: seal.Options) {
+  return await symmetricEncrypt({
+    data: JSON.stringify(
+      schema.continuation.parse({
+        ...parameters,
+        expiresAt: Math.floor(Date.now() / 1000) + continuationTtl,
+      }),
+    ),
+    key: await key(options.secret),
+  })
+}
+
+export declare namespace seal {
+  type Parameters = Omit<z.input<typeof schema.continuation>, 'expiresAt'>
+
+  type Options = {
+    /** The `SECRET` variable. */
+    secret: string
+  }
+}
+
+/**
+ * Decrypts a sealed logout request, and returns its parameters, or `undefined` when it does not
+ * decrypt with `secret`, has another shape, or expired.
+ */
+export async function unseal(sealed: string, options: unseal.Options) {
+  const value = await symmetricDecrypt({
+    data: sealed,
+    key: await key(options.secret),
+  })
+    .then((data) => schema.continuation.safeParse(JSON.parse(data)))
+    .catch(() => undefined)
+  if (!value?.success) return undefined
+  if (value.data.expiresAt <= Date.now() / 1000) return undefined
+  return value.data
+}
+
+export declare namespace unseal {
+  type Options = {
+    /** The `SECRET` variable. */
+    secret: string
+  }
+}
+
+/**
+ * Revokes the refresh tokens that apps received through the session with `sessionId`. Better Auth
+ * revokes a session's tokens when it deletes the session, except `offline_access` refresh tokens,
+ * which every app requests, so logout ends the apps' access with this first.
+ */
+export async function revoke(db: Realm.Database, options: revoke.Options) {
+  await db
+    .update(Schema.oauthRefreshToken)
+    .set({ revoked: new Date() })
+    .where(
+      and(
+        eq(Schema.oauthRefreshToken.sessionId, options.sessionId),
+        isNull(Schema.oauthRefreshToken.revoked),
+      ),
+    )
+}
+
+export declare namespace revoke {
+  type Options = {
+    /** The ID of the session that ends. */
+    sessionId: string
+  }
+}
+
+/**
+ * Returns the app, session, and user that an ID token hint names, or `HintInvalidError`. The hint
+ * may be expired, as RP-Initiated Logout §2 allows, but Tempo ID must have signed it for the app.
+ */
+async function verify(
+  options: verify.Options,
+): Promise<verify.ReturnType | HintInvalidError> {
+  const { clientId, issuer, jwks } = options
+  const payload = await (async () => {
+    try {
+      const result = await compactVerify(
+        options.hint,
+        createLocalJWKSet(jwks),
+        { algorithms: ['RS256'] },
+      )
+      return JSON.parse(new TextDecoder().decode(result.payload)) as unknown
+    } catch {
+      // A hint that does not verify is the app's mistake, not a failure to log.
+      return undefined
+    }
+  })()
+  if (!payload || typeof payload !== 'object') return new HintInvalidError()
+
+  const claims = payload as Record<string, unknown>
+  const audiences = (() => {
+    if (typeof claims.aud === 'string') return [claims.aud]
+    if (Array.isArray(claims.aud))
+      return claims.aud.filter((entry) => typeof entry === 'string')
+    return []
+  })()
+  const app = clientId ?? (audiences.length === 1 ? audiences[0] : undefined)
+  if (
+    claims.iss !== issuer ||
+    !app ||
+    !audiences.includes(app) ||
+    typeof claims.sid !== 'string' ||
+    !claims.sid ||
+    typeof claims.sub !== 'string' ||
+    !claims.sub
+  )
+    return new HintInvalidError()
+
+  return { clientId: app, sessionId: claims.sid, userId: claims.sub }
+}
+
+declare namespace verify {
+  type Options = {
+    /** The client ID that the request names. Absent to read the app from the hint's `aud`. */
+    clientId?: string | undefined
+    /** The ID token that the app received at sign-in. */
+    hint: string
+    /** Tempo ID's issuer, every ID token's `iss`. */
+    issuer: string
+    /** Tempo ID's public signing keys. */
+    jwks: JSONWebKeySet
+  }
+
+  type ReturnType = {
+    /** The client ID of the app that the hint names. */
+    clientId: string
+    /** The ID of the session that the hint names. */
+    sessionId: string
+    /** The ID of the user that the hint names. */
+    userId: string
+  }
+}
+
+/** Returns the key that seals logout requests, derived from `secret` for this purpose alone. */
+async function key(secret: string) {
+  const encoder = new TextEncoder()
+  const material = await crypto.subtle.importKey(
+    'raw',
+    encoder.encode(secret),
+    'HKDF',
+    false,
+    ['deriveBits'],
+  )
+  const bits = await crypto.subtle.deriveBits(
+    {
+      hash: 'SHA-256',
+      info: encoder.encode('tempo-id:logout-continuation:v1'),
+      name: 'HKDF',
+      salt: new Uint8Array(),
+    },
+    material,
+    256,
+  )
+  return Hex.fromBytes(new Uint8Array(bits))
+}