tapimo 0.1.0 → 0.3.0

package/src/apps/platform/routes/api-keys.ts

@@ -0,0 +1,543 @@
+import { type Context, Hono } from 'hono'
+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'
+import * as Scope from '../../../Scope.js'
+
+/** Zod schemas owned by the API-keys resource. */
+export namespace schema {
+  /** One API key: metadata only — the token appears once, at mint. */
+  export const Key = Schema.describe(
+    z.object({
+      createdAt: z
+        .string()
+        .check(
+          z.describe('When the key was minted (ISO 8601).'),
+          z.meta({ examples: ['2026-01-01T00:00:00.000Z'] }),
+        ),
+      createdBy: z
+        .optional(z.string())
+        .check(
+          z.describe('Identity that minted the key (`usr_…`, or `super_admin`).'),
+          z.meta({ examples: ['usr_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
+        ),
+      environment: z
+        .enum(['production', 'sandbox'])
+        .check(z.describe('Key environment.'), z.meta({ examples: ['sandbox'] })),
+      expiresAt: z
+        .optional(z.string())
+        .check(
+          z.describe('When the key expires (ISO 8601). Absent for a non-expiring key.'),
+          z.meta({ examples: ['2027-01-01T00:00:00.000Z'] }),
+        ),
+      id: z
+        .string()
+        .check(
+          z.describe('Opaque key id (`key_…`).'),
+          z.meta({ examples: ['key_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
+        ),
+      name: z
+        .optional(z.string())
+        .check(z.describe('Human-readable key name.'), z.meta({ examples: ['CI'] })),
+      orgId: z
+        .string()
+        .check(
+          z.describe('Owning organization id (`org_…`).'),
+          z.meta({ examples: ['org_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(
+          z.describe(
+            "Granted scopes. '*' (grant-all) appears only on keys minted by the super admin.",
+          ),
+          z.meta({ examples: [['data:read']] }),
+        ),
+      tokenLast4: z
+        .string()
+        .check(
+          z.describe('Last 4 characters of the plaintext token.'),
+          z.meta({ examples: ['a1b2'] }),
+        ),
+    }),
+    'An API key: metadata only — the token appears once, at mint.',
+  )
+
+  /** Path parameters addressing a project's key collection. */
+  export const Params = z
+    .object({
+      orgId: z
+        .string()
+        .check(
+          z.describe('The organization id (`org_…`).'),
+          z.meta({ examples: ['org_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
+        ),
+      projectId: z
+        .string()
+        .check(
+          z.describe('The project id (`prj_…`).'),
+          z.meta({ examples: ['prj_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
+        ),
+    })
+    .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({
+      keyId: z
+        .string()
+        .check(
+          z.describe('The key id (`key_…`).'),
+          z.meta({ examples: ['key_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
+        ),
+      orgId: z
+        .string()
+        .check(
+          z.describe('The organization id (`org_…`).'),
+          z.meta({ examples: ['org_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
+        ),
+      projectId: z
+        .string()
+        .check(
+          z.describe('The project id (`prj_…`).'),
+          z.meta({ examples: ['prj_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
+        ),
+    })
+    .check(z.describe('Path parameters for one API key.'))
+
+  /** Request body minting a key. The wildcard scope is not issuable here. */
+  export const KeyBody = z
+    .object({
+      environment: z
+        ._default(z.enum(['production', 'sandbox']), 'production')
+        .check(z.describe('Key environment.'), z.meta({ examples: ['sandbox'] })),
+      name: z
+        .optional(z.string().check(z.minLength(1), z.maxLength(100)))
+        .check(z.describe('Human-readable key name.'), z.meta({ examples: ['CI'] })),
+      scopes: z
+        ._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.'))
+
+  /** Schemas for the createApiKey operation. */
+  export namespace createApiKey {
+    /** The minted key plus its one-time token. */
+    export const Response = Schema.describe(
+      z.extend(Key, {
+        token: z
+          .string()
+          .check(
+            z.describe('The plaintext token — shown once, unrecoverable afterward.'),
+            z.meta({ examples: ['tempo_sandbox:sk:…'] }),
+          ),
+      }),
+      'The minted key, including its one-time token.',
+    )
+  }
+
+  /** 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({
+        data: z.array(Key).check(z.describe("The project's keys, newest first.")),
+      }),
+      "A non-paginated list of a project's API keys (metadata only).",
+    )
+  }
+
+  /** 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. */
+    export const Response = z
+      .object({
+        id: z
+          .string()
+          .check(
+            z.describe('ID of the key that was revoked.'),
+            z.meta({ examples: ['key_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
+          ),
+      })
+      .check(z.describe('Confirmation that the key was revoked.'))
+  }
+}
+
+/**
+ * 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
+  return new Hono<App.Environment>()
+    .post(
+      '/v1/orgs/:orgId{org_[A-Za-z0-9_-]+}/projects/:projectId{prj_[A-Za-z0-9_-]+}/api-keys',
+      Auth.policy({ session: true }),
+      Auth.ensureOrg({ role: 'admin' }),
+      Auth.ensureProject(),
+      OpenApi.validate('param', schema.Params, {
+        code: 'param_invalid',
+        message: 'Check the path parameters and try again.',
+      }),
+      OpenApi.validate('json', schema.KeyBody, {
+        code: 'body_invalid',
+        message: 'Check the request body and try again.',
+      }),
+      OpenApi.describeRoute({
+        description: 'Mint a project-scoped API key. The token appears once and is never shown again.', // prettier-ignore
+        hide: hidden,
+        operationId: 'createApiKey',
+        responses: OpenApi.responses({
+          errors: {
+            403: {
+              codes: ['scope_not_issuable'],
+              description: 'The requested scopes are not issuable.',
+            },
+            404: 'No accessible project was found for this id.',
+          },
+          success: {
+            description: 'The minted key, including its one-time token.',
+            schema: schema.createApiKey.Response,
+          },
+        }),
+        summary: 'Create API key',
+        tags: ['API Keys'],
+      }),
+      async (c) => {
+        if (Auth.narrowAccess) return Auth.superAdminAccessError(c)
+        if (Auth.narrowScope) return Auth.ensureProjectError(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: 'body_invalid',
+            message: 'Check the request body and try again.',
+          })
+
+        const kv = c.get('kv')
+        if (!kv) return notEnabled(c)
+        const createdBy = mintedBy(c)
+        if (!createdBy) return sessionRequired(c)
+
+        const body = c.req.valid('json')
+
+        // Sessions mint only self-issuable scopes; the super admin grants the
+        // 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)
+            return Response.error(c, {
+              code: 'scope_not_issuable',
+              message: 'The requested scopes are not issuable.',
+              status: 403,
+            })
+        }
+
+        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,
+            projectId: Auth.project(c).id,
+            scopes: body.scopes,
+          })
+          return c.json(
+            Response.validated(schema.createApiKey.Response, { ...serializeKey(record), token }),
+            200,
+          )
+        } catch (cause) {
+          return Response.upstream(c, cause)
+        }
+      },
+    )
+    .get(
+      '/v1/orgs/:orgId{org_[A-Za-z0-9_-]+}/projects/:projectId{prj_[A-Za-z0-9_-]+}/api-keys',
+      Auth.policy({ session: true }),
+      Auth.ensureOrg(),
+      Auth.ensureProject(),
+      OpenApi.validate('param', schema.Params, {
+        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: {
+            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,
+          },
+        }),
+        summary: 'List API keys',
+        tags: ['API Keys'],
+      }),
+      async (c) => {
+        if (Auth.narrowAccess) return Auth.superAdminAccessError(c)
+        if (Auth.narrowScope) return Auth.ensureProjectError(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,
+            projectId: Auth.project(c).id,
+          })
+          return c.json(
+            Response.validated(schema.listApiKeys.Response, {
+              data: records.map(serializeKey),
+            }),
+            200,
+          )
+        } catch (cause) {
+          return Response.upstream(c, cause)
+        }
+      },
+    )
+    .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 }),
+      Auth.ensureOrg({ role: 'admin' }),
+      Auth.ensureProject(),
+      OpenApi.validate('param', schema.KeyParams, {
+        code: 'param_invalid',
+        message: 'Check the path parameters and try again.',
+      }),
+      OpenApi.describeRoute({
+        description: 'Revoke an API key. Requests presenting its token stop resolving.',
+        hide: hidden,
+        operationId: 'revokeApiKey',
+        responses: OpenApi.responses({
+          errors: { 404: 'No accessible API key was found for this id.' },
+          success: {
+            description: 'Confirmation that the key was revoked.',
+            schema: schema.revokeApiKey.Response,
+          },
+        }),
+        summary: 'Revoke API key',
+        tags: ['API Keys'],
+      }),
+      async (c) => {
+        if (Auth.narrowAccess) return Auth.superAdminAccessError(c)
+        if (Auth.narrowScope) return Auth.ensureProjectError(c)
+        if (OpenApi.narrowValidation)
+          return OpenApi.validationError(c, {
+            code: 'param_invalid',
+            message: 'Check the path parameters and try again.',
+          })
+
+        const kv = c.get('kv')
+        if (!kv) return notEnabled(c)
+        const { keyId } = c.req.valid('param')
+        try {
+          // Bind the key to the scoped project before revoking: a key id from
+          // another org or project must be indistinguishable from a missing one.
+          const record = await ApiKeys.get(kv.store, keyId)
+          if (!record || record.orgId !== Auth.org(c).id || record.projectId !== Auth.project(c).id)
+            return keyNotFound(c)
+          const revoked = await ApiKeys.revoke(kv.store, keyId)
+          if (!revoked) return keyNotFound(c)
+          return c.json(Response.validated(schema.revokeApiKey.Response, { id: keyId }), 200)
+        } catch (cause) {
+          return Response.upstream(c, cause)
+        }
+      },
+    )
+}
+
+export declare namespace apiKeys {
+  /** Options for creating the API-keys resource. */
+  type Options = {
+    /** Whether the surface is enabled (a KV state store is configured); disabled routes are hidden and return `404`. */
+    enabled?: boolean | undefined
+  }
+}
+
+/** Projects a persisted record onto the platform key shape (no rate limits, no token). */
+function serializeKey(record: ApiKeys.Record) {
+  return {
+    createdAt: record.createdAt,
+    ...(record.createdBy === undefined ? {} : { createdBy: record.createdBy }),
+    environment: record.environment,
+    ...(record.expiresAt === undefined ? {} : { expiresAt: record.expiresAt }),
+    id: record.id,
+    ...(record.name === undefined ? {} : { name: record.name }),
+    orgId: record.orgId,
+    ...(record.projectId === undefined ? {} : { projectId: record.projectId }),
+    scopes: [...record.scopes],
+    tokenLast4: record.tokenLast4,
+  }
+}
+
+/** The caller identity recorded as `createdBy`, or `undefined` for non-minting principals. */
+function mintedBy(c: Context<App.Environment>) {
+  const principal = Auth.getPrincipal(c)
+  if (principal?.type === 'super_admin') return 'super_admin'
+  if (principal?.type === 'session') return principal.id
+  return undefined
+}
+
+function keyNotFound(c: Context<App.Environment>) {
+  return Response.error(c, {
+    code: 'api_key_not_found',
+    message: 'API key not found',
+    status: 404,
+  })
+}
+
+function notEnabled(c: Context<App.Environment>) {
+  return Response.error(c, {
+    code: 'api_keys_not_enabled',
+    message: 'API keys are not enabled for this Tempo API deployment.',
+    status: 404,
+  })
+}
+
+function sessionRequired(c: Context<App.Environment>) {
+  return Response.error(c, {
+    code: 'forbidden',
+    message: 'Session required',
+    status: 403,
+  })
+}