tapimo 0.2.0 → 0.4.0

package/src/apps/{platform → management}/routes/api-keys.test.ts

@@ -1,5 +1,6 @@
 import { generatePrivateKey, privateKeyToAccount } from 'viem/accounts'
 
+import * as ApiKeys from '../../../ApiKeys.js'
 import * as TestApp from '../../../../test/App.js'
 import * as Keys from './api-keys.js'
 import * as Orgs from './orgs.js'
@@ -95,8 +96,9 @@ describe('keys', () => {
     })
     expect(data.status).toBe(200)
 
-    // Listing exposes metadata only — never the token.
-    const listed = await app.request(base, { headers: { cookie } })
+    // Listing exposes metadata only — never the token. The key is sandbox, so
+    // the list is scoped to that environment (production is the default).
+    const listed = await app.request(`${base}?environment=sandbox`, { headers: { cookie } })
     expect(listed.status).toBe(200)
     const list = await TestApp.json(listed, Keys.schema.listApiKeys.Response)
     expect(list.data.map(({ id }) => id)).toEqual([created.id])
@@ -136,28 +138,87 @@ describe('keys', () => {
     expect(response.status).toBe(400)
   })
 
-  test('rejects session mints while no scope is self-issuable', async () => {
+  test('mints zero-scope keys for sessions', async () => {
     const app = createApp()
     const cookie = await session(app)
     const { org, project } = await fixture(app, cookie)
 
-    const response = await app.request(
+    const minted = await app.request(
       `/v1/orgs/${org.id}/projects/${project.id}/api-keys`,
-      json('POST', cookie, { scopes: ['data:read'] }),
+      json('POST', cookie, { name: 'CI' }),
     )
-    expect(response.status).toBe(403)
-    const { requestId, ...body } = (await response.json()) as { requestId?: string }
+    expect(minted.status).toBe(200)
+    const created = await TestApp.json(minted, Keys.schema.createApiKey.Response)
+    expect(created.scopes).toEqual([])
+    expect(created.createdBy).toMatch(/^usr_/)
+
+    // The key authenticates but grants nothing: scoped routes stay forbidden.
+    const data = await app.request('/v1/tokens', {
+      headers: { 'cache-control': 'no-store', 'tempo-api-key': created.token },
+    })
+    expect(data.status).toBe(403)
+    const { requestId, ...body } = (await data.json()) as { requestId?: string }
     expect(requestId).toBeDefined()
     expect(body).toMatchInlineSnapshot(`
       {
         "error": {
-          "code": "scope_not_issuable",
-          "message": "The requested scopes are not issuable.",
+          "code": "api_key_forbidden",
+          "message": "API key missing required scope",
         },
       }
     `)
   })
 
+  test('lets sessions mint catalog scopes on production keys', async () => {
+    const app = createApp()
+    const cookie = await session(app)
+    const { org, project } = await fixture(app, cookie)
+
+    const created = await TestApp.json(
+      await app.request(
+        `/v1/orgs/${org.id}/projects/${project.id}/api-keys`,
+        json('POST', cookie, { scopes: ['data:read'] }),
+      ),
+      Keys.schema.createApiKey.Response,
+    )
+    expect(created.environment).toBe('production')
+    expect(created.scopes).toEqual(['data:read'])
+    // Session-minted, not granted through the super admin.
+    expect(created.createdBy).not.toBe('super_admin')
+  })
+
+  test('rejects session mints of non-self-serve scopes (webhooks)', async () => {
+    const app = createApp()
+    const cookie = await session(app)
+    const { org, project } = await fixture(app, cookie)
+
+    const response = await app.request(
+      `/v1/orgs/${org.id}/projects/${project.id}/api-keys`,
+      json('POST', cookie, { scopes: ['webhooks:write'] }),
+    )
+    expect(response.status).toBe(403)
+    const body = (await response.json()) as { error: { code: string } }
+    expect(body.error.code).toBe('scope_not_issuable')
+  })
+
+  test('lets sessions mint catalog scopes on sandbox keys', async () => {
+    const app = createApp()
+    const cookie = await session(app)
+    const { org, project } = await fixture(app, cookie)
+
+    const created = await TestApp.json(
+      await app.request(
+        `/v1/orgs/${org.id}/projects/${project.id}/api-keys`,
+        json('POST', cookie, { environment: 'sandbox', scopes: ['data:read'] }),
+      ),
+      Keys.schema.createApiKey.Response,
+    )
+    expect(created.environment).toBe('sandbox')
+    expect(created.scopes).toEqual(['data:read'])
+    // Session-minted, not granted through the super admin.
+    expect(created.createdBy).not.toBe('super_admin')
+  })
+
   test('binds keys to their project on every verb', async () => {
     const app = createApp()
     const owner = await session(app)
@@ -206,6 +267,108 @@ describe('keys', () => {
     expect(list.data.map(({ id }) => id)).toEqual([minted.id])
   })
 
+  test('lists keys org-wide across projects', async () => {
+    const store = TestApp.kvStore({ keys: [] })
+    const app = createApp({ kv: { store } })
+    const owner = await session(app)
+    const { org, project } = await fixture(app, owner)
+    const other = await TestApp.json(
+      await app.request(`/v1/orgs/${org.id}/projects`, json('POST', owner, { name: 'Payments' })),
+      Projects.schema.Project,
+    )
+
+    const first = await TestApp.json(
+      await app.request(
+        `/v1/orgs/${org.id}/projects/${project.id}/api-keys`,
+        superAdminJson('POST', { name: 'Checkout CI', scopes: ['data:read'] }),
+      ),
+      Keys.schema.createApiKey.Response,
+    )
+    const second = await TestApp.json(
+      await app.request(
+        `/v1/orgs/${org.id}/projects/${other.id}/api-keys`,
+        superAdminJson('POST', { name: 'Payments CI', scopes: ['data:read'] }),
+      ),
+      Keys.schema.createApiKey.Response,
+    )
+    // Org-attributed key without a project (admin-surface mints land like this).
+    const orgWide = await ApiKeys.mint(store, { orgId: org.id, scopes: ['data:read'] })
+
+    const listed = await app.request(`/v1/orgs/${org.id}/api-keys`, {
+      headers: { cookie: owner },
+    })
+    const list = await TestApp.json(listed, Keys.schema.listOrgApiKeys.Response)
+    expect(list.data.map(({ id }) => id).sort()).toEqual(
+      [first.id, second.id, orgWide.record.id].sort(),
+    )
+    expect(list.data.find(({ id }) => id === first.id)?.projectId).toBe(project.id)
+    expect(list.data.find(({ id }) => id === second.id)?.projectId).toBe(other.id)
+    expect(list.data.find(({ id }) => id === orgWide.record.id)?.projectId).toBeUndefined()
+
+    // Non-members see the org as absent.
+    const stranger = await session(app)
+    const foreign = await app.request(`/v1/orgs/${org.id}/api-keys`, {
+      headers: { cookie: stranger },
+    })
+    expect(foreign.status).toBe(404)
+  })
+
+  test('filters keys by environment (defaulting to production)', async () => {
+    const app = createApp()
+    const cookie = await session(app)
+    const { org, project } = await fixture(app, cookie)
+    const projectBase = `/v1/orgs/${org.id}/projects/${project.id}/api-keys`
+    const orgBase = `/v1/orgs/${org.id}/api-keys`
+
+    const production = await TestApp.json(
+      await app.request(
+        projectBase,
+        superAdminJson('POST', { name: 'Prod', scopes: ['data:read'] }),
+      ),
+      Keys.schema.createApiKey.Response,
+    )
+    const sandbox = await TestApp.json(
+      await app.request(
+        projectBase,
+        superAdminJson('POST', { environment: 'sandbox', name: 'Sandbox', scopes: ['data:read'] }),
+      ),
+      Keys.schema.createApiKey.Response,
+    )
+
+    const ids = async (path: string) =>
+      (
+        await TestApp.json(
+          await app.request(path, { headers: { cookie } }),
+          Keys.schema.listApiKeys.Response,
+        )
+      ).data
+        .map(({ id }) => id)
+        .sort()
+
+    // Each filter returns only its own environment.
+    expect(await ids(`${projectBase}?environment=production`)).toEqual([production.id])
+    expect(await ids(`${projectBase}?environment=sandbox`)).toEqual([sandbox.id])
+    // Absent param defaults to production.
+    expect(await ids(projectBase)).toEqual([production.id])
+
+    // Same behavior on the org-wide list route.
+    const orgIds = async (path: string) =>
+      (
+        await TestApp.json(
+          await app.request(path, { headers: { cookie } }),
+          Keys.schema.listOrgApiKeys.Response,
+        )
+      ).data
+        .map(({ id }) => id)
+        .sort()
+    expect(await orgIds(`${orgBase}?environment=sandbox`)).toEqual([sandbox.id])
+    expect(await orgIds(orgBase)).toEqual([production.id])
+
+    // An unknown environment value is rejected.
+    const invalid = await app.request(`${projectBase}?environment=staging`, { headers: { cookie } })
+    expect(invalid.status).toBe(400)
+  })
+
   test('revokes keys when their project or organization is deleted', async () => {
     const app = createApp()
     const cookie = await session(app)

package/src/apps/{platform → management}/routes/api-keys.ts

@@ -3,7 +3,9 @@ import * as z from 'zod/mini'
 
 import * as ApiKeys from '../../../ApiKeys.js'
 import type * as App from '../../../App.js'
+import * as Db from '../../../db/Db.js'
 import * as Auth from '../../../internal/Auth.js'
+import * as Billing from '../Billing.js'
 import * as OpenApi from '../../../internal/OpenApi.js'
 import * as Response from '../../../internal/Response.js'
 import * as Schema from '../../../internal/Schema.js'
@@ -50,12 +52,10 @@ export namespace schema {
           z.describe('Owning organization id (`org_…`).'),
           z.meta({ examples: ['org_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
         ),
-      projectId: z
-        .string()
-        .check(
-          z.describe('Owning project id (`prj_…`).'),
-          z.meta({ examples: ['prj_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
-        ),
+      projectId: z.optional(z.string()).check(
+        z.describe('Owning project id (`prj_…`).'), // prettier-ignore
+        z.meta({ examples: ['prj_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
+      ),
       scopes: z
         .array(z.enum([...Scope.catalog.map((entry) => entry.scope), Scope.wildcard]))
         .check(
@@ -92,6 +92,18 @@ export namespace schema {
     })
     .check(z.describe("Path parameters for a project's API keys."))
 
+  /** Path parameters addressing an organization's key collection. */
+  export const OrgParams = z
+    .object({
+      orgId: z
+        .string()
+        .check(
+          z.describe('The organization id (`org_…`).'),
+          z.meta({ examples: ['org_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
+        ),
+    })
+    .check(z.describe("Path parameters for an organization's API keys."))
+
   /** Path parameters addressing one API key. */
   export const KeyParams = z
     .object({
@@ -126,12 +138,8 @@ export namespace schema {
         .optional(z.string().check(z.minLength(1), z.maxLength(100)))
         .check(z.describe('Human-readable key name.'), z.meta({ examples: ['CI'] })),
       scopes: z
-        .array(z.enum(Scope.catalog.map((entry) => entry.scope)))
-        .check(
-          z.minLength(1),
-          z.describe('Scopes to grant.'),
-          z.meta({ examples: [['data:read']] }),
-        ),
+        ._default(z.array(z.enum(Scope.catalog.map((entry) => entry.scope))), [])
+        .check(z.describe('Scopes to grant.'), z.meta({ examples: [['data:read']] })),
     })
     .check(z.describe('Fields for minting an API key.'))
 
@@ -153,6 +161,11 @@ export namespace schema {
 
   /** Schemas for the listApiKeys operation. */
   export namespace listApiKeys {
+    /** Query parameters filtering a project's keys. */
+    export const Query = z
+      .strictObject({ environment: Schema.Environment })
+      .check(z.describe("Query parameters for a project's API keys."))
+
     /** Non-paginated list of a project's keys. */
     export const Response = Schema.describe(
       z.object({
@@ -162,6 +175,24 @@ export namespace schema {
     )
   }
 
+  /** Schemas for the listOrgApiKeys operation. */
+  export namespace listOrgApiKeys {
+    /** Query parameters filtering the organization's keys. */
+    export const Query = z
+      .strictObject({ environment: Schema.Environment })
+      .check(z.describe("Query parameters for an organization's API keys."))
+
+    /** Non-paginated list of every key in the organization. */
+    export const Response = Schema.describe(
+      z.object({
+        data: z
+          .array(Key)
+          .check(z.describe("The organization's keys across all projects, newest first.")),
+      }),
+      "A non-paginated list of an organization's API keys (metadata only).",
+    )
+  }
+
   /** Schemas for the revokeApiKey operation. */
   export namespace revokeApiKey {
     /** Confirmation that the key was revoked. */
@@ -179,9 +210,11 @@ export namespace schema {
 }
 
 /**
- * Mounts the `/orgs/:orgId/projects/:projectId/api-keys` resource:
- * project-scoped API keys over the KV state store. Access follows the project
- * scope (owning session or super admin); the token appears once, at mint.
+ * Mounts the `/orgs/:orgId/projects/:projectId/api-keys` resource
+ * (project-scoped mint/list/revoke) plus the org-wide read
+ * `/orgs/:orgId/api-keys`, over the KV state store. Access follows the
+ * org/project scope (owning session or super admin); the token appears once,
+ * at mint.
  */
 export function apiKeys(options: apiKeys.Options = {}) {
   const hidden = !options.enabled
@@ -241,7 +274,9 @@ export function apiKeys(options: apiKeys.Options = {}) {
         const body = c.req.valid('json')
 
         // Sessions mint only self-issuable scopes; the super admin grants the
-        // full catalog.
+        // full catalog. Self-serve covers the whole catalog now that billing
+        // ships, so this is a safety net: a future non-self-serve scope would
+        // be refused here without further changes.
         if (createdBy !== 'super_admin') {
           const denied = body.scopes.filter((scope) => !Scope.selfServe.includes(scope))
           if (denied.length > 0)
@@ -253,11 +288,20 @@ export function apiKeys(options: apiKeys.Options = {}) {
         }
 
         try {
+          const orgId = Auth.org(c).id
+          // Snapshot billing onto the record so the auth path throttles a
+          // sandbox key to the public quota without a per-request billing read.
+          // Only sandbox is gated; production keys carry no snapshot.
+          const billingActive =
+            body.environment === 'sandbox'
+              ? await Billing.active(Db.get(c.get('db')), orgId, 'sandbox')
+              : undefined
           const { record, token } = await ApiKeys.mint(kv.store, {
             createdBy,
             environment: body.environment,
+            ...(billingActive === undefined ? {} : { billingActive }),
             ...(body.name === undefined ? {} : { name: body.name }),
-            orgId: Auth.org(c).id,
+            orgId,
             projectId: Auth.project(c).id,
             scopes: body.scopes,
           })
@@ -279,11 +323,18 @@ export function apiKeys(options: apiKeys.Options = {}) {
         code: 'param_invalid',
         message: 'Check the path parameters and try again.',
       }),
+      OpenApi.validate('query', schema.listApiKeys.Query, {
+        code: 'query_invalid',
+        message: 'Check the query parameters and try again.',
+      }),
       OpenApi.describeRoute({
         hide: hidden,
         operationId: 'listApiKeys',
         responses: OpenApi.responses({
-          errors: { 404: 'No accessible project was found for this id.' },
+          errors: {
+            400: { codes: ['query_invalid'], description: 'Invalid query parameters.' },
+            404: 'No accessible project was found for this id.',
+          },
           success: {
             description: "The project's keys, newest first (metadata only).",
             schema: schema.listApiKeys.Response,
@@ -300,11 +351,17 @@ export function apiKeys(options: apiKeys.Options = {}) {
             code: 'param_invalid',
             message: 'Check the path parameters and try again.',
           })
+        if (OpenApi.narrowValidation)
+          return OpenApi.validationError(c, {
+            code: 'query_invalid',
+            message: 'Check the query parameters and try again.',
+          })
 
         const kv = c.get('kv')
         if (!kv) return notEnabled(c)
         try {
           const records = await ApiKeys.listByOrg(kv.store, Auth.org(c).id, {
+            environment: c.req.valid('query').environment,
             projectId: Auth.project(c).id,
           })
           return c.json(
@@ -318,6 +375,66 @@ export function apiKeys(options: apiKeys.Options = {}) {
         }
       },
     )
+    .get(
+      '/v1/orgs/:orgId{org_[A-Za-z0-9_-]+}/api-keys',
+      Auth.policy({ session: true }),
+      Auth.ensureOrg(),
+      OpenApi.validate('param', schema.OrgParams, {
+        code: 'param_invalid',
+        message: 'Check the path parameters and try again.',
+      }),
+      OpenApi.validate('query', schema.listOrgApiKeys.Query, {
+        code: 'query_invalid',
+        message: 'Check the query parameters and try again.',
+      }),
+      OpenApi.describeRoute({
+        description: 'List every API key in the organization, across all of its projects.',
+        hide: hidden,
+        operationId: 'listOrgApiKeys',
+        responses: OpenApi.responses({
+          errors: {
+            400: { codes: ['query_invalid'], description: 'Invalid query parameters.' },
+            404: 'No accessible organization was found for this id.',
+          },
+          success: {
+            description: "The organization's keys across all projects, newest first (metadata only).", // prettier-ignore
+            schema: schema.listOrgApiKeys.Response,
+          },
+        }),
+        summary: 'List organization API keys',
+        tags: ['API Keys'],
+      }),
+      async (c) => {
+        if (Auth.narrowAccess) return Auth.superAdminAccessError(c)
+        if (Auth.narrowScope) return Auth.ensureOrgError(c)
+        if (OpenApi.narrowValidation)
+          return OpenApi.validationError(c, {
+            code: 'param_invalid',
+            message: 'Check the path parameters and try again.',
+          })
+        if (OpenApi.narrowValidation)
+          return OpenApi.validationError(c, {
+            code: 'query_invalid',
+            message: 'Check the query parameters and try again.',
+          })
+
+        const kv = c.get('kv')
+        if (!kv) return notEnabled(c)
+        try {
+          const records = await ApiKeys.listByOrg(kv.store, Auth.org(c).id, {
+            environment: c.req.valid('query').environment,
+          })
+          return c.json(
+            Response.validated(schema.listOrgApiKeys.Response, {
+              data: records.map(serializeKey),
+            }),
+            200,
+          )
+        } catch (cause) {
+          return Response.upstream(c, cause)
+        }
+      },
+    )
     .delete(
       '/v1/orgs/:orgId{org_[A-Za-z0-9_-]+}/projects/:projectId{prj_[A-Za-z0-9_-]+}/api-keys/:keyId{key_[A-Za-z0-9_-]+}',
       Auth.policy({ session: true }),
@@ -377,7 +494,7 @@ export declare namespace apiKeys {
   }
 }
 
-/** Projects a persisted record onto the platform key shape (no rate limits, no token). */
+/** Projects a persisted record onto the management key shape (no rate limits, no token). */
 function serializeKey(record: ApiKeys.Record) {
   return {
     createdAt: record.createdAt,
@@ -387,8 +504,7 @@ function serializeKey(record: ApiKeys.Record) {
     id: record.id,
     ...(record.name === undefined ? {} : { name: record.name }),
     orgId: record.orgId,
-    // The project filter guarantees attribution; the fallback never renders.
-    projectId: record.projectId ?? '',
+    ...(record.projectId === undefined ? {} : { projectId: record.projectId }),
     scopes: [...record.scopes],
     tokenLast4: record.tokenLast4,
   }