fix(plugin-security,core): security/explain resolves the user it explains through enforcement's organization-claim check (#20580)

[objectstack-fleet]

Fixes #20580

Clause-②: yes (widening)

What was wrong

When an administrator explains another user's access, the explanation is computed in the administrator's own organization (#20515). Enforcement does one more thing for that same user first. Under a walled tenancy posture (isolated, group) it vets the organization the user's session claims: a claim that no current membership backs is dropped, and the user resolves with no active organization, so only their global grants apply (#15409, ruling B). The explainer never ran that check. For a user whose membership in the administrator's organization had ended, the explanation listed that organization's grants, and the verdicts they decide, while enforcement applied none of them. Enforcement was correct throughout; the explanation was wrong.

What changes

• @objectstack/core: the session arm's check becomes one exported function, vetOrganizationClaim(claimedOrganizationId, accessibleOrgIds, tenancyPosture). It returns the claim while a current membership backs it, or while no wall is enforced, and undefined once the claim is dropped. resolveAuthzContext's session arm now asks it through the identical boolean. There is no behaviour change: the 11 existing session-arm tests in resolve-authz-context.test.ts pass unchanged.
• @objectstack/plugin-security: explainAccessForCaller asks vetOrganizationClaim about the explained user (their accessible_org_ids, and the plugin's tenancy posture) and resolves them in the organization it returns. The explainer spells no membership rule of its own.
• buildContextForUser's signature is unchanged. Its doc now says who vets the organization it is handed.

Landing point: security-plugin.ts, as expected. The check was reachable only through a new core export. The only other exported path that runs it, resolveAuthzContext itself, would skip the explainer's ruled grants-cache bypass and would write a false "session claim dropped" log line.

Evidence

Pin: packages/plugins/plugin-security/src/explain-removed-member-principal.test.ts.

• Rig: a real ObjectQL on better-sqlite3 and on sqlite-wasm, the real platform objects and the real SecurityPlugin.
• Two faces: every case compares the explanation with enforcement's own answer for the same principal over the same rows. Enforcement's face is resolveAuthzContext with a session that claims org_alpha, then assembleExecutionContext, then a find through the middleware.
• Walled (isolated, group): the removed member's explanation lists no org_alpha-scoped set, the same sets enforcement resolves for them. Its object_crud verdict is denies, where their own read is refused 403 PERMISSION_DENIED.
• KEEP: a current member's explanation still lists the set, as enforcement resolves it, and the read is granted on both faces.
• CONTROL, single: there is no wall, so the claim stands on both faces.
• Result at HEAD: 22 passed of 22.

Ablation. The fix was committed first. scripts/ablation-replace.mjs ran it with EXIT, INT and TERM restore, plus a shell trap on an absolute path.

• Mutation: the vetted organization was replaced by the caller's organization, unvetted. That is the pre-fix resolution.

• On disk: anchor count 1 went to 0, and the marker count was 1 during the run.

• Result: 8 failed, 14 passed (of 22). All 8 red cases are the removed-member pins (2 drivers, 2 walled postures, 2 pins each). KEEP, the precondition and the single control stayed green.

• Quoted:

  AssertionError: expected [ 'member_default', 'qa_probe_editor' ] to not include 'qa_probe_editor'
  AssertionError: expected 'grants' to be 'denies' // Object.is equality
  

• Restore: blob equals HEAD (6a86472402fd), and git diff HEAD is empty.

• First attempt: the tool refused it before anything ran. The replacement text already occurred on disk, so its count could not rise. Nothing was measured; the rerun used a unique marker.

Local verification

Recorded at HEAD bd7b46777. Core's test and typecheck ran at cf18f3e99; the diff from there to HEAD touches only the plugin-security pin file.

• pnpm --filter @objectstack/plugin-security test: 146 files, 3098 passed, 23 skipped.
• pnpm --filter @objectstack/plugin-security typecheck: exit 0. check:test-typecheck OK.
• pnpm --filter @objectstack/core test: 56 files, 1522 passed. vitest run --project local src/security/resolve-authz-context.test.ts: 102 passed, including the 4 new vetOrganizationClaim contract cases.
• pnpm --filter @objectstack/core test:repo: 3 files, 48 passed.
• pnpm --filter @objectstack/core typecheck: exit 0.
• Gates: node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack derived 67 commands (the 51 derived at dispatch, plus 16 for the changeset and test-layer kinds). Each exit code was captured before any pipe, and --ran reconciled them: 64 exit 0, 3 NOT MEASURED, 0 unrun.
• NOT MEASURED: check:dual-build-cjs-loads, check:i18n and check:type-check-debt. Each exited 3 with PREREQUISITE NOT MET, because each needs most of the monorepo built, and the core change invalidates the build cache for nearly every package downstream of it. CI builds that closure before these steps.
• NOT MEASURED: two runtime suites that exercise the session arm end to end (packages-orgless-grants-capability-gate, packages-vetted-org-source). Runtime's dependency closure was unbuilt here, so vitest reported "Failed to resolve entry for package" and ran no test. They are declared to CI.
• Lint, narrowed and measured:
  • Population: eslint.config.mjs's files globs, the ts and js family minus NEVER_LINTED. --print-config resolves a config for all 6 touched .ts files; the changeset .md matches no glob.
  • Count: --no-inline-config --format json over those 6 files, with 0 errors and 0 warnings.
  • Invariance: the config enables no type-aware linting (no parserOptions.project, no projectService). So this diff cannot move a verdict on an untouched file.
• Additive export: vetOrganizationClaim has no other occurrence in the repository. The two star re-exporters of core (runtime, plugin-hono-server) declare no such name.

Acceptance notes

• Surface widening (for the seat to re-judge Clause-②). @objectstack/core gains one export, vetOrganizationClaim, with no behaviour change. The changeset grades core minor and plugin-security patch. The line above is copied from the claim as it stands.
• A separate explain-versus-enforce position, measured and left alone here. The explained user's context carries no organization of its own: buildContextForUser returns none, and explainAccessForCaller sets none. Measured at c96beb27, better-sqlite3, one current member of the administrator's organization:
  • Under isolated, Layer 0 answers deny on a tenant object: the explanation says allowed: false with the fail-closed filter, while that member's own read is admitted.
  • Under every posture, a permission set authored in the database and scoped to that organization does not load for the explained user, while enforcement loads it.
  • Fixing it (set the explained context's organization to the vetted one, as resolveDelegatorContext does for a delegator) changes a current member's explanation, which this card's ruled pin keeps unchanged. It is reported to the seat for plugin-security closeout (explain ≠ enforce): object-level security.explain answers allowed: true under a row-level policy comparing two fields of no shared class, while find refuses it with INVALID_FILTER / 400 #20604, the explain-versus-enforce family card.
• Observation, not measured. With no tenancy service registered, admission hands the resolver no posture (no claim is ever dropped), while plugin-security probes org-scoping and can resolve isolated. The explainer reads the plugin's posture. In that composition the two could disagree. Both read the same tenancy service when it is registered.

Seat append (domain:services seat, session_01XY5uCwTjZj7884yYtyur4H)

• The Clause-② line above was corrected from no to yes (widening) by the seat, following the dev's deviation 2. @objectstack/core gains one export, vetOrganizationClaim, and the changeset already grades core minor. The claim was corrected in place in the same act.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 2 package(s): @objectstack/core, @objectstack/plugin-security, touching 3 documentable anchor(s). ⚠️ 2 changed file(s) yielded no anchor (packages/core/src/security/index.ts, packages/plugins/plugin-security/src/explain-engine.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

3 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/kernel/runtime-services/sharing-service.mdx (via resolveAuthzContext (symbol, a top-level function))
• content/docs/permissions/authorization.mdx (via resolveAuthzContext (symbol, a top-level function))
• content/docs/permissions/system-context.mdx (via explainAccessForCaller (symbol, a method of class SecurityPlugin))

⛔ 3 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/v14.mdx (via resolveAuthzContext (symbol, a top-level function))
• content/docs/releases/v17/17-1.mdx (via resolveAuthzContext (symbol, a top-level function))
• content/docs/releases/v17/17-3.mdx (via resolveAuthzContext (symbol, a top-level function))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

• 2 changed file(s) yielded no anchor (packages/core/src/security/index.ts, packages/plugins/plugin-security/src/explain-engine.ts) — pages documenting those are invisible to this run
• the SDK route bridge reached 54 of 206 client-bound route-ledger rows — the other 152 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 152: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 55 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 97 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 34 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json eb4b17c346c3a82aafe09462bda3b732fa3767bf → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 65dec923a50e6edd79aafee6fbeefac00c11cf35 — the merge of head bd7b4677773987cf5011dbde81e069167a69736e into base eb4b17c346c3a82aafe09462bda3b732fa3767bf, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 65dec923a50e6edd79aafee6fbeefac00c11cf35 && git checkout 65dec923a50e6edd79aafee6fbeefac00c11cf35
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin eb4b17c346c3a82aafe09462bda3b732fa3767bf bd7b4677773987cf5011dbde81e069167a69736e && git checkout -B drift-repro eb4b17c346c3a82aafe09462bda3b732fa3767bf && git merge --no-ff bd7b4677773987cf5011dbde81e069167a69736e

node scripts/docs-audit/affected-docs.mjs --json eb4b17c346c3a82aafe09462bda3b732fa3767bf

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs eb4b17c346c3a82aafe09462bda3b732fa3767bf → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[objectstack-fleet]

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: bd7b4677773987cf5011dbde81e069167a69736e
Local-runs: none

① Derived judgments

Inputs read: card #20580 (body and all four comments — the serial notice, the claim with its in-place Clause correction, the os-dev-report, the ACCEPT), PR #20614 (body, its 7-file list, the net diff against main at merge base c96beb27), and the check-runs on the head. Pre-change source was read from origin/main git objects only; nothing was built, run or re-run.

Accept-set changes (runtime behaviour):

1. security.explain (the service method behind the security explain route), an administrator explaining ANOTHER user, walled posture (isolated, group), the explained user holding no current membership in the caller's organization: the explained principal is now resolved with no active organization, so the caller's organization-scoped grants no longer appear in the explanation and the verdicts they decided follow enforcement's refusal. Right. This is enforcement's [decision · p0] a SESSION whose activeOrganizationId points at a left organization reads AND writes that organization — measured through better-auth's own remove-member endpoint #15409 ruling-B drop applied to the explained principal — the card's direction, and no second membership rule is spelled in the explainer.
2. Same route, a CURRENT member of the caller's organization: unchanged. Right — the ruled KEEP pin. vetOrganizationClaim returns the claim when accessible_org_ids holds it, so explainedTenantId === callerTenantId and no second resolution runs.
3. single, or no posture supplied: unchanged on both faces. Right — the function returns the claim before consulting memberships.
4. A caller with no active organization (callerTenantId undefined): unchanged. Right — the vet returns undefined, equal to its input, so no rebuild; the explained user is still resolved with no organization, as on main.
5. Explaining oneself, or a request with no userId: unchanged. Right — the whole edit sits inside the request.userId !== callerContext.userId arm (read at security-plugin.ts about L4690–4735 on main); the manage_users / delegated-scope gate ahead of it is untouched.
6. resolveAuthzContext session arm: no behaviour change. Right, verified at source. Old predicate: !keyPrincipal && tenantId && input.tenancyPosture && postureEnforcesWall(input.tenancyPosture) && !grants.accessible_org_ids.includes(tenantId). New: !keyPrincipal && tenantId && vetOrganizationClaim(tenantId, grants.accessible_org_ids, input.tenancyPosture) === undefined. With tenantId truthy under the guard, vetOrganizationClaim returns the claim (truthy, so not undefined) when the posture is absent or walls nothing, and returns undefined exactly when the posture walls and the claim is absent from the set — the same truth table on every input. The existing test file gains one import and one new describe block; no existing case is edited.
7. The vet's input is the right set. accessible_org_ids is built in resolveUserAuthzGrants from sys_member rows filtered by user_id alone (Leg 1, main about L757–802), never by the tenantId the grants were resolved in — so vetting against the context built in the caller's organization asks exactly the membership set enforcement asks. The new TSDoc's statement to that effect is accurate.
8. Posture input: the explainer passes this.tenancyPosture (the plugin's read of the tenancy service); enforcement passes the admission seam's read of the same service. Equal whenever a tenancy service is registered; the no-service composition is the dev's finding 2, escalated in ③.
9. The API-key arm (main about L454–470) is untouched, and rightly so — its consequence is a refusal to NO PRINCIPAL ([decision · p0] an ex-member API key reads AND writes another organization's rows on the single-kernel wiring under isolated — the wall compares against the caller's own unvetted claim #15256 2A), not a drop; a separately ruled decision outside this card.

Public-surface changes:

10. @objectstack/core gains vetOrganizationClaim(claimedOrganizationId, accessibleOrgIds, tenancyPosture) on security/index.ts, reaching the root barrel through its export * from './security/index.js', and from there @objectstack/runtime and @objectstack/plugin-hono-server through their export * from '@objectstack/core'. Additive; zero prior occurrences of the name anywhere on main, so no export * ambiguity. Right. Core has no exported-surface snapshot gate (its check: scripts are check:test-typecheck only), so no generated artifact is owed.
11. buildContextForUser and explainAccessForCaller signatures unchanged; explain-engine.ts is a four-line doc edit. Right — the A4 reading holds.
12. No packages/spec path, no REST route, no governed path, no env var: no artifact regeneration, no closed query-parameter set, and no tier record beyond this one is owed. Governed Surface Queue Guard: success. Head repo is the base repo; 438 changed lines, under the human-merge threshold.

Scope against the claim 5885265359: all seven paths are inside the named file surface. The packages/core/src/security/** exception was correctly triggered — the session arm's predicate was inline and reachable only through resolveAuthzContext itself, which would skip the explainer's ruled grants-cache bypass and write a false dropped-claim log line. postureEnforcesWall was already imported by the plugin, so an inline spelling was possible, but it is exactly the "second membership rule" the card forbids. The exception's three conditions hold: no behaviour change (item 6), a cross-lane notice (5886089080, per the ACCEPT), and Clause-② re-judged (②).

Pin quality: explain-removed-member-principal.test.ts is a parity pin, not a fixed-value pin — every case compares the explanation with enforcement's own resolution and read over the same rows (a real ObjectQL on two drivers, the real SecurityPlugin, resolveAuthzContext then assembleExecutionContext then a middleware find). Negative pins (removed member: set absent, object_crud denies, own read 403 PERMISSION_DENIED), KEEP pins (current member unchanged, granted on both faces), a single control, and a precondition that the set is resolvable at all, so a negative pin cannot pass for want of a grant. 22 cases = 2 drivers × (2 postures × 5 + 1 control), matching the report; the ablation's 8 red = 2 drivers × 2 postures × 2 removed-member pins, matching. Imports are package imports with no filesystem escape, so check:cross-package-test-inputs has nothing to see. The report's core measurements were taken at cf18f3e99; the delta from there to the head is 11 lines in the pin file alone, as stated.

Check-runs on the head, as read: success — Build Core, Governed Surface Queue Guard, Check Changeset, Type Check · debt ledger, Type Check · source gates, Dogfood Regression Gate (3/3), Dogfood Verify CLI, Check PR Size, Check Documentation Links, Flag docs affected by code changes, the five PR-shape guards (branch claim, single-writer path, same issue, part-of), filter, Auto Label. in_progress — Test Core (1/6 through 6/6), Dogfood Regression Gate (1/3, 2/3), Temporal Conformance (live PG + MySQL), Type Check · consumer gates, Type Check · workspace, Lint & Repo Gates. skipped — Console Pin Gate (an additive change, nothing for the pinned sibling to lose), Build Docs, Packed-tarball smoke. No failure at the time of reading. The seat checks convergence before landing; this verdict judges ①②③.

② Semver level

Changeset .changeset/20580-explain-removed-member.md: @objectstack/core: minor, @objectstack/plugin-security: patch. This matches what the diff publishes — one new export on core (a widening, so at least minor), and a behaviour fix with no signature change on plugin-security (patch). Not breaking: nothing is removed or renamed, so no ADR-0087 marker and no FROM → TO migration is owed, and the changeset correctly carries no Clause line (that line rides in a changeset only beside a breaking marker). Not naming runtime / plugin-hono-server for the reached additive name is within precedent (mixed; the fixed group moves them together anyway). The body describes the fix, the export with its signature and return contract, and the unchanged set. Check Changeset: success.

Clause-②: yes (widening)

That is the PR body's line as corrected by the seat from no, and this record agrees with the correction: the dev's original no was wrong once the core export existed, the seat's in-place correction of claim and body is the right act, and yes is consistent with the minor grade.

③ Boundary flags

Dev deviations (os-dev-report 5886046353):

1. A2 — a core export instead of a plugin-local rule. Accepted. Within the claim's exception; equivalence verified (① item 6); the alternative callers were rightly rejected. Cross-lane notice recorded by the ACCEPT.
2. Widening / Clause-② — Accepted and closed by the seat's correction (②). The changeset carrying no Clause line is correct for a non-breaking changeset.
3. A4 not triggered — Confirmed by the diff: buildContextForUser is doc-only.
4. A1 / A3 confirmed — Confirmed by the pin's precondition (enforcement drops the removed member's claim and keeps the current member's) and by the single control.
5. sqlite-only drivers, no PG leg — Accepted. The compared question (membership-set membership under a posture) is above the dialect; the rig's fixed platform-table ids justify avoiding a shared server. Enforcement's own PG coverage lives in its own suites.
6. Probe object platform-global so Layer 0 stays out — Accepted; it isolates the grant-driven verdict this card rules on. The tenant-object position is finding 1.
7. main not merged before opening — Accepted, no action: the three intervening commits touch rest, spec comments and plugin-audit, disjoint from every path and package here; CI on the head and the queue's rebuilt generation validate the merge (Multi-agent discipline §10).

Open question (finding 1 — the explained context carries no organization of its own): A, as the seat answered (5886097649). Fixing it here would change a current member's explanation, which this card's ruled KEEP pin holds unchanged; #20604 owns every explain-versus-enforce position with an enumeration pin. Not re-ruled here.

Out-of-scope findings:

• Entry 1 (class a, same reach, measured on two positions) — Carried by plugin-security closeout (explain ≠ enforce): object-level security.explain answers allowed: true under a row-level policy comparing two fields of no shared class, while find refuses it with INVALID_FILTER / 400 #20604 per the ACCEPT. A real defect with a named landing site, so Prime Directive chore: version packages #10 is satisfied by the carrier rather than a single-point card.
• Entry 2 (posture-source asymmetry with no tenancy service; a read-only inference) — Noted on plugin-security closeout (explain ≠ enforce): object-level security.explain answers allowed: true under a row-level policy comparing two fields of no shared class, while find refuses it with INVALID_FILTER / 400 #20604, correctly not filed: a card names measured evidence, and this has none yet. From this review's reading: the explainer reads this.tenancyPosture, which the plugin can resolve to isolated from an org-scoping probe when no tenancy service exists, while admission hands the resolver no posture in that composition — so the two faces could disagree there. Same carrier.

Reviewer findings (this record's own, none verdict-bearing):

• R1, doc accuracy: the new export's TSDoc says nothing else spells this rule and a caller that needs it calls this. The API-key arm of the same file (main about L456) still spells postureEnforcesWall(posture) && !grants.accessible_org_ids.includes(keyPrincipal.tenantId) inline, with a different consequence (refusal, [decision · p0] an ex-member API key reads AND writes another organization's rows on the single-kernel wiring under isolated — the wall compares against the caller's own unvetted claim #15256 2A). Leaving that arm alone was right for this card; the sentence is overstated. Follow-up for the plugin-security closeout (explain ≠ enforce): object-level security.explain answers allowed: true under a row-level policy comparing two fields of no shared class, while find refuses it with INVALID_FILTER / 400 #20604 family: either route the key arm's predicate through vetOrganizationClaim as a no-behaviour-change refactor, or narrow the sentence to the session arm. No runtime string, no gate and no behaviour turns on it.
• R2: explained.accessible_org_ids ?? [] guards a field buildContextForUser always sets to an array (its return is untyped, so the guard is not forced by a type). Dead in practice; if it ever fired it would fail closed (the claim dropped under a wall). Not a Prime Directive Add comprehensive test suite for Zod schema validation #12 alias — no metadata dialect is tolerated — so accepted as written.
• R3: the dropped-claim case pays a second resolveUserAuthzGrants with the ruled cache bypass. Only a stale claim reaches it; acceptable.

Implemented-by: claude/issue-20580-explain-removed-member
Reviewed-by: session_01XY5uCwTjZj7884yYtyur4H

VERDICT: PASS

---

Generated by Claude Code