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

package/src/internal/Migrations.ts

@@ -0,0 +1,86 @@
+/**
+ * Applies the package's migrations to a Postgres database. It keeps Void's ledger, `_void_migrations`
+ * by file name, so `void db migrate` in `src/app` and `tempo-id admin migrate` each skip what the
+ * other applied.
+ * @module
+ */
+import * as Fs from 'node:fs'
+import * as Path from 'node:path'
+import pg from 'pg'
+
+/**
+ * The advisory lock that serializes concurrent runs. Void's own runner takes none, so it and this
+ * command must not run at once.
+ */
+const lock = 7_105_201_133
+
+/** The package's migrations. The module is `src/internal/` or `dist/internal/`, two folders below the root. */
+export const directory = Path.join(
+  import.meta.dirname,
+  '..',
+  '..',
+  'src',
+  'app',
+  'db',
+  'migrations',
+)
+
+/**
+ * Applies each migration in `directory` that the ledger lacks, in file name order, each in its own
+ * transaction. Connects directly, since the lock needs a session that Hyperdrive does not keep.
+ * Returns the names it applied. A failed migration rolls back, and the error names its file.
+ */
+export async function apply(options: apply.Options) {
+  const client = new pg.Client({ connectionString: options.connectionString })
+  await client.connect()
+
+  try {
+    await client.query('select pg_advisory_lock($1)', [lock])
+    await client.query(
+      'create table if not exists _void_migrations (name text primary key, applied_at text not null)',
+    )
+    const ledger = await client.query<{ name: string }>(
+      'select name from _void_migrations',
+    )
+    const done = new Set(ledger.rows.map((row) => row.name))
+
+    const applied: string[] = []
+    const names = Fs.readdirSync(options.directory ?? directory)
+      .filter((name) => name.endsWith('.sql'))
+      .sort()
+    for (const name of names) {
+      if (done.has(name)) continue
+      const sql = Fs.readFileSync(
+        Path.join(options.directory ?? directory, name),
+        'utf8',
+      )
+      try {
+        await client.query('begin')
+        await client.query(sql)
+        await client.query(
+          'insert into _void_migrations (name, applied_at) values ($1, $2)',
+          [name, new Date().toISOString()],
+        )
+        await client.query('commit')
+      } catch (error) {
+        await client.query('rollback')
+        throw new Error(`Migration ${name} failed.`, { cause: error })
+      }
+      applied.push(name)
+    }
+
+    return { applied }
+  } finally {
+    // Ending the session releases the lock.
+    await client.end()
+  }
+}
+
+export declare namespace apply {
+  type Options = {
+    /** A direct Postgres connection string, never a Hyperdrive one. */
+    connectionString: string
+    /** The folder of `.sql` migrations. Defaults to the package's. */
+    directory?: string | undefined
+  }
+}

package/src/internal/OpenApi.ts

@@ -0,0 +1,300 @@
+/**
+ * Documents the API's Hono routes with `hono-openapi`. Routes stay plain Hono routes: each one adds
+ * `describeRoute` for its documentation and `validate` for each input. The document is generated
+ * from the mounted app.
+ * @module
+ */
+import type { Hono, MiddlewareHandler, ValidationTargets } from 'hono'
+import {
+  generateSpecs,
+  type HandlerUniqueProperty,
+  resolver,
+  type ResponsesWithResolver,
+  uniqueSymbol,
+  validator,
+} from 'hono-openapi'
+import type * as z from 'zod'
+import * as Auth from './Auth.js'
+import * as ErrorResponse from './ErrorResponse.js'
+import * as Validation from './Validation.js'
+
+export { describeRoute, resolver, validator } from 'hono-openapi'
+
+/**
+ * Conversion options for every schema. A hex quantity also accepts a bigint in process, which JSON
+ * Schema cannot express. That branch converts to `{}` and is dropped, which leaves the hex string
+ * that JSON requests send. Zod marks `.readonly()` schemas `readOnly`, which OpenAPI reads as
+ * server-set, so request fields drop it.
+ */
+const options = {
+  options: {
+    override: (context: {
+      jsonSchema: {
+        anyOf?: Record<string, unknown>[] | undefined
+        readOnly?: boolean | undefined
+      }
+    }) => {
+      const { jsonSchema } = context
+      delete jsonSchema.readOnly
+      const anyOf = jsonSchema.anyOf?.filter(
+        (branch) => Object.keys(branch).length > 0,
+      )
+      if (!anyOf || anyOf.length === jsonSchema.anyOf!.length) return
+      if (anyOf.length === 1) {
+        delete jsonSchema.anyOf
+        Object.assign(jsonSchema, anyOf[0])
+      } else jsonSchema.anyOf = anyOf
+    },
+    unrepresentable: 'any',
+  },
+} as const
+
+/**
+ * The Scalar bundle the reference loads: one file, pinned by version and by the SHA-384 digest of
+ * `dist/browser/standalone.js` in the npm tarball of `@scalar/api-reference@1.72.1`.
+ */
+const scalar = {
+  integrity:
+    'sha384-U11tb2XnKvmwt8RlTvnwUnYgrN+ur4Xyh9htLhjajWNR/Oyl5AX5DEz00qRmlrmK',
+  src: 'https://cdn.jsdelivr.net/npm/@scalar/api-reference@1.72.1/dist/browser/standalone.js',
+} as const
+
+/** The OpenAPI document's description of the API. */
+const info = {
+  description:
+    'Tempo ID signs users in to Tempo apps, authorizes apps for them, and signs key authorizations on their Tempo Accounts. Every refusal is an OAuth error response (RFC 6749 §5.2) whose `reason` determines its `error` and status.',
+  title: 'Tempo ID',
+  version: '0.0.0',
+} as const
+
+/**
+ * Returns the OpenAPI document for `app`, generated on the first call. The document is reused for
+ * the life of the isolate, since routes do not change while it runs. Every refusal joins its
+ * components, including those no route declares, such as `unknown_endpoint`.
+ */
+export function document(
+  app: Hono<any, any, any>,
+): ReturnType<typeof generateSpecs> {
+  const cached = documents.get(app)
+  if (cached) return cached
+
+  const generated = generate(app)
+  documents.set(app, generated)
+  // A failed generation is not cached, so the next request tries again.
+  generated.catch(() => documents.delete(app))
+  return generated
+}
+
+/**
+ * The API reference page, which renders `/openapi.json` with Scalar. Scalar mounts from the
+ * `api-reference` element, so the page has no inline script.
+ */
+export const reference = `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Tempo ID API</title>
+  </head>
+  <body>
+    <script id="api-reference" type="application/json" data-url="/openapi.json"></script>
+    <script src="${scalar.src}" integrity="${scalar.integrity}" crossorigin="anonymous"></script>
+  </body>
+</html>
+`
+
+/**
+ * The reference page's Content Security Policy. The page shares the session cookie's origin, so it
+ * runs only the pinned Scalar bundle, whose integrity the browser checks, and calls only this origin.
+ */
+export const referencePolicy = [
+  "default-src 'self'",
+  `script-src ${scalar.src}`,
+  // Scalar injects its styles at runtime, and loads its fonts from its own host.
+  "style-src 'self' 'unsafe-inline' https://fonts.scalar.com",
+  'font-src https://fonts.scalar.com',
+  "img-src 'self' data:",
+  "connect-src 'self'",
+  "object-src 'none'",
+  "base-uri 'none'",
+  "form-action 'none'",
+  "frame-ancestors 'none'",
+].join('; ')
+
+/**
+ * The OpenAPI responses for the refusals in `classes`, grouped by the status of each, plus
+ * `unexpected`, which any route can return.
+ */
+export function errors(classes: readonly ErrorResponse.Class[]) {
+  const byStatus = new Map<number, ErrorResponse.Reason[]>()
+  for (const reason of new Set(
+    [...classes, ErrorResponse.UnexpectedError].map((error) => error.reason),
+  ).values()) {
+    const status = ErrorResponse.reasons[reason].status
+    byStatus.set(status, [...(byStatus.get(status) ?? []), reason])
+  }
+  return Object.fromEntries(
+    [...byStatus].map(([status, group]) => [
+      status,
+      {
+        content: {
+          'application/json': {
+            schema: {
+              anyOf: group.map((reason) => ({
+                $ref: `#/components/schemas/ErrorResponse.${reason}`,
+              })),
+            },
+          },
+        },
+        description: group.map((reason) => `\`${reason}\``).join(', '),
+      },
+    ]),
+  )
+}
+
+/**
+ * Documents `target` with `schema` without validating or changing the request, for routes that
+ * fall through to a page or pass the issuer's requests through. A `form` documents a URL-encoded
+ * body.
+ */
+export function input<const target extends keyof ValidationTargets>(
+  target: target,
+  schema: z.ZodType,
+): MiddlewareHandler {
+  // The validator carries the documentation, which the generator reads from this symbol. OAuth
+  // form posts are URL-encoded, where the generator would otherwise document multipart.
+  const documented = validator(target, schema, undefined, {
+    ...options,
+    ...(target === 'form'
+      ? { media: 'application/x-www-form-urlencoded' }
+      : {}),
+  }) as {
+    [uniqueSymbol]?: HandlerUniqueProperty | undefined
+  }
+  return Object.assign<MiddlewareHandler, object>((_c, next) => next(), {
+    [uniqueSymbol]: documented[uniqueSymbol],
+  })
+}
+
+/**
+ * The OpenAPI responses of a JSON route: `success` at its status, and the refusals in `errors`,
+ * grouped by the status of each, plus `unexpected`.
+ */
+export function responses<const schema extends z.ZodType>(
+  options_: responses.Options<schema>,
+): ResponsesWithResolver {
+  const { errors: classes = [], success } = options_
+  return {
+    [success.status ?? 200]: {
+      content: {
+        'application/json': { schema: resolver(success.schema, options) },
+      },
+      description: success.description,
+    },
+    ...errors(classes),
+  }
+}
+
+export declare namespace responses {
+  type Options<schema extends z.ZodType> = {
+    /** The class of every refusal the route returns, thrown ones included. */
+    errors?: readonly ErrorResponse.Class[] | undefined
+    /** The success response. */
+    success: {
+      /** What the response means. */
+      description: string
+      /** The response body's schema. */
+      schema: schema
+      /** The success status. Defaults to 200. */
+      status?: 200 | 201 | undefined
+    }
+  }
+}
+
+/**
+ * Validates `target` against `schema`, documents it, and responds to a failure with an
+ * `invalid_field` error response. Hono refuses an unreadable JSON body as `malformed_body` before
+ * the schema runs.
+ */
+export function validate<
+  const target extends keyof ValidationTargets,
+  const schema extends z.ZodType,
+>(target: target, schema: schema) {
+  return validator(
+    target,
+    schema,
+    (result, c) => {
+      if (!result.success)
+        return ErrorResponse.json(
+          c,
+          new Validation.InvalidFieldError({ issues: result.error }),
+        )
+    },
+    options,
+  )
+}
+
+export namespace validate {
+  /** The refusals validation returns. Hono refuses an unreadable JSON body before the schema runs. */
+  export const errors = [
+    ErrorResponse.MalformedBodyError,
+    Validation.InvalidFieldError,
+  ] as const
+}
+
+/** Each app's document, generated once per isolate. */
+const documents = new WeakMap<
+  Hono<any, any, any>,
+  ReturnType<typeof generate>
+>()
+
+/** Generates the OpenAPI document for `app`. */
+async function generate(app: Hono<any, any, any>) {
+  // Each refusal's schema has an `id`, so converting it yields a reference plus the component.
+  const converted = await Promise.all(
+    (Object.keys(ErrorResponse.reasons) as ErrorResponse.Reason[]).map(
+      async (reason) =>
+        (
+          await resolver(
+            ErrorResponse.schema.of(reason),
+            options,
+          ).toOpenAPISchema()
+        ).components?.schemas,
+    ),
+  )
+  const schemas = Object.assign({}, ...converted)
+  return generateSpecs(app, {
+    defaultValidationErrorResponse: false,
+    // The document's own route ends in `.json`, which the generator would skip as a static file.
+    excludeStaticFile: false,
+    documentation: {
+      components: {
+        schemas,
+        securitySchemes: {
+          accessToken: {
+            bearerFormat: 'JWT',
+            description:
+              'An access token from `/oauth2/token`, as `Authorization: Bearer <token>`.',
+            scheme: 'bearer',
+            type: 'http',
+          },
+          clientBasic: {
+            description:
+              "An OAuth app's client ID and secret, as HTTP Basic `Authorization` (RFC 6749 §2.3.1).",
+            scheme: 'basic',
+            type: 'http',
+          },
+          sessionCookie: {
+            description:
+              "The Tempo ID session, which sign-in sets as an HTTP-only cookie on Tempo ID's origin.",
+            in: 'cookie',
+            name: Auth.sessionCookie,
+            type: 'apiKey',
+          },
+        },
+      },
+      info,
+      openapi: '3.1.0',
+    },
+  })
+}

package/src/internal/Owner.ts

@@ -0,0 +1,211 @@
+/**
+ * The keys that own Tempo Accounts, and the contract that each kind of owner key implements, such as
+ * Privy wallets and wallet.tempo passkeys. `TempoAccount` lists the user's owners through every kind,
+ * and creates a first account through the first kind that creates owner keys in a realm. A new kind
+ * implements {@link Kind}, and joins `TempoAccount.kinds`.
+ * @module
+ */
+import type { Hex } from 'ox'
+import type { LocalAccount } from 'viem'
+import type { Account, AccountConfig } from 'viem/tempo'
+import { sql } from 'drizzle-orm'
+import type * as Auth from './Auth.js'
+import type * as ErrorResponse from './ErrorResponse.js'
+import type * as Realm from './Realm.js'
+import type * as Timing from './Timing.js'
+
+/** The deployment variables that owner kinds read. */
+export type Env = {
+  /** The RS256 private key, as PKCS #8 PEM, whose public half each Privy app trusts. Absent, no Privy wallet signs. */
+  PRIVY_JWT_PRIVATE_KEY?: string | undefined
+  /** The `SECRET` variable, which encrypts the owner configurations of each realm. */
+  SECRET: string
+}
+
+/**
+ * One kind of owner key. `load` reads the kind's configuration for the realms that a request
+ * reaches, once, and returns the operations that list and create the user's owner keys.
+ */
+export type Kind<
+  type extends string = string,
+  errors extends readonly ErrorResponse.Class[] =
+    readonly ErrorResponse.Class[],
+> = {
+  /** The refusals that the kind's operations throw, such as an upstream service's failures. */
+  errors: errors
+  /** Reads the kind's configuration for `realms`, and returns the operations on the user's owner keys. */
+  load: (
+    c: Timing.measure.Context,
+    options: Kind.load.Options,
+  ) => Promise<Kind.Loaded<type>>
+  /** The owner type in the API, such as `privy` or `webAuthn`. */
+  type: type
+}
+
+export declare namespace Kind {
+  /** The operations on the user's owner keys of one kind, within the realms that `load` received. */
+  type Loaded<type extends string = string> = {
+    /**
+     * Returns a function that creates the user's first owner key in `realm`, or `undefined` when
+     * the kind creates none there, such as for a realm without the kind's configuration. Absent on
+     * a kind that only links owner keys created elsewhere. Such a kind lists from the database
+     * alone, since `TempoAccount.create` lists it again under the user's lock.
+     */
+    create?:
+      | ((
+          realm: Realm.Realm,
+        ) => ((c: Timing.measure.Context) => Promise<Owner<type>>) | undefined)
+      | undefined
+    /** Returns the user's owner keys of this kind, oldest first, and creates none. */
+    list: (
+      c: Timing.measure.Context,
+      options: Loaded.list.Options,
+    ) => Promise<readonly Owner<type>[]>
+  }
+
+  namespace Loaded {
+    namespace list {
+      type Options = {
+        /** The database or transaction to read. */
+        db: Realm.Database
+      }
+    }
+  }
+
+  namespace load {
+    type Options = {
+      /** The database. */
+      db: Realm.Database
+      /** The deployment variables. */
+      env: Env
+      /** The realms that the request reaches, in order. */
+      realms: readonly Realm.Realm[]
+      /** The user's ID. */
+      userId: string
+    }
+  }
+}
+
+/** A passkey that owns a Tempo Account, which signs only in a browser at its relying party. */
+export type Credential = {
+  /** The credential ID, base64url. */
+  id: string
+  /** The uncompressed P256 public key, hex. */
+  publicKey: Hex.Hex
+  /** The relying party ID of the passkey. */
+  rpId: string
+}
+
+/** A key that owns one of the user's Tempo Accounts, with the account's realm. */
+export type Owner<type extends string = string> = {
+  /** The Tempo Account that the key owns. It cannot sign. */
+  account: Account.ConfigurableAccount<AccountConfig.Config>
+  /** When the key was created, or linked when its creation time is unknown. */
+  createdAt: Date
+  /**
+   * The passkey that signs for the key in the browser. Absent for a key that signs on the server,
+   * such as a Privy wallet.
+   */
+  credential?: Credential | undefined
+  /** The account's realm. */
+  realm: Realm.Realm
+  /**
+   * Returns the key as a Viem account that signs on the server. `undefined` for a key that signs
+   * only in the browser, such as a passkey.
+   */
+  signer:
+    | ((
+        c: Timing.measure.Context,
+        options: signer.Options,
+      ) => Promise<LocalAccount>)
+    | undefined
+  /** The kind of the key, such as `privy` or `webAuthn`. */
+  type: type
+}
+
+export declare namespace signer {
+  type Options = {
+    /** The request's Better Auth instance, which signs tokens that an upstream signer verifies. */
+    auth: Auth.Instance
+  }
+}
+
+/**
+ * Instantiates an {@link Owner}.
+ *
+ * @example
+ * ```ts
+ * const owner = Owner.from({
+ *   account,
+ *   createdAt: key.createdAt,
+ *   credential: { id: key.id, publicKey: key.publicKey, rpId: key.rpId },
+ *   realm,
+ *   signer: undefined,
+ *   type: 'webAuthn',
+ * })
+ * ```
+ */
+export function from<const type extends string>(
+  value: Owner<type>,
+): Owner<type> {
+  return value
+}
+
+/**
+ * Instantiates a {@link Kind}.
+ *
+ * @example
+ * ```ts
+ * export const owner = Owner.kind({ errors: [], load, type: 'webAuthn' })
+ * ```
+ */
+export function kind<
+  const type extends string,
+  const errors extends readonly ErrorResponse.Class[],
+>(value: Kind<type, errors>): Kind<type, errors> {
+  return value
+}
+
+/**
+ * Merges lists of owners, each already oldest first, by creation time in seconds, the precision
+ * Privy records. A merge keeps the order of each list, so the first Privy wallet of a realm stays
+ * before its later wallets. An earlier list wins a tie.
+ */
+export function merge<const type extends string>(
+  lists: readonly (readonly Owner<type>[])[],
+): readonly Owner<type>[] {
+  const seconds = (date: Date) => Math.floor(date.getTime() / 1000)
+  const heads = lists.map(() => 0)
+  const merged: Owner<type>[] = []
+  while (true) {
+    const next = lists.reduce<number | undefined>((best, list, index) => {
+      const entry = list[heads[index]!]
+      if (!entry) return best
+      if (best === undefined) return index
+      const current = lists[best]![heads[best]!]!
+      return seconds(entry.createdAt) < seconds(current.createdAt)
+        ? index
+        : best
+    }, undefined)
+    if (next === undefined) return merged
+    merged.push(lists[next]![heads[next]!]!)
+    heads[next] = heads[next]! + 1
+  }
+}
+
+/**
+ * Takes the user's account lock until the transaction `tx` ends. `TempoAccount.create` and every
+ * kind that links owner keys take it, so a first account and a link for one user never interleave.
+ */
+export async function lock(tx: Realm.Database, options: lock.Options) {
+  await tx.execute(
+    sql`select pg_advisory_xact_lock(hashtextextended(${`tempo-account:${options.userId}`}, 0))`,
+  )
+}
+
+export declare namespace lock {
+  type Options = {
+    /** The user's ID. */
+    userId: string
+  }
+}