OAuth slice 2: fail-closed checks on the OAuth path (disabled, suspended, must-change-password, flock scope, rate limit)

[mforce]

Slice 2 of #788. Depends on #795. This is the slice that does the security work.

An OAuth-authenticated request bypasses CredentialEpochMiddleware, where the app runs its per-request fail-closed checks for JWT callers. This slice must re-establish every one of those checks on the OAuth path. The OAuth path inherits none of them for free.

Checks that must run on every OAuth-authenticated request

Check	Why	Existing reference
User disabled	A disabled worker's assistant must stop immediately	CredentialEpochMiddleware reads DisabledAt
Farm suspended	A suspended account's assistants must stop	The same correlated read, Account.IsActive (#532)
Must-change-password	When the app forces a user to change their password, it blocks everything except the change (#283). An assistant that kept working would bypass that gate
Flock scoping	A worker assigned to two flocks must see only those two through their assistant (#388). This is the hazard #787 is open about. Make it deliberate
Rate limits	An assistant calls far faster than a human. The limit must key on the shared IFixedWindowCounter (#543/#544), never a process-local limiter. A process-local limiter is the #271 blocker shape, which earlier derivations got wrong twice

Instant revocation

#788 chose reference tokens so that disconnecting an assistant takes effect on the next call. Verify this end to end. Revoke, then assert that the next request fails. This app does an uncached per-request credential read (#364) because revocation must not wait for an expiry.

Scheme coexistence

This will be the second authentication scheme the app has ever registered. Today there is only AddJwtBearer, with no AddPolicyScheme. Decide and document how the app routes a request to the right handler, and make sure the app cannot mistake an OAuth token for a session JWT or the reverse.

Guards

Per AGENTS.md, each check needs a test that states its red mutation. The test most likely to go wrong asserts FlockScope.IsUnrestricted instead of IsResolved. IsUnrestricted defaults to true, so a guard written against it passes while the hole stays open. docs/plans/770-mcp-server/02-guards.md documents that exact trap.

Done when

Each check has a test that fails when the check is removed, and a revoked token stops working on the next request.

[mforce]

Two corrections from an adversarial review of the design. Both change what this slice must do.

1. Roles are not read live, so this slice must decide how they stay fresh

The design previously claimed that a database-validated credential means the app reads roles live, so a demoted user's access narrows automatically. That is false. TenantResolutionMiddleware copies roles from token claims (context.User.FindAll("role")), and AuthPolicies.EffectiveRole reads IsInRole/FindAll("role") off the principal. Nothing reloads roles from the database on a request.

Today, revocation keeps roles fresh. A role change bumps CredentialEpoch, and the app rejects the next request that carries the old token. Freshness comes from the revocation mechanism, not from how the credential is stored.

If this slice does nothing, a Manager demoted to ReadOnly keeps Manager authority indefinitely through an already-issued OAuth token. The token is valid, and the app computes the scope intersection against a stale role. Both gates pass.

Choose one explicitly:

1. Carry credential_epoch in the OAuth principal and let the existing check revoke on role change. This reuses the mechanism and costs nothing new. A demotion disconnects the assistant, which must then reconnect.
2. Reconstruct roles live before authorization and flock resolution. The assistant survives a demotion with narrowed authority. The cost is a read per request and a second freshness mechanism to maintain.

Whichever option you choose, test it. Demote a user who holds an already-issued OAuth token and assert the outcome.

2. The design described the middleware boundary wrongly

The design said an OAuth request "bypasses CredentialEpochMiddleware". That is wrong in both directions. The middleware inspects any authenticated principal and has no scheme exemption. It will run for an OAuth caller, and it will reject a token that carries no credential_epoch claim.

The checks also have different owners at different points:

Check	Owner	Position
Flock scoping	FlockScopeResolutionMiddleware	before the epoch check
Credential epoch, disabled user, suspended farm	CredentialEpochMiddleware	middle
Must-change-password	MustChangePasswordMiddleware	after it. Enforcement depends on the claim being supplied, not only on the middleware running
Rate limits	UseRateLimiter	before authentication, and opt-in per endpoint, so /mcp must opt in explicitly

The implementable requirement is to authenticate OAuth during UseAuthentication. The resulting principal must carry the same claims a session JWT does: sub, account_id, credential_epoch and roles. The existing chain then applies unchanged. Authenticating later misses tenant, user and flock resolution entirely.

3. Instant revocation is not a property of the token format

The design chose reference tokens so Disconnect takes effect on the next call. The format alone does not deliver that. OpenIddict validates token entries for reference tokens but does not check authorization-grant status by default. Revoking a stored authorization can therefore leave its access tokens usable. UseLocalServer() enables token-entry validation, not authorization-entry validation.

This slice must state exactly what Disconnect revokes and what each request validates. If Disconnect revokes the authorization, the slice must call EnableAuthorizationEntryValidation(), and issued tokens must carry the authorization id. This matters more here than usual because lifetimes are indefinite. A token that outlives its revoked authorization never expires on its own.

Test both directions. The app must reject an existing access token, and it must reject a refresh.

[mforce]

Amendment, 2026-10-06: what #514 and #787 changed for this slice

The body and the 2026-09-13 comment stay as written. Paths were checked against main at 8cb14e67.

• Epoch check. CredentialEpochMiddleware still reads sub, account_id and credential_epoch from the principal. It now delegates the database read to ICredentialEpochVerifier in the Access contract ([C] #514 slice 15: Access contract — security hold point, runs last #857), and that read also checks Account.IsActive. An OAuth principal carrying the same three claims passes through it unchanged. That makes option 1 in the comment above (carry credential_epoch) a fit with no contract change. Option 2 (reconstruct roles live) would need a new Access contract method.
• Ordering with Access. The epic's 2026-09-14 note planned Modular-monolith architecture design + implementation plan (from PR #423) #514's Access work to run after this slice. Access shipped first. This slice now works against the Access contract and has no one to race in CredentialEpochMiddleware.
• Flock scope. FlockScopeGuard's fail-open branch grants account-wide flock access to an unresolved actor #787 is closed. FlockScopeGuard now returns Auth.Unauthorized for an unresolved actor before it reads assignments. The body's "the hazard FlockScopeGuard's fail-open branch grants account-wide flock access to an unresolved actor #787 is open about" is out of date. Flock-scoped writes through an OAuth principal fail closed if the actor does not resolve. Reads still depend on FlockScopeResolutionMiddleware resolving the scope, so the IsResolved versus IsUnrestricted trap in the body still applies.
• Placement. The OAuth authentication handler and any revocation wiring belong to Access (src/Cluckwork.Infrastructure/Modules/Access/, registered in AddCluckworkIdentity). The analyzer rule CW1004 is a build error for code outside Access that names Access-internal types.