fix(plugin-sharing): make package-seeded (org-null) sharing rules visible and addressable by name for org-scoped admins

[os-help]

Fixes #7676

The defect

Sharing rules seeded from an app or package are defined by bootstrapDeclaredSharingRules under plugin-sharing's SYSTEM_CTX — a context carrying no organization — so every seeded row lands with organization_id = null (platform-global). SharingRuleService.listRules and the by-name fallback of getRule scoped their reads with a strict organization_id = <caller org> equality, which such a row can never satisfy.

On a stock boot, as an org-scoped admin:

call	before	after
GET /api/v1/sharing/rules	200 {"data":[]} over 4 active seeded rules	lists them
GET /api/v1/sharing/rules/<seeded name>	404 RULE_NOT_FOUND	200
POST /api/v1/sharing/rules/<seeded name>/evaluate	404	200
POST /api/v1/sharing/rules/<row id>/evaluate (control)	200	200 (unchanged)

Enforcement was never affected — the boot reconcile also reads under SYSTEM_CTX, no org filter — which is exactly why this stayed invisible. The result is the worst half of both properties: rules that grant access org-wide while being impossible to list, inspect or deactivate.

Premise re-verified on origin/main before implementing: both sites are present as reported, listRules at the if (orgId) where.organization_id = orgId line and getRule's orgId ? {name, organization_id: orgId} : {name} fallback.

The change

Both admin reads now match "this organization OR platform-global" — the same predicate sys_business_unit approver expansion settled on in #3807 (businessUnitOrgScope) and the one sys_metadata's pending-draft listing uses. Another organization's row still fails the match; only rows belonging to no organization at all become visible.

Two details that are decisions rather than mechanics:

• defineRule is deliberately NOT widened. Its existence lookup decides upsert-vs-insert, so widening it would let one organization's admin rewrite the label, criteria, recipient and access level of a row every other organization reads — a cross-tenant WRITE, which is a different act from a cross-tenant READ of a platform-global row. A same-named create therefore still produces a row stamped with the caller's own organization.
• By-name resolution prefers the caller's own row, via two sequenced lookups rather than one $or with limit: 1. A single disjunctive query with a row cap returns whichever row the driver reached first, so an org that had authored its own share_red_projects_with_execs could get the platform row back on one dialect and its own on another. Preference is a decision, so it is written as one.

Tenant-isolation audit (pre-check before widening)

Every caller of listRules / getRule, and whether it relies on the strict equality for isolation:

caller	context	relies on strict equality for isolation?
rest-server.ts GET /sharing/rules → listRules	org-scoped admin	No — this is the defect. Widened.
rest-server.ts GET /sharing/rules/:idOrName → getRule	org-scoped admin	No. Widened (by-name only).
rest-server.ts DELETE /sharing/rules/:idOrName → deleteRule → getRule	org-scoped admin	See write-path note below.
rest-server.ts POST /sharing/rules/:idOrName/evaluate → evaluateRule → getRule	org-scoped admin	Same as delete.
rest-server.ts POST /sharing/rules → defineRule	org-scoped admin	Not fed by these two functions; left strict on purpose (above).
sharing-plugin.ts ×5 (boot reconcile, backfill, hooks)	{isSystem: true}, no org	No org id, so the unfiltered branch — untouched.
sharing-rule-service.ts evaluateAllForRecord → listRules(context)	SYSTEM_CTX from rule-hooks.ts	No org id — untouched.
sharing-rule-service.ts evaluateAllRulesForObject → listRules(SYSTEM_CTX)	system	Untouched.
bootstrap-declared-sharing-rules.ts → defineRule(SYSTEM_CTX)	system	Untouched; this is what writes the null-org rows.

Does read-widening become write/delete-widening on package-seeded rows? deleteRule and evaluateRule both resolve through getRule, so yes, they gain the by-name address. That is kept because it is symmetric with what by-id already allows: getRule's by-id branch carries no org filter at all, so an org admin could already delete and evaluate a null-org seeded rule by row id today — the issue's own control experiment is a successful by-id evaluate. This change adds an address form and discoverability, not a new class of authority. It is also consistent with the seed machinery's stated intent (#2909: admins may deactivate/customize seeded rules and that must survive redeploys), and a deleted seeded rule is reseeded on the next boot.

No cross-tenant exposure is created. Rules belonging to a different organization remain excluded from both widened reads.

One pre-existing gap found during the audit and filed separately rather than fixed here: getRule's by-id branch is org-unfiltered, so an org admin holding another organization's srule_… id can read, evaluate and delete that organization's rule. It predates this change, is not made worse by it, and narrowing it is a behaviour change deserving its own PR.

Tests

packages/plugins/plugin-sharing/src/sharing-rule.test.ts — a [#7676] block with an org-scoped admin ({userId, organizationId: 'org1', systemPermissions: ['manage_sharing']}), a package seed defined under an org-less boot context, an org1-owned rule and an org2-owned rule:

• Premise guard — asserts the fixture really stores organization_id: null on the seed and real org stamps on the other two, so the pins below cannot pass for the wrong reason.
• Visibility — seeded rule appears in listRules, resolves by name, evaluates by name (and agrees with the by-id control).
• Isolation pins — another org's rule stays absent from the list and unresolvable by name, each with a positive half so neither can pass by returning nothing.
• Conjunction — the org scope is AND-ed with object / activeOnly, not substituted for them.
• Unchanged — org-stamped rules still listed/gettable; a no-org (SYSTEM_CTX/boot) context still sees everything unfiltered; when both a platform-global and an own-org row share a name, by-name resolves the own row.

The test fake engine's filter matcher short-circuited on $or and dropped its sibling field keys, so listRules's {object_name, active, $or:[…]} would have matched the whole table there while driver-sql's applyFilterCondition and driver-memory's mingo document conjoin the two. It now conjoins — a fake looser than the contract it stands in for is how a green suite ships a broken filter. No existing test depended on the loose behaviour.

pnpm --filter @objectstack/plugin-sharing test      Test Files 16 passed | Tests 428 passed
pnpm --filter @objectstack/plugin-sharing typecheck tsc --noEmit, clean
pnpm --filter @objectstack/dogfood test             Test Files 90 passed | 1 skipped
                                                    Tests 576 passed | 3 skipped
node scripts/check-nul-bytes.mjs                    OK (7115 files)
pnpm check:engine-double-contract                   OK — 148 pinned, 133 DEBT, 2 exempt

Reverse verification (ablation)

Predicted before running: the three visibility tests flip red, every isolation and unchanged-behaviour pin stays green. Reverting only sharing-rule-service.ts to its pre-fix state and keeping the tests, on the post-merge tree:

× listRules shows the seeded rule to an org-scoped admin
× getRule resolves the seeded rule BY NAME for an org-scoped admin
× evaluateRule works BY NAME for the seeded rule (no RULE_NOT_FOUND)
  Tests  3 failed | 425 passed (428)

Exactly the predicted split — the two isolation pins, the conjunction pin, the org-stamped pin, the no-org pin and the both-rows-share-a-name pin all stayed green, so they are pinning isolation rather than riding on the visibility change.

One thing this PR does NOT ship, deliberately

An HTTP-layer regression test in packages/qa/dogfood was written and then removed after it proved it could not discriminate. bootStack's admin carries no organization — a rule created through the API in that harness comes back organization_id: null — so the org-scoped filter path is never entered and the test was green on the unfixed code for the wrong reason. An org-scoped admin needs multiTenant: true, which requires the cloud-private @objectstack/organizations package and is not reachable in the open core. Shipping it would have been a phantom check that reads as coverage. This is filed as a coverage-harness finding, and it is the direct reason this defect escaped both the plugin's 428-test suite and the 579-test dogfood suite and reached a QA run.

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 11, 2026 1:23pm

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/plugin-sharing.

7 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/kernel/runtime-services/examples.mdx (via @objectstack/plugin-sharing)
• content/docs/kernel/runtime-services/sharing-service.mdx (via @objectstack/plugin-sharing)
• content/docs/kernel/services-checklist.mdx (via @objectstack/plugin-sharing)
• content/docs/permissions/authorization.mdx (via packages/plugins/plugin-sharing)
• content/docs/permissions/permissions-matrix.mdx (via packages/plugins/plugin-sharing)
• content/docs/plugins/packages.mdx (via @objectstack/plugin-sharing)
• content/docs/protocol/objectql/security.mdx (via packages/plugins/plugin-sharing)

⛔ 1 release-owned page(s) also reference the affected code. These are read-only:

• content/docs/releases/implementation-status.mdx (via @objectstack/plugin-sharing)

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.

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.