# 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)

```go
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 }`.