tapimo 0.0.0 → 0.0.2

package/src/admin/Access.test.ts

@@ -0,0 +1,130 @@
+import * as jose from 'jose'
+
+import * as Access from './Access.js'
+
+const teamDomain = 'https://tempo.cloudflareaccess.com'
+const certsUrl = `${teamDomain}/cdn-cgi/access/certs`
+const kid = 'test-key-1'
+
+/** Generates an ES256 keypair and the JWKS the team domain would serve. */
+async function makeKeys() {
+  const { privateKey, publicKey } = await jose.generateKeyPair('ES256', { extractable: true })
+  const jwk = { ...(await jose.exportJWK(publicKey)), kid }
+  return { jwks: { keys: [jwk] }, privateKey }
+}
+
+/** Signs an Access-style JWT with the given claims/overrides. */
+async function sign(
+  privateKey: jose.CryptoKey,
+  options: {
+    audience?: string | undefined
+    email?: string | undefined
+    expirationTime?: string | number | undefined
+    issuer?: string | undefined
+  } = {},
+) {
+  const payload = options.email === undefined ? {} : { email: options.email }
+  return new jose.SignJWT(payload)
+    .setProtectedHeader({ alg: 'ES256', kid })
+    .setIssuer(options.issuer ?? teamDomain)
+    .setAudience(options.audience ?? 'test-access-aud-tag')
+    .setIssuedAt()
+    .setExpirationTime(options.expirationTime ?? '1h')
+    .sign(privateKey)
+}
+
+describe('cloudflareAccess', () => {
+  let privateKey: jose.CryptoKey
+  let jwks: { keys: readonly unknown[] }
+
+  beforeEach(async () => {
+    ;({ jwks, privateKey } = await makeKeys())
+    // Serve the public JWKS from the team-domain certs URL.
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(async (input: string | URL | Request) => {
+        const url =
+          typeof input === 'string' ? input : input instanceof URL ? input.href : input.url
+        if (url === certsUrl) return new Response(JSON.stringify(jwks))
+        throw new Error(`unexpected fetch: ${url}`)
+      }),
+    )
+  })
+
+  afterEach(() => {
+    vi.unstubAllGlobals()
+  })
+
+  test('valid JWT in header → identity', async () => {
+    const identify = Access.cloudflareAccess({ teamDomain })
+    const token = await sign(privateKey, { email: 'admin@tempo.xyz' })
+    const request = new Request('https://admin.tempo.xyz/api-keys', {
+      headers: { 'cf-access-jwt-assertion': token },
+    })
+    expect(await identify(request)).toEqual({ email: 'admin@tempo.xyz' })
+  })
+
+  test('valid JWT in CF_Authorization cookie → identity', async () => {
+    const identify = Access.cloudflareAccess({ teamDomain })
+    const token = await sign(privateKey, { email: 'admin@tempo.xyz' })
+    const request = new Request('https://admin.tempo.xyz/api-keys', {
+      headers: { cookie: `foo=bar; CF_Authorization=${token}` },
+    })
+    expect(await identify(request)).toEqual({ email: 'admin@tempo.xyz' })
+  })
+
+  test('missing assertion → null', async () => {
+    const identify = Access.cloudflareAccess({ teamDomain })
+    const request = new Request('https://admin.tempo.xyz/api-keys')
+    expect(await identify(request)).toBeNull()
+  })
+
+  test('any audience accepted (issuer still enforced)', async () => {
+    const identify = Access.cloudflareAccess({ teamDomain })
+    const token = await sign(privateKey, { audience: 'some-other-aud', email: 'admin@tempo.xyz' })
+    const request = new Request('https://admin.tempo.xyz/api-keys', {
+      headers: { 'cf-access-jwt-assertion': token },
+    })
+    expect(await identify(request)).toEqual({ email: 'admin@tempo.xyz' })
+  })
+
+  test('wrong issuer → null', async () => {
+    const identify = Access.cloudflareAccess({ teamDomain })
+    const token = await sign(privateKey, {
+      email: 'admin@tempo.xyz',
+      issuer: 'https://evil.cloudflareaccess.com',
+    })
+    const request = new Request('https://admin.tempo.xyz/api-keys', {
+      headers: { 'cf-access-jwt-assertion': token },
+    })
+    expect(await identify(request)).toBeNull()
+  })
+
+  test('expired JWT → null', async () => {
+    const identify = Access.cloudflareAccess({ teamDomain })
+    const token = await sign(privateKey, { email: 'admin@tempo.xyz', expirationTime: '-1h' })
+    const request = new Request('https://admin.tempo.xyz/api-keys', {
+      headers: { 'cf-access-jwt-assertion': token },
+    })
+    expect(await identify(request)).toBeNull()
+  })
+
+  test('valid signature but no email claim → null', async () => {
+    const identify = Access.cloudflareAccess({ teamDomain })
+    const token = await sign(privateKey)
+    const request = new Request('https://admin.tempo.xyz/api-keys', {
+      headers: { 'cf-access-jwt-assertion': token },
+    })
+    expect(await identify(request)).toBeNull()
+  })
+
+  test('signature from an unknown key → null', async () => {
+    const identify = Access.cloudflareAccess({ teamDomain })
+    const other = await makeKeys()
+    const token = await sign(other.privateKey, { email: 'admin@tempo.xyz' })
+    const request = new Request('https://admin.tempo.xyz/api-keys', {
+      headers: { 'cf-access-jwt-assertion': token },
+    })
+    expect(await identify(request)).toBeNull()
+  })
+})

package/src/admin/Access.ts

@@ -0,0 +1,87 @@
+/**
+ * The default {@link App.create.Options.identify} hook: verifies a Cloudflare
+ * Access JWT in-worker, so a request sent directly to the worker URL (bypassing
+ * the edge gate) still can't reach the admin routes (defense in depth).
+ *
+ * The only admin module that imports `jose`, keeping that dependency out of the
+ * IdP-agnostic core. Self-hosters not on Access supply their own `identify`.
+ */
+
+import * as jose from 'jose'
+
+import type * as App from './App.js'
+
+/** Header Cloudflare Access sets with the signed identity assertion (a JWT). */
+const headerName = 'cf-access-jwt-assertion'
+/** Cookie Cloudflare Access sets as a fallback carrier for the same JWT. */
+const cookieName = 'CF_Authorization'
+
+/**
+ * Builds an {@link App.create.Options.identify} hook that verifies the Cloudflare
+ * Access JWT against the team-domain JWKS (fetched lazily, cached by `jose`). Any
+ * verification failure resolves to `null` (deny) rather than throwing.
+ *
+ * Verifies the signature and issuer (the team domain). The audience (`aud`) is
+ * not checked, so any token minted for any app in the team's org is accepted —
+ * fine when everyone with org access is trusted.
+ *
+ * @example
+ * ```ts
+ * import { App, Access } from 'tapimo/admin'
+ *
+ * const source = {} as App.create.Options['apiKey']['source']
+ *
+ * App.create({
+ *   apiKey: { source },
+ *   identify: Access.cloudflareAccess({
+ *     teamDomain: 'https://tempo.cloudflareaccess.com',
+ *   }),
+ * })
+ * ```
+ */
+export function cloudflareAccess(
+  options: cloudflareAccess.Options,
+): (request: Request) => Promise<App.Identity | null> {
+  const { teamDomain } = options
+
+  // Created once and reused: `jose` caches keys and refetches on unknown `kid`.
+  const issuer = teamDomain.replace(/\/+$/, '')
+  const jwks = jose.createRemoteJWKSet(new URL(`${issuer}/cdn-cgi/access/certs`))
+
+  return async (request) => {
+    const token = readToken(request)
+    if (!token) return null
+    try {
+      const { payload } = await jose.jwtVerify(token, jwks, { issuer })
+      const email = payload['email']
+      return typeof email === 'string' && email ? { email } : null
+    } catch {
+      // Any verification failure is a denial, not an error to surface.
+      return null
+    }
+  }
+}
+
+export declare namespace cloudflareAccess {
+  /** Options for {@link cloudflareAccess}. */
+  type Options = {
+    /** Team domain (e.g. `https://<team>.cloudflareaccess.com`); the token issuer and JWKS host. */
+    teamDomain: string
+  }
+}
+
+/**
+ * Extracts the Access JWT: the `Cf-Access-Jwt-Assertion` header, falling back to
+ * the `CF_Authorization` cookie. Returns `undefined` when neither is present.
+ */
+function readToken(request: Request): string | undefined {
+  const header = request.headers.get(headerName)
+  if (header) return header
+  const cookie = request.headers.get('cookie')
+  if (!cookie) return undefined
+  for (const part of cookie.split(';')) {
+    const [name, ...rest] = part.trim().split('=')
+    if (name === cookieName && rest.length) return rest.join('=')
+  }
+  return undefined
+}

package/src/admin/App.test.ts

@@ -0,0 +1,225 @@
+import { Hono } from 'hono'
+import * as TestAdmin from '../../test/Admin.js'
+
+// Route behavior (mint/list/revoke, the scope catalog) is covered in
+// `./apps/api-keys.test.ts` and `./apps/scopes.test.ts`; this file covers the
+// app-level wiring: the auth gate, cache policy, and the SPA shell.
+describe('create', () => {
+  describe('authentication', () => {
+    test('denied identity → 401 on config + the data API', async () => {
+      const { app } = TestAdmin.setup({ identify: () => null })
+      const routes = [
+        new Request('http://admin/config.json'),
+        new Request('http://admin/scopes'),
+        new Request('http://admin/api-keys'),
+        new Request('http://admin/api-keys', {
+          body: JSON.stringify({ orgId: 'org', scopes: ['data:read'] }),
+          headers: { 'content-type': 'application/json' },
+          method: 'POST',
+        }),
+        new Request('http://admin/api-keys/key_x', { method: 'DELETE' }),
+        new Request('http://admin/verified-tokens?chainId=42431', {
+          body: JSON.stringify({ tokens: [] }),
+          headers: { 'content-type': 'application/json' },
+          method: 'PUT',
+        }),
+      ]
+      for (const request of routes) {
+        const response = await app.request(request)
+        expect(response.status).toBe(401)
+        expect(response.headers.get('cache-control')).toBe('no-store')
+      }
+    })
+
+    test('denied identity → shell + assets stay public (so the SPA can show login)', async () => {
+      const { app } = TestAdmin.setup({ identify: () => null, ui: { loginUrl: '/login' } })
+      const shell = await app.request('http://admin/')
+      expect(shell.status).toBe(200)
+      // The shell inlines `identity: null` so the SPA renders login on first paint.
+      const html = await shell.text()
+      const json = html.match(/window\.__TEMPO_API_CONFIG__=({.*?})<\/script>/)?.[1]
+      expect(JSON.parse(json!)).toEqual({ auth: { identity: null, loginUrl: '/login' } })
+      const assetPath = html.match(/\.\/(assets\/[^"]+\.js)/)?.[1]
+      expect((await app.request(`http://admin/${assetPath}`)).status).toBe(200)
+    })
+
+    test('public auth routes mounted ahead of the admin app bypass the gate', async () => {
+      // The consumer owns auth endpoints: mount them on a parent app before the
+      // admin app, so they never reach the gate while the admin surface stays gated.
+      const { app: admin } = TestAdmin.setup({ identify: () => null })
+      const app = new Hono().get('/api/auth/ping', (c) => c.text('ok')).route('/', admin)
+      expect((await app.request('http://admin/api/auth/ping')).status).toBe(200)
+      expect((await app.request('http://admin/api-keys')).status).toBe(401)
+    })
+
+    test('verified identity is recorded as createdBy on minted keys', async () => {
+      const { app } = TestAdmin.setup({ identify: () => ({ email: 'ops@tempo.xyz' }) })
+      const response = await app.request('http://admin/api-keys', {
+        body: JSON.stringify({ orgId: 'org', scopes: ['data:read'] }),
+        headers: { 'content-type': 'application/json' },
+        method: 'POST',
+      })
+      const body = (await response.json()) as { createdBy?: string }
+      expect(body.createdBy).toBe('ops@tempo.xyz')
+    })
+  })
+
+  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']) {
+        const response = await app.request(`http://admin${path}`)
+        expect(response.headers.get('cache-control')).toBe('no-store')
+      }
+    })
+  })
+
+  describe('GET /config.json', () => {
+    test('reports the signed-in identity and sign-in/out URLs', async () => {
+      const { app } = TestAdmin.setup({
+        identify: () => ({ email: 'ops@tempo.xyz' }),
+        ui: { loginUrl: '/login', logoutUrl: '/logout' },
+      })
+      const response = await app.request('http://admin/config.json')
+      expect(response.status).toBe(200)
+      expect(response.headers.get('cache-control')).toBe('no-store')
+      expect(await response.json()).toMatchInlineSnapshot(`
+        {
+          "auth": {
+            "identity": {
+              "email": "ops@tempo.xyz",
+            },
+            "loginUrl": "/login",
+            "logoutUrl": "/logout",
+          },
+        }
+      `)
+    })
+
+    test('omits sign-in/out URLs when no ui config is provided', async () => {
+      const { app } = TestAdmin.setup({ identify: () => ({ email: 'ops@tempo.xyz' }) })
+      const response = await app.request('http://admin/config.json')
+      expect(response.status).toBe(200)
+      expect(await response.json()).toMatchInlineSnapshot(`
+        {
+          "auth": {
+            "identity": {
+              "email": "ops@tempo.xyz",
+            },
+          },
+        }
+      `)
+    })
+  })
+
+  describe('GET / (SPA shell)', () => {
+    test('serves the prerendered SPA shell by default', async () => {
+      const { app } = TestAdmin.setup()
+      const response = await app.request('http://admin/')
+      expect(response.status).toBe(200)
+      expect(response.headers.get('content-type')).toContain('text/html')
+      const html = await response.text()
+      expect(html).toContain('<div id="root">')
+      // Standalone mount → `<base href="/">` so relative asset/API URLs resolve.
+      expect(html).toContain('<base href="/"/>')
+    })
+
+    test('inlines the gated auth config into the shell (no bootstrap round trip)', async () => {
+      const { app } = TestAdmin.setup({
+        ui: { loginUrl: 'https://sso/login', logoutUrl: 'https://sso/logout' },
+      })
+      const html = await (await app.request('http://admin/')).text()
+      const json = html.match(/window\.__TEMPO_API_CONFIG__=({.*?})<\/script>/)?.[1]
+      expect(json).toBeDefined()
+      expect(JSON.parse(json!)).toEqual({
+        auth: {
+          identity: { email: 'admin@tempo.xyz' },
+          loginUrl: 'https://sso/login',
+          logoutUrl: 'https://sso/logout',
+        },
+      })
+    })
+
+    test('HTML navigation to a data-route path (e.g. /api-keys) serves the shell', async () => {
+      const { app } = TestAdmin.setup()
+      // `/api-keys` is both an SPA route and a data endpoint; a browser hard
+      // reload (Accept: text/html) must get the shell, not the JSON list.
+      const response = await app.request('http://admin/api-keys', {
+        headers: { Accept: 'text/html,application/xhtml+xml' },
+      })
+      expect(response.status).toBe(200)
+      expect(response.headers.get('content-type')).toContain('text/html')
+      expect(await response.text()).toContain('<div id="root">')
+    })
+
+    test('fetch/RPC to a data-route path still returns JSON (not the shell)', async () => {
+      const { app } = TestAdmin.setup()
+      const response = await app.request('http://admin/api-keys')
+      expect(response.headers.get('content-type')).toContain('application/json')
+      expect((await response.json()) as { data: unknown[] }).toEqual({ data: [] })
+    })
+
+    test('any non-API GET falls back to the shell (client-side routing)', async () => {
+      const { app } = TestAdmin.setup()
+      const response = await app.request('http://admin/verified-tokens-ui')
+      expect(response.status).toBe(200)
+      expect(await response.text()).toContain('<div id="root">')
+    })
+
+    test('path-mounted: shell gets a `<base href>` of the mount root', async () => {
+      const { app } = TestAdmin.setup()
+      const api = new Hono().route('/admin', app)
+      const response = await api.request('http://host/admin/some/deep/link')
+      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/"/>')
+    })
+
+    test('ui: false → no shell; `/` returns the JSON 404', async () => {
+      const { app } = TestAdmin.setup({ ui: false })
+      const response = await app.request('http://admin/')
+      expect(response.status).toBe(404)
+      expect(((await response.json()) as { error: { code: string } }).error.code).toBe('not_found')
+    })
+  })
+
+  describe('GET /assets/* (SPA assets)', () => {
+    test('serves a hashed asset with an immutable cache header', async () => {
+      const { app } = TestAdmin.setup()
+      // Drive the asset name from the generated shell so the test survives UI
+      // churn (hashes change on every build).
+      const shell = await (await app.request('http://admin/')).text()
+      const assetPath = shell.match(/\.\/(assets\/[^"]+\.js)/)?.[1]
+      expect(assetPath).toBeDefined()
+      const response = await app.request(`http://admin/${assetPath}`)
+      expect(response.status).toBe(200)
+      expect(response.headers.get('content-type')).toContain('text/javascript')
+      expect(response.headers.get('cache-control')).toContain('immutable')
+    })
+
+    test('unknown asset → JSON 404', async () => {
+      const { app } = TestAdmin.setup()
+      const response = await app.request('http://admin/assets/does-not-exist.js')
+      expect(response.status).toBe(404)
+    })
+  })
+
+  describe('not found', () => {
+    test('ui: false → unknown routes get the JSON 404 envelope', async () => {
+      const { app } = TestAdmin.setup({ ui: false })
+      const response = await app.request('http://admin/nope')
+      const body = (await response.json()) as { error: { code: string } }
+      expect(response.status).toBe(404)
+      expect(body.error.code).toBe('not_found')
+    })
+
+    test('non-GET unknown routes get the JSON 404 envelope (shell only serves GET)', async () => {
+      const { app } = TestAdmin.setup()
+      const response = await app.request('http://admin/nope', { method: 'POST' })
+      const body = (await response.json()) as { error: { code: string } }
+      expect(response.status).toBe(404)
+      expect(body.error.code).toBe('not_found')
+    })
+  })
+})

package/src/admin/App.ts

@@ -0,0 +1,216 @@
+import { type Context, Hono, type Next } from 'hono'
+import { HTTPException } from 'hono/http-exception'
+import { requestId, type RequestIdVariables } from 'hono/request-id'
+
+import * as ApiKey from '../ApiKey.js'
+import * as ApiKeySource from '../ApiKeySource.js'
+import type * as Assets from '../Assets.js'
+import * as Response from '../internal/Response.js'
+import type * as Store from '../internal/Store.js'
+
+import { apiKeys } from './apps/api-keys.js'
+import { scopes } from './apps/scopes.js'
+import { verifiedTokens } from './apps/verified-tokens.js'
+import * as Ui from './ui.generated.js'
+
+/** A verified admin identity, as returned by {@link create.Options.identify}. */
+export type Identity = {
+  /** The admin's verified email, recorded as `createdBy` on every minted key. */
+  email: string
+}
+
+/** Hono environment for the admin app. */
+export type Environment = {
+  Variables: RequestIdVariables & {
+    /** Static-asset writer (e.g. the R2 icon bucket), when configured. */
+    assets: create.Assets | undefined
+    /** The admin identity, or `null` when unauthenticated (gated routes reject). */
+    identity: Identity | null
+    /** The API-key source provisioned against (mint/list/revoke). */
+    source: ApiKeySource.Source
+    /** Verified-token state store, when management is enabled. */
+    verifiedTokens: { store: Store.State } | undefined
+  }
+}
+
+/** The admin portal Hono app. Inferred from {@link create}. */
+export type App = ReturnType<typeof create>
+
+/** Creates the admin portal Hono app. */
+export function create(options: create.Options) {
+  const { identify } = options
+  const { source } = options.apiKey
+  // `false` (disabled) collapses to `undefined` so only a real config surfaces
+  // `loginUrl`/`logoutUrl` in `/config.json`.
+  const ui = options.ui || undefined
+
+  const app = new Hono<Environment>()
+
+  app.use('*', requestId({ headerName: 'tempo-request-id' }))
+
+  // Public hashed assets (no identity needed); before identify so it's skipped.
+  if (options.ui !== false) app.get('/assets/*', serveAsset)
+
+  // Resolve identity for every request, but don't reject here; the gate does.
+  app.use('*', async (c, next) => {
+    // Admin data is per-principal and mutating: never cache.
+    c.header('Cache-Control', 'no-store')
+    c.set('source', source)
+    c.set('assets', options.assets)
+    c.set('verifiedTokens', options.verifiedTokens)
+    c.set('identity', await identify(c.req.raw))
+    return next()
+  })
+
+  // Auth contract the UI reads (identity + sign-in/out URLs). Served at
+  // `/config.json` and inlined into the shell, so the UI reads it synchronously.
+  function authConfig(identity: Identity | null) {
+    return {
+      auth: {
+        identity,
+        ...(ui?.loginUrl ? { loginUrl: ui.loginUrl } : {}),
+        ...(ui?.logoutUrl ? { logoutUrl: ui.logoutUrl } : {}),
+      },
+    }
+  }
+
+  // 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>`.
+  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>`,
+      ),
+    )
+  }
+
+  // Browser navigations (`Accept: text/html`) get the public shell before the
+  // data routes match, so SPA routes that share a path with a data endpoint
+  // (e.g. `/api-keys`) still load on hard reload. `fetch`/RPC (`*/*`) fall
+  // through to the JSON API below.
+  if (options.ui !== false)
+    app.get('*', (c, next) =>
+      c.req.header('accept')?.includes('text/html') ? serveShell(c) : next(),
+    )
+
+  // Gate config + data API (`identity` → `null` ⇒ 401); shell/assets stay public.
+  const requireAuth = async (c: Context<Environment>, next: Next) => {
+    if (!c.get('identity'))
+      return Response.error(c, {
+        code: 'unauthorized',
+        message: 'Admin authentication required.',
+        status: 401,
+      })
+    return next()
+  }
+  for (const path of [
+    '/config.json',
+    '/api-keys',
+    '/api-keys/*',
+    '/scopes',
+    '/scopes/*',
+    '/verified-tokens',
+    '/verified-tokens/*',
+  ])
+    app.use(path, requireAuth)
+
+  const routed = app
+    .get('/config.json', (c) => c.json(authConfig(c.get('identity')), 200))
+    .route('/api-keys', apiKeys())
+    .route('/scopes', scopes())
+    .route('/verified-tokens', verifiedTokens())
+
+  // Any other non-API GET renders the public SPA shell (catch-all last, so data
+  // routes win); the HTML-navigation handler above covers shared-path reloads.
+  if (options.ui !== false) app.get('*', serveShell)
+
+  app.notFound((c) =>
+    Response.error(c, { code: 'not_found', message: 'Route not found', status: 404 }),
+  )
+
+  app.onError((cause, c) => {
+    if (cause instanceof HTTPException) return cause.getResponse()
+    // Redact any leaked API-key token from the logged error/stack.
+    console.error(
+      ApiKey.redact(cause instanceof Error ? (cause.stack ?? cause.message) : String(cause)),
+    )
+    return Response.error(c, {
+      code: 'internal_error',
+      message: 'Internal server error',
+      status: 500,
+    })
+  })
+
+  return routed
+}
+
+// Serves a hashed SPA asset with an immutable cache (override the global
+// `no-store`). Filename comes from the path, so it resolves under any mount.
+function serveAsset(c: Context<Environment>) {
+  const asset = Ui.assets[`assets/${c.req.path.split('/assets/').at(-1)}`]
+  if (!asset)
+    return Response.error(c, { code: 'not_found', message: 'Route not found', status: 404 })
+  c.header('Cache-Control', 'public, max-age=31536000, immutable')
+  c.header('Content-Type', asset.contentType)
+  return c.body(
+    asset.encoding === 'base64'
+      ? Uint8Array.from(atob(asset.content), (ch) => ch.charCodeAt(0))
+      : asset.content,
+  )
+}
+
+export declare namespace create {
+  /**
+   * Static-asset store for the deployment (e.g. `Assets.cloudflareR2(...)`,
+   * shared with the main API). Keyed `<chainId>/<path>`; `get` enables logo
+   * previews, `put` enables logo uploads.
+   */
+  type Assets = Assets.Assets
+
+  /** Options for {@link create}. */
+  type Options = {
+    /** API-key provisioning config (mirrors the API app's `apiKey` option). */
+    apiKey: {
+      /** Source to provision against (mint/list/revoke). */
+      source: ApiKeySource.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
+    /**
+     * Extracts the verified admin identity from a request, or `null` to deny.
+     * Must only return an identity for an already-authenticated request (a
+     * verified Access JWT, or a header set by a trusted proxy).
+     */
+    identify: (request: Request) => Identity | null | Promise<Identity | null>
+    /**
+     * Admin UI options, or `false` to disable the bundled UI (JSON API only).
+     * `loginUrl`/`logoutUrl` are surfaced in `GET /config.json`.
+     */
+    ui?: Ui | false | undefined
+    /**
+     * Verified-token management config (store shared with the main API's reads)
+     * to enable the `/verified-tokens` routes; omit to serve them as `404`.
+     */
+    verifiedTokens?:
+      | {
+          /** Verified-token state store (shared with the main API's reads). */
+          store: Store.State
+        }
+      | undefined
+  }
+
+  /** Admin UI options surfaced to the SPA via `GET /config.json`. */
+  type Ui = {
+    /** Where the deployer's sign-in page lives; shown by the UI on a `401`. */
+    loginUrl?: string | undefined
+    /** Where to send the user to sign out (e.g. Cloudflare Access logout). */
+    logoutUrl?: string | undefined
+  }
+}