tapimo 0.4.0 → 0.4.3

package/src/ApiKey.ts

@@ -16,7 +16,6 @@ import * as z from 'zod/mini'
 
 import * as Id from './internal/Id.js'
 import * as RateLimit from './internal/RateLimit.js'
-import * as Scope from './Scope.js'
 
 /** Zod schemas owned by the API-key module. */
 export namespace schema {
@@ -40,7 +39,7 @@ export namespace schema {
     id: z.string().check(z.describe('Stable key id.')),
     name: z.optional(z.string()).check(z.describe('Human-readable key name.')),
     orgId: z.string().check(z.describe('Owning organization id.')),
-    projectId: z.optional(z.string()).check(z.describe('Owning project id (`prj_…`).')),
+    projectId: z.optional(z.string()).check(z.describe('Attributed project id (`prj_…`).')),
     rateLimits: z
       .optional(z.record(z.string(), RateLimit.schema.Limit))
       .check(
@@ -49,7 +48,7 @@ export namespace schema {
         ),
       ),
     scopes: z
-      .readonly(z.array(z.enum([...Scope.catalog.map((entry) => entry.scope), Scope.wildcard])))
+      .readonly(z.array(z.string().check(z.minLength(1))))
       .check(z.describe("Granted scopes. '*' grants all scopes.")),
   })
 }

package/src/ApiKeys.ts

@@ -15,14 +15,14 @@ import * as z from 'zod/mini'
 
 import * as ApiKey from './ApiKey.js'
 import type * as Store from './internal/Store.js'
+import * as Scope from './Scope.js'
 
 /** Zod schemas owned by the API-keys module. */
 export namespace schema {
   /**
    * Fields accepted when minting a key, and the single source of truth for the
-   * {@link MintInput} type and `mint` validation. Derived from the resolved
-   * `ApiKey.schema` (minus the generated `id`) so the scope vocabulary stays in
-   * lockstep with the resolved shape.
+   * {@link MintInput} type and structural validation. {@link mint} validates
+   * scope identifiers against its configured catalog.
    */
   export const MintInput = z.extend(z.omit(ApiKey.schema.ApiKey, { id: true }), {
     createdBy: z
@@ -78,12 +78,19 @@ export type MintResult = {
  *
  * @param state - The KV state store holding key records.
  * @param input - The key to mint.
+ * @param options - Scope catalog used for validation.
  * @returns The persisted record and its one-time token.
  */
-export async function mint(state: Store.State, input: MintInput): Promise<MintResult> {
+export async function mint(
+  state: Store.State,
+  input: MintInput,
+  options: mint.Options = {},
+): Promise<MintResult> {
   const valid = schema.MintInput.safeParse(input)
   if (!valid.success) throw new Error(`invalid API key input: ${z.prettifyError(valid.error)}`)
   const data = valid.data
+  if (!validScopes(data.scopes, options.scopeCatalog ?? Scope.catalog))
+    throw new Error('invalid API key input: unknown scope')
 
   const time = new Date()
   const token = ApiKey.generateToken(data.environment)
@@ -121,6 +128,14 @@ export async function mint(state: Store.State, input: MintInput): Promise<MintRe
   return { record, token }
 }
 
+export declare namespace mint {
+  /** Options for {@link mint}. */
+  type Options = {
+    /** Scope catalog accepted while minting the key. */
+    scopeCatalog?: Scope.Catalog | undefined
+  }
+}
+
 /**
  * Resolves a plaintext API key token to its metadata, or `null`. Expiry is
  * enforced on read — not just via the store's native TTL — so it holds on
@@ -128,10 +143,23 @@ export async function mint(state: Store.State, input: MintInput): Promise<MintRe
  *
  * @param state - The KV state store holding key records.
  * @param token - The presented plaintext token.
+ * @param options - Scope catalog used for validation.
  * @returns The resolved key metadata, or `null`.
  */
-export async function resolve(state: Store.State, token: string): Promise<ApiKey.ApiKey | null> {
-  return read(state, ApiKey.keyFor(token), Date.now())
+export async function resolve(
+  state: Store.State,
+  token: string,
+  options: resolve.Options = {},
+): Promise<ApiKey.ApiKey | null> {
+  return read(state, ApiKey.keyFor(token), Date.now(), options.scopeCatalog ?? Scope.catalog)
+}
+
+export declare namespace resolve {
+  /** Options for {@link resolve}. */
+  type Options = {
+    /** Scope catalog accepted while resolving the key. */
+    scopeCatalog?: Scope.Catalog | undefined
+  }
 }
 
 /**
@@ -139,12 +167,25 @@ export async function resolve(state: Store.State, token: string): Promise<ApiKey
  *
  * @param state - The KV state store holding key records.
  * @param id - The key id (`key_…`).
+ * @param options - Scope catalog used for validation.
  * @returns The record, or `null`.
  */
-export async function get(state: Store.State, id: string): Promise<Record | null> {
+export async function get(
+  state: Store.State,
+  id: string,
+  options: get.Options = {},
+): Promise<Record | null> {
   const recordKey = await state.get(idKeyFor(id))
   if (!recordKey) return null
-  return read(state, recordKey, Date.now())
+  return read(state, recordKey, Date.now(), options.scopeCatalog ?? Scope.catalog)
+}
+
+export declare namespace get {
+  /** Options for {@link get}. */
+  type Options = {
+    /** Scope catalog accepted while reading the key. */
+    scopeCatalog?: Scope.Catalog | undefined
+  }
 }
 
 /**
@@ -162,7 +203,7 @@ export async function list(
   const { keys } = await state.list({ prefix: ApiKey.recordPrefix })
   const records: Record[] = []
   for (const { name } of keys) {
-    const record = await read(state, name, Date.now())
+    const record = await read(state, name, Date.now(), options.scopeCatalog ?? Scope.catalog)
     if (record && (!options.orgId || record.orgId === options.orgId)) records.push(record)
   }
   // Newest first; ids are random, so sort by creation time.
@@ -174,6 +215,8 @@ export declare namespace list {
   type Options = {
     /** Restrict results to keys owned by this organization. */
     orgId?: string | undefined
+    /** Scope catalog accepted while listing keys. */
+    scopeCatalog?: Scope.Catalog | undefined
   }
 }
 
@@ -196,7 +239,9 @@ export async function listByOrg(
   const records: Record[] = []
   for (const { name } of keys) {
     const recordKey = await state.get(name)
-    const record = recordKey ? await read(state, recordKey, Date.now()) : null
+    const record = recordKey
+      ? await read(state, recordKey, Date.now(), options.scopeCatalog ?? Scope.catalog)
+      : null
     if (!record) {
       await state.delete(name)
       continue
@@ -214,6 +259,8 @@ export declare namespace listByOrg {
     environment?: 'production' | 'sandbox' | undefined
     /** Restrict results to keys attributed to this project. */
     projectId?: string | undefined
+    /** Scope catalog accepted while listing keys. */
+    scopeCatalog?: Scope.Catalog | undefined
   }
 }
 
@@ -251,16 +298,18 @@ export async function revoke(state: Store.State, id: string): Promise<boolean> {
  * @param state - The KV state store holding key records.
  * @param id - The key id (`key_…`).
  * @param input - The attribution to apply.
+ * @param options - Scope catalog used for validation.
  * @returns The updated record, or `null` when the key is absent.
  */
 export async function attribute(
   state: Store.State,
   id: string,
   input: attribute.Input,
+  options: attribute.Options = {},
 ): Promise<Record | null> {
   const recordKey = await state.get(idKeyFor(id))
   if (!recordKey) return null
-  const record = await read(state, recordKey, Date.now())
+  const record = await read(state, recordKey, Date.now(), options.scopeCatalog ?? Scope.catalog)
   if (!record) return null
 
   const updated: Record = {
@@ -283,9 +332,15 @@ export declare namespace attribute {
   type Input = {
     /** New owning organization id (`org_…`). */
     orgId?: string | undefined
-    /** New owning project id (`prj_…`). */
+    /** New attributed project id (`prj_…`). */
     projectId?: string | undefined
   }
+
+  /** Options for {@link attribute}. */
+  type Options = {
+    /** Scope catalog accepted while reading the key. */
+    scopeCatalog?: Scope.Catalog | undefined
+  }
 }
 
 /**
@@ -303,8 +358,8 @@ export async function setBillingActive(
   state: Store.State,
   options: setBillingActive.Options,
 ): Promise<number> {
-  const { active, environment, orgId } = options
-  const records = await listByOrg(state, orgId, { environment })
+  const { active, environment, orgId, scopeCatalog } = options
+  const records = await listByOrg(state, orgId, { environment, scopeCatalog })
   let updated = 0
   for (const record of records) {
     if (record.billingActive === active) continue
@@ -330,6 +385,8 @@ export declare namespace setBillingActive {
     environment: 'production' | 'sandbox'
     /** Owning organization id (`org_…`). */
     orgId: string
+    /** Scope catalog accepted while updating keys. */
+    scopeCatalog?: Scope.Catalog | undefined
   }
 }
 
@@ -339,13 +396,17 @@ export declare namespace setBillingActive {
  * themselves are never modified, so existing tokens keep resolving.
  *
  * @param state - The KV state store holding key records.
+ * @param options - Scope catalog used for validation.
  * @returns Scanned and indexed record counts.
  */
-export async function backfill(state: Store.State): Promise<backfill.Result> {
+export async function backfill(
+  state: Store.State,
+  options: backfill.Options = {},
+): Promise<backfill.Result> {
   const { keys } = await state.list({ prefix: ApiKey.recordPrefix })
   let indexed = 0
   for (const { name } of keys) {
-    const record = await read(state, name, Date.now())
+    const record = await read(state, name, Date.now(), options.scopeCatalog ?? Scope.catalog)
     if (!record) continue
     const ttl =
       record.expiresAt === undefined
@@ -359,6 +420,12 @@ export async function backfill(state: Store.State): Promise<backfill.Result> {
 }
 
 export declare namespace backfill {
+  /** Options for {@link backfill}. */
+  type Options = {
+    /** Scope catalog accepted while reading keys. */
+    scopeCatalog?: Scope.Catalog | undefined
+  }
+
   /** Result of {@link backfill}. */
   type Result = {
     /** Records whose index entries were written. */
@@ -372,7 +439,12 @@ export declare namespace backfill {
  * Reads and validates a stored record by storage key. Invalid, corrupt, or
  * expired records (`expiresAt <= now`) resolve to `null`.
  */
-async function read(state: Store.State, key: string, now: number): Promise<Record | null> {
+async function read(
+  state: Store.State,
+  key: string,
+  now: number,
+  scopeCatalog: Scope.Catalog,
+): Promise<Record | null> {
   const raw = await state.get(key)
   if (!raw) return null
   const value = (() => {
@@ -386,10 +458,16 @@ async function read(state: Store.State, key: string, now: number): Promise<Recor
   const parsed = schema.Record.safeParse(value)
   if (!parsed.success) return null
   const record = parsed.data
+  if (!validScopes(record.scopes, scopeCatalog)) return null
   if (record.expiresAt !== undefined && Date.parse(record.expiresAt) <= now) return null
   return record
 }
 
+/** Returns whether every granted scope belongs to the configured catalog. */
+function validScopes(scopes: readonly string[], scopeCatalog: Scope.Catalog): boolean {
+  return scopes.every((scope) => scope === Scope.wildcard || Scope.includes(scopeCatalog, scope))
+}
+
 /** Storage-key prefix for the `id → recordKey` index. */
 const idPrefix = 'apikey_id:'
 

package/src/App.test.ts

@@ -72,6 +72,45 @@ describe('create', () => {
     `)
   })
 
+  test('documents supported API key transports', async () => {
+    const app = TestApp.create()
+    const spec = await (await app.request('/openapi.json')).json()
+
+    expect({
+      queryApiKey: {
+        in: spec.components.securitySchemes.queryApiKey.in,
+        name: spec.components.securitySchemes.queryApiKey.name,
+        type: spec.components.securitySchemes.queryApiKey.type,
+      },
+      security: spec.security,
+    }).toMatchInlineSnapshot(`
+      {
+        "queryApiKey": {
+          "in": "query",
+          "name": "key",
+          "type": "apiKey",
+        },
+        "security": [
+          {
+            "apiKey": [],
+          },
+          {
+            "queryApiKey": [],
+          },
+          {
+            "bearerAuth": [],
+          },
+        ],
+      }
+    `)
+    expect(spec.paths['/v1/orgs'].get.security).toContainEqual({ queryApiKey: [] })
+    expect(spec.paths['/v1/orgs'].get['x-required-scopes']).toMatchInlineSnapshot(`
+      [
+        "management:read",
+      ]
+    `)
+  })
+
   test('authenticates a minted store-backed key and rejects after revoke', async () => {
     const store = Store.memory()
     const { record, token } = await ApiKeys.mint(store, {
@@ -93,7 +132,7 @@ describe('create', () => {
     expect(revoked.status).toMatchInlineSnapshot(`401`)
   })
 
-  test('authenticates via the deprecated x-api-key header and key query param', async () => {
+  test('authenticates via x-api-key header and key query param', async () => {
     const store = Store.memory()
     const { token } = await ApiKeys.mint(store, { orgId: 'org_test', scopes: ['data:read'] })
     const app = TestApp.create({ auth: { cache: false }, kv: { store } })
@@ -105,10 +144,13 @@ describe('create', () => {
     })
     expect(viaHeader.status).toMatchInlineSnapshot(`400`)
 
-    // Deprecated `key` query parameter authenticates the same way.
+    // The `key` query parameter authenticates the same way.
     const viaQuery = await app.request(`/v1/tokens/not-an-address?key=${encodeURIComponent(token)}`)
     expect(viaQuery.status).toMatchInlineSnapshot(`400`)
 
+    const rejectedQuery = await app.request('/v1/tokens/not-an-address?key=wrong')
+    expect(rejectedQuery.status).toMatchInlineSnapshot(`401`)
+
     // An unknown legacy credential is still rejected.
     const rejected = await app.request('/v1/tokens/not-an-address', {
       headers: { 'x-api-key': 'wrong' },

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'