MeshTender/docs/auth-cross-host.md

Cross-host identity & sessions

MeshTender serves three kinds of host from one binary (web.Dispatcher):

• auth host — login/signup/WebAuthn (internal/auth)
• app host + custom org domains — the authenticated product (internal/core)
• root host — public marketing & org/repeater discovery (internal/marketing)

Cookies are host-only by design (__Host- prefix over HTTPS, no Domain attribute — see internal/auth/service.go). Each host gets its own independent session; one host's cookie is never sent to another. This file records the rules that let the public discovery surface show logged-in-aware UI (e.g. "you're already a member — open it") without weakening that isolation. Do not break these without revisiting the whole model.

Rules

1. Never widen cookie scope. No Domain attribute; keep the __Host- prefix over HTTPS. Identity is propagated by giving each host its own host-only cookie, not by sharing one.

2. The root cookie is a minimal, read-only identity beacon — not a session. It carries only login_id (and a cached user_id for rendering). It grants no powers. Never cache facts like org membership in it; resolve those live per-request (e.g. Store.OrgRole) so they can't go stale.

3. The root surface is strictly side-effect-free GET. No state-changing request of any method lives on the root host — all mutations stay on the app host. This is what makes CSRF on root a non-issue: there is nothing to forge. A side-effecting GET (logout link, a /join that actually joins, identity-tied writes) breaks this rule.

4. No credentialed CORS on personalized responses. SSR is the only personalization path for the root surface. Never serve a personalized endpoint with Access-Control-Allow-Credentials: true + a permissive origin — that's what lets a cross-origin attacker read a viewer's identity.

5. The beacon must be authenticated. The root identity cookie is set only in exchange for a valid single-use handoff code minted for the currently logged-in app user (reuse CreateAuthCode/ConsumeAuthCode). Never "set a cookie for whoever calls the endpoint" — that is login-CSRF / fixation.

6. XSS hygiene on root (GET-only does not mitigate XSS — it only widens the payoff of one): html/template autoescaping only, zero template.HTML/ raw HTML on the root surface, keep HttpOnly on all session cookies, and serve a CSP (no inline script, locked-down connect-src). Blast radius stays on root because host-only cookies stop any pivot to the app session.

Global logout model

A parent logins row is the source of truth for a login (id, user_id, created_at, revoked_at, optional device label). Every per-host session (app, auth, root beacon, custom org domains) stores login_id in its scs data blob and is validated against the parent on each request.

• Logout = one write: set revoked_at on the logins row. Every host drops to anonymous on its next request (ValidateSession destroys any session whose backing login is revoked) — including custom org domains, which the old redirect-chain logout never covered.
• Per-device logout = revoke one row; "log out everywhere" = revoke all of a user's rows.
• Do not add per-host token columns to the scs sessions table — scs resolves a cookie by its single token PK, and the host set is unbounded (every custom domain is another host).

Logout is a per-host POST, never a cross-host GET chain

Sign-out is a POST on the host that holds the session (app, auth, or a custom org domain). That handler revokes the shared login row and lands the visitor on the public root. Because a single real sign-in maps to exactly one login row (the handoff callbacks reuse it via loginWithID), revoking it once on any of those hosts drops all of them on their next request — so there is no redirect chain from the app host to an auth-host /logout. The auth host's own POST /logout still exists to cover the auth-local case: a visitor who authenticated on the auth host (e.g. for account settings) with no app session signs out there directly.

/logout is POST-only on every host — state-changing actions are POST (rule 3's spirit applied everywhere), so a forged cross-site GET like <img src=".../logout"> cannot sign anyone out. The template picks the right target via LogoutURL (relative /logout on mutating surfaces); the root host is side-effect-free GET and therefore has no /logout at all — its chrome hides the sign-out control and the user signs out from the app dashboard.