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

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

@@ -0,0 +1,83 @@
+{
+  "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
+    }
+  ]
+}

package/src/app/db/schema.ts

@@ -0,0 +1,218 @@
+/**
+ * Tempo ID's tables, as Drizzle declares them: the Better Auth tables, then Tempo ID's own.
+ * @module
+ */
+import { sql } from 'drizzle-orm'
+import {
+  check,
+  index,
+  integer,
+  jsonb,
+  pgTable,
+  primaryKey,
+  text,
+  timestamp,
+  unique,
+} from 'drizzle-orm/pg-core'
+import { oauthClient, user } from './auth.js'
+
+export * from './auth.js'
+
+/**
+ * The realms of each OAuth app, in order. The first realm holds a user's first account. An app
+ * without rows reaches the `default` realm.
+ */
+export const appRealms = pgTable(
+  '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,
+    ),
+  ],
+)
+
+/**
+ * What a CLI reported with each device grant request, where it came from, and the key that it
+ * requested, which the device page shows beside the user code. Each row shares the ID of its `device_code` row. It has no foreign key, so it outlives the
+ * redemption that deletes that row, and the cleanup cron deletes it once it expires.
+ */
+export const deviceRequests = pgTable('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'),
+})
+
+/**
+ * The realm of each user's first created account, claimed before an owner kind, such as Privy,
+ * creates the key. A request that finds a claim in its realms completes that account instead of
+ * creating another, so the kind's calls hold no database connection.
+ */
+export const firstAccounts = pgTable(
+  '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 keys that users sign in with: for now, passkeys. Each row is one WebAuthn credential of one
+ * relying party, linked to one user.
+ */
+export const keys = pgTable(
+  'keys',
+  {
+    // The address that the public key derives, in lowercase.
+    address: text('address').notNull().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(),
+    // `tempo-id` for a passkey that Tempo ID stored, `wallet` for one that wallet.tempo created.
+    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 ('tempo-id', 'wallet')`),
+    check('keys_type_check', sql`${table.type} = 'passkey'`),
+    index('keys_user_id_idx').on(table.userId),
+  ],
+)
+
+/**
+ * The key authorizations that the approval page signed, each held for the code that the same
+ * approval returned, by the app's client ID and the request's PKCE challenge. The first redemption
+ * of a code with the challenge's verifier deletes the row and returns the key beside the tokens.
+ */
+export const pendingKeys = pgTable(
+  '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) => [primaryKey({ columns: [table.clientId, table.codeChallenge] })],
+)
+
+/**
+ * The passkey relying party of each realm that holds passkey owners. Two realms cannot share one,
+ * since a passkey belongs to exactly one relying party.
+ */
+export const realmPasskeys = pgTable('realm_passkeys', {
+  createdAt: timestamp('created_at').defaultNow().notNull(),
+  realmId: text('realm_id')
+    .primaryKey()
+    .references(() => realms.id, { onDelete: 'cascade' }),
+  rpId: text('rp_id').notNull().unique(),
+})
+
+/**
+ * The Privy app of each realm that holds Privy owners. `app_secret` holds the Privy app secret,
+ * encrypted with the `SECRET` variable, never the secret itself.
+ */
+export const realmPrivy = pgTable('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 owners Tempo ID holds itself, which the suites and local development
+ * turn on. A production realm never has a row, since such a key stays in Tempo ID's database.
+ */
+export const realmSecp256k1 = pgTable('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 realm's owner configurations, such as `realm_privy`
+ * and `realm_passkeys`, live in their own tables. A migration adds the `default` realm.
+ */
+export const realms = pgTable(
+  '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]+)*$'`),
+  ],
+)
+
+/**
+ * The secp256k1 owner key of each user in each realm that `realm_secp256k1` names, which Tempo ID
+ * creates and signs with. `private_key` holds the key encrypted with the `SECRET` variable, never
+ * the key itself.
+ */
+export const secp256k1Owners = pgTable(
+  '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/env.ts

@@ -0,0 +1,49 @@
+/**
+ * The variables Tempo ID reads, which Void validates. Void loads `env.ts` with Node, outside Vite, so
+ * this module imports no other module.
+ * @module
+ */
+import { defineEnv, oneOf, string, url } from 'void/env'
+
+/** The variables Tempo ID reads. Void's own `DATABASE_URL` stays outside it. */
+const schema = defineEnv({
+  /** Google's OAuth client ID. Without it and its secret, Tempo ID offers no Google sign-in. */
+  GOOGLE_CLIENT_ID: string().optional(),
+  /** Google's OAuth client secret, beside `GOOGLE_CLIENT_ID`. */
+  GOOGLE_CLIENT_SECRET: string().optional(),
+  /**
+   * The RS256 private key, as PKCS #8 PEM, that signs the tokens Tempo ID sends to Privy. Each Privy
+   * app trusts only its public half, so no app's token signs as a user's wallet. Without it, Privy
+   * owners sign nothing.
+   */
+  PRIVY_JWT_PRIVATE_KEY: string().optional(),
+  /** The secret that signs cookies and encrypts the signing keys. */
+  SECRET: string(),
+  /**
+   * The domain whose sign-in codes go to the `TEST_INBOX` binding instead of email, such as
+   * `example.org` on a preview. Only the domains that RFC 2606 reserves pass, as `TestInbox.domains`
+   * in `src/internal/TestInbox.ts` lists them. Without it, or without the binding, every code is
+   * emailed.
+   */
+  TEST_EMAIL_DOMAIN: oneOf([
+    'example.com',
+    'example.net',
+    'example.org',
+  ]).optional(),
+  /**
+   * An RPC URL that replaces every chain's own for balance reads, such as a local Tempo node. The
+   * test harness sets it, and deployments leave it unset.
+   */
+  TEMPO_RPC_URL: url().optional(),
+  /** Tempo ID's origin, such as `https://id.tempo.xyz`. It becomes 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/lib/Client.ts

@@ -0,0 +1,82 @@
+/**
+ * Calls Tempo ID's JSON API from a page with `hc`, typed by the root app's routes. During server
+ * rendering the client calls the API in process, through the request context that `server.ts`
+ * passes. In the browser it fetches the page's origin. The root route creates one client for the
+ * document and provides it, and pages read it with {@link use}. Loaders create their own.
+ * @module
+ */
+import {
+  createIsomorphicFn,
+  getGlobalStartContext,
+} from '@tanstack/react-start'
+import { DetailedError, hc } from 'hono/client'
+import { createContext, useContext } from 'react'
+import type { App } from '../../Api.js'
+
+/** A client for Tempo ID's JSON API. */
+export type Client = ReturnType<typeof create>
+
+/** Returns the `fetch` that reaches the API: in process on the server, and the network in the browser. */
+const fetcher = createIsomorphicFn()
+  .server(() => getGlobalStartContext()!.fetch)
+  .client(() => fetch)
+
+/** Returns the page's origin. */
+const origin = createIsomorphicFn()
+  .server(() => getGlobalStartContext()!.origin)
+  .client(() => window.location.origin)
+
+/** The client that the root route provides to every page. */
+export const Context = createContext<Client | undefined>(undefined)
+
+/**
+ * Creates a client for the page request on the server, or for the page in the browser. Requests go
+ * to the page's own origin, so the session cookie goes with each one.
+ */
+export function create() {
+  return hc<App>(origin(), { fetch: fetcher() })
+}
+
+/**
+ * Returns the message to show for `error`: the `error_description` of a refusal that `parseResponse`
+ * throws, or a generic message for any other failure, such as a lost connection.
+ */
+export function message(error: unknown) {
+  if (error instanceof DetailedError) {
+    const data: unknown = error.detail?.data
+    if (
+      typeof data === 'object' &&
+      data !== null &&
+      'error_description' in data &&
+      typeof data.error_description === 'string'
+    )
+      return data.error_description
+    return 'Something went wrong. Try again.'
+  }
+  return 'Tempo ID cannot be reached. Check the connection, and try again.'
+}
+
+/** Returns the `reason` of a refusal that `parseResponse` throws, or `undefined` for any other failure. */
+export function reason(error: unknown) {
+  if (!(error instanceof DetailedError)) return undefined
+  const data: unknown = error.detail?.data
+  if (
+    typeof data === 'object' &&
+    data !== null &&
+    'reason' in data &&
+    typeof data.reason === 'string'
+  )
+    return data.reason
+  return undefined
+}
+
+/**
+ * Returns the root route's client.
+ *
+ * @throws {Error} When a component renders outside the root route.
+ */
+export function use() {
+  const client = useContext(Context)
+  if (!client) throw new Error('The client is used outside the root route.')
+  return client
+}

package/src/app/lib/Loader.ts

@@ -0,0 +1,24 @@
+/** Shared parts of the pages' loaders. @module */
+import { redirect as router_redirect } from '@tanstack/react-router'
+
+/**
+ * Throws a redirect to `href`, with status 302. A redirect to a path that no route serves, such as
+ * `/oauth2/authorize`, or to another origin loads the document, since the router cannot render it.
+ */
+export function redirect(options: redirect.Options): never {
+  const { document = false, href } = options
+  throw router_redirect({
+    href,
+    ...(document ? { reloadDocument: true } : {}),
+    statusCode: 302,
+  })
+}
+
+export declare namespace redirect {
+  type Options = {
+    /** Whether the browser loads `href` as a document. Defaults to `false`. */
+    document?: boolean | undefined
+    /** The path, or the absolute URL, that the redirect names. */
+    href: string
+  }
+}

package/src/app/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "@tempoxyz/id-app",
+  "private": true,
+  "type": "module",
+  "devDependencies": {
+    "@tanstack/react-start": "catalog:"
+  }
+}

package/src/app/routeTree.gen.ts

@@ -0,0 +1,198 @@
+/* eslint-disable */
+
+// @ts-nocheck
+
+// noinspection JSUnusedGlobalSymbols
+
+// This file was automatically generated by TanStack Router.
+// You should NOT make any changes in this file as it will be overwritten.
+// Additionally, you should also exclude this file from your linter and/or formatter to prevent it from being checked or modified.
+
+import { Route as rootRouteImport } from './routes/__root'
+import { Route as IndexRouteImport } from './routes/index'
+import { Route as AuthorizeRouteImport } from './routes/authorize'
+import { Route as ChooseAccountRouteImport } from './routes/choose-account'
+import { Route as DepositRouteImport } from './routes/deposit'
+import { Route as DeviceRouteImport } from './routes/device'
+import { Route as LoginRouteImport } from './routes/login'
+import { Route as Char91_Char93FlowsRouteImport } from './routes/[_].flows'
+
+const IndexRoute = IndexRouteImport.update({
+  id: '/',
+  path: '/',
+  getParentRoute: () => rootRouteImport,
+} as any)
+const AuthorizeRoute = AuthorizeRouteImport.update({
+  id: '/authorize',
+  path: '/authorize',
+  getParentRoute: () => rootRouteImport,
+} as any)
+const ChooseAccountRoute = ChooseAccountRouteImport.update({
+  id: '/choose-account',
+  path: '/choose-account',
+  getParentRoute: () => rootRouteImport,
+} as any)
+const DepositRoute = DepositRouteImport.update({
+  id: '/deposit',
+  path: '/deposit',
+  getParentRoute: () => rootRouteImport,
+} as any)
+const DeviceRoute = DeviceRouteImport.update({
+  id: '/device',
+  path: '/device',
+  getParentRoute: () => rootRouteImport,
+} as any)
+const LoginRoute = LoginRouteImport.update({
+  id: '/login',
+  path: '/login',
+  getParentRoute: () => rootRouteImport,
+} as any)
+const Char91_Char93FlowsRoute = Char91_Char93FlowsRouteImport.update({
+  id: '/_/flows',
+  path: '/_/flows',
+  getParentRoute: () => rootRouteImport,
+} as any)
+
+export interface FileRoutesByFullPath {
+  '/': typeof IndexRoute
+  '/authorize': typeof AuthorizeRoute
+  '/choose-account': typeof ChooseAccountRoute
+  '/deposit': typeof DepositRoute
+  '/device': typeof DeviceRoute
+  '/login': typeof LoginRoute
+  '/_/flows': typeof Char91_Char93FlowsRoute
+}
+export interface FileRoutesByTo {
+  '/': typeof IndexRoute
+  '/authorize': typeof AuthorizeRoute
+  '/choose-account': typeof ChooseAccountRoute
+  '/deposit': typeof DepositRoute
+  '/device': typeof DeviceRoute
+  '/login': typeof LoginRoute
+  '/_/flows': typeof Char91_Char93FlowsRoute
+}
+export interface FileRoutesById {
+  __root__: typeof rootRouteImport
+  '/': typeof IndexRoute
+  '/authorize': typeof AuthorizeRoute
+  '/choose-account': typeof ChooseAccountRoute
+  '/deposit': typeof DepositRoute
+  '/device': typeof DeviceRoute
+  '/login': typeof LoginRoute
+  '/_/flows': typeof Char91_Char93FlowsRoute
+}
+export interface FileRouteTypes {
+  fileRoutesByFullPath: FileRoutesByFullPath
+  fullPaths:
+    | '/'
+    | '/authorize'
+    | '/choose-account'
+    | '/deposit'
+    | '/device'
+    | '/login'
+    | '/_/flows'
+  fileRoutesByTo: FileRoutesByTo
+  to:
+    | '/'
+    | '/authorize'
+    | '/choose-account'
+    | '/deposit'
+    | '/device'
+    | '/login'
+    | '/_/flows'
+  id:
+    | '__root__'
+    | '/'
+    | '/authorize'
+    | '/choose-account'
+    | '/deposit'
+    | '/device'
+    | '/login'
+    | '/_/flows'
+  fileRoutesById: FileRoutesById
+}
+export interface RootRouteChildren {
+  IndexRoute: typeof IndexRoute
+  AuthorizeRoute: typeof AuthorizeRoute
+  ChooseAccountRoute: typeof ChooseAccountRoute
+  DepositRoute: typeof DepositRoute
+  DeviceRoute: typeof DeviceRoute
+  LoginRoute: typeof LoginRoute
+  Char91_Char93FlowsRoute: typeof Char91_Char93FlowsRoute
+}
+
+declare module '@tanstack/react-router' {
+  interface FileRoutesByPath {
+    '/': {
+      id: '/'
+      path: '/'
+      fullPath: '/'
+      preLoaderRoute: typeof IndexRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+    '/authorize': {
+      id: '/authorize'
+      path: '/authorize'
+      fullPath: '/authorize'
+      preLoaderRoute: typeof AuthorizeRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+    '/choose-account': {
+      id: '/choose-account'
+      path: '/choose-account'
+      fullPath: '/choose-account'
+      preLoaderRoute: typeof ChooseAccountRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+    '/deposit': {
+      id: '/deposit'
+      path: '/deposit'
+      fullPath: '/deposit'
+      preLoaderRoute: typeof DepositRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+    '/device': {
+      id: '/device'
+      path: '/device'
+      fullPath: '/device'
+      preLoaderRoute: typeof DeviceRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+    '/login': {
+      id: '/login'
+      path: '/login'
+      fullPath: '/login'
+      preLoaderRoute: typeof LoginRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+    '/_/flows': {
+      id: '/_/flows'
+      path: '/_/flows'
+      fullPath: '/_/flows'
+      preLoaderRoute: typeof Char91_Char93FlowsRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+  }
+}
+
+const rootRouteChildren: RootRouteChildren = {
+  IndexRoute: IndexRoute,
+  AuthorizeRoute: AuthorizeRoute,
+  ChooseAccountRoute: ChooseAccountRoute,
+  DepositRoute: DepositRoute,
+  DeviceRoute: DeviceRoute,
+  LoginRoute: LoginRoute,
+  Char91_Char93FlowsRoute: Char91_Char93FlowsRoute,
+}
+export const routeTree = rootRouteImport
+  ._addFileChildren(rootRouteChildren)
+  ._addFileTypes<FileRouteTypes>()
+
+import type { getRouter } from './router.tsx'
+import type { createStart } from '@tanstack/react-start'
+declare module '@tanstack/react-start' {
+  interface Register {
+    ssr: true
+    router: Awaited<ReturnType<typeof getRouter>>
+  }
+}