@tempoxyz/id 0.0.0-stage → 0.0.1

package/package.json

@@ -1,6 +1,86 @@
 {
   "name": "@tempoxyz/id",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.1",
+  "description": "Tempo ID: sign-in, tokens, and access keys for Tempo, on Better Auth and Void.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "src": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./client": {
+      "src": "./src/client.ts",
+      "types": "./dist/client.d.ts",
+      "default": "./dist/client.js"
+    },
+    "./worker": {
+      "src": "./src/worker.ts",
+      "types": "./dist/worker.d.ts",
+      "default": "./dist/worker.js"
+    }
+  },
+  "imports": {
+    "#app": "./dist/app/server/index.js"
+  },
+  "bin": {
+    "tempo-id": "./dist/cli/bin.js",
+    "tempo-id.src": "./src/cli/bin.ts"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!**/*.test.ts",
+    "!src/app/.env*",
+    "!src/app/.void",
+    "!src/app/.void-wrangler.jsonc",
+    "!src/app/dist"
+  ],
+  "dependencies": {
+    "incur": "0.7.0",
+    "jose": "6.2.12",
+    "ox": "0.14.59",
+    "pg": "8.23.1",
+    "tldts": "7.4.16"
+  },
+  "peerDependencies": {
+    "@better-auth/cimd": "^1.8.0-beta.2",
+    "@better-auth/core": "^1.8.0-beta.2",
+    "@better-auth/oauth-provider": "^1.8.0-beta.2",
+    "better-auth": "^1.8.0-beta.2",
+    "drizzle-orm": "^0.45.4",
+    "viem": "^2.57.12",
+    "zod": "^4.6.7"
+  },
+  "peerDependenciesMeta": {
+    "@better-auth/cimd": {
+      "optional": true
+    },
+    "@better-auth/core": {
+      "optional": true
+    },
+    "@better-auth/oauth-provider": {
+      "optional": true
+    },
+    "better-auth": {
+      "optional": true
+    },
+    "drizzle-orm": {
+      "optional": true
+    },
+    "viem": {
+      "optional": true
+    },
+    "zod": {
+      "optional": true
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tempoxyz/id.git"
+  },
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts"
 }

package/src/Api.ts

@@ -0,0 +1,157 @@
+/**
+ * Tempo ID's server: the root Hono app, which mounts each app in `api/` under the middleware of
+ * every request, pages included. A path that no route serves renders a TanStack Start page.
+ * @module
+ */
+import { Hono } from 'hono'
+import { except } from 'hono/combine'
+import { csrf } from 'hono/csrf'
+import { secureHeaders } from 'hono/secure-headers'
+import { trimTrailingSlash } from 'hono/trailing-slash'
+import { account } from './api/account.js'
+import { authenticate } from './api/authenticate.js'
+import { authorize } from './api/authorize.js'
+import { device } from './api/device.js'
+import { health } from './api/health.js'
+import * as Auth from './api/lib/Auth.js'
+import * as Cors from './api/lib/Cors.js'
+import * as IsolateCache from './api/lib/IsolateCache.js'
+import { oauth } from './api/oauth.js'
+import * as BodyLimit from './internal/BodyLimit.js'
+import type { Env } from './internal/Env.js'
+import * as ErrorResponse from './internal/ErrorResponse.js'
+import * as OpenApi from './internal/OpenApi.js'
+import * as Privy from './internal/Privy.js'
+import * as RequestId from './internal/RequestId.js'
+import * as TempoAccount from './internal/TempoAccount.js'
+import * as Timing from './internal/Timing.js'
+
+/** Every route, with the RPC types that `type App` carries. */
+const routes = new Hono<Env>()
+  .route('/', health)
+  .route('/', account)
+  .route('/', authenticate)
+  .route('/', authorize)
+  .route('/', device)
+  .route('/', oauth)
+
+/** The API's routes, whose RPC types a typed client reads. */
+export type App = typeof routes
+
+/**
+ * The root app, which serves every request. The annotation breaks the type cycle with its document
+ * route, which reads `api`.
+ */
+export const api: Hono<Env> = new Hono<Env>()
+  // Middleware runs before the routes registered after it, so timing covers the rest. The request ID
+  // comes next, so every response and log entry carries it.
+  .use(Timing.middleware)
+  .use(RequestId.middleware())
+  // The isolate's cache comes before CORS, whose first-party check reads it.
+  .use(IsolateCache.middleware)
+  // Each request reads a user's Privy user once, so the Privy users live only for the request.
+  .use(Privy.middleware)
+  // Each request lists a user's owner keys in the same realms once, as it reads Privy users once.
+  .use(TempoAccount.middleware)
+  // A form post carries `Origin: null` under `no-referrer`, so Void refuses an early sign-in submit.
+  // `same-origin` keeps the origin on same-origin posts, and sends no referrer to other sites.
+  .use(secureHeaders({ referrerPolicy: 'same-origin' }))
+  // A `GET` of a known path with a trailing slash, such as `/health/`, redirects to the path without it.
+  .use(trimTrailingSlash())
+  // CORS runs before the CSRF check and the body limit, so a browser reads their refusals. The OAuth
+  // discovery documents and the endpoints that read no cookie serve any page. `/device/code` gets no
+  // CORS, since a page that read its user code could start a code from the visitor's own IP address.
+  .use('/.well-known/oauth-authorization-server', Cors.oauth)
+  .use('/.well-known/openid-configuration', Cors.oauth)
+  .use('/oauth2/introspect', Cors.oauth)
+  .use('/oauth2/jwks', Cors.oauth)
+  .use('/oauth2/revoke', Cors.oauth)
+  .use('/oauth2/token', Cors.oauth)
+  .use('/oauth2/userinfo', Cors.oauth)
+  // Every app's page reads the sign-in page's assets, which are public, and the chain list, which
+  // holds no RPC URL.
+  .use('/v1/auth/assets', Cors.oauth)
+  .use('/v1/chains', Cors.oauth)
+  .use('/v1/*', Cors.firstParty)
+  // Token endpoints authenticate each client, and server-to-server form posts carry no `Origin`.
+  // A device posts its device authorization request as a form, without `Origin`, too.
+  .use(except(['/device/code', '/oauth2/*'], csrf()))
+  // Before every route, so no validator reads an uncapped body.
+  .use('/device/code', BodyLimit.middleware)
+  .use('/i/*', BodyLimit.middleware)
+  .use('/oauth2/*', BodyLimit.middleware)
+  .use('/v1/*', BodyLimit.middleware)
+  .use(Auth.middleware)
+  .route('/', routes)
+  .get(
+    '/openapi.json',
+    OpenApi.describeRoute({
+      description: 'Returns this OpenAPI document.',
+      responses: {
+        200: {
+          content: { 'application/json': { schema: { type: 'object' } } },
+          description: 'The OpenAPI 3.1 document.',
+        },
+        ...OpenApi.errors([]),
+      },
+      tags: ['Reference'],
+    }),
+    async (c) =>
+      c.json(
+        await Timing.measure(c, OpenApi.document(api), 'OpenApi.document'),
+        200,
+      ),
+  )
+  // The reference runs only its pinned script, under the policy it sends.
+  .get(
+    '/docs',
+    OpenApi.describeRoute({
+      description: 'Renders this OpenAPI document as an API reference.',
+      responses: {
+        200: {
+          content: { 'text/html': { schema: { type: 'string' } } },
+          description: 'The API reference page.',
+        },
+        ...OpenApi.errors([]),
+      },
+      tags: ['Reference'],
+    }),
+    (c) => {
+      c.header('content-security-policy', OpenApi.referencePolicy)
+      return c.html(OpenApi.reference)
+    },
+  )
+  // A JSON API path of any version that matches no route, or a method that no route serves.
+  .all('/:version{v\\d+}/*', (c) =>
+    ErrorResponse.json(c, new ErrorResponse.UnknownEndpointError()),
+  )
+  // A path that no route serves is a page, unless its first segment is the API's.
+  .notFound(async (c) => {
+    if (serves(c.req.path))
+      return ErrorResponse.json(c, new ErrorResponse.UnknownEndpointError())
+    return Timing.measure(c, c.env.pages(c), 'page.render')
+  })
+  .onError(ErrorResponse.handle)
+
+/**
+ * Returns whether `path` is an API path: its first segment starts a route of {@link api}, such as
+ * `oauth2`, or is a version, such as `v2`. Each of {@link pages} is a page.
+ */
+function serves(path: string) {
+  if (pages.has(path)) return false
+  const segment = path.split('/')[1] ?? ''
+  return segments.has(segment) || /^v\d+$/.test(segment)
+}
+
+/** The pages whose first segment also starts a route, such as `/device` and `POST /device/code`. */
+const pages = new Set(['/device'])
+
+/** The first segment of each route path, such as `i`, `v1`, or `oauth2`. */
+const segments = new Set(
+  api.routes.flatMap((route) => {
+    const segment = route.path.split('/')[1] ?? ''
+    return segment && segment !== '*' && !segment.startsWith(':')
+      ? [segment]
+      : []
+  }),
+)

package/src/App.ts

@@ -0,0 +1,316 @@
+/**
+ * Tempo ID as a Cloudflare Worker, from the deployment's options.
+ * @module
+ */
+import handlers from '#app'
+import type * as Apps from './internal/Apps.js'
+import * as Cache from './internal/Cache.js'
+import * as ChainList from './internal/ChainList.js'
+import * as SigningKey from './internal/SigningKey.js'
+import type * as TestInbox from './internal/TestInbox.js'
+import type * as Wallet from './internal/Wallet.js'
+
+/** An option of `App.create` is absent or invalid. */
+export class InvalidOptionError extends Error {
+  override readonly name = 'App.InvalidOptionError'
+}
+
+/**
+ * Returns the Worker's handlers, which serve the pages, the API, and the cron triggers.
+ *
+ * ```ts
+ * import { env } from 'cloudflare:workers'
+ * import { App } from '@tempoxyz/id/worker'
+ *
+ * export default App.create({
+ *   db: env.HYPERDRIVE,
+ *   email: { binding: env.SEND_EMAIL, from: 'Tempo ID <noreply@id.example.com>' },
+ *   secret: env.SECRET,
+ *   url: 'https://id.example.com',
+ * })
+ * ```
+ *
+ * @throws {InvalidOptionError} When an option is absent or invalid, so the Worker fails to start.
+ */
+export function create(options: create.Options): create.ReturnType {
+  validate(options)
+
+  const {
+    apiUrls,
+    cacheTtl,
+    clientMetadata,
+    configurableAccounts,
+    db,
+    email,
+    privy,
+    rpcUrl,
+    rpcUrls,
+    secret,
+    signUpDomains,
+    testInbox,
+    url,
+    wallet,
+  } = options
+
+  // Each handler has a cache of its own, so two handlers in one Worker never share configuration. It
+  // holds no request's I/O, so the isolate's requests share it.
+  const cache = Cache.create({ ttl: (cacheTtl ?? 30) * 1000 })
+
+  // The built app reads its settings from the bindings under these names. Each name takes its
+  // option's value, or none, so no variable of the Worker with the same name reaches the app.
+  const bindings = (env: Record<string, unknown>) => ({
+    ...env,
+    __VOID_EMAIL_FROM: email.from,
+    CACHE: cache,
+    CLIENT_METADATA: clientMetadata,
+    CONFIGURABLE_ACCOUNTS: configurableAccounts?.join(','),
+    // Void's database client prefers `DATABASE_URL` to `HYPERDRIVE`, and reads only the connection
+    // string of either. A Hyperdrive binding's string is read for each request.
+    DATABASE_URL: db.connectionString,
+    HYPERDRIVE: undefined,
+    PRIVY_JWT_PRIVATE_KEY: privy?.privateKey,
+    RPC_URLS: rpcUrls,
+    SECRET: secret,
+    SEND_EMAIL: email.binding,
+    SIGN_UP_DOMAINS: signUpDomains?.join(','),
+    TEMPO_API_URLS: apiUrls,
+    TEMPO_RPC_URL: rpcUrl,
+    TEST_EMAIL_DOMAIN: testInbox?.domain,
+    TEST_INBOX: testInbox?.binding,
+    URL: url,
+    WALLET: wallet,
+  })
+
+  return {
+    fetch: (request, env, ctx) => handlers.fetch(request, bindings(env), ctx),
+    scheduled: (controller, env, ctx) =>
+      handlers.scheduled(controller, bindings(env), ctx),
+  }
+}
+
+export declare namespace create {
+  type Options = {
+    /**
+     * The Tempo API that values balances, as `rpcUrls` entries with the key as user information,
+     * such as `mainnet:4217=https://<key>@api.tempo.xyz`. Without an entry, `mainnet` and `testnet`
+     * read `https://api.tempo.xyz` without a key. `none` turns the API off.
+     */
+    apiUrls?: string | undefined
+    /**
+     * Seconds that each isolate caches configuration rows, such as realms and signing keys.
+     * Defaults to 30, and 0 turns it off. At most 300, the delay before a rotated key signs.
+     */
+    cacheTtl?: number | undefined
+    /**
+     * A service binding that serves the metadata documents of third-party apps, such as a test
+     * stand-in. Absent, each host serves its own.
+     */
+    clientMetadata?: Apps.fetchMetadata.Fetcher | undefined
+    /**
+     * The chains whose accounts are configurable (TIP-1107), by name: `mainnet`, `testnet`, or a
+     * name that `rpcUrls` lists, such as `local`. No other `rpcUrls` entry may serve the same chain.
+     * There, every new account is configurable, and a wallet.tempo passkey's account upgrades in
+     * place (TIP-1113). The chain's Tempo API in `apiUrls` sponsors each change when its URL holds a
+     * key. Absent, no account is configurable.
+     */
+    configurableAccounts?: readonly string[] | undefined
+    /**
+     * A Hyperdrive binding, such as `env.HYPERDRIVE`, or `{ connectionString }`. Run
+     * `tempo-id admin migrate` before the first deploy.
+     */
+    db: {
+      /** The Postgres connection string. */
+      connectionString: string
+    }
+    /** The email service that sends sign-in codes. */
+    email: {
+      /** The `send_email` binding, such as `env.SEND_EMAIL`. */
+      binding: EmailBinding
+      /** The sender of every email, such as `Tempo ID <noreply@id.example.com>`. */
+      from: string
+    }
+    /** The key that signs Privy's tokens. Absent, Privy owner keys sign nothing. */
+    privy?:
+      | {
+          /** The RS256 private key as PKCS #8 PEM, from a Worker secret. */
+          privateKey: string
+        }
+      | undefined
+    /**
+     * Replaces the RPC URL of each built-in chain that `rpcUrls` does not name, such as with a
+     * local Tempo node.
+     */
+    rpcUrl?: string | undefined
+    /**
+     * Extra chains for the `chain` parameter, as comma-separated `name:chainId=url` entries, such
+     * as `local:1337=http://localhost:8545`. An entry named `mainnet` or `testnet` replaces that
+     * chain's RPC URL. No response names a URL, since it can hold a key.
+     */
+    rpcUrls?: string | undefined
+    /**
+     * Signs cookies and encrypts the signing keys. A new secret makes every session and signing key
+     * unreadable.
+     */
+    secret: string
+    /**
+     * The lowercase domains where a sign-up creates an account, such as `['tempo.xyz']`. An existing
+     * account at any domain still signs in. Absent, every verified address can create an account.
+     */
+    signUpDomains?: readonly string[] | undefined
+    /** Receives the sign-in codes of a test domain instead of email, as on a preview. */
+    testInbox?:
+      | {
+          /** The inbox's `Capture` entrypoint, through a service binding. */
+          binding: TestInbox.Service
+          /** The test domain, such as `example.org`. Only domains that RFC 2606 reserves apply. */
+          domain: string
+        }
+      | undefined
+    /** Tempo ID's origin, such as `https://id.example.com`, and every token's `iss`. */
+    url: string
+    /**
+     * wallet.tempo's `Credentials` entrypoint, which links its passkeys at their first sign-in.
+     * Absent, only stored passkeys sign in.
+     */
+    wallet?: Wallet.Service | undefined
+  }
+
+  type ReturnType = {
+    /** Serves a request to the Worker. */
+    fetch: (
+      request: Request,
+      env: Record<string, unknown>,
+      ctx: unknown,
+    ) => Promise<Response>
+    /** Runs the cron triggers that the Worker's Wrangler config names. */
+    scheduled: (
+      controller: unknown,
+      env: Record<string, unknown>,
+      ctx: unknown,
+    ) => Promise<void>
+  }
+
+  type ErrorType = InvalidOptionError
+}
+
+/** A `send_email` binding, which sends one message. */
+export type EmailBinding = {
+  /** Sends `message`. */
+  send: (message: never) => Promise<unknown>
+}
+
+/** Throws when an option is absent or invalid, since bindings and secrets escape type checks. */
+function validate(options: create.Options) {
+  const {
+    cacheTtl,
+    configurableAccounts,
+    db,
+    email,
+    privy,
+    secret,
+    signUpDomains,
+    url,
+  } = options
+
+  if (
+    cacheTtl !== undefined &&
+    (typeof cacheTtl !== 'number' ||
+      !Number.isFinite(cacheTtl) ||
+      cacheTtl < 0 ||
+      // A cached signing key must expire before a rotation's new key starts to sign.
+      cacheTtl > SigningKey.publication)
+  )
+    throw new InvalidOptionError(
+      `Invalid \`cacheTtl\`: ${String(cacheTtl)}. Pass a number of seconds from 0 to ${SigningKey.publication}, such as 30.`,
+    )
+  // `db` can be a Hyperdrive binding, whose connection string is read only within a request.
+  if (typeof db !== 'object' || db === null)
+    throw new InvalidOptionError(
+      'Missing `db`. Pass a Hyperdrive binding, such as `env.HYPERDRIVE`, or `{ connectionString }`.',
+    )
+  if (typeof email?.binding?.send !== 'function')
+    throw new InvalidOptionError(
+      'Missing `email.binding`. Declare a `send_email` binding in the Wrangler config, and pass it, such as `env.SEND_EMAIL`.',
+    )
+  if (typeof email.from !== 'string' || !email.from.includes('@'))
+    throw new InvalidOptionError(
+      'Invalid `email.from`. Pass a sender with an address, such as `Tempo ID <noreply@id.example.com>`.',
+    )
+  if (typeof secret !== 'string' || !secret)
+    throw new InvalidOptionError(
+      'Missing `secret`. Set a Worker secret from `openssl rand -base64 32`, and pass it, such as `env.SECRET`.',
+    )
+
+  const parsed = typeof url === 'string' ? URL.parse(url) : null
+  if (
+    !parsed ||
+    !['http:', 'https:'].includes(parsed.protocol) ||
+    parsed.origin !== url.replace(/\/$/, '')
+  )
+    throw new InvalidOptionError(
+      'Invalid `url`. Pass the origin that serves Tempo ID, such as `https://id.example.com`, without a path.',
+    )
+
+  if (privy && !privy.privateKey)
+    throw new InvalidOptionError(
+      'Invalid `privy`. Pass `privateKey`, or leave `privy` out.',
+    )
+  // Each label is a hostname label, as the email validator requires, so every listed domain can
+  // sign up.
+  if (
+    signUpDomains &&
+    (signUpDomains.length === 0 ||
+      !signUpDomains.every((domain) => {
+        const labels = domain.split('.')
+        return (
+          labels.length > 1 &&
+          labels.every((label) =>
+            /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(label),
+          )
+        )
+      }))
+  )
+    throw new InvalidOptionError(
+      `Invalid \`signUpDomains\`: ${JSON.stringify(signUpDomains)}. Pass lowercase domains, such as \`['tempo.xyz']\`, or leave \`signUpDomains\` out.`,
+    )
+  if (configurableAccounts) configurable(options)
+}
+
+/**
+ * Checks `configurableAccounts`: each chain resolves to a Tempo chain, and no other `rpcUrls` entry
+ * serves its ID, since a key authorization names its chain by ID alone.
+ */
+function configurable(options: create.Options) {
+  const { configurableAccounts, rpcUrl, rpcUrls } = options
+  const names = configurableAccounts ?? []
+  if (names.length === 0)
+    throw new InvalidOptionError(
+      'Invalid `configurableAccounts`: the list is empty. Name a chain, such as `local`, or leave `configurableAccounts` out.',
+    )
+
+  const resolved = ChainList.configurable({
+    rpcUrl,
+    rpcUrls,
+    value: names.join(','),
+  })
+  for (const name of names)
+    if (!resolved.some((entry) => entry.name === name))
+      throw new InvalidOptionError(
+        `Invalid \`configurableAccounts\`: \`${name}\` is neither \`mainnet\`, \`testnet\`, nor an \`rpcUrls\` entry. Name a listed chain.`,
+      )
+
+  const listed = [
+    { chainId: ChainList.ids.mainnet, name: 'mainnet' },
+    { chainId: ChainList.ids.testnet, name: 'testnet' },
+    ...ChainList.list({ value: rpcUrls }),
+  ]
+  for (const entry of resolved) {
+    const shared = listed.find(
+      (other) => other.chainId === entry.chainId && !names.includes(other.name),
+    )
+    if (shared)
+      throw new InvalidOptionError(
+        `Invalid \`configurableAccounts\`: \`${entry.name}\` and \`${shared.name}\` serve chain ${entry.chainId}. Remove \`${shared.name}\` from \`rpcUrls\`, or name it too.`,
+      )
+  }
+}