Guardian edge TLS + CORS for remote clients (Phase 6.5 — gates the phone/PWA story)

[fwdslsh-dev]

Summary

Give the guardian edge an HTTPS story and a CORS allowlist so remote clients (the hosted PWA at the official URL, and any phone) can connect. This is Phase 6.5 of docs/technical/ui-runtime-modes-plan.md and a hard prerequisite for the mobile half of #511.

Why this is unavoidable (platform rules, not our code)

• Secure context: a PWA installs only over HTTPS or from localhost. Plain HTTP on a LAN IP is never installable.
• Mixed content: an HTTPS origin (the hosted client) cannot fetch() a plain-HTTP guardian. So every phone → guardian connection needs TLS, regardless of where the client was installed from.
• The desktop/localhost install path needs none of this — a http://127.0.0.1 origin is a secure context and may call plain-HTTP LAN guardians (loopback is the most-trusted Private Network Access tier). That's why it's the zero-setup default and this issue only gates the remote/phone story.

Today there is no TLS anywhere in the stack (verified: no caddy/tls references in packages/skeleton/system/stack/ or containers/) and guardian sends no CORS headers.

Simplicity guardrail (from the ratified plan, §8 rule 11)

TLS is never a manual user task on default paths. Explicit non-goal: asking non-technical users to install a private CA on iOS/Android (mkcert-style). The chosen flows must be guided.

Scope

• Recommended default: Tailscale. Guided docs + (optionally) a sidecar/serve integration so a guardian gets a ts.net name with a real Let's Encrypt cert — no cert management for the user
• Alternative: Caddy front for the guardian with a user-owned domain (DNS-challenge Let's Encrypt) for users who don't want Tailscale
• CORS allowlist on guardian ingress: official hosted origin (e.g. app.openpalm.dev) baked in, additional origins configurable; enforced tests
• requiresHttpsForRemoteConnections enforced client-side too: the hosted client refuses plain-HTTP non-loopback targets with an actionable message deep-linking to the TLS guide
• Coordinate with Guardian LAN/mDNS self-advertisement #488 (mDNS advertisement should surface the HTTPS name when enabled) and Guardian: mTLS adapter auth + keep authn/authz seams generic  #435 (credentials only ever sent over HTTPS for non-loopback targets)

Non-goals

• No change to the loopback-default posture: guardian stays LAN-dark unless explicitly exposed (OP_BIND_ADDRESS policy unchanged)
• No public-internet exposure guidance beyond the Tailscale/Caddy paths

Related

• docs/technical/ui-runtime-modes-plan.md — Phase 6.5, §6.10
• docs/technical/ui-client-split-assessment.md — evidence §4 (secure context, mixed content, PNA)
• PWA mode: installable client from two origins — localhost (zero TLS) + official hosted URL #511 — PWA install paths (blocked on this for phones)
• Remote-only (client) install: connect to a remote assistant/stack #486 — remote-only install
• Guardian: mTLS adapter auth + keep authn/authz seams generic  #435 — guardian auth
• Guardian LAN/mDNS self-advertisement #488 — mDNS

[itlackey]

Status after merged PR #559 (merge commit c1eadbd): #559 delivered the client artifact and local/desktop client-serving prerequisite, but did not implement guardian edge TLS or production CORS policy.\n\nLeaving this open. It still gates the phone/hosted-PWA path described in #511: HTTPS for non-loopback guardians, configured CORS allowlist, and client-side refusal of unsafe remote HTTP targets.

[itlackey]

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

Current state:

• Guardian CORS allowlist support exists: GUARDIAN_CORS_ALLOWED_ORIGINS is parsed as exact http/https origins with wildcard/path/query/hash rejection.
• Direct ingress preflight and response CORS handling exists in packages/guardian/src/server.ts, with coverage in packages/guardian/src/cors.test.ts using https://app.openpalm.dev as the allowed-origin example.
• TLS is not implemented here. There is no Tailscale/Caddy edge flow or certificate automation in the shipped stack yet.

Remaining work to complete this issue:

• Decide and implement the default guided TLS path, likely Tailscale ts.net, without making manual CA/certificate installation a default user task.
• Add the alternative Caddy/user-domain path if it remains in scope.
• Wire docs and UI affordances that tell the user which Guardian URL is safe for hosted/mobile clients.
• Enforce client-side refusal of plain HTTP non-loopback targets from hosted/mobile contexts before credentials are sent.
• Ensure GUARDIAN_CORS_ALLOWED_ORIGINS includes the official hosted client origin in the appropriate install/deploy path and supports operator extras.
• Coordinate Guardian LAN/mDNS self-advertisement #488 so discovery advertises the HTTPS name when enabled.

Suggested verification gate:

• Guardian direct-ingress preflight from the hosted origin returns 204 with expected CORS headers.
• Denied origin returns fail-closed with no credential leakage.
• Hosted client connects successfully to an HTTPS guardian.
• Hosted client refuses http://<lan-ip> guardian URLs with an actionable TLS guide link.
• Release docs include the chosen TLS path and the operator configuration for extra allowed origins.