3 Commits

Author	SHA1	Message	Date
shankar0123	5e2accbf5f	auth-bundle-2 Phase 12: extend auth-threat-model.md with Bundle 2 sections (OIDC + sessions + back-channel logout + OIDC first-admin + break-glass + 8 Bundle 2 threat sub-sections) ... Closes Phase 12 of cowork/auth-bundle-2-prompt.md. The single canonical operator-facing threat model (one doc per topic per the docs convention) now covers both Bundle 1 (RBAC) AND Bundle 2 (OIDC + sessions + back-channel logout + OIDC first-admin + break-glass) in one place. File: docs/operator/auth-threat-model.md (MODIFIED, +485 LOC) Conventions held ================ * The Bundle 1 sections ("Threat actors", "Defenses Bundle 1 ships", "Threats Bundle 1 does NOT close", "Compliance mapping", "Operator-facing checks", "Cross-references") stay structurally intact. Bundle 2 EXTENDS them; nothing is rewritten in place. * `Last reviewed:` header bumped 2026-05-09 → 2026-05-10. * Per the prompt's explicit instruction: "do NOT create a separate auth-threat-model-bundle-2.md companion." This commit is a single-file extension. Changes ======= Intro paragraph rewritten: * From "Bundle 1 lands... Bundle 2 will be updated" to "Bundle 1 AND Bundle 2 land." Sets the reader's expectation that this is the post-Bundle-2 doc. Threat actors section (4 new actors appended): * OIDC-federated end user (token-forgery / session-hijacking / group-claim-manipulation surface). * Stolen session cookie holder (XSS / network MITM / pasted-token). * Compromised IdP (rogue token issuance; mitigations bounded to audit trail + group-mapping configuration). * Break-glass-password holder (Phase 7.5 path bypasses OIDC + group layer entirely; default-OFF is the load-bearing mitigation). NEW: Defenses Bundle 2 ships (5 sub-sections): * OIDC token validation (Phase 3) — alg allow-list, IdP-downgrade defense, exact iss match, aud + azp checks, at_hash REQUIRED-when-access_token-present (Phase 3 tightening of OIDC core's MAY → MUST), single-use state + nonce, PKCE-S256 mandatory, iat window, JWKS rotation handling, JWKS-fetch-fail closed, encrypted client_secret at rest. * Session minting + cookies (Phases 4 + 6) — length-prefixed HMAC defeating concatenation collision, HttpOnly + Secure + SameSite cookie hardening, idle + absolute timeouts, CSRF defense via double-submit-cookie + hashed-token-on-row, optional IP/UA bind, signing-key rotation primitive with retention window, fail-fatal EnsureInitialSigningKey at boot, pre-login vs post-login cookie discrimination. * Back-channel logout (Phase 5) — OpenID Connect Back-Channel Logout 1.0 (NOT RFC 8414), required-claim pinning, jti-based replay defense, alg allow-list applies, Cache-Control: no-store. * OIDC first-admin bootstrap (Phase 7) — coexists with Bundle 1's env-var-token bootstrap, group-scoped, one-shot per tenant via admin-existence probe, explicit OIDC provider gate, audit row on every grant. * Break-glass admin (Phase 7.5) — default-OFF, surface-invisibility via 404-not-403, Argon2id with OWASP 2024 params, lockout state machine, constant-time across all failure paths via verifyDummy, WARN log at boot when ENABLED=true, 5/min rate limit on the public login endpoint. NEW: Bundle 2 threat catalogue (8 sub-sections, one per prompt-enumerated threat axis): 1. OIDC token forgery vectors and mitigations (9-row table covering alg confusion, audience injection, issuer mismatch, nonce replay, state replay, at_hash substitution, iat window manipulation, JWKS rotation mid-login, JWKS-fetch failure during a key rotation). 2. Session hijacking vectors and mitigations (7-row table covering XSS cookie theft, network MITM, CSRF, concatenation-collision forgery, stolen-cookie replay, cross-tab interference, sign-out race). 3. IdP compromise scenarios (operator monitors IdP audit logs, operator can rotate group-role mappings without redeploying, audit trail records source provider, provider-delete returns 409 with active sessions). 4. Back-channel logout failure modes (6-row table covering IdP unreachable, invalid signature, replay via jti, alg confusion, missing events claim, present-nonce-claim). 5. Group-claim manipulation (4-row table covering operator misconfigured mapping, misconfigured groups_claim_path, IdP renames a group, IdP user maintainer adds user to unintended group). 6. Bootstrap phase risks post-Bundle-2 (4-row table covering CERTCTL_BOOTSTRAP_TOKEN leak, CERTCTL_BOOTSTRAP_ADMIN_GROUPS misconfigured to a wide group, both bootstrap strategies simultaneously, multi-IdP without explicit provider gate). 7. Break-glass risks (7-row table covering phished password, online brute-force, offline brute-force on DB compromise, operator forgets to disable, side-channel timing on wrong-vs-no-credential-vs-locked, surface fingerprinting, reserved-actor mutation). 8. Token-leak hygiene (the explicit grep policy with three per-package logging_test.go pointers + the audit_redact.go defense-in-depth note). Threats Bundle 1 does NOT close section relabeled: * Section header now reads "Threats Bundle 1 does NOT close (Bundle 2 closure status)" with each item carrying ✅ / ⚠️ / "still deferred" markers. * Items 1, 2, 3, 8 marked ✅ closed by Bundle 2. * Items 4, 5, 7, 9 marked still-deferred with v3 / follow-on pointers. * Item 6 (rate limiting on bootstrap) marked acceptable; Bundle 2 adds the same rate-limit primitive to /auth/breakglass/login. NEW: Threats Bundle 2 does NOT close section listing the 8 v3 / future-work items: * WebAuthn / FIDO2 second factor (Decision 12). * Time-bound role grants / JIT elevation. * SAML federation (operators broker through Keycloak). * Multi-tenant data isolation activation (gated to managed-service hosting work). * HSM / FIPS-validated signing key for sessions. * OIDC RP-initiated logout (Bundle 2 implements only back-channel). * GUI E2E via Playwright. * Per-IdP runbook external-tester sign-off (encouraged, NOT a merge gate post-2026-05-10 policy change). Operator-facing checks section extended: * 6 new SQL-shaped checks for Bundle 2 (provider count drift, per-actor session count, unmapped-groups audit-row spike, break-glass usage outside incidents, OIDC first-admin one-row-per- tenant invariant, retired-signing-key GC liveness). Cross-references section split into Bundle 1 anchors + Bundle 2 anchors: * Bundle 2 anchors enumerate every load-bearing file: 6 internal/auth/ packages, 5 migrations, 3 ci-guards. Compliance mapping section UNCHANGED: * Phase 15 (standards-and-RFC-implementation table) is the proper home for the RFC + CWE evidence the Bundle 2 surface adds. Re-introducing framework-mapping prose at the threat-model layer would regress the operator's 2026-05-05 retired-compliance-docs decision, which is explicitly forbidden by the Phase 15 prompt. Verification ============ * `> Last reviewed: 2026-05-10` — confirmed via head -3. * All 8 prompt-mandated Bundle 2 threat sub-sections present — confirmed via grep `^### ` count (19 ### headers total: 6 Bundle 1 + 5 Bundle 2 defenses + 8 Bundle 2 threats). * All 39 prompt-listed threat-vector keywords present — confirmed via single-line grep counting 39 hits across the prompt's vocabulary. * Internal markdown links resolve cleanly — confirmed via shell loop iterating each `]( ...)` reference and checking `[ -e "$path" ]`. * No backend / Go-test impact — pure docs commit. * `make verify` gate unchanged.	2026-05-10 16:11:08 +00:00
shankar0123	5313cd8492	auth-bundle-1 Phase 13 follow-up: em-dash sweep + broken-link fix ... Self-audit on e7a94b6 flagged the prompt's 'zero em dashes' discipline rule. The four new Phase 13 docs and the v2.1.0 CHANGELOG section had 97 em-dash hits between them; this commit sweeps them all to ASCII hyphens. Counts before -> after: docs/operator/rbac.md 28 -> 0 docs/operator/auth-threat-model.md 36 -> 0 docs/migration/api-keys-to-rbac.md 16 -> 0 docs/operator/security.md 8 -> 0 docs/reference/profiles.md 3 -> 0 CHANGELOG.md 6 -> 0 Mechanical: ' - ' (spaced em dash) and bare em-dash both replaced with spaced ASCII hyphen, then double-spaces collapsed. Markdown list bullets ('^- ', '^ - ', '^ - ') verified intact across all six files. Internal-link sweep also re-run. Also fixes a pre-existing broken link the audit caught: docs/operator/security.md:70 referenced '../internal/crypto/encryption.go' which is a 1-level-up jump from docs/operator/, not the 2-level-up jump it actually needs ('../../internal/crypto/encryption.go'). Pre-Bundle-1 link rot; fixed in lockstep so the merge gate's docs validation passes cleanly. Final state across the Phase-13 docs + CHANGELOG: - 0 em dashes - 0 broken internal links - Last-reviewed: 2026-05-09 header on every new doc Bundle 1 documentation is now ready for the operator-side merge gate review.	2026-05-10 00:15:30 +00:00
shankar0123	e7a94b6080	auth-bundle-1 Phase 13: docs (rbac.md + threat model + migration guide + security.md update) ... Closes the last Phase before the Bundle 1 Exit gate. Operators now have authoritative reference + threat model + migration guide covering every behavior change Bundles 0-12 introduced. # New docs * docs/operator/rbac.md (340 lines) — operator how-to: - Mental model (actors / roles / permissions / scopes) - 7 default roles seeded by migration 000029 + the 5 admin-only fine-grained perms seeded by 000030 - Permission catalogue table by namespace - Scope semantics (global beats specific) + the Bundle-2 deferral on scope_id FK enforcement - Granting / revoking access from GUI + CLI + HTTP API + MCP - The auditor pattern (audit-only, no resource read) - Day-0 bootstrap flow (CERTCTL_BOOTSTRAP_TOKEN → curl → HTTP 410 thereafter) - Demo-mode (CERTCTL_AUTH_TYPE=none) caveat for production * docs/operator/auth-threat-model.md (180 lines) — what the controls defend against: - 5 threat actors (external, wrong-role, compromised key, insider operator, compromised auditor) - Per-defense walk-through (API-key auth, RBAC, bootstrap, approval workflow + Phase 9 closure, audit trail, protocol-endpoint allowlist) - 9 explicit deferrals (OIDC, sessions, local accounts, JIT elevation, MFA, etc.) — Bundle 2 / future scope - Compliance mapping (SOC 2 CC6.1/CC6.3, HIPAA §164.312(b), NIST SSDF PO.5.2, FedRAMP AU-9, PCI-DSS §10) - 5 operator-runnable sanity checks (e.g., 'SELECT FROM audit_events WHERE actor=system-bypass' MUST return 0 in production) * docs/migration/api-keys-to-rbac.md (200 lines) — v2.0.x → v2.1.0 upgrade flow: - The SECURITY: AUDIT YOUR API KEYS callout - Migration list (000029-000033) + what each does - 4-mode scope-down flow (interactive / non-interactive JSON / --suggest / --suggest --apply) - What changes for code that called auth.IsAdmin - Helm-specific upgrade flow with example post-upgrade Job - Docker Compose upgrade flow + the 5 examples folders that ride demo mode unchanged - Verification queries + rollback flow # Updated docs * docs/operator/security.md — Last-reviewed bumped to 2026-05-09; existing Authentication-surface section extended to call out the Bundle 1 RBAC primitive, day-0 bootstrap path, and approval-bypass closure with cross-references to the new docs. * docs/reference/profiles.md — Last-reviewed header formatting fixed (added the > blockquote prefix used consistently across the docs tree). # docs/README.md navigation * Operator section gains 2 new rows (RBAC + auth-threat-model) and Approval-workflow row updated to mention Phase 9 closure. * Reference section gains the Profiles row. * Migration section gains the api-keys-to-rbac row with the AUDIT YOUR API KEYS callout in the link description. # CHANGELOG.md v2.1.0 section refreshed The Phase 7 commit landed the SECURITY: AUDIT YOUR API KEYS callout. This commit appends the missing Phase 9-12 highlights: - Approval-bypass closure (profile-edit gate + flip-flop loophole + ErrApproveBySameActor invariant) - GUI: Roles / API Keys / Auth Settings / Approvals queue - 12 new MCP RBAC tools - Coverage gates on internal/auth + internal/service/auth - Protocol-endpoint allowlist pinned at 3 layers Trailing cross-reference block now points at all 4 new docs. # Verifications * Every internal link in the 4 new/modified docs validated by shell sweep (find broken links → 0 hits). * Every new doc carries 'Last reviewed: 2026-05-09' header with the > blockquote prefix matching the docs-tree convention. * go vet ./... clean. * staticcheck across every Bundle-1-touched Go package clean. * gofmt -l clean repo-wide. * go test -short -count=1 green across internal/auth (incl. bootstrap), internal/api/handler, internal/api/router, internal/cli, internal/service (incl. auth), internal/domain/auth, internal/mcp, cmd/cli (cmd/server has 1 environmental failure on the sandbox virtiofs-tmp: TestPreflightSCEPRACertKey_KeyWorldReadable_Refuses depends on tmpfs file-mode semantics that virtiofs propagates differently — pre-existing, unrelated to Bundle 1). * Frontend: 19 Vitest tests across src/pages/auth/ + AuditPage all pass; tsc --noEmit clean.	2026-05-10 00:10:15 +00:00