@tempoxyz/id 0.0.0-stage → 0.0.1

package/src/app/server.ts

@@ -0,0 +1,342 @@
+/**
+ * The server entry. The root Hono app serves every request, TanStack Start renders the pages, and
+ * loaders call the API in process. The cron trigger runs `crons/cleanup.ts`. @module
+ */
+import type { Register } from '@tanstack/react-start'
+import type { RequestHandler } from '@tanstack/react-start/server'
+import type { Context, ExecutionContext } from 'hono'
+import { withRuntimeEnv } from 'void/_env'
+import reset from 'zyzz/reset.css?url'
+import { api } from '../Api.js'
+import type { Env, Pages } from '../internal/Env.js'
+import * as Log from '../internal/Log.js'
+import * as Timing from '../internal/Timing.js'
+import cleanup from './crons/cleanup.js'
+
+/** The server render's context for each page request. */
+export type RequestContext = {
+  /**
+   * Calls the API in process with the page request's cookies and client headers. A rate limit's
+   * refusal makes the page respond with 429.
+   */
+  fetch: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>
+  /**
+   * Calls the API in process as `fetch` does, for data that the page renders without, such as
+   * options that it streams. A rate limit's refusal leaves the page's status as it is.
+   */
+  fetchOptional: (
+    input: RequestInfo | URL,
+    init?: RequestInit,
+  ) => Promise<Response>
+  /** The page's origin. */
+  origin: string
+}
+
+declare module '@tanstack/react-start' {
+  interface Register {
+    server: { requestContext: RequestContext }
+  }
+}
+
+/** The headers of a rate limit's refusal, which the page carries if its loader meets the limit. */
+const limit = ['ratelimit', 'ratelimit-policy', 'retry-after'] as const
+
+/** The page request's headers that each in-process call forwards. */
+const forwarded = [
+  'cf-connecting-ip',
+  'cf-ray',
+  'cf-worker',
+  'user-agent',
+] as const
+
+/**
+ * TanStack Start's handler, which the first page that an isolate renders imports. The page code,
+ * React's server renderer, and the route tree then load only for a page, so a cold start that
+ * serves only the API, such as a sign-in's `POST`, evaluates none of it.
+ */
+let handler: Promise<RequestHandler<Register>> | undefined
+
+/**
+ * The paths of the sign-in page's scripts and style sheets: the root route's, then the `/login`
+ * route's. The build fixes them, so an isolate reads the manifest once.
+ */
+let signInAssets: Promise<readonly string[]> | undefined
+
+export default {
+  fetch: (
+    request: Request,
+    env: Record<string, unknown>,
+    ctx: ExecutionContext,
+  ) =>
+    api.fetch(
+      request,
+      {
+        ...env,
+        pages: (c: Context<Env>, options: Pages = {}) =>
+          render(c, { ctx, env, request: options.request }),
+        signInAssets: () => (signInAssets ??= assets()),
+      },
+      ctx,
+    ),
+  // Void's Worker entry runs only `fetch` in its runtime scope, so the cron trigger enters it here.
+  scheduled: (...args: Parameters<typeof cleanup>) =>
+    withRuntimeEnv(args[1], () => cleanup(...args)),
+}
+
+/**
+ * Renders the page of `options.request`, or of `c`'s request. Each call carries the newest session
+ * cookie, so no refresh reuses a spent token. A loader's rate-limited call makes the page respond
+ * with 429, unless the call is optional. A loader's redirect to the sign-in page renders that page
+ * instead. A page of another URL than `c`'s replaces the browser's URL with its own before it
+ * hydrates.
+ */
+async function render(c: Context<Env>, options: render.Options) {
+  const { ctx, env } = options
+  const request = options.request ?? c.req.raw
+  const cookies = parse(request.headers.get('cookie') ?? undefined)
+  const origin = new URL(c.req.url).origin
+  let first: Promise<Response> | undefined
+  let limited: Response | undefined
+  let sent = false
+
+  const call = async (input: RequestInfo | URL, init?: RequestInit) => {
+    const request = new Request(input, init)
+    // Loaders read only the JSON API on the page's origin, under `/v1` or `/i`, so a value from a
+    // page's query that resolves to another path never reaches another route with the session.
+    const url = new URL(request.url)
+    if (
+      url.origin !== origin ||
+      !['/i/', '/v1/'].some((prefix) => url.pathname.startsWith(prefix))
+    )
+      throw new Error('A page called a path outside the JSON API.')
+    if (cookies.size > 0) request.headers.set('cookie', serialize(cookies))
+    for (const name of forwarded) {
+      const value = c.req.header(name)
+      if (value) request.headers.set(name, value)
+    }
+
+    // Each call logs its own spans, and the page's header shows the call's total. Each call shares
+    // the owner keys that the page's request listed, such as for `/oauth2/authorize`'s account step.
+    const response = await Timing.measure(
+      c,
+      Promise.resolve(
+        api.fetch(
+          request,
+          {
+            ...env,
+            ownerLists: c.var.ownerLists,
+            pages: () => notFound(),
+            signInAssets: c.env.signInAssets,
+          },
+          ctx,
+        ),
+      ),
+      'api',
+      `${request.method} ${new URL(request.url).pathname}`,
+    )
+    for (const setCookie of response.headers.getSetCookie()) {
+      apply(cookies, { setCookie })
+      // The page's headers go out when the page starts to stream, before its body ends.
+      if (sent)
+        Log.warn(c, {
+          message: 'A page set a cookie after its headers were sent.',
+        })
+      else c.header('set-cookie', setCookie, { append: true })
+    }
+    return response
+  }
+
+  /** Returns a `fetch` that calls the API in process. An optional call's 429 sets no status. */
+  const fetcher =
+    (mode: { optional: boolean }) =>
+    async (input: RequestInfo | URL, init?: RequestInit) => {
+      // Later calls wait for the first one's cookies, so concurrent reads refresh a session once.
+      // A call that a loader starts beside the first one also waits for it, so a page that needs
+      // the session reads it in its first call, such as `GET /v1/account`, and not in a call of
+      // its own.
+      if (first)
+        await Timing.measure(
+          c,
+          first.catch(() => undefined),
+          'api.wait',
+        )
+      const pending = call(input, init)
+      first ??= pending
+      const response = await pending
+      if (response.status === 429 && !mode.optional) limited ??= response
+      return response
+    }
+
+  handler ??= import('@tanstack/react-start/server').then((module) =>
+    module.createStartHandler(module.defaultStreamHandler),
+  )
+  const start = await Timing.measure(c, handler, 'pages.load')
+  const response = await start(request, {
+    context: {
+      fetch: fetcher({ optional: false }),
+      fetchOptional: fetcher({ optional: true }),
+      origin,
+    },
+  })
+
+  // A loader that sends the visitor to sign-in, such as the account page's, renders the sign-in page
+  // in this response instead, so the browser loads it without a second request. The sign-in page's
+  // own redirect, such as for a signed-in visitor, goes out as it is. A form's post keeps its
+  // redirect, so a reload of the page that follows sends no form again. A `HEAD` request receives
+  // the status of its `GET`.
+  const signIn =
+    options.signIn || !['GET', 'HEAD'].includes(request.method)
+      ? undefined
+      : signInUrl(response, { origin })
+  if (signIn) {
+    await response.body?.cancel()
+    const headers = new Headers(request.headers)
+    if (cookies.size > 0) headers.set('cookie', serialize(cookies))
+    else headers.delete('cookie')
+    return render(c, {
+      ctx,
+      env,
+      request: new Request(signIn, { headers }),
+      signIn: true,
+    })
+  }
+  sent = true
+  // Pages show the signed-in user's data and an app's signed request, so no cache keeps them.
+  c.header('cache-control', 'private, no-store')
+
+  // The rendered page's URL applies to a rate-limited page too, which renders the same route.
+  const body = (
+    request === c.req.raw
+      ? response
+      : replaceUrl(response, { url: request.url })
+  ).body
+  if (limited && response.status === 200) {
+    for (const name of limit) {
+      const value = limited.headers.get(name)
+      if (value) c.header(name, value)
+    }
+    return c.newResponse(body, { headers: response.headers, status: 429 })
+  }
+  return c.newResponse(body, response)
+}
+
+declare namespace render {
+  type Options = {
+    /** The Worker's execution context. */
+    ctx: ExecutionContext
+    /** The Worker's bindings. */
+    env: Record<string, unknown>
+    /** The request of the page to render. Defaults to `c`'s request. */
+    request?: Request | undefined
+    /** Whether the render is the sign-in page that a loader redirected to. Defaults to `false`. */
+    signIn?: boolean | undefined
+  }
+}
+
+/** Returns the URL of the sign-in page that `response` redirects to, or `undefined`. */
+function signInUrl(response: Response, options: signInUrl.Options) {
+  if (response.status < 300 || response.status > 399) return undefined
+  const url = URL.parse(response.headers.get('location') ?? '', options.origin)
+  if (url?.origin !== options.origin || url.pathname !== '/login')
+    return undefined
+  return url.href
+}
+
+declare namespace signInUrl {
+  type Options = {
+    /** The page's origin. */
+    origin: string
+  }
+}
+
+/**
+ * Returns `response` with a script at the start of its head that replaces the browser's URL with
+ * `url`'s path and query. The script runs before the router reads the URL to hydrate.
+ */
+function replaceUrl(response: Response, options: replaceUrl.Options) {
+  const url = new URL(options.url)
+  // `<` is escaped, so no value of the URL ends the script element.
+  const path = JSON.stringify(url.pathname + url.search).replaceAll(
+    '<',
+    '\\u003c',
+  )
+  return new HTMLRewriter()
+    .on('head', {
+      element: (element) => {
+        element.prepend(
+          `<script>history.replaceState(null, '', ${path})</script>`,
+          { html: true },
+        )
+      },
+    })
+    .transform(response)
+}
+
+declare namespace replaceUrl {
+  type Options = {
+    /** The URL of the page that the response renders. */
+    url: string
+  }
+}
+
+/** Applies a `Set-Cookie` header to `cookies`, and removes an expired cookie. */
+function apply(cookies: Map<string, string>, options: apply.Options) {
+  // `split` returns at least one element.
+  const [pair, ...attributes] = options.setCookie.split(';') as [
+    string,
+    ...string[],
+  ]
+  const index = pair.indexOf('=')
+  const name = pair.slice(0, index).trim()
+  const value = pair.slice(index + 1).trim()
+  // `deleteCookie` sets an empty value with `Max-Age=0`.
+  const expired = attributes.some((attribute) =>
+    /^max-age=0$/i.test(attribute.trim()),
+  )
+  if (expired || !value) cookies.delete(name)
+  else cookies.set(name, value)
+}
+
+declare namespace apply {
+  type Options = {
+    /** One `Set-Cookie` header value. */
+    setCookie: string
+  }
+}
+
+/**
+ * Reads the sign-in page's scripts and style sheets from TanStack Start's manifest. The root route
+ * links zyzz's reset style sheet itself, outside the manifest, so it comes first.
+ */
+async function assets() {
+  const { tsrStartManifest } = await import('tanstack-start-manifest:v')
+  const { routes } = tsrStartManifest()
+  const paths = ['__root__', '/login'].flatMap((id) => {
+    const route = routes[id]
+    return [...(route?.css ?? []), ...(route?.preloads ?? [])].map((link) =>
+      typeof link === 'string' ? link : link.href,
+    )
+  })
+  return [...new Set([reset, ...paths])]
+}
+
+/** Responds with 404 to an in-process call that no route serves. */
+function notFound() {
+  return Promise.resolve(new Response(null, { status: 404 }))
+}
+
+/** Parses a `Cookie` header into raw values by name. */
+function parse(header: string | undefined) {
+  const cookies = new Map<string, string>()
+  for (const pair of header?.split(';') ?? []) {
+    const index = pair.indexOf('=')
+    if (index > 0)
+      cookies.set(pair.slice(0, index).trim(), pair.slice(index + 1).trim())
+  }
+  return cookies
+}
+
+/** Serializes `cookies` as a `Cookie` header. */
+function serialize(cookies: Map<string, string>) {
+  return [...cookies].map(([name, value]) => `${name}=${value}`).join('; ')
+}

package/src/app/vite.config.ts

@@ -0,0 +1,128 @@
+/** Builds and serves the app with Void, TanStack Start, zyzz, and icons. @module */
+import { type ConfigPlugin, transform } from '@svgr/core'
+import jsx from '@svgr/plugin-jsx'
+import { tanstackStart } from '@tanstack/react-start/plugin/vite'
+import react from '@vitejs/plugin-react'
+import * as Url from 'node:url'
+import icons from 'unplugin-icons/vite'
+import { defineConfig } from 'vite'
+import { voidPlugin } from 'void'
+import { zyzz } from 'zyzz/vite'
+import * as Coverage from './coverage.js'
+import * as Inbox from './inbox.js'
+
+/** svgr's JSX plugin. Node returns the CommonJS exports, with the plugin as `default`. */
+const svgJsx: ConfigPlugin =
+  typeof jsx === 'function' ? jsx : (jsx as { default: ConfigPlugin }).default
+
+/** Whether the build instruments the Worker for the integration suite's coverage report. */
+const coverage = process.env.COVERAGE === 'true'
+
+export default defineConfig({
+  environments: {
+    // The Worker bundles every dependency. TanStack Start lists its own packages, which would leave
+    // the rest external, and zyzz then cannot read the contracts of `@tempoxyz/ds` and `zyzz`.
+    ssr: { resolve: { noExternal: true } },
+  },
+  // Plugins run in order: Void comes before TanStack Start, zyzz compiles styles before the route and
+  // React transforms, and TanStack Start comes before React's plugin.
+  plugins: [
+    // When `WALLET_URL` names a local wallet, `vp dev` runs `wallet.ts`, which `void.config.ts` binds
+    // as `WALLET`.
+    voidPlugin(
+      process.env.WALLET_URL
+        ? {
+            auxiliaryWorkers: [
+              {
+                config: {
+                  compatibility_date: '2026-02-24',
+                  main: Url.fileURLToPath(
+                    new URL('wallet.ts', import.meta.url),
+                  ),
+                  name: 'wallet',
+                  vars: { WALLET_URL: process.env.WALLET_URL },
+                },
+                devOnly: true,
+              },
+            ],
+          }
+        : {},
+    ),
+    // The dev toolbar reads Void's dev inbox as JSON.
+    Inbox.plugin(),
+    // Void targets browsers with native `light-dark()`, which zyzz needs, and Cloudflare's plugin adds
+    // `es2024` to its Worker environment, which zyzz cannot check. Vite concatenates the two lists, so
+    // the resolved list drops the addition before zyzz reads it.
+    {
+      configResolved: (config) => {
+        const builds = [
+          config.build,
+          ...Object.values(config.environments).map((entry) => entry.build),
+        ]
+        for (const build of builds)
+          if (Array.isArray(build.cssTarget))
+            build.cssTarget = build.cssTarget.filter(
+              (target) => target !== 'es2024',
+            )
+      },
+      enforce: 'pre',
+      name: 'tempo-id:css-target',
+    },
+    // Styles live in routes, screens, and components. The extractor cannot load server-only modules.
+    zyzz({
+      exclude: [
+        'coverage.server.ts',
+        'coverage.ts',
+        'crons/**',
+        'db/**',
+        'env.ts',
+        'inbox.ts',
+        'routeTree.gen.ts',
+        'server.ts',
+        'void.config.ts',
+        'wallet.ts',
+      ],
+    }),
+    // The app's root is `src/app`, which holds the router, the routes, and the server entry.
+    tanstackStart({ srcDirectory: '.' }),
+    react(),
+    // Icons compile to React components, imported from `~icons/<collection>/<name>`. The compiler
+    // imports svgr here, since the icons plugin's own lookup of it fails under `vp dev`.
+    icons({
+      compiler: {
+        compiler: (svg, collection, icon) =>
+          transform(
+            svg,
+            { plugins: [svgJsx], ref: true, titleProp: true },
+            {
+              componentName: `${collection}-${icon}`.replace(
+                /-(\w)/g,
+                (_, letter: string) => letter.toUpperCase(),
+              ),
+            },
+          ),
+        extension: 'jsx',
+      },
+      jsx: 'react',
+      scale: 1,
+    }),
+    // It instruments the output of every other plugin, which its source maps trace to `src/`.
+    ...(coverage ? [Coverage.plugin()] : []),
+  ],
+  // Void's Worker entry imports TanStack Start's default server entry, so the alias points it at
+  // `server.ts`, which serves every request through the root Hono app and runs the cron trigger. The
+  // coverage build's entry wraps `server.ts`.
+  resolve: {
+    alias: [
+      {
+        find: /^@tanstack\/react-start\/server-entry$/,
+        replacement: coverage
+          ? Coverage.entry
+          : Url.fileURLToPath(new URL('server.ts', import.meta.url)),
+      },
+    ],
+  },
+  // The dev server's own CORS answers each preflight before the app runs, and admits only localhost
+  // origins, so it would refuse the playgrounds. The root Hono app's `Cors` policies decide instead.
+  server: { cors: false },
+})

package/src/app/void.config.ts

@@ -0,0 +1,36 @@
+/**
+ * The app's Void configuration: database, bindings, and rate limits. A deployment declares the same
+ * bindings. @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 },
+    })),
+    // When `WALLET_URL` names a local wallet, `vp dev` binds `WALLET` to the stand-in in `wallet.ts`,
+    // which `vite.config.ts` runs beside the app. A deployment binds wallet.tempo's own entrypoint.
+    ...(process.env.WALLET_URL
+      ? {
+          services: [
+            { binding: 'WALLET', entrypoint: 'Credentials', service: 'wallet' },
+          ],
+        }
+      : {}),
+    // `/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.tempo.xyz>' },
+  // 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/wallet.ts

@@ -0,0 +1,69 @@
+/**
+ * A Worker for `vp dev` that stands in for wallet.tempo's `Credentials` entrypoint, bound as
+ * `WALLET` when `WALLET_URL` names a local wallet. A service binding cannot reach the wallet's own
+ * dev server in another container, so each call posts to the wallet's dev route instead. Tempo ID
+ * validates what each call returns, as it does for the real entrypoint.
+ * @module
+ */
+import { WorkerEntrypoint } from 'cloudflare:workers'
+
+/** The Worker's bindings. */
+type Env = {
+  /** The local wallet's origin, with its dev key as user information, such as `https://<key>@wallet.tempo.local`. */
+  WALLET_URL: string
+}
+
+/** Serves wallet.tempo's `Credentials` calls through the local wallet's dev route. */
+export class Credentials extends WorkerEntrypoint<Env> {
+  /** Returns the passkey with `credentialId`, or `undefined` when the wallet stores none. */
+  async credential(options: { credentialId: string }) {
+    return (
+      (await post(this.env, { body: options, path: 'credential' })) ?? undefined
+    )
+  }
+
+  /** Returns the passkeys of the accounts whose verified email is `email`, oldest first. */
+  credentials(options: { email: string }) {
+    return post(this.env, { body: options, path: 'credentials' })
+  }
+}
+
+export default {
+  fetch: () => new Response(null, { status: 404 }),
+}
+
+/** Posts `body` to the wallet's dev route `path`, and returns its JSON. Throws on any other status than 200. */
+async function post(env: Env, options: post.Options): Promise<unknown> {
+  // The URL holds the key in its user name and password, such as `dev:key`, which the URL splits at
+  // the first colon. The wallet reads the key as a bearer token.
+  const url = new URL(env.WALLET_URL)
+  const key = [url.username, url.password]
+    .filter(Boolean)
+    .map(decodeURIComponent)
+    .join(':')
+  url.username = ''
+  url.password = ''
+  url.pathname = `/api/dev/${options.path}`
+
+  const response = await fetch(url, {
+    body: JSON.stringify(options.body),
+    headers: {
+      authorization: `Bearer ${key}`,
+      'content-type': 'application/json',
+    },
+    method: 'POST',
+  })
+  if (!response.ok)
+    throw new Error(`The local wallet responded with ${response.status}.`)
+
+  return response.json()
+}
+
+declare namespace post {
+  type Options = {
+    /** The options of the `Credentials` call. */
+    body: unknown
+    /** The route, named for the `Credentials` call. */
+    path: 'credential' | 'credentials'
+  }
+}

package/src/app/zyzz.config.ts

@@ -0,0 +1,52 @@
+/**
+ * Configures zyzz: the design system's variables, the canvas tokens, and the document styles.
+ * @module
+ */
+import { variables } from '@tempoxyz/ds'
+import { Config, Vars } from 'zyzz'
+import { global } from 'zyzz/web'
+
+/** The tokens of the third-party app on the flows canvas. */
+const thirdParty = Vars.extend(
+  variables,
+  {
+    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: { '6': '1rem', '8': '1.25rem' },
+  },
+  { id: 'tempo-id/third-party' },
+)
+
+/** The style helpers. `vars({ set: 'thirdParty' })` applies the third-party tokens. */
+export const { style, variants, vars } = Config.create({
+  defaultVars: 'default',
+  id: 'tempo-id',
+  vars: { default: variables, thirdParty },
+})
+
+// The page draws on the surface color in light mode and the primary color in dark mode, so the gray
+// fills of cards stand out in both. `light-dark()` follows the root's `color-scheme`, which the dev
+// toolbar's scheme switch sets.
+global({
+  'html, body': {
+    // oxlint-disable-next-line typescript/restrict-template-expressions -- zyzz reads each token reference at build time, so it stays a direct interpolation.
+    backgroundColor: `light-dark(${vars.color.background.surface}, ${vars.color.background.primary})`,
+    color: vars.color.foreground,
+  },
+  body: { fontFamily: vars.fontFamily.sans },
+  'button, input': { font: 'inherit' },
+  'code, pre': { fontFamily: vars.fontFamily.mono },
+  html: { colorScheme: 'light dark' },
+})