feat(plugin-security)!: refuse a principal-less, non-system data-engine context (ADR-0096 D5 strict mode)

[objectstack-fleet]

Fixes #21908
Clause-②: no (narrowing)

Summary

ADR-0096 D5 strict mode, the deny round of #21908. A data-engine context that carries no principal (no user id, no position, no permission set) and is not a system context is now refused at every place plugin-security used to hand it through. The published contract sentence on ChatWithToolsOptions.toolExecutionContext ("unauthenticated (RLS-on, sees-nothing)") now holds.

Before the deny, every producer of such a context that a run or a static read found was closed inside this claim: it carries the caller's principal or the explicit system opt-in (isSystem: true) inside its owning code. Breaking for in-process code (the ! banner); the changeset carries the migration and an ADR-0087 disposition. The at-tier contract review is owed before the queue.

The ADR-0096 D5 dated note is its own Tier H draft PR, on claude/issue-21908-adr-0096-d5-note, for the maintainer's approval.

What changes, by class

The predicate is isPrincipalLessContext(context) && !isSystem, the one the hand-off already used. These are the six sites, at origin/main 0e9371f0 positions:

Site (security-plugin.ts)	Before	After
engine middleware (near :2616)	return next(): no CRUD gate, no RLS, no field mask, no tenant wall	throws PermissionDeniedError (403 PERMISSION_DENIED) for every verb, before the operation runs
getReadFilter (near :5875)	the sharing predicate alone	the deny filter (zero rows)
resolveProjectionFieldMask (near :6126)	the full field set	no early answer: the zero-set field answers, like any caller that resolves no set
canReadObject (near :6299)	true	false
canWriteObject (near :6585)	true	false
canExport (near :6688)	true	false

• Unchanged: a system context is admitted everywhere.
• Unchanged: a context that carries a principal without a user id is decided by what it carries. That covers a named permission set, the guest principal, and the public-form grant.
• The gates that run before the refusal keep their own answers: package-managed, system-row, curated-capability, audience-anchor, engine-owned and delegated-admin.

Why the five service sites return rather than throw. The ruling's error class is the engine-level refusal, and the middleware throws it. The published ISecurityService contract has canReadObject, canWriteObject and canExport return false, and has getReadFilter return the deny filter. Each of them now gives a principal-less context the deny it already gives a caller that carries a principal and resolves no set (ADR-0056 D2). The field projections are field answers, not admission answers. The contract text for getReadableFields names the answer for "a non-system caller who resolves no permission set", and that answer now applies to this context too. Object admission is refused by the middleware and the three probes.

Producer census (H1), by class, position and function

Method.

• A temporary probe recorded the call stack at every principal-less exit while the deny was in place. It was never committed; it was reverted, and the blob was proven equal to HEAD.
• It ran over the full dogfood suite (10 shards, 239 files) and over every unit file in 22 packages that composes the security plugin (about 90 files).
• A static sweep covered every sys_* engine call in production source that passes no context.
• After the fixes, a real boot was driven, with a member's first query and the admin authoring doors.

Class	Position	Function	From a request	Closure
production, measured	metadata-protocol protocol.ts	promoteDraftForPublish (the draft read)	yes: the publish door, behind its authorization	explicit system opt-in
production, static	metadata-protocol protocol.ts	resolveDraftOrgScopeForPublish (both probes)	yes: an organization-scoped publish	explicit system opt-in
production, static	metadata-protocol protocol.ts	resolveMetaItemOrgScope (both history probes)	yes: the organization-scoped revert path	explicit system opt-in
production, static	metadata-protocol protocol.ts	auditMetaItem	yes: the audit door	explicit system opt-in
production, static	metadata-protocol protocol.ts	diffMetaItem (the history read and the current-row read)	yes: the diff door	explicit system opt-in
production, static	metadata-protocol protocol.ts	listCommits, revertCommit, rollbackToPackageCommit	yes: the commit doors	explicit system opt-in
production, static	metadata-protocol protocol.ts	metaTypeNamespaceExists, migrateStoredMetadata	yes: the authoring and migration doors	explicit system opt-in
production, static	metadata-protocol protocol.ts	deleteMetaItem legacy path (read and delete)	yes: the code-only delete on a control-plane kernel	explicit system opt-in
test harness	qa/dogfood	the federated-fixture test (context passed as the options argument)	no	carries { context }
test harness	qa/dogfood	package-first-authoring (a direct store insert)	no	system opt-in
test harness	runtime	standalone-stack-seeder-declaration-copy (context-less reads)	no	system opt-in
test harness	runtime	the share-links-enforcement-context engine double (dropped the trailing read options)	no	honours the trailing context, as mergeReadContext does

Not producers today. loadMetaFromDb and reportUnhydratableOrgScopedRows read context-less at boot. They run inside ObjectQL's start(), and plugin-security depends on ObjectQL, so they run before the security middleware is registered. Noted, not edited.

No producer was found outside plugin-security, protocol.ts and the test harnesses. The static sweep's other 25 hits all go through a system-context wrapper or a context-carrying options object, or are comments. Every edit uses only the declared opt-in; nothing guesses a boundary. Each moved call is a sys_metadata* store read, or the legacy delete of a sys_metadata row. None of the six gates the middleware runs before the refusal keys on those objects, so the opt-in changes nothing they decide.

The dispatcher's identity-resolution fault class (the domain:cli seat's note) is closed by this deny by construction. It is pinned below, and http-dispatcher.ts is not edited.

Pins

The ruling's three pins:

• A principal-less context is refused on read and write: plugin-security principal-less-strict-mode.test.ts. It covers every spelling: no context, an empty one, empty arrays, isSystem: false, a tenant id alone, and provenance only. The middleware answers PERMISSION_DENIED / 403 for all seven verbs before the operation runs, the probes answer false, and the row scope is the deny filter.
• An explicit system context is unchanged: the same file, with and without a principal.
• The dogfood suite is green under the deny: see Evidence.

Further pins:

• The hand-through pins became refusal pins: zero-set-deny-baseline, zero-set-masking, zero-set-capability-fold, metadata-unresolvable-posture, predicate-related-read-tenant-scope and security-plugin.test.ts's row-scope case.
• The deny is keyed on carrying no principal: a user-less named set, the guest principal and the public-form grant are each decided by what they carry.
• The resolveRequestScope fault class is now denied: runtime dispatcher-plugin.endpoint-principal-less-deny.integration.test.ts, over the real dispatcher plugin and the real security middleware. The engine is handed no principal, the store is never reached, and the caller gets 403 with nothing of the rows. Its two controls: an anonymous request with no fault runs as the guest (the posture of security(rest, runtime): an anonymous request at an app-declared authRequired: false endpoint executes principal-less — execute it as the guest principal (ruled C), never principal-less, never system #22147, unchanged), and a granted signed-in caller is served.
• The guest posture is unchanged at a real boot: test(runtime): pin the guest principal an anonymous request executes as at authRequired:false endpoints #22177's declarative-endpoint-anonymous-guest pins stay green under the deny.
• The composed Q2 pin: qa/dogfood owner-of-private-object-under-strict-mode. An owner_of: audience on a private object reaches its owner's inbox, and nobody else's, end to end. In the same composition, a principal-less read of that object is refused.
• The protocol producers: metadata-protocol protocol.platform-store-system-opt-in.test.ts, deny-round block. Each producer is driven, and every engine call it issues must carry isSystem: true.

Ablations

Each ablation ran through scripts/ablation-replace.mjs (wrap mode, plus a shell trap). Every mutation landed (anchor 1 → 0, blob changed), and every restore was proven (blob == HEAD, git diff HEAD empty). The dist legs were proven with ablation-dist-preflight (marker present while live, --absent after the restore rebuild, tree clean).

#	Mutation	Red
A1	the middleware refusal replaced by the old return next() (dist leg)	plugin-security 13 of 42; runtime fault-class pin 1 of 3 (the store was reached)
A2	getReadFilter answers no scope for the class	8 of 305
A3	canReadObject admits the class	7 of 305
A4	the diff door's history read loses the opt-in	1 of 7
A5	the promotion's draft read loses the opt-in	1 of 7
A6	resolveOwnerOf loses its opt-in (service-messaging, dist leg)	the composed Q2 pin 1 of 1 (0 recipients)

Evidence

Final head 454d0e89b9: origin/main 8cbe255ef6 merged at 6681b216e1, then a docblock-only test commit. All runs were made under the shared verify lock, so wall times are shared-box readings.

On the merged tree (6681b216e1):

• plugin-security: 180 files, 3800 passed, 45 skipped.
• metadata-protocol: 221 files (+3 skipped), 28280 passed.
• runtime: 339 files, 5490 passed, 19 skipped.
• The composing unit files of the packages main touched (rest, cli, lint, platform-objects, plugin-approvals, service-analytics, organizations, spec): all green.
• dogfood, the whole suite in 10 shards: 223 files, 1754 passed, 9 skipped.
• typecheck exits 0 for plugin-security, metadata-protocol, runtime and dogfood. tsc --listFiles shows metadata-protocol's program compiles the edited pin.

Before the merge (8248ceb97f): objectql 381 files / 7525 passed, and core 81 files / 2240 passed. Neither package is touched by main's incoming commits or by this diff.

Real boot, showcase --fresh, on the merged tree:

• An anonymous request answers 401.
• The admin signs in and invites a member. The member signs up, and the member's first data query answers 200, as do the member's object read and inbox.
• The admin's draft save, publish, diff, audit, history, delete and package-commits doors all answer 200.
• The server log carries zero strict-mode refusals.

Gates: dispatch-gates --commands derived 73 families at 454d0e89b9. All 73 ran and exited 0. --ran: "73 derived famil(ies) accounted for — 73 run, 0 NOT-MEASURED (a DERIVED zero — all 73 recorded an exit code and none of them is 3)". Selected verdict lines:

• ✓ check-adr-0087-registration: 1 declared-breaking changeset(s), each carrying an ADR-0087 disposition.
• ✓ This diff introduces no \major` bump.`
• check-nul-bytes: OK
• check-engine-double-contract: OK
• check-test-source-alias OK
• check:cross-package-test-inputs OK

Lint, a proven narrowing (CI runs the full pnpm lint):

• The population read from eslint.config.mjs is **/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs} plus the packages/** blocks.
• eslint --no-inline-config --format json over the 16 changed .ts files at 454d0e89b9 gives 16 files, 0 errors, 0 warnings.
• The config enables no type-aware linting (no parserOptions.project, no typed rules), so no untouched file's verdict can move.

check-governed-merges --branch: 0 of 17 paths on the register; 1083 changed lines.

Acceptance notes

• The spec's ISecurityService prose still describes the hand-off. Four TSDoc sentences on getReadFilter, canExport and canReadObject in packages/spec/src/contracts/security-service.ts say a context with no principal "is admitted" or "keeps the scope". packages/spec is outside this claim, so the sentences are not edited here. The report asks the seat how to route them.
• Two of the producers closed here are outside the cross-lane declaration. The domain:engine declaration on [PM seat] domain:engine — ⏳ vacant #6367 names promoteDraftForPublish. The census found the other protocol.ts producers listed above in the same file: the same class, with the same mechanical opt-in. They are closed here and named for the seat, so the declaration can be amended.
• A test-side spelling trap. Passing an ExecutionContext variable as the options argument of an engine verb compiles, and silently drops the context. One fixture did this. Under strict mode it is now a loud 403, no longer a silent hand-through.
• What the census cannot see. The static sweep reads sys_* object names spelled as literals; a call whose object name is a variable is covered only by the runs.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 2 package(s): @objectstack/metadata-protocol, @objectstack/plugin-security, touching 27 documentable anchor(s).

21 hand-written doc(s) name something this change touched — list omitted above 15 rows. Re-derive on the tree named below: node scripts/docs-audit/affected-docs.mjs --json 4578c56e65c1f50f04da9259579091272d319558.

⛔ 10 release-owned page(s) also affected — read-only, see AGENTS.md Documentation Guardrails.

What this run could not see

• 1 name(s) were too generic to anchor anything (single lowercase words)
• 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 — 24 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 4578c56e65c1f50f04da9259579091272d319558 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from b49796f36f5fa21598680b59709d13f830252d96 — the merge of head 454d0e89b9397900c6d4b01bd30e8e505d886bbe into base 4578c56e65c1f50f04da9259579091272d319558, 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 b49796f36f5fa21598680b59709d13f830252d96 && git checkout b49796f36f5fa21598680b59709d13f830252d96
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 4578c56e65c1f50f04da9259579091272d319558 454d0e89b9397900c6d4b01bd30e8e505d886bbe && git checkout -B drift-repro 4578c56e65c1f50f04da9259579091272d319558 && git merge --no-ff 454d0e89b9397900c6d4b01bd30e8e505d886bbe

node scripts/docs-audit/affected-docs.mjs --json 4578c56e65c1f50f04da9259579091272d319558

⚠️ 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 4578c56e65c1f50f04da9259579091272d319558 → pass the list as
args.docs, on the commit named under Which tree this was computed on.