@tempoxyz/id 0.0.0-stage → 0.0.1

package/src/app/db/migrations/meta/_journal.json

@@ -0,0 +1,146 @@
+{
+  "version": "7",
+  "dialect": "postgresql",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "7",
+      "when": 1792103783439,
+      "tag": "0000_better_auth",
+      "breakpoints": true
+    },
+    {
+      "idx": 1,
+      "version": "7",
+      "when": 1792104841313,
+      "tag": "0001_oauth_provider",
+      "breakpoints": true
+    },
+    {
+      "idx": 2,
+      "version": "7",
+      "when": 1792105790542,
+      "tag": "0002_device_code",
+      "breakpoints": true
+    },
+    {
+      "idx": 3,
+      "version": "7",
+      "when": 1792120897368,
+      "tag": "0003_realms",
+      "breakpoints": true
+    },
+    {
+      "idx": 4,
+      "version": "7",
+      "when": 1792120898985,
+      "tag": "0004_default_realm",
+      "breakpoints": true
+    },
+    {
+      "idx": 5,
+      "version": "7",
+      "when": 1792122703707,
+      "tag": "0005_passkeys",
+      "breakpoints": true
+    },
+    {
+      "idx": 6,
+      "version": "7",
+      "when": 1792191457718,
+      "tag": "0006_first_accounts",
+      "breakpoints": true
+    },
+    {
+      "idx": 7,
+      "version": "7",
+      "when": 1792215096143,
+      "tag": "0007_pending_keys",
+      "breakpoints": true
+    },
+    {
+      "idx": 8,
+      "version": "7",
+      "when": 1792228621255,
+      "tag": "0008_secp256k1_owners",
+      "breakpoints": true
+    },
+    {
+      "idx": 9,
+      "version": "7",
+      "when": 1792272924631,
+      "tag": "0009_device_requests",
+      "breakpoints": true
+    },
+    {
+      "idx": 10,
+      "version": "7",
+      "when": 1792277670228,
+      "tag": "0010_device_keys",
+      "breakpoints": true
+    },
+    {
+      "idx": 11,
+      "version": "7",
+      "when": 1792405636242,
+      "tag": "0011_registered_passkeys",
+      "breakpoints": true
+    },
+    {
+      "idx": 12,
+      "version": "7",
+      "when": 1792439149087,
+      "tag": "0012_passkey_accounts",
+      "breakpoints": true
+    },
+    {
+      "idx": 13,
+      "version": "7",
+      "when": 1792444125564,
+      "tag": "0013_first_party_apps",
+      "breakpoints": true
+    },
+    {
+      "idx": 14,
+      "version": "7",
+      "when": 1792456783693,
+      "tag": "0014_logout_revokes_tokens",
+      "breakpoints": true
+    },
+    {
+      "idx": 15,
+      "version": "7",
+      "when": 1792462099241,
+      "tag": "0015_expiry_indexes",
+      "breakpoints": true
+    },
+    {
+      "idx": 16,
+      "version": "7",
+      "when": 1792664075869,
+      "tag": "0016_configurable_accounts",
+      "breakpoints": true
+    },
+    {
+      "idx": 17,
+      "version": "7",
+      "when": 1792680110964,
+      "tag": "0017_account_config_keys",
+      "breakpoints": true
+    },
+    {
+      "idx": 18,
+      "version": "7",
+      "when": 1792796693715,
+      "tag": "0018_better_auth_1_8",
+      "breakpoints": true
+    },
+    {
+      "idx": 19,
+      "version": "7",
+      "when": 1792993184768,
+      "tag": "0019_drop_provider_account_index",
+      "breakpoints": true
+    }
+  ]
+}

package/src/app/db/schema.ts

@@ -0,0 +1,241 @@
+/** Tempo ID's Drizzle tables: the Better Auth tables, then Tempo ID's own. @module */
+import { sql } from 'drizzle-orm'
+import {
+  check,
+  index,
+  integer,
+  jsonb,
+  primaryKey,
+  text,
+  timestamp,
+  unique,
+} from 'drizzle-orm/pg-core'
+import { oauthClient, user } from './auth.js'
+import * as Table from './table.js'
+
+export * from './auth.js'
+
+/**
+ * The configuration of each configurable account (TIP-1107) on one chain. The chain stores only a
+ * commitment, so Tempo ID keeps the configuration, and checks it against the chain before a change.
+ */
+export const accountConfigs = Table.define(
+  'account_configs',
+  {
+    // The account's address, in lowercase.
+    address: text('address').notNull(),
+    chainId: integer('chain_id').notNull(),
+    createdAt: timestamp('created_at').defaultNow().notNull(),
+    // The address of the key whose account this is, in lowercase: the account's own for an upgrade,
+    // or, for an account that is configurable from its creation, the key that created it.
+    key: text('key').notNull(),
+    // The owners, in the configuration's canonical order, each `{ address, type, weight }`. `type`
+    // is the owner kind, such as `privy` or `webAuthn`, and `address` is in lowercase.
+    owners: jsonb('owners').notNull(),
+    // The 32-byte salt, hex.
+    salt: text('salt').notNull(),
+    threshold: integer('threshold').notNull(),
+    updatedAt: timestamp('updated_at').defaultNow().notNull(),
+    userId: text('user_id')
+      .notNull()
+      .references(() => user.id, { onDelete: 'cascade' }),
+    // The configuration version, a decimal integer. A creation installs version 0, and an upgrade
+    // version 1.
+    version: text('version').notNull(),
+  },
+  (table) => [
+    primaryKey({ columns: [table.chainId, table.address] }),
+    index('account_configs_user_id_idx').on(table.userId),
+  ],
+)
+
+/**
+ * Each OAuth app's realms, in order. The first holds a user's first account. Without rows, an app
+ * uses `default`.
+ */
+export const appRealms = Table.define(
+  'app_realms',
+  {
+    clientId: text('client_id')
+      .notNull()
+      .references(() => oauthClient.clientId, { onDelete: 'cascade' }),
+    position: integer('position').notNull(),
+    // A realm that an app names cannot be deleted.
+    realmId: text('realm_id')
+      .notNull()
+      .references(() => realms.id),
+  },
+  (table) => [
+    check('app_realms_position_check', sql`${table.position} >= 0`),
+    primaryKey({ columns: [table.clientId, table.position] }),
+    unique('app_realms_client_id_realm_id_unique').on(
+      table.clientId,
+      table.realmId,
+    ),
+  ],
+)
+
+/**
+ * Each device request's CLI details and key, for the device page. It shares its `device_code` row's
+ * ID, without a foreign key, so it outlives the redemption.
+ */
+export const deviceRequests = Table.define(
+  'device_requests',
+  {
+    // The Tempo Account that the signed key acts for. Null until approval signs the key.
+    account: text('account'),
+    // The message whose hash is the key's witness. Null for a request without one.
+    challenge: text('challenge'),
+    createdAt: timestamp('created_at').defaultNow().notNull(),
+    // The name that the CLI reported, such as its hostname. Null for a code from `POST /device/code`.
+    device: text('device'),
+    expiresAt: timestamp('expires_at').notNull(),
+    // The ID of the `device_code` row.
+    id: text('id').primaryKey(),
+    // The CLI's IP address. Null when it is unknown.
+    ip: text('ip'),
+    // The key that the CLI requested, as JSON with every default filled. Null for a request without one.
+    key: jsonb('key'),
+    // The signed key authorization, in the node's RPC format. Null until approval signs the key, and
+    // again once the first redemption of the device code takes it.
+    keyAuthorization: jsonb('key_authorization'),
+    // The CLI's city and country, from its IP address. Null when they are unknown.
+    location: text('location'),
+  },
+  (table) => [index('device_requests_expires_at_idx').on(table.expiresAt)],
+)
+
+/**
+ * The realm of each user's first account, claimed before the owner key exists, so a later request
+ * completes that account.
+ */
+export const firstAccounts = Table.define(
+  'first_accounts',
+  {
+    createdAt: timestamp('created_at').defaultNow().notNull(),
+    realmId: text('realm_id')
+      .notNull()
+      .references(() => realms.id, { onDelete: 'cascade' }),
+    userId: text('user_id')
+      .notNull()
+      .references(() => user.id, { onDelete: 'cascade' }),
+  },
+  (table) => [primaryKey({ columns: [table.userId, table.realmId] })],
+)
+
+/** The passkeys that users sign in with: one WebAuthn credential of one relying party each. */
+export const keys = Table.define(
+  'keys',
+  {
+    // The address that the public key derives, in lowercase, for a passkey that owns the Tempo
+    // Account at it. `null` marks a sign-in passkey, which owns no account, so never derive it.
+    address: text('address').unique(),
+    createdAt: timestamp('created_at').defaultNow().notNull(),
+    // The WebAuthn credential ID, base64url, as the browser returns it.
+    id: text('id').primaryKey(),
+    // The uncompressed P256 public key, hex.
+    publicKey: text('public_key').notNull(),
+    rpId: text('rp_id').notNull(),
+    // Where the passkey comes from: `tempo-id` for one that Tempo ID stored, such as a registration,
+    // or `tempo-wallet` for one that wallet.tempo created and that linked here. Rows that the
+    // deployment before this one wrote keep `registered` and `wallet` until a later migration
+    // renames them, so a migration never breaks the Worker that is live while it runs.
+    source: text('source').notNull(),
+    type: text('type').notNull(),
+    userId: text('user_id')
+      .notNull()
+      .references(() => user.id, { onDelete: 'cascade' }),
+  },
+  (table) => [
+    check(
+      'keys_source_check',
+      sql`${table.source} in ('registered', 'tempo-id', 'tempo-wallet', 'wallet')`,
+    ),
+    check('keys_type_check', sql`${table.type} = 'passkey'`),
+    index('keys_user_id_idx').on(table.userId),
+  ],
+)
+
+/**
+ * The key authorizations that approval signed, by client ID and PKCE challenge, until the code's
+ * first redemption returns the key.
+ */
+export const pendingKeys = Table.define(
+  'pending_keys',
+  {
+    // The Tempo Account that the key acts for.
+    account: text('account').notNull(),
+    clientId: text('client_id')
+      .notNull()
+      .references(() => oauthClient.clientId, { onDelete: 'cascade' }),
+    codeChallenge: text('code_challenge').notNull(),
+    createdAt: timestamp('created_at').defaultNow().notNull(),
+    expiresAt: timestamp('expires_at').notNull(),
+    // The signed key authorization, in the node's RPC format.
+    keyAuthorization: jsonb('key_authorization').notNull(),
+    userId: text('user_id')
+      .notNull()
+      .references(() => user.id, { onDelete: 'cascade' }),
+  },
+  (table) => [
+    index('pending_keys_expires_at_idx').on(table.expiresAt),
+    primaryKey({ columns: [table.clientId, table.codeChallenge] }),
+  ],
+)
+
+/** Each passkey realm's relying party. A passkey belongs to one relying party, so it is unique. */
+export const realmPasskeys = Table.define('realm_passkeys', {
+  createdAt: timestamp('created_at').defaultNow().notNull(),
+  realmId: text('realm_id')
+    .primaryKey()
+    .references(() => realms.id, { onDelete: 'cascade' }),
+  rpId: text('rp_id').notNull().unique(),
+})
+
+/** Each Privy realm's Privy app. `app_secret` is encrypted with `SECRET`. */
+export const realmPrivy = Table.define('realm_privy', {
+  appId: text('app_id').notNull().unique(),
+  appSecret: text('app_secret').notNull(),
+  createdAt: timestamp('created_at').defaultNow().notNull(),
+  realmId: text('realm_id')
+    .primaryKey()
+    .references(() => realms.id, { onDelete: 'cascade' }),
+})
+
+/** The realms whose secp256k1 owner keys Tempo ID holds, for tests and local development only. */
+export const realmSecp256k1 = Table.define('realm_secp256k1', {
+  createdAt: timestamp('created_at').defaultNow().notNull(),
+  realmId: text('realm_id')
+    .primaryKey()
+    .references(() => realms.id, { onDelete: 'cascade' }),
+})
+
+/** The realms, each a set of Tempo Accounts. A migration adds the `default` realm. */
+export const realms = Table.define(
+  'realms',
+  {
+    createdAt: timestamp('created_at').defaultNow().notNull(),
+    id: text('id').primaryKey(),
+    name: text('name').notNull(),
+  },
+  (table) => [
+    check('realms_id_check', sql`${table.id} ~ '^[a-z0-9]+(-[a-z0-9]+)*$'`),
+  ],
+)
+
+/** Each user's secp256k1 owner key in each `realm_secp256k1` realm, encrypted with `SECRET`. */
+export const secp256k1Owners = Table.define(
+  'secp256k1_owners',
+  {
+    address: text('address').notNull().unique(),
+    createdAt: timestamp('created_at').defaultNow().notNull(),
+    privateKey: text('private_key').notNull(),
+    realmId: text('realm_id')
+      .notNull()
+      .references(() => realms.id, { onDelete: 'cascade' }),
+    userId: text('user_id')
+      .notNull()
+      .references(() => user.id, { onDelete: 'cascade' }),
+  },
+  (table) => [primaryKey({ columns: [table.userId, table.realmId] })],
+)

package/src/app/db/table.ts

@@ -0,0 +1,31 @@
+/**
+ * Declares Tempo ID's tables in the Postgres schema that the `DATABASE_SCHEMA` variable names, or in
+ * `public` without it. Previews share one database, each in a schema of its own, such as `pr_141`,
+ * and every statement names the schema, since a pooled connection keeps no `search_path`.
+ * @module
+ */
+import { pgSchema, pgTable } from 'drizzle-orm/pg-core'
+
+/** A Postgres schema name, which becomes part of SQL identifiers. */
+const pattern = /^[a-z_][a-z0-9_]{0,62}$/
+
+/**
+ * The schema of every table, or `undefined` for `public`. Each table is declared when its module
+ * loads, so the value comes from `process.env`, which the Worker fills from its variables.
+ */
+export const schema = (() => {
+  const value = globalThis.process?.env?.DATABASE_SCHEMA
+  if (!value || value === 'public') return undefined
+  if (!pattern.test(value))
+    throw new Error(
+      `Invalid DATABASE_SCHEMA: ${JSON.stringify(value)}. Set it to a lowercase Postgres schema name, such as pr_141, or leave it unset.`,
+    )
+  return value
+})()
+
+/** Declares a table in {@link schema}, as `pgTable` declares one in `public`. */
+export const define = schema
+  ? // The tables' types differ only in their schema's name, which no query reads, so every
+    // deployment shares one set of table types.
+    (pgSchema(schema).table as unknown as typeof pgTable)
+  : pgTable

package/src/app/env.ts

@@ -0,0 +1,57 @@
+/**
+ * The variables that Tempo ID reads and Void validates. Void loads this file in Node, so it imports
+ * only `void/env`. @module
+ */
+import { defineEnv, number, oneOf, string, url } from 'void/env'
+
+/** The variables Tempo ID reads, without Void's `DATABASE_URL`. */
+const schema = defineEnv({
+  /** Seconds that each isolate caches configuration rows. Defaults to 30. 0 turns the cache off. */
+  CONFIG_CACHE_TTL: number().optional(),
+  /**
+   * The chains whose Tempo Accounts are configurable (TIP-1107), as comma-separated names, such as
+   * `local`. Without it, no account is configurable. `ConfigurableAccount.chains` reads it.
+   */
+  CONFIGURABLE_ACCOUNTS: string().optional(),
+  /**
+   * The RS256 PKCS #8 PEM key that signs tokens for Privy. Without it, Privy owners cannot sign.
+   */
+  PRIVY_JWT_PRIVATE_KEY: string().optional(),
+  /**
+   * Extra chains, as comma-separated `name:chainId=url` entries. A `mainnet` or `testnet` entry
+   * replaces that chain's RPC URL.
+   */
+  RPC_URLS: string().optional(),
+  /** Signs cookies and encrypts the signing keys. */
+  SECRET: string(),
+  /**
+   * The domains where a sign-up creates an account, as a comma-separated list, such as `tempo.xyz`.
+   * Without it, every verified address can create one. A sign-in of an existing account is never
+   * refused. `Auth.signUpDomains` reads it.
+   */
+  SIGN_UP_DOMAINS: string().optional(),
+  /** The RFC 2606 domain whose codes go to `TEST_INBOX`. Otherwise every code goes by email. */
+  TEST_EMAIL_DOMAIN: oneOf([
+    'example.com',
+    'example.net',
+    'example.org',
+  ]).optional(),
+  /**
+   * Each chain's Tempo API for balances, as `name:chainId=url` entries with the key as user
+   * information. `mainnet` and `testnet` default to `https://api.tempo.xyz`. `none` turns it off.
+   */
+  TEMPO_API_URLS: string().optional(),
+  /** An RPC URL for each built-in chain that `RPC_URLS` does not list. Only tests set it. */
+  TEMPO_RPC_URL: url().optional(),
+  /** Tempo ID's origin, such as `https://id.tempo.xyz`, and every token's `iss`. */
+  URL: url(),
+})
+
+type Shape = typeof schema
+
+// Void writes the same augmentation in `.void/env.d.ts`, which `tsc` does not read.
+declare module 'void/env' {
+  interface ValidatedEnv extends Shape {}
+}
+
+export default schema

package/src/app/inbox.ts

@@ -0,0 +1,190 @@
+/**
+ * Serves Void's dev inbox as JSON for the dev toolbar, since Void's own inbox refuses frames.
+ * @module
+ */
+import * as Crypto from 'node:crypto'
+import * as Fs from 'node:fs'
+import type { ServerResponse } from 'node:http'
+import * as Path from 'node:path'
+import type { Plugin } from 'vite'
+import * as Inbox from './lib/Inbox.js'
+
+/** A message in Void's dev inbox buffer. */
+type Captured = {
+  /** Milliseconds since the epoch. */
+  capturedAt: number
+  /** The sender. */
+  from: Address
+  /** Absent without an HTML part. */
+  html?: string | undefined
+  /** Void's ID of the message. */
+  id: string
+  /** The subject line. */
+  subject: string
+  /** Absent without a text part. */
+  text?: string | undefined
+  /** The recipients. */
+  to: readonly Address[]
+}
+
+/** The part of Void's dev inbox buffer that the plugin reads. */
+type Captures = {
+  /** Oldest first. */
+  items: readonly Captured[]
+}
+
+/** An address on a captured message. */
+type Address = {
+  /** The email address. */
+  email: string
+  /** Absent without a display name. */
+  name?: string | undefined
+}
+
+/** The global key of Void's dev inbox buffer. If a Void upgrade renames it, the inbox is empty. */
+const bufferKey = '__voidEmailDevBuffer__'
+
+/**
+ * Returns the Vite plugin that serves the inbox in `vp dev`:
+ *
+ * - `GET /__devtools/inbox`: each message's summary, newest first.
+ * - `GET /__devtools/inbox/:id`: one message and its parts.
+ * - `GET /__devtools/token`: the token, to a same-origin request only.
+ *
+ * The inbox routes require the token, and each route refuses a `Host` that Vite does not allow.
+ */
+export function plugin(): Plugin {
+  return {
+    apply: 'serve',
+    configureServer: (server) => {
+      const file = Path.join(server.config.root, '.void', 'dev-trigger-token')
+      // Void writes the file as its plugin starts, so each read finds the current token.
+      const token = () => {
+        try {
+          return Fs.readFileSync(file, 'utf8').trim() || undefined
+        } catch {
+          return undefined
+        }
+      }
+
+      server.middlewares.use(Inbox.tokenPath, (request, response) => {
+        if (!allowed(request.headers.host, server.config.server.allowedHosts))
+          return send(response, 403, { error: 'The host is not allowed.' })
+        // Only a browser page on the dev server's own origin sends `same-origin`. A client without the
+        // header, such as a script, reads the token from `.void/dev-trigger-token` instead.
+        if (request.headers['sec-fetch-site'] !== 'same-origin')
+          return send(response, 403, {
+            error: 'Only the same origin reads the token.',
+          })
+
+        const value = token()
+        if (!value)
+          return send(response, 404, {
+            error: 'Void has no dev-trigger token yet.',
+          })
+        return send(response, 200, { token: value })
+      })
+
+      server.middlewares.use(Inbox.path, (request, response) => {
+        if (!allowed(request.headers.host, server.config.server.allowedHosts))
+          return send(response, 403, { error: 'The host is not allowed.' })
+
+        if (!authorized(request.headers[Inbox.header], token()))
+          return send(response, 401, {
+            error: `The inbox needs Void's dev-trigger token in ${Inbox.header}.`,
+          })
+
+        if (request.method !== 'GET')
+          return send(response, 405, { error: 'Method not allowed.' })
+
+        // A malformed escape names no message, as an unknown ID does.
+        const id = (() => {
+          try {
+            return decodeURIComponent(
+              new URL(request.url ?? '/', 'http://localhost').pathname.slice(1),
+            )
+          } catch {
+            return undefined
+          }
+        })()
+        if (id === undefined)
+          return send(response, 404, { error: 'No message has this ID.' })
+
+        const buffer = read()
+
+        const items = buffer?.items ?? []
+        if (!id)
+          return send(response, 200, {
+            messages: items.toReversed().map((message) => ({
+              capturedAt: message.capturedAt,
+              from: message.from,
+              id: message.id,
+              subject: message.subject,
+              to: message.to,
+            })),
+          })
+
+        const message = items.find((entry) => entry.id === id)
+        if (!message)
+          return send(response, 404, { error: 'No message has this ID.' })
+        return send(response, 200, {
+          capturedAt: message.capturedAt,
+          from: message.from,
+          html: message.html,
+          id: message.id,
+          subject: message.subject,
+          text: message.text,
+          to: message.to,
+        })
+      })
+    },
+    name: 'tempo-id:devtools-inbox',
+  }
+}
+
+/**
+ * Returns whether Vite allows `host`: `localhost`, an IP address, or an entry of `allowedHosts`.
+ */
+function allowed(host: string | undefined, hosts: true | readonly string[]) {
+  if (hosts === true) return true
+  if (!host || !URL.canParse(`http://${host}`)) return false
+
+  const { hostname } = new URL(`http://${host}`)
+  if (hostname === 'localhost' || hostname.endsWith('.localhost')) return true
+  if (/^\d{1,3}(\.\d{1,3}){3}$/.test(hostname) || hostname.startsWith('['))
+    return true
+  return hosts.some((entry) =>
+    entry.startsWith('.')
+      ? hostname === entry.slice(1) || hostname.endsWith(entry)
+      : hostname === entry,
+  )
+}
+
+/** Responds with `body` as JSON. */
+function send(response: ServerResponse, status: number, body: unknown) {
+  response.writeHead(status, {
+    'Cache-Control': 'no-store',
+    'Content-Type': 'application/json',
+    'X-Content-Type-Options': 'nosniff',
+  })
+  response.end(JSON.stringify(body))
+}
+
+/** Returns whether `presented` equals the token, in constant time. */
+function authorized(
+  presented: string | readonly string[] | undefined,
+  expected: string | undefined,
+) {
+  if (typeof presented !== 'string' || !expected) return false
+  const a = Buffer.from(presented)
+  const b = Buffer.from(expected)
+  return a.byteLength === b.byteLength && Crypto.timingSafeEqual(a, b)
+}
+
+/** Returns Void's dev inbox buffer, or `undefined` before the first message. */
+function read() {
+  const buffer = (globalThis as Record<string, unknown>)[bufferKey]
+  if (typeof buffer !== 'object' || buffer === null) return undefined
+  if (!Array.isArray((buffer as { items?: unknown }).items)) return undefined
+  return buffer as Captures
+}