docs(adr): ADR-0106 — metadata-plane FLS, per-caller masking of object schemas (#3661 step ③)

[os-zhuang]

Step ③ of #3661, as an ADR (status: Proposed). Steps ① ② shipped client-side as objectstack-ai/objectui#2866.

Why the decision flipped

An earlier disposition ("target deployments have no untrusted authenticated users → document no-masking as the explicit default") died on the platform premise: ObjectStack customers build portals and products whose authenticated callers the platform cannot vouch for. Per ADR-0049, enforcement must therefore be the platform default — so this ADR decides to mask, and resolves the three hard problems the issue flagged (cache key, protocol context, exemptions) instead of documenting their absence.

Decision summary

• D1 — Object-schema reads project fields onto security.getReadableFields(object, caller); masked fields are removed entirely (name, label, options, formula, visibleWhen, requiredPermissions — the leak is more than names). readable only; editable stays with /auth/me/permissions, so no getEditableFields dual is needed.
• D2 — Enforcement lives in the dispatch layer (REST /meta + runtime /metadata); metadata-protocol signatures unchanged.
• D3 — Answer to the issue's §4 "structural obstacle": the shared cache keeps one full copy per object; masking runs after cache retrieval; the caller's field-visibility fingerprint (hash of the denied set, empty for unrestricted callers) folds into the ETag. Cohort-correct 304s, zero regression for unrestricted callers, no O(users × objects) blowup. Full cache bypass (doc/book pattern) is recorded as implementation fallback, not the end state.
• D4 — isSystem / platform-admin exemption (Studio/Setup authoring needs the full schema).
• D5 — Coverage: single read (cached and uncached paths), list read, runtime catch-all, plus an audit of other schema-bearing outlets.
• D6 — Three-tier failure posture: no security service → open (deployment has no FLS posture); undefined → open with telemetry + private, no-store (matches the engine-middleware and security 服务 getReadableFields 查询面(export 列投影的长期正解) #3547 export precedents; window is operational, not attacker-inducible; failing closed risks a bootstrap deadlock since permission sets are themselves metadata); evaluation throws → 5xx — never the unmasked body on an error path, never an empty-fields 200 (silently wrong and cacheable poison). Includes the reconciliation with ADR-0049 and why doc/book fail-closed is a different class (content access control vs disclosure control on infrastructure).
• D7 — Zero-permission-set callers resolve the fallback set (member_default/guest), aligning with /auth/me/permissions — public deployments' schema exposure becomes a deliberate permission-set decision.
• D8 — Default on, ships with the current major (same train as objectui#2866's breaking removal), config escape hatch; the client-side gates from ① remain complementary, not superseded.

Verification

Docs-only change. Cross-linked ADR files (0046/0049/0066/0090) verified present; no ADR index file requires registration.

Implementation (D1–D5 + tests in rest/runtime/plugin-security) is deliberately a separate PR once this is accepted.

🤖 Generated with Claude Code

https://claude.ai/code/session_01AEb4XCVb7iLEBVe9HghjTt

---

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		Jul 27, 2026 2:09pm