@tempoxyz/id 0.0.0-stage → 0.0.0

package/src/cli/Session.ts

@@ -0,0 +1,239 @@
+/**
+ * The CLI's stored session: the signed-in user, the tokens, and the access key that `tempo-id
+ * login` receives through Tempo ID's device grant as the `tempo-cli` app. The session lives in
+ * `id/credentials.json` under `TEMPO_HOME`, in a file only the current user can read.
+ * @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 stored session, as `Actions.device.authorize` returns it, without its Viem account, and with
+ * the origin of the deployment that issued it.
+ */
+export type Session = Omit<Authorization.Authorization, 'account'> & {
+  /** The origin of the Tempo ID deployment that issued the tokens. */
+  url: string
+}
+
+/** The client ID of Tempo ID's own device app, which every CLI shares. */
+export const clientId = 'tempo-cli'
+
+/** Returns the client of Tempo ID at `url`, or at `https://id.tempo.xyz`, as `tempo-cli`. */
+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, with its access token refreshed when it expires within 30 seconds.
+ * Returns `undefined` without a session, for a session without a user or an access key, or for one
+ * whose key expired or whose refresh fails, so the user signs in again. A session that another
+ * deployment issued also returns `undefined`, so its tokens never reach the deployment at `url`.
+ */
+export async function get(options: get.Options): Promise<Session | undefined> {
+  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
+  if (saved.expiresAt - 30_000 > Date.now()) return saved
+  if (!saved.refreshToken) return undefined
+
+  const tokens = await Actions.refresh(auth(options), {
+    refreshToken: saved.refreshToken,
+  }).catch(() => undefined)
+  if (!tokens) return undefined
+  return await save({ ...options, session: { ...saved, ...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 Tempo ID's device grant with a new access key, and returns the code to show and `wait`.
+ * `wait` resolves once the user approves the code in a browser, stores the new session, revokes the
+ * refresh token of the session that it replaced, and returns the new session. It rejects with
+ * `Auth.RequestError` when the user denies the code or the code 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()
+      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 session's refresh token at the deployment that issued it, and deletes the
+ * session. A failed revocation, such as without a network, or a file that holds no readable
+ * session, still deletes it, and returns `false`.
+ */
+export async function remove(options: remove.Options) {
+  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. The session replaces the
+ * stored one in one rename, so a failed write leaves the earlier session as it was.
+ */
+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 signed-in user's email, from Tempo ID's UserInfo endpoint, and the Tempo Account that
+ * the session's access key acts for. Returns `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's file under `home`, or under `~/.tempo` for an unset or empty `home`. */
+function file(options: { home?: string | undefined }) {
+  return Path.join(
+    options.home || Path.join(Os.homedir(), '.tempo'),
+    'id',
+    'credentials.json',
+  )
+}
+
+/**
+ * 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' }
+    },
+  )
+}
+
+/**
+ * Revokes `token` at the revocation endpoint (RFC 7009) of the deployment at `url`, and returns
+ * whether it succeeded. A deployment that does not respond within 10 seconds counts as a failure.
+ */
+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,45 @@
+/**
+ * What the `login`, `logout`, and `whoami` commands share: the variables that name Tempo ID and the
+ * session's folder, and the loader of the session module. incur imports every command when the CLI
+ * starts, so this module imports only incur, and the session module loads only when these commands
+ * run.
+ * @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 creates and signs with the access key. */
+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 that needs a session, and finds none. */
+export const signedOut = {
+  code: 'signed_out',
+  message: 'Not signed in. Run `tempo-id login`.',
+} as const
+
+/**
+ * Loads the session module, or returns `undefined` when Viem, the client's optional peer, is not
+ * installed.
+ */
+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'))
+}

package/src/cli/V1.ts

@@ -0,0 +1,57 @@
+/**
+ * The `tempo-id v1` command group: one command per `/v1` route of a Tempo ID deployment, which incur
+ * generates from the deployment's OpenAPI document in its namespace mode, such as `tempo-id v1 auth
+ * providers` for `GET /v1/auth/providers`. The commands send no session, so the routes that need
+ * one refuse them with status 401.
+ * @module
+ */
+/**
+ * Fetches the OpenAPI document of the deployment at `url`, and returns the `v1` group's definition.
+ * The document keeps only the `/v1` routes, without the `/v1` prefix, which the group's name and
+ * base path supply. Rejects when the deployment does not respond within 10 seconds, or responds
+ * with an error.
+ */
+export async function load(options: load.Options) {
+  const { url } = options
+  const fetch = options.fetch ?? globalThis.fetch
+  const response = await fetch(new URL('/openapi.json', url), {
+    signal: AbortSignal.timeout(10_000),
+  })
+  if (!response.ok)
+    throw new Error(
+      `Tempo ID at ${url} responded to /openapi.json with ${response.status}.`,
+    )
+  const document = (await response.json()) as {
+    paths?: Record<string, unknown> | undefined
+  }
+  const paths = Object.fromEntries(
+    Object.entries(document.paths ?? {}).flatMap(([path, item]) =>
+      path.startsWith('/v1/') ? [[path.slice('/v1'.length), item]] : [],
+    ),
+  )
+  return {
+    basePath: '/v1',
+    description: "Call Tempo ID's /v1 API, one command per route.",
+    // Each request goes to the deployment, whatever origin incur builds it with. The path is set on
+    // the deployment's URL, never resolved against it, so a path argument such as `//host` keeps
+    // the deployment's origin.
+    fetch: (request: Request) => {
+      const source = new URL(request.url)
+      const target = new URL(url)
+      target.pathname = source.pathname
+      target.search = source.search
+      return fetch(new Request(target, request))
+    },
+    openapi: { ...document, paths },
+    openapiConfig: { mode: 'namespace' as const },
+  }
+}
+
+export declare namespace load {
+  type Options = {
+    /** The fetch that reaches the deployment. Defaults to the global `fetch`. */
+    fetch?: typeof globalThis.fetch | undefined
+    /** Tempo ID's origin. */
+    url: string
+  }
+}

package/src/cli/bin.ts

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+/**
+ * Runs the `tempo-id` CLI with the process's arguments. Only `v1` and `--mcp` load Tempo ID's
+ * OpenAPI document, so every other command starts without the network. When the deployment does not
+ * respond, a `v1` command exits with code 1, and an MCP server serves the other commands. Both warn
+ * on stderr.
+ * @module
+ */
+import * as Cli from './Cli.js'
+import * as V1 from './V1.js'
+
+const argv = process.argv.slice(2)
+const url = process.env.TEMPO_ID_URL ?? 'https://id.tempo.xyz'
+/** incur's global options that take a value, which the command follows. */
+const valued = [
+  '--filter-output',
+  '--format',
+  '--token-limit',
+  '--token-offset',
+]
+// The command is the first argument that is no option, since global options, such as
+// `--format json`, can come before it. An argument of another command can be `v1` too.
+const command = (() => {
+  for (let index = 0; index < argv.length; index++) {
+    const entry = argv[index]!
+    if (!entry.startsWith('-')) return entry
+    if (valued.includes(entry)) index++
+  }
+  return undefined
+})()
+const group = command === 'v1'
+const v1 = await (async () => {
+  if (!group && !argv.includes('--mcp')) return undefined
+  return await V1.load({ url }).catch((error: unknown) => {
+    process.stderr.write(
+      `The v1 commands are unavailable: ${error instanceof Error ? error.message : String(error)}\n`,
+    )
+    return null
+  })
+})()
+
+// A `v1` command fails without its group. An MCP server serves the other commands.
+if (v1 === null && group) process.exitCode = 1
+else await Cli.create({ v1: v1 ?? undefined }).serve()

package/src/cli/commands/admin/apps/create.ts

@@ -0,0 +1,101 @@
+/**
+ * `tempo-id admin apps create`: registers an OAuth app. The output holds the client secret, which no
+ * later command returns.
+ * @module
+ */
+import { Cli, z } from 'incur'
+import * as Admin from '../../../Admin.js'
+
+export default Cli.command({
+  description:
+    'Register an OAuth app. The output holds its client secret, which no later command returns.',
+  env: Admin.env.extend({
+    TEMPO_ID_CLIENT_SECRET: z
+      .string()
+      .optional()
+      .describe(
+        'Client secret to keep with --secret, such as one that another deployment issued. No flag takes it, so it stays out of the shell history.',
+      ),
+  }),
+  // Hidden from MCP clients, as is every `admin apps` command, since the group returns client secrets.
+  mcp: false,
+  options: Admin.options.extend({
+    clientId: z
+      .string()
+      .optional()
+      .describe(
+        'Client ID to keep, such as one that another deployment issued. Defaults to a random ID.',
+      ),
+    device: z
+      .boolean()
+      .default(false)
+      .describe(
+        'Sign in through the device grant instead of a redirect, as a CLI does. A device app needs no redirect URI.',
+      ),
+    name: z.string().describe('Display name, which the approval page shows.'),
+    native: z
+      .boolean()
+      .default(false)
+      .describe('Register a mobile app instead of a web app.'),
+    postLogoutRedirectUri: z
+      .array(z.string())
+      .default([])
+      .describe(
+        'URI that the app returns to after it ends the session. Repeat the flag for each URI.',
+      ),
+    redirectUri: z
+      .array(z.string())
+      .default([])
+      .describe(
+        'Redirect URI. Repeat the flag for each URI, in each environment. Every app but a device app needs one.',
+      ),
+    secret: z
+      .boolean()
+      .default(false)
+      .describe(
+        'Issue a client secret, for an app with a backend. TEMPO_ID_CLIENT_SECRET sets it instead of a new one.',
+      ),
+    sign: z
+      .boolean()
+      .default(false)
+      .describe(
+        'Grant the tempo-id:sign scope, which permits the app to bind its own challenges.',
+      ),
+    skipConsent: z
+      .boolean()
+      .default(false)
+      .describe('Skip the approval page for requests without a key.'),
+  }),
+  async run(c) {
+    const connectionString = c.options.databaseUrl ?? c.env.DATABASE_URL
+    if (!connectionString) return c.error(Admin.missingDatabaseUrl)
+
+    const Apps = await Admin.loadApps()
+    if (!Apps) return c.error(Admin.missingPeers)
+
+    const client = Apps.connect({ connectionString })
+    try {
+      return await Apps.Apps.create(client.db, {
+        clientId: c.options.clientId,
+        // The variable applies only with `--secret`, so an exported one never makes an app confidential.
+        clientSecret: c.options.secret
+          ? c.env.TEMPO_ID_CLIENT_SECRET
+          : undefined,
+        device: c.options.device,
+        name: c.options.name,
+        postLogoutRedirectUris: c.options.postLogoutRedirectUri,
+        redirectUris: c.options.redirectUri,
+        secret: c.options.secret,
+        sign: c.options.sign,
+        skipConsent: c.options.skipConsent,
+        type: c.options.native ? 'native' : 'web',
+      })
+    } catch (error) {
+      const refusal = Apps.error(error)
+      if (refusal) return c.error(refusal)
+      throw error
+    } finally {
+      await client.end()
+    }
+  },
+})

package/src/cli/commands/admin/apps/delete.ts

@@ -0,0 +1,38 @@
+/**
+ * `tempo-id admin apps delete`: removes an OAuth app, with its consents, tokens, and realms.
+ * @module
+ */
+import { Cli, z } from 'incur'
+import * as Admin from '../../../Admin.js'
+
+export default Cli.command({
+  args: z.object({
+    clientId: z.string().describe("OAuth app's client ID."),
+  }),
+  description: 'Remove an app, with its consents, tokens, and realms.',
+  env: Admin.env,
+  // Hidden from MCP clients, as is every `admin apps` command, since the group returns client secrets.
+  mcp: false,
+  options: Admin.options,
+  async run(c) {
+    const connectionString = c.options.databaseUrl ?? c.env.DATABASE_URL
+    if (!connectionString) return c.error(Admin.missingDatabaseUrl)
+
+    const Apps = await Admin.loadApps()
+    if (!Apps) return c.error(Admin.missingPeers)
+
+    const client = Apps.connect({ connectionString })
+    try {
+      const app = await Apps.Apps.remove(client.db, {
+        clientId: c.args.clientId,
+      })
+      return { removed: app.clientId }
+    } catch (error) {
+      const refusal = Apps.error(error)
+      if (refusal) return c.error(refusal)
+      throw error
+    } finally {
+      await client.end()
+    }
+  },
+})

package/src/cli/commands/admin/apps/index.ts

@@ -0,0 +1,15 @@
+/** `tempo-id admin apps`: the commands that register and change OAuth apps. @module */
+import { Cli } from 'incur'
+
+export default Cli.command({
+  description: 'Manage OAuth apps, their redirect URIs, and their scopes.',
+  // Hidden from MCP clients, as is every `admin apps` command, since the group returns client secrets.
+  mcp: false,
+  run(c) {
+    return c.error({
+      code: 'missing_command',
+      message:
+        'Missing command. Run `tempo-id admin apps --help` to list the commands.',
+    })
+  },
+})

package/src/cli/commands/admin/apps/list.ts

@@ -0,0 +1,25 @@
+/** `tempo-id admin apps list`: lists every OAuth app, oldest first. @module */
+import { Cli } from 'incur'
+import * as Admin from '../../../Admin.js'
+
+export default Cli.command({
+  description: 'List every OAuth app, oldest first.',
+  env: Admin.env,
+  // Hidden from MCP clients, as is every `admin apps` command, since the group returns client secrets.
+  mcp: false,
+  options: Admin.options,
+  async run(c) {
+    const connectionString = c.options.databaseUrl ?? c.env.DATABASE_URL
+    if (!connectionString) return c.error(Admin.missingDatabaseUrl)
+
+    const Apps = await Admin.loadApps()
+    if (!Apps) return c.error(Admin.missingPeers)
+
+    const client = Apps.connect({ connectionString })
+    try {
+      return { apps: await Apps.Apps.list(client.db) }
+    } finally {
+      await client.end()
+    }
+  },
+})

package/src/cli/commands/admin/apps/rotate-secret.ts

@@ -0,0 +1,47 @@
+/**
+ * `tempo-id admin apps rotate-secret`: replaces an OAuth app's client secret. The earlier secret
+ * stops working at once, and the output holds the new one.
+ * @module
+ */
+import { Cli, z } from 'incur'
+import * as Admin from '../../../Admin.js'
+
+export default Cli.command({
+  args: z.object({
+    clientId: z.string().describe("OAuth app's client ID."),
+  }),
+  description:
+    "Replace an app's client secret. The earlier secret stops working at once.",
+  env: Admin.env.extend({
+    TEMPO_ID_CLIENT_SECRET: z
+      .string()
+      .optional()
+      .describe(
+        'New client secret, such as one that another deployment issued. No flag takes it, so it stays out of the shell history. Defaults to a random secret.',
+      ),
+  }),
+  // Hidden from MCP clients, as is every `admin apps` command, since the group returns client secrets.
+  mcp: false,
+  options: Admin.options,
+  async run(c) {
+    const connectionString = c.options.databaseUrl ?? c.env.DATABASE_URL
+    if (!connectionString) return c.error(Admin.missingDatabaseUrl)
+
+    const Apps = await Admin.loadApps()
+    if (!Apps) return c.error(Admin.missingPeers)
+
+    const client = Apps.connect({ connectionString })
+    try {
+      return await Apps.Apps.rotateSecret(client.db, {
+        clientId: c.args.clientId,
+        clientSecret: c.env.TEMPO_ID_CLIENT_SECRET,
+      })
+    } catch (error) {
+      const refusal = Apps.error(error)
+      if (refusal) return c.error(refusal)
+      throw error
+    } finally {
+      await client.end()
+    }
+  },
+})