tapimo 0.0.0 → 0.0.2

package/src/admin/apps/api-keys.test.ts

@@ -0,0 +1,156 @@
+import * as ApiKey from '../../ApiKey.js'
+
+import * as TestAdmin from '../../../test/Admin.js'
+import * as TestApp from '../../../test/App.js'
+import * as ApiKeys from './api-keys.js'
+
+/** Minimal valid mint payload. */
+const validBody = { orgId: 'org_test', scopes: ['data:read'] } as const
+
+describe('POST /api-keys', () => {
+  test('mints a key, returns the token once, persists a hashed record', async () => {
+    const { client, source, store } = TestAdmin.setup()
+    const response = await client['api-keys'].$post({ json: { ...validBody, name: 'CI' } })
+    const body = await TestApp.json(response, ApiKeys.schema.createApiKey.Response)
+
+    expect(response.status).toBe(200)
+    // The plaintext token is returned exactly once, in the documented format.
+    expect(body.token).toMatch(/^tempo:sk:[a-f0-9]{48}$/)
+    // createdBy is the verified admin email, not anything the client sent.
+    expect(body.createdBy).toBe(TestAdmin.identity.email)
+    expect(TestAdmin.redact(body)).toMatchInlineSnapshot(`
+      {
+        "createdAt": "<createdAt>",
+        "createdBy": "admin@tempo.xyz",
+        "environment": "production",
+        "id": "<id>",
+        "name": "CI",
+        "orgId": "org_test",
+        "scopes": [
+          "data:read",
+        ],
+        "token": "<token>",
+        "tokenLast4": "<tokenLast4>",
+      }
+    `)
+
+    // The token resolves through the source (proving the record persisted),
+    // and at rest it is keyed by the token hash — never the plaintext token.
+    const resolved = await source.resolve(body.token)
+    expect(resolved?.orgId).toBe('org_test')
+    expect(await store.get(body.token)).toBeNull()
+    expect(await store.get(ApiKey.keyFor(body.token))).not.toBeNull()
+  })
+
+  test('defaults to the production environment', async () => {
+    const { client, source } = TestAdmin.setup()
+    const response = await client['api-keys'].$post({ json: validBody })
+    const body = await TestApp.json(response, ApiKeys.schema.createApiKey.Response)
+
+    expect(response.status).toBe(200)
+    expect(body.environment).toBe('production')
+    expect((await source.list())[0]?.environment).toBe('production')
+  })
+
+  test('persists a sandbox environment when provided', async () => {
+    const { client, source } = TestAdmin.setup()
+    const response = await client['api-keys'].$post({
+      json: { ...validBody, environment: 'sandbox' },
+    })
+    const body = await TestApp.json(response, ApiKeys.schema.createApiKey.Response)
+
+    expect(response.status).toBe(200)
+    expect(body.environment).toBe('sandbox')
+    // Sandbox tokens carry a distinct prefix for recognizability/leak detection.
+    expect(body.token).toMatch(/^tempo_sandbox:sk:[a-f0-9]{48}$/)
+    const resolved = await source.resolve(body.token)
+    expect(resolved?.environment).toBe('sandbox')
+  })
+
+  test('records the expiry when provided', async () => {
+    const { client, source } = TestAdmin.setup()
+    const expiresAt = '2100-01-01T00:00:00.000Z'
+    const response = await client['api-keys'].$post({ json: { ...validBody, expiresAt } })
+    const body = await TestApp.json(response, ApiKeys.schema.createApiKey.Response)
+
+    expect(response.status).toBe(200)
+    expect(body.expiresAt).toBe(expiresAt)
+    expect((await source.list())[0]?.expiresAt).toBe(expiresAt)
+  })
+
+  test('rejects an unknown scope with 400', async () => {
+    const { client } = TestAdmin.setup()
+    const response = await client['api-keys'].$post({
+      // Cast past the typed client to exercise runtime validation.
+      json: { ...validBody, scopes: ['nope:read'] } as never,
+    })
+    const body = (await response.json()) as { error?: { code?: string } }
+
+    expect(response.status).toMatchInlineSnapshot(`400`)
+    expect(body.error?.code).toMatchInlineSnapshot(`"body_invalid"`)
+  })
+
+  test('ignores a client-supplied createdBy (audit trail is server-set)', async () => {
+    const { client } = TestAdmin.setup()
+    const response = await client['api-keys'].$post({
+      // Cast past the typed client: the body schema omits createdBy, so an
+      // unknown key is stripped and the server records the verified identity.
+      json: { ...validBody, createdBy: 'spoof@example.com' } as never,
+    })
+    const body = await TestApp.json(response, ApiKeys.schema.createApiKey.Response)
+
+    expect(response.status).toBe(200)
+    expect(body.createdBy).toBe(TestAdmin.identity.email)
+  })
+})
+
+describe('GET /api-keys', () => {
+  test('lists records as metadata only (never the token)', async () => {
+    const { client, source } = TestAdmin.setup()
+    const { token } = await source.mint(validBody)
+
+    const response = await client['api-keys'].$get({ query: {} })
+    const body = await TestApp.json(response, ApiKeys.schema.listApiKeys.Response)
+
+    expect(response.status).toBe(200)
+    expect(body.data).toHaveLength(1)
+    // No record (and no serialized response) may carry the plaintext token.
+    expect(body.data[0]).not.toHaveProperty('token')
+    expect(JSON.stringify(body)).not.toContain(token)
+  })
+
+  test('filters by orgId', async () => {
+    const { client, source } = TestAdmin.setup()
+    await source.mint({ orgId: 'org_a', scopes: ['data:read'] })
+    await source.mint({ orgId: 'org_b', scopes: ['data:read'] })
+
+    const response = await client['api-keys'].$get({ query: { orgId: 'org_a' } })
+    const body = await TestApp.json(response, ApiKeys.schema.listApiKeys.Response)
+
+    expect(body.data.map((record) => record.orgId)).toEqual(['org_a'])
+  })
+})
+
+describe('DELETE /api-keys/:id', () => {
+  test('revokes a key, after which it no longer resolves or lists', async () => {
+    const { client, source } = TestAdmin.setup()
+    const { record, token } = await source.mint(validBody)
+
+    const response = await client['api-keys'][':id'].$delete({ param: { id: record.id } })
+    const body = await TestApp.json(response, ApiKeys.schema.revokeApiKey.Response)
+
+    expect(response.status).toBe(200)
+    expect(body).toEqual({ id: record.id })
+    expect(await source.resolve(token)).toBeNull()
+    expect(await source.list()).toEqual([])
+  })
+
+  test('unknown id → 404', async () => {
+    const { client } = TestAdmin.setup()
+    const response = await client['api-keys'][':id'].$delete({ param: { id: 'key_missing' } })
+    const body = (await response.json()) as { error?: { code?: string } }
+
+    expect(response.status).toMatchInlineSnapshot(`404`)
+    expect(body.error?.code).toMatchInlineSnapshot(`"not_found"`)
+  })
+})

package/src/admin/apps/api-keys.ts

@@ -0,0 +1,157 @@
+import { Hono } from 'hono'
+import * as z from 'zod/mini'
+
+import * as ApiKeySource from '../../ApiKeySource.js'
+import * as OpenApi from '../../internal/OpenApi.js'
+import * as Response from '../../internal/Response.js'
+import * as Schema from '../../internal/Schema.js'
+import type * as App from '../App.js'
+
+/** Zod schemas owned by the admin API-keys handler. */
+export namespace schema {
+  /** Schemas for the createApiKey operation. */
+  export namespace createApiKey {
+    /**
+     * Request body for minting a key (`MintInput` minus `createdBy`, which the
+     * server sets from the verified identity so it can't be spoofed).
+     */
+    export const Body = Schema.describe(
+      z.omit(ApiKeySource.schema.MintInput, { createdBy: true }),
+      'Fields accepted when minting an API key.',
+    )
+
+    /** Response: the record plus the one-time plaintext token. */
+    export const Response = Schema.describe(
+      z.extend(ApiKeySource.schema.Record, {
+        token: z
+          .string()
+          .check(z.describe('The plaintext token, shown once and unrecoverable afterward.')),
+      }),
+      'A minted API key, including its one-time token.',
+    )
+  }
+
+  /** Schemas for the listApiKeys operation. */
+  export namespace listApiKeys {
+    /** Query parameters for listing keys. */
+    export const Query = z
+      .object({
+        orgId: z
+          .optional(z.string())
+          .check(z.describe('Restrict results to keys owned by this organization.')),
+      })
+      .check(z.describe('Query parameters for listing API keys.'))
+
+    /** Response body: a list of key records (metadata only — never tokens). */
+    export const Response = Schema.describe(
+      z.object({
+        data: z
+          .array(ApiKeySource.schema.Record)
+          .check(z.describe('API-key records, newest first (metadata only — never tokens).')),
+      }),
+      'A list of API-key records.',
+    )
+  }
+
+  /** Schemas for the revokeApiKey operation. */
+  export namespace revokeApiKey {
+    /** Path parameters for revoking a key. */
+    export const Params = z
+      .object({
+        id: z.string().check(z.describe('Stable id of the key to revoke.')),
+      })
+      .check(z.describe('Path parameters for revoking an API key.'))
+
+    /** Response body for a successful revocation. */
+    export const Response = z
+      .object({ id: z.string().check(z.describe('Revoked key id.')) })
+      .check(z.describe('API-key revocation result.'))
+  }
+}
+
+/**
+ * Provisioning routes for API keys, backed by the request's
+ * {@link App.Environment} `source`:
+ *
+ * - `POST /` mints a key, recording `createdBy` from the verified identity and
+ *   returning the one-time token.
+ * - `GET /` lists key records (metadata only), optionally filtered by `orgId`.
+ * - `DELETE /:id` revokes a key by id (`404` if absent).
+ */
+export function apiKeys() {
+  return new Hono<App.Environment>()
+    .post(
+      '/',
+      OpenApi.validate('json', schema.createApiKey.Body, {
+        code: 'body_invalid',
+        message: 'Invalid request body',
+      }),
+      OpenApi.describeRoute({
+        operationId: 'createApiKey',
+        responses: OpenApi.responses({
+          success: {
+            description: 'Minted key (includes the one-time token).',
+            schema: schema.createApiKey.Response,
+          },
+        }),
+        summary: 'Create API key',
+        tags: ['API keys'],
+      }),
+      async (c) => {
+        // `createdBy` is the verified admin email, never client-supplied.
+        // `requireAuth` guarantees identity on this gated route.
+        const { record, token } = await c.get('source').mint({
+          ...c.req.valid('json'),
+          createdBy: c.get('identity')!.email,
+        })
+        return c.json(Response.validated(schema.createApiKey.Response, { ...record, token }))
+      },
+    )
+    .get(
+      '/',
+      OpenApi.validate('query', schema.listApiKeys.Query, {
+        code: 'query_invalid',
+        message: 'Invalid query parameters',
+      }),
+      OpenApi.describeRoute({
+        operationId: 'listApiKeys',
+        responses: OpenApi.responses({
+          success: { description: 'API-key records.', schema: schema.listApiKeys.Response },
+        }),
+        summary: 'List API keys',
+        tags: ['API keys'],
+      }),
+      async (c) => {
+        const { orgId } = c.req.valid('query')
+        const data = await c.get('source').list(orgId ? { orgId } : {})
+        return c.json(Response.validated(schema.listApiKeys.Response, { data }))
+      },
+    )
+    .delete(
+      '/:id',
+      OpenApi.validate('param', schema.revokeApiKey.Params, {
+        code: 'param_invalid',
+        message: 'Invalid path parameters',
+      }),
+      OpenApi.describeRoute({
+        operationId: 'revokeApiKey',
+        responses: OpenApi.responses({
+          errors: { 404: 'API key not found.' },
+          success: { description: 'Key revoked.', schema: schema.revokeApiKey.Response },
+        }),
+        summary: 'Revoke API key',
+        tags: ['API keys'],
+      }),
+      async (c) => {
+        const { id } = c.req.valid('param')
+        const revoked = await c.get('source').revoke(id)
+        if (!revoked)
+          return Response.error(c, {
+            code: 'not_found',
+            message: 'API key not found.',
+            status: 404,
+          })
+        return c.json(Response.validated(schema.revokeApiKey.Response, { id }))
+      },
+    )
+}

package/src/admin/apps/scopes.test.ts

@@ -0,0 +1,52 @@
+import * as Scope from '../../Scope.js'
+
+import * as TestAdmin from '../../../test/Admin.js'
+import * as TestApp from '../../../test/App.js'
+import * as Scopes from './scopes.js'
+
+describe('GET /scopes', () => {
+  test('serves the issuable scope catalog', async () => {
+    const { client } = TestAdmin.setup()
+    const response = await client.scopes.$get()
+    const body = await TestApp.json(response, Scopes.schema.getScopes.Response)
+
+    expect(response.status).toBe(200)
+    expect(body).toMatchInlineSnapshot(`
+      {
+        "data": [
+          {
+            "description": "Read public chain data: tokens, transactions, transfers, blocks, and receipts.",
+            "scope": "data:read",
+          },
+          {
+            "description": "Run ad-hoc queries against the raw indexer passthrough.",
+            "scope": "indexer:query",
+          },
+          {
+            "description": "Read webhook subscriptions.",
+            "scope": "webhooks:read",
+          },
+          {
+            "description": "Create, update, and delete webhook subscriptions.",
+            "scope": "webhooks:write",
+          },
+        ],
+      }
+    `)
+  })
+
+  test('serves the Scope.catalog source of truth verbatim', async () => {
+    const { client } = TestAdmin.setup()
+    const response = await client.scopes.$get()
+    const body = await TestApp.json(response, Scopes.schema.getScopes.Response)
+
+    expect(body.data).toEqual(Scope.catalog)
+  })
+
+  test('is never cached (admin responses are per-principal)', async () => {
+    const { client } = TestAdmin.setup()
+    const response = await client.scopes.$get()
+
+    expect(response.headers.get('cache-control')).toMatchInlineSnapshot(`"no-store"`)
+  })
+})

package/src/admin/apps/scopes.ts

@@ -0,0 +1,47 @@
+import { Hono } from 'hono'
+import * as z from 'zod/mini'
+
+import * as OpenApi from '../../internal/OpenApi.js'
+import * as Scope from '../../Scope.js'
+import type * as App from '../App.js'
+
+/** Zod schemas owned by the admin scope catalog handler. */
+export namespace schema {
+  /** Schemas for the getAdminScopes operation. */
+  export namespace getScopes {
+    /** A single issuable API-key scope. */
+    export const Scope = z
+      .object({
+        description: z
+          .string()
+          .check(z.describe('Human-readable explanation of what the scope grants.')),
+        scope: z
+          .string()
+          .check(z.describe('Scope identifier used in API-key grants and route policies.')),
+      })
+      .check(z.describe('A single issuable API-key scope.'))
+
+    /** Response body for the scope catalog. */
+    export const Response = z
+      .object({
+        data: z.array(Scope).check(z.describe('Issuable API-key scopes.')),
+      })
+      .check(z.describe('Response body for the scope catalog.'))
+  }
+}
+
+/** Catalog of issuable API-key scopes, served from {@link Scope.catalog}. */
+export function scopes() {
+  return new Hono<App.Environment>().get(
+    '/',
+    OpenApi.describeRoute({
+      operationId: 'getAdminScopes',
+      responses: OpenApi.responses({
+        success: { description: 'Issuable scope catalog.', schema: schema.getScopes.Response },
+      }),
+      summary: 'List scopes',
+      tags: ['Scopes'],
+    }),
+    (c) => c.json({ data: Scope.catalog }),
+  )
+}