Closes the leaked-key revocation gap from RBAC M3/M6 (#3054). Editing users[].api_key_hash via update_user (or by hand in config.toml) only becomes effective after a daemon restart today, because AuthState.user_api_keys is a frozen Arc<Vec<…>> snapshot built once at boot. A leaked per-user bearer token therefore stays valid until the operator restarts the daemon — exactly the scenario rotation needs to defeat.

Surface

POST /api/users/{name}/rotate-key

• Owner-only — covered by the existing is_owner_only_write allowlist for /api/users/* non-GET (no middleware change needed; the prefix match in middleware.rs:109 already blocks Admin/User/Viewer).
• No request body. Server generates a 32-byte random hex plaintext, hashes with Argon2id via the existing password_hash::hash_password, persists via the existing persist_users path.
• Response shape:

  { "status": "ok", "new_api_key": "<plaintext, 64 hex chars>", "sessions_invalidated": <count> }

  The plaintext is the only time the server exposes it. Audit log records RoleChange with detail "api_key rotated by <actor> for user <name>" and the caller's user_id — never the plaintext.

Why owner-only

Rotating a user's key is a credential-management action with the same blast radius as user create/delete. Without an Owner gate, any Admin per-user API key could rotate the Owner's key and lock everyone else out — exactly the self-promotion attack the existing is_owner_only_write allowlist exists to block. Self-rotation through this endpoint is also denied for the same reason; users who want a fresh key ask an Owner.

How session invalidation works (the load-bearing part)

SessionToken (the value stored in AppState.active_sessions) does not carry a user_id. Reading the auth flow at middleware.rs:603-668:

1. The active-sessions store holds dashboard tokens issued by /api/auth/dashboard-login, keyed by opaque token, tied to the single shared dashboard_user/dashboard_pass credential pair — not per-user.
2. Per-user API key callers never land in active_sessions at all. Their bearer token is hashed against each entry in auth_state.user_api_keys via Argon2 verify.

So the actual revocation primitive is the user_api_keys snapshot, not active_sessions. To make swapping that snapshot work this PR converts AuthState.user_api_keys from Arc<Vec<ApiUserAuth>> to Arc<RwLock<Vec<ApiUserAuth>>> and shares the same Arc with AppState.user_api_keys. After persist_users finishes the on-disk write + kernel reload, it now also rebuilds the in-memory snapshot — which means the next request that presents the OLD plaintext immediately fails Argon2 verify against the freshly-rotated entry. The same refresh fixes the latent bug for update_user / delete_user / import_users along the way (they were all silently waiting for a daemon restart before).

I considered also clearing active_sessions in the rotate path, but rejected it: those sessions belong to the dashboard credential pair, not the rotated user, and clobbering them on every per-user rotation would force the operator to log back into the dashboard. If a future change ties dashboard sessions to a UserId, the rotate path can extend sessions_invalidated to include those evictions; today the count reflects the per-user-bearer-token kill, which is the actual revocation that matters for this surface.

Files

Backend

• crates/librefang-api/src/routes/users.rs — rotate_user_key handler, RotateKeyResponse, generate_api_key_plaintext, rebuild_api_user_records, and the state.user_api_keys refresh wired into persist_users after the kernel reload.
• crates/librefang-api/src/middleware.rs — AuthState.user_api_keys field type change + read-once snapshot at the top of auth() so each request only takes the lock once.
• crates/librefang-api/src/routes/mod.rs — AppState.user_api_keys field.
• crates/librefang-api/src/server.rs — share the new Arc between AppState and AuthState (mirrors the existing api_key_lock pattern).
• crates/librefang-api/src/openapi.rs — register the new path and response schema.

Dashboard

• crates/librefang-api/dashboard/src/api.ts — rotateUserKey() + RotateUserKeyResponse.
• crates/librefang-api/dashboard/src/lib/http/client.ts — re-exports.
• crates/librefang-api/dashboard/src/lib/mutations/users.ts — useRotateUserKey() with userKeys.lists() / userKeys.detail(name) invalidation in onSuccess.
• crates/librefang-api/dashboard/src/pages/UsersPage.tsx — "Rotate API key" button per row (only shown when has_api_key), confirm modal, and a copy-once display modal that makes the "this won't be shown again" wording explicit.

Tests

• crates/librefang-api/tests/users_test.rs (new tests):
  • users_rotate_key_returns_new_plaintext — happy path, asserts 64-char hex
  • users_rotate_key_persists_new_hash — on-disk round-trip, hash differs from seed
  • users_rotate_key_invalidates_existing_session — the load-bearing test: pre-populates the live snapshot, rotates, asserts the OLD plaintext stops verifying and the NEW plaintext starts verifying
  • users_rotate_key_unknown_user_404
  • users_rotate_key_preserves_other_fields — RBAC M3 policy + memory_access + bindings + role survive rotation (regression cover for the M5/M3 preserve pattern)
• crates/librefang-api/tests/api_integration_test.rs:
  • users_rotate_key_admin_returns_403 — full-stack owner-only gate via start_test_server_with_full_user_configs. Asserts both Admin-rotates-other and Bob-self-rotates get 403, mirroring the spec's pointer to users_policy_put_owner_only.
  • start_test_server_with_full_user_configs now mounts routes::users::router() so the gate can actually be exercised end-to-end.

Test-harness alignment (mechanical)

Every existing AppState constructor (5 test files + routes/agents.rs + librefang-testing) gets user_api_keys: Arc::new(tokio::sync::RwLock::new(Vec::new())), and every AuthState constructor in middleware.rs tests is updated to wrap its user_api_keys in the same RwLock. No semantic changes — the tests still assert the same things.

Test plan

• CI builds (cargo build --workspace --lib)
• CI tests (cargo test --workspace) — new tests above pass alongside the 2100+ existing
• CI clippy (cargo clippy --workspace --all-targets -- -D warnings)
• CI dashboard typecheck + build
• Manual smoke (post-merge):
  • Seed a user with an API key, hit a protected endpoint with the old plaintext → 200
  • POST /api/users/{name}/rotate-key → response carries new_api_key
  • Hit the same protected endpoint with the OLD plaintext → 401 (the actual session kill)
  • Hit it with the NEW plaintext → 200
  • Restart the daemon, repeat with the NEW plaintext → still 200 (persistence)

Follow-ups not in scope

• Self-service rotation for non-Owner users — would need a separate scoped endpoint with a fresh-credential-required gate; intentionally out of scope here.
• Tying dashboard SessionToken to a UserId so rotate can also evict dashboard sessions for the rotated user. Requires a schema change to SessionToken; not load-bearing for the per-user API key surface this PR fixes.
• The spec mentioned subtle for constant-time comparison — not used in this PR because Argon2 verify already gives constant-time semantics, and the plaintext returned is fresh per-rotation so there's no comparison risk on the response path.

Review follow-ups (post-initial-review)

Atomicity hole in the persist path (race window)

Initial implementation took the state.user_api_keys.write() lock AFTER the file write + kernel reload. Between the std::fs::write and the *state.user_api_keys.write().await = … swap, the kernel config already carried the new hash but the in-memory Vec<ApiUserAuth> the auth middleware actually verifies against still held the OLD record. Any request landing in that window — bounded by reload_config latency, but exploitable under load — would still authenticate with the just-rotated plaintext.

Fix (crates/librefang-api/src/routes/users.rs::persist_users): acquire state.user_api_keys.write() BEFORE the disk write, hold the guard across persist + reload + snapshot rebuild, drop only after the swap. Concurrent auth checks now either see the pre-rotation snapshot (fully consistent with the file at the moment they observed it) or block on this writer until the swap completes; never the in-between read where on-disk and live state disagree. Hold time is bounded by reload_config (a config reparse + a few inner RwLock writes — ms scale), and authentication blocking with the rotated key is the correct behavior.

Regression-guard test added in crates/librefang-api/tests/users_test.rs::users_rotate_key_snapshot_consistent_with_disk_post_return: asserts the on-disk hash and the live user_api_keys snapshot for the rotated user agree immediately after the handler returns 200. The deterministic content-level guard remains users_rotate_key_invalidates_existing_session.

Audit detail: short fingerprint of the OLD api_key_hash

Initial detail string was "api_key rotated by {actor} for user {name}" with no reference to the just-revoked credential. Forensically useless when correlating with an authentication-failure log line auth failed with leaked key X.

Fix (crates/librefang-api/src/routes/users.rs::rotate_user_key): capture the OLD api_key_hash from the persist_users closure (now returns Option<String>), compute sha256(old_hash) truncated to the first 8 hex chars (32 bits — a hash-of-hash, no plaintext or reversibly-related material), and append (old: {fingerprint}) to the audit detail. First-time key assignment via rotate (no prior hash) renders as (old: none) so downstream parsers see a stable shape.

Helper: api_key_hash_fingerprint(&str) -> String (uses the existing workspace sha2 dep).

Tests added:

• users_rotate_key_audit_includes_old_hash_fingerprint — asserts the audit detail contains (old: <expected fingerprint>) and that none of {old plaintext, new plaintext, full old hash} leak into the audit detail.
• users_rotate_key_audit_old_none_when_no_prior_hash — first-time-key rotation produces (old: none).

Title alignment with gate

Title now reads "owner-only" to match the actual is_owner_only_write gate at middleware.rs (was previously "admin-only"). The Owner gate is the right policy for this surface — same blast radius as user create/delete; an Admin per-user key able to rotate the Owner's key would lock the Owner out of their own deployment.