NextMyDay/docs/specs/spec-003-core-door.md

SPEC-003 — the core door (internal/core/server + httpx)

Field	Value
Status	Implemented (2026-10-13) — see §10; build/vet/test/-race green · static binary · live-smoked. Hardened 2026-10-14 — see §11 (REVIEW-001 H1/H2/M1c/M3s/L1s/L4s).
Created	2026-10-13
Author	OpenArchitect
Target milestone	M0
Governing decisions	D-002 · D-003 · D-031 · D-039 · D-043 · D-045 · PROJECT_PLAN.md §4/§12
Related	SPEC-002 (routing) · SPEC-004 (identity)

---

1. Goal

The single HTTP entry — the door — that turns an inbound request into a dispatched module function, applying identity / session / role and all cross-cutting concerns. The door resolves and gates; a module never sees a request it shouldn't (D-002, D-039).

---

2. Non-goals

• The routing model → SPEC-002.
• Identity/session storage, users, roles, the chain → SPEC-004.
• The /setup, enroll, login, recovery flows → SPEC-005+.

---

3. Structural changes

Path	Purpose
cmd/myday/main.go	assemble config → core → discover modules → serve
internal/core/server/	the door pipeline + dispatch
internal/core/httpx/	session cookie · client IP (trusted proxies) · RedactPath · security headers · CSRF
internal/core/middleware/	correlation id · rate limit · audit

---

4. The door pipeline

request
  1. correlation id      — generate a UUID; put it on the context and in every log line
  2. client IP           — resolve from `server.trusted_proxies`; walk XFF **right→left** and
                           SET it to the one resolved value (never append)  [A6/H1]
  3. security headers    — X-Content-Type-Options · Referrer-Policy · a strict CSP · HSTS (when https)
                           · Permissions-Policy · COOP · CORP  [L4s]
  4. routing.Dispatch()  — the pure model (SPEC-002)
  5. setup gate           — the gate is the config toggle `setup` (D-045). While `setup: true`
                            `/setup` serves the wizard (the code form first when `setup_code` is
                            set, D-044); `GET /` points at it; everything else 404. `setup: false`
                            with no admin is the LOCKED state: `/` and `/setup` get the "enable
                            setup" boilerplate, everything else 404 (§7)
  6. switch on Kind:
       Redirect   → 302
       NotFound   → 404
       Setup      → the setup wizard, ONLY in setup mode; else 404
       Enroll     → the enrollment screen (if already enrolled → redirect)
       Route/Action →  [the identity gate]
            a. load the session cookie → validate:
                 exists · not expired · not revoked · **non-empty session id**  [A2]
            b. session.user_id == the resolved GUID's user   (the identity match)
            c. missing/invalid → KindLogin (login screen)
            d. ROLE gate: does the user's role permit this function?
            e. build the RequestContext → dispatch to the module function
  7. audit               — every auth event + every mutation (A11)
  8. rate limit          — `/{GUID}`, `/access`, `/setup` (A3)

• Before dispatching, the door attaches audit.Meta{ActorUserID · ClientIP · CorrelationID} to the context.Context, so services can write their audit rows (SPEC-004 §5, ruling R-1).
• The setup module is pinned at the door: the wizard's functions are reachable only through the reserved setup workflow; any other resolution naming it 404s (M1c/L3s).

The door renders no dynamic HTML — it resolves, gates, and hands off.

---

5. RequestContext (in-process hand-over)

type RequestContext struct {
    Workflow    string   // PARAM1 classification
    UserID      int64    // the resolved user (0 when anonymous)
    Principal   string   // "user:<id>" — IDENTIFICATION only, never a credential
    Function    string   // the resolved module function / action
    Page        string   // the joined remainder
    Correlation string   // the request's correlation id
    ClientIP    string   // resolved client IP
    Location    string   // IP-derived, AUDIT ONLY (D-031) — no tracking
}

• Carries identification, never a credential.
• Principal and the credential (session cookie) are separate concerns (D-001).

---

6. Session cookie & CSRF

• Cookie myday_session: HttpOnly · Secure · SameSite=Lax · Path=/.
• Over https the cookie carries the __Host- prefix (__Host-myday_session, L1s): a browser only accepts it with Secure · Path=/ · no Domain, so the cookie is pinned to the exact origin and a sibling subdomain cannot shadow it. On plain-http loopback (the bootstrap / human test) the bare name is used — a browser rejects a __Host- cookie sent without Secure, so the prefix cannot be unconditional.
• Opaque random id; the server-side row is authoritative (SPEC-004).
• CSRF: a per-session token on every action (do/action) — hidden field, verified server-side (A8). The action fields are not a security control on their own.
• The pre-session double-submit token (A15) covers every anonymous form (/setup, /access, enroll/login). In setup mode the CSRF + cookie signing keys are generated at startup when left at a placeholder, so the ceremony is never signed with a shipped, public key (M1s).
• Logout revokes the session row.

---

7. Setup gate (D-045)

• No bind refusal. The app may bind any address — 0.0.0.0:8080 behind Zoraxy (D-043).
• The gate is the config toggle setup (D-045; the peer/tunnel rule of D-025 is retired).
  • setup: true → /setup serves the wizard. If setup_code is set the code form comes first (D-044) and the unlock is a signed cookie; otherwise the toggle alone admits. GET / points at the wizard; every other route is 404.
  • setup: false, no admin → the LOCKED state: GET / and GET /setup show an "enable setup" boilerplate; every other route is 404. Not publicly claimable.
• Once productive (setup: false with an admin), normal service: the trusted proxy's X-Forwarded-Proto drives Secure on the session cookie, the __Host- prefix, and HSTS (§6 · D-043). The XFF handling keeps the client IP honest (A6) — it is no longer a gate.

---

8. Logging & redaction

• slog, structured, with the correlation id on every line.
• The access log records the raw path + PARAMS; the GUID is public (a username) but any credential that rides the path is redacted (RedactPath) — A8/A11.
• The door logs the resolved (workflow, module, function); a module logs its own steps.

---

9. Acceptance criteria

#	Criterion
AC-1	/ → 302 /home; /holy-shit → 404
AC-2	/home renders with no session and no DB lookup
AC-3	/{GUID} with no session → login; with a valid session → the module function
AC-4	A session whose user_id ≠ the GUID's user is rejected
AC-5	An empty / missing session id is rejected on every path (A2)
AC-6	A do/action request without a valid CSRF token is rejected
AC-7	While the wizard is enabled (setup: true) with a required setup_code, GET /setup shows the code form to every peer; only an unlocked request reaches the wizard. The peer/tunnel rule of D-025 is retired (D-045)
AC-8	Every response carries a correlation id, echoed in the log; path credentials are redacted
AC-9	The rate limiter returns 429 on the auth-sensitive routes (A3)
AC-10	While the wizard is enabled with a required code, no peer reaches the wizard without the unlock; the code form is shown instead, and every non-wizard route is 404 (D-045, superseding D-025/H2)
AC-11	The setup module is reachable only through Workflow == "setup"; any other resolution naming it is 404 (M1c/L3s)
AC-12	X-Forwarded-For is resolved right→left; a forged leftmost entry is ignored (H1/A6)
AC-13	Behind the proxy, X-Forwarded-Proto: https ⇒ the session cookie is Secure + __Host-, and HSTS is set (D-043)
AC-14	setup: true → GET /setup serves the wizard (or the code form when setup_code is set); GET / points at it; the correct setup code unlocks it, a wrong/absent one does not (D-044/D-045). setup: false with no admin → a locked boilerplate at / and /setup (never a bare 404)

---

10. Implementation notes (accepted rulings)

Built 2026-10-13. build · vet · test · -race green; static CGO-free binary; live smoke verified (/→302 · /home→200 · /setup→200 · /holy-shit→404 · correlation id in header and log · loopback enforcement · fail-closed secrets). internal/core/routing purity intact.

#	Builder choice	Ruling
D-1	gopkg.in/yaml.v3 + KnownFields(true) (unknown config key = error)	Accepted — pure-Go, static-safe, fail-closed.
D-2	Secret strength: cookie_secret/csrf_key ≥ 32 bytes; totp_encryption_key = 32 bytes; CHANGE_ME rejected in productive mode	Accepted — to be documented in the config reference. Amended 2026-10-14: the dead session_key is removed (L1c/L2s).
D-3	CSRF = stateless HMAC-SHA256(csrf_key, "myday.csrf.v1:"+session_id)	Accepted — no extra table; dies with the session.
D-4	In-memory fixed-window rate limiter (30/min; classes access·setup·guid)	Accepted.
D-5	RoleGate seam, defaulting to allow any authenticated user	Accepted — the policy lands in SPEC-007/008.
D-6	Env: config path via MYDAY_CONFIG only	Accepted; per-key env override deferred.
D-7	RequestContext = exactly §5 (no Module field)	Accepted — module identity stays on Resolution.

Rulings on the flagged items:

#	Item	Ruling
R-4	auth.Mint/Rotate/Revoke hard-code the owning user as actor.	Use the context actor (creator/approver); the affected user is the subject — see SPEC-004 §8.
R-5	Pre-session CSRF — /setup, /access and the enroll/login actions run before a session, so §6's session-bound CSRF doesn't cover them.	Must be added — a signed double-submit cookie for anonymous forms. Applies to SPEC-005/006/007; tracked as A15.
—	RequestContext.Location always empty (D-031)	Accepted — the seam exists; the IP-geo lookup is deferred.
—	RedactPath over-redacts a segment after a credential-like name	Accepted — log-only; no leak.

---

11. M0 review hardening (2026-10-14 · REVIEW-001)

The independent M0 review found the identity/session/CSRF core sound but the perimeter weak. The fixes touching this spec:

Finding	Fix
H2 — dispatch checked loopback only at bind	§7: a per-request gate — in setup mode a non-loopback resolved client IP is 404 before dispatch (AC-10).
H1 — resolveForwarded returned the leftmost untrusted hop	ClientIP now walks right→left and returns the first untrusted entry, falling back to the peer (AC-12). An append-style proxy can no longer be forged past.
M1c — the /setup action door was not pinned to the module	serveSetupAction rejects Module != "setup" (AC-11).
L3s — /{GUID}?do=setup&… fell through to serveGUID	The door rejects any resolution naming the setup module outside Workflow == "setup", in every mode (AC-11).
M1s — placeholder signing keys ran the whole setup	cmd/myday generates the CSRF/cookie keys at startup in setup mode, mirroring the TOTP key (R-6/D-1); finish persists the same values.
M3s — the rate limiter's state map was never pruned	middleware.RateLimiter sweeps elapsed windows (time-gated, amortised) and caps the map.
L1s — no __Host- cookie prefix	§6: session cookie is __Host-myday_session over https.
L4s — missing hardening headers	Permissions-Policy · Cross-Origin-Opener-Policy · Cross-Origin-Resource-Policy (§4 step 3).
L1c/L2s — dead secrets.session_key	Removed (D-2 amended).
L7c — the passkey nudge trusted the client Host	SPEC-006 §8: the configured base_url host is the origin signal, falling back to the request Host.

build · vet · test -race green; the static CGO-free binary is unchanged; internal/core/routing purity intact.

---

12. D-044 — the setup code gate & the first-run boilerplate (2026-10-15b)

Superseded in part by D-045 (§13). The code mechanics below stand; the tunnel gate (a) and the generated code are retired, and GET / is no longer the code form.

The topology (LXC behind Proxmox + Zoraxy) makes the SSH tunnel impractical: pct enter/SSH lands on the container gateway, so a tunnel to 127.0.0.1:8080 cannot be formed and gate (a) alone would lock the operator out. D-025 is re-revised so /setup is served when either (a) the request is the direct tunnel or (b) it is unlocked with the setup code (D-044).

• dispatch gains the gate: unlocked := SetupGate.Unlocked(r); allowed := setupTunnel || unlocked. The unlock action (POST /setup?do=setup&action=unlock) is the ONE request served without either — it is what grants the unlock — and it is still pinned to the setup module and CSRF-protected (A15) and rate-limited (A3).
• GET / and an un-unlocked GET /setup are handed to the first-run boilerplate — the door resolves to SetupGate.Boilerplate rather than a 404, so the domain never looks "down".
• The gate is a narrow interface on server.Deps (implemented by *setup.Gate), so the door keeps rendering no dynamic HTML itself.
• The code is single-use, rate-limited and redacted (A8); the unlock is a signed cookie carrying a keyed fingerprint of the code, never the code (SPEC-005 §9).

AC-7/AC-10 are reworded: "refused" now means "refused the wizard" — the boilerplate may still answer GET //GET /setup with 200 (AC-14).

---

13. D-045 — the toggle gate, the optional code, the retired tunnel (2026-10-15c)

The peer/tunnel gate is retired: setup: true is the gate. dispatch evaluates the config toggle per request:

• setup: true — setupAdmitted(r) is true when no setup_code is required, else it needs a valid SetupGate.Unlocked(r). /setup with a required code un-entered → SetupGate.CodeForm; GET / → SetupGate.Landing; the unlock action is the one carve-out; every other route → 404 (static assets are served so the first-run pages render inside the shell).
• setup: false, no admin — the LOCKED state (Deps.LockedMode): GET / and GET /setup → SetupGate.Locked; every other route → 404.

Removed: httpx.SetupRequestAllowed, httpx.IsLoopbackIP (and their tests). Kept: the XFF right→left client-IP resolution and the X-Forwarded-Proto-driven Secure/__Host-/HSTS (A6/A11 · D-043). SetupGate is now { Required · Unlocked · CodeForm · Landing · Locked }.