@huynle/hub 0.9.2 → 0.10.0

package/src/central/agent/connect.ts

@@ -0,0 +1,868 @@
+// Connect an app (AF1, docs/plans/2026-11-08-app-front-contracts.md §3; decisions w6lfbfaq, zn7oxf4g, nixct956): an
+// OAuth 2.1-style authorization code + PKCE flow for registered, confidential app clients.
+//
+// - Clients live on the registering user's agent data (`appClients`, the secret's sha256 only): audience "hub"
+//   (an admin's, every user may connect) or "user" (personal: only its owner sees and uses it). IDs are hub-unique.
+// - GET /connect/authorize opens a pending flow (hcf_, 10 min) in the shared Kv, then the consent page approves or
+//   denies it as the signed-in user (cookie only); approve mints a one-time code (hco_, 60 s, stored by hash).
+// - POST /connect/token (form-encoded, client_secret_basic|post + PKCE S256) turns a code into a connection on the
+//   user's agent data (`connections`, hashes only) with an access token (hca_<connection>_, 1 h) and a rotating
+//   refresh token (hcr_<connection>_, 30 days sliding). The just-rotated refresh token answers the same new pair for
+//   30 s (sealed with a key derived from it, never stored in clear); any other reuse revokes the connection, as does
+//   a second use of a code.
+// - POST /connect/revoke (RFC 7009) ends the connection; so does the user (Settings) or a client change. Ending one
+//   calls `ended` (the hub deletes the app's grants and webhooks).
+// - The access-token verifier resolves to the app actor whose tokenID is the connection ID (stable across refresh).
+// Codes, flows, secrets and tokens are never logged or audited; only IDs and scope names are.
+import { createCipheriv, createDecipheriv, createHash, randomBytes, timingSafeEqual } from "node:crypto"
+import {
+  ACCESS_TOKEN_TTL_MS,
+  AUTHORIZATION_CODE_TTL_MS,
+  CLIENT_AUDIENCES,
+  type ClientAudience,
+  CONNECT_FLOW_TTL_MS,
+  CONNECT_LIMITS,
+  CONNECT_PATHS,
+  CONNECT_TOKEN_PATTERNS,
+  parseConnectToken,
+  parseScopeParam,
+  pkceChallengeProblem,
+  pkceVerifierProblem,
+  REFRESH_GRACE_MS,
+  REFRESH_TOKEN_IDLE_MS,
+  redirectUriMatches,
+  redirectUriProblem,
+  TOKEN_ERROR_STATUS,
+  type TokenError,
+} from "../../protocol"
+import type { AppClientRecord, ConnectionRecord } from "../agent-data"
+import type { Counters, Kv } from "../backend/types"
+import { hashToken, type Store, type UserRecord } from "../store"
+import type { AppActor, BearerVerifier, VerifyResult } from "./actor"
+import { boundedText } from "./body"
+import { AgentError } from "./errors"
+
+/** Longest form body the token and revoke endpoints read. */
+const FORM_MAX = 16 * 1024
+/** How long a spent code remembers the connection it issued (a second use revokes it). */
+const CODE_USED_TTL_MS = 10 * 60_000
+const RATE_WINDOW_MS = 60_000
+const NO_STORE = { "cache-control": "no-store" }
+
+const KEYS = {
+  flow: (id: string) => `connect:flow:${id}`,
+  code: (hash: string) => `connect:code:${hash}`,
+  codeUsed: (hash: string) => `connect:code-used:${hash}`,
+  authorizeRate: (clientID: string, address: string) => `connect:authorize-rate:${clientID}:${address}`,
+  tokenRate: (clientID: string) => `connect:token-rate:${clientID}`,
+  authFailures: (clientID: string, address: string) => `connect:auth-failures:${clientID}:${address}`,
+}
+
+interface Flow {
+  readonly id: string
+  readonly clientID: string
+  readonly redirectURI: string
+  readonly scopes: readonly string[]
+  readonly state: string
+  readonly challenge: string
+  readonly created: number
+  readonly expiresAt: number
+}
+
+interface Code {
+  readonly clientID: string
+  readonly redirectURI: string
+  readonly challenge: string
+  readonly userID: string
+  readonly scopes: readonly string[]
+  readonly expiresAt: number
+}
+
+/** A client as Settings shows it (never the secret or its hash). */
+export interface AppClientView {
+  readonly id: string
+  readonly name: string
+  readonly redirectURIs: readonly string[]
+  readonly scopes: readonly string[]
+  readonly created: number
+  readonly createdBy: string
+  readonly audience: ClientAudience
+  readonly disabled?: true
+}
+
+export interface ConnectionView {
+  readonly id: string
+  readonly clientID: string
+  readonly clientName: string
+  readonly scopes: readonly string[]
+  readonly created: number
+  readonly lastUsed?: number
+  readonly refreshExpiresAt: number
+}
+
+export interface ConnectFlowView {
+  readonly id: string
+  readonly client: { readonly id: string; readonly name: string; readonly redirectOrigin: string }
+  readonly scopes: readonly string[]
+  readonly expiresAt: number
+  readonly connection?: { readonly id: string; readonly scopes: readonly string[] }
+}
+
+export interface AppConnectDeps {
+  readonly store: Store
+  readonly kv: Kv
+  readonly counters: Counters
+  /** The hub's public URL: the issuer. */
+  publicURL(): string
+  /** What a client may ask for (APP_SCOPES). */
+  readonly scopes: readonly string[]
+  readonly now?: () => number
+  /** A connection ended (revoked, reused, lapsed, its client changed): the hub deletes its grants and webhooks. */
+  ended?(userID: string, connectionID: string): Promise<void>
+}
+
+interface Found {
+  readonly owner: UserRecord
+  readonly record: AppClientRecord
+}
+
+/** The answer of the token endpoint (RFC 6749 §5.1). */
+interface TokenBody {
+  readonly access_token: string
+  readonly token_type: "Bearer"
+  readonly expires_in: number
+  readonly refresh_token: string
+  readonly scope: string
+  readonly connection_id: string
+}
+
+class OAuthError extends Error {
+  constructor(
+    readonly error: TokenError,
+    message: string,
+    readonly headers: Record<string, string> = {},
+  ) {
+    super(message)
+  }
+}
+
+const sha256 = (value: string) => createHash("sha256").update(value).digest()
+/** Constant-time comparison of two hex digests. */
+function sameHash(a: string | undefined, b: string): boolean {
+  if (!a) return false
+  const x = Buffer.from(a, "hex")
+  const y = Buffer.from(b, "hex")
+  return x.length === y.length && x.length > 0 && timingSafeEqual(x, y)
+}
+const secret = () => randomBytes(32).toString("base64url")
+const strings = (value: unknown): string[] => (Array.isArray(value) ? value.filter((s): s is string => typeof s === "string") : [])
+const audienceOf = (record: AppClientRecord): ClientAudience => (record.audience === "user" ? "user" : "hub")
+const isObject = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v)
+
+/** The new pair, sealed for the refresh grace with a key only the presenter of the old refresh token can derive. */
+function seal(body: TokenBody, oldRefresh: string): string {
+  const iv = randomBytes(12)
+  const cipher = createCipheriv("aes-256-gcm", sha256(`hub-connect-grace\n${oldRefresh}`), iv)
+  const data = Buffer.concat([cipher.update(JSON.stringify(body), "utf8"), cipher.final()])
+  return Buffer.concat([iv, cipher.getAuthTag(), data]).toString("base64url")
+}
+
+function unseal(sealed: string, oldRefresh: string): TokenBody | undefined {
+  try {
+    const raw = Buffer.from(sealed, "base64url")
+    const decipher = createDecipheriv("aes-256-gcm", sha256(`hub-connect-grace\n${oldRefresh}`), raw.subarray(0, 12))
+    decipher.setAuthTag(raw.subarray(12, 28))
+    return JSON.parse(Buffer.concat([decipher.update(raw.subarray(28)), decipher.final()]).toString("utf8")) as TokenBody
+  } catch {
+    return undefined
+  }
+}
+
+const escapeHTML = (text: string) => text.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`)
+
+/** The authorize endpoint's error page (never a redirect: no open redirector); it cannot be framed. */
+function errorPage(message: string): Response {
+  const html = `<!doctype html><html lang="en"><meta charset="utf-8"><meta name="viewport" content="width=device-width"><title>Cannot connect</title><h1>Cannot connect this app</h1><p>${escapeHTML(message)}</p><p>Start again from the app, or ask whoever runs it to check its Hub registration.</p></html>`
+  return new Response(html, {
+    status: 400,
+    headers: { "content-type": "text/html; charset=utf-8", "content-security-policy": "default-src 'none'; frame-ancestors 'none'", "x-frame-options": "DENY", ...NO_STORE },
+  })
+}
+
+function oauthResponse(cause: OAuthError): Response {
+  return Response.json({ error: cause.error, error_description: cause.message.slice(0, 200) }, { status: TOKEN_ERROR_STATUS[cause.error], headers: { ...NO_STORE, pragma: "no-cache", ...cause.headers } })
+}
+
+export class AppConnect {
+  private readonly now: () => number
+
+  constructor(private readonly deps: AppConnectDeps) {
+    this.now = deps.now ?? Date.now
+  }
+
+  // ---------- metadata ----------
+
+  /** RFC 8414 authorization server metadata. */
+  metadata(): Response {
+    const issuer = this.deps.publicURL()
+    return Response.json(
+      {
+        issuer,
+        authorization_endpoint: `${issuer}${CONNECT_PATHS.authorize}`,
+        token_endpoint: `${issuer}${CONNECT_PATHS.token}`,
+        revocation_endpoint: `${issuer}${CONNECT_PATHS.revoke}`,
+        response_types_supported: ["code"],
+        grant_types_supported: ["authorization_code", "refresh_token"],
+        code_challenge_methods_supported: ["S256"],
+        token_endpoint_auth_methods_supported: ["client_secret_basic", "client_secret_post"],
+        scopes_supported: [...this.deps.scopes],
+        authorization_response_iss_parameter_supported: true,
+      },
+      { headers: { "cache-control": "public, max-age=60" } },
+    )
+  }
+
+  // ---------- clients ----------
+
+  /** The client of an ID, wherever it is stored. */
+  private find(id: string): Found | undefined {
+    if (!CONNECT_TOKEN_PATTERNS.clientID.test(id)) return undefined
+    for (const owner of this.deps.store.users()) {
+      const record = owner.agent?.appClients?.find((c) => c.id === id)
+      if (record) return { owner, record }
+    }
+    return undefined
+  }
+
+  /** A client that may connect now: enabled, and a personal one's owner active. */
+  private usable(id: string): Found | undefined {
+    const found = this.find(id)
+    if (!found || found.record.disabled) return undefined
+    if (audienceOf(found.record) === "user" && found.owner.disabled) return undefined
+    return found
+  }
+
+  /** Whether `user` may see (and connect to) the client: hub-wide ones, and their own personal ones. */
+  private visible(found: Found, userID: string): boolean {
+    return audienceOf(found.record) === "hub" || found.owner.id === userID
+  }
+
+  private allClients(): Found[] {
+    return this.deps.store.users().flatMap((owner) => (owner.agent?.appClients ?? []).map((record) => ({ owner, record })))
+  }
+
+  private clientView({ owner, record }: Found): AppClientView {
+    return {
+      id: record.id,
+      name: typeof record.name === "string" ? record.name : record.id,
+      redirectURIs: strings(record.redirectURIs),
+      scopes: strings(record.scopes),
+      created: typeof record.created === "number" ? record.created : 0,
+      createdBy: owner.id,
+      audience: audienceOf(record),
+      ...(record.disabled ? { disabled: true as const } : {}),
+    }
+  }
+
+  /** The clients `user` sees: hub-wide ones and their own personal ones, newest first. */
+  clients(user: UserRecord): AppClientView[] {
+    return this.allClients()
+      .filter((found) => this.visible(found, user.id))
+      .map((found) => this.clientView(found))
+      .sort((a, b) => b.created - a.created || (a.id < b.id ? -1 : 1))
+  }
+
+  /** A client `user` may change: hub-wide ones for admins (forbidden for others), personal ones for their owner only. */
+  private manageable(user: UserRecord, id: string): Found {
+    const found = this.find(id)
+    if (!found || !this.visible(found, user.id)) throw new AgentError("not_found", "No such app client")
+    if (audienceOf(found.record) === "hub" && user.role !== "admin") throw new AgentError("forbidden", "Only an admin changes a hub-wide app client")
+    return found
+  }
+
+  private newID(prefix: string, taken: (id: string) => boolean): string {
+    for (;;) {
+      const id = `${prefix}${randomBytes(8).toString("hex")}`
+      if (!taken(id)) return id
+    }
+  }
+
+  async register(user: UserRecord, body: unknown): Promise<{ client: AppClientView; secret: string }> {
+    const input = this.clientInput(body, false)
+    const audience = input.audience ?? (user.role === "admin" ? "hub" : "user")
+    if (audience === "hub" && user.role !== "admin") throw new AgentError("forbidden", "Only an admin registers a hub-wide app client", { hint: 'Register it for your own account (audience "user")' })
+    if (audience === "hub" && this.allClients().filter((c) => audienceOf(c.record) === "hub").length >= CONNECT_LIMITS.clients) {
+      throw new AgentError("rate_limited", `At most ${CONNECT_LIMITS.clients} hub-wide app clients`, { hint: "Delete unused clients" })
+    }
+    if (audience === "user" && (user.agent?.appClients ?? this.deps.store.agentData(user.id).appClients ?? []).filter((c) => audienceOf(c) === "user").length >= CONNECT_LIMITS.personalClientsPerUser) {
+      throw new AgentError("rate_limited", `At most ${CONNECT_LIMITS.personalClientsPerUser} personal app clients per user`, { hint: "Delete unused clients" })
+    }
+    const id = this.newID("hcl_", (candidate) => this.find(candidate) !== undefined)
+    const plain = `hcs_${secret()}`
+    const record: AppClientRecord = { id, secretHash: hashToken(plain), name: input.name!, redirectURIs: [...input.redirectURIs!], scopes: [...input.scopes!], audience, created: this.now() }
+    await this.deps.store.updateAgentData(user.id, (data) => {
+      data.appClients = [...(data.appClients ?? []).filter((c) => c.id !== id), record]
+    })
+    await this.deps.store.audit({ actor: user.id, action: "app-client.create", target: id, detail: audience })
+    return { client: this.clientView({ owner: this.deps.store.user(user.id) ?? user, record }), secret: plain }
+  }
+
+  async update(user: UserRecord, id: string, body: unknown): Promise<AppClientView> {
+    const found = this.manageable(user, id)
+    const input = this.clientInput(body, true)
+    let next: AppClientRecord | undefined
+    await this.deps.store.updateAgentData(found.owner.id, (data) => {
+      next = undefined
+      data.appClients = (data.appClients ?? []).map((c) => {
+        if (c.id !== id) return c
+        const { disabled: _drop, ...rest } = c
+        next = {
+          ...rest,
+          ...(input.name !== undefined ? { name: input.name } : {}),
+          ...(input.redirectURIs ? { redirectURIs: [...input.redirectURIs] } : {}),
+          ...(input.scopes ? { scopes: [...input.scopes] } : {}),
+          ...((input.disabled ?? c.disabled === true) ? { disabled: true as const } : {}),
+          updated: this.now(),
+        }
+        return next
+      })
+    })
+    if (!next) throw new AgentError("not_found", "No such app client")
+    await this.deps.store.audit({ actor: user.id, action: "app-client.update", target: id, ...(input.disabled !== undefined ? { detail: input.disabled ? "disabled" : "enabled" } : {}) })
+    if (next.disabled) await this.endClient(id, user.id, "client disabled")
+    else if (input.scopes) await this.narrowClient(id, input.scopes, user.id)
+    return this.clientView({ owner: found.owner, record: next })
+  }
+
+  async rotate(user: UserRecord, id: string): Promise<{ client: AppClientView; secret: string }> {
+    const found = this.manageable(user, id)
+    const plain = `hcs_${secret()}`
+    let next: AppClientRecord | undefined
+    await this.deps.store.updateAgentData(found.owner.id, (data) => {
+      next = undefined
+      data.appClients = (data.appClients ?? []).map((c) => (c.id === id ? (next = { ...c, secretHash: hashToken(plain), updated: this.now() }) : c))
+    })
+    if (!next) throw new AgentError("not_found", "No such app client")
+    await this.deps.store.audit({ actor: user.id, action: "app-client.secret", target: id })
+    return { client: this.clientView({ owner: found.owner, record: next }), secret: plain }
+  }
+
+  async remove(user: UserRecord, id: string): Promise<void> {
+    const found = this.manageable(user, id)
+    let removed = false
+    await this.deps.store.updateAgentData(found.owner.id, (data) => {
+      const before = data.appClients ?? []
+      removed = before.some((c) => c.id === id)
+      data.appClients = before.filter((c) => c.id !== id)
+    })
+    if (!removed) throw new AgentError("not_found", "No such app client")
+    await this.deps.store.audit({ actor: user.id, action: "app-client.delete", target: id })
+    await this.endClient(id, user.id, "client deleted")
+  }
+
+  /** Register/PATCH bodies: name 1–100, redirect URIs (redirectUriProblem), known scopes, audience; PATCH also disabled. */
+  private clientInput(body: unknown, partial: boolean): { name?: string; redirectURIs?: string[]; scopes?: string[]; audience?: ClientAudience; disabled?: boolean } {
+    if (!isObject(body)) throw new AgentError("invalid", "Body must be a JSON object")
+    const allowed = partial ? ["name", "redirectURIs", "scopes", "disabled"] : ["name", "redirectURIs", "scopes", "audience"]
+    const extra = Object.keys(body).find((key) => !allowed.includes(key))
+    if (extra !== undefined) throw new AgentError("invalid", `Unknown field: ${extra.slice(0, 40)}`)
+    if (partial && Object.keys(body).length === 0) throw new AgentError("invalid", "Nothing to change")
+    const out: { name?: string; redirectURIs?: string[]; scopes?: string[]; audience?: ClientAudience; disabled?: boolean } = {}
+    if (body.name !== undefined || !partial) {
+      const name = typeof body.name === "string" ? body.name.trim().replace(/\s+/g, " ") : ""
+      if (!name || name.length > CONNECT_LIMITS.clientNameMax) throw new AgentError("invalid", `name is 1–${CONNECT_LIMITS.clientNameMax} characters`)
+      out.name = name
+    }
+    if (body.redirectURIs !== undefined || !partial) {
+      const uris = body.redirectURIs
+      if (!Array.isArray(uris) || uris.length === 0 || uris.length > CONNECT_LIMITS.redirectURIsPerClient) throw new AgentError("invalid", `redirectURIs lists 1–${CONNECT_LIMITS.redirectURIsPerClient} URIs`)
+      for (const uri of uris) {
+        const problem = redirectUriProblem(uri)
+        if (problem) throw new AgentError("invalid", `redirectURIs: ${problem}`)
+      }
+      out.redirectURIs = [...new Set(uris as string[])]
+    }
+    if (body.scopes !== undefined || !partial) {
+      const scopes = body.scopes
+      if (!Array.isArray(scopes) || scopes.length === 0 || !scopes.every((s): s is string => typeof s === "string")) throw new AgentError("invalid", "scopes lists at least one scope")
+      const unknown = scopes.find((s) => !this.deps.scopes.includes(s))
+      if (unknown !== undefined) throw new AgentError("invalid", `Unknown scope: ${unknown.slice(0, 64)}`, { extra: { scopes: this.deps.scopes } })
+      out.scopes = [...new Set(scopes)]
+    }
+    if (body.audience !== undefined) {
+      if (!CLIENT_AUDIENCES.includes(body.audience as ClientAudience)) throw new AgentError("invalid", 'audience is "hub" or "user"')
+      out.audience = body.audience as ClientAudience
+    }
+    if (body.disabled !== undefined) {
+      if (typeof body.disabled !== "boolean") throw new AgentError("invalid", "disabled is true or false")
+      out.disabled = body.disabled
+    }
+    return out
+  }
+
+  // ---------- connections ----------
+
+  /** The connection of an ID and its user, wherever it is stored. */
+  private connectionOf(id: string): { user: UserRecord; connection: ConnectionRecord } | undefined {
+    for (const user of this.deps.store.users()) {
+      const connection = user.agent?.connections?.find((c) => c.id === id)
+      if (connection) return { user, connection }
+    }
+    return undefined
+  }
+
+  /** Whether the user's connection exists now (grants and webhooks of app:<id>). Synchronous: the Store's cache. */
+  alive(userID: string, id: string): boolean {
+    return (this.deps.store.agentData(userID).connections ?? []).some((c) => c.id === id)
+  }
+
+  /** The scopes a connection has now (its own, within its client's ceiling). */
+  scopesOf(userID: string, id: string): string[] | undefined {
+    const connection = (this.deps.store.agentData(userID).connections ?? []).find((c) => c.id === id)
+    if (!connection) return undefined
+    const ceiling = strings(this.find(connection.clientID)?.record.scopes)
+    return strings(connection.scopes).filter((s) => ceiling.includes(s))
+  }
+
+  /** The user's connections (lapsed ones left out), newest first. */
+  connections(userID: string): ConnectionView[] {
+    const at = this.now()
+    return (this.deps.store.agentData(userID).connections ?? [])
+      .filter((c) => (c.refreshExpiresAt ?? 0) >= at)
+      .map((c) => {
+        const client = this.find(c.clientID)
+        return {
+          id: c.id,
+          clientID: c.clientID,
+          clientName: typeof client?.record.name === "string" ? client.record.name : c.clientID,
+          scopes: this.scopesOf(userID, c.id) ?? [],
+          created: c.created ?? 0,
+          ...(typeof c.lastUsed === "number" ? { lastUsed: c.lastUsed } : {}),
+          refreshExpiresAt: c.refreshExpiresAt ?? 0,
+        }
+      })
+      .sort((a, b) => b.created - a.created || (a.id < b.id ? -1 : 1))
+  }
+
+  /**
+   * Ends a connection (both tokens at once) and tells the hub (grants, webhooks); false when it did not exist.
+   * `by` is the audit actor; `action` connect.revoke or connect.reuse.
+   */
+  async end(userID: string, id: string, options: { readonly by: string; readonly why: string; readonly action?: "connect.revoke" | "connect.reuse" }): Promise<boolean> {
+    let removed = false
+    await this.deps.store.updateAgentData(userID, (data) => {
+      const before = data.connections ?? []
+      removed = before.some((c) => c.id === id)
+      if (removed) data.connections = before.filter((c) => c.id !== id)
+    })
+    if (!removed) return false
+    await this.deps.store.audit({ actor: options.by, action: options.action ?? "connect.revoke", target: id, detail: options.why })
+    try {
+      await this.deps.ended?.(userID, id)
+    } catch (cause) {
+      console.error(`[hub] cleaning up connection ${id} failed: ${(cause as Error).message}`)
+    }
+    return true
+  }
+
+  private async endClient(clientID: string, by: string, why: string): Promise<void> {
+    for (const user of this.deps.store.users()) {
+      for (const c of user.agent?.connections ?? []) if (c.clientID === clientID) await this.end(user.id, c.id, { by, why })
+    }
+  }
+
+  /** A client's ceiling narrowed: every connection keeps only what is still allowed (none left: it ends). */
+  private async narrowClient(clientID: string, ceiling: readonly string[], by: string): Promise<void> {
+    for (const user of this.deps.store.users()) {
+      for (const c of user.agent?.connections ?? []) {
+        if (c.clientID !== clientID) continue
+        const kept = strings(c.scopes).filter((s) => ceiling.includes(s))
+        if (!kept.length) await this.end(user.id, c.id, { by, why: "client scopes" })
+        else await this.deps.store.updateAgentData(user.id, (data) => void (data.connections = (data.connections ?? []).map((x) => (x.id === c.id ? { ...x, scopes: kept } : x))))
+      }
+    }
+  }
+
+  // ---------- authorize and consent ----------
+
+  /** GET /connect/authorize: a flow and a redirect to the consent page, an error redirect, or an error page. */
+  async authorize(url: URL, address = "unknown"): Promise<Response> {
+    const q = url.searchParams
+    const one = (key: string): string | undefined => (q.getAll(key).length === 1 ? q.get(key)! : undefined)
+    const clientID = one("client_id") ?? ""
+    const redirectURI = one("redirect_uri")
+    const found = this.usable(clientID)
+    if (!found) return errorPage("This app is not registered with this hub, or it is disabled.")
+    if (!redirectUriMatches(strings(found.record.redirectURIs), redirectURI)) return errorPage("The app asked to come back to an address it did not register.")
+    const rawState = one("state")
+    const state = rawState && rawState.length <= CONNECT_LIMITS.stateMax ? rawState : undefined
+    const back = (error: string, description: string) => {
+      const target = new URL(redirectURI!)
+      target.searchParams.set("error", error)
+      target.searchParams.set("error_description", description.slice(0, 200))
+      if (state !== undefined) target.searchParams.set("state", state)
+      target.searchParams.set("iss", this.deps.publicURL())
+      return new Response(null, { status: 302, headers: { location: target.toString(), ...NO_STORE } })
+    }
+    if (one("response_type") !== "code") return back("unsupported_response_type", "response_type must be code")
+    if (state === undefined) return back("invalid_request", `state is required (1–${CONNECT_LIMITS.stateMax} characters)`)
+    const challenge = one("code_challenge")
+    const pkce = pkceChallengeProblem(challenge, one("code_challenge_method"))
+    if (pkce) return back("invalid_request", pkce)
+    const parsed = parseScopeParam(one("scope"), this.deps.scopes)
+    if ("problem" in parsed) return back("invalid_scope", parsed.problem)
+    const ceiling = strings(found.record.scopes)
+    const beyond = parsed.scopes.find((s) => !ceiling.includes(s))
+    if (beyond !== undefined) return back("invalid_scope", `This app may not ask for ${beyond}`)
+    if ((await this.deps.counters.incr(KEYS.authorizeRate(clientID, address), RATE_WINDOW_MS)) > CONNECT_LIMITS.authorizePerMinute) return back("temporarily_unavailable", "Too many requests; try again in a minute")
+    const created = this.now()
+    const flow: Flow = { id: `hcf_${randomBytes(12).toString("hex")}`, clientID, redirectURI: redirectURI!, scopes: parsed.scopes, state, challenge: challenge!, created, expiresAt: created + CONNECT_FLOW_TTL_MS }
+    await this.deps.kv.set(KEYS.flow(flow.id), JSON.stringify(flow), { px: CONNECT_FLOW_TTL_MS + 1 })
+    // Not audited here (anyone may call it): the user's consent or denial is.
+    return new Response(null, { status: 302, headers: { location: `/connect/consent/${flow.id}`, ...NO_STORE } })
+  }
+
+  /** The pending flow `user` may decide (personal clients: their owner only); not_found otherwise. */
+  private async flow(user: UserRecord, id: string): Promise<{ flow: Flow; found: Found }> {
+    const missing = () => new AgentError("not_found", "This request expired: start again from the app")
+    if (!CONNECT_TOKEN_PATTERNS.flow.test(id)) throw missing()
+    const raw = await this.deps.kv.get(KEYS.flow(id))
+    const flow = raw ? (JSON.parse(raw) as Flow) : undefined
+    if (!flow || flow.expiresAt < this.now()) throw missing()
+    const found = this.usable(flow.clientID)
+    if (!found || !this.visible(found, user.id)) throw missing()
+    return { flow, found }
+  }
+
+  /** GET /api/connect/flows/:flow: what the consent page shows. */
+  async flowView(user: UserRecord, id: string): Promise<ConnectFlowView> {
+    const { flow, found } = await this.flow(user, id)
+    const connection = (this.deps.store.agentData(user.id).connections ?? []).find((c) => c.clientID === flow.clientID && (c.refreshExpiresAt ?? 0) >= this.now())
+    return {
+      id: flow.id,
+      client: { id: found.record.id, name: this.clientView(found).name, redirectOrigin: new URL(flow.redirectURI).origin },
+      scopes: [...flow.scopes],
+      expiresAt: flow.expiresAt,
+      ...(connection ? { connection: { id: connection.id, scopes: this.scopesOf(user.id, connection.id) ?? [] } } : {}),
+    }
+  }
+
+  /** Approve (with the scopes the user kept: a non-empty subset of the request) or deny: where the page goes next. */
+  async decide(user: UserRecord, id: string, decision: "approve" | "deny", scopes?: unknown): Promise<{ redirect: string }> {
+    const { flow } = await this.flow(user, id)
+    let approved: string[] = []
+    if (decision === "approve") {
+      if (!Array.isArray(scopes) || !scopes.every((s): s is string => typeof s === "string") || scopes.length === 0) throw new AgentError("invalid", "Choose at least one scope")
+      const extra = scopes.find((s) => !flow.scopes.includes(s))
+      if (extra !== undefined) throw new AgentError("invalid", `The app did not ask for ${extra.slice(0, 64)}`)
+      approved = flow.scopes.filter((s) => scopes.includes(s))
+      const mine = this.deps.store.agentData(user.id).connections ?? []
+      if (!mine.some((c) => c.clientID === flow.clientID) && mine.length >= CONNECT_LIMITS.connectionsPerUser) {
+        throw new AgentError("rate_limited", `At most ${CONNECT_LIMITS.connectionsPerUser} connected apps per user`, { hint: "Revoke unused connections in Settings → Agents" })
+      }
+    }
+    // The first decision wins (GETDEL), on any pod.
+    if (!(await this.deps.kv.getdel(KEYS.flow(flow.id)))) throw new AgentError("not_found", "This request expired: start again from the app")
+    const target = new URL(flow.redirectURI)
+    if (decision === "approve") {
+      const code = `hco_${secret()}`
+      const record: Code = { clientID: flow.clientID, redirectURI: flow.redirectURI, challenge: flow.challenge, userID: user.id, scopes: approved, expiresAt: this.now() + AUTHORIZATION_CODE_TTL_MS }
+      await this.deps.kv.set(KEYS.code(hashToken(code)), JSON.stringify(record), { px: AUTHORIZATION_CODE_TTL_MS + 1 })
+      target.searchParams.set("code", code)
+      await this.deps.store.audit({ actor: user.id, action: "connect.consent", target: flow.clientID, detail: approved.join(" ") })
+    } else {
+      target.searchParams.set("error", "access_denied")
+      await this.deps.store.audit({ actor: user.id, action: "connect.deny", target: flow.clientID })
+    }
+    target.searchParams.set("state", flow.state)
+    target.searchParams.set("iss", this.deps.publicURL())
+    return { redirect: target.toString() }
+  }
+
+  // ---------- token and revoke endpoints ----------
+
+  /** The form of a token/revoke request: form-encoded only, each parameter at most once. */
+  private async form(request: Request): Promise<URLSearchParams> {
+    const type = (request.headers.get("content-type") ?? "").split(";")[0]!.trim().toLowerCase()
+    if (type !== "application/x-www-form-urlencoded") throw new OAuthError("invalid_request", "Send application/x-www-form-urlencoded")
+    let text: string
+    try {
+      text = await boundedText(request, FORM_MAX)
+    } catch {
+      throw new OAuthError("invalid_request", "The request body is too large")
+    }
+    const form = new URLSearchParams(text)
+    for (const key of new Set(form.keys())) if (form.getAll(key).length > 1) throw new OAuthError("invalid_request", `${key.slice(0, 40)} is given more than once`)
+    return form
+  }
+
+  /**
+   * client_secret_basic or client_secret_post (not both), then the secret. A failure counts against (client,
+   * address): past CONNECT_LIMITS.failedClientAuthPerMinute that address's failures answer 429, while a request with
+   * the right secret is never refused for them. Only authenticated requests count against the per-client limit.
+   */
+  private async authenticate(request: Request, form: URLSearchParams, address: string): Promise<Found> {
+    const header = request.headers.get("authorization") ?? ""
+    const basic = /^\s*Basic\s+([A-Za-z0-9+/=]+)\s*$/i.exec(header)
+    let id: string | undefined
+    let presented: string | undefined
+    if (basic) {
+      if (form.has("client_secret")) throw new OAuthError("invalid_request", "Use one client authentication method")
+      const decoded = Buffer.from(basic[1]!, "base64").toString("utf8")
+      const colon = decoded.indexOf(":")
+      try {
+        id = decodeURIComponent(decoded.slice(0, Math.max(0, colon)).replace(/\+/g, " "))
+        presented = decodeURIComponent(decoded.slice(colon + 1).replace(/\+/g, " "))
+      } catch {
+        id = undefined
+      }
+      if (form.has("client_id") && form.get("client_id") !== id) throw new OAuthError("invalid_request", "client_id does not match the authentication")
+    } else {
+      id = form.get("client_id") ?? undefined
+      presented = form.get("client_secret") ?? undefined
+    }
+    const refused = (message: string) => new OAuthError("invalid_client", message, basic ? { "www-authenticate": 'Basic realm="hub"' } : {})
+    const busy = () => new OAuthError("temporarily_unavailable", "Too many requests; try again in a minute", { "retry-after": String(RATE_WINDOW_MS / 1000) })
+    const found = id ? this.find(id) : undefined
+    if (!found || presented === undefined || !sameHash(found.record.secretHash, hashToken(presented)) || (audienceOf(found.record) === "user" && found.owner.disabled)) {
+      const key = id && CONNECT_TOKEN_PATTERNS.clientID.test(id) ? id : "other"
+      if ((await this.deps.counters.incr(KEYS.authFailures(key, address), RATE_WINDOW_MS)) > CONNECT_LIMITS.failedClientAuthPerMinute) throw busy()
+      throw refused("Client authentication failed")
+    }
+    if ((await this.deps.counters.incr(KEYS.tokenRate(found.record.id), RATE_WINDOW_MS)) > CONNECT_LIMITS.tokenPerMinute) throw busy()
+    if (found.record.disabled) throw new OAuthError("unauthorized_client", "This app client is disabled")
+    return found
+  }
+
+  /** POST /connect/token. */
+  async token(request: Request, address = "unknown"): Promise<Response> {
+    try {
+      const form = await this.form(request)
+      const grantType = form.get("grant_type")
+      if (grantType !== "authorization_code" && grantType !== "refresh_token") {
+        // Authenticate first: an unknown client learns nothing more.
+        await this.authenticate(request, form, address)
+        throw new OAuthError(grantType ? "unsupported_grant_type" : "invalid_request", grantType ? "grant_type is authorization_code or refresh_token" : "grant_type is required")
+      }
+      const client = await this.authenticate(request, form, address)
+      const body = grantType === "authorization_code" ? await this.exchange(client, form) : await this.refresh(client, form)
+      return Response.json(body, { headers: { ...NO_STORE, pragma: "no-cache" } })
+    } catch (cause) {
+      if (cause instanceof OAuthError) return oauthResponse(cause)
+      throw cause
+    }
+  }
+
+  private fresh(connectionID: string): { access: string; refresh: string } {
+    return { access: `hca_${connectionID}_${secret()}`, refresh: `hcr_${connectionID}_${secret()}` }
+  }
+
+  private body(connectionID: string, pair: { access: string; refresh: string }, scopes: readonly string[]): TokenBody {
+    return { access_token: pair.access, token_type: "Bearer", expires_in: ACCESS_TOKEN_TTL_MS / 1000, refresh_token: pair.refresh, scope: scopes.join(" "), connection_id: connectionID }
+  }
+
+  /** grant_type=authorization_code: the code (once), the redirect URI and the PKCE verifier → the user's connection. */
+  private async exchange(client: Found, form: URLSearchParams): Promise<TokenBody> {
+    const code = form.get("code")
+    const redirectURI = form.get("redirect_uri")
+    const verifier = form.get("code_verifier")
+    if (!code || !redirectURI) throw new OAuthError("invalid_request", "code and redirect_uri are required")
+    const problem = pkceVerifierProblem(verifier)
+    if (problem) throw new OAuthError("invalid_request", problem)
+    const codeHash = hashToken(code)
+    // The binding (client, redirect URI) is checked before the code is spent: another client presenting an
+    // intercepted code neither consumes nor revokes anything.
+    const peeked = await this.deps.kv.get(KEYS.code(codeHash))
+    if (peeked) {
+      const bound = JSON.parse(peeked) as Code
+      if (bound.clientID !== client.record.id) throw new OAuthError("invalid_grant", "The code was issued to another client")
+      if (bound.redirectURI !== redirectURI) throw new OAuthError("invalid_grant", "redirect_uri does not match the authorization request")
+    }
+    const raw = peeked ? await this.deps.kv.getdel(KEYS.code(codeHash)) : undefined
+    if (!raw) {
+      const used = await this.deps.kv.get(KEYS.codeUsed(codeHash))
+      const issued = used ? (JSON.parse(used) as { userID: string; connectionID: string; clientID: string }) : undefined
+      if (issued && issued.clientID === client.record.id) {
+        await this.end(issued.userID, issued.connectionID, { by: "system", why: "authorization code reused", action: "connect.reuse" })
+      }
+      throw new OAuthError("invalid_grant", "The code is unknown, expired or already used")
+    }
+    const grant = JSON.parse(raw) as Code
+    if (grant.expiresAt < this.now()) throw new OAuthError("invalid_grant", "The code expired")
+    if (grant.clientID !== client.record.id) throw new OAuthError("invalid_grant", "The code was issued to another client")
+    if (grant.redirectURI !== redirectURI) throw new OAuthError("invalid_grant", "redirect_uri does not match the authorization request")
+    const expected = Buffer.from(grant.challenge)
+    const actual = Buffer.from(createHash("sha256").update(verifier!).digest("base64url"))
+    if (expected.length !== actual.length || !timingSafeEqual(expected, actual)) throw new OAuthError("invalid_grant", "code_verifier does not match the code challenge")
+    const user = this.deps.store.user(grant.userID)
+    if (!user || user.disabled) throw new OAuthError("invalid_grant", "The user cannot connect apps now")
+    if (audienceOf(client.record) === "user" && client.owner.id !== user.id) throw new OAuthError("invalid_grant", "This client is not this user's")
+
+    const existing = (user.agent?.connections ?? []).find((c) => c.clientID === client.record.id)
+    const connectionID = existing?.id ?? this.newID("", (id) => this.taken(id))
+    await this.deps.kv.set(KEYS.codeUsed(codeHash), JSON.stringify({ userID: user.id, connectionID, clientID: client.record.id }), { px: CODE_USED_TTL_MS })
+    const pair = this.fresh(connectionID)
+    const at = this.now()
+    let full = false
+    await this.deps.store.updateAgentData(user.id, (data) => {
+      const list = data.connections ?? []
+      const current = list.find((c) => c.id === connectionID)
+      full = !current && list.length >= CONNECT_LIMITS.connectionsPerUser
+      if (full) return
+      const record: ConnectionRecord = {
+        id: connectionID,
+        clientID: client.record.id,
+        scopes: [...grant.scopes],
+        created: current?.created ?? at,
+        lastUsed: at,
+        accessHash: hashToken(pair.access),
+        accessExpiresAt: at + ACCESS_TOKEN_TTL_MS,
+        refreshHash: hashToken(pair.refresh),
+        refreshExpiresAt: at + REFRESH_TOKEN_IDLE_MS,
+      }
+      data.connections = [...list.filter((c) => c.id !== connectionID), record]
+    })
+    if (full) throw new OAuthError("invalid_grant", `At most ${CONNECT_LIMITS.connectionsPerUser} connected apps per user`)
+    await this.deps.store.audit({ actor: user.id, action: "connect.token", target: connectionID, detail: "authorization_code" })
+    return this.body(connectionID, pair, grant.scopes)
+  }
+
+  /** A connection ID the hub never used: not a connection's, not a hand-made app token's. */
+  private taken(id: string): boolean {
+    return this.deps.store.users().some((u) => (u.agent?.connections ?? []).some((c) => c.id === id) || (u.agent?.appTokens ?? []).some((t) => t.id === id))
+  }
+
+  /** grant_type=refresh_token: rotate; the just-rotated token within the grace answers the same pair; else reuse. */
+  private async refresh(client: Found, form: URLSearchParams): Promise<TokenBody> {
+    const presented = form.get("refresh_token")
+    if (!presented) throw new OAuthError("invalid_request", "refresh_token is required")
+    const parsed = parseConnectToken(presented)
+    const invalid = () => new OAuthError("invalid_grant", "The refresh token is unknown, expired or revoked")
+    if (!parsed || parsed.kind !== "refresh") throw invalid()
+    const located = this.connectionOf(parsed.connectionID)
+    if (!located) throw invalid()
+    await this.deps.store.recheck({ users: [located.user.id] })
+    const user = this.deps.store.user(located.user.id)
+    const connection = user?.agent?.connections?.find((c) => c.id === parsed.connectionID)
+    if (!user || !connection || connection.clientID !== client.record.id) throw invalid()
+    if (user.disabled) throw invalid()
+    let narrowed: string[] | undefined
+    const scope = form.get("scope")
+    if (scope !== null) {
+      const result = parseScopeParam(scope, strings(connection.scopes))
+      if ("problem" in result) throw new OAuthError("invalid_scope", result.problem)
+      narrowed = result.scopes
+    }
+
+    const hash = hashToken(presented)
+    const pair = this.fresh(connection.id)
+    const at = this.now()
+    type Outcome = { kind: "rotated"; body: TokenBody } | { kind: "grace"; sealed: string } | { kind: "lapsed" } | { kind: "reuse" } | { kind: "gone" }
+    let outcome = { kind: "gone" } as Outcome
+    await this.deps.store.updateAgentData(user.id, (data) => {
+      const current = (data.connections ?? []).find((c) => c.id === connection.id)
+      outcome = { kind: "gone" }
+      if (!current) return
+      if (sameHash(current.refreshHash, hash)) {
+        if ((current.refreshExpiresAt ?? 0) < at) {
+          outcome = { kind: "lapsed" }
+          return
+        }
+        const scopes = narrowed ?? strings(current.scopes)
+        const body = this.body(current.id, pair, scopes)
+        outcome = { kind: "rotated", body }
+        const next: ConnectionRecord = {
+          ...current,
+          scopes: [...scopes],
+          lastUsed: at,
+          accessHash: hashToken(pair.access),
+          accessExpiresAt: at + ACCESS_TOKEN_TTL_MS,
+          refreshHash: hashToken(pair.refresh),
+          refreshExpiresAt: at + REFRESH_TOKEN_IDLE_MS,
+          previous: { refreshHash: hash, accessHash: current.accessHash ?? "", until: at + REFRESH_GRACE_MS, accessUntil: Math.min(current.accessExpiresAt ?? 0, at + REFRESH_GRACE_MS), sealed: seal(body, presented) },
+        }
+        data.connections = (data.connections ?? []).map((c) => (c.id === current.id ? next : c))
+        return
+      }
+      const previous = current.previous
+      if (previous && sameHash(previous.refreshHash, hash) && at <= previous.until) outcome = { kind: "grace", sealed: previous.sealed }
+      else outcome = { kind: "reuse" }
+    })
+    const result: Outcome = outcome
+    switch (result.kind) {
+      case "rotated":
+        await this.deps.store.audit({ actor: user.id, action: "connect.token", target: connection.id, detail: "refresh_token" })
+        return result.body
+      case "grace": {
+        const body = unseal(result.sealed, presented)
+        if (body) return body
+        throw invalid()
+      }
+      case "lapsed":
+        await this.end(user.id, connection.id, { by: "system", why: "refresh token idle 30 days" })
+        throw invalid()
+      case "reuse":
+        await this.end(user.id, connection.id, { by: "system", why: "refresh token reused", action: "connect.reuse" })
+        throw new OAuthError("invalid_grant", "The refresh token was already used: the connection is revoked")
+      case "gone":
+        throw invalid()
+    }
+  }
+
+  /** POST /connect/revoke (RFC 7009): either token of the client's connection ends it; 200 for anything else. */
+  async revoke(request: Request, address = "unknown"): Promise<Response> {
+    try {
+      const form = await this.form(request)
+      const client = await this.authenticate(request, form, address)
+      const value = form.get("token")
+      if (!value) throw new OAuthError("invalid_request", "token is required")
+      const parsed = parseConnectToken(value)
+      const located = parsed ? this.connectionOf(parsed.connectionID) : undefined
+      if (located && located.connection.clientID === client.record.id) {
+        const hash = hashToken(value)
+        const c = located.connection
+        if ([c.accessHash, c.refreshHash, c.previous?.accessHash, c.previous?.refreshHash].some((h) => sameHash(h, hash))) {
+          await this.end(located.user.id, c.id, { by: `app:${c.id}`, why: "revoked by the app" })
+        }
+      }
+      return new Response(null, { status: 200, headers: NO_STORE })
+    } catch (cause) {
+      if (cause instanceof OAuthError) return oauthResponse(cause)
+      throw cause
+    }
+  }
+
+  // ---------- the access token verifier ----------
+
+  /** hca_<connection>_<secret> → the connected app's actor; past its hour "expired"; anything else undefined. */
+  readonly verifier: BearerVerifier = {
+    kind: "app",
+    verify: async (value: string): Promise<VerifyResult> => {
+      const parsed = parseConnectToken(value)
+      if (!parsed || parsed.kind !== "access") return undefined
+      const located = this.connectionOf(parsed.connectionID)
+      if (!located) return undefined
+      // A revocation on another pod applies at once: read the user again (a no-op for the file store).
+      await this.deps.store.recheck({ users: [located.user.id] })
+      const connection = this.deps.store.agentData(located.user.id).connections?.find((c) => c.id === parsed.connectionID)
+      if (!connection) return undefined
+      const client = this.usable(connection.clientID)
+      if (!client) return undefined
+      const hash = hashToken(value)
+      const at = this.now()
+      if (sameHash(connection.accessHash, hash)) {
+        if ((connection.accessExpiresAt ?? 0) < at) return "expired"
+      } else if (!(connection.previous && sameHash(connection.previous.accessHash, hash) && at <= connection.previous.accessUntil)) return undefined
+      const actor: AppActor = {
+        kind: "app",
+        userID: located.user.id,
+        tokenID: connection.id,
+        scopes: this.scopesOf(located.user.id, connection.id) ?? [],
+        label: this.clientView(client).name,
+        clientID: client.record.id,
+        connection: true,
+      }
+      return actor
+    },
+  }
+}