@escalay/kit 0.0.0-stage → 1.8.0

package/src/core/discovery.ts

@@ -0,0 +1,315 @@
+/**
+ * How agents find an API before they hold a key: public, read-only metadata the kit serves from what the app already
+ * has, so none of it can drift from the real routes.
+ *   /.well-known/api-catalog            RFC 9727 linkset: the OpenAPI document, docs, guide and health
+ *   Link headers                        RFC 8288 on `/`, `/api`, health, the docs and every 401: the same pointers
+ *   /robots.txt                         Content Signals (ai-train, search, ai-input) and whether to crawl at all
+ *   Accept: text/markdown               `/` and `/docs` answer with the agent guide (llms.txt) instead of HTML
+ *   /.well-known/agent-skills/…         the skills index (Agent Skills Discovery v0.2.0) and one archive per skill
+ *   <mcp>/server-card                   the MCP Server Card (SEP-2127), also at /.well-known/mcp/server-card.json
+ *   /.well-known/ai-catalog.json        an AI Catalog listing all of the above (ARD)
+ *   /sitemap.xml                        the public pages (`discovery.sitemap`), named in robots.txt
+ *   /.well-known/poppy.json             Personal Agent Protocol discovery (`discovery.poppy`): the APIs and the issuer
+ * `createAgentApi`, `serveGuide` and `mountMcp` wire their parts themselves; an app adds `serveAiCatalog` last. OAuth
+ * metadata comes with `oauth.ts` when the app is its own authorization server.
+ *
+ * @example
+ * const app = createAgentApi({ …, discovery: { contentSignal: { aiTrain: false, search: false, aiInput: false } } })
+ * serveGuide(app, { dir, vars, full })              // skills index + archives
+ * mountMcp(app, { factory, allowedHostnames })      // server card
+ * serveAiCatalog(app, { host: 'Cookbook', queries: { api: ['find a quick dinner recipe'], mcp: ['…'] } })
+ */
+import { createHash } from 'node:crypto'
+import { gzipSync } from 'node:zlib'
+import type { Context, Hono } from 'hono'
+import { originOf } from './hal.js'
+
+/** What a discovery document links to; the kit serves each of these. */
+export const WELL_KNOWN = {
+  apiCatalog: '/.well-known/api-catalog',
+  skillsIndex: '/.well-known/agent-skills/index.json',
+  serverCard: '/.well-known/mcp/server-card.json',
+  aiCatalog: '/.well-known/ai-catalog.json',
+  agentCard: '/.well-known/agent-card.json',
+  openapi: '/openapi.json',
+  docs: '/docs',
+  guide: '/llms.txt',
+  health: '/api/health',
+} as const
+
+export const OPENAPI_TYPE = 'application/vnd.oai.openapi+json;version=3.1'
+export const MARKDOWN_TYPE = 'text/markdown; charset=utf-8'
+
+// ---- Shared response rules ----
+
+const PUBLIC_CACHE = 'public, max-age=3600'
+const CORS = {
+  'access-control-allow-origin': '*',
+  'access-control-allow-methods': 'GET, HEAD',
+  'access-control-allow-headers': 'Content-Type, If-None-Match',
+  'access-control-expose-headers': 'ETag',
+}
+
+export const sha256 = (bytes: string | Uint8Array) => createHash('sha256').update(bytes).digest('hex')
+
+/**
+ * A public metadata document: open CORS, an hour of caching, a strong ETag and `304` on `If-None-Match` (what the
+ * Server Card and skills specs ask for; harmless for the rest).
+ */
+export const sendPublic = (c: Context, body: string | Uint8Array, type: string) => {
+  const etag = `"${sha256(body).slice(0, 32)}"`
+  const headers = { 'content-type': type, 'cache-control': PUBLIC_CACHE, etag, ...CORS }
+  const sent = c.req.header('if-none-match')?.split(',').map((value) => value.trim())
+  if (sent?.includes(etag) || sent?.includes('*')) return c.body(null, 304, headers)
+  return c.body(typeof body === 'string' ? body : (body as Uint8Array<ArrayBuffer>), 200, headers)
+}
+
+// ---- RFC 9727 API catalog and RFC 8288 Link headers ----
+
+/** The API catalog for one API rooted at `<origin>/api`: its description, docs and status. */
+export const apiCatalog = (origin: string) => ({
+  linkset: [
+    {
+      anchor: `${origin}/api`,
+      'service-desc': [{ href: origin + WELL_KNOWN.openapi, type: OPENAPI_TYPE }],
+      'service-doc': [
+        { href: origin + WELL_KNOWN.docs, type: 'text/html' },
+        { href: origin + WELL_KNOWN.guide, type: 'text/markdown' },
+      ],
+      status: [{ href: origin + WELL_KNOWN.health, type: 'application/json' }],
+    },
+  ],
+})
+
+export const API_CATALOG_TYPE = 'application/linkset+json; profile="https://www.rfc-editor.org/info/rfc9727"'
+
+/** The `Link` header value pointing at the catalog and what it lists (relative references, valid per RFC 8288). */
+export const LINK_HEADER = [
+  `<${WELL_KNOWN.apiCatalog}>; rel="api-catalog"`,
+  `<${WELL_KNOWN.openapi}>; rel="service-desc"; type="${OPENAPI_TYPE}"`,
+  `<${WELL_KNOWN.docs}>; rel="service-doc"; type="text/html"`,
+  `<${WELL_KNOWN.guide}>; rel="describedby"; type="text/markdown"`,
+].join(', ')
+
+// ---- robots.txt with Content Signals ----
+
+export type DiscoveryConfig = {
+  /**
+   * Content Signals (contentsignals.org): may crawlers train on this, index it for search, use it as input to AI
+   * answers. Defaults to no, no, no: private by default.
+   */
+  contentSignal?: { aiTrain?: boolean; search?: boolean; aiInput?: boolean }
+  /** Whether crawlers may walk the site at all (`Disallow: /` when false, the default). */
+  crawl?: boolean
+  /** Public paths for `/sitemap.xml` (and its `Sitemap:` line in robots.txt). */
+  sitemap?: string[]
+  /** Personal Agent Protocol discovery: the organization's name and what it offers agents, as paths on this origin. */
+  poppy?: { name: string; apis?: { type: string; path: string; description: string }[]; protocols?: { type: string; path: string }[]; scopes?: Record<string, { description: string; changes: 'none' | 'reversible' | 'irreversible'; personalData: boolean }> }
+}
+
+export const robotsTxt = ({ contentSignal = {}, crawl = false, sitemap, private: hidden }: DiscoveryConfig & { private?: boolean }, origin: string) => {
+  const yesNo = (value: boolean | undefined) => (value ? 'yes' : 'no')
+  // A private service names nothing: no guide, no catalog, no sitemap
+  if (hidden) return ['User-agent: *', 'Content-Signal: ai-train=no, search=no, ai-input=no', 'Disallow: /', ''].join('\n')
+  return [
+    'User-agent: *',
+    `Content-Signal: ai-train=${yesNo(contentSignal.aiTrain)}, search=${yesNo(contentSignal.search)}, ai-input=${yesNo(contentSignal.aiInput)}`,
+    crawl ? 'Allow: /' : 'Disallow: /',
+    '',
+    `# Agents: the guide is ${origin}${WELL_KNOWN.guide}, the catalog ${origin}${WELL_KNOWN.aiCatalog}`,
+    `Agentmap: ${origin}${WELL_KNOWN.aiCatalog}`,
+    ...(sitemap?.length ? [`Sitemap: ${origin}/sitemap.xml`] : []),
+    '',
+  ].join('\n')
+}
+
+/** The sitemap of public pages (sitemaps.org). */
+export const sitemapXml = (origin: string, paths: string[]) =>
+  `<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n${paths.map((path) => `  <url><loc>${origin}${path.replace(/&/g, '&amp;')}</loc></url>`).join('\n')}\n</urlset>\n`
+
+/** `/.well-known/poppy.json` (Personal Agent Protocol draft 0.3, section 3): this origin is the organization and the issuer. */
+export const poppyJson = (origin: string, { name, apis = [], protocols = [], scopes }: NonNullable<DiscoveryConfig['poppy']>, withIssuer: boolean) => ({
+  protocol_version: '0.3',
+  organization: { name, domain: new URL(origin).hostname },
+  ...(withIssuer
+    ? {
+        auth: {
+          issuer: origin,
+          ...(scopes
+            ? {
+                scopes: Object.fromEntries(Object.entries(scopes).map(([scope, one]) => [scope, one.description])),
+                scope_hints: Object.fromEntries(Object.entries(scopes).map(([scope, one]) => [scope, { changes: one.changes, personal_data: one.personalData }])),
+              }
+            : {}),
+        },
+      }
+    : {}),
+  ...(protocols.length ? { agent: { protocols: protocols.map((one) => ({ type: one.type, endpoint: `${origin}${one.path}` })) } } : {}),
+  ...(apis.length ? { apis: apis.map((one) => ({ type: one.type, url: `${origin}${one.path}`, description: one.description })) } : {}),
+  web: {},
+})
+
+/** Rough tokens for `x-markdown-tokens`: about four characters each. */
+export const markdownTokens = (text: string) => Math.ceil(text.length / 4)
+
+/** True when the client asked for Markdown ahead of HTML (`Accept: text/markdown`). */
+export const wantsMarkdown = (accept: string | undefined) => {
+  const types = (accept ?? '').split(',').map((part) => part.split(';')[0]!.trim().toLowerCase())
+  const markdown = types.indexOf('text/markdown')
+  const html = types.indexOf('text/html')
+  return markdown >= 0 && (html < 0 || markdown < html)
+}
+
+// ---- Skills: index and deterministic archives ----
+
+export const SKILLS_INDEX_SCHEMA = 'https://schemas.agentskills.io/discovery/0.2.0/schema.json'
+
+/** `name` and `description` from a SKILL.md's YAML frontmatter (single-line values, as the skills spec writes them). */
+export const frontmatterOf = (markdown: string) => {
+  const block = markdown.match(/^---\n([\s\S]*?)\n---/)?.[1] ?? ''
+  const field = (key: string) => block.match(new RegExp(`^${key}:\\s*(.+)$`, 'm'))?.[1]?.trim().replace(/^(['"])(.*)\1$/, '$2')
+  return { name: field('name'), description: field('description') }
+}
+
+/**
+ * A gzipped ustar archive of `files` (path → text) with fixed metadata, so the same files always give the same bytes
+ * and the same digest. SKILL.md comes first; the skill's files sit at the root, as the discovery spec asks.
+ */
+export const tarGz = (files: [string, string][]) => {
+  const blocks: Buffer[] = []
+  const octal = (value: number, width: number) => value.toString(8).padStart(width - 1, '0') + '\0'
+  // SKILL.md first, so a reader can stop after it; the rest in a fixed order
+  for (const [path, text] of [...files].sort(([a], [b]) => Number(b === 'SKILL.md') - Number(a === 'SKILL.md') || a.localeCompare(b))) {
+    if (path.startsWith('/') || path.split('/').includes('..') || Buffer.byteLength(path) > 100) throw new Error(`Unsafe or too long archive path: ${path}`)
+    const content = Buffer.from(text, 'utf8')
+    const header = Buffer.alloc(512)
+    header.write(path, 0, 'utf8')
+    header.write(octal(0o644, 8), 100)
+    header.write(octal(0, 8), 108)
+    header.write(octal(0, 8), 116)
+    header.write(octal(content.length, 12), 124)
+    header.write(octal(0, 12), 136)
+    header.write('        ', 148)
+    header.write('0', 156)
+    header.write('ustar\0', 257)
+    header.write('00', 263)
+    let sum = 0
+    for (const byte of header) sum += byte
+    header.write(octal(sum, 7) + ' ', 148)
+    blocks.push(header, content, Buffer.alloc((512 - (content.length % 512)) % 512))
+  }
+  blocks.push(Buffer.alloc(1024))
+  return new Uint8Array(gzipSync(Buffer.concat(blocks), { level: 9 }))
+}
+
+export type SkillArtifact = { name: string; description: string; type: 'skill-md' | 'archive'; url: string; bytes: Uint8Array | string; mediaType: string }
+
+/** The index entry for each skill, its digest taken over the exact bytes its `url` serves. */
+export const skillsIndex = (origin: string, skills: SkillArtifact[]) => ({
+  $schema: SKILLS_INDEX_SCHEMA,
+  skills: skills.map((skill) => ({ name: skill.name, type: skill.type, description: skill.description, url: origin + skill.url, digest: `sha256:${sha256(skill.bytes)}` })),
+})
+
+// ---- MCP Server Card (SEP-2127) ----
+
+export const SERVER_CARD_SCHEMA = 'https://static.modelcontextprotocol.io/schemas/v1/server-card.schema.json'
+export const SERVER_CARD_TYPE = 'application/mcp-server-card+json'
+/** The 2026 revision the kit's servers speak; the SDK answers the 2025 ones through its fallback. */
+export const MODERN_PROTOCOL_VERSION = '2026-07-28'
+
+export type ServerCardInfo = { name: string; version: string; title?: string; description?: string; websiteUrl?: string }
+
+/** `cookbook.example.com` + `cookbook` → `com.example.cookbook/cookbook`: the reverse-DNS name the card spec asks for. */
+export const reverseDnsName = (origin: string, name: string) => `${new URL(origin).hostname.split('.').reverse().join('.')}/${name}`
+
+export const serverCard = (origin: string, path: string, info: ServerCardInfo, protocolVersions: string[]) => ({
+  $schema: SERVER_CARD_SCHEMA,
+  name: reverseDnsName(origin, info.name),
+  version: info.version,
+  description: info.description ?? info.title ?? info.name,
+  ...(info.title ? { title: info.title } : {}),
+  websiteUrl: info.websiteUrl ?? `${origin}${WELL_KNOWN.guide}`,
+  remotes: [
+    {
+      type: 'streamable-http' as const,
+      url: origin + path,
+      headers: [
+        {
+          name: 'Authorization',
+          description: 'An API key issued per client by the owner.',
+          isRequired: true,
+          isSecret: true,
+          value: 'Bearer {api_key}',
+          variables: { api_key: { description: 'Your API key.', isRequired: true, isSecret: true } },
+        },
+      ],
+      supportedProtocolVersions: protocolVersions,
+    },
+  ],
+})
+
+// ---- What an app has mounted, for the catalogs ----
+
+/** What the guide needs of an MCP tool: the kit's `McpTool` fits, so does any tool with a name, a description and a call. */
+export type ToolLike = { name: string; description: string; call: (args: never) => { method?: string; path: string } }
+/** What the guide needs of an MCP resource: its URI template and what it is. */
+export type ResourceLike = { uriTemplate: string; title: string; description: string }
+
+type Mounted = {
+  skills?: (origin: string) => SkillArtifact[]
+  /** Builds the skill artifacts for an origin (they are rendered per origin and per data snapshot). */
+  refreshSkills?: (origin: string, credentials?: Record<string, string>) => Promise<SkillArtifact[]>
+  mcp?: { path: string; card: (origin: string) => ReturnType<typeof serverCard>; tools: ToolLike[]; resources?: ResourceLike[] }
+}
+const mountedByApp = new WeakMap<object, Mounted>()
+
+/** `serveGuide` and `mountMcp` record what they serve so `serveAiCatalog` lists exactly that. */
+export const recordMounted = (app: object, part: Mounted) => mountedByApp.set(app, { ...mountedByApp.get(app), ...part })
+export const mountedOf = (app: object) => mountedByApp.get(app) ?? {}
+
+// ---- AI Catalog (ARD) ----
+
+export const AI_CATALOG_TYPE = 'application/ai-catalog+json'
+
+export type AiCatalogConfig = {
+  /** Who operates this, shown by registries. */
+  host: string
+  /** The publisher segment of `urn:air` identifiers; defaults to the request's host name. */
+  publisher?: string
+  /** 2–5 questions per artifact that registries embed to match it to what people ask. */
+  queries: { api: string[]; mcp?: string[]; skills?: Record<string, string[]> }
+}
+
+export const aiCatalog = (origin: string, config: AiCatalogConfig, mounted: Mounted, apiTitle: string) => {
+  const publisher = config.publisher ?? new URL(origin).hostname
+  const urn = (namespace: string, name: string) => `urn:air:${publisher}:${namespace}:${name}`
+  const card = mounted.mcp?.card(origin)
+  return {
+    specVersion: '1.0',
+    host: { displayName: config.host, identifier: `did:web:${new URL(origin).hostname}`, documentationUrl: origin + WELL_KNOWN.guide },
+    entries: [
+      { identifier: urn('api', 'openapi'), displayName: apiTitle, type: OPENAPI_TYPE, url: origin + WELL_KNOWN.openapi, representativeQueries: config.queries.api },
+      // ARD asks every entry for a displayName; the card's own title, so the two can't drift
+      ...(card && mounted.mcp ? [{ identifier: urn('mcp', card.name.split('/').pop()!), displayName: card.title ?? card.name, type: SERVER_CARD_TYPE, url: `${origin}${mounted.mcp.path}/server-card`, representativeQueries: config.queries.mcp ?? config.queries.api }] : []),
+      ...(mounted.skills?.(origin) ?? []).map((skill) => ({
+        identifier: urn('skill', skill.name),
+        displayName: skill.name,
+        description: skill.description,
+        type: skill.type === 'archive' ? 'application/agent-skills+gzip' : 'application/agent-skills+md',
+        url: origin + skill.url,
+        digest: `sha256:${sha256(skill.bytes)}`,
+        representativeQueries: config.queries.skills?.[skill.name] ?? config.queries.api,
+      })),
+    ],
+  }
+}
+
+/** Serves the AI Catalog over whatever the app mounted; call after `serveGuide` and `mountMcp`. */
+export const serveAiCatalog = (app: Hono<any, any, any>, config: AiCatalogConfig & { apiTitle: string }) => {
+  app.get(WELL_KNOWN.aiCatalog, async (c) => {
+    const mounted = mountedOf(app)
+    // The caller's own credentials: a private service renders its skills only for them
+    await mounted.refreshSkills?.(originOf(c), Object.fromEntries((['authorization', 'cookie', 'cf-access-jwt-assertion'] as const).flatMap((name) => (c.req.header(name) ? [[name, c.req.header(name)!]] : []))))
+    return sendPublic(c, JSON.stringify(aiCatalog(originOf(c), config, mounted, config.apiTitle), null, 2), AI_CATALOG_TYPE)
+  })
+}

package/src/core/guards.ts

@@ -0,0 +1,109 @@
+/**
+ * Two guards for calls that change something or cost money, both keyed by the caller:
+ *   idempotency   `Idempotency-Key` on POST and PATCH (IETF httpapi-idempotency-key): a retry with the same key and
+ *                 body gets the stored answer (`Idempotent-Replayed: true`), the same key with another body is a 422,
+ *                 one still in flight a 409. Kept 24 hours.
+ *   rateLimit     at most `limit` calls per `windowSeconds` per caller on the routes it guards, with the draft
+ *                 `RateLimit-Policy` / `RateLimit` headers (IETF httpapi-ratelimit-headers) and a 429 problem with
+ *                 `Retry-After` past it: a looping agent can't drain a paid budget.
+ * Both keep their state in a `GuardStore`: `memoryGuardStore()` (the default) is right for one Node process; on
+ * Workers, where every isolate has its own memory, pass `dbGuardStore(db)` (`db`) so all of them share it.
+ *
+ * @example
+ * const guards = await dbGuardStore(db)
+ * const app = createAgentApi({ …, guards: { store: guards } })                   // idempotency, wired for you
+ * app.use('/api/v1/products/:id/gaps', rateLimit({ policy: 'paid', limit: 120, windowSeconds: 3600, store: guards }))
+ */
+import { createHash } from 'node:crypto'
+import type { Context, MiddlewareHandler } from 'hono'
+import { problemResponse } from './problem.js'
+
+/** A stored answer to replay: the body is base64, so a store can keep it as JSON. */
+export type StoredAnswer = { bodyHash: string; status: number; headers: [string, string][]; body: string }
+
+/** Where the guards keep their state. Each method is atomic, so concurrent requests can't both pass a check. */
+export type GuardStore = {
+  /** Counts one call against `id`; a window that started `windowMs` ago or earlier starts over. */
+  count: (id: string, windowMs: number, now: number) => Promise<{ start: number; used: number }>
+  /**
+   * Claims an idempotency key for `lockMs`: null when this request now holds it, `'running'` when another request
+   * does, or the answer saved for it.
+   */
+  claim: (id: string, lockMs: number, now: number) => Promise<StoredAnswer | 'running' | null>
+  /** Saves the answer for a key this request holds, kept until `expiresAt` (epoch ms). */
+  save: (id: string, answer: StoredAnswer, expiresAt: number) => Promise<void>
+  /** Lets go of a key this request holds without an answer (a server error), so a retry can run. */
+  release: (id: string) => Promise<void>
+}
+
+/** The guards' state in this process's memory: one Node instance. Old entries go once there are `maxEntries`. */
+export const memoryGuardStore = ({ maxEntries = 2000 }: { maxEntries?: number } = {}): GuardStore => {
+  const windows = new Map<string, { start: number; used: number }>()
+  const keys = new Map<string, { answer: StoredAnswer | null; expiresAt: number }>()
+  const prune = (now: number) => {
+    for (const [id, entry] of keys) if (entry.expiresAt <= now || keys.size > maxEntries) keys.delete(id)
+  }
+  return {
+    count: async (id, windowMs, now) => {
+      const current = windows.get(id)
+      const window = current && now - current.start < windowMs ? current : { start: now, used: 0 }
+      window.used++
+      windows.set(id, window)
+      if (windows.size > maxEntries) for (const [old, entry] of windows) if (now - entry.start >= windowMs) windows.delete(old)
+      return { ...window }
+    },
+    claim: async (id, lockMs, now) => {
+      prune(now)
+      const entry = keys.get(id)
+      if (entry) return entry.answer ?? 'running'
+      keys.set(id, { answer: null, expiresAt: now + lockMs })
+      return null
+    },
+    save: async (id, answer, expiresAt) => void keys.set(id, { answer, expiresAt }),
+    release: async (id) => {
+      if (keys.get(id)?.answer === null) keys.delete(id)
+    },
+  }
+}
+
+const callerOf = (c: Context) => {
+  const caller = c.get('caller' as never) as { kind: string; name?: string; email?: string } | undefined
+  return caller ? `${caller.kind}:${caller.name ?? caller.email}` : `ip:${c.req.header('cf-connecting-ip') ?? c.req.header('x-forwarded-for') ?? 'local'}`
+}
+
+export const idempotency = ({ ttlMs = 24 * 60 * 60 * 1000, lockMs = 60_000, store = memoryGuardStore() }: { ttlMs?: number; lockMs?: number; store?: GuardStore } = {}): MiddlewareHandler =>
+  async (c, next) => {
+    const key = c.req.header('idempotency-key')
+    if (!key || (c.req.method !== 'POST' && c.req.method !== 'PATCH')) return next()
+    if (key.length > 255) return problemResponse(c, 'bad_request', { detail: 'Idempotency-Key is at most 255 characters.', errors: [{ in: 'header', path: 'Idempotency-Key', message: 'too long' }] })
+    const id = `${callerOf(c)} ${c.req.method} ${c.req.path} ${key}`
+    const bodyHash = createHash('sha256').update(new Uint8Array(await c.req.raw.clone().arrayBuffer())).digest('hex')
+    const now = Date.now()
+    const hit = await store.claim(id, lockMs, now)
+    if (hit === 'running') return problemResponse(c, 'conflict', { detail: 'A request with this Idempotency-Key is still running. Retry when it has answered.' })
+    if (hit) {
+      if (hit.bodyHash !== bodyHash) return problemResponse(c, 'unprocessable', { detail: 'This Idempotency-Key was used with a different body. Use a new key for a new request.' })
+      return new Response(Buffer.from(hit.body, 'base64'), { status: hit.status, headers: [...hit.headers, ['idempotent-replayed', 'true']] })
+    }
+    try {
+      await next()
+    } catch (error) {
+      await store.release(id)
+      throw error
+    }
+    // Server errors aren't kept: a retry with the same key should be able to succeed
+    if (c.res.status >= 500) return void (await store.release(id))
+    const body = Buffer.from(await c.res.clone().arrayBuffer()).toString('base64')
+    await store.save(id, { bodyHash, status: c.res.status, headers: [...c.res.headers.entries()], body }, now + ttlMs)
+  }
+
+export const rateLimit = ({ policy, limit, windowSeconds, store = memoryGuardStore() }: { policy: string; limit: number; windowSeconds: number; store?: GuardStore }): MiddlewareHandler =>
+  async (c, next) => {
+    const now = Date.now()
+    const window = await store.count(`${policy} ${callerOf(c)}`, windowSeconds * 1000, now)
+    const reset = Math.max(1, Math.ceil((window.start + windowSeconds * 1000 - now) / 1000))
+    const headers = { 'ratelimit-policy': `"${policy}";q=${limit};w=${windowSeconds}`, ratelimit: `"${policy}";r=${Math.max(0, limit - window.used)};t=${reset}` }
+    if (window.used > limit) return problemResponse(c, 'too_many_requests', { detail: `More than ${limit} calls to ${policy} routes in ${windowSeconds / 60} minutes. Try again in ${reset} seconds; answers already computed are cached, so repeating one is not needed.`, headers: { ...headers, 'retry-after': String(reset) } })
+    await next()
+    for (const [name, value] of Object.entries(headers)) c.res.headers.set(name, value)
+  }

package/src/core/hal.ts

@@ -0,0 +1,63 @@
+/**
+ * HAL hypermedia (`application/hal+json`): every resource carries `_links` with absolute `href`s and, when the caller
+ * asked for neighbours, `_embedded`. An agent chains calls by following links instead of building URLs, so a route can
+ * move without breaking anyone who started from `/api`.
+ *
+ * @example
+ * const origin = originOf(c)
+ * linksOf(origin, { self: '/api/v1/cooks/123', recipes: { path: '/api/v1/cooks/123/recipes', title: 'Its 12 recipes' } })
+ * // { self: { href: 'https://cookbook.example.com/api/v1/cooks/123' }, recipes: { href: '…/recipes', title: 'Its 12 recipes' } }
+ * pathWith('/api/v1/search/recipes', { q: 'soup', platform: undefined }) // '/api/v1/search/recipes?q=soup'
+ */
+import { z } from '@hono/zod-openapi'
+import type { Context } from 'hono'
+
+export const HAL_JSON = 'application/hal+json'
+
+export type Link = { href: string; title?: string; templated?: boolean; type?: string }
+export type Links = Record<string, Link>
+export type LinkTarget = string | { path: string; title?: string; templated?: boolean; type?: string } | null | undefined
+
+// Behind Traefik and Cloudflare the socket is plain http: trust the forwarded proto and host for absolute URLs
+export const originOf = (c: Context) => {
+  const url = new URL(c.req.url)
+  const proto = c.req.header('x-forwarded-proto')?.split(',')[0]?.trim()
+  return `${proto ?? url.protocol.replace(':', '')}://${c.req.header('x-forwarded-host') ?? url.host}`
+}
+
+/** A path with its query, leaving out empty values; arrays repeat the key (`platform=ios&platform=web`). */
+export const pathWith = (path: string, query: Record<string, string | number | boolean | string[] | null | undefined> = {}) => {
+  const params = new URLSearchParams()
+  for (const [key, value] of Object.entries(query)) {
+    if (value === undefined || value === null || value === '') continue
+    for (const one of Array.isArray(value) ? value : [value]) params.append(key, String(one))
+  }
+  const search = params.toString()
+  return search ? `${path}?${search}` : path
+}
+
+/** Relative paths → absolute links; `null` and `undefined` targets are left out, so optional links just disappear. */
+export const linksOf = (origin: string, targets: Record<string, LinkTarget>): Links =>
+  Object.fromEntries(
+    Object.entries(targets)
+      .filter((entry): entry is [string, Exclude<LinkTarget, null | undefined>] => entry[1] != null)
+      .map(([rel, target]) => {
+        if (typeof target === 'string') return [rel, { href: origin + target }]
+        const { path, ...rest } = target
+        return [rel, { href: origin + path, ...Object.fromEntries(Object.entries(rest).filter(([, value]) => value !== undefined)) }]
+      }),
+  )
+
+export const LinkSchema = z
+  .object({
+    href: z.string().url().openapi({ description: 'Absolute URL to follow.', example: 'https://api.example.com/api/v1/cooks/123' }),
+    title: z.string().optional().openapi({ description: 'What is at the other end, in a few words.' }),
+    templated: z.boolean().optional().openapi({ description: 'True when `href` is a URI template (RFC 6570) to fill in first.' }),
+    type: z.string().optional().openapi({ description: 'Media type of the target when it is not HAL JSON (an image, Markdown).' }),
+  })
+  .openapi('Link', { description: 'A HAL link.' })
+
+export const LinksSchema = z.record(z.string(), LinkSchema).openapi('Links', {
+  description: 'HAL `_links`: relation name → link. `self` is always present; follow links instead of building URLs.',
+  example: { self: { href: 'https://api.example.com/api/v1/cooks/123' } },
+})

package/src/core/kv.ts

@@ -0,0 +1,29 @@
+/**
+ * A key-value store with expiry: what the OAuth server keeps (codes, tokens, registrations) and A2A's tasks. Values
+ * are small JSON objects under a `kind` and an id; `expiresAt` is epoch seconds, and an expired value reads as null.
+ * `memoryStore` is for tests and single-process scripts; `dbOAuthStore(db)` (`oauth`) keeps them in the app's database.
+ *
+ * @example
+ * const store = memoryStore()
+ * await store.put('a2a-task', id, task, Math.floor(Date.now() / 1000) + 86_400)
+ */
+export type KeyValueStore = {
+  get: (kind: string, id: string) => Promise<Record<string, unknown> | null>
+  put: (kind: string, id: string, value: Record<string, unknown>, expiresAt: number) => Promise<void>
+  delete: (kind: string, id: string) => Promise<void>
+}
+
+const now = () => Math.floor(Date.now() / 1000)
+
+/** A store in memory. */
+export const memoryStore = (): KeyValueStore => {
+  const rows = new Map<string, { value: Record<string, unknown>; expiresAt: number }>()
+  return {
+    get: async (kind, id) => {
+      const row = rows.get(`${kind}:${id}`)
+      return row && row.expiresAt > now() ? row.value : null
+    },
+    put: async (kind, id, value, expiresAt) => void rows.set(`${kind}:${id}`, { value, expiresAt }),
+    delete: async (kind, id) => void rows.delete(`${kind}:${id}`),
+  }
+}

package/src/core/problem.ts

@@ -0,0 +1,124 @@
+/**
+ * Errors as RFC 9457 problem details (`application/problem+json`). Every error has a stable machine `code` (also the
+ * last segment of its `type` URI, which the API serves as a page), a human `title`, the HTTP `status`, and a `detail`
+ * that says what to do next. Validation errors list each bad field in `errors`.
+ *
+ * @example
+ * throw new ProblemError(404, 'not_found', { detail: 'No item 42. Search with GET /api/v1/search/recipes.' })
+ * createRoute({ …, responses: { 200: …, ...problemResponses(400, 404) } })
+ */
+import { z } from '@hono/zod-openapi'
+import type { Context } from 'hono'
+import { HTTPException } from 'hono/http-exception'
+import type { ContentfulStatusCode } from 'hono/utils/http-status'
+import { originOf } from './hal.js'
+
+export const PROBLEM_JSON = 'application/problem+json'
+
+/** Every problem the API returns, with the status it comes with and what it means. */
+export const PROBLEMS = {
+  bad_request: { status: 400, title: 'Bad request', description: 'A parameter or the body is invalid. `errors` lists each one with its path; fix them and retry.' },
+  unauthorized: { status: 401, title: 'Unauthorized', description: 'No valid API key. Send `Authorization: Bearer <key>`; keys are issued per client.' },
+  forbidden: { status: 403, title: 'Forbidden', description: 'The key is valid but may not do this.' },
+  not_found: { status: 404, title: 'Not found', description: 'Nothing at this path or with this id in the current snapshot. Find ids through search or a list, then follow `_links`.' },
+  method_not_allowed: { status: 405, title: 'Method not allowed', description: 'This path exists but not with this method.' },
+  conflict: { status: 409, title: 'Conflict', description: 'The change clashes with the current state (a name already taken, a stale If-Match).' },
+  gone: { status: 410, title: 'Gone', description: 'This existed in an earlier snapshot and was removed.' },
+  payload_too_large: { status: 413, title: 'Payload too large', description: 'The body is over the limit given in `detail`.' },
+  unsupported_media_type: { status: 415, title: 'Unsupported media type', description: 'Send the content type the operation lists.' },
+  unprocessable: { status: 422, title: 'Unprocessable', description: 'The request is well formed but can\'t be applied as sent, e.g. an Idempotency-Key reused with a different body.' },
+  too_many_requests: { status: 429, title: 'Too many requests', description: 'Slow down: wait the seconds in `Retry-After`, then retry.' },
+  spend_cap: { status: 429, title: 'Spend cap reached', description: 'This operation costs money and its budget is used up. Free operations still work.' },
+  internal: { status: 500, title: 'Internal error', description: 'A bug on our side. Retrying the same request rarely helps; report the `instance`.' },
+  upstream: { status: 503, title: 'Upstream failed', description: 'A service this call depends on (a model, storage) failed. Retry after `Retry-After` seconds.' },
+  unavailable: { status: 503, title: 'Unavailable', description: 'The data is still loading or being replaced. Retry after `Retry-After` seconds.' },
+} as const satisfies Record<string, { status: number; title: string; description: string }>
+
+export type ProblemCode = keyof typeof PROBLEMS
+
+export const ProblemSchema = z
+  .object({
+    type: z.string().url().openapi({ description: 'URI of the problem type; its last segment is `code`, and it opens a page describing it.', example: 'https://api.example.com/problems/not_found' }),
+    code: z.enum(Object.keys(PROBLEMS) as [ProblemCode, ...ProblemCode[]]).openapi({ description: 'Stable machine-readable code. Branch on this, not on `title`.' }),
+    title: z.string().openapi({ description: 'Short, human summary of the problem type.', example: 'Not found' }),
+    status: z.number().int().openapi({ description: 'The HTTP status, repeated for convenience.', example: 404 }),
+    detail: z.string().optional().openapi({ description: 'What went wrong this time and what to do next.', example: 'No item 42.' }),
+    instance: z.string().optional().openapi({ description: 'The request id; quote it when reporting a bug.', example: 'req_01J…' }),
+    errors: z
+      .array(z.object({ in: z.enum(['path', 'query', 'header', 'body']).optional(), path: z.string(), message: z.string() }))
+      .optional()
+      .openapi({ description: 'For `bad_request`: every invalid field, where it is (`in`) and why.' }),
+  })
+  .catchall(z.unknown())
+  .openapi('Problem', { description: 'An error, as RFC 9457 problem details (`application/problem+json`).' })
+
+export type Problem = z.infer<typeof ProblemSchema>
+
+export class ProblemError extends Error {
+  constructor(
+    readonly code: ProblemCode,
+    readonly options: { detail?: string; errors?: Problem['errors']; headers?: Record<string, string>; extensions?: Record<string, unknown> } = {},
+  ) {
+    super(options.detail ?? PROBLEMS[code].title)
+  }
+}
+
+export const problemBody = (c: Context, code: ProblemCode, options: ProblemError['options'] = {}): Problem => ({
+  type: `${originOf(c)}/problems/${code}`,
+  code,
+  title: PROBLEMS[code].title,
+  status: PROBLEMS[code].status,
+  ...(options.detail ? { detail: options.detail } : {}),
+  ...(c.get('requestId' as never) ? { instance: c.get('requestId' as never) as string } : {}),
+  ...(options.errors ? { errors: options.errors } : {}),
+  ...options.extensions,
+})
+
+/** Seconds an `upstream` problem asks the client to wait unless the code passes its own `retry-after`. */
+export const UPSTREAM_RETRY_AFTER = 30
+
+export const problemResponse = (c: Context, code: ProblemCode, options: ProblemError['options'] = {}) =>
+  c.body(JSON.stringify(problemBody(c, code, options)), PROBLEMS[code].status as ContentfulStatusCode, {
+    'content-type': PROBLEM_JSON,
+    // 503, never 502: Cloudflare replaces a 502's body with its own page, and the problem is lost
+    ...(code === 'upstream' ? { 'retry-after': String(UPSTREAM_RETRY_AFTER) } : {}),
+    ...options.headers,
+  })
+
+/** Response entries for `createRoute`: `...problemResponses(400, 404)` documents those errors as problem+json. */
+export const problemResponses = (...statuses: number[]) =>
+  Object.fromEntries(
+    statuses.map((status) => {
+      const codes = Object.entries(PROBLEMS).filter(([, problem]) => problem.status === status)
+      return [status, { description: codes.map(([code, problem]) => `\`${code}\`: ${problem.description}`).join(' '), content: { [PROBLEM_JSON]: { schema: ProblemSchema } } }]
+    }),
+  )
+
+type Issue = { path: PropertyKey[]; message: string }
+
+/** `defaultHook` for OpenAPIHono: a failed zod validation becomes a 400 problem listing every bad field. */
+export const validationHook = (result: { success: boolean; target?: string; error?: { issues: Issue[] } }, c: Context) => {
+  if (result.success) return
+  const where = ({ param: 'path', query: 'query', header: 'header', json: 'body', form: 'body' } as const)[result.target as 'param'] ?? undefined
+  const errors = (result.error?.issues ?? []).map((issue) => ({ ...(where ? { in: where } : {}), path: issue.path.map(String).join('.') || '(root)', message: issue.message }))
+  return problemResponse(c, 'bad_request', { detail: `${errors.length} invalid ${errors.length === 1 ? 'field' : 'fields'}: ${errors.map((error) => error.path).join(', ')}.`, errors })
+}
+
+/** `app.onError`: problems as themselves, Hono's HTTP errors by status, anything else as a logged 500. */
+export const errorHandler = (error: Error, c: Context) => {
+  if (error instanceof ProblemError) return problemResponse(c, error.code, error.options)
+  if (error instanceof HTTPException) {
+    // A bare 503 says the service can't answer now, not that something behind it failed: `upstream` is only ever named
+    const code = (error.status === 503 ? 'unavailable' : (Object.entries(PROBLEMS).find(([, problem]) => problem.status === error.status)?.[0] ?? 'internal')) as ProblemCode
+    return problemResponse(c, code, { detail: error.message })
+  }
+  console.error(`${c.req.method} ${c.req.path}`, error)
+  return problemResponse(c, 'internal')
+}
+
+/** A wrong path says how to find the right one: a trailing slash dropped, the root, the spec. */
+export const notFoundHandler = (c: Context) => {
+  const path = c.req.path
+  const hint = path.length > 1 && path.endsWith('/') ? ` Drop the trailing slash: ${path.slice(0, -1)}.` : ''
+  return problemResponse(c, 'not_found', { detail: `No route ${c.req.method} ${path}.${hint} Start from GET /api and follow _links, look the operation up in GET /openapi.json, or read /llms.txt.` })
+}