Skip to content

Commit d08b859

Browse files
docs(verify): posture-only docblocks say what the stand-in walls and what it does not (#28760)
<!-- claude-projects-attribution: {"github_login":"marchtian"} --> _Requested by **田騏** · [project thread](https://claude.ai/code/project/chan_01VmuUhXU9SSUzqJYyXSmYSi?thread=cmsg_01VmuUhXU9SSUzqJYyXSmYSi9paTx1Lu8ENYwwssthfK3h)_ Fixes #28703 Clause-②: no Metadata-protocol: none ## 维护者速读 - 改了什么:只改 `packages/verify/src/harness.ts` 里的注释(`SimulatedOrgScopingPlugin`、`BootOptions.multiTenant: 'posture-only'`、`orgContext` 一段、一行行内注释),外加一条 `@objectstack/verify` patch changeset;不改任何代码。 - 为什么改:旧注释说 posture-only 启动"不打 organization_id、不做隔离,跨组织测试写了也白写";ADR-0131 之后引擎按姿态落组织、Layer 0 按姿态拦截,注释与代码正相反,会让写测试的人放弃本可低成本钉住的跨组织隔离。 - 风险与回滚:零运行时风险(仅注释,`dist/index.d.ts` 里的 JSDoc 随之变化);回滚即 revert 本 PR。 - 先看:`packages/verify/src/harness.ts` 的 `multiTenant` 文档块("What it walls" / "What it does NOT give a fixture" 两节);其次文件顶部 `SimulatedOrgScopingPlugin` 文档块。 - 两分钟验证:`git diff origin/main...HEAD -- packages/verify/src/harness.ts`,预期只见注释行变动、无一行代码变化。 - 需要你做的:无,席位落地。 ## What changes Comments only, in `packages/verify/src/harness.ts`, plus a `patch` changeset for `@objectstack/verify` (the `BootOptions` JSDoc ships in `dist/index.d.ts`, so the published bytes change). - **`SimulatedOrgScopingPlugin` docblock.** The "⛔ It stamps no `organization_id` and scopes no query" sentence is replaced. The stand-in itself still stamps and scopes nothing, but since ADR-0131 (D8, D11) the wall is open-core code that keys on the posture the stand-in makes true. The engine lands an insert in the caller's active organization (`ObjectQL#driverWriteTarget`), the SQL driver fills an absent `organization_id` (`SqlDriver#injectTenantOnInsert`), and reads are scoped by the one Layer 0 verdict (`computeTenantLayer0Verdict`, `postureEnforcesWall`). - **`BootOptions.multiTenant` `'posture-only'` section.** "It performs no tenant isolation whatsoever … would assert nothing and pass" is removed. Two subsections replace it: - *What it walls*: insert and read, with the code locations behind each. - *What it does NOT give a fixture*: no default-organization bootstrap (the admin resolves org-less), no per-organization seed replay, no walled membership-policy gate, no deployment declarations on the service, and the memory driver refuses a walled posture. The section tells a cross-organization fixture to measure the wall, and points to the precondition case of `packages/qa/dogfood/test/create-caller-id-collision-walled.dogfood.test.ts` as the shape. - **`orgContext` docblock.** "Cross-tenant isolation has exactly one honest proof in this repo: `multiTenant: true`" is replaced. A cross-tenant fixture needs a walled posture, either `'posture-only'` or `true`. The "asserts nothing on `single`" sentence stays, because it is still true. It now names the Layer 0 verdict as well as the RLS strip. - **Inline comment** at the `'posture-only'` branch of `bootStack`: "activates the POSTURE, never the WALL" now says the open core's wall follows from the posture. ## Tests No behaviour changes, so no test was added or changed. <details><summary>Local runs at head 5b630f0</summary> - `pnpm --filter '@objectstack/verify...' build` (under `os-verify-lock`): `VERDICT command-exit 0`. - `pnpm --filter @objectstack/verify typecheck`: `VERDICT command-exit 0`. `check:test-typecheck: OK`. - `pnpm --filter @objectstack/verify exec vitest run --maxWorkers=2`: `Test Files 48 passed (48)`, `Tests 401 passed (401)`, `VERDICT command-exit 0`. - Published-surface check after the build: `dist/index.d.ts` contains "What it does NOT give a fixture" (1 match) and "performs no tenant isolation whatsoever" (0 matches). The positive control `databaseDriver` has 2 matches. `files` is `["dist","README.md","CHANGELOG.md"]`. </details> ## Acceptance notes - **Changeset level.** os-dev's fast track lists comments as not published. Here, though, the `BootOptions` JSDoc measurably ships in `dist/index.d.ts`, so this takes a `patch` changeset, not `skip-changeset`. - **Left as is (out of scope).** The `SimulatedOrgScopingPlugin` docblock still says "The proof that the REAL plugin walls tenants lives in cloud's `security-enterprise` multi-org integration test". The read wall is now open-core code that this repo pins too (see the walled pin above), so that sentence understates where the proof lives. It is not a defect, and this PR does not touch it. - **Spec docblock (not edited, out of scope).** `postureStampsOrganization`'s docblock in `packages/spec/src/security/tenancy-posture.ts` says the stamper is the enterprise runtime, "not the open engine". The open engine plus the SQL driver now stamp the active organization on insert in every posture (`ObjectQL#driverWriteTarget`, `SqlDriver#injectTenantOnInsert`). This looks like the same class of drift in another package. It is noted here and not filed. ## Verification <details><summary>Derived gate families (dispatch-gates --commands, head 5b630f0)</summary> - 54 derived families. 53 exited 0. - 1 is NOT MEASURED: `pnpm check:dual-build-cjs-loads` exited 3 with `PREREQUISITE NOT MET` because it needs a full `pnpm build` and only the verify closure was built. CI runs it. - `node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --ran FILE` reports `54 derived famil(ies) accounted for — 53 run, 1 NOT-MEASURED (1 DERIVED from a recorded exit 3)` and exits 0. - Every family CI runs, the repo-wide ones included, is CI's to report on this PR. </details> Session: https://claude.ai/code/session_017ihL2gLghEqeDKTbDTC7Zd 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude <noreply@anthropic.com>
1 parent 373081f commit d08b859

2 files changed

Lines changed: 95 additions & 29 deletions

File tree

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
---
2+
'@objectstack/verify': patch
3+
---
4+
5+
docs(verify): the `BootOptions.multiTenant: 'posture-only'` doc comment says what the stand-in walls and what it does not
6+
7+
Clause-②: no
8+
Metadata-protocol: none
9+
10+
Doc comments only; no behaviour changes. The `multiTenant` doc comment said a `'posture-only'` boot stamps no `organization_id`, scopes no query, and that a cross-organization fixture booted this way "would assert nothing". Since ADR-0131 (D8, D11) the organization wall keys on the posture in force, so that was the opposite of what the code does:
11+
12+
- **Insert.** The engine lands a write in the caller's active organization, and the SQL driver stamps an absent `organization_id` from it.
13+
- **Read.** Layer 0 and the driver scope project one verdict, which walls under `isolated` (`organization_id = active org`) and `group` (`IN accessible_org_ids`).
14+
15+
The comment now says a cross-organization fixture can boot this way, as long as it measures the wall: the other organization's row is hidden, its own row is served, and the stamp is checked. It also names what the stand-in does not give a fixture, for which `multiTenant: true` with `@objectstack/organizations` is still needed: the default-organization bootstrap, per-organization seed replay, the walled membership-policy gate, and the deployment declarations on the `org-scoping` service. It notes that `databaseDriver: 'memory'` refuses a walled posture. The `orgContext` comment no longer says `multiTenant: true` is the only cross-organization proof.

‎packages/verify/src/harness.ts‎

Lines changed: 80 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -75,9 +75,16 @@ interface InjectableApp {
7575
* ADR-0093 D5), so registering it turns a degraded deployment into a
7676
* non-degraded `isolated` one from every consumer's point of view.
7777
*
78-
* ⛔ It stamps no `organization_id` and scopes no query — it is the deployment's
79-
* POSTURE, not its WALL. See `BootOptions.multiTenant` for what that permits and
80-
* what it must never be used to claim.
78+
* The stand-in itself stamps nothing and scopes nothing, and since ADR-0131 it
79+
* does not need to: the organization wall is open-core code that keys on the
80+
* POSTURE this stand-in makes true (D8 one predicate, D11 postures differ only
81+
* in enforcement). The engine lands an insert in the caller's active
82+
* organization (`ObjectQL#driverWriteTarget`), the SQL driver fills an absent
83+
* `organization_id` from it (`SqlDriver#injectTenantOnInsert`), and reads are
84+
* scoped by the one Layer 0 verdict (`computeTenantLayer0Verdict`,
85+
* `packages/core/src/security/tenant-layer0-verdict.ts`), which walls whenever
86+
* `postureEnforcesWall` holds. See `BootOptions.multiTenant` for what that
87+
* walls and what the stand-in still does not give a fixture.
8188
*
8289
* `supportedPostures` is declared (ADR-0105 D12) so the stand-in entitles the
8390
* same set a runtime predating that seam does, rather than accidentally
@@ -235,32 +242,74 @@ export interface BootOptions {
235242
* unless the caller already set `OS_TENANCY_POSTURE` — mounting the plugin
236243
* entitles a walled posture but no longer activates one by itself.
237244
*
238-
* ## `'posture-only'` — a stand-in, for proving org LIFECYCLE without isolation
245+
* ## `'posture-only'` — a stand-in for the `org-scoping` service
239246
*
240247
* `multiTenant: 'posture-only'` boots the same shape but registers a built-in
241248
* stand-in for the `org-scoping` service instead of requiring the enterprise
242249
* package that no framework package may declare (ADR-0132's entitlement
243250
* boundary). The `tenancy` service then resolves a real, NON-DEGRADED
244-
* `isolated` posture, which is what posture-gated seams key on — above all
251+
* `isolated` posture (`group` when the caller sets `OS_TENANCY_POSTURE` to
252+
* it), which is what posture-gated seams key on — above all
245253
* `POST /auth/organization/create`, which since #5261 refuses whenever the
246254
* EFFECTIVE posture has no organization wall.
247255
*
248-
* ⛔ **It performs no tenant isolation whatsoever.** Nothing stamps
249-
* `organization_id`, nothing scopes a query. It makes the deployment's POSTURE
250-
* true, not its WALL. A fixture that asserts one tenant cannot read another's
251-
* rows and boots this way would assert nothing and pass — the constant-false
252-
* capability probe of #4700 wearing the opposite mask. Cross-tenant isolation
253-
* has exactly one honest proof in this repo: `multiTenant: true` with the real
254-
* `@objectstack/organizations` installed, which is why those gates SKIP here
255-
* (see `test/enterprise-organizations.ts`) instead of pretending.
256+
* ### What it walls
256257
*
257-
* Use it only where the organization wall is the PRECONDITION of the thing
258-
* under test rather than the thing itself — `org-create-default-team`
259-
* (#3624: better-auth's default-team insert must not 500) is the case it was
260-
* built for. Before #5261 that fixture opened the route by flipping
261-
* `OS_MULTI_ORG_ENABLED` after boot and leaning on the gate's live env read;
262-
* the gate now reads the tenancy service, so the honest way to open it is to
263-
* simulate the deployment that legitimately has it open.
258+
* The open core's organization wall. Since ADR-0131 that wall keys on the
259+
* posture in force, not on which package registered the service (D8: one
260+
* predicate, computed once; D11: postures differ only in enforcement):
261+
*
262+
* - **Insert.** The engine lands a write in the caller's active organization
263+
* in every posture (`ObjectQL#driverWriteTarget`), and the SQL driver
264+
* fills an absent `organization_id` from it
265+
* (`SqlDriver#injectTenantOnInsert`). A row a member of organization A
266+
* creates is stamped A.
267+
* - **Read.** Layer 0 (`computeTenantLayer0Filter`, plugin-security) and the
268+
* driver scope the engine threads (`SqlDriver#applyTenantScope`) project one
269+
* verdict, `computeTenantLayer0Verdict`
270+
* (`packages/core/src/security/tenant-layer0-verdict.ts`), which walls
271+
* whenever `postureEnforcesWall` holds: `organization_id = active org`
272+
* under `isolated`, `IN accessible_org_ids` under `group`. SecurityPlugin
273+
* keeps the shipped tenant RLS policies instead of stripping them.
274+
*
275+
* So a fixture that asserts one organization cannot read another's rows CAN
276+
* boot this way and assert something. It must still MEASURE the wall rather
277+
* than assume it — read the other organization's row and see it hidden, read
278+
* its own and see it served, and check the stamped `organization_id` — as the
279+
* precondition case of
280+
* `packages/qa/dogfood/test/create-caller-id-collision-walled.dogfood.test.ts`
281+
* does. Without that, a later assertion may be comparing two visible rows.
282+
*
283+
* ### What it does NOT give a fixture
284+
*
285+
* The stand-in registers the service and nothing else, so what the real
286+
* `@objectstack/organizations` runtime does BESIDES making the posture true
287+
* is absent. When one of these is the subject, use `multiTenant: true` with
288+
* that package installed (those gates skip in this repo — see
289+
* `packages/qa/dogfood/test/enterprise-organizations.ts`):
290+
*
291+
* - **No default-organization bootstrap.** The open bootstrap abstains under
292+
* every walled posture (cloud ADR-0081 D1), so the harness admin resolves
293+
* org-less. A fixture mints its own organizations
294+
* (`POST /auth/organization/create`, then `set-active`), and `orgContext`
295+
* refuses to compose with this mode.
296+
* - **No per-organization seed replay.** A new organization starts empty;
297+
* the app's seed datasets are not replayed into it.
298+
* - **No walled membership-policy gate.** The real runtime refuses a walled
299+
* boot whose membership policy is undeclared
300+
* (`assertWalledMembershipPolicyDeclared`); the stand-in does not ask.
301+
* - **No deployment declarations on the service** (`platformGlobalObjects`,
302+
* `suppressUnboundedOrgAdminGrant`); their readers see them as absent.
303+
* - **The SQL driver only.** `databaseDriver: 'memory'` refuses a walled
304+
* posture (`assertSingleTenantPosture`, driver-memory), so the wall is
305+
* measured on the default `sqlite-wasm` driver.
306+
*
307+
* It was built for `org-create-default-team` (#3624: better-auth's
308+
* default-team insert must not 500), where the wall is the PRECONDITION of
309+
* the route under test. Before #5261 that fixture opened the route by
310+
* flipping `OS_MULTI_ORG_ENABLED` after boot and leaning on the gate's live
311+
* env read; the gate now reads the tenancy service, so the honest way to open
312+
* it is to simulate the deployment that legitimately has it open.
264313
*/
265314
multiTenant?: boolean | 'posture-only';
266315
/**
@@ -293,16 +342,17 @@ export interface BootOptions {
293342
* ## ⛔ It performs NO tenant isolation whatsoever
294343
*
295344
* A bound caller is not an organization wall. With no `org-scoping` service
296-
* registered — and nothing here registers one — `SecurityPlugin` STRIPS the
297-
* wildcard `organization_id` RLS policies that ship in the default
298-
* permission sets (`collectRLSPolicies`; see the `multiTenant` doc block
299-
* above). So a fixture asserting "tenant B cannot read tenant A's rows" on a
345+
* registered — and nothing here registers one — the posture stays `single`,
346+
* where the Layer 0 verdict walls nothing (`postureEnforcesWall`, ADR-0131
347+
* D8, D11) and `SecurityPlugin` STRIPS the wildcard `organization_id` RLS
348+
* policies that ship in the default permission sets (`collectRLSPolicies`).
349+
* So a fixture asserting "tenant B cannot read tenant A's rows" on a
300350
* `single` boot asserts nothing and passes.
301351
*
302-
* Cross-tenant isolation has exactly one honest proof in this repo:
303-
* `multiTenant: true` with the real `@objectstack/organizations` installed
304-
* (which is why those gates SKIP here instead of pretending — see
305-
* `test/enterprise-organizations.ts`).
352+
* A cross-tenant fixture needs a WALLED posture, which this flag never
353+
* requests: `multiTenant: 'posture-only'` (the open core's wall, measured as
354+
* the `multiTenant` doc block above says) or `multiTenant: true` with the
355+
* real `@objectstack/organizations` installed.
306356
*
307357
* The tenancy POSTURE is likewise untouched, and that is not an accident of
308358
* this implementation but a property of the seam: `TenancyService`'s
@@ -1088,7 +1138,8 @@ async function bootClaimed(
10881138
// so a missing package is a hard, actionable error — not a silent
10891139
// single-org downgrade that would flip the fixture's RLS posture.
10901140
if (opts.multiTenant === 'posture-only') {
1091-
// See BootOptions.multiTenant: activates the POSTURE, never the WALL.
1141+
// See BootOptions.multiTenant: activates the walled POSTURE; the open
1142+
// core's wall (insert stamp, Layer 0 read verdict) follows from it.
10921143
// Registered in the enterprise plugin's own slot so every downstream probe
10931144
// (SecurityPlugin's strip decision, the `tenancy` service's `isolationActive`,
10941145
// `requiresService: 'org-scoping'` nav gating) sees one consistent answer —

0 commit comments

Comments
 (0)