@@ -0,0 +1,37 @@
+---
+'@objectstack/spec': minor
+'@objectstack/core': minor
+'@objectstack/rest': minor
+'@objectstack/runtime': minor
+'@objectstack/plugin-auth': minor
+'@objectstack/plugin-sharing': minor
+'@objectstack/service-datasource': minor
+'@objectstack/service-settings': minor
+'@objectstack/service-storage': minor
+'@objectstack/platform-objects': minor
+---
+
+feat(spec,core,plugin-auth)!: an API key answers as its owner's session does when the ADR-0069 policy holds the account, the forced reset gets its own code and an explicit revocation switch
+
+Clause-②: yes (narrowing) — the published contract widens (the posture codes become a closed vocabulary with a declared scope, a new `PASSWORD_RESET_REQUIRED` code, a per-user posture member on the auth service contract, new `@objectstack/core` exports) and the API-key door narrows (a key whose owner holds an account-scope posture is refused where it was served).
+
+<!-- adr-0087: not-required (no-migration-prescription) An authentication-policy change at the API-key admission seam plus one new error code, not a metadata change. No authorable spec key, stored shape or metadata surface is removed or renamed, so `objectstack migrate meta` has nothing to rewrite. `ExecutionContext.authGate.code` narrows from a bare string to the closed posture vocabulary, but that field is server-constructed only and never authored; its one producer already wrote only members of it. What narrows is which API keys are served (a key whose owner owes MFA enrolment is refused with 403 MFA_REQUIRED), and the administrator-forced password change answers its own code. The packages publish (not unpublished), no ADR-0087 id covers this and none is added (not registered or already-registered). -->
+
+**BREAKING** (an accept-set narrowing at the API-key door, and a changed code for the administrator-forced password change), shipped as `minor` under the launch-window convention for breaking changes.
+
+Ruling C′ on #23287: posture codes are a closed vocabulary, and each code declares what it holds.
+
+- **The vocabulary and its scope (`@objectstack/spec/kernel`).** `AuthGateCodeSchema` is the closed set of codes an `authGate` may carry: `PASSWORD_EXPIRED`, `PASSWORD_RESET_REQUIRED` and `MFA_REQUIRED`. `AUTH_GATE_SCOPES` declares each code's scope once: `MFA_REQUIRED` holds the **account** (every credential of the user); `PASSWORD_EXPIRED` and `PASSWORD_RESET_REQUIRED` hold the **credential** (password sign-in alone). `ExecutionContext.authGate.code` is typed against the vocabulary, and `PASSWORD_RESET_REQUIRED` is registered for `@objectstack/plugin-auth` in the error-code ledger.
+- **One per-user posture computation (`@objectstack/plugin-auth`, `IAuthService.resolveUserAuthGates`).** It answers every posture a user holds, most urgent first, keyed by user id and the organization the credential operates in. The session gate shows its first entry, as before.
+- **One judgment at the shared key-admission seam (`@objectstack/core`).** `resolveApiKeyAdmission` asks that computation for the key's owner and holds the key on an account-scope posture (a new `held` outcome). `resolveAuthzContext` resolves a held key as a held principal: the owner, `credential: 'api_key'`, and the posture on `authGate`. Both new inputs are optional (`userAuthGates`), and `userAuthGateSourceOf(authService)` binds one from an auth service.
+- **REST and the runtime dispatcher** judge a key-admitted request by the key's answer, and re-read the session cookie for the gate only when a session admitted the caller. The declared-endpoint fallback does the same.
+- **The raw-host families** take the same answer through the shared seam: datasource admin, share links, settings, and the storage family's door. The webhook-redeliver door admits no API key at all, and still does not.
+- **The forced reset (`POST /api/v1/auth/admin/set-user-password`, the `set_user_password` action).** `must_change_password` now answers `PASSWORD_RESET_REQUIRED` instead of reusing `PASSWORD_EXPIRED`. The act carries `revokeSessionsAndKeys`, **on by default**: it ends every live session of the user and revokes every API key they own, and the response reports what landed (`revoked: { sessions, apiKeys, failed, complete }`).
+
+What changes for you:
+
+- **Refused now:** an API key whose owner owes MFA enrolment past the grace window gets `403 MFA_REQUIRED`, with the message the session gets, on every face that admits keys. It works again the moment the owner enrols, with nothing reissued: the refusal is not a revocation.
+- **Unchanged:** a key whose owner's password expired, or whose administrator forced a password change, keeps working. A session sent beside an API key no longer answers for the key.
+- **A forced password change answers `PASSWORD_RESET_REQUIRED`.** A client that recognises `PASSWORD_EXPIRED` to show its change-password flow should recognise `PASSWORD_RESET_REQUIRED` the same way.
+- **An administrator's password reset now signs the user out everywhere and revokes their API keys by default.** For a routine reset, pass `revokeSessionsAndKeys: false` (or clear the switch in the Set Password dialog). Revoked keys stay revoked after the password change; an administrator can restore a key a routine reset revoked with the Restore API Key action, or the owner mints a replacement.
+- **Hosts calling `resolveAuthzContext` or `resolveApiKeyAdmission` directly** pass `userAuthGates: userAuthGateSourceOf(authService)` to have the key's owner asked. Code switching exhaustively over `ApiKeyAdmission['outcome']` handles the new `held` outcome.
@@ -602,8 +602,17 @@ often before the account-level lock engages.
 > HTTP endpoint), and every route family that a plugin or service mounts
 > directly on the host server and that resolves its own caller, at the family's
 > own door. A gated session gets `403` with the gate's own code
-> (`PASSWORD_EXPIRED` or `MFA_REQUIRED`) at whichever of them serves the
-> request. The auth endpoints (sign-in, change-password, two-factor enrollment
+> (`PASSWORD_EXPIRED`, `PASSWORD_RESET_REQUIRED` for an administrator-forced
+> change, or `MFA_REQUIRED`) at whichever of them serves the request.
+>
+> **API keys answer for the account, not for the password.** Each code has a
+> scope. `MFA_REQUIRED` holds the *account*: an API key whose owner owes MFA
+> enrollment is refused with the same `403 MFA_REQUIRED` and message on every
+> face that admits keys. `PASSWORD_EXPIRED` and `PASSWORD_RESET_REQUIRED` hold
+> *password sign-in* only, so the owner's API keys keep working. The refusal is
+> not a revocation: the same key works again the moment its owner enrolls. A
+> request is judged by the credential that admitted it, so a session cookie
+> sent beside an API key never answers for the key. The auth endpoints (sign-in, change-password, two-factor enrollment
 > and sign-out among them) and a short allow-list kept with that decision
 > (health and discovery among them) still pass, so the user can remediate. Platform administration is not part of that exemption: the
 > platform-admin actions refuse a gated session with the same `403`, a platform
@@ -961,8 +970,10 @@ const response = await fetch('http://localhost:3000/api/v1/auth/admin/create-use
 A generated temporary password is returned **once** in the response (the
 Users-list action reveals it in a one-shot dialog) and is never persisted or
 logged. While `mustChangePassword` is set, the user is blocked with
-`403 PASSWORD_EXPIRED` on every protected route until they complete a
-password change — the same gate and Console redirect as password expiry.
+`403 PASSWORD_RESET_REQUIRED` on every protected route until they complete a
+password change. It is the same gate as password expiry, under its own code,
+and like expiry it holds password sign-in only: the user's API keys are not
+held by it.
 
 #### Set / Reset a Password
 
@@ -971,6 +982,13 @@ password change — the same gate and Console redirect as password expiry.
 same `mustChangePassword` flag. It also provisions a credential account for
 SSO-onboarded users who never had a local password.
 
+The forced reset also carries `revokeSessionsAndKeys`, **on by default**: it
+ends every session of the user and revokes every API key they own, so a
+suspected compromise leaves no live credential behind. Pass
+`revokeSessionsAndKeys: false` for a routine reset. The response reports what
+was revoked (`revoked: { sessions, apiKeys, failed, complete }`), and revoked
+keys stay revoked after the password change.
+
 #### Bulk Import Users
 
 `POST /api/v1/auth/admin/import-users` accepts the same payload shapes as the
 
@@ -122,7 +122,7 @@ are reported as `undecidable` rather than assumed either way.
 
 The same holds twice over for the context. An options argument spelled as a
 literal can be read; one spelled `options`, `{ ...opts }`, or handed through a
-forwarding shim cannot, and **53 of the 225 sites are spelled that way**. A
+forwarding shim cannot, and **53 of the 227 sites are spelled that way**. A
 context resolved from an inline literal or a local `const` can be tested for
 `isSystem`; one arriving from a helper call cannot.
 
@@ -187,10 +187,10 @@ reproduce them. Where it disagrees, it disagrees on the page:
 
 | carried figure | where it survives | this census |
 | :--- | :--- | ---: |
-| 175 write call sites | quoted in the merged changeset | **225** |
+| 175 write call sites | quoted in the merged changeset | **227** |
 | 24 carrying no tenant context | quoted in the merged changeset | **2** provable and tenancy-enabled; **32** more whose options argument is unreadable |
-| 127 of 175 statically decidable, 48 runtime-parameter-name sites | restated on the `isSystem`-scoping card | **154 of 225** decidable, **71** undecidable |
-| 135 (77%) silenced by the `isSystem` guard before the posture gate | the lost issue body — **no surviving corroboration** | **not reproduced**: 120 decidably elevated, 0 decidably not, 97 undecidable |
+| 127 of 175 statically decidable, 48 runtime-parameter-name sites | restated on the `isSystem`-scoping card | **154 of 227** decidable, **73** undecidable |
+| 135 (77%) silenced by the `isSystem` guard before the posture gate | the lost issue body — **no surviving corroboration** | **not reproduced**: 122 decidably elevated, 0 decidably not, 97 undecidable |
 | 141 and 132, two independent re-derivations | the card that filed this work | — |
 
 **The differences are not reconciled, and deliberately so.** The old census's
@@ -207,11 +207,11 @@ would report a smaller number and would not say so.
 
 The fourth row is the one worth flagging to anyone citing it. **The 135 / 77%
 figure has no surviving corroboration anywhere in the tree.** This census reads
-120 of 225 (53%) as decidably elevated, with 97 more whose elevation is a
+122 of 227 (54%) as decidably elevated, with 97 more whose elevation is a
 run-time fact — so the claim is neither confirmed nor refuted, and the honest
 answer is that a static reading cannot settle it.
 
-⇒ **Cite `2 / 225`, and say what it is**: the sites whose options argument was
+⇒ **Cite `2 / 227`, and say what it is**: the sites whose options argument was
 READ and holds no tenant context, against a decidably tenancy-enabled object.
 That is the control's provable yield surface. ⛔ Do not cite it as "the sites
 without tenant context" — **32 further sites** have an options argument this
@@ -223,31 +223,31 @@ cannot read, and they are neither in nor out.
 
 | what | count |
 | :--- | ---: |
-| write call sites on the application surface | **225** |
+| write call sites on the application surface | **227** |
 | …whose object name is statically decidable | 154 |
-| …whose object name is chosen at run time | 71 |
+| …whose object name is chosen at run time | 73 |
 | …against an object with tenancy ENABLED | 153 |
 | …against an object that declares tenancy off | 1 |
-| threading a tenant context | 164 |
+| threading a tenant context | 166 |
 | PROVABLY carrying none (options read, no context key) | **8** |
 | …of those, against a decidably tenancy-enabled object | **2** |
 | options argument UNREADABLE — may or may not carry one | 53 |
 | …of those, against a decidably tenancy-enabled object | 32 |
-| threading a decidably ELEVATED (`isSystem`) context | 120 |
+| threading a decidably ELEVATED (`isSystem`) context | 122 |
 | threading a context that is decidably NOT elevated | 0 |
 | threading a context whose elevation is a run-time fact | 97 |
 
 | how the instrument reached the site | count |
 | :--- | ---: |
-| receiver carried a readable engine type | 187 |
+| receiver carried a readable engine type | 189 |
 | receiver erased, placed by the object NAME | 28 |
 | receiver erased, placed by an `object: string` PARAMETER | 5 |
 | receiver erased, placed by an `UNTYPED_RECEIVERS` row | 5 |
 
 | object name spelled inline | 104 |
 | object name spelled through a `const` | 50 |
 | object name is an `object: string` parameter | 7 |
-| object name is some other run-time expression | 64 |
+| object name is some other run-time expression | 66 |
 
 ### Subtractions the census could NOT defend — enforced
 
@@ -297,12 +297,12 @@ holds still. They are required to be HERE and to say WHEN they were true;
 their values are not compared. The reasoning, and the measurement behind it,
 are in `scripts/check-tenant-audit-census.mjs`.
 
-Measured on 2026-10-14 at `ddcdb46bd`.
+Measured on 2026-10-14 at `f98ac45c5`.
 
 | corpus scale (not enforced) | count |
 | :--- | ---: |
-| tracked non-test sources scanned | 649 |
-| engine-shaped types recognised | 75 |
+| tracked non-test sources scanned | 650 |
+| engine-shaped types recognised | 76 |
 | declared objects in the registry | 116 |
 | same-named calls subtracted as non-engine | 164 |
 
 
@@ -28,7 +28,7 @@ const result = ApiErrorSchema.parse(data);
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **code** | `Enum<'VALIDATION_ERROR' \| 'INVALID_FIELD' \| 'MISSING_REQUIRED_FIELD' \| 'INVALID_FORMAT' \| 'VALUE_TOO_LONG' \| 'VALUE_TOO_SHORT' \| 'VALUE_OUT_OF_RANGE' \| … +326 more>` | ✅ | Error code (e.g. VALIDATION_ERROR; StandardErrorCode ∪ the ledger the serving side registers — ERROR_CODE_LEDGER for framework packages) |
+| **code** | `Enum<'VALIDATION_ERROR' \| 'INVALID_FIELD' \| 'MISSING_REQUIRED_FIELD' \| 'INVALID_FORMAT' \| 'VALUE_TOO_LONG' \| 'VALUE_TOO_SHORT' \| 'VALUE_OUT_OF_RANGE' \| … +327 more>` | ✅ | Error code (e.g. VALIDATION_ERROR; StandardErrorCode ∪ the ledger the serving side registers — ERROR_CODE_LEDGER for framework packages) |
 | **declaredCode** | `string` | optional | The producer-declared code, verbatim, when it is not a member of the closed `code` vocabulary — the open, author-authored channel (app-specific spellings; ADR-0112) |
 | **message** | `string` | ✅ | Readable error message |
 | **userMessage** | `string` | optional | Producer-marked user-facing refusal text, verbatim. Present exactly when the producer opted in at throw time; consumers render it to end users and keep their generic substitution for anything unmarked. Status-agnostic; never replaces `message`. |
@@ -269,6 +269,7 @@ const result = ApiErrorSchema.parse(data);
 * `PASSWORD_ALREADY_SET`
 * `PASSWORD_EXPIRED`
 * `PASSWORD_POLICY_VIOLATION`
+* `PASSWORD_RESET_REQUIRED`
 * `PASSWORD_REUSE`
 * `PAYLOAD_TOO_LARGE`
 * `PERMISSION_NOT_ALLOWED`
 
@@ -436,6 +436,7 @@ const result = ErrorCode.parse(data);
 * `PASSWORD_ALREADY_SET`
 * `PASSWORD_EXPIRED`
 * `PASSWORD_POLICY_VIOLATION`
+* `PASSWORD_RESET_REQUIRED`
 * `PASSWORD_REUSE`
 * `PAYLOAD_TOO_LARGE`
 * `PERMISSION_NOT_ALLOWED`