Credential epoch: per-request revocation check, deployed inert ahead of the user-admin mutations

[mforce]

Design: docs/superpowers/specs/2026-08-01-user-disable-and-email-design.md. Deploy A of three — must ship, and the old fleet must be fully drained, before #356 is exposed.

Why this is its own deploy

Adding a per-request check is a fleet-wide change, not a code change. An old replica runs the pre-epoch pipeline and has no CredentialEpochMiddleware to consult, so during a rolling deploy an Owner could disable a user on a new replica while the load balancer keeps routing that user's pre-deploy access token to an old one — which authorizes it. The suspension would be immediate on part of the fleet, which is worse than a documented delay because nothing surfaces it.

Nothing the mutation does can fix that; the gap belongs to the replica that never learned to enforce. So the gate ships first, inert, and the promise ships after.

This deploy makes no new promise. The only epoch bumps it introduces are the existing password-reset paths, which already revoke refresh tokens today — so on an old replica the behaviour is exactly what it is now, and there is no window of false assurance. It can roll at any pace.

Scope

Storage

// ApplicationUser
public int CredentialEpoch { get; set; } = 1;   // monotonic; the gate
// RefreshToken
public int IssuedEpoch { get; set; }            // the user's epoch when minted

Epoch 0 is permanently retired — the value a row receives when written by something that does not know the column exists, never equal to a live user's epoch. AspNetUsers.CredentialEpoch defaults to 1; refresh_tokens.IssuedEpoch defaults to 0, and every mint site stamps it explicitly (LoginAsync, the rotation, ChangeOwnPasswordAsync's re-issue). That is what makes an old binary's INSERTs inert by construction rather than by timing, since migrate runs before the new serving process (#263).

Cutover. The migration revokes every existing refresh token (UPDATE refresh_tokens SET "RevokedAt" = now() WHERE "RevokedAt" IS NULL) — one forced re-login for everyone. Revocation alone is not sufficient (the epoch separation is what stops a stolen legacy token burning the victim's post-re-login family); it is kept as defence-in-depth, deliberately in the direction where a regressed comparison degrades to lockout rather than to access.

Enforcement. JwtTokenService stamps the claim. New CredentialEpochMiddleware:

UseAuthentication → TenantResolutionMiddleware → CredentialEpoch → MustChangePassword → UseAuthorization → Idempotency

After authentication (before it, every caller looks anonymous and it is inert), before UseAuthorization (applies regardless of AuthPolicies tier), before idempotency (a blocked write burns no key). Look up by both UserId and AccountId — ApplicationUser has no tenant query filter — untracked projection, skip re-execution under IExceptionHandlerFeature, leave auth/logout reachable.

An absent or unparsable claim is a mismatch, not an exemption. Every pre-deploy access token carries no claim and stays valid ~15 min. The codebase's own convention pulls the wrong way here — must_change_password is omitted when false, so "claim absent ⇒ doesn't apply" is an idiom already in hand, and it is correct there. A convention that is right for a feature flag is a vulnerability for a revocation check. Missing/malformed parses to 0, which flows through the ordinary comparison.

RefreshAsync refuses a disabled user and any IssuedEpoch mismatch — ahead of the #176 grace/replay branch, not merely ahead of the rotation. A revoked token reaches RevokeAllActiveForUserAsync before FindByIdAsync loads the user, so a check placed near the rotation never runs on that path; the consequence is a repeatable denial of service (hold a superseded token, wait for the victim to log back in, burn their new family). A mismatch fails inert — generic error, no family revocation. Same-epoch reuse still burns the family, which is #176's actual purpose.

Bumps: all three password-reset paths (self-service, SetUserPasswordAsync, break-glass).

SPA: carry a 401's error title through auth teardown. client.ts turns any authenticated 401 into refresh-and-retry then calls a parameterless onUnauthenticated, and Login.tsx maps every 401 to "invalid credentials" — so a distinct title is necessary but not sufficient. Needed here rather than in #356 so the mutations land on plumbing that already exists.

Tests

• A live access token stops working on the next request after a bump.
• Cutover, against a pre-migration seeded database: a pre-existing refresh token is refused; after the user logs in again the stolen legacy token still cannot burn their new family (revocation alone passes the first and fails this); a pre-migration access token is refused; a default-0 row standing in for an old binary mid-rollout is refused, and refused inert.
• A malformed epoch claim is refused — pinned separately from absent, since they are two code paths and only one is obvious.
• Barrier-controlled: a refresh in flight across a bump leaves no usable child token, asserted by presenting the child, not by checking its access token; a superseded token must not burn the current family; genuine same-epoch reuse still must.
• Middleware ordering asserted explicitly — the guarantee is positional and a silent reorder fails open.

Docs

GLOSSARY.md gains credential epoch. Deployment requirement stated in the repo (portable): deploy B must not be exposed until no process from before this deploy is still serving. The drain mechanism itself belongs to the deployment/ops repo.

Blocks

#356, then #357.

[mforce]

Scope correction from codex round 8 on the spec PR (ea9820e): this deploy carries every reader, not just the epoch mechanism.

Add to the scope above:

• ApplicationUser.DisabledAt / DisabledBy columns ship here, unused by any mutation.
• LoginAsync, RefreshAsync, and StepUpGrantService.IssueAsync all refuse a disabled user as of this deploy.

Why: during #356's own gradual rollout, a disabled user's login or refresh can land on a replica running only this deploy. If the disabled checks shipped with the mutations, that replica would mint a current-epoch token — which every #356 replica then honours, because the epoch is valid. The suspension bypassed by a credential issued after it.

General rule, now in the spec: readers ship before writers, always. A reader deployed early is inert; a writer deployed early is a hole.

Two operational requirements also added:

• The migration sets a short lock_timeout and fails fast. Constant defaults avoid a heap rewrite, but each ADD COLUMN still takes ACCESS EXCLUSIVE, and a long transaction on refresh_tokens from a still-serving old process makes the migrate job wait — with its queued exclusive request blocking login and refresh behind it. DatabaseReadyHealthCheck gates the replacement process, not the old fleet taking traffic.
• revoke-legacy-tokens (the post-drain defence-in-depth verb) has predicate IssuedEpoch = 0 AND RevokedAt IS NULL, preserves existing timestamps, and is repeat-safe — a second run changes zero rows.

[mforce]

Further scope correction (d88b151, codex round 9).

Add to this deploy: RefreshAsync's replay revocation is scoped to the presented token's epoch, not to UserId.

The epoch comparison is a point-in-time read. A request can read IssuedEpoch = E against CredentialEpoch = E and pass — then, before it reaches RevokeAllActiveForUserAsync, a password change or (later) a disable commits E+1 and the user logs in fresh at E+1. The stale request then burns a family minted after the credentials it was checked against were rotated. Denial of service, entered by passing the check rather than skipping it.

Predicate the revocation on IssuedEpoch = stored.IssuedEpoch. Semantically right regardless of the race: theft detection should burn the compromised family, not one issued after the compromise was already answered.

The test must be barrier-controlled — present the revoked epoch-E token, pause after the comparison succeeds, bump and re-login, then release. A sequential test passes with the defect fully present.

This matters in this issue even though disable does not exist yet: the password-reset paths already bump the epoch, so the race is reachable as of this deploy.