Oxicloud/docs/plan/opaque-only.md

Plan — Retire legacy password_hash, move to OPAQUE-only

Context

Phases 0–6 of the OPAQUE work shipped a full RFC 9807 substrate alongside the legacy Argon2id password path. The two live in parallel today: every user has BOTH a password_hash column populated (used by POST /api/auth/login) and, for anyone who's logged in at least once since the substrate went live, an opaque_envelope column populated (silent-migrated by Phase 2 on the first successful legacy login). Phase 4 makes legacy login refuse users whose opaque_migrated_at IS NOT NULL — the visible cutover — but the underlying Argon2 hash stays on the row for admin-reset compatibility and as a fallback if OPAQUE ever needs to be disabled.

This plan describes the endgame: remove password_hash from the DB entirely, run the deployment purely on OPAQUE envelopes, and redesign the two flows that today assume the hash exists (change_password, admin_reset_password). It's the "no plaintext password ever touches the server, and no derivable-from-password material lives at rest either" state. Scoped to internal password users; OIDC and magic-link paths are unaffected.

Design conversation captured 2026-08-05 with Ed. Design is locked; timing and ordering are the load-bearing decisions here.

What we gain

1. Complete removal of the offline-brute-force target. Today's password_hash is Argon2id at OWASP interactive params. If a DB dump leaks, that column is where an attacker starts guessing. OPAQUE envelopes are useless without both the passphrase AND the server's OXICLOUD_AUTH_OPAQUE_SERVER_SETUP — a two-secret compromise is qualitatively harder than a one-secret one.

2. has_password becomes obsolete. All the DTO/UI gates that today branch on "does this user have a legacy password" collapse — the only per-user auth-capability signal that matters is "has OPAQUE envelope + which SSO" after the wipe.

3. admin_reset_password gets cleaner. Today it means "admin picks a temp password the user must change." Post-wipe there's no field for the admin to type into — the redesign centres on a recovery-magic-link, which is a nicer UX anyway (user picks their own password without an intermediate temp).

What we lose

1. Legacy-login fallback for OPAQUE-off deployments. After the wipe, an operator flipping OXICLOUD_AUTH_OPAQUE_MODE=off locks EVERY user out (/api/auth/login verifies against NULL password_hash → refuses). The wipe is one-way for the deployment: once OPAQUE-only for a while, no going back short of admin-resetting every user manually.

2. admin_reset_password today (write new hash, force change). The fastest recovery flow — admin types a temp, hands it to the user, done — goes away. Recovery-magic-link is slower (email round-trip, user needs inbox access). Fine for the compromise-recovery case; slightly worse for the "user forgot password, needs immediate access" case.

3. change_password today (verify current-plaintext via Argon2). Loses its verification anchor. Redesign needed (see below).

Preconditions before we start the wipe

Every one of these MUST hold. Adding a pre-flight check in oxicloud opaque wipe-legacy (proposed below) that refuses to run otherwise.

1. OXICLOUD_AUTH_OPAQUE_MODE=opaque_only on the deployment for at least 90 days. Any shorter and we haven't given the fleet a chance to fully migrate — users who log in seldom (monthly, quarterly) need long enough to hit an OPAQUE login and stamp opaque_migrated_at.

2. Every internal, non-OIDC, non-external user has BOTH opaque_envelope IS NOT NULL AND opaque_migrated_at IS NOT NULL. Envelope alone is insufficient — silent-migrated envelopes exist but haven't proven the crypto pipeline works for that user until an actual OPAQUE login has completed. The admin badge from Phase 5 surfaces both signals; the dashboard should report N users still needing at least one OPAQUE login.

3. Manual audit of the "envelope but never migrated" cohort. Any user who has an envelope from silent-migration but never did an OPAQUE login is at risk. Options:

   • Prompt them to log in (email nudge)
   • Admin-reset them manually (they'll re-migrate on next login)
   • Exclude them from the wipe and manually delete their password_hash later once they've done at least one OPAQUE login

4. Recovery-magic-link flow is live and tested. Without it, admin_reset_password has no path forward and the operator can't help any user who ever locks themselves out. Non-negotiable prerequisite.

5. Backups strategy documented. The wipe SQL is one-way. Point-in-time restore of a pre-wipe backup would resurrect hashes on selected rows. Operator needs to know what the recovery path looks like AND what NOT to restore.

The new endpoints

POST /api/auth/opaque/verify-current — proof-of-current-password

Motivation: change_password needs to prove the user knows the current password before accepting a new one. Today it uses Argon2 verify against password_hash. Post-wipe there's no hash, so the proof has to run through OPAQUE.

Shape: mirrors login KE1/KE3 exactly, but the KE3 handler does NOT mint a session. Returns 204 on success, 401 with error_type: "InvalidCredentials" on failure (same wire shape as /login/ke3 — anti-enum). Requires an authenticated session on the request (user is already logged in and just proving they know their own current password).

Wire:

POST /api/auth/opaque/verify-current/ke1  { startLoginRequest }
  → { exchangeId, loginResponse }
POST /api/auth/opaque/verify-current/ke3  { exchangeId, finishLoginRequest }
  → 204 No Content   (or 401 InvalidCredentials)

The userIdentifier is implicit — it's the authenticated caller (from the JWT / session cookie), not something the client re-declares. That closes off "prove you know some OTHER user's password."

State machine: same OpaqueLoginExchange cache we use for login KE1/KE3. Single-use, 60s TTL, anti-replay via .take() on KE3 arrival.

Rate limit: shared with the legacy login limiter, same reasoning as /login/lookup — prevents this from becoming a cheaper offline password oracle than the login endpoint.

POST /api/admin/users/{id}/reset-password-recovery — replaces admin-picks-temp

Motivation: the current PUT /api/admin/users/{id}/password writes a new Argon2 hash. Post-wipe there's no hash to write. Recovery-magic-link is the substitute: admin triggers, server emails, user redeems, user picks their own password.

Shape:

POST /api/admin/users/{id}/reset-password-recovery
  (admin bearer / cookie)
  → 204 No Content   (magic-link dispatched via SMTP)

Server-side flow:

1. Admin-gate check (existing middleware layer)
2. Look up target user; refuse if OIDC-linked (their IdP owns their credentials)
3. Clear OPAQUE envelope + set force_password_change_at_next_login = TRUE in one UPDATE (existing clear_registration — reuse as-is)
4. Revoke all sessions for the target
5. Mint a magic-link scoped to resource_kind = 'password_reset' (new resource kind) with a short TTL (say 1 hour); mail it to the target's registered email
6. Return 204 to the admin

Client-side (user side):

1. User clicks link in email
2. GET /magic/v1/{token} redeems, mints a session tied to resource_kind = 'password_reset', marks the session as "elevated for password reset only" (session claim, checked by middleware)
3. SPA routes to a dedicated set-password page (NOT the usual profile page — the user has no other authenticated capability in this session)
4. User picks a new password → SPA does OPAQUE register (new envelope under new passphrase) — the session's password-reset scope allows the register endpoints
5. Server clears force_password_change on register success
6. SPA revokes the reset-scoped session, prompts a fresh login

Distinct-magic-link-resource-kind matters so a normal login-link token can't be used to change password without proving current-password (which it can't, since login-link users just clicked email — no proof-of-current).

The wipe migration

Delivered as oxicloud opaque wipe-legacy — a dedicated subcommand, NOT a schema migration. Reasons:

• Idempotent (won't re-wipe already-nulled rows)
• Pre-flight refuses when preconditions aren't met (unlike a migration which runs unconditionally)
• Operator-driven, not deploy-triggered — a rolling deploy shouldn't suddenly wipe hashes because the release contained this feature

Pre-flight checks (all must pass, or the CLI refuses):

1. OXICLOUD_AUTH_OPAQUE_MODE is opaque_only in the running server's config (queried via /api/auth/opaque/params or a dedicated admin-only endpoint that reports config)
2. Fewer than N% of internal non-OIDC users lack an OPAQUE envelope AND opaque_migrated_at. N configurable via --allow-unmigrated-percent (default: 0 — strict; operator can raise if some users deliberately never log in and admin has accepted the resulting lockout)
3. Recovery-magic-link is available (SMTP wired + auth methods allow magic-link OR OIDC — the wipe requires a working recovery path)

Wipe SQL (inside the CLI, after pre-flight passes):

UPDATE auth.users
   SET password_hash = NULL
 WHERE oidc_subject IS NULL              -- not OIDC (they don't have a hash anyway)
   AND is_external = FALSE               -- not grant-only recipient
   AND opaque_envelope IS NOT NULL       -- has an envelope to log in with
   AND opaque_migrated_at IS NOT NULL    -- has proven OPAQUE works for them
   AND password_hash IS NOT NULL;        -- still has a hash to wipe (idempotent)

Output: N password_hash columns nulled. M users still have password_hash because they don't meet the OPAQUE-migrated preconditions — inspect via oxicloud opaque wipe-legacy --dry-run and address separately.

The WHERE clause is intentionally strict: OIDC users, externals, and under-migrated users are ALL left alone. The strict version is safer than "wipe everyone" because it can't lock out a user we didn't expect to lock out.

Code cleanups after the wipe

Once every deployment has wiped and enough time has passed (say a year), we can drop the legacy password code:

1. password_hash column: ALTER TABLE auth.users DROP COLUMN password_hash; (new migration)
2. Argon2PasswordHasher service: delete
3. POST /api/auth/login handler: delete (or reduce to a hardcoded 410 Gone with error_type: "LegacyLoginRemoved")
4. AuthApplicationService::login(): delete
5. is_oidc_user() gate in change_password (blocked by task #31 fix discussion): now defended by "no password_hash to verify, must go through OPAQUE-verify-current" — becomes structurally impossible for OIDC-only users to hit change_password
6. has_password field on UserDto / AdminUserSummaryDto: delete (always false, meaningless signal)
7. admin-badge password chip: delete (same reason)
8. oxicloud opaque reset --user X for legacy-recovery: still useful as an emergency lever (envelope somehow corrupted, need to force re-registration via recovery-magic-link), but its "silent-migration handles the recovery" semantics become "recovery-magic-link handles the recovery"
9. Silent-migration hook (Phase 2): delete — nothing to migrate FROM

Deprecation window before each of these: at least one major version. Users who somehow still have password_hash set after the wipe need one more opportunity to log in and complete migration before the column disappears.

OIDC users through the transition

OIDC-linked users never had password_hash populated in the first place (the OIDC-JIT path doesn't write one). They're unaffected by the wipe. change_password refuses them today ("Password changes are not available for SSO/OIDC accounts") — that check STAYS, because their credentials are still IdP-managed and the OPAQUE verify-current handshake would fail anyway (no envelope).

Hybrid users (SSO-linked + local password + OPAQUE envelope) — a real case today, e.g. Ed's own admin account — flow through the wipe like any other internal user: their password_hash gets nulled once they're OPAQUE- migrated. They continue to have SSO available as an alternative login path (independent of the wipe).

Timeline / decision gates

Rough sequencing; each gate is "green when the previous one has been running smoothly for the indicated period."

Gate	Condition	Est. duration
G0	Land per-envelope KSF (A+B+C)	✅ shipped
G1	Land task #31: change_password OPAQUE-lockout fix + hybrid-user password gate	Days
G2	Land recovery-magic-link admin reset flow	Weeks
G3	Land OPAQUE-verify-current + change_password redesign that COMPOSES the two (Argon2-verify AND OPAQUE-verify both work; use whichever the user has)	Weeks
G4	Ship oxicloud opaque wipe-legacy (dry-run only initially, no destructive flag)	Days
G5	Add admin-dashboard metric: "N users still on legacy (password_hash IS NOT NULL AND !opaque_migrated)"	Days
G6	Operator switches deployment to opaque_only mode	✅ already possible
G7	Wait 90+ days at opaque_only, watch the metric drop to 0	Months
G8	Enable destructive flag on wipe-legacy CLI; operator runs it	Minutes
G9	One major version passes without regression	~6 months
G10	Delete legacy code paths (per checklist above)	Days

G3 is the load-bearing one: it's the "change_password works for BOTH legacy and OPAQUE-verified users simultaneously" bridge that lets the fleet migrate at its own pace without a big-bang cutover. Without it, we'd need to atomically switch every user's change-password flow at once, which is hostile to gradual rollouts.

Rollback plan

If we hit trouble AFTER the wipe:

1. Point-in-time DB restore to just before the wipe — resurrects password_hash for the affected rows. Cost: any user changes between the wipe and the restore are lost.
2. If restore is off the table: every affected user needs admin_reset_password (recovery-magic-link flow). Feasible for dozens; painful for thousands.
3. Preventive: keep the wipe's SQL output as an audit log — the CLI prints the count of affected rows; for a large deployment, capture the actual user_ids in a wipe-report.jsonl for the recovery path.

If we hit trouble BEFORE the wipe:

• Just don't run the CLI. opaque_only mode is reversible (flip back to migrate). Users can log in either way as long as password_hash is present.

The wipe itself is the one-way door; everything before it is reversible.

Related work / dependencies

• docs/plan/opaque.md — the original multi-phase OPAQUE plan (Phases 0–6 now shipped as of 2026-08-05)
• Task #31 — change_password OPAQUE-lockout fix (blocker for G1)
• Feedback memory feedback_config_file_overrides_shell — recovery-magic-link flow needs SMTP config; document the operator setup
• Existing magic_link_repo — recovery-magic-link reuses this infrastructure with a new resource_kind variant