@tempoxyz/id 0.0.0-stage → 0.0.1

package/src/cli/Admin.ts

@@ -0,0 +1,74 @@
+/**
+ * What the `tempo-id admin` commands share. It imports only incur, since incur imports every
+ * command at startup.
+ * @module
+ */
+import { z } from 'incur'
+
+/** The variables that name the database. */
+export const env = z.object({
+  DATABASE_SCHEMA: z
+    .string()
+    .optional()
+    .describe(
+      "Postgres schema of the tables, such as a preview's pr_141. Defaults to public.",
+    ),
+  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 a command without its optional peers. */
+export const missingPeers = {
+  code: 'missing_peer',
+  message:
+    'Missing peer dependencies. Install better-auth, @better-auth/cimd, @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 of the app and signing key commands, or returns `undefined` without its peers.
+ */
+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 of the realm commands, or returns `undefined` without its optional peers. */
+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` if 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,27 @@
+/**
+ * What the `tempo-id admin apps` and `admin rotate-key` commands share. Its peers are optional, 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 code and message of a refusal from `Apps` or `SigningKey`, or else `undefined`. */
+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,41 @@
+/**
+ * The `tempo-id` CLI. incur routes each file in `commands/` by its path, such as
+ * `commands/admin/migrate.ts` for `tempo-id admin migrate`. Only `login`, `logout`, `whoami`, and
+ * `v1` 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 the `package.json` 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 the `v1` group of `options.v1`.
+ */
+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,119 @@
+/**
+ * Writes a Tempo ID Worker project, as `apps/id` holds it: the Worker and its Wrangler config.
+ * @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 files into `options.root`, except existing ones, and 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'",
+      "import { env } from 'cloudflare:workers'",
+      '',
+      'export default App.create({',
+      '  db: env.HYPERDRIVE,',
+      `  email: { binding: env.SEND_EMAIL, from: ${JSON.stringify(from)} },`,
+      '  secret: env.SECRET,',
+      `  url: ${JSON.stringify(url)},`,
+      '})',
+      '',
+    ].join('\n'),
+    'wrangler.jsonc': [
+      '{',
+      '  "$schema": "node_modules/wrangler/config-schema.json",',
+      `  "name": ${JSON.stringify(name)},`,
+      '  "main": "worker.ts",',
+      '  "compatibility_date": "2026-02-24",',
+      "  // Third-party apps' metadata documents, which every fetch reaches by its public path.",
+      '  "compatibility_flags": ["global_fetch_strictly_public", "nodejs_compat"],',
+      "  // The app's client scripts and styles, from the package. Files under `/assets/` skip the Worker.",
+      '  "assets": {',
+      '    "binding": "ASSETS",',
+      '    "directory": "node_modules/@tempoxyz/id/dist/app/client",',
+      '    "run_worker_first": ["/**", "!/assets/*"],',
+      '  },',
+      '  // 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",',
+      '    },',
+      '  ],',
+      '  // A smaller bundle starts each isolate sooner.',
+      '  "keep_names": false,',
+      '  "minify": true,',
+      '  // 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 * * * *"] },',
+      '  "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,49 @@
+/**
+ * What the `tempo-id admin realms` commands share. Its peers are optional, 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`
+ * after the command.
+ */
+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 code and message of 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 }
+}

package/src/cli/Session.ts

@@ -0,0 +1,290 @@
+/**
+ * The CLI's stored session from `tempo-id login`, in `id/credentials.json` under `TEMPO_HOME`. Only
+ * the current user can read the file.
+ * @module
+ */
+import * as Fs from 'node:fs/promises'
+import * as Os from 'node:os'
+import * as Path from 'node:path'
+import * as Actions from '../client/Actions.js'
+import * as Auth from '../client/Auth.js'
+import type * as Authorization from '../client/Authorization.js'
+import * as Key from '../client/Key.js'
+
+/** A session as `Actions.device.authorize` returns it, without its Viem account. */
+export type Session = Omit<Authorization.Authorization, 'account'> & {
+  /** The origin of the deployment that issued the tokens. */
+  url: string
+}
+
+/** The client ID of Tempo ID's own device app. */
+export const clientId = 'tempo-cli'
+
+/** Returns the `tempo-cli` client of Tempo ID at `url`. */
+export function auth(options: auth.Options) {
+  return Auth.create({ clientId, url: options.url })
+}
+
+export declare namespace auth {
+  type Options = {
+    /** Tempo ID's origin. Defaults to `https://id.tempo.xyz`. */
+    url?: string | undefined
+  }
+}
+
+/**
+ * Returns the stored session, and refreshes its access token if it expires within 30 seconds.
+ * Returns `undefined` if no session is usable or the refresh fails. A session from another
+ * deployment is not usable, so its tokens never reach `url`.
+ */
+export async function get(options: get.Options): Promise<Session | undefined> {
+  const saved = await usable(options)
+  if (!saved) return undefined
+  if (saved.expiresAt - 30_000 > Date.now()) return saved
+
+  // Issuers revoke every refresh token of the app for the user when one is sent twice, so one
+  // process at a time refreshes, and it reads the file again once it holds the lock.
+  return await locked(options, async () => {
+    const current = await usable(options)
+    if (!current) return undefined
+    if (current.expiresAt - 30_000 > Date.now()) return current
+    if (!current.refreshToken) return undefined
+
+    const tokens = await Actions.refresh(auth(options), {
+      refreshToken: current.refreshToken,
+    }).catch(() => undefined)
+    if (!tokens) return undefined
+    return await save({ ...options, session: { ...current, ...tokens } })
+  })
+}
+
+export declare namespace get {
+  type Options = {
+    /** The folder that holds the session. Defaults to `~/.tempo`. */
+    home?: string | undefined
+    /** Tempo ID's origin. Defaults to `https://id.tempo.xyz`. */
+    url?: string | undefined
+  }
+}
+
+/**
+ * Starts the device grant with a new access key, and returns the code and `wait`. Once the user
+ * approves, `wait` stores the new session, revokes the refresh token of the replaced one, and
+ * returns it. It rejects with `Auth.RequestError` if the user denies the code or it expires.
+ */
+export async function login(options: login.Options) {
+  const client = auth(options)
+  const device = await Actions.device.authorize(client)
+  return {
+    ...device,
+    async wait() {
+      const { account: _, ...authorization } = await device.wait()
+      return await locked(options, async () => {
+        const replaced = await readSession(options)
+        // The new session is stored first, so a failed write keeps the replaced one usable.
+        const session = await save({
+          home: options.home,
+          session: { ...authorization, url: new URL(client.url).origin },
+        })
+        // The replaced session's refresh token goes only to the deployment that issued it.
+        if (
+          replaced.status === 'found' &&
+          replaced.session.refreshToken &&
+          replaced.session.url
+        )
+          await revoke({
+            token: replaced.session.refreshToken,
+            url: replaced.session.url,
+          })
+        return session
+      })
+    },
+  }
+}
+
+export declare namespace login {
+  type Options = get.Options
+}
+
+/**
+ * Revokes the stored refresh token at the deployment that issued it, and deletes the session either
+ * way. Returns `false` if the token is not revoked, such as without a network.
+ */
+export async function remove(options: remove.Options) {
+  return await locked(options, async () => {
+    const read = await readSession(options)
+    const revoked = await (async () => {
+      if (read.status === 'missing') return true
+      if (read.status === 'invalid') return false
+      const { refreshToken, url } = read.session
+      if (!refreshToken) return true
+      // A session stored before its origin was recorded names no deployment to revoke it at.
+      if (!url) return false
+      return await revoke({ token: refreshToken, url })
+    })()
+    await Fs.rm(file(options), { force: true })
+    return revoked
+  })
+}
+
+export declare namespace remove {
+  type Options = get.Options
+}
+
+/**
+ * Stores `session`, readable only by the current user, and returns it. One rename replaces the
+ * earlier session, so a failed write keeps it.
+ */
+export async function save(options: save.Options) {
+  const path = file(options)
+  await Fs.mkdir(Path.dirname(path), { mode: 0o700, recursive: true })
+  const temporary = `${path}.${crypto.randomUUID()}.tmp`
+  try {
+    await Fs.writeFile(temporary, JSON.stringify(options.session), {
+      flag: 'wx',
+      mode: 0o600,
+    })
+    await Fs.rename(temporary, path)
+  } catch (error) {
+    await Fs.rm(temporary, { force: true })
+    throw error
+  }
+  return options.session
+}
+
+export declare namespace save {
+  type Options = {
+    /** The folder that holds the session. Defaults to `~/.tempo`. */
+    home?: string | undefined
+    /** The session to store. */
+    session: Session
+  }
+}
+
+/**
+ * Returns the user's email and the Tempo Account of the session's access key, or `undefined`
+ * without a session.
+ */
+export async function whoami(options: whoami.Options) {
+  const session = await get(options)
+  if (!session) return undefined
+  // The UserInfo endpoint accepts the access token, as any Tempo API does.
+  const user = await Actions.oauth.userInfo(auth(options), {
+    accessToken: session.accessToken,
+  })
+  return { account: session.key.account, email: user.email }
+}
+
+export declare namespace whoami {
+  type Options = get.Options
+}
+
+/** Returns the path of the session file under `home`, or `~/.tempo` if `home` is unset or empty. */
+function file(options: { home?: string | undefined }) {
+  return Path.join(
+    options.home || Path.join(Os.homedir(), '.tempo'),
+    'id',
+    'credentials.json',
+  )
+}
+
+/**
+ * Runs `fn` while this process holds the session's lock file. It takes over a lock older than
+ * {@link lockLifetime}.
+ */
+async function locked<T>(
+  options: { home?: string | undefined },
+  fn: () => Promise<T>,
+): Promise<T> {
+  const path = `${file(options)}.lock`
+  await Fs.mkdir(Path.dirname(path), { mode: 0o700, recursive: true })
+  for (;;) {
+    const handle = await Fs.open(path, 'wx', 0o600).catch((error: unknown) => {
+      if ((error as { code?: unknown }).code === 'EEXIST') return undefined
+      throw error
+    })
+    if (handle) {
+      await handle.close()
+      break
+    }
+
+    const stat = await Fs.stat(path).catch(() => undefined)
+    if (stat && Date.now() - stat.mtimeMs > lockLifetime)
+      await Fs.rm(path, { force: true })
+    else await new Promise((resolve) => setTimeout(resolve, 50))
+  }
+
+  try {
+    return await fn()
+  } finally {
+    await Fs.rm(path, { force: true })
+  }
+}
+
+/** Milliseconds that a lock holds at most, which covers a refresh or a revocation. */
+const lockLifetime = 30_000
+
+/**
+ * Reads the stored session. Returns `missing` without a file, and `invalid` for a file that holds
+ * no JSON object.
+ */
+async function readSession(options: { home?: string | undefined }) {
+  type Result =
+    | { status: 'found'; session: Session }
+    | { status: 'invalid' }
+    | { status: 'missing' }
+  return await Fs.readFile(file(options), 'utf8').then(
+    (text): Result => {
+      const session = (() => {
+        try {
+          return JSON.parse(text) as unknown
+        } catch {
+          return undefined
+        }
+      })()
+      if (typeof session !== 'object' || !session) return { status: 'invalid' }
+      return { session: session as Session, status: 'found' }
+    },
+    (error: unknown): Result => {
+      if ((error as { code?: unknown }).code === 'ENOENT')
+        return { status: 'missing' }
+      return { status: 'invalid' }
+    },
+  )
+}
+
+/**
+ * Returns the stored session, or `undefined` if another deployment issued it, or it has no user,
+ * access token, or unexpired access key.
+ */
+async function usable(options: get.Options) {
+  const read = await readSession(options)
+  const saved = read.status === 'found' ? read.session : undefined
+  if (
+    saved?.url !== new URL(auth(options).url).origin ||
+    !saved.user ||
+    !saved.key?.keyAuthorization ||
+    !saved.accessToken ||
+    Key.expired(saved.key)
+  )
+    return undefined
+  return saved
+}
+
+/**
+ * Revokes `token` at the RFC 7009 endpoint of `url`, and returns whether it succeeded within 10
+ * seconds.
+ */
+async function revoke(options: { token: string; url: string }) {
+  const response = await fetch(new URL('/oauth2/revoke', options.url), {
+    body: new URLSearchParams({
+      client_id: clientId,
+      token: options.token,
+      token_type_hint: 'refresh_token',
+    }),
+    method: 'POST',
+    signal: AbortSignal.timeout(10_000),
+  }).catch(() => undefined)
+  await response?.body?.cancel()
+  return response?.ok ?? false
+}

package/src/cli/User.ts

@@ -0,0 +1,40 @@
+/**
+ * What the `login`, `logout`, and `whoami` commands share. incur imports every command at startup,
+ * so this module imports no optional peer.
+ * @module
+ */
+import { z } from 'incur'
+import * as Admin from './Admin.js'
+
+/** The variables that name Tempo ID and the folder of the stored session. */
+export const env = z.object({
+  TEMPO_HOME: z
+    .string()
+    .optional()
+    .describe(
+      'The folder that holds the session, in id/credentials.json. Defaults to ~/.tempo.',
+    ),
+  TEMPO_ID_URL: z
+    .url()
+    .optional()
+    .describe("Tempo ID's origin. Defaults to https://id.tempo.xyz."),
+})
+
+/** The error for a command without Viem, which the access key needs. */
+export const missingPeers = {
+  code: 'missing_peer',
+  message:
+    'Missing peer dependency. Install viem to run login, logout, and whoami.',
+} as const
+
+/** The error for a command without a session. */
+export const signedOut = {
+  code: 'signed_out',
+  message: 'Not signed in. Run `tempo-id login`.',
+} as const
+
+/** Loads the session module, or returns `undefined` without Viem, the client's optional peer. */
+export async function loadSession() {
+  // A dynamic import, since the module needs an optional peer that the other commands do not.
+  return await Admin.optional(import('./Session.js'))
+}