// Package server is MyDay's ONE door (SPEC-003 §1/§4): it turns an inbound // request into a dispatched module function, applying identity · session · role // and every cross-cutting concern. The door RESOLVES and GATES; a module never // sees a request it should not (D-002, D-039). // // The pipeline (SPEC-003 §4): // // 1. correlation id -> context + response header // 2. client IP -> from server.trusted_proxies (SET XFF, A6) // 3. security headers // 4. rate limit -> /{GUID}, /access, /setup (A3) // 5. routing.Dispatch -> the pure model (SPEC-002) // 6. the Kind switch -> Redirect · NotFound · Setup · Enroll · Route/Action // Route/Action under a GUID -> the identity/session/role gate: // session valid? (non-empty, not expired/revoked — A2) // session.user_id == the GUID's user? // role permits the function? // attach audit.Meta -> dispatch // // Spec: docs/specs/spec-003-core-door.md. package server import ( "errors" "log/slog" "net/http" "strconv" "strings" "time" "git.lohmar.co.uk/cclohmar/NextMyDay/internal/core/audit" "git.lohmar.co.uk/cclohmar/NextMyDay/internal/core/auth" "git.lohmar.co.uk/cclohmar/NextMyDay/internal/core/config" "git.lohmar.co.uk/cclohmar/NextMyDay/internal/core/httpx" "git.lohmar.co.uk/cclohmar/NextMyDay/internal/core/middleware" "git.lohmar.co.uk/cclohmar/NextMyDay/internal/core/routing" "git.lohmar.co.uk/cclohmar/NextMyDay/internal/core/users" ) // Deps assembles the door's dependencies. type Deps struct { // Config is the loaded configuration. Config *config.Config // Resolver answers the pure model's GUID question (SPEC-002 §3.1). Resolver routing.Resolver // Registry is the module + core-handler dispatch surface. Registry Registry // Sessions validates the session cookie. Sessions auth.Sessions // Identities resolves a GUID to a user (the door's own lookup, distinct // from the pure Resolver surface). Identities auth.Identities // Users loads the authenticated user's role for the role gate. Users users.Users // Audit receives the door's and the services' audit rows. Audit audit.Audit // CSRF verifies action requests (A8). CSRF *httpx.CSRF // PreSession verifies the anonymous enroll/login double-submit token // (A15). When nil the `auth` action module is unavailable (404). PreSession *httpx.PreSessionCSRF // TrustedProxies overrides the set parsed from Config.Server.TrustedProxies. TrustedProxies httpx.TrustedProxies // SetupMode reports whether the instance is in setup mode (D-025). When nil // it defaults to Config.Setup; the entrypoint widens it to "or no user // exists" (SPEC-005 §3). SetupMode func() bool // RoleGate enforces per-function authorisation. Defaults to // AllowAuthenticated. RoleGate RoleGate // Logger receives structured logs. Defaults to slog.Default(). Logger *slog.Logger // Now is the clock (tests). Defaults to time.Now. Now func() time.Time // RateLimit / RateWindow tune the auth-sensitive limiter (A3). RateLimit int RateWindow time.Duration } // Server is the door. type Server struct { cfg *config.Config disp *routing.Dispatcher reg Registry sessions auth.Sessions ids auth.Identities users users.Users audit audit.Audit csrf *httpx.CSRF precsrf *httpx.PreSessionCSRF trusted httpx.TrustedProxies setup func() bool roles RoleGate log *slog.Logger now func() time.Time limiter *middleware.RateLimiter } // New validates the dependencies and builds the door. func New(d Deps) (*Server, error) { if d.Config == nil { return nil, errors.New("server: Config is required") } if d.Resolver == nil { return nil, errors.New("server: Resolver is required") } if d.Registry == nil { return nil, errors.New("server: Registry is required") } if d.Sessions == nil { return nil, errors.New("server: Sessions is required") } if d.Identities == nil { return nil, errors.New("server: Identities is required") } if d.Users == nil { return nil, errors.New("server: Users is required") } if d.CSRF == nil { return nil, errors.New("server: CSRF is required") } trusted := d.TrustedProxies if trusted == nil { var err error trusted, err = httpx.ParseTrustedProxies(d.Config.Server.TrustedProxies) if err != nil { return nil, err } } setup := d.SetupMode if setup == nil { cfg := d.Config setup = func() bool { return cfg.Setup } } logger := d.Logger if logger == nil { logger = slog.Default() } clock := d.Now if clock == nil { clock = time.Now } roles := d.RoleGate if roles == nil { roles = AllowAuthenticated{} } return &Server{ cfg: d.Config, disp: routing.New(d.Resolver, d.Registry), reg: d.Registry, sessions: d.Sessions, ids: d.Identities, users: d.Users, audit: d.Audit, csrf: d.CSRF, precsrf: d.PreSession, trusted: trusted, setup: setup, roles: roles, log: logger, now: clock, limiter: middleware.NewRateLimiter(d.RateLimit, d.RateWindow), }, nil } // Handler wraps the door with the correlation-id middleware (SPEC-003 §4). func (s *Server) Handler() http.Handler { return middleware.CorrelationID(s) } // Serve binds listen and serves the door until it fails. Any address may be // bound — including `0.0.0.0:8080` behind a reverse proxy (D-025 revised, // D-043); the bootstrap is protected per request by the setup gate, not by a // bind check. func (s *Server) Serve(listen string) error { s.log.Info("myday: listening", "addr", listen, "setup_mode", s.setup()) srv := &http.Server{ Addr: listen, Handler: s.Handler(), ReadHeaderTimeout: 10 * time.Second, } return srv.ListenAndServe() } // ServeHTTP is the door pipeline (SPEC-003 §4). func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request) { start := s.now() // D-025 (revised): the setup gate must see the RAW X-Forwarded-For, before // step 2 below SETS it (A6). Capture the tunnel verdict now. setupTunnel := httpx.SetupRequestAllowed(r) ctx := r.Context() cid := middleware.CorrelationFrom(ctx) if cid == "" { cid = middleware.NewCorrelationID() ctx = middleware.WithCorrelation(ctx, cid) } w.Header().Set(middleware.CorrelationHeader, cid) // 2. client IP (SET XFF, never append — A6). ip := httpx.ClientIP(r, s.trusted) // The scheme is resolved per request (D-043): TLS, or a trusted proxy's // X-Forwarded-Proto. Every cookie writer reads it back off the context. secure := httpx.RequestIsHTTPS(r, s.trusted) ctx = httpx.WithSecure(ctx, secure) // 3. security headers. httpx.SetSecurityHeaders(w, secure) // The door attaches audit.Meta before any service call (R-1). The actor is // filled in once the identity gate resolves it. ctx = middleware.AttachAudit(ctx, 0, ip, cid) r = r.WithContext(ctx) sw := &statusWriter{ResponseWriter: w, status: http.StatusOK} var res routing.Resolution defer func() { s.log.Info("request", "correlation_id", cid, "method", r.Method, "path", httpx.RedactPath(r.URL.Path), "query", httpx.RedactQuery(r.URL.RawQuery), "client_ip", ip, "status", sw.status, "workflow", res.Workflow, "module", res.Module, "function", res.Function, "duration_ms", s.now().Sub(start).Milliseconds(), ) }() // 4. rate limit the auth-sensitive routes (A3, AC-9). if class := middleware.Class(r.URL.Path); class != "" { key := ip + "|" + class if !s.limiter.Allow(key) { if secs := s.limiter.RetryAfter(key); secs > 0 { sw.Header().Set("Retry-After", strconv.Itoa(secs)) } s.writeError(sw, http.StatusTooManyRequests, "too many requests") return } } // 5. the pure model. res = s.disp.Dispatch(r.URL.Path, r.FormValue("do"), r.FormValue("action")) // 6. the Kind switch. s.dispatch(sw, r, res, cid, ip, setupTunnel) } // dispatch is the Kind switch (SPEC-003 §4 step 5). func (s *Server) dispatch(w http.ResponseWriter, r *http.Request, res routing.Resolution, cid, ip string, setupTunnel bool) { // SPEC-003 §7 / D-025 (revised 2026-10-15) / A13: setup mode is // tunnel-only PER REQUEST. Serve only a request whose TCP peer is loopback // AND which carries no X-Forwarded-For — the direct SSH tunnel. A proxy on // the same host presents a loopback peer, so the ABSENCE of XFF is the // proof it did not traverse one. Anything else → 404 before dispatch; an // empty/unparseable peer fails closed. if s.setup() && !setupTunnel { s.log.Warn("setup request refused: not the direct tunnel", "correlation_id", cid, "client_ip", ip) s.writeError(w, http.StatusNotFound, "not found") return } // SPEC-005 §3: in setup mode the app serves ONLY /setup (+ static assets); // every other route is 404 (delete, don't redirect). Reserved names like // /home and /access are 404'd too — the bootstrap has no app yet. if s.setup() && !setupAllowed(res) { s.writeError(w, http.StatusNotFound, "not found") return } switch res.Kind { case routing.KindRedirect: // The ONE canonical redirect ("/" -> "/home"). http.Redirect(w, r, res.Redirect, http.StatusFound) case routing.KindNotFound: s.writeError(w, http.StatusNotFound, "not found") case routing.KindSetup: // /setup is served ONLY in setup mode; otherwise it 404s (delete, // don't redirect — SPEC-005 §5). if !s.setup() { s.writeError(w, http.StatusNotFound, "not found") return } s.serveCore(w, r, "setup", res, cid, ip) case routing.KindEnroll: // GUID found but not enrolled -> the enrollment screen (SPEC-006). s.serveCore(w, r, "enroll", res, cid, ip) case routing.KindLogin: s.serveCore(w, r, "login", res, cid, ip) case routing.KindRoute, routing.KindAction: // /setup is setup-mode-only through BOTH doors — a path request // classifies as KindSetup, but `do`/`action` under /setup classifies as // KindAction with Workflow "setup". Productive mode 404s either way // (delete, don't redirect — SPEC-005 §5). if res.Workflow == "setup" && !s.setup() { s.writeError(w, http.StatusNotFound, "not found") return } // SPEC-005: the wizard's steps are actions under the reserved `setup` // workflow. They run anonymously (pre-session CSRF, A15). if res.Kind == routing.KindAction && res.Workflow == "setup" { s.serveSetupAction(w, r, res, cid, ip) return } // M1c/L3s — pin the setup MODULE at the door: the wizard's functions are // reachable ONLY through the reserved `setup` workflow. Any other // resolution naming `do=setup` (a GUID path, a reserved workflow) is // invalid in every mode and 404s rather than falling through to the // module registry or the GUID door. if res.Module == setupModule { s.writeError(w, http.StatusNotFound, "not found") return } // SPEC-006: the `auth` module's actions are the enroll/login flows. // They run BEFORE the session gate (the whole point is to obtain a // session); logout is the exception and stays session-gated. if res.Kind == routing.KindAction && res.Module == authModule && !routing.IsReservedWorkflow(res.Workflow) { s.serveAuthAction(w, r, res, cid, ip) return } // SPEC-007: the anonymous /access recovery action — the recovery // request form (`do=auth`). It runs before any session (pre-session // CSRF, A15) and is always a generic response (A4). Only the `auth` // module is served here: the session-gated approve/deny actions must // ride a GUID path and are deliberately NOT reachable at /access. if res.Kind == routing.KindAction && res.Workflow == "access" && res.Module == authModule { s.serveAccessAction(w, r, res, cid, ip) return } // A reserved level-1 workflow (home · access · api · static · …) is // core-owned and needs no identity gate. if routing.IsReservedWorkflow(res.Workflow) { s.serveCore(w, r, res.Workflow, res, cid, ip) return } // Otherwise it is a GUID branch: the identity/session/role gate. s.serveGUID(w, r, res, cid, ip) default: s.writeError(w, http.StatusNotFound, "not found") } } // setupAllowed reports whether a Resolution is one of the only routes served // while in setup mode: the wizard itself (`/setup`, path or action) and static // assets (SPEC-005 §3). Everything else — including the canonical redirect and // every GUID branch — is 404. func setupAllowed(res routing.Resolution) bool { switch res.Kind { case routing.KindSetup: return true case routing.KindAction: return res.Workflow == "setup" case routing.KindRoute: return res.Workflow == "static" } return false } // serveCore hands off to a core-owned workflow handler. func (s *Server) serveCore(w http.ResponseWriter, r *http.Request, workflow string, res routing.Resolution, cid, ip string) { h, ok := s.reg.CoreHandler(workflow) if !ok { s.writeError(w, http.StatusNotFound, "not found") return } s.invoke(w, r, h, newRequestContext(res, 0, cid, ip)) } // serveAuthAction runs the anonymous enroll/login actions (SPEC-006 §4/§5). // It runs BEFORE the identity/session gate — the whole point is to obtain a // session — so it verifies the signed pre-session double-submit token (A15) // instead of the session-bound one. `logout` is session-gated (serveGUID). func (s *Server) serveAuthAction(w http.ResponseWriter, r *http.Request, res routing.Resolution, cid, ip string) { if s.precsrf == nil { s.writeError(w, http.StatusNotFound, "not found") return } // `logout` revokes an existing session, and the SPEC-006 §8 passkey-nudge // actions (passkey.add / passkey.later / passkey.never) require one — they // are session-gated (SPEC-003 §6 CSRF), NOT anonymous like the enroll/login // actions above. if res.Function == "logout" || strings.HasPrefix(res.Function, "passkey.") { s.serveGUID(w, r, res, cid, ip) return } if !s.precsrf.Valid(r, r.FormValue("csrf")) { s.writeError(w, http.StatusForbidden, "forbidden") return } h, ok := s.reg.Handler(res.Module, res.Function) if !ok { s.writeError(w, http.StatusNotFound, "not found") return } s.invoke(w, r, h, newRequestContext(res, 0, cid, ip)) } // serveSetupAction runs a SPEC-005 wizard step. The wizard is anonymous — no // session exists before the admin is created — so it verifies the signed // pre-session double-submit token (A15) rather than the session-bound CSRF. The // door has already gated this to setup mode. func (s *Server) serveSetupAction(w http.ResponseWriter, r *http.Request, res routing.Resolution, cid, ip string) { if !s.setup() { s.writeError(w, http.StatusNotFound, "not found") return } // M1c: the door pins the action door to the `setup` module. Without this a // `do=core&action=modules.toggle` under /setup would reach a core action // that the session-gated role gate (admin-only) would otherwise protect. if res.Module != setupModule { s.writeError(w, http.StatusNotFound, "not found") return } if s.precsrf == nil { s.writeError(w, http.StatusNotFound, "not found") return } if !s.precsrf.Valid(r, r.FormValue("csrf")) { s.writeError(w, http.StatusForbidden, "forbidden") return } h, ok := s.reg.Handler(res.Module, res.Function) if !ok { s.writeError(w, http.StatusNotFound, "not found") return } s.invoke(w, r, h, newRequestContext(res, 0, cid, ip)) } // serveAccessAction runs a SPEC-007 /access action. The recovery entry is // anonymous — no session exists yet — so it verifies the signed pre-session // double-submit token (A15) rather than the session-bound CSRF (§6). The // response is generic whatever the email matches (AC-4). func (s *Server) serveAccessAction(w http.ResponseWriter, r *http.Request, res routing.Resolution, cid, ip string) { if s.precsrf == nil { s.writeError(w, http.StatusNotFound, "not found") return } if !s.precsrf.Valid(r, r.FormValue("csrf")) { s.writeError(w, http.StatusForbidden, "forbidden") return } h, ok := s.reg.Handler(res.Module, res.Function) if !ok { s.writeError(w, http.StatusNotFound, "not found") return } s.invoke(w, r, h, newRequestContext(res, 0, cid, ip)) } // serveGUID runs the identity/session/role gate, then dispatches to the module // function (SPEC-003 §4 step 5). func (s *Server) serveGUID(w http.ResponseWriter, r *http.Request, res routing.Resolution, cid, ip string) { ctx := r.Context() // (a) load the session cookie; an absent or empty id is rejected (A2). // Over https the cookie name carries the `__Host-` prefix (L1s/D-043). secure := httpx.SecureFromRequest(r) cookieName := httpx.SessionCookieNameFor(secure) cookie, err := r.Cookie(cookieName) if err != nil || cookie.Value == "" { s.loginRequired(w, r, res, cid, ip) return } // Validate: exists · not expired · not revoked · non-empty (A2/AC-5). sess, err := s.sessions.Validate(ctx, cookie.Value) if err != nil { httpx.ClearSessionCookie(w, cookieName, secure) s.loginRequired(w, r, res, cid, ip) return } // Resolve the GUID's user and require an ACTIVE identity. idn, err := s.ids.ByGUID(ctx, res.Workflow) if err != nil || idn.Status != auth.StatusActive { s.writeError(w, http.StatusNotFound, "not found") return } // (b) the identity match: the session must belong to the GUID's user // (AC-4). The rejection is generic — no oracle about the session's owner. if sess.UserID != idn.UserID { s.loginRequired(w, r, res, cid, ip) return } // (d) the role gate. u, err := s.users.Get(ctx, sess.UserID) if err != nil { s.writeError(w, http.StatusNotFound, "not found") return } if !s.roles.Allowed(u.Role, res.Module, res.Function) { s.writeError(w, http.StatusForbidden, "forbidden") return } // Attach the actor now that the identity is known (R-1). ctx = middleware.AttachAudit(ctx, sess.UserID, ip, cid) // CSRF on every action (A8/AC-6). The routing fields are not a control. if res.Kind == routing.KindAction { if !s.csrf.Valid(sess.ID, r.FormValue("csrf")) { s.writeError(w, http.StatusForbidden, "invalid csrf token") return } } // (e) build the RequestContext and dispatch. h, ok := s.reg.Handler(res.Module, res.Function) if !ok { s.writeError(w, http.StatusNotFound, "not found") return } ctx = httpx.WithToken(ctx, s.csrf.Token(sess.ID)) r = r.WithContext(ctx) s.invoke(w, r, h, newRequestContext(res, sess.UserID, cid, ip)) } // loginRequired hands off to the login screen without revealing why the session // was rejected (missing, empty, invalid, or belonging to another user). The // screen is a RENDERED PAGE and answers 200; only a failed credential attempt is // 401/400 (F-1). The 401 below is a degenerate fallback for a registry that // carries no login screen at all. func (s *Server) loginRequired(w http.ResponseWriter, r *http.Request, res routing.Resolution, cid, ip string) { h, ok := s.reg.CoreHandler("login") if !ok { s.writeError(w, http.StatusUnauthorized, "login required") return } s.invoke(w, r, h, newRequestContext(res, 0, cid, ip)) } // invoke calls a handler and maps a returned error to a 500 (logged). func (s *Server) invoke(w http.ResponseWriter, r *http.Request, h Handler, rc *RequestContext) { if err := h(w, r, rc); err != nil { s.log.Error("handler error", "correlation_id", rc.Correlation, "workflow", rc.Workflow, "function", rc.Function, "error", err, ) s.writeError(w, http.StatusInternalServerError, "internal error") } } // writeError writes a terse plain-text error response. func (s *Server) writeError(w http.ResponseWriter, status int, msg string) { w.Header().Set("Content-Type", "text/plain; charset=utf-8") w.Header().Set("X-Content-Type-Options", "nosniff") w.WriteHeader(status) _, _ = w.Write([]byte(msg + "\n")) } // statusWriter captures the response status for the access log. type statusWriter struct { http.ResponseWriter status int wrote bool } func (w *statusWriter) WriteHeader(code int) { if w.wrote { return } w.status = code w.wrote = true w.ResponseWriter.WriteHeader(code) } func (w *statusWriter) Write(b []byte) (int, error) { if !w.wrote { w.WriteHeader(http.StatusOK) } return w.ResponseWriter.Write(b) } var _ http.Handler = (*Server)(nil)