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.

FileKindSize
SKILL.mdskill md18.7 KB
---
name: auth-and-authz
description: 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

| 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 (`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) | Shipped | `auth_routes.cpp:43,386` (`extract_session_cookie`, `Set-Cookie: yuzu_session=…`) |
| 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 — 6 roles × **19** securable types × 6 ops | Shipped (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) | 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`) |

---

## 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 for high-risk approvals** | "2FA/TOTP for high-risk approvals" | CC6.6 | **MISSING** |
| **Hardened-mode local-password disable** | "Disable local-password fallback in hardened mode" | CC6.3 | **MISSING** |
| **Break-glass account policy** (constrained, audited, rotated) | "or tightly constrain break-glass account policy" | CC6.6 | **MISSING** |
| **SAML 2.0 SP** (some enterprises require SAML, not OIDC) | implicit ("SSO enforcement") | CC6.1 | **MISSING** |
| **SCIM v2 provisioning** (auto-provision/deprovision from IdP) | "Periodic access reviews" automation | CC6.2/6.8 | **MISSING** |
| **Just-in-time admin elevation** (time-boxed role promotion + audit) | "Role-based least privilege and separation of duties" | CC6.6 | **MISSING** |
| **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.3 | **MISSING (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.3 | **PARTIAL — 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.3 | **MISSING** |
| **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.6 | **PARTIAL — UI only** |
| **Periodic access reviews** (export of role assignments + attestation flow) | "Periodic access reviews with manager/security attestation" | CC6.2 | **MISSING** |
| **Account lockout after N failed logins** | implicit (auth hygiene) | CC6.3 | **MISSING** |
| **Service-account governance** (separate principal type, no human login) | "Privileged access controls" | CC6.6 | **MISSING** |
| **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 | **MISSING** |
| **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.7 | **MISSING** |
| **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.1 | **PARTIAL — 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

6. **SAML 2.0 SP** with metadata exchange + signed assertion validation.
   Mirrors OIDC's group-to-role mapping. Same enforcement surface as OIDC.
7. **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).
8. **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.
9. **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.
10. **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

10. **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.
11. **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.)
12. **Periodic access-review export** — JSON/CSV of `(user, role, last_login)`
    triples plus an attestation upload endpoint.
13. **Service-account principal type** — distinct from human users, no
    login surface, only token auth, mandatory rotation.

### Priority 3 — defer

14. **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: 471kUpdated 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: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated 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: 194kUpdated Claude CodeCodexVerifiedInstall