Skip to content

Commit 9163fa7

Browse files
committed
docs(sharing): name the missing-organization refusal on both sharing pages (#8158)
The "Typical Errors" list on `services.sharing` enumerates the exact conditions behind each status, and the ADR-0111 D6 section of the sharing-rules page is where a reader of the rule surface looks. This PR adds a refusal to that surface — an authenticated `manage_sharing` holder whose session resolves no active organization now gets 403 PERMISSION_DENIED on every verb — so both pages say so, including which two callers (system contexts, platform operators) are deliberately unaffected. Same reasoning as #8217: the runtime refusing more than the page says is the enforced-but-undocumented inverse of a declared-but-unenforced gap. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PEVB6w7D7uCszR9Mw1BL73
1 parent e5c0e69 commit 9163fa7

2 files changed

Lines changed: 18 additions & 2 deletions

File tree

content/docs/kernel/runtime-services/sharing-service.mdx

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -57,10 +57,10 @@ mask AND-ed with object CRUD, not a fourth `access_level`.
5757

5858
- `FORBIDDEN` (403) — a write denied by the `canEdit` gate. Thrown by the sharing engine middleware; `canEdit` itself returns `false` rather than throwing.
5959
- `VALIDATION_FAILED` (400) — `grant`/`revoke` called without a required field (`object`, `recordId`, `recipientId`, or `shareId`), or `grant` with a non-`user` `recipientType` (only `user` rows are enforced by the gates; group/position recipients are delivered via sharing rules).
60-
- `PERMISSION_DENIED` (403) — the caller does not hold `canManageShares` on the record (ADR-0111 D1).
60+
- `PERMISSION_DENIED` (403) — the caller does not hold `canManageShares` on the record (ADR-0111 D1). On the sharing-**rule** surface (`ISharingRuleService`, declared in the same canonical source — `listRules` / `getRule` / `defineRule` / `deleteRule` / `evaluateRule`) the same code carries a second condition: the caller holds `manage_sharing` but their session resolves **no active organization**, and an org-scoped capability with no organization has no tenant whose rules it authorizes. System contexts and platform operators (`manage_platform_settings`, or the `platform_admin` position) are unaffected — see [Rule administration](/docs/permissions/sharing-rules).
6161
- `NOT_FOUND` (404) — the record is missing **or not visible to the caller** (indistinguishable by design), or a `revoke` share id does not exist / does not belong to the `scope` record.
6262
- `CONFLICT` (409) — `revoke` on a rule-materialised share (`source != 'manual'`); the next rule reconciliation would silently re-grant it. Deactivate or edit the sharing rule instead.
63-
- `SHARING_NOT_ENABLED` (422) — `grant` on an object the sharing gates never consult (public sharing model, no `owner_id` field, a bypass object, or `controlled_by_parent`).
63+
- `SHARING_NOT_ENABLED` (422) — `grant` on an object the sharing gates never consult (public sharing model, no `owner_id` field, a bypass object, `controlled_by_parent`, or a **federated** object whose `owner_id` is the platform's injected anchor rather than a real remote column — the platform provisions no storage for a federated object, so the gates read that column off a table that has not got it and can never admit).
6464

6565
## Enforcement is automatic — do not re-check it in a hook
6666

content/docs/permissions/sharing-rules.mdx

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -161,6 +161,22 @@ covered; an unauthorized call fails with `403 PERMISSION_DENIED`. Boot
161161
seeding, lifecycle hooks, and backfills run as system context and are
162162
unaffected.
163163

164+
**and an organization to be scoped by.** `manage_sharing` is declared
165+
`scope: 'org'`, so the capability alone is not enough: the caller's session
166+
must also resolve an **active organization**, which is what scopes every rule
167+
read to "this organization ∪ the platform-global rows". A session that carries
168+
nonea user who has not selected an organization, or whose active
169+
organization was clearedis refused with the same `403 PERMISSION_DENIED`,
170+
naming the missing organization rather than answering with an empty list.
171+
Answering unscoped would hand that caller **every** organization's rules, and
172+
`evaluate` would reconcile grants across all of them (objectstack#8158).
173+
Two callers are deliberately unaffected, because neither is an org-scoped
174+
principal: **system** contexts, and **platform operators**a holder of
175+
`manage_platform_settings` or of the built-in `platform_admin` position
176+
administers rules across the deployment whether or not an organization is
177+
selected, which is also what a single-tenant deployment looks like before its
178+
default organization is bootstrapped (ADR-0081 D1).
179+
164180
### Switching a rule off withdraws the access it granted
165181

166182
A sharing rule's grants are **materialized** — evaluating a rule writes real

0 commit comments

Comments
 (0)