Skip to content

DevNullLtd/Yuzu / .codex/skills/auth-and-authz

auth-and-authz

Verified

Authentication & 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:

  1. Current state — what's shipped today and where it lives.
  2. Required state — the enterprise/SOC 2 feature set we owe customers.
  3. 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

CapabilityStatusSource of truth
Local password auth (PBKDF2-SHA256)Shipped (v0.10)auth.cpp:69 pbkdf2_sha256() (OpenSSL PKCS5_PBKDF2_HMAC + BCrypt path)
Persistent auth store (auth.db, SQLite)Shipped (v0.12)auth_db.cpp:222-236 chmod 0600 + L402 MigrationRunner::run; agent-doc .claude/agents/authdb.md
Session-cookie auth (HTMX dashboard)Shippedauth_routes.cpp:43,386 (extract_session_cookie, Set-Cookie: yuzu_session=…)
API tokens — Bearer + X-Yuzu-TokenShippedapi_token_store.cpp (store); both header forms parsed at auth_routes.cpp:108-119
Owner-scoped token revocation (#222)Shippedrest_api_v1.cpp:1058-1082 (owner-vs-admin check at L1060)
Granular RBAC — 6 roles × 19 securable types × 6 opsShipped (Phase 3)rbac_store.cpp:129-193 — types: Infrastructure, UserManagement, InstructionDefinition, InstructionSet, Execution, Schedule, Approval, Tag, AuditLog, Response, ManagementGroup, ApiToken, Security, Policy, DeviceToken, SoftwareDeployment, License, FileRetrieval, GuaranteedState; ops: Read/Write/Execute/Delete/Approve/Push
Self-target principal-destruction guard (#397/#403)Shippedsettings_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 validationShippedoidc_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.0Shippeddirectory_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 ↔ serverShippedmain.cpp:111 --ca-cert flag; peer-cert identity match in agent_service_impl.cpp:47,354
Windows certificate-store mTLS (CryptoAPI/CNG) — agent-side onlyShippedagents/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 + metricsShippedcert_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)Shippedauth.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 orderingShippedmcp_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 403Shipped (gate)auth_routes.cpp:150 inside require_admin
Private-key permission validationShippedcert_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-authShippedserver.cpp:1621 (loopback always unauthenticated; remote behavior toggled by cfg.metrics_require_auth)

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

FeatureWorkstream B lineSOC 2 linkGap class
MFA / 2FA / TOTP for high-risk approvals"2FA/TOTP for high-risk approvals"CC6.6MISSING
Hardened-mode local-password disable"Disable local-password fallback in hardened mode"CC6.3MISSING
Break-glass account policy (constrained, audited, rotated)"or tightly constrain break-glass account policy"CC6.6MISSING
SAML 2.0 SP (some enterprises require SAML, not OIDC)implicit ("SSO enforcement")CC6.1MISSING
SCIM v2 provisioning (auto-provision/deprovision from IdP)"Periodic access reviews" automationCC6.2/6.8MISSING
Just-in-time admin elevation (time-boxed role promotion + audit)"Role-based least privilege and separation of duties"CC6.6MISSING
Inactivity session timeout — auth_db.cpp:363 reserves last_activity_at column with DEFAULT but no UPDATE writes anywhere in the codebase; expiry-only today. Treat as from-scratch work, not a tweak."inactivity timeout"CC6.3MISSING (column reserved)
Session revocation REST surface — DB primitive AuthDB::invalidate_all_sessions() shipped at auth_db.cpp:740 / auth_db.hpp:136, fires only via remove_user/update_role. No DELETE /api/v1/sessions route, no admin UI button."expiration, revocation"CC6.3PARTIAL — DB only
API token rotation workflow — UI-driven pair-of-tokens overlap. No rotate symbols in api_token_store.{cpp,hpp} today; only create + revoke."rotation process"CC6.3MISSING
API token inventory + last-used view — data layer shipped (api_tokens.last_used_at written/read at api_token_store.cpp:291,325-345); dashboard inventory view missing."token inventory"CC6.6PARTIAL — UI only
Periodic access reviews (export of role assignments + attestation flow)"Periodic access reviews with manager/security attestation"CC6.2MISSING
Account lockout after N failed loginsimplicit (auth hygiene)CC6.3MISSING
Service-account governance (separate principal type, no human login)"Privileged access controls"CC6.6MISSING
Conditional access (geo / IP / device posture, optional)implicit ("MFA requirements")CC6.1MISSING (P3)
Sampled auth-log evidence export for auditors"sampled auth logs"CC7.2MISSING
Self-managed Certificate Authority — issuer for (a) mTLS server + agent certs and (b) plugin code-signing certs. CSR API, lifecycle (issue / renew / revoke), audit chain. Today operators must bring their own PKI for both surfaces.implicit ("certificate management lifecycle")CC6.1 / CC6.7MISSING
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 (future) or any public CA / operator-internal CA today.implicit ("supply-chain integrity")CC6.1 / CC7.1PARTIAL — verifier shipped, CA upstream pending

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-key unless --no-https is 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.
  • auth.db 0600 / restricted ACL at create.
  • MigrationRunner::run for any new schema migration.
  • unique_ptr<AuthDB> lifetime spans Server::create().
  • yuzu-server.cfg is a one-shot first-boot seed, not a live source.
  • POST /api/settings/users role field stays ignored; role changes only via the dedicated endpoint.
  • require_admin emits auth.admin_required denied 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.

Priority 0 — needed for first enterprise customer

  1. MFA / TOTP for admin login + high-risk approvals. Standard oath-toolkit compatible; secret generation + QR enrollment + step-up flow on privileged endpoints. Schema additions land via MigrationRunner. New audit actions: mfa.enroll, mfa.verify, mfa.step_up.required, mfa.step_up.passed.
  2. Account lockout after N failed logins. Simple: per-user counter + timestamp in auth.db, reset on success, configurable threshold. Audit: auth.lockout.applied, auth.lockout.cleared. Closes a basic credential-stuffing surface. Lowest-risk P0 to implement first — good workflow shake-out.
  3. Hardened-mode local-password disable. New CLI flag --auth-mode=sso-only; auth_routes.cpp rejects local-password login with a clear message and logs auth.local_disabled. Break-glass account policy: a single named principal exempt from the flag, with mandatory MFA + 24h auto-disable + every action logged at critical.
  4. Sampled auth-log evidence export. New REST endpoint GET /api/v1/audit/auth-sample?from=...&to=...&limit=N admin-only, gated by require_admin, returning a pseudo-random sample. SOC 2 CC7.2 evidence chain.
  5. Session revocation REST surface (promoted from P1 — DB primitive already shipped). DELETE /api/v1/sessions?user=<name> admin-only that calls the existing AuthDB::invalidate_all_sessions() (auth_db.cpp:740) plus an admin-UI "Revoke all sessions" button. Audit: session.revoke_all. Self-target guard applies (admin can't lock themselves out). Cheaper than MFA, same SOC 2 control box (CC6.3 / CC6.8).

Priority 1 — enterprise-friction reducers

  1. SAML 2.0 SP with metadata exchange + signed assertion validation. Mirrors OIDC's group-to-role mapping. Same enforcement surface as OIDC.

  2. SCIM v2 provisioning — auto-create/disable users from the IdP. Reuses auth.db user table; new endpoint surface under /scim/v2/ with bearer-token auth (separate from operator API tokens).

  3. Inactivity session timeout — wire the reserved last_activity_at column at auth_db.cpp:363 end-to-end: per-request UPDATE on every authenticated touch, expiry check inside validate_session() against now - last_activity_at > inactivity_window, configurable per deployment. Treat as from-scratch since no UPDATE writes exist today.

  4. JIT admin elevation — POST /api/v1/elevate accepting a justification

    • duration; promotes the caller's effective role for the window, audits role.elevation.requested|granted|expired. Returns to base role on TTL.
  5. Self-managed Certificate Authority (mTLS + code signing). A single PKI root, server-managed, that operators can use instead of standing up their own CA. Two consumers:

    • mTLS — issue server certs and per-agent client certs against the Yuzu CA so an out-of-the-box deployment doesn't require an external PKI. Today --ca-cert consumes whatever bundle the operator hands over; the new flow lets the server be the CA.
    • Plugin code signing — issue developer signing certs whose chain anchors at the same root, so the agent's --plugin-trust-bundle points at one PEM and the operator can sign their own plugins. The verifier (issue #80, shipped) is already deployment-format-agnostic: same code path accepts public-CA, internal-CA, and self-managed-CA issued certs. The CA closes the operator UX gap, not a security gap.

    Surface required:

    • Schema additions via MigrationRunner: ca_root table (root key + cert + lifecycle), ca_issued table (issued cert inventory + status
      • revocation reason), ca_crl_versions table.
    • REST: POST /api/v1/ca/issue (CSR in, cert chain out), POST /api/v1/ca/revoke, GET /api/v1/ca/crl (DER CRL stream), GET /api/v1/ca/root (root cert PEM, public).
    • Audit actions: ca.root.created, ca.cert.issued, ca.cert.revoked, ca.crl.published.
    • RBAC: gated under the existing Security securable type with Read (root + CRL) / Write (issue) / Delete (revoke) ops.
    • Hardening: root key encrypted at rest using existing auth.db-style 0600 file or, preferred, an HSM/keyring abstraction that today wraps OpenSSL EVP_PKEY and tomorrow can target PKCS#11.

    Plugin code-signing intersects this: when the CA ships, the agent's --plugin-trust-bundle simply points at /var/lib/yuzu/ca/root.pem and the operator's plugin build pipeline calls POST /api/v1/ca/issue to mint a signing cert. No verifier change required.

Priority 2 — long-tail polish

  1. API token rotation workflow — pair-of-tokens overlap window in the dashboard; "Rotate" creates a new token while the old keeps working until the operator confirms cutover.
  2. API token inventory view — surface the existing last_used_at / owner / created_at columns from api_token_store.cpp:325-345 into a sortable Settings → API Tokens UI. (Data layer already shipped; this is a dashboard-only PR.)
  3. Periodic access-review export — JSON/CSV of (user, role, last_login) triples plus an attestation upload endpoint.
  4. Service-account principal type — distinct from human users, no login surface, only token auth, mandatory rotation.

Priority 3 — defer

  1. Conditional access policies (geo / IP / device posture) — large scope, niche customer ask. Defer until specifically requested.

4. Standard workflow for adding an A&A feature

For every feature in Section 3:

  1. Read first. In order:

    • This skill (current file) for the gap framing.
    • docs/auth-architecture.md for 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.md if the feature touches auth.db.
    • docs/mcp-server.md if the feature touches the MCP surface.
  2. Plan. Produce a short plan covering:

    • Schema changes (must use MigrationRunner).
    • REST surface additions and the RBAC permission required.
    • Audit actions (always emit on the require_admin gate 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.
  3. Implement with a single PR per feature. Drive every change through MigrationRunner for schema, HeaderBundle::make()/apply() for any header touch, require_admin for the admin gate, and parameterised SQL throughout.

  4. Test. Run /test --quick before commit. The tests/unit/server/test_auth_db_pg.cpp and tests/unit/server/test_auth_routes.cpp patterns are the reference. Their Postgres cases need YUZU_TEST_POSTGRES_DSN; without it they report SKIP, so set it before treating /test --quick as coverage.

  5. Governance. Run /governance dev..HEAD before pushing — Gate 2 (security-guardian + docs-writer mandatory deep-dive) plus the AuthDB review agent (.claude/agents/authdb.md) for any auth_db.* touch. CRITICAL/HIGH findings block merge.

  6. 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).

  7. 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
  • 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 via audit_store.cpp.
  • Operator runbook: docs/ops-runbooks/auth-db-recovery.md.
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: 466kUpdated Claude CodeCodexVerifiedInstall
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: 466kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 466kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 193kUpdated Claude CodeCodexVerifiedInstall