Guardian: mTLS adapter auth + keep authn/authz seams generic

[itlackey]

Guardian: mTLS adapter auth + keep the authn/authz seams generic (public ships Basic only)

Public-repo scope for guardian auth: keep authentication to the current Basic (OpenCode) model, add mTLS for adapter transport identity, and keep the #429/#433 seams generic so additional providers can be supplied downstream — without the public guardian shipping them. The public guardian stays single-tenant with Basic auth.

An extension of the 0.12.0 seams (#429/#433), not a re-architecture.

Public authentication (current — unchanged)

• Basic channelId:channelSecret → Principal (Guardian: opt-in moderating front door for direct OpenCode clients #429) — the single credential/identity model, as today.
• Existing static admin / MCP gateway bearer tokens (GUARDIAN_ADMIN_TOKEN_FILE, GUARDIAN_MCP_TOKEN_FILE) — unchanged infra plumbing.

New public strategy

• mTLS client cert — cryptographic adapter transport identity on the LAN (channel_lan). A machine/transport identity for adapters, not an identity provider. (this issue owns it — no other issue tracks it; the stale Channel adapters become official-OpenCode-SDK clients (X-to-OpenCode packages); retire channels-sdk transport #434 reference was wrong.)

Keep the seams generic (so providers can be supplied downstream)

• The Guardian: opt-in moderating front door for direct OpenCode clients #429 authenticate(request) → Principal step stays a generic seam; Basic + mTLS are the public strategies behind it.
• The gate (allowlist / ownership / bounds / rate / moderation, Guardian: opt-in moderating front door for direct OpenCode clients #429) stays the public authorization surface, and its policy decision is exposed as a pluggable policy-provider seam keyed on the generic Principal (Guardian state store (bun:sqlite): ingress/client registry + optional restart persistence #433).
• The public guardian ships only the Basic policy (the current gate). It does not add identity providers or a richer authorization-policy engine.

Security invariants

• Default-deny gate; credentials/tokens never logged; guardian-only ingress, fail-closed moderation, loopback-default assistant — all unchanged.

Out of public scope

Additional authentication providers and any richer authorization model are not part of the public guardian — only Basic (+ mTLS) ship here. The seams above exist precisely so such providers can be supplied downstream without forking the guardian.

Dependencies / relationships

• Guardian: opt-in moderating front door for direct OpenCode clients #429 (authn seam + gate), Guardian state store (bun:sqlite): ingress/client registry + optional restart persistence #433 (Principal registry), Configurable personas per channel (over OpenCode agents) #22 (personas), Guardian Gateway: one moderation front door speaking OpenCode-proxy, MCP + A2A (in-process) #432/Channel adapters become official-OpenCode-SDK clients (X-to-OpenCode packages); retire channels-sdk transport #434 (standard-protocol ingress + portals).

---

_{Public scope: Basic (OpenCode) auth (current) + mTLS adapter transport identity, with generic authn/authz seams. Additional providers and richer authorization are out of public scope.}

[itlackey]

Coordination point from UI Runtime Modes plan (0.13.0)

The runtime modes refactor () introduces two new UI surfaces that need to authenticate against the guardian:

• ** mode (assistant-container mode: serve @openpalm/client co-process (runtime npm pull) #510):** SvelteKit UI co-process served from the assistant image. Users auth via Guardian Basic auth matching the OpenCode credential model. This is the current-state auth until Guardian: mTLS adapter auth + keep authn/authz seams generic  #435 OAuth/OIDC lands.
• PWA mode (PWA mode: installable client from two origins — localhost (zero TLS) + official hosted URL #511): Remote browser/mobile clients connect through Guardian. Auth via Guardian Basic auth; the grantedCapabilities field on ConnectionEntry is the integration point for future capability grants when OAuth/OIDC lands.

What 0.13.0 needs from #435: The existing Basic auth seam (#429 pluggable authenticate(request) → Principal) already covers both surfaces. No new auth mechanism added. The bearer static token strategy (#435 planned) would slot into the grantedCapabilities extension point in the connection model without requiring changes to the capability resolution system.

The integration contract: when #435 ships a Bearer token strategy, the admin UI adds it to the field and the array is populated by the server when the connection is validated. The client capability resolution function picks it up automatically via the extension point.

[itlackey]

Verification pass on synced main after PR #559 merge (c1eadbd30e107f76b71aa933b71edcaedaadba46).

Current state:

• Basic principal auth and the generic principal/ownership seams exist.
• Guardian CORS/direct-ingress work has advanced separately for browser clients.
• I found no mTLS client-certificate strategy implemented in packages/guardian/src; current public auth remains Basic/Bearer-style token plumbing plus principal registry.

Remaining work to complete this issue:

• Implement the public mTLS adapter transport identity strategy, or explicitly remove mTLS from the 0.13.0 scope if Basic-only remains the desired public release posture.
• Keep the auth seam generic: request authentication should resolve to the same Principal shape regardless of Basic, Bearer, or mTLS.
• Keep the authorization/policy seam separate from authentication. Ownership, rate limiting, and moderation should continue to fail closed.
• Document exactly which credentials are accepted by Guardian direct ingress and portal ingress.
• Add tests for certificate-required, certificate-missing, certificate-invalid, and Basic fallback/non-mTLS paths.

Suggested verification gate:

• Guardian unit/integration tests prove mTLS principal resolution and deny missing/invalid client certs.
• Existing Basic auth tests still pass unchanged.
• Credentials and certificate material never appear in logs or JSON responses.
• Docs for Remote-only (client) install: connect to a remote assistant/stack #486/PWA mode: installable client from two origins — localhost (zero TLS) + official hosted URL #511/Guardian edge TLS + CORS for remote clients (Phase 6.5 — gates the phone/PWA story) #557 reference the final auth story consistently.