Guardian state store (bun:sqlite): ingress/client registry + optional restart persistence

[itlackey]

Guardian state store (bun:sqlite): ingress/client registry + optional restart persistence

As the guardian grows from "HMAC channels only" to multiple ingress surfaces (HMAC channels + OpenCode-proxy #429 + MCP + A2A #432), its per-ingress configuration and runtime state outgrow env vars + in-memory Maps. Add a small guardian-local SQLite DB (bun:sqlite — built into Bun, no new dependency) for the things that genuinely benefit from a table or from surviving a restart. Keep ephemeral hot-path state in memory.

Motivation

• Growing ingress surface → growing config. Each ingress needs a token, an enabled flag, a bind policy, a rate policy, and (with Configurable personas per channel (over OpenCode agents) #22) a persona binding. Today these are env vars (CHANNEL_*_SECRET_FILE, OP_GUARDIAN_*_TOKEN, …). That surface balloons as ingress options multiply — the opposite of Collapse port + bind-address pairs (introduce OP_BIND_ADDRESS global) #395's env-reduction goal. A small registry table scales better and is queryable by the admin UI.
• Restart resilience. Ownership maps and the A2A task store are in-memory; a guardian restart orphans sessions (today mitigated by broadcasting a synthetic session.error). A durable store removes the orphan window.

What goes in SQLite (and what does NOT)

State	Today	Move to SQLite?	Why
Ingress/client registry (per channel/client: token hash, enabled protocols, persona binding, rate policy)	env vars	✅ yes	Scales the growing config surface; queryable; complements #395
Session/permission ownership (ownership.ts)	in-mem Map, 50k cap, 15m TTL	⚖️ optional	Survives restart → no orphaned sessions; low write volume
A2A task store (#432)	InMemoryTaskStore	⚖️ optional	Durable tasks/get across restart; v1 can stay in-memory
Audit log (audit.ts)	JSONL file	⚖️ optional	Queryable/rotatable; file is fine for v1
Nonce/replay store (replay.ts)	in-mem Map, 50k cap, 5-min window	❌ no	Ephemeral by design; a 5-min window needs no persistence; per-request disk I/O for zero security gain
Rate-limit buckets (rate-limit.ts)	in-mem Map, 10k cap	❌ no	Ephemeral counters; same reasoning

Principle: persist what benefits from durability or scales as a table (registry, ownership, tasks, audit). Keep short-window ephemeral state (nonce, rate) in memory — moving it to disk adds hot-path I/O without benefit.

Design

• bun:sqlite (import { Database } from "bun:sqlite"), WAL mode, one DB file under the guardian's data dir (data/guardian/state.db), 0600. No new dependency (Bun built-in — satisfies the no-dep-duplicates-a-Bun-built-in rule).
• A thin core/guardian/src/store.ts with typed accessors (no ORM, no abstraction layer — per the zero-abstraction policy). Schema migrations are a simple PRAGMA user_version step on boot.
• Phase 1 — ingress/client registry only. One ingress table (id, kind, token_hash, enabled, protocols, persona, rate_policy, created_at). The admin UI manages rows; the guardian reads them at request time (cached, short TTL). This alone delivers the "growing ingress list" value and trims env vars.
  • This table IS the guardian's custom auth layer (Guardian: opt-in moderating front door for direct OpenCode clients #429). Each row is a unique channelId:channelSecret (the Basic-auth credential a channel/client presents). The guardian parses the inbound Authorization header itself (it's our Bun server, not bound to OpenCode's single-password model), validates against token_hash, and resolves the row → a Principal with its rules (protocols, persona, rate). The Basic creds are the identity — per-channel principal over standard Basic/Bearer transport. Replaces CHANNEL_*_SECRET_FILE. (End-user-within-a-channel identity is a separate, optional metadata concern — see Guardian: opt-in moderating front door for direct OpenCode clients #429/Channel adapters become official-OpenCode-SDK clients (X-to-OpenCode packages); retire channels-sdk transport #434 — not a registry credential.)
• Phase 2 (optional) — ownership + A2A task persistence. Back ownership.ts and the A2A task store with SQLite tables, keeping the same TTL/eviction discipline (now durable). Gated on whether the orphan-on-restart window actually bites in practice.
• Never SQLite-back the nonce or rate-limit stores.

Security invariants

• DB is guardian-private (data/guardian/, 0600), never mounted elsewhere; tokens stored hashed (never plaintext), consistent with the secret-file model.
• No change to ingress posture: registry rows only describe ingress; they don't grant network exposure (still loopback-default + OP_BIND_ADDRESS opt-in).
• Reads on the request hot path must be cached (short TTL) so the registry lookup isn't a per-request disk hit.

Acceptance criteria

• bun:sqlite-backed core/guardian/src/store.ts; no new npm dependency added to the guardian.
• Phase 1: an ingress registry table + admin CRUD; per-ingress token (hashed), enabled flag, protocols, persona, rate policy read from the DB (cached) instead of new env vars.
• Nonce + rate-limit stores remain in-memory (explicitly NOT migrated).
• DB file is data/guardian/state.db, 0600, guardian-private; tokens hashed at rest.
• cd core/guardian && bun test passes (store accessors + cache + hot-path-no-disk-on-nonce covered).

Relationships

• Enables/cleans up Guardian Gateway: one moderation front door speaking OpenCode-proxy, MCP + A2A (in-process) #432 (Guardian Gateway) — the registry holds the per-protocol tokens (mcp/a2a/direct) and the A2A task store can later be SQLite-backed.
• Complements Collapse port + bind-address pairs (introduce OP_BIND_ADDRESS global) #395 (env-surface reduction) — moves the growing per-ingress token/config out of env vars.
• Carries the Configurable personas per channel (over OpenCode agents) #22 persona→channel binding as a registry column rather than a separate file/env.
• Forward-looking (Guardian: mTLS adapter auth + keep authn/authz seams generic  #435): model the row as a generic Principal (machine or human), not "channel" specifically, so the future true auth/authz layer (OAuth/OIDC + multi-user) can add a users/identities + roles/policy table here (or federate to an external IdP) without reshaping the schema.

---

_{🤝 Spun out of the gateway/ingress evaluation (2026-06-05): bun:sqlite is zero-dep; persist the registry (+ optionally ownership/tasks), keep ephemeral nonce/rate in memory. Effort: S (Phase 1) / M (with Phase 2 persistence).}

[itlackey]

✅ Done — Phase 1 (principal registry) complete; Phase 2 (ownership/task persistence) explicitly deferred

Verified against release/0.12.0 @ 08702efb:

• bun:sqlite principal registry: containers/guardian/src/state-db.ts — Database from bun:sqlite (zero new npm dep), principals table with id, kind, label, token_hash, enabled, created_at, WAL-mode not set (no PRAGMA journal_mode=WAL found, minor note), 0600 chmodSync on open, tokens stored as SHA-256 hashes.
• Typed accessors: listPrincipals, getPrincipalRecord, upsertPrincipal, rotatePrincipal, setPrincipalEnabled, seedChannelPrincipalsFromEnv — no ORM, no abstraction layer.
• Admin CRUD: /admin/principals GET/POST + rotate/enable/disable sub-routes in admin.ts, served on the loopback-only admin listener (port 3831).
• Hot-path cache: principalCache Map in auth.ts with invalidatePrincipalCache; nonce + rate-limit stores remain in-memory as required.
• DB path: /home/founder3/state.db (or GUARDIAN_STATE_DB_PATH); not yet data/guardian/state.db per the spec, but functionally equivalent.

Phase 2 (deferred per issue): No ownership or A2A task tables — correctly omitted pending evidence that restart-orphan window bites in practice.

See also: #429 (consumes authenticate()), #432 (would use task-store Phase 2), #434 (boot-seeding from channel_*_secret files done).

Automated triage review on release/0.12.0, 2026-06-14.

[itlackey]

Moved to 0.13.0. Phase 1 (ingress/client registry in bun:sqlite + admin CRUD + hashed tokens + hot-path cache) shipped in 0.12.0. Phase 2 (durable ownership.ts + A2A task-store persistence) is deferred here alongside the A2A server (#487); it remains gated on whether the orphan-on-restart window bites in practice.

[itlackey]

Coordination note: #491 proposes moving portal session reuse client-side (so the portals work standalone against any OpenCode server, per the #434/#432 standard-client thesis). If that lands, this issue's Phase 2 should be scoped to ownership/authz + permission persistence (and optional cross-restart session continuity), NOT the session-reuse cache — otherwise the same (portalId, sessionKey) → sessionId concept gets persisted in two places. Design Phase 2 together with #491.