@tempoxyz/id 0.0.0-stage → 0.0.1

package/src/internal/Limits.ts

@@ -0,0 +1,40 @@
+/**
+ * The Workers rate limits that the app reads, by binding name. The module imports nothing, since
+ * Void loads `void.config.ts` in Node.
+ * @module
+ */
+
+/**
+ * Each rate limit, counted per Cloudflare location over `period` seconds. A binding cannot report
+ * its own configuration, so the app reads it here.
+ */
+export const limits = {
+  /** Account reads per signed-in user. Each can read every Privy app of the app's realms. */
+  ACCOUNT_LIMIT: { limit: 60, namespace: '1007', period: 60 },
+  /** Third-party authorization requests per IP address. Each can fetch a metadata document. */
+  APP_DISCOVERY_LIMIT: { limit: 30, namespace: '1009', 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 after the secret matches, so a caller
+   * cannot spend another app's quota.
+   */
+  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 an older Wrangler config can lack. A missing binding skips such a limit, and fails
+ * the request for any other.
+ */
+export const optional: readonly Limit[] = ['TOKEN_APP_LIMIT']

package/src/internal/Log.ts

@@ -0,0 +1,166 @@
+/**
+ * Structured logs for the Worker, one object per entry, which Workers Logs indexes by field. An
+ * entry holds a fixed message, chosen fields, the request's ID, method, and route, and an error's
+ * safe properties. Headers, bodies, query strings, and path parameters never reach a log.
+ * @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 a client ID. Never secrets, tokens, or personal data. */
+  fields?: Record<string, boolean | number | string | undefined> | undefined
+  /** A fixed sentence, which occurrences group by. It never holds values. */
+  message: string
+}
+
+/** Returns whether the module runs on the Vite dev server. */
+export function dev() {
+  return (import.meta as Meta).env?.DEV === true
+}
+
+/** Logs an unexpected failure. Outside a request, such as in a cron, it takes no context. */
+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. */
+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. Without one, returns `/*`, since the
+ * path can carry a code.
+ */
+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 did not fail the 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 & {
+  /** 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' }),
+    // Viem's `RpcRequestError` holds the node's JSON-RPC error message in `details`, such as the
+    // reason that a relay refuses a transaction. Its `message` adds the URL, which can hold a
+    // provider's key, and the request body, so only `details` is kept.
+    details:
+      error.name === 'RpcRequestError'
+        ? read(error, { key: 'details' })
+        : undefined,
+    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 an object, or as one condensed line on the Vite dev server. */
+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,81 @@
+/**
+ * Prints `Log` entries as condensed lines on the Vite dev server. The production build logs objects.
+ * @module
+ */
+/* istanbul ignore file -- Only the dev server formats lines. The suites run the production build. */
+
+/** 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`. */
+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 so far, such as `error.cause.`. */
+    prefix: string
+  }
+}
+
+/** Formats a log entry as one line in the style of Rust's `tracing`, then indented stack frames. */
+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 value with 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,356 @@
+/**
+ * OpenID Connect RP-Initiated Logout 1.0: the checks on an app's ID token hint and post-logout
+ * redirect URI, and the end of the session with the apps' tokens.
+ * @module
+ */
+import { symmetricDecrypt, symmetricEncrypt } from 'better-auth/crypto'
+import { and, eq, inArray, isNull, sql } 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'
+
+/** Seconds that a sealed logout request stays valid. */
+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 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's hint, 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 browser goes after logout. Absent for no redirect. */
+    postLogoutRedirectUri?: string | undefined
+    /** Returned to the app as `state`. */
+    state?: string | undefined
+  }
+
+  type ReturnType = {
+    /** The post-logout redirect URI with `state`, if the request names one. */
+    redirect: string | undefined
+    /** The session that the hint names. */
+    sessionId: string
+  }
+}
+
+/**
+ * Encrypts the parameters of a logout request with a key from `secret`, for the URL that a form
+ * POST continues at. It expires after a minute.
+ */
+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
+  }
+}
+
+/** Returns a sealed logout request's parameters, or `undefined` if it is invalid 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
+  }
+}
+
+/**
+ * Deletes the session with `token`, and revokes the tokens that apps received through it, in one
+ * statement. Better Auth's sign-out keeps the apps' refresh tokens. Returns the ended session's ID,
+ * or `undefined` when no session matches.
+ */
+export async function end(db: Realm.Database, options: end.Options) {
+  const revoked = new Date()
+  // The statement's parts read one snapshot, so the tokens still name the session that it deletes.
+  // A token that a concurrent refresh inserts misses that snapshot. The `tempo_id.logout` setting
+  // lets migration 0014's trigger revoke it when the foreign key clears its `session_id`. The
+  // setting is local to the transaction, which is this statement.
+  const ended = db.$with('ended').as(
+    db
+      .delete(Schema.session)
+      .where(
+        and(
+          eq(Schema.session.token, options.token),
+          options.sessionId === undefined
+            ? undefined
+            : eq(Schema.session.id, options.sessionId),
+          sql`set_config('tempo_id.logout', 'on', true) = 'on'`,
+        ),
+      )
+      .returning({ id: Schema.session.id }),
+  )
+  const accessTokens = db.$with('access_tokens').as(
+    db
+      .update(Schema.oauthAccessToken)
+      .set({ revoked })
+      .where(
+        and(
+          inArray(
+            Schema.oauthAccessToken.sessionId,
+            db.select({ id: ended.id }).from(ended),
+          ),
+          isNull(Schema.oauthAccessToken.revoked),
+        ),
+      )
+      .returning({ id: Schema.oauthAccessToken.id }),
+  )
+  const refreshTokens = db.$with('refresh_tokens').as(
+    db
+      .update(Schema.oauthRefreshToken)
+      .set({ revoked })
+      .where(
+        and(
+          inArray(
+            Schema.oauthRefreshToken.sessionId,
+            db.select({ id: ended.id }).from(ended),
+          ),
+          isNull(Schema.oauthRefreshToken.revoked),
+        ),
+      )
+      .returning({ id: Schema.oauthRefreshToken.id }),
+  )
+
+  const [row] = await db
+    .with(ended, accessTokens, refreshTokens)
+    .select({ id: ended.id })
+    .from(ended)
+  return row?.id
+}
+
+export declare namespace end {
+  type Options = {
+    /** The session's required ID. Absent for any session with the token. */
+    sessionId?: string | undefined
+    /** The session's token, from the signed session cookie. */
+    token: string
+  }
+}
+
+/**
+ * Returns the app, session, and user that an ID token hint names, or `HintInvalidError`. An expired
+ * hint passes, as RP-Initiated Logout §2 allows.
+ */
+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, the hint's `aud` names the app. */
+    clientId?: string | undefined
+    /** The ID token that the app received at sign-in. */
+    hint: string
+    /** Every ID token's `iss`. */
+    issuer: string
+    /** Tempo ID's public signing keys. */
+    jwks: JSONWebKeySet
+  }
+
+  type ReturnType = {
+    /** The app that the hint names. */
+    clientId: string
+    /** The session that the hint names. */
+    sessionId: string
+    /** 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))
+}