2 Commits

Author	SHA1	Message	Date
shankar0123	17b30c1f7f	auth-bundle-2 Phase 4: session service (cookie minting + signature ... validation, idle/absolute expiry, signing-key rotation, CSRF, GC), 15-case negative-test matrix, fail-fatal initial-key bootstrap Phase 4 of the bundle ships the post-login session lifecycle that backs every authenticated request once Phase 5 wires the OIDC handlers + the session middleware. The state machine is the load-bearing primitive for the Bundle 2 control plane: forge a session cookie and you bypass every RBAC gate. Service surface (internal/auth/session/service.go, ~880 LOC): - Service.Create(actorID, actorType, ip, ua) -> *CreateResult Mints a session row; signs the cookie value with the active signing key; returns the cookie payload AND the CSRF token plaintext for the handler to set on the response. - Service.Validate(ValidateInput) -> *Session Parses the cookie, looks up the signing key (incl. retired-but-in- retention), recomputes HMAC-SHA256, loads the session row, enforces revocation + absolute + idle expiry + optional IP/UA bind. Maps to one of 9 sentinel errors; the handler uniformly returns 401 to the wire (specific reason in the audit row). - Service.ValidateCSRF(headerValue, *Session) error Constant-time compares SHA-256(header) against the stored hash on the session row. - Service.UpdateLastSeen / Revoke / RevokeAllForActor - Service.RotateCSRFToken — mints fresh token, persists hash, returns plaintext; called on login completion, logout, role-change against actor, explicit operator rotate. - Service.RotateSigningKey — mints new active key, retires previous; retired keys stay valid for cfg.SigningKeyRetention so existing cookies don't immediately fail. - Service.EnsureInitialSigningKey — idempotent; mints first key on fresh deploys; emits auth.session_signing_key_bootstrap audit row with event_category=auth. Wired into cmd/server/main.go AFTER migrations + RBAC backfill, BEFORE the HTTP listener binds; failure is FATAL (logger.Error + os.Exit(1)) per the prompt — server refuses to boot rather than serve session-less. - Service.GarbageCollect — sweeps expired post-login sessions + pre-login rows >10min + retired-past-retention signing keys. Wired into the new internal/scheduler/scheduler.go::sessionGCLoop on a CERTCTL_SESSION_GC_INTERVAL tick. Cookie wire format (load-bearing): v1.<session_id>.<signing_key_id>.<base64url-no-pad(HMAC-SHA256)> The HMAC input is LENGTH-PREFIXED to defeat concatenation collisions: len(session_id) || ":" || session_id || ":" || len(signing_key_id) || ":" || signing_key_id where len(...) is the ASCII decimal byte-length. Without the length prefix, the bare-concatenation form `session_id || signing_key_id` would let a forger swap one byte across the boundary — `<a, bc>` and `<ab, c>` produce identical HMAC inputs. The length prefix moves the boundary into the input itself so the two cases can never collide. The v1. version prefix is reserved. A future incompatible upgrade ships as v2. and the parser rejects unknown prefixes (no fallback). CSRF token model: - Plaintext goes in a JS-readable certctl_csrf cookie (HttpOnly=false intentional; the GUI must read it to echo into X-CSRF-Token header). - SHA-256 hash of the plaintext lives on the session row. - Validation: SHA-256(X-CSRF-Token) constant-time-compared. - Rotated by Service.RotateCSRFToken on login / logout / role-change / explicit admin-trigger. Optional defense-in-depth (default OFF): - CERTCTL_SESSION_BIND_IP — Validate compares client IP to row's recorded IP. Mismatch -> 401, audit row, session NOT auto-revoked (user may have legitimate IP change). Mobile + corporate-NAT environments leave this off. - CERTCTL_SESSION_BIND_USER_AGENT — same shape against UA. Configurable lifetimes (env vars wired in internal/config/config.go): CERTCTL_SESSION_IDLE_TIMEOUT 1h CERTCTL_SESSION_ABSOLUTE_TIMEOUT 8h CERTCTL_SESSION_SIGNING_KEY_RETENTION 24h CERTCTL_SESSION_GC_INTERVAL 1h CERTCTL_SESSION_SAMESITE Lax CERTCTL_SESSION_BIND_IP false CERTCTL_SESSION_BIND_USER_AGENT false Test surface (internal/auth/session/service_test.go, ~860 LOC): All 15 prompt-mandated negative cases: 1. Tampered cookie (HMAC byte flipped near segment start where all 6 bits are real — base64url-no-pad's last char carries only 2 bits so a tail-flip is unreliable). 1b. Tampered SESSION_ID segment (same HMAC-recompute outcome). 2. Cookie missing v1. prefix. 3. Cookie with unknown version prefix (v99). 4. Idle expiry — back-dated last_seen_at + idle_expires_at. 5. Absolute expiry — back-dated absolute_expires_at. 6. Revoked session. 7. Wrong signing key id (no row matches). 8. Cookie signed under retired-but-in-retention key SUCCEEDS. 9. Cookie signed under retired-past-retention key FAILS. 10. Concatenation collision — direct evidence that computeHMAC("abc","de") != computeHMAC("ab","cde") AND that a forged-boundary-slide cookie is rejected. 11. CSRF token missing. 12. CSRF token mismatch (constant-time compare). 13. IP-bind enabled + IP changed -> ErrSessionIPMismatch + audit row. 14. UA-bind enabled + UA changed -> ErrSessionUAMismatch + audit row. 15. EnsureInitialSigningKey RNG failure -> ErrInitialSigningKeyMintFailed wrap (cmd/server/main.go treats as fatal). Plus coverage-lift batch covering: every error wrap on every repo collaborator (Create, Get, UpdateLastSeen, UpdateCSRFTokenHash, Revoke, RevokeAllForActor, GC), every RNG-failure surface in Create / RotateCSRFToken / RotateSigningKey, every alg-pinning helper edge, the cookie parser's full negative matrix (empty, wrong segment count, missing prefixes, bad base64, wrong HMAC length), and a real-encryption round-trip via internal/crypto.EncryptIfKeySet -> DecryptIfKeySet so the v3-blob path is exercised end-to-end at the session-cookie level. Coverage: internal/auth/session 94.5% (floor 90) internal/auth/session/domain 96+% (floor 90, Phase 1) .github/coverage-thresholds.yml extended with 2 new gate entries (internal/auth/session and internal/auth/session/domain). The why: paragraphs explain why each fail-closed branch is load-bearing. Repository extensions: internal/repository/session.go gains UpdateCSRFTokenHash on the SessionRepository interface; internal/repository/postgres/session.go ships the implementation. RotateCSRFToken consumes it. Scheduler extensions: internal/scheduler/scheduler.go gains SessionGarbageCollector interface + sessionGC field + sessionGCInterval + SetSessionGarbageCollector + SetSessionGCInterval + sessionGCLoop. Pattern matches the existing acmeGCLoop: atomic.Bool guard prevents concurrent sweeps, sync.WaitGroup tracks for graceful shutdown, per-tick context.WithTimeout(1m) bounds a stuck Postgres. Server wiring: cmd/server/main.go constructs sessionService AFTER the bootstrap block (post-RBAC backfill) and BEFORE the policy-service block. EnsureInitialSigningKey runs immediately; failure is fatal via os.Exit(1). The scheduler section wires SetSessionGarbageCollector + SetSessionGCInterval alongside the other interval setters and emits an Info log so operators can confirm the loop is enabled. Phase 4 deviation note: Service.GarbageCollect() returns (int, error) rather than the prompt's literal `error`. The int is the count of session rows deleted on this sweep; the scheduler discards it (`_, err := ...`) but tests + future operator-facing audit rows can read it. The wider behavior matches the spec exactly. Verifications: gofmt clean, go vet ./internal/auth/session/... ./internal/scheduler/... ./internal/config/... ./cmd/server/... ./internal/repository/... clean, go test -short -count=1 -race green across all 3 session packages, full repository + auth + scheduler + config test sweeps green, no regressions in Bundle 1 packages.	2026-05-10 05:31:24 +00:00
shankar0123	b0ac24fbf8	auth-bundle-2 Phase 1: OIDC + Session + User + Breakglass domain types ... Phase 1 ships the persisted-shape types Bundle 2 needs end-to-end. No DB migrations, no service layer, no HTTP handlers; Phase 2 ships the SQL, Phase 3+ ship the consumers. Each type has a Validate() method that enforces the on-disk invariants the schema will mirror, and a focused _test.go that pins each invariant's failure mode. Per-package summary: internal/auth/oidc/domain/ (OIDCProvider + GroupRoleMapping): * OIDCProvider carries the operator-configured IdP record. Fields match the prompt's Phase 1 list plus IATWindowSeconds and JWKSCacheTTLSeconds (Phase 3 references these by name; landing them in Phase 1's domain type avoids the lying-field gap). ClientSecretEncrypted is opaque from this layer; it is the v2 blob produced by internal/crypto/encryption.go and is `json:"-"` so it never wire-leaks. * Validate() rejects: invalid id prefix, empty name, non-https issuer_url (matches Phase 3's "JWKS endpoint MUST be HTTPS"), empty client_id, empty client_secret_encrypted, non-https redirect_uri, invalid groups_claim_format, scopes missing openid, IAT window outside (0, 600], JWKS cache TTL below 60s. Defaults applied in-place: GroupsClaimPath="groups", GroupsClaimFormat= "string-array", Scopes=["openid","profile","email"], IATWindowSeconds=300, JWKSCacheTTLSeconds=3600, TenantID="t-default". * GroupRoleMapping carries the operator-configured group-to-role rule. Validate() pins prefix conventions ("grm-", "op-", "r-") and non-empty group name. * 18 tests across happy-path + every negative invariant. internal/auth/session/domain/ (Session + SessionSigningKey): * Session covers BOTH the post-login row (full 1h-idle/8h-absolute cookie lifecycle) AND the Phase 5 pre-login row (10-minute TTL, carries OIDC state+nonce+PKCE verifier across the IdP redirect). IsPreLogin discriminates. CSRFTokenHash holds SHA-256 of the CSRF token plaintext (the plaintext lives in a JS-readable certctl_csrf cookie; storing only the hash on the row defends against DB-read leaks per the Phase 4 CSRF contract). * Validate() pins: id prefix "ses-", non-empty actor id/type, signing key id prefix "sk-", AbsoluteExpiresAt strictly > Idle, IdleExpiresAt strictly > CreatedAt, CSRFTokenHash exactly 64 lowercase hex chars when set. * Cookie naming constants pinned by a separate test (TestCookieNamingConstants) so a future rename can't silently break the GUI's web/src/api/client.ts which reads these names by string. * SessionSigningKey stores the v2-encrypted HMAC key material; the retired-before-created invariant catches malformed rows. 14 tests across both types. internal/auth/user/domain/ (User): * Federated-human identity for SSO logins. Distinct from Bundle 1's free-form actor_id strings: actor_roles.actor_id = User.ID for federated humans (per the prompt's note about how the two identity systems intersect). * WebAuthnCredentials JSONB column reserved for v3 (Decision 12); defaults to "[]" on Validate() so Bundle 2 + v3 share the same on-disk format from day one. * Email validation is intentionally loose (basic shape: one @, non-empty local + domain, no whitespace, dot in domain). RFC 5321 / 5322 grammars are not enforced; the IdP issued the email and we trust its shape, only rejecting gross corruption. * 8 tests across happy-path + invalid-id + empty-email + malformed-email + invalid-provider-id + tenant defaulting + WebAuthn-credentials passthrough. internal/auth/breakglass/domain/ (BreakglassCredential): * Phase 7.5 type. Argon2id PHC-format password hash; Validate() pins the Argon2id magic prefix so non-Argon2id formats (bcrypt, pbkdf2, plaintext) are rejected at the persistence boundary. * MinPasswordLengthBytes (12) + MaxPasswordLengthBytes (256) constants pinned by a dedicated test so the operator-facing password-strength contract can't drift silently. * IsLocked(now) helper exposes the lockout state machine for the Phase 7.5 service to consume; the lockout window default is 15min in the service layer. * 9 tests across happy-path + per-invariant negative + lockout state machine + tenant defaulting. Cross-cutting: * Every type has json:"-" on the encrypted-credential field (ClientSecretEncrypted, KeyMaterialEncrypted, PasswordHash, CSRFTokenHash) so even a misconfigured handler that marshals the domain type directly into a response body cannot leak the secret. Mirrors Bundle 1's pattern for issuer/target credentials. * Every type carries TenantID with Validate() defaulting to authdomain.DefaultTenantID. Forward-compat for the future managed-service multi-tenant activation; Bundle 2 ships single-tenant. Verifications: * gofmt -l clean across all 8 new files (one round-trip required to satisfy Go 1.19+ doc-comment list-formatting rules in session/domain/types.go). * go vet clean on internal/auth/oidc/... + session/... + user/... + breakglass/... * go test -short -count=1 green on all four new domain packages (49 test functions total). * go test -short -count=1 still green on Bundle 1 packages (internal/auth, internal/auth/bootstrap, internal/service/auth, internal/config). * govulncheck ./... clean (M-024 hard CI gate). * All 24 ci-guards pass locally. Phase 1 exit criteria from cowork/auth-bundle-2-prompt.md: * All types compile: yes. * Validators have at least 5 test cases each: yes (smallest is User with 8 tests; OIDCProvider has 13). * make verify equivalent green: gofmt + vet + go test pass (golangci-lint deferred to CI per the same operating-rule pattern Phase 0 used).	2026-05-10 03:41:46 +00:00