@escalay/kit 0.0.0-stage → 1.8.0

package/src/browser/vector-search-block.tsx

@@ -0,0 +1,94 @@
+/**
+ * A suggested search UI over the `search-react` hooks, as a shadcn block: a search field that also takes a pasted (⌘V),
+ * dropped or picked picture, a look/meaning/both switch, a live status line and a results grid. The app renders each
+ * result (`renderResult`), so cards stay its own. Copy it, restyle it or skip it: the hooks carry all the logic.
+ *
+ * Install: `npx shadcn add escalay/api-kit/vector-search-ui`, or `kit add
+ * vector-search-ui --dir src/components/vector-search`. Needs the shadcn `button` and `input` (Radix or Base UI alike).
+ *
+ * @example
+ * const client = useMemo(() => createSearchClient<RecipeCard>({ path: '/api/search', similarPath: '/api/recipes/{slug}/similar' }), [])
+ * <VectorSearch client={client} getKey={(recipe) => recipe.slug} renderResult={({ item }) => <RecipeCard recipe={item} />} />
+ */
+import { useState, type ReactNode } from 'react'
+import { Button } from '@/components/ui/button'
+import { Input } from '@/components/ui/input'
+import { cn } from '@/lib/utils'
+import type { SearchBy, SearchClient, SearchResult } from './search-client'
+import { usePictureInput, useVectorSearch } from './search-react'
+
+const BY: { value: SearchBy; label: string }[] = [
+  { value: 'both', label: 'Both' },
+  { value: 'look', label: 'Look' },
+  { value: 'meaning', label: 'Meaning' },
+]
+
+export function VectorSearch<Item>({ client, renderResult, getKey, placeholder = 'Describe it, or paste a picture', limit, className }: { client: SearchClient<Item>; renderResult: (result: SearchResult<Item>) => ReactNode; getKey: (item: Item) => string; placeholder?: string; limit?: number; className?: string }) {
+  const search = useVectorSearch(client, { limit })
+  const [text, setText] = useState('')
+  const picture = usePictureInput({
+    onPicture: (file) => {
+      setText('')
+      search.setPicture(file)
+    },
+  })
+  const status =
+    search.status === 'loading' ? 'Searching…'
+    : search.status === 'error' ? search.error?.detail
+    : search.status === 'done' ? (search.results.length ? `${search.results.length} ${search.results.length === 1 ? 'match' : 'matches'}, best first` : 'Nothing stands out. Try other words, or compare by both.')
+    : 'Type what you are looking for, or paste (⌘V), drop or choose a picture.'
+
+  return (
+    <div {...picture.dropProps} data-dragging={picture.dragging || undefined} className={cn('flex flex-col gap-4 rounded-lg', picture.dragging && 'ring-2 ring-ring ring-offset-2', className)}>
+      <div className="flex flex-wrap items-center gap-2">
+        <div className="relative flex min-w-0 flex-1 items-center">
+          {search.input.kind === 'picture' ? (
+            <span className="absolute left-1.5 flex items-center">
+              <img src={search.input.preview} alt="Your picture" className="size-7 rounded object-cover" />
+              <button type="button" aria-label="Remove the picture" onClick={search.clear} className="-ml-2 -mt-6 grid size-4 place-items-center rounded-full bg-foreground text-[10px] leading-none text-background">
+                ×
+              </button>
+            </span>
+          ) : null}
+          <Input
+            type="search"
+            value={text}
+            placeholder={search.input.kind === 'picture' ? 'Searching by your picture' : placeholder}
+            aria-label="Search"
+            className={cn(search.input.kind === 'picture' && 'pl-12')}
+            onChange={(event) => {
+              setText(event.target.value)
+              search.setWords(event.target.value)
+            }}
+          />
+        </div>
+        <Button type="button" variant="outline" onClick={picture.openPicker}>
+          Picture
+        </Button>
+        <input {...picture.inputProps} />
+        <div role="group" aria-label="Compare by" className="flex gap-1">
+          {BY.map(({ value, label }) => (
+            <Button key={value} type="button" size="sm" variant={search.by === value ? 'secondary' : 'ghost'} aria-pressed={search.by === value} onClick={() => search.setBy(value)}>
+              {label}
+            </Button>
+          ))}
+        </div>
+      </div>
+      <p role="status" aria-live="polite" className="flex items-center gap-2 text-sm text-muted-foreground">
+        {status}
+        {search.status === 'error' ? (
+          <Button type="button" variant="link" size="sm" onClick={search.retry}>
+            Retry
+          </Button>
+        ) : null}
+      </p>
+      {search.results.length ? (
+        <ul className="grid grid-cols-2 gap-4 sm:grid-cols-3 lg:grid-cols-4">
+          {search.results.map((result) => (
+            <li key={getKey(result.item)}>{renderResult(result)}</li>
+          ))}
+        </ul>
+      ) : null}
+    </div>
+  )
+}

package/src/core/README.md

@@ -0,0 +1,37 @@
+# core
+
+The API itself: `createAgentApi` builds an OpenAPIHono app that already follows the standard (problem+json errors,
+HAL, auth, caching, discovery), so an app only adds its routes. Every other server module builds on it.
+
+Needs: `hono`, `@hono/zod-openapi`, `zod`, `jose`, `@scalar/hono-api-reference`.
+
+```ts
+import { createAgentApi, parseApiKeys, problemResponses, HAL_JSON, linksOf, originOf, ProblemError } from './kit/index.js'
+
+const app = createAgentApi({
+  title: 'Notes', version: '1.0.0', description: 'What it is and where to start (Markdown).',
+  tags: [{ name: 'Notes', description: 'The notes.' }],       // the workflow tag first: the generated guide follows tag order
+  auth: { realm: 'notes', keys: parseApiKeys(env.API_KEYS), access },
+  oauth,                                                        // optional: createOAuth(…) from the oauth module
+  private: true,                                                // optional: nothing readable without credentials, noindex
+})
+```
+
+| File | What |
+|---|---|
+| `api.ts` | `createAgentApi`: request ids, secure headers, CORS, auth, strict query parameters (unknown ones answer 400), `Idempotency-Key` replay, `/openapi.json`, `/docs`, `/problems/{code}`, `/api/health`, the discovery it can serve alone |
+| `problem.ts` | RFC 9457: `ProblemError` (throw it), `PROBLEMS`, `problemResponses(400, 404…)` for a route's documented errors, `problemResponse` |
+| `hal.ts` | `linksOf(origin, { self, next… })`, `originOf(c)` (the public origin behind proxies), `pathWith(path, query)`, `LinksSchema`, `HAL_JSON` |
+| `auth.ts` | API keys (only hashes kept: `hashApiKey`, `mintApiKey`, `parseApiKeys`), Cloudflare Access, `authenticate`; `SCOPES`, `OAUTH_OPEN_PATHS` and the `OAuthServer` shape the oauth module fills |
+| `cache.ts` | `snapshotEtag` (on Workers pass `boot: env.CF_VERSION_METADATA.id`), `CACHE` presets, `cacheControl` |
+| `guards.ts` | `idempotency` (wired for you) and `rateLimit({ policy, limit, windowSeconds, store? })` for anything that spends money; both keep state in a `GuardStore`: `memoryGuardStore()` (default, one Node process) or `dbGuardStore(db)` from `db` (every instance shares it: required on Workers), passed as `createAgentApi({ guards: { store } })` and to each `rateLimit` |
+| `discovery.ts` | api-catalog, Link headers, robots.txt with Content Signals, Markdown for agents, skills index, Server Card, `serveAiCatalog` |
+| `kv.ts` | `KeyValueStore` (values with expiry) and `memoryStore`, what OAuth and A2A keep |
+
+## Rules
+
+- Every route is `createRoute` + `app.openapi`: camelCase `operationId`, a summary, a description whose first sentence
+  says what it is for, described parameters with real examples, a named HAL response, `...problemResponses(…)`.
+- Errors are thrown as `ProblemError('not_found', { detail })`; the detail says what to do next.
+- A route that spends money answers 202 with a run when slow and carries a `rateLimit`.
+- The standard behind all of this: `docs/STANDARD.md` §1–9, §12, §14.

package/src/core/api.ts

@@ -0,0 +1,239 @@
+/**
+ * One call gives an app the whole standard: an `OpenAPIHono` whose every error is problem+json, every request has an
+ * id, the OpenAPI 3.1 document at `/openapi.json` describes auth, tags and the agent guide, Scalar renders it at
+ * `/docs`, `/problems/{code}` explains each error, and `/api/health` answers without a key. The app then adds its own
+ * routes with `createRoute` and `app.openapi`.
+ *
+ * @example
+ * const app = createAgentApi({
+ *   title: 'Cookbook', version: '1.0.0', description: 'What it is and where to start.',
+ *   tags: [{ name: 'Catalog', description: 'Cooks, recipes, menus' }],
+ *   auth: { realm: 'cookbook', keys: parseApiKeys(process.env.API_KEYS), access: { team: 'example', audience: process.env.ACCESS_AUD ?? '' } },
+ *   health: () => ({ snapshot: store.snapshot }),
+ * })
+ * app.openapi(getAppRoute, (c) => c.json(appOf(c.req.valid('param').id), 200))
+ */
+import { createRoute, OpenAPIHono, z } from '@hono/zod-openapi'
+import { Scalar } from '@scalar/hono-api-reference'
+import type { MiddlewareHandler } from 'hono'
+import { cors } from 'hono/cors'
+import { requestId } from 'hono/request-id'
+import { secureHeaders } from 'hono/secure-headers'
+import { authenticate, OAUTH_OPEN_PATHS, SCOPES, type OAuthServer } from './auth.js'
+import { cacheControl, CACHE } from './cache.js'
+import { idempotency, type GuardStore } from './guards.js'
+import { API_CATALOG_TYPE, apiCatalog, LINK_HEADER, markdownTokens, MARKDOWN_TYPE, poppyJson, robotsTxt, sendPublic, sitemapXml, WELL_KNOWN, wantsMarkdown, type DiscoveryConfig } from './discovery.js'
+import { HAL_JSON, originOf } from './hal.js'
+import { errorHandler, notFoundHandler, PROBLEMS, problemResponse, problemResponses, validationHook, type ProblemCode } from './problem.js'
+
+export type AgentApiConfig = {
+  title: string
+  version: string
+  /** Markdown for the top of the OpenAPI document and the docs page: what this is, where to start. */
+  description: string
+  tags: { name: string; description: string }[]
+  /** Scalar's sidebar groups (`x-tagGroups`). */
+  tagGroups?: { name: string; tags: string[] }[]
+  auth: Parameters<typeof authenticate>[0]
+  /** Extra fields for `/api/health`, e.g. the snapshot the API serves. */
+  health?: () => Record<string, unknown>
+  /** Origins allowed to call from a browser; the API's own pages are same-origin and need none. */
+  corsOrigins?: string[]
+  /** robots.txt: Content Signals and crawling (defaults: private, no, no, no). See `discovery.ts`. */
+  discovery?: DiscoveryConfig
+  /** `docs` (default): `/` sends people to `/docs` and agents asking for Markdown to the guide. `false`: the app serves `/`. */
+  home?: 'docs' | false
+  /** The service as its own OAuth server (`createOAuth`): mounted here, its tokens accepted beside keys. */
+  oauth?: OAuthServer
+  /** Where Idempotency-Key answers are kept (default: this process's memory). On Workers: `dbGuardStore(db)`. */
+  guards?: { store?: GuardStore }
+  /**
+   * Private: nothing about the service is readable without credentials. Only `robots.txt`, `/api/health` (status only),
+   * the error pages and what an OAuth client needs to ask for access stay open; the guide, docs, spec, discovery files
+   * and agent cards need a key, a token or the Access cookie. Every response says `noindex`, and no page points at
+   * the guide. Agents still connect: MCP clients through OAuth (the 401 names the resource metadata), others with a key.
+   */
+  private?: boolean
+}
+
+/** What an OAuth client needs before it holds a token, and nothing more (private mode). */
+const PRIVATE_OPEN = ['/robots.txt', '/api/health', '/problems/*', '/.well-known/oauth-protected-resource*', '/.well-known/oauth-authorization-server*', '/.well-known/jwks.json']
+const PRIVATE_OAUTH_OPEN = ['/oauth/*', '/agent/identity', '/agent/identity/claim']
+const NOINDEX = 'noindex, nofollow, noarchive, nosnippet, noimageindex'
+
+export const SECURITY_SCHEME = 'apiKey'
+
+type Parameter = { name?: string; in?: string; required?: boolean; description?: string; example?: unknown; schema?: { description?: string; example?: unknown; type?: string; maxLength?: number } }
+type OpenApiDocument = { paths?: Record<string, Record<string, { parameters?: Parameter[] }>> } & Record<string, unknown>
+
+const IDEMPOTENCY_HEADER = {
+  name: 'Idempotency-Key',
+  in: 'header',
+  required: false,
+  description: 'Any unique string (a UUID): a retry with the same key and body gets the first answer instead of doing the work twice; the same key with another body is a 422. Kept 24 hours.',
+  schema: { type: 'string', maxLength: 255 },
+}
+
+/**
+ * Copies each parameter's schema description and example up to the parameter, where OpenAPI readers look first, and
+ * documents `Idempotency-Key` on every POST and PATCH (the kit honours it on all of them).
+ */
+export const hoistParameterDocs = (doc: OpenApiDocument) => {
+  for (const item of Object.values(doc.paths ?? {}))
+    for (const [method, operation] of Object.entries(item)) {
+      if (method === 'post' || method === 'patch') operation.parameters = [...(operation.parameters ?? []), IDEMPOTENCY_HEADER as Parameter]
+      for (const parameter of operation.parameters ?? []) {
+        parameter.description ??= parameter.schema?.description
+        if (parameter.example === undefined && parameter.schema?.example !== undefined) parameter.example = parameter.schema.example
+      }
+    }
+  return doc
+}
+
+/**
+ * A parameter the operation doesn't declare is an error, not a no-op: `?since=` on a route without it would otherwise
+ * answer 200 as if it had filtered. The allowed names come from each route's own query schema, read once.
+ */
+const rejectUnknownQuery = (app: OpenAPIHono): MiddlewareHandler => {
+  let routes: { method: string; pattern: RegExp; allowed: Set<string> }[] | null = null
+  return async (c, next) => {
+    routes ??= app.openAPIRegistry.definitions.flatMap((definition) => {
+      if (definition.type !== 'route') return []
+      const { method, path, request } = definition.route as { method: string; path: string; request?: { query?: { shape?: Record<string, unknown> } } }
+      return [{ method: method.toUpperCase(), pattern: new RegExp(`^${path.replace(/\{[^}]+\}/g, '[^/]+')}$`), allowed: new Set(Object.keys(request?.query?.shape ?? {})) }]
+    })
+    const route = routes.find((candidate) => candidate.method === c.req.method && candidate.pattern.test(c.req.path))
+    const unknown = route ? Object.keys(c.req.queries()).filter((name) => !route.allowed.has(name)) : []
+    if (!unknown.length) return next()
+    const allowed = route!.allowed.size ? `Allowed here: ${[...route!.allowed].join(', ')}.` : 'This operation takes no query parameters.'
+    return problemResponse(c, 'bad_request', { detail: `Unknown query parameter${unknown.length > 1 ? 's' : ''} ${unknown.join(', ')}. ${allowed}`, errors: unknown.map((name) => ({ in: 'query' as const, path: name, message: 'not a parameter of this operation' })) })
+  }
+}
+
+/** The pages an agent lands on first; each carries the RFC 8288 pointers, as does every 401. */
+const LINKED = new Set(['/', '/api', WELL_KNOWN.health, WELL_KNOWN.docs, WELL_KNOWN.guide])
+const linkHeaders: MiddlewareHandler = async (c, next) => {
+  await next()
+  if (LINKED.has(c.req.path) || c.res.status === 401) c.res.headers.append('link', LINK_HEADER)
+}
+
+/** `Accept: text/markdown` on `/` or `/docs` gets the agent guide (llms.txt) instead of HTML; browsers still get HTML. */
+const markdownForAgents = (app: { request: (input: string, init?: RequestInit) => Response | Promise<Response> }): MiddlewareHandler => async (c, next) => {
+  if (c.req.method !== 'GET' || (c.req.path !== '/' && c.req.path !== WELL_KNOWN.docs) || !wantsMarkdown(c.req.header('accept'))) {
+    await next()
+    if (c.req.path === '/' || c.req.path === WELL_KNOWN.docs) c.res.headers.append('vary', 'Accept')
+    return
+  }
+  const guide = await app.request(WELL_KNOWN.guide, { headers: { 'x-forwarded-proto': new URL(originOf(c)).protocol.slice(0, -1), 'x-forwarded-host': new URL(originOf(c)).host } })
+  if (!guide.ok) return next()
+  const text = await guide.text()
+  return c.body(text, 200, { 'content-type': MARKDOWN_TYPE, 'x-markdown-tokens': String(markdownTokens(text)), vary: 'Accept', 'cache-control': CACHE.docs })
+}
+
+export const createAgentApi = (config: AgentApiConfig) => {
+  const app = new OpenAPIHono({ defaultHook: validationHook as never })
+  const home = config.home ?? 'docs'
+  // Discovery is public: what exists and how to reach it, never the data
+  const discovery = ['/robots.txt', '/sitemap.xml', '/.well-known/*', '*/server-card', ...(home === 'docs' ? ['/'] : [])]
+  const open = config.private
+    ? [...PRIVATE_OPEN, ...(config.oauth ? PRIVATE_OAUTH_OPEN : []), ...(config.auth.open ?? [])]
+    : ['/api/health', '/openapi.json', '/docs', '/llms.txt', '/llms-full.txt', '/agents/*', '/skills/*', '/problems/*', ...discovery, ...(config.oauth ? OAUTH_OPEN_PATHS : []), ...(config.auth.open ?? [])]
+
+  app.use('*', requestId({ headerName: 'x-request-id' }))
+  app.use('*', secureHeaders({ crossOriginResourcePolicy: false, contentSecurityPolicy: undefined }))
+  // Same-site unless a route says otherwise (a sandboxed page's own files must load from its opaque origin)
+  app.use('*', async (c, next) => {
+    await next()
+    if (!c.res.headers.has('cross-origin-resource-policy')) c.res.headers.set('cross-origin-resource-policy', 'same-site')
+  })
+  if (config.corsOrigins?.length) app.use('*', cors({ origin: config.corsOrigins, exposeHeaders: ['etag', 'link', 'retry-after', 'x-request-id'] }))
+  // Before auth, so a 401 also tells an agent where the catalog and docs are
+  if (config.private)
+    app.use('*', async (c, next) => {
+      await next()
+      c.res.headers.set('x-robots-tag', NOINDEX)
+      // Anything readable only with credentials must never sit in a shared cache (Cloudflare keeps .txt and .js by extension)
+      const cache = c.res.headers.get('cache-control')
+      if (cache?.includes('public') && c.req.path !== '/robots.txt') c.res.headers.set('cache-control', cache.replace('public', 'private'))
+    })
+  else {
+    app.use('*', linkHeaders)
+    app.use('*', markdownForAgents(app))
+  }
+  app.use('*', authenticate({ relay: ['/mcp', '/a2a'], ...config.auth, open, ...(config.oauth ? { tokens: config.oauth.verify, resourceMetadata: config.oauth.resourceMetadataFor } : {}) }) as MiddlewareHandler)
+  app.use('*', cacheControl({ '/openapi.json': CACHE.docs, '/problems/': CACHE.docs, '/api/': CACHE.api }))
+  // Resources under /api are HAL; Hono writes plain JSON, so name the media type once here
+  app.use('/api/*', async (c, next) => {
+    await next()
+    if (c.res.status < 300 && c.req.path !== '/api/health' && c.res.headers.get('content-type')?.startsWith('application/json')) c.res.headers.set('content-type', HAL_JSON)
+  })
+  app.use('*', rejectUnknownQuery(app))
+  // After auth: a retried POST is recognised per caller
+  app.use('*', idempotency({ store: config.guards?.store }))
+  app.onError(errorHandler)
+  app.notFound(notFoundHandler)
+
+  app.openAPIRegistry.registerComponent('securitySchemes', SECURITY_SCHEME, {
+    type: 'http',
+    scheme: 'bearer',
+    description: 'An API key per client: `Authorization: Bearer <key>`. People reach the same routes through the single sign-on in front of the site.',
+  })
+  if (config.oauth) {
+    app.openAPIRegistry.registerComponent('securitySchemes', 'oauth', {
+      type: 'oauth2',
+      description: 'An OAuth token the owner approved: authorization code with PKCE (clients register at `/oauth/register`), or agent registration as `/auth.md` describes.',
+      flows: { authorizationCode: { authorizationUrl: '/oauth/authorize', tokenUrl: '/oauth/token', refreshUrl: '/oauth/token', scopes: Object.fromEntries(SCOPES.map((scope) => [scope, scope === 'read' ? 'Read everything' : 'Make changes (boards)'])) } },
+    })
+    config.oauth.mount(app)
+  }
+
+  app.openapi(
+    createRoute({
+      method: 'get',
+      path: '/api/health',
+      operationId: 'getHealth',
+      summary: 'Health check',
+      description: 'Answers without a key: `ok` while the service can serve, with the version it runs.',
+      tags: ['Meta'],
+      security: [],
+      responses: {
+        200: { description: 'The service is up.', content: { 'application/json': { schema: z.object({ status: z.literal('ok'), version: z.string() }).catchall(z.unknown()).openapi('Health', { description: 'Up, with the version it runs and what it serves.' }) } } },
+        ...problemResponses(503),
+      },
+    }),
+    (c) => c.json({ status: 'ok' as const, version: config.version, ...(config.private ? {} : config.health?.()) }, 200),
+  )
+
+  app.get('/problems/:code', (c) => {
+    const code = c.req.param('code') as ProblemCode
+    if (!(code in PROBLEMS)) return problemResponse(c, 'not_found', { detail: `No problem type "${code}". All of them: ${Object.keys(PROBLEMS).join(', ')}.` })
+    const problem = PROBLEMS[code]
+    return c.json({ code, status: problem.status, title: problem.title, description: problem.description })
+  })
+
+  // The generator leaves a parameter's description and example inside its schema; tools and agents read them on the
+  // parameter, so lift them there
+  app.get('/openapi.json', (c) => {
+    const doc = app.getOpenAPI31Document({
+      openapi: '3.1.0',
+      info: { title: config.title, version: config.version, description: config.description },
+      servers: [{ url: originOf(c), description: 'This server' }],
+      security: [{ [SECURITY_SCHEME]: [] }, ...(config.oauth ? [{ oauth: [...SCOPES] }] : [])],
+      tags: [...config.tags, { name: 'Meta', description: 'Health and errors.' }],
+      externalDocs: { url: `${originOf(c)}/llms.txt`, description: 'Agent guide: concepts, every endpoint with examples, trust and limits, and task playbooks.' },
+    }) as unknown as OpenApiDocument
+    return c.json({ ...hoistParameterDocs(doc), ...(config.tagGroups ? { 'x-tagGroups': [...config.tagGroups, { name: 'Meta', tags: ['Meta'] }] } : {}) })
+  })
+  app.get('/docs', Scalar({ url: '/openapi.json', pageTitle: `${config.title} — API`, hideClientButton: false, defaultOpenAllTags: false }))
+
+  app.get(WELL_KNOWN.apiCatalog, (c) => sendPublic(c, JSON.stringify(apiCatalog(originOf(c)), null, 2), API_CATALOG_TYPE))
+  app.get('/robots.txt', (c) => sendPublic(c, robotsTxt(config.private ? { private: true } : (config.discovery ?? {}), originOf(c)), 'text/plain; charset=utf-8'))
+  const { sitemap, poppy } = config.private ? {} : (config.discovery ?? {})
+  if (sitemap?.length) app.get('/sitemap.xml', (c) => sendPublic(c, sitemapXml(originOf(c), sitemap), 'application/xml; charset=utf-8'))
+  if (poppy) app.get('/.well-known/poppy.json', (c) => sendPublic(c, JSON.stringify(poppyJson(originOf(c), poppy, Boolean(config.oauth)), null, 2), 'application/json'))
+  if (home === 'docs') app.get('/', (c) => c.redirect('/docs', 302))
+
+  return app
+}
+
+export type AgentApi = ReturnType<typeof createAgentApi>

package/src/core/auth.ts

@@ -0,0 +1,147 @@
+/**
+ * Who may call: agents and scripts with an API key (`Authorization: Bearer <key>`), people through Cloudflare Access
+ * (its signed `Cf-Access-Jwt-Assertion` header, checked against the team's keys so a misrouted request without Access
+ * in front is still refused). A browser app on the same host also sends Access's `CF_Authorization` cookie, the same
+ * signed token, on paths that bypass the gate; it is accepted too, and writes made with it must come from the same
+ * site (`Sec-Fetch-Site` / `Origin`), so another site can't post through someone's login. The service only ever holds key *hashes* (`API_KEYS=name:sha256,…`); the keys themselves
+ * live in your secret store, one per client, so revoking one is removing its line.
+ *
+ * @example
+ * const { key, hash } = mintApiKey('cli')                  // once per client: key → the secret store, `laptop:<hash>` → API_KEYS
+ * app.use('*', authenticate({ realm: 'cookbook', keys: parseApiKeys(process.env.API_KEYS), access: { team: 'example', audience: process.env.ACCESS_AUD }, open: ['/llms.txt', '/api/health'] }))
+ * c.get('caller') // { kind: 'key', name: 'laptop' } or { kind: 'person', email: '…' }
+ */
+import { createHash, randomBytes } from 'node:crypto'
+import type { Context, Hono, MiddlewareHandler } from 'hono'
+import { getCookie } from 'hono/cookie'
+import { createRemoteJWKSet, jwtVerify } from 'jose'
+import { problemResponse } from './problem.js'
+
+/** What an OAuth token can do: `read` for safe methods, `write` for the rest. */
+export const SCOPES = ['read', 'write'] as const
+
+/** The paths an app with an OAuth server must leave open to anonymous callers: discovery, registration, the token endpoints, auth.md. */
+export const OAUTH_OPEN_PATHS = ['/.well-known/*', '/auth.md', '/oauth/*', '/agent/identity', '/agent/identity/claim']
+
+/** What `createAgentApi` needs from an OAuth server (`createOAuth`, the `oauth` module): mount it, check its tokens, name its metadata. */
+export type OAuthServer = {
+  mount: (app: Hono<any>) => void
+  verify: NonNullable<AuthOptions['tokens']>
+  resourceMetadataFor: (c: Context) => string
+}
+
+export type Caller = { kind: 'key'; name: string } | { kind: 'person'; email: string } | { kind: 'agent'; name: string; scopes: string[]; owner: string }
+
+export const hashApiKey = (key: string) => createHash('sha256').update(key).digest('hex')
+
+/** A new key, `<prefix>_` + 192 random bits in base64url, and the hash the service stores. */
+export const mintApiKey = (prefix: string) => {
+  const key = `${prefix}_${randomBytes(24).toString('base64url')}`
+  return { key, hash: hashApiKey(key) }
+}
+
+/** `laptop:<sha256>,ci:<sha256>` → hash → client name. Malformed entries are refused loudly at boot. */
+export const parseApiKeys = (value: string | undefined) => {
+  const keys = new Map<string, string>()
+  for (const entry of (value ?? '').split(',').map((part) => part.trim()).filter(Boolean)) {
+    const [name, hash] = entry.split(':')
+    if (!name || !hash || !/^[0-9a-f]{64}$/.test(hash)) throw new Error(`API_KEYS entry "${name ?? entry}" is not name:sha256`)
+    keys.set(hash, name)
+  }
+  return keys
+}
+
+const SAFE = new Set(['GET', 'HEAD', 'OPTIONS'])
+
+/** A write sent with a cookie must come from this host: browsers say so in `Sec-Fetch-Site`, older ones in `Origin`. */
+const sameSite = (c: Context) => {
+  const site = c.req.header('sec-fetch-site')
+  if (site) return site === 'same-origin'
+  const origin = c.req.header('origin')
+  return Boolean(origin) && new URL(origin!).host === new URL(c.req.url).host
+}
+
+const bearerOf = (c: Context) => {
+  const header = c.req.header('authorization') ?? ''
+  return /^bearer\s+/i.test(header) ? header.replace(/^bearer\s+/i, '').trim() : undefined
+}
+
+/** Checks a Cloudflare Access token against the team's published keys (cached by jose). */
+export const accessVerifier = ({ team, audience }: { team: string; audience: string }) => {
+  const issuer = `https://${team}.cloudflareaccess.com`
+  const keys = createRemoteJWKSet(new URL(`${issuer}/cdn-cgi/access/certs`))
+  return async (token: string) => {
+    const { payload } = await jwtVerify(token, keys, { issuer, audience })
+    return typeof payload.email === 'string' ? payload.email : null
+  }
+}
+
+/** The signed-in person on a page behind Access (header or cookie), for OAuth's approval pages: their email, or null. */
+export const accessOwner = (access: AccessOptions) => {
+  const verify = access.verify ?? accessVerifier(access)
+  return async (c: Context) => {
+    const assertion = c.req.header('cf-access-jwt-assertion') ?? getCookie(c, 'CF_Authorization')
+    return assertion ? verify(assertion).catch(() => null) : null
+  }
+}
+
+// `/llms.txt` matches itself, `/skills/x.md` matches `/skills/*`, and a leading star matches a suffix (`/mcp/server-card`)
+const matches = (path: string, pattern: string) =>
+  pattern.endsWith('*') ? path.startsWith(pattern.slice(0, -1)) : pattern.startsWith('*') ? path.endsWith(pattern.slice(1)) : path === pattern
+
+export type AccessOptions = { team: string; audience: string; /** Replaces the JWKS check, for tests. */ verify?: (token: string) => Promise<string | null> }
+
+export type AuthOptions = {
+  realm: string
+  keys: Map<string, string>
+  access?: AccessOptions
+  open?: string[]
+  /** OAuth access tokens (`oauth.ts`): a JWT → its caller, or null. Keys still work beside them. */
+  tokens?: (jwt: string, c: Context) => Promise<{ kind: 'agent'; name: string; scopes: string[]; owner: string } | null>
+  /** Where a 401 points (`WWW-Authenticate: … resource_metadata=`): a URL, or one per request. */
+  resourceMetadata?: string | ((c: Context) => string)
+  /** Endpoints that POST but only relay to routes in-process (MCP, A2A): a token needs just `read` there, each route checks its own scope. */
+  relay?: string[]
+}
+
+const isJwt = (value: string) => /^[\w-]+\.[\w-]+\.[\w-]+$/.test(value)
+
+export const authenticate = ({ realm, keys, access, open = [], tokens, resourceMetadata, relay = [] }: AuthOptions): MiddlewareHandler => {
+  const verifyAccess = access?.verify ?? (access?.audience ? accessVerifier(access) : null)
+  return async (c, next) => {
+    if (c.req.method === 'OPTIONS' || open.some((pattern) => matches(c.req.path, pattern))) return next()
+    const key = bearerOf(c)
+    const name = key ? keys.get(hashApiKey(key)) : undefined
+    if (name) {
+      c.set('caller' as never, { kind: 'key', name } satisfies Caller as never)
+      return next()
+    }
+    const agent = key && tokens && isJwt(key) ? await tokens(key, c) : null
+    if (agent) {
+      // read covers what an agent can look at; anything that changes state needs write
+      const needed = SAFE.has(c.req.method) || relay.includes(c.req.path) ? 'read' : 'write'
+      if (!agent.scopes.includes(needed)) return problemResponse(c, 'forbidden', { detail: `This token lacks the ${needed} scope: authorize again asking for it.`, headers: { 'www-authenticate': `Bearer realm="${realm}", error="insufficient_scope", scope="${needed}"` } })
+      c.set('caller' as never, agent satisfies Caller as never)
+      return next()
+    }
+    const header = c.req.header('cf-access-jwt-assertion')
+    const cookie = header ? undefined : getCookie(c, 'CF_Authorization')
+    const assertion = header ?? cookie
+    if (!key && assertion && verifyAccess) {
+      const email = await verifyAccess(assertion).catch(() => null)
+      if (email && cookie && !SAFE.has(c.req.method) && !sameSite(c))
+        return problemResponse(c, 'forbidden', { detail: 'A write signed in with the Access cookie must come from this site.' })
+      if (email) {
+        c.set('caller' as never, { kind: 'person', email } satisfies Caller as never)
+        return next()
+      }
+    }
+    const metadata = typeof resourceMetadata === 'function' ? resourceMetadata(c) : resourceMetadata
+    const challenge = [`Bearer realm="${realm}"`, ...(key ? ['error="invalid_token"'] : []), ...(metadata ? [`resource_metadata="${metadata}"`] : [])].join(', ')
+    const howToGetOne = tokens ? ' Or get a token yourself: OAuth from the resource metadata in WWW-Authenticate, or /auth.md.' : ''
+    return problemResponse(c, 'unauthorized', {
+      detail: key ? `This token or API key is not valid (expired, revoked, mistyped, or for another service).${howToGetOne}` : `Send an API key: \`Authorization: Bearer <key>\`. Keys are issued per client; ask the owner for one.${howToGetOne}`,
+      headers: { 'www-authenticate': challenge },
+    })
+  }
+}

package/src/core/cache.ts

@@ -0,0 +1,53 @@
+/**
+ * Caching for read-mostly data. An API over a snapshot changes only when the snapshot or the code serving it does, so
+ * a GET's ETag is the snapshot version, this process's start and the URL: a client that sends it back in
+ * `If-None-Match` gets `304 Not Modified` without the route running, and a deploy never leaves it on an old answer. `Cache-Control` says how long each kind of response may be kept; errors are never stored.
+ *
+ * @example
+ * app.use('/api/*', snapshotEtag(() => store.version, { skip: (path) => path.startsWith('/api/v1/boards') }))
+ * app.use('*', cacheControl({ '/media/': CACHE.media, '/api/': CACHE.api }))
+ */
+import { createHash, randomUUID } from 'node:crypto'
+import type { MiddlewareHandler } from 'hono'
+
+export const CACHE = {
+  /** Revalidate every time (cheap with ETags), keep out of shared caches. */
+  api: 'private, no-cache',
+  /** Images and videos never change under the same URL. */
+  media: 'private, max-age=86400, immutable',
+  /** Guides and the OpenAPI document. */
+  docs: 'private, max-age=300',
+  error: 'no-store',
+} as const
+
+/**
+ * Changes on every start, so answers a code change altered are never confirmed from before it. Made on first use:
+ * Workers refuse random values at global scope.
+ */
+let started: string | undefined
+const startId = () => (started ??= randomUUID())
+
+/**
+ * `boot` names the deploy instead of the process: on Workers pass the version id (`env.CF_VERSION_METADATA.id`), so
+ * every isolate of one deploy agrees on the ETag and a new deploy still changes it.
+ */
+export const snapshotEtag = (versionOf: () => string | undefined, { skip = () => false, boot }: { skip?: (path: string) => boolean; boot?: string } = {}): MiddlewareHandler =>
+  async (c, next) => {
+    const version = versionOf()
+    if ((c.req.method !== 'GET' && c.req.method !== 'HEAD') || !version || skip(c.req.path)) return next()
+    const tag = `W/"${createHash('sha256').update(`${version}|${boot ?? startId()}|${c.req.url}|${c.req.header('accept') ?? ''}`).digest('base64url').slice(0, 27)}"`
+    const sent = c.req.header('if-none-match')?.split(',').map((value) => value.trim())
+    if (sent?.includes(tag) || sent?.includes('*')) return c.body(null, 304, { etag: tag })
+    await next()
+    if (c.res.status === 200 && !c.res.headers.has('etag')) c.res.headers.set('etag', tag)
+  }
+
+/** The first matching path prefix sets `Cache-Control` on success; any error is `no-store`. */
+export const cacheControl = (byPrefix: Record<string, string>): MiddlewareHandler => async (c, next) => {
+  await next()
+  if (c.res.status >= 400) c.res.headers.set('cache-control', CACHE.error)
+  else if (!c.res.headers.has('cache-control')) {
+    const match = Object.entries(byPrefix).find(([prefix]) => c.req.path.startsWith(prefix))
+    if (match) c.res.headers.set('cache-control', match[1])
+  }
+}