tapimo 0.15.0 → 0.18.0

package/src/apps/management/routes/cli.ts

@@ -0,0 +1,533 @@
+import { type Context, Hono } from 'hono'
+import * as z from 'zod/mini'
+
+import * as Auth from '../../../internal/Auth.js'
+import * as CliAuth from '../../../internal/CliAuth.js'
+import * as OpenApi from '../../../internal/OpenApi.js'
+import * as Response from '../../../internal/Response.js'
+import * as Schema from '../../../internal/Schema.js'
+import * as Scope from '../../../Scope.js'
+import type { Environment } from '../App.js'
+import * as ManagementError from '../Error.js'
+
+/** Schemas owned by the CLI sign-in routes. */
+export namespace schema {
+  /** API permissions approved for this CLI device. */
+  export const ApproveRequest = z.object({
+    scopes: z.optional(
+      z.array(z.string()).check(
+        z.refine((scopes) => new Set(scopes).size === scopes.length),
+        z.describe('API scopes approved for this device. Omit to use the default scopes.'),
+        z.meta({ examples: [['data:read', 'routes:read', 'routes:write', 'rpc-relay:read']] }),
+      ),
+    ),
+  })
+  const code = z
+    .string()
+    .check(
+      z.describe('Code shown in both the terminal and the console to match the request.'),
+      z.meta({ examples: ['BCDF-GHJK'] }),
+    )
+  const expiresAt = z.iso
+    .datetime()
+    .check(
+      z.describe('When the pending sign-in expires (ISO 8601).'),
+      z.meta({ examples: ['2026-01-01T00:10:00.000Z'] }),
+    )
+  const device = z
+    .string()
+    .check(
+      z.minLength(1),
+      z.maxLength(100),
+      z.describe('Hostname of the machine running the CLI.'),
+      z.meta({ examples: ['build-box'] }),
+    )
+  const name = z
+    .string()
+    .check(
+      z.minLength(1),
+      z.maxLength(100),
+      z.describe('CLI name and version.'),
+      z.meta({ examples: ['tempo api 0.1.0'] }),
+    )
+
+  /** Path parameters naming one sign-in request. */
+  export const Params = z.object({
+    code: z.string().check(z.describe('Authorization code.'), z.meta({ examples: ['BCDF-GHJK'] })),
+  })
+
+  /** Body for starting a CLI sign-in. */
+  export const CreateRequest = Schema.describe(
+    z.object({
+      codeChallenge: CliAuth.schema.CodeChallenge.check(
+        z.describe('PKCE S256 challenge: base64url SHA-256 of the code verifier, unpadded.'),
+        z.meta({ examples: ['E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM'] }),
+      ),
+      device: z.optional(device),
+      name: z.optional(name),
+    }),
+    'Fields for starting a CLI sign-in.',
+  )
+
+  /** A started CLI sign-in. */
+  export const CreateResponse = Schema.describe(
+    z.object({
+      code,
+      expiresAt,
+      interval: z
+        .number()
+        .check(
+          z.int(),
+          z.positive(),
+          z.describe('Seconds to wait between token polls.'),
+          z.meta({ examples: [CliAuth.pollInterval] }),
+        ),
+      verificationUrl: z
+        .url()
+        .check(
+          z.describe('Console page where the user approves the sign-in.'),
+          z.meta({ examples: ['https://console.tempo.xyz/cli?code=BCDF-GHJK'] }),
+        ),
+    }),
+    'A started CLI sign-in.',
+  )
+
+  /** A sign-in request as shown to the approving user. */
+  export const Authorization = Schema.describe(
+    z.object({
+      client: z
+        .object({ device: z.optional(device), name: z.optional(name) })
+        .check(z.describe('CLI details reported when the sign-in started.')),
+      code,
+      createdAt: z.iso
+        .datetime()
+        .check(
+          z.describe('When the sign-in started (ISO 8601).'),
+          z.meta({ examples: ['2026-01-01T00:00:00.000Z'] }),
+        ),
+      expiresAt,
+      ip: z.optional(
+        z
+          .string()
+          .check(
+            z.describe('IP address that started the sign-in.'),
+            z.meta({ examples: ['203.0.113.7'] }),
+          ),
+      ),
+      scopes: z
+        .array(z.string())
+        .check(
+          z.describe('Default or approved API scopes for this device.'),
+          z.meta({ examples: [['data:read', 'routes:read', 'routes:write', 'rpc-relay:read']] }),
+        ),
+      status: z
+        .enum(['approved', 'denied', 'pending'])
+        .check(z.describe('Whether the sign-in was decided.'), z.meta({ examples: ['pending'] })),
+    }),
+    'A pending CLI sign-in.',
+  )
+
+  /** Outcome of approving or denying a sign-in. */
+  export const Decision = Schema.describe(
+    z.object({
+      code,
+      status: z
+        .enum(['approved', 'denied'])
+        .check(z.describe('The recorded decision.'), z.meta({ examples: ['approved'] })),
+    }),
+    'The recorded decision.',
+  )
+
+  /** Body for exchanging an approved sign-in for a CLI session token. */
+  export const TokenRequest = Schema.describe(
+    z.object({
+      codeVerifier: CliAuth.schema.CodeVerifier.check(
+        z.describe('PKCE code verifier whose challenge started the sign-in.'),
+        z.meta({ examples: ['dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk'] }),
+      ),
+    }),
+    'Fields for exchanging a sign-in for a CLI session.',
+  )
+
+  /** Sign-in state, carrying the session token once approved. */
+  export const TokenResponse = z
+    .discriminatedUnion('status', [
+      z.object({ status: z.literal('pending') }),
+      z.object({ status: z.literal('denied') }),
+      z.object({
+        expiresAt: z.iso
+          .datetime()
+          .check(
+            z.describe('When the CLI session expires (ISO 8601).'),
+            z.meta({ examples: ['2026-01-31T00:00:00.000Z'] }),
+          ),
+        scopes: z
+          .array(z.string())
+          .check(
+            z.describe('API scopes approved for this device.'),
+            z.meta({ examples: [['data:read', 'routes:read']] }),
+          ),
+        status: z.literal('approved'),
+        token: z
+          .string()
+          .check(
+            z.describe('CLI session token, sent as `Authorization: Bearer`. Shown once.'),
+            z.meta({ examples: [`tempo:cli:${'ab'.repeat(32)}`] }),
+          ),
+      }),
+    ])
+    .check(
+      z.describe('Sign-in state; `approved` carries the session token.'),
+      z.meta({ examples: [{ status: 'pending' }] }),
+    )
+}
+
+const bodyValidation = {
+  code: 'body_invalid',
+  message: 'Check the request body and try again.',
+} as const
+const paramValidation = {
+  code: 'param_invalid',
+  message: 'Check the path parameters and try again.',
+} as const
+
+// These routes are CLI-to-console plumbing, not public API surface: they stay
+// out of the OpenAPI document, so neither generated CLI commands nor MCP tools
+// expose them. `hide: true` still registers each route with the auth policy.
+const hide = true
+
+/**
+ * CLI sign-in: a CLI starts a PKCE-bound request, a signed-in console user
+ * approves it, and the CLI exchanges the approval for a CLI session token.
+ */
+export function cli(options: cli.Options = {}) {
+  const consoleUrl = (options.consoleUrl ?? 'https://console.tempo.xyz').replace(/\/$/, '')
+  const validateApproval = OpenApi.validate('json', schema.ApproveRequest, bodyValidation)
+  return new Hono<Environment>()
+    .post(
+      '/v1/cli/authorizations',
+      Auth.policy({ public: true }),
+      OpenApi.validate('json', schema.CreateRequest, bodyValidation),
+      OpenApi.describeRoute({
+        hide,
+        operationId: 'createCliAuthorization',
+        responses: OpenApi.responses({
+          errors: {
+            400: { codes: ['body_invalid'], description: 'Invalid body.' },
+            404: { codes: ['cli_auth_not_enabled'], description: 'CLI sign-in is not enabled.' },
+          },
+          success: { description: 'The started sign-in.', schema: schema.CreateResponse },
+        }),
+        summary: 'Start CLI sign-in',
+        tags: ['Authentication'],
+      }),
+      async (c) => {
+        if (Auth.narrowAccess) return Auth.accessError(c)
+        if (OpenApi.narrowValidation) return OpenApi.validationError(c, bodyValidation)
+        const kv = c.get('kv')
+        if (!kv) return notEnabled(c)
+        const { codeChallenge, device, name } = c.req.valid('json')
+        try {
+          const ip = Auth.getTrustedClientIp(c)
+          const authorization = await CliAuth.authorize(kv.store, {
+            client: { ...(device ? { device } : {}), ...(name ? { name } : {}) },
+            codeChallenge,
+            ...(ip ? { ip } : {}),
+          })
+          const code = CliAuth.formatCode(authorization.code)
+          const verificationUrl = new URL(`${consoleUrl}/cli`)
+          verificationUrl.searchParams.set('code', code)
+          return c.json(
+            Response.validated(schema.CreateResponse, {
+              code,
+              expiresAt: authorization.expiresAt,
+              interval: CliAuth.pollInterval,
+              verificationUrl: verificationUrl.toString(),
+            }),
+            200,
+          )
+        } catch (cause) {
+          return Response.upstream(c, cause)
+        }
+      },
+    )
+    .get(
+      '/v1/cli/authorizations/:code{[A-Za-z -]+}',
+      Auth.policy({ session: true }),
+      OpenApi.validate('param', schema.Params, paramValidation),
+      OpenApi.describeRoute({
+        hide,
+        operationId: 'getCliAuthorization',
+        responses: OpenApi.responses({
+          errors: {
+            400: { codes: ['param_invalid'], description: 'Invalid path.' },
+            403: { codes: ['forbidden'], description: 'A console session is required.' },
+            404: {
+              codes: ['cli_auth_not_enabled', 'cli_authorization_not_found'],
+              description: 'No pending sign-in was found for this code.',
+            },
+          },
+          success: { description: 'The sign-in request.', schema: schema.Authorization },
+        }),
+        summary: 'Get CLI sign-in',
+        tags: ['Authentication'],
+      }),
+      async (c) => {
+        if (Auth.narrowAccess) return Auth.superAdminAccessError(c)
+        if (OpenApi.narrowValidation) return OpenApi.validationError(c, paramValidation)
+        const kv = c.get('kv')
+        if (!kv) return notEnabled(c)
+        if (!consoleSession(c)) return consoleSessionRequired(c)
+        const code = CliAuth.normalizeCode(c.req.valid('param').code)
+        if (!code) return notFound(c)
+        try {
+          const authorization = await CliAuth.getAuthorization(kv.store, code)
+          if (!authorization) return notFound(c)
+          const { client, createdAt, expiresAt, ip, status } = authorization
+          return c.json(
+            Response.validated(schema.Authorization, {
+              client,
+              code: CliAuth.formatCode(code),
+              createdAt,
+              expiresAt,
+              ...(ip ? { ip } : {}),
+              scopes:
+                authorization.scopes ??
+                CliAuth.defaultScopes.filter((scope) =>
+                  Scope.includes(c.get('scopeCatalog'), scope),
+                ),
+              status,
+            }),
+            200,
+          )
+        } catch (cause) {
+          return Response.upstream(c, cause)
+        }
+      },
+    )
+    .post(
+      '/v1/cli/authorizations/:code{[A-Za-z -]+}/approve',
+      Auth.policy({ session: true }),
+      OpenApi.validate('param', schema.Params, paramValidation),
+      OpenApi.documentJsonRequest(schema.ApproveRequest),
+      async (c, next) => {
+        // Legacy approvals omit the body, even when their Content-Type declares JSON.
+        if ((await c.req.text()) !== '') return validateApproval(c as never, next)
+        c.req.addValidatedData('json', {})
+        return next()
+      },
+      OpenApi.describeRoute({
+        hide,
+        operationId: 'approveCliAuthorization',
+        responses: OpenApi.responses({
+          errors: {
+            400: {
+              codes: ['body_invalid', 'param_invalid'],
+              description: 'Invalid path or scopes.',
+            },
+            403: { codes: ['forbidden'], description: 'A console session is required.' },
+            404: {
+              codes: ['cli_auth_not_enabled', 'cli_authorization_not_found'],
+              description: 'No pending sign-in was found for this code.',
+            },
+            409: {
+              codes: ['cli_authorization_decided'],
+              description: 'The sign-in was already decided.',
+            },
+          },
+          success: { description: 'The sign-in was approved.', schema: schema.Decision },
+        }),
+        summary: 'Approve CLI sign-in',
+        tags: ['Authentication'],
+      }),
+      async (c) => {
+        if (Auth.narrowAccess) return Auth.superAdminAccessError(c)
+        if (OpenApi.narrowValidation) return OpenApi.validationError(c, paramValidation)
+        const kv = c.get('kv')
+        if (!kv) return notEnabled(c)
+        const principal = consoleSession(c)
+        if (!principal) return consoleSessionRequired(c)
+        const code = CliAuth.normalizeCode(c.req.valid('param').code)
+        if (!code) return notFound(c)
+        try {
+          const catalog = c.get('scopeCatalog')
+          const scopes =
+            c.req.valid('json').scopes ??
+            CliAuth.defaultScopes.filter((scope) => Scope.includes(catalog, scope))
+          if (
+            !scopes.every(
+              (scope) => Scope.selfServeFrom(catalog).includes(scope) || scope === 'routes:write',
+            )
+          )
+            return Response.error(c, {
+              code: 'body_invalid',
+              message: 'Select supported CLI API scopes.',
+              status: 400,
+            })
+          const result = await CliAuth.approve(kv.store, { code, scopes, userId: principal.id })
+          if (result.status === 'not_found') return notFound(c)
+          if (result.status === 'conflict') return decided(c)
+          return c.json(
+            Response.validated(schema.Decision, {
+              code: CliAuth.formatCode(code),
+              status: 'approved',
+            }),
+            200,
+          )
+        } catch (cause) {
+          return Response.upstream(c, cause)
+        }
+      },
+    )
+    .post(
+      '/v1/cli/authorizations/:code{[A-Za-z -]+}/deny',
+      Auth.policy({ session: true }),
+      OpenApi.validate('param', schema.Params, paramValidation),
+      OpenApi.describeRoute({
+        hide,
+        operationId: 'denyCliAuthorization',
+        responses: OpenApi.responses({
+          errors: {
+            400: { codes: ['param_invalid'], description: 'Invalid path.' },
+            403: { codes: ['forbidden'], description: 'A console session is required.' },
+            404: {
+              codes: ['cli_auth_not_enabled', 'cli_authorization_not_found'],
+              description: 'No pending sign-in was found for this code.',
+            },
+            409: {
+              codes: ['cli_authorization_decided'],
+              description: 'The sign-in was already decided.',
+            },
+          },
+          success: { description: 'The sign-in was denied.', schema: schema.Decision },
+        }),
+        summary: 'Deny CLI sign-in',
+        tags: ['Authentication'],
+      }),
+      async (c) => {
+        if (Auth.narrowAccess) return Auth.superAdminAccessError(c)
+        if (OpenApi.narrowValidation) return OpenApi.validationError(c, paramValidation)
+        const kv = c.get('kv')
+        if (!kv) return notEnabled(c)
+        if (!consoleSession(c)) return consoleSessionRequired(c)
+        const code = CliAuth.normalizeCode(c.req.valid('param').code)
+        if (!code) return notFound(c)
+        try {
+          const result = await CliAuth.deny(kv.store, code)
+          if (result.status === 'not_found') return notFound(c)
+          if (result.status === 'conflict') return decided(c)
+          return c.json(
+            Response.validated(schema.Decision, {
+              code: CliAuth.formatCode(code),
+              status: 'denied',
+            }),
+            200,
+          )
+        } catch (cause) {
+          return Response.upstream(c, cause)
+        }
+      },
+    )
+    .post(
+      '/v1/cli/authorizations/:code{[A-Za-z -]+}/token',
+      Auth.policy({ public: true }),
+      OpenApi.validate('param', schema.Params, paramValidation),
+      OpenApi.validate('json', schema.TokenRequest, bodyValidation),
+      OpenApi.describeRoute({
+        hide,
+        operationId: 'exchangeCliAuthorization',
+        responses: OpenApi.responses({
+          errors: {
+            400: { codes: ['body_invalid', 'param_invalid'], description: 'Invalid path or body.' },
+            404: {
+              codes: ['cli_auth_not_enabled', 'cli_authorization_not_found'],
+              description: 'The sign-in expired, was redeemed, or the verifier does not match.',
+            },
+          },
+          success: { description: 'The sign-in state.', schema: schema.TokenResponse },
+        }),
+        summary: 'Exchange CLI sign-in',
+        tags: ['Authentication'],
+      }),
+      async (c) => {
+        if (Auth.narrowAccess) return Auth.accessError(c)
+        if (OpenApi.narrowValidation) return OpenApi.validationError(c, paramValidation)
+        if (OpenApi.narrowValidation) return OpenApi.validationError(c, bodyValidation)
+        const kv = c.get('kv')
+        if (!kv) return notEnabled(c)
+        const code = CliAuth.normalizeCode(c.req.valid('param').code)
+        if (!code) return notFound(c)
+        try {
+          const result = await CliAuth.redeem(kv.store, {
+            code,
+            codeVerifier: c.req.valid('json').codeVerifier,
+          })
+          if (!result) return notFound(c)
+          // Pending and denied states must never be cached; the token only appears once.
+          c.header('Cache-Control', 'no-store')
+          if (result.status !== 'approved')
+            return c.json(Response.validated(schema.TokenResponse, { status: result.status }), 200)
+          return c.json(
+            Response.validated(schema.TokenResponse, {
+              expiresAt: result.session.expiresAt,
+              scopes: result.session.scopes ?? CliAuth.defaultScopes,
+              status: 'approved',
+              token: result.token,
+            }),
+            200,
+          )
+        } catch (cause) {
+          return Response.upstream(c, cause)
+        }
+      },
+    )
+}
+
+export declare namespace cli {
+  /** Options for the CLI sign-in routes. */
+  type Options = {
+    /** Console origin hosting the approval page. @default 'https://console.tempo.xyz' */
+    consoleUrl?: string | undefined
+  }
+}
+
+// Only browser sessions may decide sign-ins, so a leaked CLI token cannot mint fresh CLI sessions.
+function consoleSession(c: Context<Environment>) {
+  const principal = Auth.getPrincipal(c)
+  if (principal?.type !== 'session' || principal.identity.provider === 'cli') return undefined
+  return principal
+}
+
+function consoleSessionRequired(c: Context<Environment>) {
+  const principal = Auth.getPrincipal(c)
+  if (principal?.type !== 'session') return ManagementError.sessionRequired(c)
+  return Response.error(c, {
+    code: 'forbidden',
+    message: 'Approve CLI sign-ins from the console',
+    status: 403,
+  })
+}
+
+function decided(c: Context<Environment>) {
+  return Response.error(c, {
+    code: 'cli_authorization_decided',
+    message: 'This sign-in was already approved or denied. Start a new sign-in from the CLI.',
+    status: 409,
+  })
+}
+
+function notEnabled(c: Context<Environment>) {
+  return Response.error(c, {
+    code: 'cli_auth_not_enabled',
+    message: 'CLI sign-in is not enabled for this Tempo API deployment.',
+    status: 404,
+  })
+}
+
+function notFound(c: Context<Environment>) {
+  return Response.error(c, {
+    code: 'cli_authorization_not_found',
+    message: 'Sign-in not found or expired. Start a new sign-in from the CLI.',
+    status: 404,
+  })
+}

package/src/apps/management/routes/me.test.ts

@@ -286,7 +286,7 @@ describe('SIWE identity', () => {
     }
   })
 
-  test('folds the token-verified email onto the session', async () => {
+  test('requires fresh sign-in after the verified email changes', async () => {
     const oidc = await createIssuer({ email: 'dev@example.com' })
     const db = TestApp.database()
     try {
@@ -299,15 +299,25 @@ describe('SIWE identity', () => {
       const { cookie, verifyResponse } = await TestApp.signIn(app, account, {
         idToken: ({ nonce }) => oidc.mint({ address: account.address, nonce }),
       })
-      // Simulate the previous Worker writing after the auth-field backfill.
+      expect(verifyResponse.status).toBe(200)
       await db.kysely
         .updateTable('users')
         .set({ email: 'Dev@Example.com', emailVerified: false })
         .where('address', '=', account.address.toLowerCase())
         .execute()
 
-      expect(verifyResponse.status).toBe(200)
-      const response = await app.request('/v1/me', { headers: { cookie: cookie! } })
+      const stale = await app.request('/v1/me', { headers: { cookie: cookie! } })
+      expect(stale.status).toBe(401)
+      await expect(Users.getByAddress(db, account.address)).resolves.toMatchObject({
+        email: 'Dev@Example.com',
+        emailVerified: false,
+      })
+
+      const fresh = await TestApp.signIn(app, account, {
+        idToken: ({ nonce }) => oidc.mint({ address: account.address, nonce }),
+      })
+      expect(fresh.verifyResponse.status).toBe(200)
+      const response = await app.request('/v1/me', { headers: { cookie: fresh.cookie! } })
       expect(response.status).toBe(200)
       const body = await TestApp.json(response, Me.schema.User)
       expect(body.email).toBe('dev@example.com')