tapimo 0.4.0 → 0.4.3

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
@@ -1221,6 +1221,53 @@ describe('narrows responses by status', () => {
     }
   })
 
+  test('POST /v1/funding/routes/quote', async () => {
+    const client = Client.create()
+    const res = await client.v1.funding.routes.quote.$post({
+      json: {
+        depositor: '0x1111111111111111111111111111111111111111',
+        provider: 'across',
+        sourceAmount: '1000000',
+        sourceChain: 'base',
+        sourceToken: 'USDC',
+      },
+    })
+
+    expectTypeOf(res.status).toEqualTypeOf<200 | 400 | 404 | 501 | 502 | PaidAccessStatus>()
+
+    switch (res.status) {
+      case 200: {
+        const json = await res.json()
+        expectTypeOf(json).toEqualTypeOf<
+          z.output<typeof Funding.schema.quoteFundingRoute.Response>
+        >()
+        return
+      }
+      case 400: {
+        const json = await res.json()
+        expectTypeOf(json.error.code).toEqualTypeOf<Access400<'body_invalid'>>()
+        return
+      }
+      case 404: {
+        const json = await res.json()
+        expectTypeOf(json.error.code).toEqualTypeOf<'quote_unavailable' | 'route_not_found'>()
+        return
+      }
+      case 501: {
+        const json = await res.json()
+        expectTypeOf(json.error.code).toEqualTypeOf<'provider_unconfigured'>()
+        return
+      }
+      case 502: {
+        const json = await res.json()
+        expectTypeOf(json.error.code).toEqualTypeOf<
+          'provider_error' | 'provider_rate_limited' | 'provider_timeout'
+        >()
+        return
+      }
+    }
+  })
+
   test('GET /v1/funding/chains', async () => {
     const client = Client.create()
     const res = await client.v1.funding.chains.$get()

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 () => {

package/src/admin/App.ts

@@ -4,11 +4,14 @@ import { requestId, type RequestIdVariables } from 'hono/request-id'
 
 import * as ApiKey from '../ApiKey.js'
 import type * as Assets from '../Assets.js'
-import type * as Db from '../db/Db.js'
+import type * as Analytics from '../analytics/Analytics.js'
+import * as Db from '../db/Db.js'
+import * as AdminAuditLogs from '../db/tables/adminAuditLogs.js'
 import type * as Store from '../internal/Store.js'
 import * as Response from '../internal/Response.js'
 
 import { apiKeys } from './apps/api-keys.js'
+import { organizations } from './apps/organizations.js'
 import { scopes } from './apps/scopes.js'
 import { verifiedTokens } from './apps/verified-tokens.js'
 import * as Ui from './ui.generated.js'
@@ -22,6 +25,8 @@ export type Identity = {
 /** Hono environment for the admin app. */
 export type Environment = {
   Variables: RequestIdVariables & {
+    /** ClickHouse analytics source used by operational usage reads. */
+    analytics: Analytics.Source
     /** Static-asset writer (e.g. the R2 icon bucket), when configured. */
     assets: create.Assets | undefined
     /** Authoritative Postgres store, or a per-request factory. Resolve at the leaf with `Db.get`. */
@@ -54,6 +59,7 @@ export function create(options: create.Options) {
   app.use('*', async (c, next) => {
     // Admin data is per-principal and mutating: never cache.
     c.header('Cache-Control', 'no-store')
+    c.set('analytics', options.analytics)
     c.set('assets', options.assets)
     c.set('db', options.db)
     c.set('kv', options.kv)
@@ -73,17 +79,18 @@ export function create(options: create.Options) {
     }
   }
 
-  // Renders the public SPA shell: injects a `<base href>` of the mount root (so
-  // relative asset/API URLs resolve) and the auth config (read synchronously,
-  // `identity` is `null` when logged out). `<` is escaped to keep `<script>`.
+  // Renders the public SPA shell: stamps its hydration-safe base and auth
+  // placeholders with request values. `<` is escaped to keep the config script.
   const serveShell = (c: Context<Environment>) => {
     const mount = c.req.routePath.replace(/\*$/, '').replace(/\/$/, '')
     const config = JSON.stringify(authConfig(c.get('identity'))).replaceAll('<', '\\u003c')
     return c.html(
-      Ui.shell.replace(
-        '<head>',
-        `<head><base href="${mount}/"/><script>window.__TEMPO_API_CONFIG__=${config}</script>`,
-      ),
+      Ui.shell
+        .replace(
+          '<base data-tempo-base="true" href="/"/>',
+          `<base data-tempo-base="true" href="${mount}/"/>`,
+        )
+        .replace('window.__TEMPO_API_CONFIG__=undefined', `window.__TEMPO_API_CONFIG__=${config}`),
     )
   }
 
@@ -106,20 +113,46 @@ export function create(options: create.Options) {
       })
     return next()
   }
-  for (const path of [
+  const protectedPaths = [
     '/config.json',
     '/api-keys',
     '/api-keys/*',
+    '/organizations',
+    '/organizations/*',
     '/scopes',
     '/scopes/*',
     '/verified-tokens',
     '/verified-tokens/*',
-  ])
-    app.use(path, requireAuth)
+  ] as const
+  for (const path of protectedPaths) app.use(path, requireAuth)
+
+  for (const path of protectedPaths)
+    app.use(path, async (c, next) => {
+      const identity = c.get('identity')
+      if (!identity) return
+      const search = new URL(c.req.url).searchParams
+      const record = (status: number) =>
+        AdminAuditLogs.insert(Db.get(c.get('db')), {
+          actor: identity.email,
+          method: c.req.method,
+          path: c.req.path,
+          query: search.size ? search.toString() : undefined,
+          requestId: c.get('requestId'),
+          status,
+        })
+      try {
+        await next()
+      } catch (cause) {
+        await record(500)
+        throw cause
+      }
+      await record(c.res.status)
+    })
 
   const routed = app
     .get('/config.json', (c) => c.json(authConfig(c.get('identity')), 200))
     .route('/api-keys', apiKeys())
+    .route('/organizations', organizations())
     .route('/scopes', scopes())
     .route('/verified-tokens', verifiedTokens())
 
@@ -172,15 +205,17 @@ export declare namespace create {
 
   /** Options for {@link create}. */
   type Options = {
+    /** ClickHouse analytics source used by operational usage reads. */
+    analytics: Analytics.Source
     /**
      * Static-asset writer for logo uploads (shared with the main API's `assets`
      * loader) to enable `PUT /verified-tokens/:address/logo`; omit for `404`.
      */
     assets?: Assets | undefined
     /**
-     * Authoritative Postgres store shared with the main API (verified
-     * tokens). Pass a long-lived `Db.postgres(...)` singleton on Node, or a
-     * factory (`() => Db.postgres(...)`) on Workers.
+     * Authoritative Postgres store shared with the main API. Pass a long-lived
+     * `Db.postgres(...)` singleton on Node, or a factory
+     * (`() => Db.postgres(...)`) on Workers.
      */
     db: Db.Source
     /**

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

@@ -5,6 +5,7 @@ import * as ApiKeys from '../../ApiKeys.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'
 import type * as App from '../App.js'
 
 /** Zod schemas owned by the admin API-keys handler. */
@@ -16,7 +17,11 @@ export namespace schema {
      * server sets from the verified identity so it can't be spoofed).
      */
     export const Body = Schema.describe(
-      z.omit(ApiKeys.schema.MintInput, { createdBy: true }),
+      z.extend(z.omit(ApiKeys.schema.MintInput, { createdBy: true }), {
+        scopes: z
+          .readonly(z.array(z.enum([...Scope.catalog.map((entry) => entry.scope), Scope.wildcard])))
+          .check(z.describe("Granted scopes. '*' grants all scopes.")),
+      }),
       'Fields accepted when minting an API key.',
     )
 
@@ -59,7 +64,7 @@ export namespace schema {
     export const Body = Schema.describe(
       z.object({
         orgId: z.optional(z.string()).check(z.describe('New owning organization id (`org_…`).')),
-        projectId: z.optional(z.string()).check(z.describe('New owning project id (`prj_…`).')),
+        projectId: z.optional(z.string()).check(z.describe('New attributed project id (`prj_…`).')),
       }),
       'Attribution to apply to an API key.',
     )
@@ -174,7 +179,9 @@ export function apiKeys() {
       }),
       async (c) => {
         const { orgId } = c.req.valid('query')
-        const data = await ApiKeys.list(c.get('kv').store, orgId ? { orgId } : {})
+        const data = orgId
+          ? await ApiKeys.listByOrg(c.get('kv').store, orgId)
+          : await ApiKeys.list(c.get('kv').store)
         return c.json(Response.validated(schema.listApiKeys.Response, { data }))
       },
     )