DevNullLtd/Yuzu / .claude/skills/auth-and-authz
auth-and-authz
UnverifiedAuthentication & Authorisation control plane for Yuzu — the canonical entry point for any work on RBAC, OIDC SSO, SAML, SCIM, MFA/TOTP, AD/Entra integration, API tokens, session lifecycle, enrollment, and the audit/evidence chain. Use when the user says "/auth-and-authz", "/auth", "/iam", asks to plan or implement an enterprise A&A feature, asks "what's our auth gap to enterprise readiness", asks to audit current auth state against SOC 2 CC6.x / Workstream B, or starts work that touches `auth_*`, `rbac_*`, `oidc_*`, `api_token_*`, `enrollment_*`, or `cert_store.*`. The skill bundles current-state inventory, required-features inventory, gap matrix, the canonical workflow for adding a new A&A feature, and the load order for the routed reference docs.
Authentication & Authorisation skill
The single entry point for any A&A work in Yuzu. Bundles three things:
- Current state — what's shipped today and where it lives.
- Required state — the enterprise/SOC 2 feature set we owe customers.
- Gap matrix + workflow — what's missing and the standard procedure for closing a gap.
This skill does NOT replace the routed docs or specialist agents. It tells you which to load, in which order, and what questions to ask before you start cutting code.
Usage
/auth-and-authz # default: print gap matrix + suggested next gaps
/auth-and-authz audit # produce a compliance-ready snapshot of A&A state
/auth-and-authz plan <feature> # plan-only walk-through for a single feature (e.g. SAML, SCIM, TOTP)
/auth-and-authz implement <feature> # full workflow: plan → governance → implement → test → docs
If the user invokes the skill without a subcommand, default to printing the gap matrix (Section 3) and asking which gap they want to work on.
1. Current state — what's shipped
Authoritative reference: docs/auth-architecture.md. Read it before this
skill claims anything is "done."
Shipped capabilities
| Capability | Status | Source of truth |
|---|---|---|
| Local password auth (PBKDF2-SHA256) | Shipped (v0.10) | auth.cpp:69 pbkdf2_sha256() (OpenSSL PKCS5_PBKDF2_HMAC + BCrypt path) |
Persistent auth store — Postgres, schema auth (SQLite auth.db retired) | Shipped (v0.12 SQLite → migrated to PG, ADR-0006) | auth_db.cpp born-on-Postgres AuthDB(pg::PgPool&, pg::SecretCodec&), pg::PgMigrationRunner::run(lease, "auth", …); mfa_totp_secret is a SecretCodec envelope column (ADR-0010 first consumer); agent-doc .claude/agents/authdb.md |
| Session-cookie auth (HTMX dashboard) | Shipped | auth_routes.cpp:43,386 (extract_session_cookie, Set-Cookie: yuzu_session=…) |
Durable operator sessions — Postgres SessionStore (HA WS-1/1a, ADR-2002 §4) | Shipped | session_store.{hpp,cpp} (schema-migrated PG store, authoritative); AuthManager write-through with the in-memory sessions_ map as a generation-gated validate cache; DB-clock authority (#3715) — durable timestamps authored from Postgres now(), adjudicated on a local monotonic steady_clock deadline via derive_session_deadlines. A session survives replica restart/failover and validates identically on any replica. |
API tokens — Bearer + X-Yuzu-Token | Shipped | api_token_store.cpp (store); both header forms parsed at auth_routes.cpp:108-119 |
| Owner-scoped token revocation (#222) | Shipped | rest_api_v1.cpp:1058-1082 (owner-vs-admin check at L1060) |
Granular RBAC — 8 roles (adds Reviewer, access-review attestation, and ForensicsAnalyst, the read-only delegable Forensics tier, #4990) × 38 securable types × 8 ops (adds Attest, gated via the dedicated AccessReview securable — NOT AuditLog; the rationale lives in #2324, the access-reviews PR, not #2225, which is the governance-gate-check PR that ran alongside it — and Rotate, P2 #11 SOC 2 CC6.3, ApiToken-specific self-service human-token rotation, seeded only to Administrator/ApiTokenManager, deliberately distinct from Write) | Shipped (Phase 3 + P2 #11) | rbac_store.cpp's seed_defaults types array (std::array<std::string_view, 38>) — the A&A-program 23: Infrastructure, UserManagement, InstructionDefinition, InstructionSet, Execution, Schedule, Approval, Tag, AuditLog, Response, ManagementGroup, ApiToken, Security, Policy, DeviceToken, SoftwareDeployment, License, FileRetrieval, GuaranteedState, Inventory, AccessReview, SoftwareLicensing, EnginePrincipal (#2376 — cut away from the over-broad Security:Read); plus 15 landed via unrelated feature work, tracked here only so the count stays correct, not because they're A&A surface: PluginConfig/PluginSecret/UploadGrant (plugin config/secret/upload-grant plane, PR1.5/1.6), PowerManagement (Wave 6 W1B), Workflow/ProductPack/Directory (#4028-#4032 api-parity FK-seeding fixes — these three were already gating live routes via string comparison before being seeded here, so RBAC-enabled deployments silently couldn't grant them until the fix), TlsConfig/PluginSigning/ServerConfig/AnalyticsConfig (#4028 Settings-read-twins, split by sensitivity), Enrollment/OidcConfig (#4031 admin-only config reads), Forensics/Decommission (Wave 7 forensics class + ADR-0024 Decision 9 erasure gate); ops: Read/Write/Execute/Delete/Approve/Push/Attest/Rotate. Re-verify this count by grepping the array before quoting it — see the routed doc's own "line-number anchors decay faster than status" caution just below; the same caution applies to counts. |
| RBAC admin plane — turning enforcement on/off and assigning roles to human users. Partial: enable toggle + fleet-wide human role assignment shipped; custom-role CRUD, a config/CLI enable path and an SSO/break-glass path are NOT. RBAC still ships OFF and every fresh install is legacy-open until an operator flips it. | Enable toggle + assignment SHIPPED on dev 2026-09-25..27; custom-role CRUD MISSING — on dev only, not in release/v0.14.0-rc1, which predates all three PRs | A2 #4985 (09-26): POST/DELETE /api/v1/rbac/roles/{name}/assignments + MCP assign_rbac_role/unassign_rbac_role; gated on the shared durable-admin predicate is_rbac_administrator() (takes a required RbacAdminSurface{kRest,kMcp}; an MCP-tier bearer token is denied on REST), NOT require_permission; assignable roles are a closed list of 6 (rbac_assignable_roles.hpp: Administrator, PlatformEngineer, Operator, ApiTokenManager, Viewer, Reviewer — ITServiceOwner rejected, it needs a management-group scope this surface lacks; unassign is deliberately not so restricted); last-Administrator guard runs in the same txn as the DELETE, in RbacAdminAuthorityOwner (rbac_admin_authority_owner.{hpp,cpp}, the ADR-0012 §3 query owner). A1 #5030 (09-27): PUT /api/v1/rbac/enforcement + MCP set_rbac_enforcement (Security:Write, supervised tier, step-up on the REST route); caller-inclusive guard — refused unless the caller holds authority under BOTH the durably-true source regime (403) and the destination regime (409); new gauge/counter + YuzuRbacEnforcementChanged/YuzuRbacEnforcementDisabled alerts. A3 #4986 (09-25): the access-review export/campaign carries rbac_enforcement: enabled|disabled|degraded (degraded = closed/unwired store, so an outage is never read as "ungoverned"); the CSV gained a breaking leading # rbac_enforcement=<value> line. Still absent, verified 2026-09-28: RbacStore::create_role/set_permission/remove_permission have ZERO production callers (custom roles need direct psql against rbac_store; docs/user-manual/rbac.md "Custom Roles (Planned)"); no [rbac] config key or CLI flag (#388); only a LOCAL admin account can pass the enable guard, so an SSO-only fleet cannot enable RBAC; no break-glass if enabling strands the operator (#4203). RbacStore::set_rbac_enabled() still has no production caller — A1 goes through RbacAdminAuthorityOwner, so a grep for that name gives a false "no enable path". History: never a regression — RbacStore arrived in PR #203 (2026-03-18) with no wiring. Ref: docs/user-manual/rbac.md "Enabling RBAC", docs/adr/1008-rbac-management-groups-target-architecture.md |
| Self-target principal-destruction guard (#397/#403) | Shipped | settings_routes.cpp:434,1830,2488-2504 (3 call sites); design in docs/auth-architecture.md §self-target |
| OIDC SSO — full PKCE flow, Entra discovery, JWT validation | Shipped | oidc_provider.cpp:189 generate_code_verifier(), L194 compute_code_challenge(), L385 code_verifier post, L766 /.well-known/openid-configuration discovery, L542/L623 JWKS fetch + JWT signature verify |
| Directory Sync — AD/Entra users + groups + role mapping via Microsoft Graph v1.0 | Shipped | directory_sync.cpp:336,509,556,608 calls https://graph.microsoft.com/v1.0/users, /groups, /groups/{id}/members; persisted directory_group_role_mappings + directory_sync_status tables (directory_sync.cpp:147). NOTE: oidc_provider.cpp:248 only parses the JWT groups claim — Graph integration is the separate Directory Sync subsystem. |
| mTLS for agent ↔ server | Shipped | main.cpp:111 --ca-cert flag; peer-cert identity match in agent_service_impl.cpp:47,354 |
| Windows certificate-store mTLS (CryptoAPI/CNG) — agent-side only | Shipped | agents/core/src/cert_store.cpp:78,84,199-201 (CertOpenStore, NCrypt CNG export) |
| HTTPS-by-default, secure bind default (127.0.0.1) | Shipped (hard invariant) | main.cpp:100 127.0.0.1 default, L216 --no-https opt-out; design in docs/auth-architecture.md |
| HTTP security headers — six (CSP, HSTS, X-Frame-Options, X-Content-Type-Options, Referrer-Policy, Permissions-Policy) | Shipped (SOC2-C1) | security_headers.cpp:187-195 (HSTS conditional on HTTPS responses) |
| Cert hot-reload (HTTPS) with audit + metrics | Shipped | cert_reloader.cpp:31 audit cert.reload, L80 watcher loop, L114-191 atomic SSL_CTX swap |
| Agent enrollment — pre-shared / platform-trust (auto-approve via attestation_provider) / admin-approval queue (3 tiers) | Shipped | auth.cpp:717-948 + agent_service_impl.cpp:67-189 (pre-shared L70, attestation auto-approve L101-136, pending-admin queue L138-189) |
| MCP token issuance + tier-before-RBAC ordering | Shipped | mcp_server.cpp:556-557,591,599 (tier check at L591 precedes RBAC at L599); design in docs/mcp-server.md |
auth.admin_required denied audit on every 403 | Shipped (gate) | auth_routes.cpp:150 inside require_admin |
| Private-key permission validation | Shipped | cert_reloader.cpp:120 validate_key_file_permissions() (helper in file_utils.hpp); called at startup from server.cpp and on hot-reload |
| Metrics endpoint localhost-only-no-auth | Shipped | server.cpp:1621 (loopback always unauthenticated; remote behavior toggled by cfg.metrics_require_auth) |
| Account lockout after N failed local-password logins | Shipped (SOC 2 CC6.3) | auth.db v3 columns + AuthDB::lockout_status/record_failed_login/clear_failed_logins (auth_db.cpp); POST /login pre-check + record/clear (auth_routes.cpp); admin unlock POST /api/v1/users/<name>/unlock (rest_api_v1.cpp); --auth-lockout-threshold/--auth-lockout-window-secs (main.cpp). Generic-401 (no enum/oracle), auto-expiring window, audit auth.lockout.applied/.cleared. Ref: docs/auth-architecture.md "Account lockout". |
| Local password self-change + admin reset (#5342), cfg seed-only (#5274) | In PR (#5342) — on feat/5342-local-password-change, not yet on dev — SOC 2 CC6.3 | POST /api/v1/users/me/password + POST /api/v1/users/{name}/password (rest_api_v1.cpp register_password_routes); CredentialChangeOwner (ADR-0012 §3 query owner, the ONLY credential writer — credential + session delete + provisional-MFA wipe + lockout clear (admin) + audit rows in ONE transaction under the auth.users row lock; AuthManager::commit_password_change); locking post-mint re-read (recheck_role_locked); MFA enrolment bound to the proven hash; verify_password → expected<VerifiedCredential, VerifyFailure> (store failure / mid-verify hash change = transient → /login 503, no strike); AuthRoutes::verify_password_with_lockout + sso_only_local_password_gate (shared with /login); password_policy.hpp (12..1024 bytes); Settings → User Management buttons (settings_routes.cpp render_users_fragment + settings_ui.cpp). Interactive cookie sessions only (tokens 403), same-site CSRF + JSON gates, MFA step-up; the admin reset gates on the A2/A1 durable-Administrator predicate (is_rbac_administrator(kRest) + current-regime re-check, replacing perm_fn; JIT/IdP-group/custom-role refused) and refuses self + the break-glass account; every session incl. the caller's deleted in the same transaction, no re-minted session; audit user.password_change/user.password_reset in-transaction (audit failure ⇒ no change, 503 audit_unavailable); metric yuzu_auth_password_changes_total. #5274: find_user_or_hydrate is DB-first in AuthDB mode, a mid-login hash change is transient, boot WARN + yuzu_auth_cfg_credentials_stale; the Windows installer refuses /ADMIN_PASS on upgrade (exit 11). No MCP twin (parity-ledger exception: rows + ADR-1005 ledger entry 2026-10-04). SOC 2 gap note: length bounds are the ONLY password-quality control — no complexity rules, no password history/reuse check, no expiry or forced rotation, and no must-change-at-next-sign-in flag (that arrives with #5357); state this plainly in a CC6.1/CC6.3 questionnaire rather than implying a full password policy. Follow-ups: #5357 MCP temp-password reset (auth schema v3), #5358 sessions-route audit principal, #5359 reserve me, #5360 (re-titled: migrate other audited mutations onto AuditStore::log_in_txn), #5361 boot audit row for stale cfg creds, #5362 (moot — no rollback exists), #5363 compose wizard, #5364 locked-vs-wrong timing, #5365 /readyz AuthDB probe, #5366 chaos harness; related #5343 (second first-run / /OPERATOR_USER account unusable on Postgres), #5353 (non-admin account page). Ref: docs/auth-architecture.md "Local password change and reset". |
MFA / TOTP — full ladder (enrollment + login challenge + recovery codes; step-up on 11 high-risk surfaces; enforcement modes + OIDC amr short-circuit + login-time enrollment bootstrap) | Shipped (v0.12–v0.13, SOC 2 CC6.6) | server/core/src/totp.{hpp,cpp} (RFC 6238 + base32); AuthDB::mfa_* accessors; POST /login 202-branches + POST /login/mfa, /login/mfa/stepup, /login/mfa/enroll at auth_routes.cpp; require_mfa_step_up + amr_asserts_mfa at mfa_step_up.{hpp,cpp}; --mfa-enforcement at main.cpp; Settings panel + self-target disable guard at settings_routes.cpp. At-rest TOTP-secret encryption has SHIPPED (PR #2394): auth.users.mfa_totp_secret is a pg::SecretCodec envelope column (ADR-0010, fail-closed decrypt); the auth_kv scaffolding was not used. Full reference: docs/auth-mfa-design.md. |
SCIM v2 provisioning — auto-create/deactivate/reactivate operators from an IdP, plus Groups→role mapping (/scim/v2/*, Users and Groups) | Shipped (SOC 2 CC6.2/CC6.7/CC6.8) | server/core/include/yuzu/server/scim_store.hpp (born-on-Postgres, schema scim_store — scim_resources/scim_tokens, pg::PgMigrationRunner; migrated off the retired auth.db, PR #2394) + scim_json.hpp (JSON codec/discovery) + scim_routes.{hpp,cpp} (routes); provenance guard via AuthDB::set_provisioning_source/get_provisioning_source (auth.users.provisioning_source), now also re-checking role == "user". --scim-admin-group grants role=admin to a SCIM-provisioned user currently in that group (Model A: IdP membership is authoritative, a manual role change is reverted on the next membership recompute). See docs/auth-architecture.md "SCIM v2 provisioning". |
| SCIM ↔ OIDC/SAML identity linkage + credential revoke on deprovision (ADR-2001) | OIDC: Shipped PR1+PR2+PR3 (SOC 2 CC6.8). SAML: Shipped PR4a+PR4b (SOC 2 CC6.8) | Login-time link (oidc::link_oidc_login_to_scim, ScimStore::identity_links/--oidc-scim-link-claim, default sub, allow-list {sub,oid}) + deprovision-time revoke across slug + every linked oidc: principal (deprovision_revoke.{hpp,cpp}, oidc_principal.hpp), credentials-first, fail-closed on non-persist. D1 (yuzu_scim_deprovision_role_refused_with_active_link_total + scim.user.deprovision_role_refused_with_link audit, result=failure — AuditStore has no severity column, so the ADR's "kCritical audit" language is realized as an optional Severity::kCritical AnalyticsEvent gated on analytics collection being enabled, never the audit row itself) covers an externally-elevated SCIM admin (#2021 guard still applies; a human must revoke that identity's tokens manually). D2 (yuzu_scim_deprovision_unlinked_total) covers a federated user who logged in but no link formed (misconfigured --oidc-scim-link-claim, or an IdP whose externalId shares no claim with any OIDC token Yuzu trusts — genuinely unrevocable via SCIM in that case); login records BOTH the sub and oid observation candidates (oidc_login_observations, keyed (iss,sub,claim_name)), so D2 reliably fires on a misconfigured link-claim (an externalId matching the other, unconfigured claim is still detected). Revocation is durable within ~60s (ApiTokenStore validate-cache TTL), not instant. Two residuals: (a) the migration-v3 partial-unique index on scim_resources.external_id is fail-closed — a server carrying a pre-existing duplicate non-empty external_id refuses to boot (dedup pre-upgrade, see docs/user-manual/server-admin.md Upgrade Notes); (b) a login racing an in-flight deprovision (TOCTOU) — now closed by the shipped PR3 deny-at-login (ScimStore::linked_resource_active + oidc_login_denied_deprovisioned, auth.oidc.deprovisioned_denied audit): re-login after a completed deprovision is fully closed, the in-flight microsecond race narrowed (not eliminated) by a post-mint re-check. SAML (PR4a+PR4b): the same shape, keyed on the stable saml:<entity_id>#<NameID> principal (saml::saml_principal_id, saml_principal.hpp), a dedicated saml_identity_links table (ScimStore migration v4, saml_scim_link.{hpp,cpp}), and a link forming ONLY for a stable NameID Format (persistent/SAML-1.1 emailAddress — never transient/unspecified, saml::is_linkable_name_id_format); since SAML mints no API/MCP tokens, deprovision-revoke for a SAML principal is session-invalidation only. PR4b (#3066, the SAML analogue of PR3) SHIPPED — ScimStore::saml_linked_resource_active (the SAML analogue of linked_resource_active, same LEFT-join/fail-closed/orphan-reprovision tri-state) + saml::saml_login_denied_deprovisioned, wired as a primary pre-mint check and a post-mint re-check in /saml/acs, exactly mirroring OIDC's two call sites; denies redirect to the byte-identical /login?error=saml, audit auth.saml.deprovisioned_denied, metric yuzu_auth_saml_deprovisioned_denied_total. Same honest scope as OIDC's PR3: re-login after a completed SAML deprovision is fully closed; the in-flight microsecond race is narrowed (not eliminated) by the post-mint re-check, and — since SAML mints no tokens — a slipped session is bounded by its own TTL rather than the ~60s token-cache window. See docs/auth-architecture.md "SCIM ↔ OIDC identity linkage for deprovision" + "SAML ↔ SCIM identity linkage" and docs/adr/2001-scim-oidc-identity-linkage.md (incl. its SAML addendum, item 8). |
2. Required state — enterprise / SOC 2 readiness
Source of truth: docs/enterprise-readiness-soc2-first-customer.md
Workstream B — Identity, Access, and Administrative Security (§3.2).
SOC 2 alignment: CC6.1 (logical access), CC6.2 (provisioning), CC6.3
(authentication), CC6.6 (privileged access), CC6.7 (change in role), CC6.8
(termination), CC7.2 (anomalies → audit).
Required-but-not-yet-shipped feature inventory
| Feature | Workstream B line | SOC 2 link | Gap class |
|---|---|---|---|
MFA / 2FA / TOTP — full ladder (PR 1 enrollment + login challenge; PR 2 step-up on 11 surfaces; PR 3 enforcement modes admin-only/required + OIDC amr short-circuit + login-time enrollment bootstrap; docs/auth-mfa-design.md) | "2FA/TOTP for high-risk approvals" | CC6.6 | SHIPPED — ladder complete; the at-rest TOTP-secret encryption tail has also shipped (PR #2394: auth.users.mfa_totp_secret is an ADR-0010 SecretCodec envelope column, fail-closed decrypt) |
| Hardened-mode local-password disable | "Disable local-password fallback in hardened mode" | CC6.3 | SHIPPED — --auth-mode=sso-only (Config::auth_mode) disables local-password login fleet-wide (only an SSO provider mints a session); boot fails closed without an SSO provider — OIDC, or (Linux/macOS, HTTPS on) SAML (sso_boot_guard.hpp). Gate in auth_routes.cpp POST /login returns the same generic 401 (no oracle); denial is metric-only (yuzu_auth_local_disabled_total). See docs/auth-architecture.md "Hardened mode". |
| Break-glass account policy (constrained, audited, rotated) | "or tightly constrain break-glass account policy" | CC6.6 | SHIPPED — --break-glass-user exempt from sso-only only while armed (users.break_glass_armed_until, migration v4, auto-expiring --break-glass-window-secs default 24h); mandatory MFA enforced fail-closed at boot AND forced at login; armed out-of-band via the host CLI --break-glass-arm (audited auth.breakglass.armed, OS-principal-attributed); use audits auth.breakglass.login + metric yuzu_auth_break_glass_login_total. |
| SAML 2.0 SP (some enterprises require SAML, not OIDC) | implicit ("SSO enforcement") | CC6.1 | PARTIAL (thin slice + group→role mapping + AuthnRequest signing shipped) — SP-initiated login (HTTP-Redirect binding), assertion-signature validation against a pinned IdP cert, replay-protected (InResponseTo single-use), ephemeral session (auth_source="saml", role=admin via exact-match IdP-attested group membership — --saml-group-attribute/--saml-admin-group, mirrors the OIDC --oidc-admin-group guard — else role=user), Linux/macOS only (Windows server is out of scope — not a targeted server platform — so SAML-on-Windows-server is a NON-GAP, not remaining work). Admins are now reachable via SAML without a local account. AuthnRequest signing has since SHIPPED — optional --saml-sp-key (RSA-only PEM) signs AuthnRequests over the Redirect binding (RSA PKCS#1v1.5+SHA-256), fail-closed on a bad/non-RSA key, unsigned-by-default otherwise. AttributeStatement display-name/email parsing has since SHIPPED (PR #3698, MERGED into dev @ commit 548f19476, verified 2026-09-03) — --saml-name-attribute/--saml-email-attribute derive session display name→email→NameID from the same XSW-verified assertion node, session-enrichment only (never identity/authz/SCIM-linkage; admin still only from the group attribute). --auth-mode=sso-only now covers SAML (CC6.3) — SHIPPED (feat/auth-saml-sso-only, 2026-09-08): a complete SAML SP config with HTTPS enabled satisfies the hardened-mode boot guard on Linux/macOS, so a SAML-only deployment can disable local-password login (sso_only_boot_guard_ok in sso_boot_guard.{hpp,cpp}; the --no-https case is refused fail-closed to avoid a lockout). Deferred (still open, per docs/auth-architecture.md "Deferred items"): SP metadata endpoint (GET /saml/metadata), IdP-metadata auto-fetch, Settings-UI reconfigure. (Windows-server support is deliberately out of scope, NOT deferred — SAML is a stub there, so Windows-server still needs OIDC for sso-only; see the item-6 note below.) SCIM linkage + deprovision-revoke has since SHIPPED (ADR-2001 PR4a+PR4b, incl. deny-at-login) — see the "SCIM ↔ OIDC/SAML identity linkage" row in Section 1 above. See docs/auth-architecture.md "SAML 2.0 SP". |
| SCIM v2 provisioning (auto-provision/deprovision from IdP) | "Periodic access reviews" automation | CC6.2/6.7/6.8 | SHIPPED (Users + Groups→role mapping) — --scim-enable/YUZU_SCIM_TOKEN (preferred over --scim-token, which is ps-visible; fail-closed: refuses to start without a token, or with --no-https); every /scim/v2/* route (including discovery) bearer-authed constant-time, its own scim-service audit principal. POST /scim/v2/Users provisions at the fixed role=user (SSO login, discarded local password; reviving a deactivated same-userName account rather than 409 — returning-employee reprovision); PATCH/PUT .../{id} active:false/active:true deprovisions (soft-delete + session-revoke cascade) / reactivates (lockout cleared, MFA NOT restored). userName must be a slug (no @) — a stock Okta/Entra userName=email mapping 400s until remapped. Provenance guard (auth.users.provisioning_source, Postgres schema auth) makes every deactivate/reactivate/delete/update re-verify provisioning_source == "scim" and role == "user" before mutating, refusing 404 (never 403) on either mismatch — a locally-created admin, the break-glass account, or a since-promoted former-SCIM account can never be touched by an IdP push. Groups→role mapping (#2021): /scim/v2/Groups (POST/GET/PUT/PATCH/DELETE, displayName-keyed exact-case match, whitespace-trimmed --scim-admin-group, bounded members[], 409 on a displayName collision or rename-onto-existing) reuses resolve_role_from_groups — a SCIM-provisioned user is role=admin iff currently a member of --scim-admin-group; there is no other field or code path to role=admin, so a compromised IdP can elevate only as far as that one configured group. Model A: IdP membership is authoritative — a manual dashboard role change on a SCIM account is reverted on the next membership-recomputing event (Group mutation or User reprovision), not on a plain deactivate/restart/flag change; deprovision_role_ok is a demote-before-delete ordering gate (blocks deprovisioning a non-user account), not a permanent-elevation guarantee. Audit success/failure/denied results incl. new scim.auth.denied/scim.group.*/scim.user.role_changed; metrics yuzu_scim_requests_total{op,status} + yuzu_scim_role_changes_total + yuzu_scim_role_change_failures_total + 3 more (see docs/auth-architecture.md). Storage is now a born-on-Postgres ScimStore (schema scim_store, PR #2394 — off the retired SQLite auth.db; the earlier ADR-0006 SQLite exception is closed). Deferred: native email-userName support, userName rename, per-route rate-limiting, and not SCIM-token-at-rest encryption — struck as a non-gap (2026-07-25): scim_store.cpp stores a verify-only sha256_hex, the ADR-0010-correct posture for a bearer credential the server only ever compares. Do NOT "fix" it into a SecretCodec envelope. API-token revocation on user delete/deactivate has since SHIPPED (ADR-2001) — see the "SCIM ↔ OIDC identity linkage + credential revoke on deprovision" row in Section 1 above for the honest scope (D1/D2 residuals, ~60s window; the PR3 deny-at-login backstop HAS shipped — re-login after a completed deprovision is fully closed, the in-flight microsecond race narrowed, not eliminated, by the post-mint re-check). See docs/auth-architecture.md "SCIM v2 provisioning" and Section 3 item 7. |
| Just-in-time admin elevation (time-boxed role promotion + audit) | "Role-based least privilege and separation of duties" | CC6.6 | SHIPPED — POST /api/v1/elevate (--jit-max-elevation-secs); see priority item 9 below |
| Inactivity session timeout | "inactivity timeout" | CC6.3 | SHIPPED — --session-inactivity-secs (default 0 = disabled, opt-in). Sliding idle window enforced in AuthManager::validate_session, under the absolute 8h lifetime; cookie sessions only (API/MCP tokens exempt). On the durable path the sliding touch is mirrored via SessionStore::touch_activity (DB-clock authored, throttled); the store-less legacy path uses the in-memory Session.last_activity_at. See docs/auth-architecture.md "Inactivity session timeout". |
| Session revocation REST surface | "expiration, revocation" | CC6.3 | SHIPPED — DELETE /api/v1/sessions?username=<name> (admin) + DELETE /api/v1/sessions/me (self) in rest_api_v1.cpp (audit session.revoke_all/session.revoke_all.self, step-up, self-target guard), over AuthManager::invalidate_user_sessions (auth.cpp, durable delete via SessionStore) |
| API token rotation workflow — pair-of-tokens overlap. | "rotation process" | CC6.3 | SHIPPED for both principal kinds on both REST and MCP. Engine credentials: ApiTokenStore::rotate_engine_credential/confirm_rotation (api_token_store.hpp:254) behind POST /api/v1/engine-principals/{id}/credentials/rotate + .../confirm (REST + MCP). Human-owned tokens: ApiTokenStore::rotate_token/confirm_token_rotation (api_token_store.hpp:397,417) behind POST /api/v1/tokens/{id}/rotate + .../confirm AND the rotate_api_token/confirm_api_token_rotation MCP twins — a deliberately token-keyed state machine (≤2 active per rotation_group, not per principal), self-service only, lifetime-neutral, gated on the dedicated ApiToken:Rotate operation on both transports. See Section 3 item 11. |
API token inventory + last-used view — data layer, Settings → API Tokens dashboard fragment (render_api_tokens_fragment in settings_routes.cpp), and GET /api/v1/tokens REST route all shipped, both surfacing owner/created/last-used columns. | "token inventory" | CC6.6 | SHIPPED |
| Periodic access reviews (export of role assignments + attestation flow) | "Periodic access reviews with manager/security attestation" | CC6.2 | SHIPPED — GET /api/v1/access-reviews/export?format=json|csv (grant-table-driven: one row per principal holding a live grant, enumerates principal_type IN (user, group, engine) per the engine-principal program, a grant on a principal outside every roster is surfaced as source="orphan" rather than dropped (a disabled-but-still-granted user correctly shows source="user", lifecycle_state="disabled" instead), CSV formula-injection neutralized, AccessReview:Read, self-audited access_review.exported, 503 fail-loud never a silent partial export) + GET /api/v1/access-reviews (list every campaign, newest-first, capped 500, AccessReview:Read, self-audited access_review.list) + attestation-campaign lifecycle (POST /api/v1/access-reviews freezes the current grant population as pending rows; POST .../{id}/attestations records attested/flagged_revoke (UPSERT — overwrites a prior decision) — flag ≠ revoke, evidence only; POST .../{id}/close; GET .../{id} for full state — all AccessReview:Attest except the reads). Every route, reads included, structurally denies an engine-classed caller. MCP twins export_access_review/open_access_review/record_attestation/get_access_review/list_access_reviews/close_access_review (JSON only; record_attestation is destructiveHint:true, the rest false). 4 Prometheus metrics (yuzu_access_review_export_total{format}, _export_duration_seconds, _campaigns_opened_total, _attestations_total{decision}). Dedicated AccessReview securable (Read+Attest ops) + seeded Reviewer role (AccessReview:Read+Attest only) — round-2 fix: the first round gated this surface on AuditLog:Read/AuditLog:Attest, which over-disclosed the full grant population to Operator/PlatformEngineer (both seeded AuditLog:Read for unrelated reasons); the dedicated securable closes that. Born-on-PG AccessReviewStore (no prune — evidence persists). Deliberately gated on a global AccessReview:Read/Attest, not the ADR-0017 confinement filter (#2225 — a scoped slice is useless as fleet-wide CC6.2 evidence). Known gap: user rows list direct grants only (group-inherited access is on the group's own row); last_activity_kind is "n/a" for every user row (AuthDB has no last-login read accessor yet). See docs/auth-architecture.md "Periodic access reviews" and docs/security-reviews/access-reviews-2026-07-21.md. |
| Account lockout after N failed logins | implicit (auth hygiene) | CC6.3 | SHIPPED — auth.db v3 columns (failed_login_count/last_failed_login_at/locked_until) + AuthDB::lockout_status/record_failed_login/clear_failed_logins; --auth-lockout-threshold/--auth-lockout-window-secs; generic-401 pre-check (no enum/oracle, skips PBKDF2), auto-expiring window w/ fresh budget, admin unlock POST /api/v1/users/<name>/unlock; audit auth.lockout.applied/.cleared + metrics. See docs/auth-architecture.md "Account lockout". |
| Service-account governance (separate principal type, no human login) | "Privileged access controls" | CC6.6 | SHIPPED — the engine principal class (ADR-0031), full 4.1–4.5 ladder merged: EnginePrincipalStore, no login surface, credential-only auth, overlap-pair rotation, per-principal quota cap, live principal_class="engine" metric. Resolves authority RBAC-only (403 RBAC-off/no-grant, 503 store-unavailable). Grants are default-deny but FLEET-WIDE ONLY — PrincipalRole has no per-assignment scope field, and management-group-scoped engine assignment is rejected pending ADR-0017/Phase 5 (the scoped-assignment reject in the /engine-principals/{id}/roles handler, rest_api_v1.cpp). Literal admin/built-in roles are structurally barred (kEngineDisallowedRoles + the is_system check in assign_role); a custom role granted unrestricted permissions is auditor-detected, not prevented — by design (rbac_store.cpp deliberately refuses to enumerate "dangerous" permission combos). Phase 5 (delegation, RFC 8693 token exchange) remains design-only. See Section 3 item 14. |
| Conditional access (geo / IP / device posture, optional) | implicit ("MFA requirements") | CC6.1 | MISSING (P3) |
| Sampled auth-log evidence export for auditors | "sampled auth logs" | CC7.2 | SHIPPED — GET /api/v1/audit/auth-sample (rest_api_v1.cpp); AuditQuery.action_prefixes + random_sample (audit_store.{hpp,cpp}); scoped to auth./mfa./session.; AuditLog:Read; export audited as audit.auth_sample.exported |
| Self-managed Certificate Authority — issuer for (a) mTLS server + agent certs and (b) plugin code-signing certs. | implicit ("certificate management lifecycle") | CC6.1 / CC6.7 | SHIPPED — mTLS half + code-signing-issuance half both shipped; general operator-issue route remains deliberately deferred (item 10 re-verified 2026-09-10, feat/auth-ca-code-signing). CaStore/ca_store (Postgres schema, ADR-0053; ca_root/ca_issued/ca_crl_versions), root private key behind KeyProvider and never in the DB, sign_agent_csr (the ServerImpl chokepoint, server.cpp:10036 — not a function in x509_ca.hpp, which declares pki::sign_csr) as the single shared signer for Register + ProxyRegister (subject/SAN/EKU server-chosen, CSR ignored), full ca.* audit chain. Route permissions are NOT uniformly Security:* — GET /ca/root and GET /ca/crl are PUBLIC by design (login-exempt at web_utils.hpp:237; clients need the root to trust the install and it is already in the TLS handshake), /ca/issued + /ca/root-csr are Security:Read, /ca/revoke is Security:Delete, /ca/import-chain and /ca/issue-code-signing are Security:Write. Agent-mTLS issuance stays enrollment-driven; the general POST /ca/issue (operator-chosen CN, operator-chosen EKU) is deliberately still absent (namespace-collision risk at the #1118 identity gate). Code-signing cert issuance now SHIPPED — POST /ca/issue-code-signing + MCP twin issue_code_signing_cert, CSR-custody (operator holds the key), usage hard-pinned to codeSigning only — so --plugin-trust-bundle no longer requires an external CA; see item 10 below for the full contract and the two remaining follow-ups (CRL-distribution-to-agent-verifier enforcement, an optional CSR-mode CLI). Doc: docs/pki-architecture.md. See Section 3 item 10. |
Plugin code-signing trust anchor — operator-configured PEM trust bundle on the agent, CMS-verify of <plugin>.sig against it before dlopen. Trust bundle accepts any X.509 root — Yuzu's self-managed CA or any public CA / operator-internal CA. | implicit ("supply-chain integrity") | CC6.1 / CC7.1 | SHIPPED — verifier shipped, self-managed CA upstream (code-signing issuance) now shipped too; CRL-distribution-to-verifier enforcement remains a tracked follow-up (#4234, see item 10). |
Hard invariants that must NOT regress when adding any of the above
These are pulled from docs/auth-architecture.md and
.claude/agents/authdb.md. Every PR adding a feature in Section 2 above
must check them:
- HTTPS by default; refuse to start without
--https-cert+--https-keyunless--no-httpsis passed. - Web UI binds 127.0.0.1 by default; warn at startup if overridden.
- Private-key files must not be group/others-readable on Unix.
- Every error response uses the structured JSON envelope.
- Six security headers on every HTTP response.
- All SQL parameterised; no string interpolation.
- Self-target principal-destruction guard applied to any new destructive/demoting endpoint.
- AuthDB lifetime (two invariants, catastrophic — silent-UB auth bypass if
wrong; see
.claude/agents/authdb.md"Hard invariants → Lifetime"): (a) the short-lived bootstrapAuthDBbuilt inmain.cppis fully torn down beforeServer::create()(main.cppauth_db.reset()+ its pool/provider/ codec, so the process never holds two live AuthDB reaper threads / PgPools at once); the long-lived storeServerImplowns is constructed insideServer::create()(server.cppauth_db_ = make_unique<AuthDB>(*pg_pool_, *auth_secret_codec_)) — do NOT describe it as "spanningServer::create()". (b)ServerImpldeclarespg_pool_ → provider → secret_codec_ → auth_db_so the borrowedPgPool/SecretCodecoutlive the store and its reaper thread. Constructor takespg::PgPool&+pg::SecretCodec&(born-on-Postgres, schemaauth), not a SQLite path. yuzu-server.cfgis a one-shot first-boot seed, not a live source — still true; it now seeds theauthPostgres schema viaRbacStore::provision_first_admin(account + a durable Administrator grant, one transaction, plus a durablerbac.bootstrap.first_adminaudit row), not a SQLiteauth.dband notseed_admin_if_empty(no longer called in production — see its own header comment). A bootstrap error is FATAL.- (Retired, do NOT reintroduce as invariants): the former
auth.db0600 / restricted-ACL-at-create andMigrationRunner::run(sqlite3*, …)bullets are SQLite-era and no longer apply — AuthDB creates no file and migrates viapg::PgMigrationRunner::run(lease, "auth", migrations()). A NEW auth schema migration usespg::PgMigrationRunner; file-permission hardening is not a concern for a Postgres-resident store. POST /api/settings/usersrolefield stays ignored; role changes only via the dedicated endpoint.require_adminemitsauth.admin_requireddenied audit on every 403.- New code never holds
AuthDB::mu_while publishing to a sibling subsystem's bus.
3. Gap matrix — priority order
Recommended order for closing gaps. Each block stands alone; pick whichever matches the customer ask.
Last WHOLESALE verification: origin/dev @ ef4582be (2026-07-25) — every
"SHIPPED" status was re-confirmed by reading the named file/route on that tree,
not by trusting a design doc's status header (that pass corrected four items a
571-commit-behind tree had reported as unbuilt). Re-stamp whenever you revise;
a matrix derived from a stale checkout is worse than no matrix.
Targeted refresh 2026-09-07 against origin/dev @ 7997a799e — NOT a
wholesale re-verification. This pass re-verified only: (1) the engine-principal
audit-fail-close cluster is now fully closed (REST #2466/#2406 PR #3944 + MCP
twin #3937 PR #3971, merge 6d40b399 confirmed an ancestor of dev; #3937 issue
issue CLOSED 2026-09-07 after §5.1 verification); (2) the durable-SessionStore
- DB-clock-authority landing (HA WS-1/1a, ADR-2002 §4, #3715) — items 8 & 9 and
the session-durability wording were corrected accordingly; (3) the AuthDB +
ScimStore Postgres migration (schema
auth/scim_store, SQLiteauth.dbretired, PR #2394) — Section 1's persistent-store row, the hard-invariants list, and workflow steps 1–2 were de-SQLite'd; (4) the Open hardening backlog issue states. Every other "SHIPPED" cell still rests on theef4582bestamp — treat those as up to ~6 weeks stale and re-grep the symbol before relying on it.
Targeted refresh 2026-10-04 against feat/5342-local-password-change
(branch, NOT dev) — NOT a wholesale re-verification. Added only the
Section 1 "Local password self-change + admin reset" row, read from that
branch's rest_api_v1.cpp, auth.cpp, auth_db.cpp and settings_routes.cpp
(re-read after the branch's Gate 7 fix round, same day). Its status cell says
"In PR (#5342)", not "Shipped": flip it, and re-stamp it against dev, once
the PR merges.
Targeted refresh 2026-09-28 against origin/dev @ 257bfb338 — NOT a
wholesale re-verification. Re-verified only: (1) the RBAC admin plane — the
new Section 1 row, from rbac_store.cpp, rbac_assignable_roles.hpp,
rest_api_v1.cpp and mcp_server.cpp on that tree, plus a repo-wide grep
showing create_role/set_permission/remove_permission/set_rbac_enabled
still have no production caller; (2) the RBAC seed counts — 8 roles / 8 ops /
38 securable types (matches seed_defaults); (3) the Open hardening backlog
issue states below. None of the P0/P1/P2 status cells were re-read; they still
rest on the stamps above. release/v0.14.0-rc1 predates A1/A2/A3, so a
statement about "what ships in 0.14.0" must be checked against that branch, not
dev.
⚠️ Standing instruction — update on close. Every PR that closes or materially changes the status of an item in this gap matrix MUST update that item's status and re-stamp the Verified line in the SAME PR. Treat status drift as a review-blocking defect, exactly like a stale doc comment.
Item 11 re-verified 2026-08-10, targeted, not wholesale — against
feat/auth-human-token-rotation @ e1bf2d86 (a pre-merge integration
branch off origin/dev, not yet on dev), by reading
api_token_store.{hpp,cpp}, rest_api_v1.cpp, and mcp_server.cpp
directly (the human arm's REST routes exist; greping mcp_server.cpp for
rotate_token/confirm_token_rotation now finds the rotate_api_token
and confirm_api_token_rotation tool handlers calling into the store — the
MCP twins have merged code, per the SHIPPED status on this surface below).
Cited by SYMBOL, deliberately not by line number: this stamp has now been
stale twice — once claiming the grep returned nothing after the twins
shipped, then once citing line numbers the named grep does not return — and
a citation that rots on every unrelated edit above it is worse than no
citation, because it reads as verified. This does not re-verify the
other items in this section — their last wholesale check remains the
ef4582be stamp above.
Item 7 (SCIM) re-verified 2026-08-12, targeted, not wholesale — against
feat/auth-token-revoke-on-deprovision @ f1b9e508 (a pre-merge branch off
origin/dev @ e458871c, not yet on dev), by reading scim_routes.cpp
(D1/D2 detectors, the new scim.user.deprovision_role_refused_with_link
audit action and emit_scim_critical_event), deprovision_revoke.{hpp,cpp},
oidc_principal.hpp, scim_store.hpp (identity_links,
find_unique_active_by_external_id, observation_matches), auth_routes.cpp
(login-time link_oidc_login_to_scim call), settings_routes.cpp (the
dashboard-delete revoke seam), and main.cpp (--oidc-scim-link-claim
flag/allow-list) directly — the "API-token revocation on user
delete/deactivate" gap struck from item 7's Remaining list above SHIPPED
per this read, with the two named residuals (D1/D2) confirmed against the
code, not assumed from the ADR. This does not re-verify the other items
in this section.
Item 6 (SAML) partially re-verified 2026-09-03, targeted — the
AttributeStatement display-name/email slice previously listed as "Remaining
(next slice)" has SHIPPED: PR #3698 is MERGED into dev, real commit
548f19476 confirmed an ancestor of origin/dev (git merge-base --is-ancestor). A stale local commit fe9c5941b (same subject, 2026-08-28)
is orphaned — on no branch, superseded by the governed/Hermes-reviewed
548f19476 — so do NOT mistake it for unfinished work. The CC6.3 SAML tail
(--auth-mode=sso-only covering SAML) has since SHIPPED too — feat/auth-saml-sso-only,
2026-09-08, boot guard sso_only_boot_guard_ok (sso_boot_guard.{hpp,cpp}),
test_sso_boot_guard.cpp. The remaining SAML gaps are the
docs/auth-architecture.md "Deferred items" UX set — SP metadata endpoint,
IdP-metadata auto-fetch, Settings-UI reconfigure (see item 6 and the Section 2
SAML row for the full statement; Windows-server remains out of scope, a
non-gap). This does not re-verify the other items in this section.
Two standing cautions, learned from this revision's own review:
- A "SHIPPED" status is not a licence to describe the control loosely.
The first cut of this revision fixed four false-MISSING claims and, in
doing so, introduced two false-SHIPPED ones — engine grants described as
"scoped" (they are fleet-wide only) and a
dangerous-class gate that does not exist. Overstating a control is worse than understating it: these cells get copied into security questionnaires. When a control is partial, say which half shipped. - Line-number anchors decay faster than status. Statuses here were
re-verified wholesale; a few individual
file:lineanchors were carried over unchecked and two were wrong. Treat an anchor as a hint, and re-grep the symbol before relying on it.
P0/P1 item numbers are stable — commits, PR titles, and memories cite them
(P0 #3, P1 #7, P1 #9). P2 was renumbered 11–14 in this revision to fix a
duplicate 10; the one live cross-reference to the old numbering
(docs/security-reviews/access-reviews-2026-07-21.md) was updated with it.
Priority 0 — needed for first enterprise customer
MFA / TOTP for admin login + high-risk approvals.DONE — the full 3-PR ladder shipped: TOTP enrollment + login challenge + recovery codes, step-up on 11 high-risk surfaces, enforcement modes (admin-only/required) with login-time enrollment bootstrap, and the OIDCamrshort-circuit. Seedocs/auth-mfa-design.md. The at-rest TOTP-secret encryption tail has since SHIPPED (PR #2394, auth + SCIM → Postgres; verified onorigin/dev2026-09-07):auth.users.mfa_totp_secretis now apg::SecretCodecenvelope-encrypted column per ADR-0010 — auth is the platform's first SecretCodec consumer. The decrypt path is fail-closed: a decrypt failure surfaces as an error, NEVER as "no MFA enrolled". Theauth_kvscaffolding was not used and was dropped by that migration. TOTP secrets are no longer plaintext — a customer security questionnaire can state at-rest encryption for the MFA secret.Account lockout after N failed logins.DONE —auth.dbv3 columns (failed_login_count/last_failed_login_at/locked_until) +AuthDB::lockout_status/record_failed_login/clear_failed_logins;--auth-lockout-threshold(default 5, 0 disables) /--auth-lockout-window-secs(default 900).POST /loginpre-check returns the same generic 401 as a bad password (no enumeration/oracle, skips PBKDF2 on a locked account); the window auto-expires and a waited-out user gets a fresh budget. Admin unlockPOST /api/v1/users/<name>/unlock(UserManagement:Write+ step-up, self-target allowed). Auditauth.lockout.applied/.cleared; metricsyuzu_auth_lockout_applied_total/yuzu_auth_lockout_blocked_total. Seedocs/auth-architecture.md"Account lockout".Hardened-mode local-password disable.DONE —--auth-mode=sso-only(YUZU_AUTH_MODE) disables the local-password path fleet-wide; only an SSO provider mints a session, and the server refuses to start without one — OIDC, or (Linux/macOS, HTTPS on) SAML (it would otherwise lock everyone out). ThePOST /logingate returns the same generic 401 as a bad password (no enumeration/mode oracle); the denial is metric-only (yuzu_auth_local_disabled_total{target}), NOT a per-attempt audit row (anti-flood, matches the lockout-blocked posture). Break-glass account:--break-glass-useris the single exempt principal, exempt only while armed (users.break_glass_armed_until, migration v4 — a future timestamp evaluated in SQL likelocked_until, so it auto-expires;--break-glass-window-secsdefault 24h). Mandatory MFA is enforced two ways: boot fails closed if the break-glass user lacks MFA (break_glass_account_problem), and at login an un-enrolled break-glass account is hard-denied 403 (auth.breakglass.denied) — enrollment is never offered (it would defeat the second factor; governance UP-1). Arming is an out-of-band host CLI op —yuzu-server --break-glass-arm(auditedauth.breakglass.armedatkCritical, attributed to the kernel OS identity, audit-store writable-checked before mutate; mirrors the--mfa-resetcontract) — so it works when the IdP is down. Use is loud:kCriticalauth.breakglass.loginaudit +yuzu_auth_break_glass_login_totalmetric. Seedocs/auth-architecture.md"Hardened mode",docs/security-reviews/auth-hardened-mode-2026-06-29.md, thedocs/ops-runbooks/auth-db-recovery.mdarm runbook;tests/unit/server/test_auth_break_glass.cpp+test_auth_routes_hardened.cpp.Sampled auth-log evidence export.DONE —GET /api/v1/audit/auth-sample?from=...&to=...&limit=Nreturns a pseudo-random sample of the auth surface (auth./mfa./session.action prefixes) over an optional window. Gated onAuditLog:Read(NOTrequire_admin— a read-only auditor role can pull evidence without full admin; separation of duties), and the export is itself audited asaudit.auth_sample.exported. Backed byAuditQuery.action_prefixes+random_sample. SOC 2 CC7.2. Seedocs/security-reviews/auth-sample-export-2026-06-15.md.Session revocation REST surface.DONE —DELETE /api/v1/sessions?username=<name>(admin) +DELETE /api/v1/sessions/me(self) overAuthManager::invalidate_user_sessions(auth.cpp; durable delete viaSessionStore); auditsession.revoke_all/session.revoke_all.self, step-up, self-target guard. (The skill matrix previously listed this as PARTIAL — it has in fact shipped.)
Priority 1 — enterprise-friction reducers
-
SAML 2.0 SP — thin first slice shipped, plus group→role mapping (
feat/auth-saml-group-role). SP-initiated login via HTTP-Redirect binding; ACS via HTTP-POST binding. Assertion signature validated against the pinned IdP cert (in-document<KeyInfo>ignored); XML signature-wrapping defended; audience / recipient / expiry validated; solicited-only + single-useInResponseTo(replay-protected). Sessions are ephemeral,auth_source="saml"; role isadminwhen the assertion's IdP-attested groups (--saml-group-attribute) contain the configured--saml-admin-group(exact match only, parsed from the same XSW-verified assertion node as NameID — mirrors the OIDC--oidc-admin-groupguard), elserole=user. Both flags empty (default) reproduces the original all-role=userbehaviour. Linux and macOS only — and this is a deliberate NON-GAP, not remaining work: running the Yuzu server on Windows is out of scope (Windows endpoints still run the agent). Do not plan a Windows-server SAML port.saml_provider.cpp:10-21compiles a stub on_WIN32and the provider reports disabled at startup. AuthnRequest signing has since SHIPPED (feat/auth-saml-authnrequest-signing): optional--saml-sp-key/YUZU_SAML_SP_KEY(RSA-only PEM path) signs SP-initiated AuthnRequests over the HTTP-Redirect binding with RSA PKCS#1 v1.5 + SHA-256 (SigAlg/Signaturequery params); left unset, AuthnRequests stay unsigned (backward-compatible default). Fails closed — an unreadable/over-permissioned/oversized/malformed/non-RSA key disables SAML entirely at boot rather than silently falling back to unsigned requests; a per-request signing failure fails/auth/saml/startrather than emit an unsigned redirect. AttributeStatement display-name/email parsing has since SHIPPED — PR #3698, MERGED intodev@ commit548f19476(verified 2026-09-03; the earlier local commitfe9c5941bwas a superseded/orphaned pre-governance copy, on no branch — do NOT treat it as unfinished work).--saml-name-attribute/--saml-email-attributederive session display name→email→NameID from the same XSW-verified assertion node, session-enrichment only (never identity/authz/SCIM-linkage; admin still only from the group attribute). Remaining (next slice), each verified unbuilt onorigin/dev: IdP-metadata auto-fetch (the remaining--saml-*flags are hand-configured), Settings-UI reconfigure. State it accurately: the shipped slice does complete a full SP-initiated login (signed or unsigned, per configuration) (test_saml_provider.cpp, the full-login case), and admins are reachable via SAML (Section 1). The remaining absences are thedocs/auth-architecture.md"Deferred items (not in this slice)" list. The compliance one —--auth-mode=sso-onlycovering SAML (CC6.3) — has since SHIPPED (feat/auth-saml-sso-only, 2026-09-08): the hardened-mode boot guard (sso_only_boot_guard_ok,sso_boot_guard.{hpp,cpp}, called frommain.cpp) now accepts a complete SAML SP config with HTTPS enabled as an SSO path, so a SAML-only Linux/macOS deployment can disable local-password login; the--no-httpscase is refused fail-closed (the SAML provider is disabled over plain HTTP, so booting would lock everyone out), and a SAML session still cannot use JIT elevation (no local TOTP / no OIDCamr). The rest are UX/polish: SP metadata endpoint (GET /saml/metadata), IdP-metadata auto-fetch, and the Settings-UI reconfigure. Windows is NOT among them: running the server on Windows is out of scope, so SAML being Windows-server-only is a non-gap rather than remaining work (the Windows agent on managed endpoints is unaffected). Seedocs/auth-architecture.md"SAML 2.0 SP". SCIM linkage + deprovision-revoke has since SHIPPED for SAML too (ADR-2001 PR4a+PR4b — do NOT list it as a gap): a SAML login now mints its session on a stablesaml:<entity_id>#<NameID>principal, forms a durable link to a SCIM resource when the NameID's Format is stable (persistent/SAML-1.1emailAddress— nevertransient), and a SCIM deprovision now revokes that linked SAML session (SAML has no API tokens to revoke). PR4b (#3066), the SAML deny-at-login backstop, has since SHIPPED too — a deprovisioned SAML identity is now refused at/saml/acsthe same way OIDC's PR3 refuses/auth/callback, closing the re-authenticate-and-mint-a-fresh-session window for the completed- deprovision case (the in-flight race is narrowed, not eliminated by construction, exactly as for OIDC). See the "SCIM ↔ OIDC/SAML identity linkage" row above anddocs/auth-architecture.md"SAML ↔ SCIM identity linkage" for the honest scope. -
SCIM v2 provisioningDONE (Users + Groups→role mapping, #2021) — auto-create/deactivate/reactivate users from the IdP over/scim/v2/*(--scim-enable/--scim-token, fail-closed without a token or without HTTPS). Theprovisioning_sourcecolumn lives on theauth.userstable (Postgres schemaauth); SCIM's own resources are a born-on-PostgresScimStore(schemascim_store—scim_resources/scim_tokens+ Group resources/membership rows; PR #2394, a fresh start with no SQLite backfill, off the retiredauth.db). Bearer-token auth (constant-time, separate from operator API tokens), soft-delete + session-revoke on deactivate, lockout-clear (not MFA-restore) on reactivate. The provenance guard — every mutating call re-verifiesprovisioning_source == "scim"immediately before touching the account, refusing404(never403, no existence oracle) on mismatch — is the invariant that makes it safe to point a third-party IdP connector at this surface: a local admin or the break-glass account can never be deactivated by SCIM — a check also re-verifiesrole == "user", so an operator-elevated former-SCIM account is likewise beyond SCIM's reach (this is a demote-before-delete ordering gate, not a claim the elevation is permanent — see Groups→role mapping below).PUTtriggers the same deactivate/reactivate semantics asPATCHwhenactiveflips; aPOSTagainst a deactivated SCIM account'suserNamerevives it (returning-employee reprovision) rather than409ing./scim/v2/Groups(POST/GET/PUT/PATCH/DELETE,displayName-keyed, whitespace-trimmed + exact-case--scim-admin-groupmatch, boundedmembers[],409on adisplayNamecollision or rename-onto-existing) grants a SCIM-provisioned userrole=adminiff currently a member of the configured admin group, via the sameresolve_role_from_groupsSAML/OIDC already use — the only code path from a SCIM request torole=admin. Model A: IdP group membership is authoritative for a SCIM account's role — a manual dashboard role change is reverted on the next event that recomputes that user's membership (a Group mutation or User reprovision), not on a plain deactivate/restart/--scim-admin-groupchange; a manually-promoted admin in no SCIM group is the one residual case Model A does not reach (neither reverted nor SCIM-deprovisionable until demoted by hand). Audit result values aresuccess/failure/denied(incl. newscim.group.created/.updated/.deletedandscim.user.role_changed); metricsyuzu_scim_requests_total{op,status},yuzu_scim_auth_failures_total,yuzu_scim_audit_write_failures_total,yuzu_scim_provenance_denied_total,yuzu_scim_role_changes_total,yuzu_scim_role_change_failures_total(the last a hardening-round fix — a role-apply failure now gets its own auditfailurerow + metric, distinct from the pre-existing audit-write-failure counter). Remaining: native email-shapeduserNamesupport (Yuzu usernames are slug-only — a stock Okta/EntrauserName=emailmapping 400s until the operator remaps it; this is the highest-friction of the four for a real IdP onboarding),userNamerename viaPUT, and per-route rate-limiting. Struck from this list (2026-07-25): "SCIM-token-at-rest encryption" —scim_store.cppstores a verify-onlysha256_hex, which is the ADR-0010-correct posture for a bearer credential the server only ever compares. It is not a gap; do NOT "fix" it into a SecretCodec envelope. Storage moved to Postgres (SHIPPED, PR #2394; verified onorigin/dev2026-09-07):ScimStoreis now born-on-Postgres (schemascim_store,pg::PgPool, nosqlite3*/db_mtx_, migrated viapg::PgMigrationRunner), off the retiredauth.db— a fresh start with no SQLite backfill; the verify-onlysha256_hextoken posture is preserved. Seedocs/auth-architecture.md"SCIM v2 provisioning". API-token revocation on user delete/deactivate has since SHIPPED (ADR-2001) — do NOT list it as a gap. Deprovision now revokes the SCIM slug's tokens AND every OIDC identity durably linked to it at login (--oidc-scim-link-claim, defaultsub; Entra needsoid), for both the SCIM seam and the dashboard's manual delete. This is a covered control with two NAMED, monitored residuals, not "complete" flatly: (1) a SCIM slug elevated to admin outside SCIM still blocks the #2021 deprovision guard, so its linked identity's tokens are NOT auto-revoked —yuzu_scim_deprovision_role_refused_with_active_link_total+scim.user.deprovision_role_refused_with_link(result=failure; the audit row itself carries no severity —AuditEventhas no severity column — the ADR's "kCritical" language is realized only as an optionalAnalyticsEventgated on analytics collection being enabled, never as a property of the audit row) — a human must terminate that identity manually; (2) an IdP whose SCIMexternalIdshares no claim value with any OIDC token Yuzu trusts cannot be linked at all — surfaced viayuzu_scim_deprovision_unlinked_total(D2), never silently. Revocation is durable withinApiTokenStore's ~60s validate-cache window, not instant. The OIDC deny-at-login backstop (ADR-2001 §4/PR3) has SHIPPED — a deprovisioned linked identity is refused at OIDC login (ScimStore::linked_resource_active+oidc_login_denied_deprovisioned). Read the scope precisely (do NOT flatten to "CC6.8 complete"): re-login against an already-completed deprovision is fully closed; a login racing an in-flight deprovision is narrowed by a post-mint re-check (not eliminated by construction). Seedocs/auth-architecture.md"SCIM ↔ OIDC identity linkage for deprovision" anddocs/adr/2001-scim-oidc-identity-linkage.md. SAML gained the same coverage via PR4a+PR4b (SAML addendum to the same ADR): a stablesaml:<entity_id>#<NameID>session principal (saml_principal.hpp), a dedicatedsaml_identity_linkstable (ScimStoremigration v4), link formation gated on a stable NameID Format only (nevertransient), deprovision-revoke of the linked SAML session (SAML mints no tokens, so there is nothing else to revoke), and PR4b (#3066) deny-at-login, SHIPPED —ScimStore::saml_linked_resource_active+saml::saml_login_denied_deprovisioned, the identical primary-check/post-mint-re-check shape OIDC's PR3 uses, closing the re-authenticate-and-mint-a-fresh-session window for a completed deprovision the same way; a login racing an in-flight deprovision is narrowed by the post-mint re-check, not eliminated by construction — the same scope statement as the OIDC line above. Seedocs/auth-architecture.md"SAML ↔ SCIM identity linkage" and the ADR's SAML addendum (item 8). -
Inactivity session timeoutDONE —--session-inactivity-secs(YUZU_SESSION_INACTIVITY_SECS,Config::session_inactivity_secs), default 0 = disabled (opt-in; existing deployments unaffected; recommended 900). Enforced inAuthManager::validate_session, which now branches by whether a durable session store is wired. Store-backed (HA) path — the production posture since HA WS-1/1a (durableSessionStore, ADR-2002 §4): idle is decided invalidate_session_durableagainst a monotonicsteady_clockdeadline derived from the DB-clock-authoredlast_activity+db_now_ms(derive_session_deadlines, #3715), and the sliding touch is mirrored durably viaSessionStore::touch_activity(stamps Postgresnow(), GREATEST-clamped, no generation bump, throttled) — so idle survives a replica restart/failover and adjudicates identically on any replica. A cache-hit idle verdict re-checks the authoritative row before evicting (a touch may have landed on another replica). Store-less (legacy config-file-only) path: the old byte-for-byte in-memory body still runs — idle against the in-memorySession.last_activity_at. Either way: under the absolute 8hkSessionDuration, cookie sessions only (API/MCP tokens resolve viasynthesize_token_session, nevervalidate_session, so they are never idle-timed-out). Seedocs/auth-architecture.md"Inactivity session timeout" and — for the durable session design — the AuthDB routed-concern row (.claude/routed-concerns-access-control.md) +docs/adr/2002-high-availability-architecture.md§4;tests/unit/server/test_auth.cpp[idle]. Do NOT trust the stale session text in.claude/agents/authdb.mdor the in-tree comments inauth_db.hpp/rest_api_v1.cppthat still call the in-memory map the sole/only session store — they predateSessionStore; #2343 is the related cleanup. -
JIT admin elevationDONE —POST /api/v1/elevate{justification, duration_secs}promotes the caller's effective role to admin for a bounded window (--jit-max-elevation-secs, default 1h), then auto-reverts. Eligibility = the per-userusers.elevation_eligibleflag (auth.db migration v5, admin-set viaPOST /api/v1/users/<name>/elevation-eligibility; keyed on ausersrow, which OIDC login does not create — a federated identity needs one provisioned first), distinct from standing admin and enumerable for access reviews. Gated on eligibility + mandatory MFA enrollment (unconditional — elevation is the privilege boundary) + a fresh MFA step-up; the grant audit is fail-closed, revoking eligibility ends active elevations, and self-grant is blocked. A local session's factor is local TOTP; an OIDC session with an IdP-MFA (amr) proof satisfies this WITHOUT local enrollment, per--jit-oidc-amr-elevation(default true) — an OIDC session never consults a local namesake account's TOTP enrollment, and--no-jit-oidc-amr-elevationblocks OIDC sessions from elevating entirely (they cannot present a local TOTP step-up).auth::effective_role(session)(admin whileis_elevated) is honoured byrequire_admin+ the permission gates. The elevation window is now DURABLE inSessionStoreon the store-backed (HA) path —elevate_sessioncallsSessionStore::set_elevation, which authorselevation_issued/elevated_until = LEAST(now()+duration, expires_at)in SQL (the "never past absolute expiry" clamp is atomic in-DB, no TOCTOU), bumps the durable generation, and the local cache re-derives a monotonicsteady_elevated_untilviaderive_session_deadlines(with the H2 width/future-dated clamps). So an elevation survives failover and is seen on any replica. Only the store-less legacy path keeps the old purely-in-memory-per-cookie window. Either way it is cookie-session-only — API/MCP tokens can never elevate. Auditsrole.elevation.{granted,denied,revoked,expired}+user.elevation_eligibility.set;POST /api/v1/elevate/revokefor step-down. Passive expiry is now audited too — lazily, at theAuthRoutes::resolve_sessioncookie chokepoint on the operator's next authenticated request after the window lapses (no background reaper); a session already at/past its own absolute lifetime is rejected401rather than granted a zero-length window (dead-window guard). Seedocs/auth-architecture.md"JIT admin elevation";tests/unit/server/test_auth_jit_elevation.cpp. -
Self-managed Certificate Authority — mTLS half SHIPPED; code-signing issuance half now SHIPPED too (CSR-custody model, REST + MCP twin — item 10 re-verified 2026-09-10,
feat/auth-ca-code-signing). The matrix previously listed this whole item as MISSING; that was stale by the entire PKI ladder (#1237–#1244 — an inclusive range with one hole: #1242 is an MCP prompt-argument fix, not PKI). Routed doc:docs/pki-architecture.md.Shipped (mTLS):
CaStoreover theca_storePostgres schema (ADR-0053, migrated off SQLiteca.db) withca_root/ca_issued/ca_crl_versions. The root private key is never in the DB —ca_rootholds an opaquekey_refand the key lives behindKeyProvider(key_provider.{hpp,cpp}), which is the seam an HSM/PKCS#11 provider plugs into later.sign_agent_csr(x509_ca.hpp) is the single shared signer for both directRegisterand gatewayProxyRegister, with subject/SAN/EKU server-chosen and the CSR's own values ignored. Revoke is serial-scoped. REST (ca_routes.cpp):GET /api/v1/ca/rootandGET /ca/crlare PUBLIC by design — login-exempt atweb_utils.hpp:237, because a client needs the root to trust the install and it is already presented in the TLS handshake (docs/pki-architecture.md:112-113documents this). The gated ones areGET /ca/issued+GET /ca/root-csr(Security:Read),POST /ca/revoke(Security:Delete), andPOST /ca/import-chain(Security:Write) — plus dashboard twins under/api/settings/ca/. Do not describe this surface as uniformlySecurity:*: the public posture is correct, but overstating it is the wrong direction to be wrong on a security questionnaire. Audit:ca.cert.issued,ca.cert.revoked,ca.cert.reissue_blocked,ca.crl.published,ca.root_csr.exported,ca.subordinate.imported.Note the shape difference from the original design above: there is no generic
POST /api/v1/ca/issue. Issuance is enrollment-driven throughsign_agent_csron the agent-registration path — deliberately, so the server chooses every field of every cert it signs. Do not add an operator-facing "issue me a cert for X" route without re-deciding that.Shipped (code-signing issuance, gap-matrix #10):
POST /api/v1/ca/issue-code-signing(Security:Write) + MCP twinissue_code_signing_cert(supervised tier, approval-gated like every otherSecurity:WriteMCP tool). CSR-custody model — the operator generates their own key and CSR locally and submits only the CSR ({csr_pem,label,validity_days?}); the server never sees the private key and returns only{certificate_pem,chain_pem,serial_hex,not_after, purpose:"code-signing"}. A server-side key-minting CLI was deliberately not built — that would put the server in transient custody of a secret whose compromise signs arbitrary plugins, exactly the boundary this feature exists to avoid. Usage is hard-pinned topki::LeafUsage{.code_signing=true}(neverclientAuth/serverAuth, so the leaf is rejected by the mTLSSSL_CLIENTpurpose check and can never reach the #1118 agent-identity gate) and the subject CN is the caller's validatedlabel(^[A-Za-z0-9._-]{1,64}$), never an agent-style SAN — this is what makes issuance safe here while the generalPOST /api/v1/ca/issue(operator-chosen CN, operator-chosen EKU) stays deferred, unchanged from above. Validity defaults to 365 days, caller-selectable up to a hard 730-day ceiling, clamped to the issuing CA's own expiry. Issuance is recorded inca_store(purpose="code-signing"), so it appears inGET /ca/issuedand is revocable via the existingPOST /ca/revoke; auditsca.cert.issued(target_type=CodeSigningCertificate).docs/user-manual/agent-plugins.md"Signing a plugin" now leads with this route; the pre-existing bring-your-own-CAopenssl req -x509/openssl cms -signrecipe remains documented as an alternative for operators not using the internal CA. The verifier (issue #80) needed no change — it was already CA-agnostic.Remaining (two tracked follow-ups, both honest gaps, not overstated): (a) CRL-distribution enforcement. Revoking a code-signing leaf via
POST /ca/revokerecords the revocation and republishes the CRL, but the agent-side plugin-load verifier (detached_signature.cpp) does not consult the CRL — so revocation does not yet reach agents at plugin-load time, identical to today's hand-rolled-external-CA posture. Tracked follow-up:#4234. (b) Optional CSR-mode operator CLI convenience (#4239) — an--out-style local helper that wraps theopenssl req/curl /ca/issue-code-signing/openssl cms -signsequence documented indocs/user-manual/server-admin.md"Issuing a code-signing certificate" into one command. Neither is a security gap; both are UX/observability polish on top of a shipped, CSR-custody-safe issuance path.
Priority 2 — long-tail polish
-
API token rotation workflow — engine credentials SHIPPED, human tokens NOT ADOPTED.HUMAN TOKENS: STORE CORE + REST + MCP ALL SHIPPED (full REST/MCP parity). Engine-credential rotation was already SHIPPED (ApiTokenStore::rotate_engine_credential/confirm_rotation,api_token_store.hpp:254,POST /api/v1/engine-principals/{id}/credentials/rotate/.../confirm) — see item 14 below. Human-owned tokens now have their own, deliberately different, token-keyed state machine (a principal-keyed copy of the engine arm would have been wrong — a human holds N concurrent unrelated tokens, an engine principal holds one):ApiTokenStore::rotate_token/confirm_token_rotation(api_token_store.hpp:397,417), serialized on the samepg_advisory_xact_lock(hashtext(principal_id))the engine arm and the T12 sweep use, enforcing a ≤2-active ceiling perrotation_group, never per principal. Shipped: the store core,POST /api/v1/tokens/{id}/rotate/.../confirmAND the MCP twins (rotate_api_token/confirm_api_token_rotation) (self-service only, gated onApiToken:Rotate— a dedicated operation distinct from theApiToken:Writecreate/list/revoke axis and fromSecurity:Write— no admin bypass, wrong-owner indistinguishable from nonexistent, lifetime-neutral with no caller-exposed override), kind-discriminated telemetry (yuzu_api_token_rotation_*/yuzu_api_token_confirm_total, both surfaces incrementing the same symbol), and a 33-case[human]adversarial regression suite. Full design record:docs/auth-architecture.md"Human API-token rotation";docs/mcp-server.md"Human API-token rotation tools"; evidence chain:docs/security-reviews/human-token-rotation-2026-08-10.md(records a caught-in-review, now-shipped-as-adjudicated privilege-escalation finding on the MCP-side RBAC allowance that drove theApiToken:Rotatesplit, a SEPARATE governance-caught-before-merge authority-inheritance fix onrotate_tokenitself, and three pre-existing follow-up issues it surfaced —#2943/#2944/#2945— none of which are defects in the shipped human-token surface itself). -
API token inventory view.DONE —render_api_tokens_fragment(Settings → API Tokens,settings_routes.cpp) andGET /api/v1/tokens(rest_api_v1.cpp) both surface owner / created / last-used columns fromapi_token_store.cpp:516-549(list_tokens— the earlier:325-345anchor pointed at validate-cache logic, not the columns). (The skill matrix previously listed this as PARTIAL — it has in fact shipped.) -
Periodic access-review exportSHIPPED —GET /api/v1/access-reviews/export?format=json|csv(grant-table-driven, orphan grants surfaced, CSV-safe) plusGET /api/v1/access-reviews(list campaigns) and the attestation-campaign lifecycle (POST /api/v1/access-reviews+.../attestations+.../close+GET .../{id}); MCP twinsexport_access_review/open_access_review/record_attestation/get_access_review/list_access_reviews/close_access_review. Enumeratesprincipal_type IN (user, group, engine)— unblocked by the engine-principal program landing first, per the original note. Seedocs/auth-architecture.md"Periodic access reviews". -
Service-account principal typeSHIPPED — the full 4.1–4.5 ladder is merged (the matrix previously said "DESIGNED, not yet built"; that was stale). Theengineprincipal class per ADR-0031: dedicatedEnginePrincipalStore, no login surface, credential-only auth, overlap-pair rotation, default-deny grants. Ladder as merged — 4.1ApiTokenStore→ Postgres +principal_kindseam (#2188); 4.2 the principal class itself — store, RBAC resolution, audit attribution,engine:namespace-collision guard that fails closed at boot (#2192/#2202); 4.3 the operator lifecycle surface — REST/api/v1/engine-principals+{id}/credentials{,/rotate,/confirm}+{id}/roles+{id}/transfer-owner, MCP twins, console, and the no-admin auditor (#2194/#2284); 4.4 per-principal quota cap (#2309 — gate decision extracted intoprincipal_quota_gate.hpp. #2309's "closes #1973" did NOT auto-close it — #1973 issecurity-labelled and so protected from automated closure. It was CLOSED deliberately on 2026-08-07 after an independent human verification againstdev(perdocs/agents/issue-standard.md§5.1, the closure path for asecurityissue); the production-enablement interlock ("the cap must exist before any engine principal is enabled in production") is discharged); 4.5principal_class="engine"as a liveyuzu_http_requests_totallabel value (#2342), which required the resolvedprincipal_kindand so could not be done from presentation (principal_class.hpp:77).Hard invariants (do not regress) — stated precisely, because the routing-table wording overstates two of them:
- Authority resolution is RBAC-only — never the pre-RBAC legacy path, never the service-scoped fallback (403 when RBAC is off or there is no grant, 503 when the store is unavailable). This one is exact.
- Grants are FLEET-WIDE ONLY.
PrincipalRolecarries no per-assignment scope field; a management-group-scoped engine assignment is rejected (the scoped-assignment reject inrest_api_v1.cpp's/engine-principals/{id}/roleshandler, asserted by the scoped-rejection case intest_engine_principal_integration.cpp). Scoped engine confinement is ADR-0017 PR-A / Phase 5 work. Do not describe engine grants as "scoped" — in Yuzu "scoped" is ADR-0017 confinement, a control that does not exist here yet. - Literal admin/built-in roles are structurally barred, via
kEngineDisallowedRolesinvalidate_assignmentplus theis_systemcheck inassign_role. There is nodangerous-class gate — that phrase belongs to Guardian'sdangerous_enforce_in_specand was mis-transcribed onto this function. A custom (is_system=0) role granted unrestricted permissions is auditor-detected, not prevented, and that is deliberate: enumerating "dangerous" permission combinations to hard-block them is trivially bypassable and would falsely advertise completeness (the rationale comment that once stated this inrbac_store.cppwas removed by the ADR-0041 Postgres migration; the posture —kEngineDisallowedRoles+is_system, no wildcard hard-block — still holds in code). Claiming an engine can NEVER hold a wildcard grant is exactly that false advertisement. (The overstateddangerous-class-gate wording lives in.claude/routed-concerns-access-control.md— the engine-principal row, notrouted-concerns.md. Resolved 2026-10-23 (#2485): the row, the user manual, the SOC 2 addendum and the design doc (decision log #15) now state "permitted, detected afterwards by the fail-closed no-admin auditor".)
Remaining: Phase 5 (delegation). RFC 8693 token exchange and write-back are still design-only, as is 2c's Decision-14 confinement choice; both consume
docs/auth-engine-principals-design.mdas their reference. Post-ship hardening: the engine-principal audit-fail-close cluster has since CLOSED (#2454 liveness-cache global-revoke; the REST #2466/#2406 and MCP-twin #3937 audit-fail-close, PRs #3944/#3971 — see the Open hardening backlog note). Still open: #2343 (consolidate the engine-session discriminator ontoSession::is_engine()), #2374 (regression test for MCP stream revocation).
Priority 3 — defer
- Conditional access policies (geo / IP / device posture) — large scope, niche customer ask. Defer until specifically requested.
Open hardening backlog (tracked issues, not features)
Not gaps in the feature matrix — accepted debt on shipped surfaces. Ranked by
what a security reviewer would flag first. (Reconciled against dev
2026-09-07: the engine-principal audit cluster is now fully closed —
#2466/#2406 (REST fail-closed, PR #3944) and its MCP twin #3937 (PR
#3971 merged 2026-09-04, verified an ancestor of origin/dev; issue #3937
CLOSED 2026-09-07 after §5.1 verification) have landed, along with #2454 (engine
liveness-cache global-revoke), #3777 (MFA enroll-race audit branch),
#3762/#3764 (MFA counter/recovery-code guards); all dropped from this
list. Earlier-landed items dropped 2026-09-01: #1973 engine-principal
interlock, #2376 grant-graph topology floor, #2396 login/PG-degrade,
#2395 KEK rotation, #2397 auth-recovery docs, #2399 MFA-store
robustness, #2407 pre-auth body cap. What remains below is all OPEN and
security- or evidence-relevant.)
- RBAC admin-plane cluster (all OPEN, verified 2026-09-28) — these are the
residuals of the Section 1 "RBAC admin plane" row, and the most consequential
open auth items because RBAC still ships OFF: #388 no
[rbac]config key or CLI enable (the oldest report, v0.10.0); #4203 no break-glass — enabling can strand an operator behind 403s, and an SSO-only fleet cannot pass the enable guard at all; #1496 the RBAC-enable visibility lockout (a user with no management-group role sees no agents); #4966 the last-Administrator guard now also covers account deactivation and local-admin demotion (the account-lifecycle guard,docs/user-manual/rbac.md); what stays open is SSO admin recognition (#5182), the inactive-admin view (#5629) and the mixed-version-fleet window (drain old replicas); #2809 a deliberately revoked built-in grant is silently restored at next boot (seed_defaultshas no tombstone); #4972 the access-reviewrbac_enforcementstamp has no freshness / degraded-since signal; #4202 therbac.mdtoggle text (the enable-path half is now corrected ondev; re-check before closing). Custom-role CRUD has no issue of its own here — it is the "Planned" section ofrbac.md. - #4785 — stale role/securable-count twins outside this skill:
SECURITY.md(the one a prospect reads),docs/enterprise-parity-plan.md,docs/capability-map.md, and the.codexcopy of this skill (which is maintained separately from this file). - #2485 — engine-principal authorization doc-overstatement. The "scoped"
half was already corrected in
.claude/routed-concerns-access-control.md(it now describes grants as fleet-wide, not "scoped" — exact wording varies as that file evolves independently). Still live: that same row cites a "dangerous-class gatevalidate_assignment" — the gate exists (kEngineDisallowedRoles+ theis_systemcheck bar literal admin/built-in roles) but "dangerous-class" is Guardian's term, mis-applied, and a custom wildcard-granting role is auditor-detected, not prevented (rbac_store.cppdeliberately refuses to enumerate "dangerous" combos). Doc- honesty, but it feeds security questionnaires, so worth closing deliberately. - #3779 — concurrent
mfa_regenerate_recovery_codesorphans the earlier code set (last-writer-wins on an explicit, user-initiated regenerate — the same class as the enrollment orphan #3762 closed, but arguably acceptable semantics). Decide deliberately: serialize it, or document the last-writer contract. Follow-up from #3762. - #2401 —
yuzu_auth_secret_unavailable_totallacks the cardinality to tell a retry storm from a uniform outage (CC7.2 evidence quality). - #2375 — access reviews cannot distinguish a deprovisioned/terminated
principal from a temporarily-disabled one in
lifecycle_state(CC6.2). - #2398 — extract a shared
build_auth_stack();main.cppandserver.cppduplicate the PgPool → FileKeyProvider → SecretCodec → AuthDB construction chain, so a wiring fix has to be made twice. - #3783 — nightly TSan leg for the live-PG MFA concurrency regressions
(
test_auth_db_pg.cpp) — test-hardening; the concurrency guards are checked by inspection today. Follow-up from #3762. - #3969 / #3970 / #3938 — deferred follow-ups from the now-shipped #3937
MCP fail-close: #3969 the create/revoke/transfer engine-principal twins
share a byte-identical fail-close block but lack direct
[audit_failclose]coverage (mint/rotate/confirm/assign/unassign got the 5 new cases); #3970 agentic-first polish — served tool descriptions + atoken_idin the mint 503 so a caller can reconcile the withheld-secret mint; #3938 theYuzuAuditPersistFailuresalert description omits the engine-principal management surface. All three aregovernance-deferred/roadmappolish, not live defects.
4. Standard workflow for adding an A&A feature
For every feature in Section 3:
-
Read first. In order:
- This skill (current file) for the gap framing.
docs/auth-architecture.mdfor the existing auth surface and hard invariants.docs/enterprise-readiness-soc2-first-customer.md§3.2 for the enterprise/SOC 2 framing..claude/agents/authdb.mdif the feature touches theauthPostgres schema (the former SQLiteauth.db). Note: that agent doc predates the durableSessionStore— for session-store work also read the AuthDB routed-concern row (.claude/routed-concerns-access-control.md) anddocs/adr/2002-high-availability-architecture.md§4, not the stale "sessions are in-memory only" text in the agent doc.docs/mcp-server.mdif the feature touches the MCP surface.
-
Plan. Produce a short plan covering:
- Schema changes (server stores use
pg::PgMigrationRunneragainst their own schema — auth isauth; the legacy SQLiteMigrationRunner::runsurvives only for the remaining SQLite stores, e.g. server-sidenvd_db). - REST surface additions and the RBAC permission required.
- Audit actions (always emit on the
require_admingate side and on every state mutation). - Self-target guard implications (does this destroy/demote a principal?).
- Test plan: unit (
tests/unit/), integration if it touches multiple stores, a puppeteer smoke if it touches the dashboard.
- Schema changes (server stores use
-
Implement with a single PR per feature. Drive every schema change through
pg::PgMigrationRunner(consistent with step 2),HeaderBundle::make()/apply()for any header touch,require_adminfor the admin gate, and parameterised SQL throughout. -
Test. Run
/test --quickbefore commit. Thetests/unit/server/test_auth_db_pg.cppandtest_auth_routes.cpppatterns are the reference. -
Governance. Run
/governance dev..HEADbefore pushing — Gate 2 (security-guardian + docs-writer mandatory deep-dive) plus the AuthDB review agent (.claude/agents/authdb.md) for anyauth_db.*touch. CRITICAL/HIGH findings block merge. -
Docs. docs-writer always picks up the user-manual + REST API updates during Gate 2; verify the change is in the findings report and ship the doc edit in the same PR (or the immediate follow-up).
-
Compliance evidence. For features that close a SOC 2 control gap, add an entry to
docs/security-reviews/for the change record. The compliance-officer agent will catch this in Gate 6.
5. Cross-references
- Routed reference doc:
docs/auth-architecture.md - Engine principals & delegation design (ADR-1005 item 2b):
docs/auth-engine-principals-design.md— third principal class, scoped role assignments, RFC 8693 delegation, credential rotation/lifetime ceilings; the most detailed reference for the token-rotation and service-account-governance gaps in the matrix above. - AuthDB review agent:
.claude/agents/authdb.md - Security review agent:
.claude/agents/security-guardian.md - MCP token + tier policy:
docs/mcp-server.md - Enterprise readiness plan:
docs/enterprise-readiness-soc2-first-customer.md - SOC 2 evidence pattern:
docs/security-reviews/*and audit-log emission viaaudit_store.cpp. - Operator runbook:
docs/ops-runbooks/auth-db-recovery.md.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 465k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 465k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 465k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 192k | Updated | Claude CodeCodex | Verified | Install |