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 |
| **Created** | 2026-10-13 |
| **Author** | OpenArchitect |
| **Target milestone** | **M0** |
| **Governing decisions** | **D-002** · **D-003** · **D-025** · **D-031** · **D-039** · `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`; SET `X-Forwarded-For` (never append)  [A6]
  3. security headers    — X-Content-Type-Options · Referrer-Policy · a strict CSP · HSTS (when https)
  4. routing.Dispatch()  — the pure model (SPEC-002)
  5. 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
  6. audit               — every auth event + every mutation (A11)
  7. 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 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=/`**.
- 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.
- **Logout** revokes the session row.

---

## 7. Loopback enforcement (D-025)

- In **setup mode**, if `server.listen` is **not loopback**, the process **refuses to start**
  (fail-closed). The operator bootstraps over an **SSH tunnel** to `127.0.0.1:8080`.
- Once the top admin exists (`setup: false`), a public bind is allowed.

---

## 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 | In setup mode with a non-loopback `listen`, the process **exits with an error** (D-025) |
| 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) |

---

## 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: `session_key`/`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. |
| 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. |