Merge branch 'main' into claude/issue-16344-readonly-hook-input

Author: os-sam

.changeset/adr-0112-envelope-refusal-declaration.md

@@ -0,0 +1,17 @@
+---
+"@objectstack/spec": minor
+---
+
+feat(spec): the ADR-0112 error envelope gains a producer-side `refusal` declaration, so a deliberate 5xx refusal can keep its caller-authored `message` (#16335)
+
+`ApiErrorSchema` and `EnhancedApiErrorSchema` declare one new optional key, **`refusal: true`** — the producer's declaration that the 5xx it named is a deliberate REFUSAL whose `message` is authored for the caller, so the boundary keeps that message verbatim instead of withholding it. Director ruling, decision batch #58 (2026-09-06, option C): the refusal/fault distinction is a producer-side declaration on the published envelope — not a status heuristic and not a second allow-list.
+
+The three cases are now documented side by side on the envelope's TSDoc:
+
+- **undeclared 5xx** (no `status` on the throw) — unchanged: the leak heuristic decides per message.
+- **declared fault** (`status >= 500` + `code`, nothing declared here) — unchanged, and still the DEFAULT: `message` is withheld from the body and logged for the operator.
+- **declared refusal** (`status >= 500` + `code` + `refusal: true`) — new: `message` is kept verbatim, bounded exactly as a 4xx message is.
+
+Purely additive: a producer that says nothing here gets exactly the previous behaviour. `true` is the only value — `refusal: false` fails parse instead of becoming a third state consumers would have to interpret. `userMessage` is orthogonal (end-user text; it never replaces `message`) and may ride the same envelope; the TSDoc reconciles this flag with the recorded reason `userMessage` is a text-carrying field rather than "a boolean beside `message`".
+
+This is the spec half. The relay half — the three withhold arms reading the declaration (two in `@objectstack/rest`: `declaredServerFaultAnswer`, and `resolveErrorResponse`'s own 5xx passthrough arm, which the `/references` door reaches; one at `@objectstack/runtime`'s dispatcher exit, `errorResponseBase`, which `objectstack serve` mounts and which never consults the first), plus retiring the route-local patch from PR #16143 on `/meta/:type/:name/references` — is #16146 for the REST pair and its sub-issue #17153 for the runtime exit; until they land, a declared refusal is still withheld at the wire.

.changeset/approvals-terminal-run-status-exhaustive.md

@@ -0,0 +1,13 @@
+---
+"@objectstack/plugin-approvals": patch
+---
+
+fix(approvals): the dead-run sweep classifies every `ExecutionStatus` member, so a `refused` run releases its pending approval (#16433)
+
+`ApprovalService.releaseDeadRunRequests` guarded on a hand-copied four-member subset of `ExecutionStatus` — `completed`, `failed`, `cancelled`, `timed_out` — written when that enum had eight members. #14945 then appended `refused`, documented on the enum as *"Terminal, never resumed"*, and the subset did not grow with it. A run in `refused` was therefore skipped by the sweep, so a still-pending approval on it read as ALIVE, was never released, and kept its record lock forever.
+
+**Why this is shipped as a fix rather than left alone.** Nothing inside this repo drives a run to `refused` yet — that is #15788 (lane 2 of the #14945 ruling), still open. But `ApprovalService` takes a HOST-supplied automation surface through `attachAutomation`, so a host whose `getRun` already answers with the status the published spec declares sees the corrected behaviour the moment it upgrades, rather than on the day lane 2 lands. That is a real behaviour change in a published package, which is why it carries a bump instead of `skip-changeset`.
+
+The repair is not "add `refused`" — that yields a five-member hand-copy with the identical trap re-armed for the tenth member — and it is not "derive the terminal set from the enum" either, since `running` and `paused` are plainly not terminal and a wholesale derivation would default every future member to terminal, i.e. to releasing approvals out from under LIVE runs. Instead the file now declares a **total map** over `ExecutionStatus`, classifying each member `terminal` or `live`, from which the terminal set is derived. A tenth member fails to compile until someone classifies it, and fails a test as well.
+
+No API change: the classification is module-internal and the package barrel is untouched.

.changeset/artifact-granted-permissions-load-binding.md

@@ -0,0 +1,15 @@
+---
+'@objectstack/runtime': minor
+---
+
+Bind an environment artifact's install-time GRANTED permission set to the packages that artifact materializes.
+
+`EnvironmentArtifactSchema.grantedPermissions` — the consented `{ services, hooks, network, fs }` set the control plane compiles onto the artifact at install-consent time (ADR-0025 §3.5 step 2 / F4) — now reaches `PluginPermissionEnforcer.registerGrantedPermissions` at materialize time, one call per consent record, keyed by the plugin manifest `id`. `AppPlugin.init()` performs the binding, so it happens on every path that turns an artifact into a kernel plugin without either caller changing a line, and the enforcer holding the result is readable as `AppPlugin.permissionEnforcer` (with `AppPlugin.grantBinding` recording what bound).
+
+Absent, `{}` and a consented entry stay three distinct states. An artifact carrying no `grantedPermissions` key allocates no enforcer and registers nothing, so a package with no consent record loads exactly as it did; a per-plugin `{}` is a consent record that consented to nothing and registers a bag that denies every service, hook, host and path. A consent record naming a package the artifact does not carry is reported at `warn` rather than passing in silence.
+
+Fixed alongside, because without it the binding was unreachable: the `{ schemaVersion, metadata }` envelope unwrap in `loadArtifactBundle` handed the kernel `metadata` alone and dropped every key standing beside it, so an envelope artifact reached the kernel with `grantedPermissions` stripped. The loss was silent and indistinguishable from the legitimate absent reading. The unwrap now carries the key across when the envelope declares it, `{}` included, and never invents one.
+
+New exports from `@objectstack/runtime`: `registerArtifactGrantedPermissions`, `resolveArtifactGrantBinding`, `carriedPackageIds`, `ArtifactGrantBinding`.
+
+This is the registration half. Access-time enforcement runs through `SecurePluginContext`, which no production path constructs; that seam is ADR-0025 install-flow work and is unchanged here.

.changeset/auth-gate-allowlist-anchored.md

@@ -0,0 +1,13 @@
+---
+"@objectstack/core": patch
+---
+
+`isAuthGateAllowlisted` matches allow-listed routes at a mount boundary, so an object named `auth` or a record whose id is `health` no longer bypasses the ADR-0069 authentication-policy gate.
+
+The predicate that decides which paths are exempt from the password-expiry / enforced-MFA gate matched with two UNANCHORED tests: `path.includes('/auth/')` matched at any position, and an `endsWith` test over `['/health', '/ready', '/discovery', '/me/apps', '/me/localization']` matched at any depth. A path segment whose VALUE merely spelled one of those tokens therefore carried the exemption — and object names and record ids are tenant-controlled. Both transport seams hand the predicate a data-plane path directly (`HttpDispatcher.enforceAuthGate` passes `cleanPath`, `RestServer.enforceAuth` passes `req.path`), so these were reachable requests. Measured on the built package before the repair: `/data/auth/123`, `/meta/auth/objects`, `/data/x/health` and `/data/xyz/me/apps` were all exempt, while `/auth/me` (exempt) and `/data/contacts/1` (gated) held as controls.
+
+- **What replaced them.** The path is read as segments and each test is anchored to a mount base — `/api/v1`, `/api`, or the empty base the dispatcher sees (the hono adapter hands `dispatch()` the app prefix already stripped) — plus at most one environment scope immediately after that base (`/environments/<id>`, or ADR-0006's superseded `/projects/<id>`), because the dispatcher evaluates the gate before its scoped-URL strip. `/auth/…` at that position stays exempt; the five bootstrap reads are EXACT routes there instead of suffixes. The scope is only recognised immediately after a base, which is why `/data/environments/x/health` is not a scoped `/health`.
+- **This only ever removes exemptions.** Measured, not asserted: over a generated corpus of 111,152 paths, the number that are newly exempt is **0** and 25,979 stopped being exempt. The check is kept as a test, with the pre-anchoring predicate transcribed beside it, so a later widening cannot arrive quietly.
+- **Every genuinely-exempt shape still is**, pinned in both directions: `/auth/sign-out`, `/health`, `/ready`, `/discovery` (dispatcher shapes); `/api/auth/sign-in`, `/api/v1/auth/change-password`, `/api/v1/auth/me/permissions`, `/api/v1/health`, `/api/v1/me/apps`, `/api/v1/me/localization`; and the scoped `/api/v1/environments/<id>/auth/sign-out`.
+
+**If you serve the API from a non-default mount,** an allow-listed route reached as `${basePath}/${version}/…` with `basePath`/`version` moved off `/api` and `v1` is no longer named by the allow-list. That price cannot be avoided: `/rest/v2/health` and `/data/xyz/health` are the same shape, so a rule that accepts an arbitrary base is the defect itself. It costs nothing at either live seam — the dispatcher's path arrives base-stripped, and REST registers its control-plane routes without `enforceAuth` at all — but if you gate a custom mount through this predicate, mount the remediation routes under one of the named bases.

.changeset/client-adopts-rotated-session-token.md

@@ -0,0 +1,27 @@
+---
+"@objectstack/client": minor
+---
+
+feat(client): a bearer-mode `ObjectStackClient` keeps the session the server rotates it onto (#16534)
+
+Three better-auth routes ROTATE the caller's session on success — they mint a new session, install it in `Set-Cookie` (and, through `bearer()`, in the `set-auth-token` response header), and DELETE the row the caller was presenting:
+
+| route | where the new credential is |
+| --- | --- |
+| `auth.twoFactor.verifyTotp()` on the enrolment lane | body — `token`, and it is the LIVE one (plugin-auth's `two-factor-rotated-token-echo` repairs the vendor's stale echo) |
+| `auth.changePassword({ revokeOtherSessions: true })` | body — `token` |
+| `auth.twoFactor.disable()` | **response header only** — the body is `{ status: true }` |
+
+A browser is carried across all three by its own cookie. A bearer client — this SDK's own mode — kept presenting the DELETED session's token, so its very next call answered `401 UNAUTHORIZED`. Measured against a real `AuthManager` (better-auth 1.7.2) over a real driver, driven through the real `ObjectStackClient`, `login → enable → verifyTotp → disable → deleteUser` could not run to the end without the caller re-seating `client.token` by hand between the steps.
+
+The three methods now adopt the rotated credential themselves, the way `login()` already adopts the token it is handed. The `token` members stay on the wire and stay declared, so a caller that keeps its own credential store is unaffected; what changes is that it no longer has to.
+
+**No public surface moves.** No new export, no new option or flag, no new key on any declared request or response type — the SDK stores a token the server already sends and this package already declares. Graded `minor` rather than `patch` because the published runtime behaviour of three methods moves for existing callers.
+
+## What does NOT change, deliberately
+
+The adoption is on those three routes only, never in the shared `fetch` wrapper. `set-auth-token` rides **every** response that stages a session cookie — `POST /update-user` stages one to carry the updated user without rotating anything — and it carries the SIGNED `<token>.<sig>` spelling while every JSON `token` echo carries the UNSIGNED one. A wrapper-level read would therefore rewrite the stored credential into a different spelling of the SAME session on ordinary traffic. `auth.me()`, `auth.sessions.list()`, `auth.updateUser()` and `auth.twoFactor.verifyBackupCode()` (which does not rotate — the vendor echoes the session it resolved at entry) all leave the stored credential byte-identical, and that is pinned.
+
+A cookie-only deployment sends no `set-auth-token`; there is then nothing to adopt and `twoFactor.disable()` leaves the stored credential exactly as it was. `changePassword` without `revokeOtherSessions` answers `token: null` and likewise stores nothing.
+
+The three TSDoc warnings that told bearer callers "this SDK does not store it" are updated in the same change.

.changeset/client-get-session-envelope-and-refresh-read.md

@@ -0,0 +1,64 @@
+---
+"@objectstack/client": patch
+---
+
+fix(client): `auth.me` / `auth.refreshToken` deliver the `SessionResponse` envelope they declare, and `refreshToken` reads the token the route actually serves (#16760)
+
+Both methods annotate their return as `SessionResponse` — ObjectStack's REST
+`{ success, data }` envelope — for `GET /api/v1/auth/get-session`. better-auth
+owns those bytes and answers **bare**. Measured against a real `AuthManager`
+(better-auth 1.7.2, organization plugin) over a real driver:
+
+```
+GET /api/v1/auth/get-session  (signed in) -> 200 {"user":{…},"session":{…,"token":"…"}}
+GET /api/v1/auth/get-session  (anonymous) -> 200 null
+```
+
+So `(await client.auth.me()).data.user` type-checked and was `undefined` at
+runtime, while `.user` — the real payload — did not type-check. The annotation
+pointed every caller at the wrong key.
+
+## What changed
+
+- The bare answer is now lifted into the declared envelope, the same lift
+  `auth.login` has always carried for `/sign-in/email`. `SessionResponse` is
+  **unchanged** and so is each method's published return annotation: the fix is
+  in what the methods produce, not in what they promise.
+- The lift fills `success` as well as `data`. `SessionResponseSchema` is
+  `BaseResponseSchema.extend(…)` and that base declares `success` as a required
+  boolean, so a body carrying `data` alone still would not parse as the declared
+  type.
+- The raw `.user` / `.session` keys are **kept** alongside `data`. They are what
+  callers were pushed onto while the declared shape was unreachable; dropping
+  them would trade one silent breakage for another.
+- `auth.refreshToken` now reads `data.session.token`. It used to read
+  `data.data?.token` — a field this route does not produce at any nesting, so
+  the method returned successfully having captured nothing. A bearer-mode client
+  calling it to refresh kept whatever credential it already had, silently.
+
+## The read was not a consequence of the envelope
+
+Worth stating because the reverse is the natural assumption: enveloping the body
+does **not** put a token at `data.token`, because the route serves no top-level
+`token` to lift. The only credential in the body is `session.token`, and that is
+now the read. Fixing the shape alone would have left `refreshToken` exactly as
+inert as it was.
+
+## FROM → TO
+
+| you wrote | write instead |
+|:--|:--|
+| `(await client.auth.me()).user` | still works — kept deliberately |
+| `(await client.auth.me()).data.user` | now populated (was `undefined`) |
+| `(await client.auth.refreshToken(t)).data.token` | `.data.session.token` |
+
+`refreshToken` stores the **unsigned** session token, which is the spelling
+`/get-session` serves; `bearer()` accepts it and the signed
+`token.signature` form interchangeably, so a client that held the signed form
+stays signed in across the call.
+
+Two answers stay outside the declared type and are **not** addressed here: the
+anonymous `null`, which would need the published return annotation to widen, and
+`SessionUser.image`, declared `z.string().optional()` against a route that
+serves `null` (#17235). The sibling `auth.login` / `auth.register`, which
+normalize into `data` but set no `success`, are #17234.

.changeset/client-invite-role-default-member.md

@@ -0,0 +1,24 @@
+---
+"@objectstack/client": patch
+---
+
+fix(client): `organizations.invite` defaults `role` to `'member'`, so the shorter call it declares actually works (#16582)
+
+`organizations.invite` declares `role?` as **optional** and forwarded the caller's object to better-auth verbatim. better-auth 1.7.2's body schema for `POST /organization/invite-member` makes `role` **required**, so the documented-looking minimal call was refused before it reached any ObjectStack code:
+
+```
+client.organizations.invite({ email, organizationId })   ->  400  [body.role] Invalid input   (VALIDATION_ERROR)
+```
+
+Omitting `role` now sends `'member'`. **No published type moves** — `role` stays optional, and a caller who names a role still gets exactly that role on the wire (including `role: undefined`, which is treated as omission rather than dropped).
+
+The default is `'member'` because the sibling `organizations.invitations.resend` has always substituted exactly that over the **same** vendor endpoint. That asymmetry is why the gap stayed invisible: one member of the family papered over the vendor's requirement and the other did not, so only the shorter form ever failed. It is also the least-privileged name in the closed membership vocabulary (ADR-0108 D1 — `orgRoleGrade` floors at `member` and rises only for `owner`/`admin`), and an invitation is a pending row the invitee must still accept, so the implicit choice cannot confer reach the caller did not ask for.
+
+Measured against a real `AuthManager` (better-auth 1.7.2, organization plugin, `teams: { enabled: true }`) over a real `SqlDriver` (better-sqlite3), before and after:
+
+```
+before:  POST /organization/invite-member  ->  400  {"message":"[body.role] Invalid input","code":"VALIDATION_ERROR"}
+after:   POST /organization/invite-member  ->  200  {"role":"member","status":"pending", ...}
+```
+
+No caller had to change: the census found no in-repo or Console caller using the two-argument form, so this repairs a path that was declared and unreachable rather than one that was in use.