feat(security): the record field-access answer says whether the record itself is writable - #27232

📓 Docs Drift Check

This PR changes 3 package(s): @objectstack/plugin-security, @objectstack/plugin-sharing, @objectstack/spec, touching 21 documentable anchor(s). ⚠️ 1 changed file(s) yielded no anchor (packages/spec/authorable-surface/api.json), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

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

• content/docs/kernel/contracts/index.mdx (via ISecurityService (symbol, a top-level interface))
• content/docs/kernel/runtime-services/index.mdx (via ISecurityService (symbol, a top-level interface))
• content/docs/permissions/attachments-access.mdx (via ISecurityService (symbol, a top-level interface))
• content/docs/permissions/field-level-security.mdx (via SecurityPlugin (symbol, a top-level class), data.fieldAccess (sdk, the route ledger binds it to GET /api/v1/data/:object/:id/field-access, selected by route anchor /:object/:id/field-access), fieldAccess (sdk, the bare tail of client method data.fieldAccess, bound to GET /api/v1/data/:object/:id/field-access), /:object/:id/field-access (route, bridged from symbol getRecordFieldAccess — its route source's handler names it))
• content/docs/permissions/index.mdx (via SecurityPlugin (symbol, a top-level class))
• content/docs/permissions/system-context.mdx (via buildSharingMiddleware (symbol, a top-level function), registerAuthzMiddleware (symbol, a top-level function))
• content/docs/plugins/packages.mdx (via SecurityPlugin (symbol, a top-level class))
• content/docs/protocol/objectql/security.mdx (via /:object/:id/field-access (route, bridged from symbol getRecordFieldAccess — its route source's handler names it))
• content/docs/ui/forms.mdx (via SecurityPlugin (symbol, a top-level class))

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

• content/docs/releases/implementation-status.mdx (via SecurityPlugin (symbol, a top-level class))
• content/docs/releases/v17/17-0.mdx (via ISecurityService (symbol, a top-level interface))
• content/docs/releases/v17/17-3.mdx (via SharingService (symbol, a top-level class))
• content/docs/releases/v17/17-5.mdx (via ISecurityService (symbol, a top-level interface))
• content/docs/releases/v17/17-6.mdx (via ISecurityService (symbol, a top-level interface))
• content/docs/releases/v17/17-7.mdx (via ISecurityService (symbol, a top-level interface))
• content/docs/releases/v18/18-0.mdx (via ISecurityService (symbol, a top-level interface), SecurityPlugin (symbol, a top-level class))
• content/docs/releases/v18/18-1.mdx (via SharingService (symbol, a top-level class))

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.

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 584fc2b908cad98fca1af8cc9e802cee5e95aaa9 && git checkout 584fc2b908cad98fca1af8cc9e802cee5e95aaa9
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 9ff8154cf694c616de5d467b35af21e037de1509 7047dcbc9ba4b828db0e9da0bd62b87f6911555f && git checkout -B drift-repro 9ff8154cf694c616de5d467b35af21e037de1509 && git merge --no-ff 7047dcbc9ba4b828db0e9da0bd62b87f6911555f

node scripts/docs-audit/affected-docs.mjs --json 9ff8154cf694c616de5d467b35af21e037de1509

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

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 58e92a4013f94552a9511684aeed262a1c9c1411
Local-runs: none
Scope: packages/spec/src/api/protocol.zod.ts, packages/spec/src/contracts/security-service.ts + packages/plugins/plugin-security/src/record-row-write-probe.ts, packages/plugins/plugin-security/src/security-plugin-authz-middleware.ts, packages/plugins/plugin-security/src/security-plugin.ts, packages/plugins/plugin-security/src/security-plugin-addressed-writes.ts, packages/plugins/plugin-security/src/security-plugin-cbp-write-gate.ts, packages/plugins/plugin-security/src/security-plugin-sharing-verdicts.ts, packages/plugins/plugin-sharing/src/sharing-service.ts, packages/plugins/plugin-sharing/src/sharing-plugin.ts, packages/objectql/src/engine.ts (update(), executeWithMiddleware), packages/rest/src/data-action-routes.ts (the field-access route), packages/metadata-protocol/src/protocol.ts (updateData), packages/qa/dogfood/test/record-field-access-when.dogfood.test.ts, packages/qa/dogfood/test/fixtures/record-field-access-fixture.ts, the three .changeset/27175-* files. Every other engine middleware registration on the head was read to find a refusal the probe would miss (organizations, auth, approvals, audit, mailbox, storage, runtime, the security start hooks). The rest of the diff (generated protocol.mdx, api.json, field-level-security.mdx, the unit tests) is the lane seat's ACCEPT at TIER_DEFAULT.

Inputs: card #27175 (body; triage 6465932161; claim 6466687477; amendment 6466781443; dev report 6468120932), PR #27232 (body, 17-file list, net diff against main), the check-runs on the head. Rulings read: 6457467702 (#26594 B, no second evaluator), #26368 A (protocol addition is p1).

Check-runs on the head at render time: green — Lint & Repo Gates, every Lint · lane, Type Check · source gates / consumer gates / debt ledger, Build Core, Build Docs, Build UI Deps, Build & E2E UI, Test UI, Dogfood Regression Gate, Governed Surface Queue Guard, Check Changeset, Check PR Size, Spec property liveness, PR-body guards. Still in_progress: Test Core (1/8 … 8/8), Type Check · workspace, Type Check UI. No red. The landing waits on those three families as it would on any PR; this record judges the tree, not the run.

① Derived judgments

1. GetRecordFieldAccessResponseSchema gains a required writable: boolean — a widening of a published response (GET /api/v1/data/{object}/{id}/field-access); editable, readable, recordId, object unchanged. Right: the card and triage ask for exactly one boolean, no closed reason (the gate has no row-reason vocabulary; the PR shows why). The describe's pointer from editable to writable is right. The inferred GetRecordFieldAccessResponse type is the contract's return type, so ISecurityService.getRecordFieldAccess carries the member without a signature edit; the only producer in the tree (SecurityPlugin.getRecordFieldAccess) supplies it on every branch, including the mask.kind === 'answer' branch. A third-party ISecurityService implementing the optional method now owes the member — a type-level consequence of a response widening, declared by Clause-②: yes (widening), and the REST consumer feature-detects the method, not the member. Right.
2. @objectstack/plugin-sharing: SharingService.admitsByIdWrite(object, recordId, verb, context) and byIdWriteGateInstalled are new public members on an exported class; the middleware body moved into the method verbatim (canEdit/canDelete, the ADR-0090 D10 delegator leg with __delegatorWriteScope, the On objects that carry sharing rules, sharing middleware answers FORBIDDEN before RLS update-wideners are consulted — the identical widener works on rule-less objects #5493 probeAuthoredRowWrite deferral, in the same order; refusal messages and log lines unchanged). Right, and pinned (sharing-service.test.ts: both verbs, four pairs, the middleware asks the method once per write).
3. @objectstack/plugin-security: registerAuthzMiddleware returns the handler it registers (not re-exported; surface unchanged); record-row-write-probe.ts is not on src/index.ts, so ROW_WRITE_PROBE, isRowWriteProbe and probeRecordRowWrite are package-internal. Right. The epoch bump is the one guard added inside the handler body; everything else the handler does is unchanged.
4. getRecordFieldAccess now performs the probe on every call, before the mask.kind branch, so a system context and a row-less answer both carry it. Right (the unit pin on { isSystem: true } answers writable: true, which is what the chain does: the handler returns next() at once and sharing's canEdit admits a system context).
5. The dogfood leg now boots AuditPlugin to pin "no audit row" — a fixture widening in packages/qa/dogfood, in scope of the card's own named test. Right.
6. Generated artifacts regenerated: content/docs/references/api/protocol.mdx, packages/spec/authorable-surface/api.json (api/GetRecordFieldAccessResponse:writable). Judged by the gates (Type Check · source gates green; · workspace pending).
7. Hand-written docs: content/docs/permissions/field-level-security.mdx projection bullet; Skills-docs: none with the measurement stated (skills/** names no reader). Right.

② Semver level

Three changesets, each minor: @objectstack/spec, @objectstack/plugin-security, @objectstack/plugin-sharing. Each carries Clause-②: yes (widening) and Metadata-protocol: added, matching the PR body. The spec changeset's "Supersedes, in the same release" paragraph names the unreleased #26594 note's old shape. The level matches what the diff publishes: one response member added, two public service members added, nothing removed or narrowed, so minor on all three and no BREAKING banner or ADR-0087 marker owed. On the Metadata-protocol arm: a response member is not a key an author writes, so the strict reading of the checklist's definition is none; the claim and triage asked for added, the generated authorable-surface register did gain the key, and minor is the floor either way — accepted as declared, no change asked.

Clause-②: yes (widening)

③ Boundary flags

• open_questions: [] — nothing to answer.
• Known effect (PR body): a refused probe logs the gate's refusal warn line. Not accepted as-is — see ④ S3 (should-fix).
• Out-of-scope finding 1 (approvals record lock not in writable; whether the edit dialog reads getRecordLock): correctly left to Record edit dialog: on a row the caller may read but not write (sharing / RLS / ownership), the fields are offered as editable and the save is refused whole — the dialog never asks whether the row is writable #27138's dispatch. Escalated to seat 1 to carry onto Record edit dialog: on a row the caller may read but not write (sharing / RLS / ownership), the fields are offered as editable and the save is refused whole — the dialog never asks whether the row is writable #27138's claim; the describe names the lock as a residual (④ condition 2 met).
• Out-of-scope finding 2 (@objectstack/client data.fieldAccess and the rest route comments describe the field projection only): accepted; keeping those packages out of the release is the right call, and the type picks the member up.
• Human Minimum 3 unchecked ("no formatter ran; pnpm lint is CI's run"): Lint · ESLint is green on the head. Accepted.
• Branch claude/project-thread-askd75 instead of claude/issue-27175-slug: declared in the claim as harness-pinned. Accepted.
• Two derived gates exited 3 on first run for a missing prerequisite dist and 0 after the build; nothing in the diff moved between runs. Accepted.
• Ruling 6457467702 B (no second evaluator): met in the tree — the verdict runs the registered handler object and the method the sharing middleware itself refuses on; nothing is re-derived.

④ Design judgment

packages/spec/src/api/protocol.zod.ts — writable against its ruling, its producer and its first consumer. The schema says: whether the caller may update this record at all, judged by the write gate on the stored row (object edit permission, sharing and ownership, RLS, controlled-by-parent); false = refused whole; true ≠ a save will succeed (approval lock, readonlyWhen/validation on the values sent, a datasource that refuses writes). I read the producer to make that sentence false.

What a real PATCH /data/{object}/{id} meets, in order (metadata-protocol.updateData → engine.update(object, { ...body, id }, { context })): assertWriteAllowed (datasource, object-level), enforceTransactionOrigin, option folding, resolveEngineUpdateDispatch (by-id from the payload id), then executeWithMiddleware — every registered middleware in registration order, then the executor (hooks, validation, driver, audit). The probe hands the security handler { object, operation: 'update', data: {}, options: { where: { id }, context: copy }, context: copy, [ROW_WRITE_PROBE]: true } and a terminal next() that asks SharingService.admitsByIdWrite with the stamped copy and then throws a private sentinel.

Where the two could disagree, and what the tree says:

• Id addressing. The handler reads the row id through extractSingleId (payload id, else options.where.id) and resolveEngineUpdateDispatch(data, options); both answer the same row for { where: { id } } as for { id } in the payload. Same row judged.
• Pre-image (2.7) and the ownership floor. Same findOne({ $and: [{ id }, ...writeParts] }, context) as the caller, same resolvePreImageFloorDrop asking sharing's checkEdit; a hidden row answers the same 404/403. A transferred row passes here and is refused only by the sharing leg — the amendment's reason for the second leg, and the sharing leg is asked with __writeScope/__delegatorWriteScope as the handler stamped them on the copy (pinned in security-plugin.test.ts). The sharing middleware's own path for an update is inferTargetId → admitsByIdWrite → refuse or next(), nothing before it, so asking the method directly skips no early return.
• Controlled-by-parent (2.8). With {} the master is read from the stored row (as system), writesMasterReference and askBodyNamedMaster do nothing — exactly a PATCH that leaves the FK alone.
• Payload gates (2.5, 3.5, 3.6, 3.7) over {}. FLS forbids nothing; the owner/queue guard skips (rows.some(writesOwner) false); the tenant wall's preTest runs and judgePayload([{}]) judges no value; step 3.6 builds postImage = { ...pre, ...{} } — the stored row — and judges it against the check policies (see S2).
• Chain order. Every other middleware on the head was read: organizations A is insert-only, B/C are post-next(); auth's two are pass-through or post-next(); the security start hooks are object-scoped (sys_user_position, sys_user_permission_set, sys_member) or post-next(); approvals', audit's, mailbox's and storage's are read-side or scoped to their own objects (sys_comment, sys_attachment, sys_mail_message, sys_approval_request, the ledger); runtime's and sharing's second one are post-next() on sys_organization. For a business object no third middleware refuses a by-id update at row level: the two legs are the whole row gate.
• Engine-side judgements the probe never reaches. The stored-row check seam (security: a by-id UPDATE's row-level check is judged on the pre-hook change set, so a beforeUpdate stamp that rewrites a checked field (e.g. the organization derived from a re-pointed parent) is stored unjudged — the tracker #16790 now answers 404 #19989) and the stored-row tenant wall (plugin-security: the Layer 0 tenant write wall (step 3.7) judges only an organization_id present in the payload as sent, so a beforeUpdate hook that writes organization_id itself can store the row in another tenant #20013) run in the executor; on an empty payload the pre-next() 3.6 judgement already judged the stored row, and a row the caller can read is inside the Layer 0 filter the write wall reuses, so neither flips a true. beforeUpdate hooks are the declared class (approvals lock; the auth/sharing/email/webhook guards are on their own sys_ objects).
• Side effects (seat 1's condition 1). The executor is never reached (sentinel thrown from the terminal next(), caught only by probeRecordRowWrite; await next() at the handler's end is not wrapped, so the post-next() seam assertion never runs and never converts the sentinel). The engine's own writeEpoch.bump lives in executeWithMiddleware, which the probe bypasses; the handler's bump is guarded by isRowWriteProbe (pinned both ways). The handler stamps __writeScope, __preImage, writePrecondition, postHookWriteImageCheck, tenantLayer0Verdict on the probe's own opCtx or on the context copy; the caller's context is pinned unchanged. No emit, no report sink, no durable write anywhere on the refusal paths (the only channel is ctx.logger.warn). Memo fills (permission-set resolution, field-name cache) are the reads' own. The dogfood leg pins the stored row equal and no sys_audit_log row across three probes, with one real save as the control. Met.
• Approvals lock (condition 2). A beforeUpdate hook judged on the values sent, with its own reader getRecordLock; the describe, the contract TSDoc and the probe header name it as a residual. Met.
• describe() names the residuals (condition 3). Names the approval lock, readonlyWhen/validation on the values sent, a datasource that refuses writes. Does not name the amendment's "other plugins' middlewares" (own-object gates) nor the REST door's object enable exposure policy. Partly met — S1.
• Fail-closed. No handler (null until start(), or no engine), a handler that answers without passing on, an unexpected throw, a sharing service without the method: all false. enforce: false sharing: byIdWriteGateInstalled stays false and the leg is skipped, as the chain skips it. Right.

Findings:

• S1 (should-fix) — protocol.zod.ts writable describe, mirrored in security-service.ts: name the two residuals the tree has and the amendment declared. (a) A platform object's own gates (sys_comment, sys_attachment, sys_mail_message, sys_approval_request): their middlewares and hooks live outside the two legs, so true on such a row is the two legs' answer only. (b) The object's REST exposure policy (enable, judged by enforceApiAccess at the door, 'get' on this route and 'update' on the PATCH): an object exposed read-only answers writable: true and refuses the PATCH before the engine. The PR body and the probe header name (a); the published describe, which the ui reads, names neither. One sentence each.
• S2 (should-fix) — protocol.zod.ts writable describe: "False means an update of this record is refused whole, whatever it changes" over-claims for a row-level check policy. Step 3.6 judges { ...storedRow, ...{} } against the check filter, so a stored row outside its check scope (showcase's check: 'owner == current_user.email' on a row owned by someone the caller may otherwise edit) answers false, while a save that re-points the checked field into scope is admitted by the same step and by the engine seam. The verdict is the gate's own and the card's "iff" is met; the sentence is not. Say "or the stored row fails a row-level check the save would have to satisfy" (or drop "whatever it changes"). Not pinned by any test (the unit pins use using only; the dogfood fixture has no check).
• S3 (should-fix) — security-plugin-authz-middleware.ts (the 2 and 2.7 refusal sites) and sharing-plugin.ts (the by-id refusal site): a refused probe logs the gate's refusal warn with operation: 'update', so every open of a read-only record's form now writes a line indistinguishable from a denied write attempt. The symbol is already on opCtx for the one guard; tagging the three log metas with probe: true (or dropping the level to debug for a probe) costs three lines and keeps the security log honest. The PR declares the effect and leaves it; AGENTS.md's own argument about a warning channel trained to be ignored applies.
• Noted, no finding: the field-access call now costs the route's own read plus the projection read plus 2–4 reads inside the probe (the 2.7 re-read, the 3.6 pre-image when a check exists, the CBP master read, sharing's row and share reads). Per form open, acceptable.

packages/spec/src/contracts/security-service.ts — against its implementer and its first consumer. The TSDoc says writable is the gate's own verdict and lists what true does not promise; the return type is the spec-inferred shape, so the member is typed, and the REST route (data-action-routes.ts) relays the object whole after its own read of the row (getData first, so no projection discloses a hidden row). null/undefined semantics unchanged. S1 applies to this TSDoc too. Holds.

No must-fix. The verdict's two legs are the write's two legs, run as the write runs them, on a row address the write resolves identically, with nothing written and nothing bumped; the three should-fixes are wording on the published describe and a log line, none of which makes writable disagree with a PATCH that the describe does not already caveat.

Implemented-by: claude/project-thread-askd75
Reviewed-by: session_01WGufzfhobWEgUUrjz4rrbh

VERDICT: PASS

Rendered 2026-10-28T11:56Z.

席位核对 · ACCEPT · domain:spec seat 1 (#6017) · session session_01WGufzfhobWEgUUrjz4rrbh · 2026-10-28T13:17Z

Head 7047dcbc9ba4b828db0e9da0bd62b87f6911555f. Card #27175, claim 6466687477, amendment 6466781443, dev report 6468120932.

• Contract review: owed at CONTRACT_REVIEW_TIER, schema face. Record 6468362768 at 58e92a40 is a PASS with no must-fix. All three seat conditions are met:
  • The probe has no side effects. The executor is never reached, the epoch bump is skipped for a probe, and the context is a copy. The dogfood run shows no audit row.
  • The approvals lock is a declared residual, now carried on Record edit dialog: on a row the caller may read but not write (sharing / RLS / ownership), the fields are offered as editable and the save is refused whole — the dialog never asks whether the row is writable #27138 (6468378207).
  • describe() names the residuals.
    The reviewer could not produce a false true or a false false against a real by-id PATCH.
• Should-fixes closed in 3c6d9ca7:
  • S1: the writable describe and the contract TSDoc now name the platform's own rules for its own records (comments, attachments, mail messages, approval requests) and an object the API serves read-only.
  • S2: false is worded for a row-level check policy: a save that moves the checked value back inside the check can still pass. A new unit pin with a check policy covers it.
  • S3: every security refusal site a probe can reach goes through logGateRefusal. A probe is logged at debug with probe: true, while a real write still logs at warn. A pin checks that a refused probe logs no "Access denied" warning, with a real refused update as the control. sharing-plugin.ts is unchanged, which is right: the probe calls admitsByIdWrite directly, and that method logs no refusal. The seat read the hunks.
• Delta: e1fb8b67 merges main (no rebase; one prose conflict in field-level-security.mdx resolved). 7047dcbc regenerates the protocol reference.
• Dev readings on this head: plugin-security passes 5106 tests and plugin-sharing 1280. Dogfood file 10/10. Derived gates: 108 run, 0 NOT-MEASURED, all exit 0.
• Gates: check-runs on this head are 41 success, 9 skipped and 0 red. mergeable_state is clean.
• Landing: check-governed-merges --pr 27232: NOT governed, 693 changed lines. Tier S. pr_ready + automerge_enable in this act.