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

package/src/app/void.config.ts

@@ -0,0 +1,29 @@
+/**
+ * The Void configuration of the Tempo ID app: its database, bindings, and rate limits. A Worker that
+ * runs the built app through `App.create` declares the same bindings in its own Wrangler config.
+ * Void loads this file with Node, outside Vite, so it imports no other module.
+ * @module
+ */
+import { defineConfig } from 'void/config'
+import { limits } from '../internal/Limits.js'
+
+export default defineConfig({
+  cloudflare: {
+    // Void's dev inbox reaches the dev server through the assets binding, which a deployment binds
+    // under the same name.
+    assets: { binding: 'ASSETS' },
+    ratelimits: Object.entries(limits).map(([name, limit]) => ({
+      name,
+      namespace_id: limit.namespace,
+      simple: { limit: limit.limit, period: limit.period },
+    })),
+    // `/health` reports the version that served the request.
+    version_metadata: { binding: 'CF_VERSION_METADATA' },
+  },
+  database: 'pg',
+  // The sender in `vp dev`. `App.create` names each deployment's own.
+  email: { from: 'Tempo ID <noreply@id.tehq.dev>' },
+  // Void infers bindings only from its convention folders, and `lib/Auth.ts` reads the database and email.
+  inference: { bindings: { db: true, email: true } },
+  worker: { compatibility_date: '2026-02-24' },
+})

package/src/app/zyzz.config.ts

@@ -0,0 +1,274 @@
+/**
+ * Configures styling: zyzz's default tokens extended with Tempo ID's own, the Pilat and Geist Mono
+ * faces their stacks name, and document styles.
+ * @module
+ */
+import { defineConfig, extendVars } from 'zyzz'
+import { vars as defaults } from 'zyzz/default'
+import { fontFace, global, keyframes } from 'zyzz/web'
+
+/** A short sideways shake that marks a refused code. `animate.nudge` names it by its ID. */
+const nudge = keyframes(
+  {
+    '0%, 100%': { transform: 'translateX(0)' },
+    '20%': { transform: 'translateX(-6px)' },
+    '40%': { transform: 'translateX(5px)' },
+    '60%': { transform: 'translateX(-3px)' },
+    '80%': { transform: 'translateX(2px)' },
+  },
+  { id: 'tempo-id/nudge' },
+)
+
+// The `animate.nudge` token names the keyframes as text, so nothing else reads the constant.
+void nudge
+
+/**
+ * Tokens Tempo ID adds to the default set, or replaces in it. Add a token here rather than writing
+ * a custom value. The neutrals follow Link: controls and lists are gray fills on a near-white page,
+ * with few borders.
+ */
+const tokens = extendVars(
+  defaults,
+  {
+    animate: {
+      nudge:
+        'z-kid-tempo_2d_id_2f_nudge 400ms cubic-bezier(0.36, 0.07, 0.19, 0.97)',
+    },
+    // A code box, slightly taller than wide.
+    aspect: { code: '6 / 7' },
+    backgroundImage: {
+      // A white sheen from the top, which gives a solid button fill depth in both schemes.
+      sheen:
+        'linear-gradient(180deg, rgb(255 255 255 / 0.16), rgb(255 255 255 / 0))',
+    },
+    color: {
+      background: {
+        primary: { dark: '#0f0f0f', light: '#fdfdfd' },
+        surface: { dark: '#1a1a1a', light: '#ffffff' },
+      },
+      foreground: { dark: '#f5f5f5', light: '#1a1a1a' },
+      gray: {
+        // The fill of inputs, code boxes, and grouped lists.
+        100: { dark: '#1f1f1f', light: '#f5f5f5' },
+        // The fill of a hovered row or control.
+        200: { dark: '#2a2a2a', light: '#ededed' },
+        400: { dark: '#2e2e2e', light: '#e5e5e5' },
+        900: { dark: '#a3a3a3', light: '#6b6b6b' },
+        // The hover fill of a `foreground` button.
+        950: { dark: '#d6d6d6', light: '#333333' },
+      },
+      transparent: 'transparent',
+    },
+    fontFamily: {
+      sans: 'Pilat, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", "Noto Sans", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"',
+    },
+    letterSpacing: {
+      // A lone wallet's balance, which tracks tighter than its heading style.
+      balance: '-0.03em',
+      // The deposit screen's title.
+      title: '-0.02em',
+    },
+    radius: { full: '9999px' },
+    spacing: {
+      auto: 'auto',
+      // A negative inset that extends an icon control's hit area past the icon.
+      bleed: '-0.75rem',
+      // A smaller bleed, for an icon control beside text in a row.
+      bleedSmall: '-0.375rem',
+      full: '100%',
+      max: 'max-content',
+      // Negative insets that hang an icon control's glyph past the content edge, on phones and wider screens.
+      outdent: '-1rem',
+      outdentWide: '-3.5rem',
+      // A negative margin that overlaps stacked token icons.
+      overlap: '-0.375rem',
+      // The text of the flows canvas: at most 36rem, and within the viewport less the canvas's inset.
+      readable: 'min(36rem, calc(100vw - 2rem))',
+      screen: '100dvh',
+    },
+    // The default typography names Geist as text, not as a token, so each style in use names the
+    // Pilat stack again. Theme data takes only literals.
+    typography: {
+      button: {
+        14: {
+          fontFamily:
+            'Pilat, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", "Noto Sans", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"',
+        },
+        16: {
+          fontFamily:
+            'Pilat, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", "Noto Sans", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"',
+        },
+      },
+      copy: {
+        // Listing a size drops its nested styles, so `copy.13` restores the default mono style.
+        13: {
+          fontFamily:
+            'Pilat, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", "Noto Sans", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"',
+          mono: {
+            fontFamily:
+              '"Geist Mono", ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace',
+            fontSize: '13px',
+            fontWeight: 400,
+            letterSpacing: '0px',
+            lineHeight: '18px',
+          },
+        },
+        14: {
+          fontFamily:
+            'Pilat, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", "Noto Sans", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"',
+        },
+        16: {
+          fontFamily:
+            'Pilat, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", "Noto Sans", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"',
+          strong: {
+            fontFamily:
+              'Pilat, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", "Noto Sans", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"',
+          },
+        },
+      },
+      // Pilat's headings track at -0.015em, as in `@tempoxyz/ds`.
+      heading: {
+        16: {
+          fontFamily:
+            'Pilat, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", "Noto Sans", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"',
+          letterSpacing: '-0.24px',
+        },
+        20: {
+          fontFamily:
+            'Pilat, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", "Noto Sans", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"',
+          letterSpacing: '-0.3px',
+        },
+        24: {
+          fontFamily:
+            'Pilat, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", "Noto Sans", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"',
+          letterSpacing: '-0.36px',
+        },
+        32: {
+          fontFamily:
+            'Pilat, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", "Noto Sans", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"',
+          letterSpacing: '-0.48px',
+        },
+      },
+      label: {
+        12: {
+          fontFamily:
+            'Pilat, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", "Noto Sans", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"',
+          // The deposit address. Listing `label.12` again drops its nested styles, so this restores
+          // the default mono style.
+          mono: {
+            fontFamily:
+              '"Geist Mono", ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace',
+            fontSize: '12px',
+            fontWeight: 400,
+            letterSpacing: '0px',
+            lineHeight: '16px',
+          },
+        },
+        14: {
+          fontFamily:
+            'Pilat, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", "Noto Sans", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"',
+        },
+        16: {
+          fontFamily:
+            'Pilat, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", "Noto Sans", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"',
+        },
+        20: {
+          fontFamily:
+            'Pilat, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", "Noto Sans", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"',
+        },
+      },
+    },
+  },
+  { id: 'tempo-id/vars' },
+)
+
+/**
+ * Tokens for a third-party app's own interface, which only the flows canvas uses, beside Tempo ID's
+ * pages. A food-delivery brand's red, soft grays, and pill corners set the app's screens apart.
+ */
+const thirdParty = extendVars(
+  tokens,
+  {
+    color: {
+      background: {
+        primary: { dark: '#121212', light: '#ffffff' },
+        surface: { dark: '#1e1e1e', light: '#ffffff' },
+      },
+      blue: { 700: { dark: '#6b9bf2', light: '#4f86ec' } },
+      foreground: { dark: '#f5f5f5', light: '#191919' },
+      gray: {
+        100: { dark: '#2a2a2a', light: '#f5f5f5' },
+        400: { dark: '#3a3a3a', light: '#e7e7e7' },
+        900: { dark: '#b3b3b3', light: '#606060' },
+      },
+      red: { 700: { dark: '#ff4a2b', light: '#eb1700' } },
+    },
+    radius: { lg: '1.25rem', md: '1rem' },
+  },
+  { id: 'tempo-id/third-party' },
+)
+
+/**
+ * The style helpers and tokens that pages and components use. `vars({ set: 'thirdParty' })`
+ * applies the third-party tokens to a section.
+ */
+export const { appearance, script, style, variants, vars } = defineConfig({
+  defaultVars: 'default',
+  id: 'tempo-id',
+  vars: { default: tokens, thirdParty },
+})
+
+fontFace({
+  fontDisplay: 'swap',
+  fontFamily: 'Pilat',
+  fontStyle: 'normal',
+  fontWeight: 400,
+  src: 'url("@tempoxyz/ds/fonts/Pilat-Regular.woff2") format("woff2")',
+})
+
+fontFace({
+  fontDisplay: 'swap',
+  fontFamily: 'Pilat',
+  fontStyle: 'normal',
+  fontWeight: 500,
+  src: 'url("@tempoxyz/ds/fonts/Pilat-Book.woff2") format("woff2")',
+})
+
+fontFace({
+  fontDisplay: 'swap',
+  fontFamily: 'Pilat',
+  fontStyle: 'normal',
+  fontWeight: 600,
+  src: 'url("@tempoxyz/ds/fonts/Pilat-Demi.woff2") format("woff2")',
+})
+
+fontFace({
+  fontDisplay: 'swap',
+  fontFamily: 'Pilat',
+  fontStyle: 'normal',
+  fontWeight: 700,
+  src: 'url("@tempoxyz/ds/fonts/Pilat-Bold.woff2") format("woff2")',
+})
+
+fontFace({
+  fontDisplay: 'swap',
+  fontFamily: 'Geist Mono',
+  fontStyle: 'normal',
+  fontWeight: '100 900',
+  src: 'url("@fontsource-variable/geist-mono/files/geist-mono-latin-wght-normal.woff2") format("woff2")',
+})
+
+global({
+  'html, body': {
+    backgroundColor: vars.color.background.primary,
+    color: vars.color.foreground,
+  },
+  body: {
+    fontFamily: vars.fontFamily.sans,
+    MozOsxFontSmoothing: 'grayscale',
+    WebkitFontSmoothing: 'antialiased',
+  },
+  'button, input': { font: 'inherit' },
+  'code, pre': { fontFamily: vars.fontFamily.mono },
+  html: { colorScheme: 'light dark' },
+})

package/src/cli/Admin.ts

@@ -0,0 +1,73 @@
+/**
+ * What the `tempo-id admin` commands share: the options and variables that name the database, and
+ * the loaders of the app and realm commands' modules. incur imports every command when the CLI
+ * starts, so this module imports only incur, and each module loads only when its commands run.
+ * @module
+ */
+import { z } from 'incur'
+
+/** The variables that name the database. */
+export const env = z.object({
+  DATABASE_URL: z
+    .string()
+    .optional()
+    .describe(
+      'Postgres connection string. Used when --database-url is omitted.',
+    ),
+})
+
+/** The error for a command without a database URL. */
+export const missingDatabaseUrl = {
+  code: 'missing_database_url',
+  message:
+    'Missing database URL. Set --database-url or DATABASE_URL to a direct Postgres connection string.',
+} as const
+
+/** The error for an app, realm, or signing key command without one of its optional peers. */
+export const missingPeers = {
+  code: 'missing_peer',
+  message:
+    'Missing peer dependencies. Install better-auth, @better-auth/core, @better-auth/oauth-provider, drizzle-orm, and zod to run the admin apps, realms, and rotate-key commands.',
+} as const
+
+/** The options that name the database. */
+export const options = z.object({
+  databaseUrl: z
+    .string()
+    .optional()
+    .describe('Postgres connection string. Overrides DATABASE_URL.'),
+})
+
+/**
+ * Loads the module that the app and signing key commands share, or returns `undefined` when one of
+ * its optional peers is not installed.
+ */
+export async function loadApps() {
+  // A dynamic import, since the module needs optional peers that the other commands do not.
+  return await optional(import('./Apps.js'))
+}
+
+/**
+ * Loads the module that the realm commands share, or returns `undefined` when one of its optional
+ * peers is not installed.
+ */
+export async function loadRealms() {
+  // A dynamic import, since the module needs optional peers that the other commands do not.
+  return await optional(import('./Realms.js'))
+}
+
+/** Returns the module that `promise` loads, or `undefined` when one of its packages is missing. */
+export async function optional<module>(promise: Promise<module>) {
+  try {
+    return await promise
+  } catch (error) {
+    if (
+      error instanceof Error &&
+      'code' in error &&
+      error.code === 'ERR_MODULE_NOT_FOUND' &&
+      error.message.startsWith('Cannot find package')
+    )
+      return undefined
+    throw error
+  }
+}

package/src/cli/Apps.ts

@@ -0,0 +1,29 @@
+/**
+ * What the `tempo-id admin apps` and `admin rotate-key` commands share: `Apps`, `SigningKey`, a
+ * Drizzle connection to the database, and the codes of the refusals that both throw. It needs the
+ * `better-auth`, `@better-auth/core`, `@better-auth/oauth-provider`, `drizzle-orm`, and `zod` peers,
+ * so the commands load it with `Admin.loadApps`.
+ * @module
+ */
+import * as Apps from '../internal/Apps.js'
+import * as SigningKey from '../internal/SigningKey.js'
+
+export * as Apps from '../internal/Apps.js'
+export * as SigningKey from '../internal/SigningKey.js'
+export { connect } from './Realms.js'
+
+/** Returns the error code and message for a refusal from `Apps` or `SigningKey`, or `undefined` for another error. */
+export function error(error: unknown) {
+  const code = (() => {
+    if (error instanceof Apps.ExistsError) return 'app_exists'
+    if (error instanceof Apps.InvalidError) return 'invalid_app'
+    if (error instanceof Apps.NotFoundError) return 'unknown_app'
+    if (error instanceof Apps.PublicError) return 'public_app'
+    if (error instanceof SigningKey.FullError) return 'too_many_signing_keys'
+    if (error instanceof SigningKey.MissingError) return 'missing_signing_key'
+    if (error instanceof SigningKey.SecretError) return 'invalid_secret'
+    return undefined
+  })()
+  if (!code || !(error instanceof Error)) return undefined
+  return { code, message: error.message }
+}

package/src/cli/Cli.ts

@@ -0,0 +1,42 @@
+/**
+ * The `tempo-id` CLI. Each command is a file in `commands/`, which incur routes by its path, such as
+ * `commands/admin/migrate.ts` for `tempo-id admin migrate`. `init` and `admin` work offline. `login`,
+ * `logout`, `whoami`, and the `v1` group reach Tempo ID over HTTP.
+ * @module
+ */
+import * as Fs from 'node:fs'
+import * as Path from 'node:path'
+import { Cli as incur_Cli } from 'incur'
+import type * as V1 from './V1.js'
+
+/** The package's version, from its `package.json` one folder above `src/` or `dist/`. */
+const version = (
+  JSON.parse(
+    Fs.readFileSync(
+      Path.join(import.meta.dirname, '..', '..', 'package.json'),
+      'utf8',
+    ),
+  ) as { version: string }
+).version
+
+/**
+ * Returns the `tempo-id` CLI, with the commands in `commands/`, and with `v1`, the group that
+ * `V1.load` returns.
+ */
+export function create(options: create.Options = {}) {
+  const cli = incur_Cli
+    .create('tempo-id', {
+      description: 'Create and operate Tempo ID projects.',
+      version,
+    })
+    .fs(new URL('./commands/', import.meta.url))
+  if (!options.v1) return cli
+  return cli.command('v1', options.v1)
+}
+
+export declare namespace create {
+  type Options = {
+    /** The `v1` group, from the deployment's OpenAPI document. Absent, the CLI has no `v1` group. */
+    v1?: Awaited<ReturnType<typeof V1.load>> | undefined
+  }
+}

package/src/cli/Project.ts

@@ -0,0 +1,117 @@
+/**
+ * Writes a Tempo ID Worker project: a Worker that runs `App.create`, and the Wrangler config that
+ * declares the bindings the app reads, as `apps/id` holds them.
+ * @module
+ */
+import * as Fs from 'node:fs'
+import * as Path from 'node:path'
+import * as Limits from '../internal/Limits.js'
+
+/** The package's own `package.json`, two folders above `src/cli/` or `dist/cli/`. */
+const manifest = JSON.parse(
+  Fs.readFileSync(
+    Path.join(import.meta.dirname, '..', '..', 'package.json'),
+    'utf8',
+  ),
+) as { version: string }
+
+/** The Wrangler version a project deploys with. */
+const wrangler = '4.151.0'
+
+/**
+ * Writes the project's files into `options.root`, skipping any that exist. Returns the paths it
+ * wrote.
+ */
+export function init(options: init.Options) {
+  const { from, root, url } = options
+  const name = options.name ?? Path.basename(Path.resolve(root))
+
+  const files = {
+    '.gitignore': ['.dev.vars', '.wrangler', 'node_modules', ''].join('\n'),
+    'package.json': `${JSON.stringify(
+      {
+        name,
+        private: true,
+        type: 'module',
+        scripts: { deploy: 'wrangler deploy', dev: 'wrangler dev' },
+        dependencies: { '@tempoxyz/id': `^${manifest.version}` },
+        devDependencies: { wrangler },
+      },
+      null,
+      2,
+    )}\n`,
+    'worker.ts': [
+      '/** Runs Tempo ID on this host. @module */',
+      "import { App } from '@tempoxyz/id/worker'",
+      '',
+      'export default App.create()',
+      '',
+    ].join('\n'),
+    'wrangler.jsonc': [
+      '{',
+      '  "$schema": "node_modules/wrangler/config-schema.json",',
+      `  "name": ${JSON.stringify(name)},`,
+      '  "main": "worker.ts",',
+      '  "compatibility_date": "2026-02-24",',
+      '  "compatibility_flags": ["nodejs_compat"],',
+      "  // The app's client scripts and styles, from the package.",
+      '  "assets": {',
+      '    "binding": "ASSETS",',
+      '    "directory": "node_modules/@tempoxyz/id/dist/app/client",',
+      '    "run_worker_first": ["/**"],',
+      '  },',
+      '  // Postgres. Create a Hyperdrive configuration with `wrangler hyperdrive create`, and set its ID.',
+      '  "hyperdrive": [',
+      '    {',
+      '      "binding": "HYPERDRIVE",',
+      '      "id": "<hyperdrive-id>",',
+      '      "localConnectionString": "postgresql://localhost:5432/tempo_id",',
+      '    },',
+      '  ],',
+      '  // Each limit counts per Cloudflare location over its period, in seconds.',
+      '  "ratelimits": [',
+      ...Object.entries(Limits.limits).map(
+        ([binding, limit]) =>
+          `    { "name": "${binding}", "namespace_id": "${limit.namespace}", "simple": { "limit": ${limit.limit}, "period": ${limit.period} } },`,
+      ),
+      '  ],',
+      '  // Set it with `wrangler secret put SECRET`, from `openssl rand -base64 32`.',
+      '  "secrets": { "required": ["SECRET"] },',
+      "  // Sign-in codes. The sender's domain needs Cloudflare Email Sending on the account.",
+      '  "send_email": [{ "name": "SEND_EMAIL" }],',
+      '  // The cleanup of expired rows.',
+      '  "triggers": { "crons": ["0 * * * *"] },',
+      '  "vars": {',
+      `    "EMAIL_FROM": ${JSON.stringify(from)},`,
+      `    "URL": ${JSON.stringify(url)},`,
+      '  },',
+      '  "version_metadata": { "binding": "CF_VERSION_METADATA" },',
+      '}',
+      '',
+    ].join('\n'),
+  }
+
+  const written: string[] = []
+  for (const [path, content] of Object.entries(files)) {
+    const target = Path.join(root, path)
+    if (Fs.existsSync(target)) continue
+    Fs.mkdirSync(Path.dirname(target), { recursive: true })
+    Fs.writeFileSync(target, content)
+    written.push(path)
+  }
+
+  return { paths: written }
+}
+
+export declare namespace init {
+  type Options = {
+    /** The sender of every email, such as `Tempo ID <noreply@id.example.com>`. */
+    from: string
+    /** The project's package name and Worker name. Defaults to the folder's name. */
+    name?: string | undefined
+    /** The project's folder, which need not exist. */
+    root: string
+    /** Tempo ID's origin, such as `https://id.example.com`, and every token's `iss`. */
+    url: string
+  }
+}

package/src/cli/Realms.ts

@@ -0,0 +1,50 @@
+/**
+ * What the `tempo-id admin realms` commands share: `Realm`, a Drizzle connection to the database,
+ * and the codes of the refusals that `Realm` throws. It needs the `better-auth`, `drizzle-orm`, and
+ * `zod` peers, so the commands load it with `Admin.loadRealms`.
+ * @module
+ */
+import { drizzle } from 'drizzle-orm/node-postgres'
+import pg from 'pg'
+import * as Schema from '../app/db/schema.js'
+import * as Realm from '../internal/Realm.js'
+
+export * as Realm from '../internal/Realm.js'
+
+/**
+ * Connects to the database at `connectionString` directly, never through Hyperdrive. Call `end` once
+ * the command is done with it.
+ */
+export function connect(options: connect.Options) {
+  const pool = new pg.Pool({
+    connectionString: options.connectionString,
+    max: 1,
+  })
+  return {
+    db: drizzle({ client: pool, schema: Schema }),
+    end: () => pool.end(),
+  }
+}
+
+export declare namespace connect {
+  type Options = {
+    /** A direct Postgres connection string. */
+    connectionString: string
+  }
+}
+
+/** Returns the error code and message for a refusal from `Realm`, or `undefined` for another error. */
+export function error(error: unknown) {
+  const code = (() => {
+    if (error instanceof Realm.InUseError) return 'realm_in_use'
+    if (error instanceof Realm.InvalidError) return 'invalid_realm'
+    if (error instanceof Realm.NotFoundAppError) return 'unknown_app'
+    if (error instanceof Realm.NotFoundError) return 'unknown_realm'
+    if (error instanceof Realm.TakenError) return 'realm_exists'
+    if (error instanceof Realm.TakenPasskeysError) return 'relying_party_taken'
+    if (error instanceof Realm.TakenPrivyAppError) return 'privy_app_taken'
+    return undefined
+  })()
+  if (!code || !(error instanceof Error)) return undefined
+  return { code, message: error.message }
+}