@tempoxyz/id 0.0.0-stage → 0.0.0

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

@@ -0,0 +1,86 @@
+/**
+ * `tempo-id admin apps update`: changes an OAuth app. A value left out stays.
+ * @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:
+    "Change an app's name, redirect URIs, post-logout redirect URIs, or scopes. A value left out stays.",
+  env: Admin.env,
+  // Hidden from MCP clients, as is every `admin apps` command, since the group returns client secrets.
+  mcp: false,
+  options: Admin.options.extend({
+    clearPostLogoutRedirectUris: z
+      .boolean()
+      .default(false)
+      .describe(
+        'Remove every post-logout redirect URI. Logout then ends the session without a redirect.',
+      ),
+    name: z.string().optional().describe('Display name.'),
+    postLogoutRedirectUri: z
+      .array(z.string())
+      .optional()
+      .describe(
+        'URI that the app returns to after it ends the session. Repeat the flag for each URI. The URIs replace the earlier ones.',
+      ),
+    redirectUri: z
+      .array(z.string())
+      .optional()
+      .describe(
+        'Redirect URI. Repeat the flag for each URI. The URIs replace the earlier ones.',
+      ),
+    sign: z
+      .boolean()
+      .optional()
+      .describe('Grant the tempo-id:sign scope, or remove it with --no-sign.'),
+    skipConsent: z
+      .boolean()
+      .optional()
+      .describe(
+        'Skip the approval page for requests without a key, or show it with --no-skip-consent.',
+      ),
+  }),
+  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)
+
+    if (
+      c.options.clearPostLogoutRedirectUris &&
+      c.options.postLogoutRedirectUri
+    )
+      return c.error({
+        code: 'invalid_app',
+        message:
+          'Invalid options: --clear-post-logout-redirect-uris and --post-logout-redirect-uri conflict. Pass one of them.',
+      })
+
+    const client = Apps.connect({ connectionString })
+    try {
+      const app = await Apps.Apps.update(client.db, {
+        clientId: c.args.clientId,
+        name: c.options.name,
+        postLogoutRedirectUris: c.options.clearPostLogoutRedirectUris
+          ? []
+          : c.options.postLogoutRedirectUri,
+        redirectUris: c.options.redirectUri,
+        sign: c.options.sign,
+        skipConsent: c.options.skipConsent,
+      })
+      return { app }
+    } catch (error) {
+      const refusal = Apps.error(error)
+      if (refusal) return c.error(refusal)
+      throw error
+    } finally {
+      await client.end()
+    }
+  },
+})

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

@@ -0,0 +1,14 @@
+/** `tempo-id admin`: the commands that reach a Tempo ID database directly. @module */
+import { Cli } from 'incur'
+
+export default Cli.command({
+  description: 'Operate a Tempo ID database.',
+  mcp: false,
+  run(c) {
+    return c.error({
+      code: 'missing_command',
+      message:
+        'Missing command. Run `tempo-id admin --help` to list the commands.',
+    })
+  },
+})

package/src/cli/commands/admin/migrate.ts

@@ -0,0 +1,16 @@
+/** `tempo-id admin migrate`: applies the package's pending migrations. @module */
+import { Cli } from 'incur'
+import * as Migrations from '../../../internal/Migrations.js'
+import * as Admin from '../../Admin.js'
+
+export default Cli.command({
+  description: "Apply the package's pending migrations.",
+  env: Admin.env,
+  mcp: false,
+  options: Admin.options,
+  async run(c) {
+    const connectionString = c.options.databaseUrl ?? c.env.DATABASE_URL
+    if (!connectionString) return c.error(Admin.missingDatabaseUrl)
+    return await Migrations.apply({ connectionString })
+  },
+})

package/src/cli/commands/admin/realms/add.ts

@@ -0,0 +1,40 @@
+/** `tempo-id admin realms add`: adds a realm, a new set of Tempo Accounts. @module */
+import { Cli, z } from 'incur'
+import * as Admin from '../../../Admin.js'
+
+export default Cli.command({
+  args: z.object({
+    id: z
+      .string()
+      .describe('Realm ID, in lowercase kebab case, such as tempo-cash.'),
+  }),
+  description:
+    'Add a realm. Set its owner configurations, such as its Privy app, with their own commands.',
+  env: Admin.env,
+  mcp: false,
+  options: Admin.options.extend({
+    name: z.string().describe('Display name, such as "Tempo Cash".'),
+  }),
+  async run(c) {
+    const connectionString = c.options.databaseUrl ?? c.env.DATABASE_URL
+    if (!connectionString) return c.error(Admin.missingDatabaseUrl)
+
+    const Realms = await Admin.loadRealms()
+    if (!Realms) return c.error(Admin.missingPeers)
+
+    const client = Realms.connect({ connectionString })
+    try {
+      const realm = await Realms.Realm.add(client.db, {
+        id: c.args.id,
+        name: c.options.name,
+      })
+      return { realm }
+    } catch (error) {
+      const refusal = Realms.error(error)
+      if (refusal) return c.error(refusal)
+      throw error
+    } finally {
+      await client.end()
+    }
+  },
+})

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

@@ -0,0 +1,14 @@
+/** `tempo-id admin realms`: the commands that define realms and the realms of each app. @module */
+import { Cli } from 'incur'
+
+export default Cli.command({
+  description: 'Manage realms, and the realms that each app reaches.',
+  mcp: false,
+  run(c) {
+    return c.error({
+      code: 'missing_command',
+      message:
+        'Missing command. Run `tempo-id admin realms --help` to list the commands.',
+    })
+  },
+})

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

@@ -0,0 +1,38 @@
+/**
+ * `tempo-id admin realms list`: lists every realm, or the realms of one app in order.
+ * @module
+ */
+import { Cli, z } from 'incur'
+import * as Admin from '../../../Admin.js'
+
+export default Cli.command({
+  description:
+    'List every realm, or the realms that one app reaches, in order.',
+  env: Admin.env,
+  mcp: false,
+  options: Admin.options.extend({
+    clientId: z
+      .string()
+      .optional()
+      .describe(
+        "OAuth app's client ID. Lists the app's realms instead of every realm.",
+      ),
+  }),
+  async run(c) {
+    const connectionString = c.options.databaseUrl ?? c.env.DATABASE_URL
+    if (!connectionString) return c.error(Admin.missingDatabaseUrl)
+
+    const Realms = await Admin.loadRealms()
+    if (!Realms) return c.error(Admin.missingPeers)
+
+    const client = Realms.connect({ connectionString })
+    try {
+      const realms = c.options.clientId
+        ? await Realms.Realm.forApp(client.db, { clientId: c.options.clientId })
+        : await Realms.Realm.list(client.db)
+      return { realms }
+    } finally {
+      await client.end()
+    }
+  },
+})

package/src/cli/commands/admin/realms/passkeys/index.ts

@@ -0,0 +1,15 @@
+/** `tempo-id admin realms passkeys`: the commands that set the passkey relying party of a realm. @module */
+import { Cli } from 'incur'
+
+export default Cli.command({
+  description:
+    "Manage the passkey relying party whose passkeys own a realm's accounts.",
+  mcp: false,
+  run(c) {
+    return c.error({
+      code: 'missing_command',
+      message:
+        'Missing command. Run `tempo-id admin realms passkeys --help` to list the commands.',
+    })
+  },
+})

package/src/cli/commands/admin/realms/passkeys/set.ts

@@ -0,0 +1,44 @@
+/**
+ * `tempo-id admin realms passkeys set`: sets the passkey relying party of a realm, whose passkeys
+ * then sign in and own accounts in it.
+ * @module
+ */
+import { Cli, z } from 'incur'
+import * as Admin from '../../../../Admin.js'
+
+export default Cli.command({
+  args: z.object({
+    realmId: z.string().describe('Realm ID, such as default.'),
+  }),
+  description:
+    "Set the passkey relying party whose passkeys own a realm's accounts. It replaces an earlier relying party.",
+  env: Admin.env,
+  mcp: false,
+  options: Admin.options.extend({
+    rpId: z
+      .string()
+      .describe('Relying party ID, a registrable domain such as tempo.xyz.'),
+  }),
+  async run(c) {
+    const connectionString = c.options.databaseUrl ?? c.env.DATABASE_URL
+    if (!connectionString) return c.error(Admin.missingDatabaseUrl)
+
+    const Realms = await Admin.loadRealms()
+    if (!Realms) return c.error(Admin.missingPeers)
+
+    const client = Realms.connect({ connectionString })
+    try {
+      const realm = await Realms.Realm.setPasskeys(client.db, {
+        realmId: c.args.realmId,
+        rpId: c.options.rpId,
+      })
+      return { realm }
+    } catch (error) {
+      const refusal = Realms.error(error)
+      if (refusal) return c.error(refusal)
+      throw error
+    } finally {
+      await client.end()
+    }
+  },
+})

package/src/cli/commands/admin/realms/privy/index.ts

@@ -0,0 +1,14 @@
+/** `tempo-id admin realms privy`: the commands that set the Privy app of a realm. @module */
+import { Cli } from 'incur'
+
+export default Cli.command({
+  description: "Manage the Privy app that holds a realm's Privy owners.",
+  mcp: false,
+  run(c) {
+    return c.error({
+      code: 'missing_command',
+      message:
+        'Missing command. Run `tempo-id admin realms privy --help` to list the commands.',
+    })
+  },
+})

package/src/cli/commands/admin/realms/privy/set.ts

@@ -0,0 +1,69 @@
+/**
+ * `tempo-id admin realms privy set`: sets the Privy app of a realm. The database holds the app
+ * secret only encrypted with `SECRET`.
+ * @module
+ */
+import { Cli, z } from 'incur'
+import * as Admin from '../../../../Admin.js'
+
+export default Cli.command({
+  args: z.object({
+    realmId: z.string().describe('Realm ID, such as tempo-cash.'),
+  }),
+  description:
+    "Set the Privy app that holds a realm's Privy owners. It replaces an earlier Privy app.",
+  env: Admin.env.extend({
+    PRIVY_APP_SECRET: z
+      .string()
+      .optional()
+      .describe(
+        'Privy app secret. No flag takes it, so it stays out of the shell history.',
+      ),
+    SECRET: z
+      .string()
+      .optional()
+      .describe(
+        "The deployment's SECRET variable, which encrypts the app secret.",
+      ),
+  }),
+  mcp: false,
+  options: Admin.options.extend({
+    appId: z.string().describe('Privy app ID.'),
+  }),
+  async run(c) {
+    const connectionString = c.options.databaseUrl ?? c.env.DATABASE_URL
+    if (!connectionString) return c.error(Admin.missingDatabaseUrl)
+    const appSecret = c.env.PRIVY_APP_SECRET
+    if (!appSecret)
+      return c.error({
+        code: 'missing_app_secret',
+        message: 'Missing Privy app secret. Set PRIVY_APP_SECRET.',
+      })
+    if (!c.env.SECRET)
+      return c.error({
+        code: 'missing_secret',
+        message:
+          "Missing SECRET. Set it to the deployment's SECRET variable, which encrypts the app secret.",
+      })
+
+    const Realms = await Admin.loadRealms()
+    if (!Realms) return c.error(Admin.missingPeers)
+
+    const client = Realms.connect({ connectionString })
+    try {
+      const realm = await Realms.Realm.setPrivy(client.db, {
+        appId: c.options.appId,
+        appSecret,
+        realmId: c.args.realmId,
+        secret: c.env.SECRET,
+      })
+      return { realm }
+    } catch (error) {
+      const refusal = Realms.error(error)
+      if (refusal) return c.error(refusal)
+      throw error
+    } finally {
+      await client.end()
+    }
+  },
+})

package/src/cli/commands/admin/realms/remove.ts

@@ -0,0 +1,33 @@
+/** `tempo-id admin realms remove`: removes a realm that no app reaches. @module */
+import { Cli, z } from 'incur'
+import * as Admin from '../../../Admin.js'
+
+export default Cli.command({
+  args: z.object({
+    id: z.string().describe('Realm ID, such as tempo-cash.'),
+  }),
+  description:
+    'Remove a realm and its owner configurations. No app can name it.',
+  env: Admin.env,
+  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 Realms = await Admin.loadRealms()
+    if (!Realms) return c.error(Admin.missingPeers)
+
+    const client = Realms.connect({ connectionString })
+    try {
+      await Realms.Realm.remove(client.db, { id: c.args.id })
+      return { removed: c.args.id }
+    } catch (error) {
+      const refusal = Realms.error(error)
+      if (refusal) return c.error(refusal)
+      throw error
+    } finally {
+      await client.end()
+    }
+  },
+})

package/src/cli/commands/admin/realms/secp256k1/disable.ts

@@ -0,0 +1,40 @@
+/**
+ * `tempo-id admin realms secp256k1 disable`: turns off the secp256k1 owners that Tempo ID holds in a
+ * realm. The realm keeps the keys it holds, and lists them again when turned on.
+ * @module
+ */
+import { Cli, z } from 'incur'
+import * as Admin from '../../../../Admin.js'
+
+export default Cli.command({
+  args: z.object({
+    realmId: z.string().describe('Realm ID, such as default.'),
+  }),
+  description:
+    'Turn off the secp256k1 owners that Tempo ID holds in a realm. The realm keeps its stored keys.',
+  env: Admin.env,
+  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 Realms = await Admin.loadRealms()
+    if (!Realms) return c.error(Admin.missingPeers)
+
+    const client = Realms.connect({ connectionString })
+    try {
+      const realm = await Realms.Realm.setSecp256k1(client.db, {
+        enabled: false,
+        realmId: c.args.realmId,
+      })
+      return { realm }
+    } catch (error) {
+      const refusal = Realms.error(error)
+      if (refusal) return c.error(refusal)
+      throw error
+    } finally {
+      await client.end()
+    }
+  },
+})

package/src/cli/commands/admin/realms/secp256k1/enable.ts

@@ -0,0 +1,40 @@
+/**
+ * `tempo-id admin realms secp256k1 enable`: turns on the secp256k1 owners that Tempo ID holds in a
+ * realm, which then creates a user's first account there with a key that Tempo ID holds.
+ * @module
+ */
+import { Cli, z } from 'incur'
+import * as Admin from '../../../../Admin.js'
+
+export default Cli.command({
+  args: z.object({
+    realmId: z.string().describe('Realm ID, such as default.'),
+  }),
+  description:
+    'Turn on the secp256k1 owners that Tempo ID holds in a realm, for tests and local development. Never turn them on in production, since the keys stay in the database.',
+  env: Admin.env,
+  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 Realms = await Admin.loadRealms()
+    if (!Realms) return c.error(Admin.missingPeers)
+
+    const client = Realms.connect({ connectionString })
+    try {
+      const realm = await Realms.Realm.setSecp256k1(client.db, {
+        enabled: true,
+        realmId: c.args.realmId,
+      })
+      return { realm }
+    } catch (error) {
+      const refusal = Realms.error(error)
+      if (refusal) return c.error(refusal)
+      throw error
+    } finally {
+      await client.end()
+    }
+  },
+})

package/src/cli/commands/admin/realms/secp256k1/index.ts

@@ -0,0 +1,19 @@
+/**
+ * `tempo-id admin realms secp256k1`: the commands that turn on and off the secp256k1 owners that
+ * Tempo ID holds in a realm.
+ * @module
+ */
+import { Cli } from 'incur'
+
+export default Cli.command({
+  description:
+    'Manage the secp256k1 owners that Tempo ID holds in a realm, for tests and local development.',
+  mcp: false,
+  run(c) {
+    return c.error({
+      code: 'missing_command',
+      message:
+        'Missing command. Run `tempo-id admin realms secp256k1 --help` to list the commands.',
+    })
+  },
+})

package/src/cli/commands/admin/realms/set.ts

@@ -0,0 +1,46 @@
+/**
+ * `tempo-id admin realms set`: sets the realms that one app reaches, in order. The first realm holds
+ * a user's first account.
+ * @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."),
+    realms: z
+      .array(z.string())
+      .default([])
+      .describe(
+        'Realm IDs, in order, such as default tempo-cash. None resets the app to the default realm.',
+      ),
+  }),
+  description:
+    'Set the realms that an app reaches, in order. The first realm holds a first account.',
+  env: Admin.env,
+  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 Realms = await Admin.loadRealms()
+    if (!Realms) return c.error(Admin.missingPeers)
+
+    const client = Realms.connect({ connectionString })
+    try {
+      const realms = await Realms.Realm.setForApp(client.db, {
+        clientId: c.args.clientId,
+        realms: c.args.realms,
+      })
+      return { realms }
+    } catch (error) {
+      const refusal = Realms.error(error)
+      if (refusal) return c.error(refusal)
+      throw error
+    } finally {
+      await client.end()
+    }
+  },
+})

package/src/cli/commands/admin/rotate-key.ts

@@ -0,0 +1,47 @@
+/**
+ * `tempo-id admin rotate-key`: adds a new signing key, and retires the earlier one. `GET /oauth2/jwks`
+ * serves the new key at once, Tempo ID signs with it after the publication delay, and the JWKS serves
+ * the earlier key through its grace period.
+ * @module
+ */
+import { Cli, z } from 'incur'
+import * as Admin from '../../Admin.js'
+
+export default Cli.command({
+  description:
+    'Rotate the signing key. The new key signs after 5 minutes, and the JWKS serves the earlier key for 30 more days.',
+  env: Admin.env.extend({
+    SECRET: z
+      .string()
+      .optional()
+      .describe(
+        "The deployment's SECRET variable, which encrypts the signing keys.",
+      ),
+  }),
+  mcp: false,
+  options: Admin.options,
+  async run(c) {
+    const connectionString = c.options.databaseUrl ?? c.env.DATABASE_URL
+    if (!connectionString) return c.error(Admin.missingDatabaseUrl)
+    if (!c.env.SECRET)
+      return c.error({
+        code: 'missing_secret',
+        message:
+          "Missing SECRET. Set it to the deployment's SECRET variable, which encrypts the signing keys.",
+      })
+
+    const Apps = await Admin.loadApps()
+    if (!Apps) return c.error(Admin.missingPeers)
+
+    const client = Apps.connect({ connectionString })
+    try {
+      return await Apps.SigningKey.rotate(client.db, { secret: c.env.SECRET })
+    } catch (error) {
+      const refusal = Apps.error(error)
+      if (refusal) return c.error(refusal)
+      throw error
+    } finally {
+      await client.end()
+    }
+  },
+})

package/src/cli/commands/init.ts

@@ -0,0 +1,42 @@
+/** `tempo-id init`: writes a Tempo ID Worker project. @module */
+import { Cli, z } from 'incur'
+import * as Project from '../Project.js'
+
+export default Cli.command({
+  args: z.object({
+    dir: z
+      .string()
+      .optional()
+      .describe(
+        'The folder to write the project in. Defaults to the working directory.',
+      ),
+  }),
+  description: 'Write a Tempo ID Worker project.',
+  mcp: false,
+  options: z.object({
+    from: z
+      .string()
+      .describe(
+        'The sender of every email, such as "Tempo ID <noreply@id.example.com>".',
+      ),
+    name: z
+      .string()
+      .optional()
+      .describe(
+        "The project's package name and Worker name. Defaults to the folder's name.",
+      ),
+    url: z
+      .string()
+      .describe(
+        "Tempo ID's origin, such as https://id.example.com, and every token's iss.",
+      ),
+  }),
+  run(c) {
+    return Project.init({
+      from: c.options.from,
+      name: c.options.name,
+      root: c.args.dir ?? process.cwd(),
+      url: c.options.url,
+    })
+  },
+})

package/src/cli/commands/login.ts

@@ -0,0 +1,32 @@
+/**
+ * `tempo-id login`: signs in through Tempo ID's device grant as the `tempo-cli` app, and stores the
+ * session with its access key.
+ * @module
+ */
+import { Cli } from 'incur'
+import * as User from '../User.js'
+
+export default Cli.command({
+  description:
+    'Sign in by approving a code in any browser, and store the session.',
+  env: User.env,
+  // An agent cannot approve the code in a browser for the user.
+  mcp: false,
+  async *run(c) {
+    const Session = await User.loadSession()
+    if (!Session) return c.error(User.missingPeers)
+
+    const options = { home: c.env.TEMPO_HOME, url: c.env.TEMPO_ID_URL }
+    const device = await Session.login(options)
+    yield `Open ${device.verificationUriComplete}`
+    yield `and confirm the code ${device.userCode}.`
+
+    const session = await device.wait().catch((error: Error) => error)
+    if (session instanceof Error)
+      return c.error({ code: 'not_signed_in', message: session.message })
+
+    // A streaming command prints what it yields, not what it returns.
+    yield `Signed in as ${session.user.email}.`
+    return c.ok({ account: session.key.account, email: session.user.email })
+  },
+})

package/src/cli/commands/logout.ts

@@ -0,0 +1,19 @@
+/** `tempo-id logout`: revokes the stored session's refresh token, and deletes the session. @module */
+import { Cli } from 'incur'
+import * as User from '../User.js'
+
+export default Cli.command({
+  description: 'Sign out on this machine, and revoke the refresh token.',
+  env: User.env,
+  mcp: false,
+  async run(c) {
+    const Session = await User.loadSession()
+    if (!Session) return c.error(User.missingPeers)
+
+    const revoked = await Session.remove({
+      home: c.env.TEMPO_HOME,
+      url: c.env.TEMPO_ID_URL,
+    })
+    return { revoked, signed_out: true }
+  },
+})