tapimo 0.4.1 → 0.4.4

package/src/App.ts

@@ -19,6 +19,7 @@ import * as OpenApi from './internal/OpenApi.js'
 import * as Store from './internal/Store.js'
 import * as Path from './internal/Path.js'
 import * as Response from './internal/Response.js'
+import * as Scope from './Scope.js'
 import type * as Tidx from './internal/Tidx.js'
 import * as Timing from './internal/Timing.js'
 import * as Viem from './internal/Viem.js'
@@ -53,6 +54,8 @@ export type Environment = {
       dbCached: Db.Source
       /** KV state store backing API-key records, or undefined when key auth is closed. */
       kv: { store: Store.State } | undefined
+      /** Issuable API-key scope catalog, including host-defined entries. */
+      scopeCatalog: Scope.Catalog
       /** Gets one static API asset. */
       getAsset: GetAsset
       /** Gets a Tempo RPC client for a chain id. */
@@ -83,6 +86,11 @@ export type Environment = {
  */
 export type App = ReturnType<typeof compose>
 
+/** Defines an external route group with metadata collected by {@link create}. */
+export function from<const app extends Hono<any, any>>(app: app, metadata: create.Metadata): app {
+  return Metadata.attach(app, metadata)
+}
+
 // Type anchor only — never invoked. Expresses the canonical composition so
 // `App` (and thus `Client`) reflect the full route surface; real consumers
 // compose explicitly.
@@ -138,6 +146,7 @@ export function create<const path extends string = '/'>(options: create.Options<
   // Authoritative state lives elsewhere: webhooks + verified tokens in
   // `options.db`, API-key records in `options.kv`.
   const store = options.cache?.store ?? Store.memory()
+  const scopeCatalog = Scope.extend(options.scopes)
 
   // Build the app in two phases: register middleware imperatively, then chain
   // route mounts so the merged Hono schema flows through the return type. The
@@ -211,7 +220,12 @@ export function create<const path extends string = '/'>(options: create.Options<
 
   // Built-in auth: the session surface (mounted last) plus the enforcement
   // middleware (installed below), wired together in `Auth.install`.
-  const auth = Auth.install({ auth: options.auth, db: db.source, kv: options.kv })
+  const auth = Auth.install({
+    auth: options.auth,
+    db: db.source,
+    kv: options.kv,
+    scopeCatalog,
+  })
 
   base.use('*', Timing.middleware())
   base.use('*', async (c, next) => {
@@ -220,6 +234,7 @@ export function create<const path extends string = '/'>(options: create.Options<
     c.set('db', db.source)
     c.set('dbCached', db.cached ?? db.source)
     c.set('kv', options.kv)
+    c.set('scopeCatalog', scopeCatalog)
     c.set('store', store)
     await next()
   })
@@ -331,6 +346,13 @@ export function create<const path extends string = '/'>(options: create.Options<
               scheme: 'bearer',
               type: 'http',
             },
+            queryApiKey: {
+              description:
+                'Supported query-string alternative for API keys. Prefer `tempo-api-key` because URLs may be logged by clients and infrastructure.',
+              in: 'query',
+              name: 'key',
+              type: 'apiKey',
+            },
             ...contributedSchemes,
           },
         },
@@ -339,7 +361,7 @@ export function create<const path extends string = '/'>(options: create.Options<
           title: 'Tempo API',
           version: '1.0.0',
         },
-        security: [{ apiKey: [] }, { bearerAuth: [] }],
+        security: [{ apiKey: [] }, { queryApiKey: [] }, { bearerAuth: [] }],
         servers: [
           ...(options.servers ?? [
             { url: basePath || '/', description: 'Relative to the host serving this document.' },
@@ -441,6 +463,8 @@ export declare namespace create {
     path?: path | undefined
     /** OpenAPI `servers` for the generated document. Defaults to a single relative server (the host serving the doc), so the reference targets the deployment it is served from. Set the canonical public URL(s) here, e.g. `[{ url: 'https://api.tempo.xyz' }]`. */
     servers?: readonly Server[] | undefined
+    /** Host-defined API-key scopes appended to the built-in {@link Scope.catalog}. */
+    scopes?: readonly Scope.Entry[] | undefined
   }
 
   /** KV state-store configuration. */
@@ -601,12 +625,8 @@ function sortPaths(paths: PathsObject): PathsObject {
 }
 
 /**
- * Sets per-operation `security` and the `402` payment-challenge response from
- * each route's resolved access lanes (see {@link Auth.describeAccess}).
- * Security options compose from the enabled lanes — API keys (header +
- * bearer), sessions (cookie + bearer token), anonymous (`{}`) — and the `402`
- * response is emitted only where the MPP lane is enabled; required API-key
- * scopes are surfaced as the `x-required-scopes` extension.
+ * Applies route security, required scopes, and payment responses from resolved access lanes.
+ * API keys support header, query, and bearer authentication.
  */
 function applyAccess(paths: PathsObject, access: Record<string, Auth.OperationAccess>) {
   for (const item of Object.values(paths)) {
@@ -615,7 +635,7 @@ function applyAccess(paths: PathsObject, access: Record<string, Auth.OperationAc
       const lanes = access[op.operationId]
       if (!lanes) continue
       const security = [
-        ...(lanes.apiKey ? [{ apiKey: [] }, { bearerAuth: [] }] : []),
+        ...(lanes.apiKey ? [{ apiKey: [] }, { queryApiKey: [] }, { bearerAuth: [] }] : []),
         ...(lanes.session ? [{ session: [] }, ...(lanes.apiKey ? [] : [{ bearerAuth: [] }])] : []),
         ...(lanes.public ? [{}] : []),
       ]

package/src/Assets.ts

@@ -26,6 +26,9 @@ export type Assets = {
 export function cloudflareR2(bucket: cloudflareR2.Bucket): Assets {
   return {
     async get(key) {
+      // Exact keys sort first, so expected misses avoid `NoSuchKey` spans.
+      const { objects } = await bucket.list({ limit: 1, prefix: key })
+      if (objects[0]?.key !== key) return undefined
       const object = await bucket.get(key)
       if (!object) return undefined
       return {
@@ -48,6 +51,11 @@ export declare namespace cloudflareR2 {
       /** HTTP metadata stored with the object. */
       httpMetadata?: { contentType?: string | undefined } | undefined
     } | null>
+    /** Lists objects matching a key prefix. */
+    list(options: { limit: number; prefix: string }): Promise<{
+      /** Matching objects. */
+      objects: readonly { key: string }[]
+    }>
     /** Writes an object. */
     put(
       key: string,

package/src/Auth.test-d.ts

@@ -0,0 +1,36 @@
+import { Hono } from 'hono'
+import { testClient } from 'hono/testing'
+import { expectTypeOf } from 'vite-plus/test'
+import { App, Auth } from 'tapimo'
+
+describe('Auth', () => {
+  test('exports the external route-authoring surface', () => {
+    expectTypeOf(Auth.policy).toBeFunction()
+    expectTypeOf(Auth.ensureOrg).toBeFunction()
+    expectTypeOf(Auth.ensureProject).toBeFunction()
+    expectTypeOf<Auth.PolicyOverride>().toMatchTypeOf<{
+      apiKey?: { scopes?: readonly string[] | undefined } | boolean | undefined
+    }>()
+    expectTypeOf<Auth.Principal['type']>().toEqualTypeOf<
+      'api_key' | 'public' | 'session' | 'super_admin'
+    >()
+  })
+
+  test('preserves route response unions', async () => {
+    const app = new Hono<App.Environment>().get(
+      '/v1/projects/:projectId',
+      Auth.policy({ apiKey: true }),
+      Auth.ensureProject(),
+      (c) => {
+        if (Auth.narrowAccess) return Auth.accessError(c)
+        if (Auth.narrowScope) return Auth.ensureProjectError(c)
+        return c.json({ id: Auth.project(c).id }, 200)
+      },
+    )
+    const response = await testClient(app).v1.projects[':projectId'].$get({
+      param: { projectId: 'prj_test' },
+    })
+
+    expectTypeOf(response.status).toEqualTypeOf<200 | 400 | 401 | 403 | 404 | 429>()
+  })
+})

package/src/Auth.ts

@@ -1 +1,20 @@
-export { middleware } from './internal/Auth.js'
+/** Supported authentication helpers for external route groups. */
+export {
+  accessError,
+  ensureOrg,
+  ensureOrgError,
+  ensureProject,
+  ensureProjectError,
+  getPrincipal,
+  membership,
+  middleware,
+  narrowAccess,
+  narrowScope,
+  org,
+  paidAccessError,
+  policy,
+  project,
+  superAdminAccessError,
+  type PolicyOverride,
+  type Principal,
+} from './internal/Auth.js'

package/src/Client.test-d.ts

@@ -182,7 +182,7 @@ describe('narrows responses by status', () => {
       param: { orgId: 'org_test' },
     })
 
-    expectTypeOf(res.status).toEqualTypeOf<200 | 400 | 401 | 403 | 404>()
+    expectTypeOf(res.status).toEqualTypeOf<200 | 404 | PublicAccessStatus>()
 
     switch (res.status) {
       case 200: {
@@ -206,7 +206,7 @@ describe('narrows responses by status', () => {
       param: { orgId: 'org_test' },
     })
 
-    expectTypeOf(res.status).toEqualTypeOf<200 | 400 | 401 | 403 | 404 | 501 | 502>()
+    expectTypeOf(res.status).toEqualTypeOf<200 | 404 | 501 | 502 | PublicAccessStatus>()
 
     switch (res.status) {
       case 200: {
@@ -230,7 +230,7 @@ describe('narrows responses by status', () => {
       param: { orgId: 'org_test' },
     })
 
-    expectTypeOf(res.status).toEqualTypeOf<200 | 400 | 401 | 403 | 404 | 502>()
+    expectTypeOf(res.status).toEqualTypeOf<200 | 404 | 502 | PublicAccessStatus>()
 
     switch (res.status) {
       case 200: {
@@ -257,7 +257,7 @@ describe('narrows responses by status', () => {
       param: { orgId: 'org_test' },
     })
 
-    expectTypeOf(res.status).toEqualTypeOf<200 | 400 | 401 | 403 | 404 | 501 | 502>()
+    expectTypeOf(res.status).toEqualTypeOf<200 | 404 | 501 | 502 | PublicAccessStatus>()
 
     switch (res.status) {
       case 200: {
@@ -284,7 +284,7 @@ describe('narrows responses by status', () => {
       param: { orgId: 'org_test' },
     })
 
-    expectTypeOf(res.status).toEqualTypeOf<200 | 400 | 401 | 403 | 404 | 501 | 502>()
+    expectTypeOf(res.status).toEqualTypeOf<200 | 404 | 501 | 502 | PublicAccessStatus>()
 
     switch (res.status) {
       case 200: {
@@ -310,7 +310,7 @@ describe('narrows responses by status', () => {
       param: { orgId: 'org_test' },
     })
 
-    expectTypeOf(res.status).toEqualTypeOf<200 | 400 | 401 | 403 | 404 | 501 | 502>()
+    expectTypeOf(res.status).toEqualTypeOf<200 | 404 | 501 | 502 | PublicAccessStatus>()
 
     switch (res.status) {
       case 200: {
@@ -338,7 +338,7 @@ describe('narrows responses by status', () => {
       ':methodId{pm_[A-Za-z0-9_-]+}'
     ].$delete({ param: { methodId: 'pm_test', orgId: 'org_test' } })
 
-    expectTypeOf(res.status).toEqualTypeOf<200 | 400 | 401 | 403 | 404 | 501 | 502>()
+    expectTypeOf(res.status).toEqualTypeOf<200 | 404 | 501 | 502 | PublicAccessStatus>()
 
     switch (res.status) {
       case 200: {
@@ -364,7 +364,7 @@ describe('narrows responses by status', () => {
       param: { orgId: 'org_test' },
     })
 
-    expectTypeOf(res.status).toEqualTypeOf<200 | 400 | 401 | 403 | 404 | 502>()
+    expectTypeOf(res.status).toEqualTypeOf<200 | 404 | 502 | PublicAccessStatus>()
 
     switch (res.status) {
       case 200: {
@@ -388,7 +388,7 @@ describe('narrows responses by status', () => {
       ':projectId{prj_[A-Za-z0-9_-]+}'
     ].$get({ param: { orgId: 'org_test', projectId: 'prj_test' } })
 
-    expectTypeOf(res.status).toEqualTypeOf<200 | 400 | 401 | 403 | 404>()
+    expectTypeOf(res.status).toEqualTypeOf<200 | 404 | PublicAccessStatus>()
 
     switch (res.status) {
       case 200: {
@@ -414,7 +414,7 @@ describe('narrows responses by status', () => {
       ':projectId{prj_[A-Za-z0-9_-]+}'
     ].$delete({ param: { orgId: 'org_test', projectId: 'prj_test' } })
 
-    expectTypeOf(res.status).toEqualTypeOf<200 | 400 | 401 | 403 | 404 | 502>()
+    expectTypeOf(res.status).toEqualTypeOf<200 | 404 | 502 | PublicAccessStatus>()
 
     switch (res.status) {
       case 200: {
@@ -464,7 +464,7 @@ describe('narrows responses by status', () => {
       param: { orgId: 'org_test' },
     })
 
-    expectTypeOf(res.status).toEqualTypeOf<200 | 400 | 401 | 403 | 404 | 502>()
+    expectTypeOf(res.status).toEqualTypeOf<200 | 404 | 502 | PublicAccessStatus>()
 
     switch (res.status) {
       case 200: {
@@ -487,7 +487,7 @@ describe('narrows responses by status', () => {
       param: { keyId: 'key_test', orgId: 'org_test', projectId: 'prj_test' },
     })
 
-    expectTypeOf(res.status).toEqualTypeOf<200 | 400 | 401 | 403 | 404 | 502>()
+    expectTypeOf(res.status).toEqualTypeOf<200 | 404 | 502 | PublicAccessStatus>()
 
     switch (res.status) {
       case 404: {
@@ -511,7 +511,7 @@ describe('narrows responses by status', () => {
       query: { projectId: 'prj_test' },
     })
 
-    expectTypeOf(res.status).toEqualTypeOf<200 | 400 | 401 | 403 | 404 | 501 | 502>()
+    expectTypeOf(res.status).toEqualTypeOf<200 | 404 | 501 | 502 | PublicAccessStatus>()
 
     switch (res.status) {
       case 200: {
@@ -545,7 +545,7 @@ describe('narrows responses by status', () => {
       param: { orgId: 'org_test' },
     })
 
-    expectTypeOf(res.status).toEqualTypeOf<200 | 400 | 401 | 403 | 404 | 502>()
+    expectTypeOf(res.status).toEqualTypeOf<200 | 404 | 502 | PublicAccessStatus>()
 
     switch (res.status) {
       case 200: {
@@ -563,7 +563,7 @@ describe('narrows responses by status', () => {
       ':userId{usr_[A-Za-z0-9_-]+}'
     ].$patch({ json: { role: 'admin' }, param: { orgId: 'org_test', userId: 'usr_test' } })
 
-    expectTypeOf(res.status).toEqualTypeOf<200 | 400 | 401 | 403 | 404 | 409 | 502>()
+    expectTypeOf(res.status).toEqualTypeOf<200 | 404 | 409 | 502 | PublicAccessStatus>()
 
     switch (res.status) {
       case 409: {
@@ -627,7 +627,7 @@ describe('narrows responses by status', () => {
     const client = Client.create()
     const res = await client.v1.orgs.$get()
 
-    expectTypeOf(res.status).toEqualTypeOf<200 | 400 | 401 | 403 | 502>()
+    expectTypeOf(res.status).toEqualTypeOf<200 | 502 | PublicAccessStatus>()
 
     switch (res.status) {
       case 200: {
@@ -640,7 +640,7 @@ describe('narrows responses by status', () => {
       }
       case 403: {
         const json = await res.json()
-        expectTypeOf(json.error.code).toEqualTypeOf<'forbidden'>()
+        expectTypeOf(json.error.code).toEqualTypeOf<'api_key_forbidden'>()
         expectTypeOf(json.error.message).toEqualTypeOf<string>()
         void json
         return

package/src/Scope.test.ts

@@ -0,0 +1,34 @@
+import * as Scope from './Scope.js'
+
+describe('extend', () => {
+  test('appends host scopes to the built-in catalog', () => {
+    expect(
+      Scope.extend([
+        {
+          description: 'Read project accounts.',
+          scope: 'accounts:read',
+          selfServe: true,
+        },
+      ]),
+    ).toEqual([
+      ...Scope.catalog,
+      {
+        description: 'Read project accounts.',
+        scope: 'accounts:read',
+        selfServe: true,
+      },
+    ])
+  })
+
+  test('rejects duplicate scope identifiers', () => {
+    expect(() =>
+      Scope.extend([
+        {
+          description: 'Duplicate data scope.',
+          scope: 'data:read',
+          selfServe: true,
+        },
+      ]),
+    ).toThrowErrorMatchingInlineSnapshot(`[Error: Duplicate scope \`data:read\`.]`)
+  })
+})

package/src/Scope.ts

@@ -1,8 +1,7 @@
 /**
- * The issuable API-key scope vocabulary: the single source of truth for the
- * `/scopes` catalog, for key minting (`ApiKeys.mint`), and for the scopes
- * required by route policies (`Auth.policy`). Exposing it publicly lets super
- * admin tooling validate scopes against the same list the server enforces.
+ * The built-in API-key scope vocabulary. Hosts append entries through
+ * `App.create({ scopes })`; the merged catalog drives discovery, minting, and
+ * API-key validation.
  */
 
 /**
@@ -13,20 +12,18 @@
 export const wildcard = '*'
 
 /** Catalog entry describing an issuable API-key scope. */
-type Entry = {
+export type Entry = {
   /** Human-readable explanation of what the scope grants. */
   description: string
   /** Scope identifier used in a key's `scopes` and in route policies. */
   scope: string
-  /** Whether a session may self-mint this scope (else super-admin-only). */
+  /** Whether an eligible session may self-mint this scope (else super-admin-only). */
   selfServe: boolean
 }
 
 /**
- * The issuable API-key scope vocabulary — the single source of truth for the
- * `/scopes` catalog and for key minting. Route policies require values from this
- * set; {@link wildcard} (`'*'`) is an implicit grant-all and is intentionally
- * not listed as an issuable scope.
+ * The built-in issuable API-key scopes. {@link wildcard} (`'*'`) is an implicit
+ * grant-all and is intentionally not listed as an issuable scope.
  */
 export const catalog = [
   {
@@ -39,6 +36,17 @@ export const catalog = [
     scope: 'indexer:query',
     selfServe: true,
   },
+  {
+    description: 'Read organization resources across projects and environments.',
+    scope: 'management:read',
+    selfServe: true,
+  },
+  {
+    description:
+      'Create, update, and delete organization resources across projects and environments.',
+    scope: 'management:write',
+    selfServe: true,
+  },
   {
     description: 'Fill and submit transactions through the relay.',
     scope: 'rpc-relay:read',
@@ -61,16 +69,44 @@ export const catalog = [
   },
 ] as const satisfies readonly Entry[]
 
-/** Issuable API-key scope identifier — the union of every {@link catalog} entry. */
-export type Id = (typeof catalog)[number]['scope']
+/** Issuable API-key scope identifier, including host-defined scopes. */
+export type Id = (typeof catalog)[number]['scope'] | (string & {})
+
+/** Scope catalog used by API-key issuance and discovery. */
+export type Catalog = readonly Entry[]
 
 /**
- * Scopes a session may self-mint through the developer platform, derived from
- * the catalog's `selfServe` flag. Paid usage (mainnet sponsorship) is gated by
- * an active billing source at request time, so self-serve users cannot consume
- * paid APIs for free. Webhooks stay super-admin-only, as does {@link wildcard}
- * (intentionally absent from the catalog).
+ * Scopes an eligible session may self-mint through the developer platform,
+ * derived from the catalog's `selfServe` flag. Route-specific ownership rules
+ * may narrow issuance. Webhooks and {@link wildcard} stay super-admin-only.
  */
 export const selfServe: readonly Id[] = catalog
   .filter((entry) => entry.selfServe)
   .map((entry) => entry.scope)
+
+/**
+ * Extends the built-in catalog with host-defined scopes.
+ *
+ * @param entries - Host-defined scope entries.
+ * @returns The merged scope catalog.
+ */
+export function extend(entries: readonly Entry[] = []): Catalog {
+  const identifiers = new Set<string>()
+  const result = [...catalog, ...entries]
+  for (const entry of result) {
+    if (!entry.scope.trim()) throw new Error('Scope identifier must not be empty.')
+    if (identifiers.has(entry.scope)) throw new Error(`Duplicate scope \`${entry.scope}\`.`)
+    identifiers.add(entry.scope)
+  }
+  return result
+}
+
+/** Returns whether a catalog contains a scope identifier. */
+export function includes(catalog: Catalog, scope: string): scope is Id {
+  return catalog.some((entry) => entry.scope === scope)
+}
+
+/** Returns the self-issuable identifiers in a scope catalog. */
+export function selfServeFrom(catalog: Catalog): readonly Id[] {
+  return catalog.filter((entry) => entry.selfServe).map((entry) => entry.scope)
+}

package/src/admin/App.test.ts

@@ -18,6 +18,10 @@ describe('create', () => {
           method: 'POST',
         }),
         new Request('http://admin/api-keys/key_x', { method: 'DELETE' }),
+        new Request('http://admin/organizations'),
+        new Request('http://admin/organizations/org_x'),
+        new Request('http://admin/organizations/org_x/members'),
+        new Request('http://admin/organizations/org_x/projects'),
         new Request('http://admin/verified-tokens?chainId=42431', {
           body: JSON.stringify({ tokens: [] }),
           headers: { 'content-type': 'application/json' },
@@ -67,13 +71,37 @@ describe('create', () => {
   describe('cache policy', () => {
     test('every response is no-store (admin data is per-principal and mutating)', async () => {
       const { app } = TestAdmin.setup()
-      for (const path of ['/scopes', '/api-keys', '/config.json']) {
+      for (const path of ['/scopes', '/api-keys', '/organizations', '/config.json']) {
         const response = await app.request(`http://admin${path}`)
         expect(response.headers.get('cache-control')).toBe('no-store')
       }
     })
   })
 
+  describe('audit logging', () => {
+    test('records authenticated data access with actor, request id, route, and status', async () => {
+      const { app, db } = TestAdmin.setup({
+        identify: () => ({ email: 'ops@tempo.xyz' }),
+      })
+      const response = await app.request('http://admin/organizations?limit=5')
+      const records = await db.kysely
+        .selectFrom('admin_audit_logs')
+        .selectAll()
+        .orderBy('createdAt', 'desc')
+        .execute()
+
+      expect(response.status).toBe(200)
+      expect(records[0]).toMatchObject({
+        actor: 'ops@tempo.xyz',
+        method: 'GET',
+        path: '/organizations',
+        query: 'limit=5',
+        status: 200,
+      })
+      expect(records[0]?.requestId).toBeTruthy()
+    })
+  })
+
   describe('GET /config.json', () => {
     test('reports the signed-in identity and sign-in/out URLs', async () => {
       const { app } = TestAdmin.setup({
@@ -120,8 +148,10 @@ describe('create', () => {
       expect(response.headers.get('content-type')).toContain('text/html')
       const html = await response.text()
       expect(html).toContain('<div id="root">')
+      expect(html).not.toContain('data-theme="dark"')
+      expect(html).toContain("localStorage.getItem('tempo-api-admin.theme')")
       // Standalone mount → `<base href="/">` so relative asset/API URLs resolve.
-      expect(html).toContain('<base href="/"/>')
+      expect(html).toContain('<base data-tempo-base="true" href="/"/>')
     })
 
     test('inlines the gated auth config into the shell (no bootstrap round trip)', async () => {
@@ -173,7 +203,7 @@ describe('create', () => {
       expect(response.status).toBe(200)
       // The base href is the mount root, not the deep link, so assets/API
       // resolve under `/admin/` from any in-app route.
-      expect(await response.text()).toContain('<base href="/admin/"/>')
+      expect(await response.text()).toContain('<base data-tempo-base="true" href="/admin/"/>')
     })
 
     test('ui: false → no shell; `/` returns the JSON 404', async () => {