Harden reset-admin-password: invalidate other sessions, audit-log it, and test it

[chrismuench]

Summary

Investigated a bug report ("we need a way for an admin to reset the local admin password if they forget it, if they have local admin or sudo on the box"). This already existed (Dispatch.Service reset-admin-password, added months ago) - the actual gaps were:

• No session invalidation (and it was worse than it looked - see below).
• No audit trail. A local CLI reset wrote no audit entry - invisible in System Logs.
• No test coverage. No Dispatch.Service.Tests project exists, and the reset logic was inline in Program.cs.
• No documentation, anywhere - it was briefly in the old README, dropped when docs moved to the Astro site, never covered in docs/SPEC.md at all.

A real bug, found by actually running this against a live service

First commit here extracted the shared password-set logic (AuthEndpoints.SetPasswordAsync) and had the CLI bump webui.session_epoch like /auth/password does, with unit tests against that logic. All green.

Then I actually ran the built CLI against a real running service instead of stopping at unit tests - started the service, logged in, ran reset-admin-password from a separate process while it was running, and checked the old cookie. It was still authenticated:true. The "fix" didn't work.

Root cause: OnValidatePrincipal (ServiceCollectionExtensions.cs) checked the session epoch against ConfigCache, an in-memory snapshot only refreshed within the same request that itself wrote a change (every /config/* endpoint calls cache.LoadAsync after writing its own change). reset-admin-password runs as a separate OS process - there's no way for it to touch the running service's in-memory cache. The database write was correct; the running process just never saw it. This is a pre-existing bug that also affects the dashboard's own in-app password change (same code path), not something the first commit introduced - it was just never exercised end-to-end before.

Fixed by reading the epoch live from IConfigRepository in OnValidatePrincipal instead of ConfigCache. Re-ran the same live test: old cookie now correctly flips to authenticated:false immediately, old password gets 401, new password works.

Changes

• AuthEndpoints.SetPasswordAsync: shared validate → hash → store → bump-epoch-if-replacing logic for both POST /auth/password and the CLI.
• Program.cs's reset-admin-password: calls the shared method, writes an audit entry (actor: local-cli), and now correctly distinguishes "first-run set" vs "reset" in both the audit message and the console output (the live test caught this being wrong too - it said "reset" even on a fresh install with no prior password).
• ServiceCollectionExtensions.cs: OnValidatePrincipal reads the session epoch live, not from ConfigCache - the actual fix.
• AdminPasswordResetTests.cs: unit tests against SetPasswordAsync directly.
• SessionEpochInvalidationTests.cs: an integration test through the real cookie-auth pipeline (a real HTTP request, not just the extracted logic) confirming a cookie issued before an externally-written epoch bump gets rejected after it. Uses its own HttpClient and restores config state in finally so it doesn't leak into the other seven test classes sharing the WebTestHost fixture (ran 5x locally to check for order-dependence).
• docs/SPEC.md: new §17.3 "Password recovery" subsection + a §1.1 delta bullet.
• dispatch-docs' security.md (separate repo, pushed already): a "Forgot the admin password?" section with the per-platform commands.

Test plan

• dotnet build Dispatch.slnx - clean
• dotnet test tests/Dispatch.Web.Tests - 105/105 pass, run 5x to check for flakiness
• dotnet test tests/Dispatch.Core.Tests - 116/116 pass (unaffected)
• Manually verified against a real running service (published binary, real SQLite DB, real HTTP requests): first-run set, a genuine reset with a live session active, old-password rejection, new-password login, and old-cookie invalidation - both before the ServiceCollectionExtensions fix (reproducing the bug) and after (confirming it)
• No em-dashes (repo's no-em-dash lint)

🤖 Generated with Claude Code