feat: single-source API-method derivation contract (#3391 P1)#3498
Draft
os-zhuang wants to merge 5 commits into
Draft
feat: single-source API-method derivation contract (#3391 P1)#3498os-zhuang wants to merge 5 commits into
os-zhuang wants to merge 5 commits into
Conversation
…PR-1) Introduce the spec's one source of truth for turning an object's `enable.apiMethods` whitelist into its effective operation set, and make the runtime dispatcher gate consume it. - spec: new `@objectstack/spec/data` `api-derivation` module — `resolveEffectiveApiMethods` / `isApiOperationAllowed` / `effectiveOperationsArray` / `API_METHOD_DERIVATION` / `DATA_ACTION_TO_API_OPERATION`. Three-state semantics (undefined = unrestricted, [] = deny-all, subset = derived closure); the legacy 8 verbs derive from the six primitives (get/list/create/update/delete/bulk). restore/purge never derive (enable.trash retired, #2377). liveness note updated. - runtime: rewrite `api-exposure.ts` to consume the shared table. Fixes the silent dead dispatcher/MCP gate — `getObject()` returns the flags nested under `.enable`, which the flat-only reader ignored (nested-first, flat- compatible). Flips `[]` from fail-open to deny-all. - objectql: registration-time deprecation warning for standalone legacy apiMethods values (`warnDeprecatedExplicitApiMethods`); cross-reference comments distinguishing the verb→affordance (UI-intent) axis from the verb→primitive (API-tightening) axis. - plugin-security: cross-reference comment on the parallel WRITE_OP_AFFORDANCE. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012L8EfEa157Pe6C73qRnaJH
…PR-2) Route every per-object exposure gate through the spec's single derivation source of truth, so the three-state whitelist and the derived verbs are resolved identically everywhere. - Main gate (`apiAccessDenialFromEnable`): resolver-backed; `[]` → deny-all; the 405 body's `allowed` array is now the EFFECTIVE operation set (enum- ordered), not the raw whitelist. `enforceApiAccess` forwards writeMode / bulkChild opts. - Import: two-stage gate — a coarse `create ∨ update` check 405s fully-closed objects before the CSV parse; a writeMode-precise second stage (insert→create, update→update, upsert→create∧update) after prep resolves the mode. - Export: reverse-derives from `list`, and the schema-derived column header is projected to the FLS-readable set (union of masked-row keys) so export can never expose a wider column set than list. Explicit `?fields=` is honored but masked values stay empty. - Bulk: all five surfaces (createMany/updateMany/deleteMany, per-object /batch, cross-object /batch) require `bulk ∧ child`. - platform-objects: the four in-repo explicit-whitelist identity objects gain the `bulk` primitive so their Many/batch surfaces keep working. Tests: rest exposure suite (405 allowed = effective, deny-all, bulk∧child), new rest-api-derivation-gates suite, batch endpoint bulk cases, and two blocking export FLS column-projection tests. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012L8EfEa157Pe6C73qRnaJH
#3391 PR-3) Add the response-side contract that lets the server hand the frontend the resolved effective operation set — the single channel the UI consumes, never the raw whitelist. - spec: `EffectiveObjectPermissionSchema` extends `ObjectPermissionSchema` with an optional `apiOperations` array; `GetEffectivePermissionsResponse.objects` uses it. The authoring `ObjectPermissionSchema` is deliberately NOT extended, so a permission-set author can never declare a meaningless key. - hono: `/me/permissions` now annotates each per-object entry with its effective `apiOperations` (`annotateEffectiveApiOperations`), and for a modify-all super-user seeds false-init entries for restricting objects absent from the merged map (`seedSuperUserRestrictedObjects`) so fold pulls them true. Sequence: seed → fold → clamp → annotate, each guarded (failure omits apiOperations and the client falls back to default-allow). - client: zero code — the typed surface carries the new field via the spec re-export. - changeset documenting the contract and the five behavior changes. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012L8EfEa157Pe6C73qRnaJH
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
github-actions
Bot
added
documentation
Contributor
📓 Docs Drift CheckThis PR changes 7 package(s): 116 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:
|
…3391) Auto-generated reference doc for the new EffectiveObjectPermissionSchema (`pnpm gen:schema && gen:docs`). Keeps content/docs/references in sync with packages/spec — fixes the check:docs CI gate. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012L8EfEa157Pe6C73qRnaJH
Regenerate the public-API surface snapshot (`gen:api-surface`) for the 19 new `@objectstack/spec` exports added by #3391 (the api-derivation module + EffectiveObjectPermission). 0 breaking, 19 added — fixes the check:api-surface CI gate. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012L8EfEa157Pe6C73qRnaJH
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
背景
落地 #3391 的 P1 契约(方案见 该 issue 评论,基线
main@69f1dfd5c)。服务端成为唯一裁决者:每个对象的有效操作集由 spec 里唯一一张派生表从 6 个原语(get/list/create/update/delete/bulk)白名单解析,REST gate、runtime dispatcher gate、/me/permissions注解全部消费同一张表;前端只渲染下发的 effective 结果,不读原始apiMethods。框架侧三个 PR(方案里的 PR-1/2/3)合并到本分支,按 commit 切分。objectui 侧(PR-4)属独立仓库,不在本分支范围。
改动
PR-1 — 派生真源(
d3ae192)@objectstack/spec/data新增api-derivation:resolveEffectiveApiMethods/isApiOperationAllowed/effectiveOperationsArray/API_METHOD_DERIVATION/DATA_ACTION_TO_API_OPERATION。三态语义(undefined=全开、[]=全禁、子集=派生闭包);legacy 8 值由 6 原语派生;restore/purge不派生(enable.trash已退役 [11.0][A2] Remove dead author-facing metadata properties (ADR-0049 enforce-or-remove) #2377)。api-exposure.ts重写消费共享表:修复 dispatcher/MCP 死码(getObject()返回嵌套.enable,旧扁平读取从未生效)——嵌套优先、兼容扁平;[]翻转为 deny-all。MANAGED_WRITE_VERB_AFFORDANCE、plugin-securityWRITE_OP_AFFORDANCE)加交叉引用注释,明确 verb→affordance(UI 意图)与 verb→primitive(API 收紧)两条正交轴。PR-2 — REST gate 接入(
209d3e5)apiAccessDenialFromEnable换共享 resolver;405allowed改为 effective 集。bulk ∧ child。bulk原语。PR-3 — 有效操作下发(
d9941b1)EffectiveObjectPermissionSchema(ObjectPermissionSchema.extend({ apiOperations }),仅响应侧,authoring schema 不动);/me/permissions注解每对象 effectiveapiOperations,超管 enumerate 补条目;seed → fold → clamp → annotate,全程 guarded。行为变化(收紧,均属"declared ≠ enforced"缺口收口)
apiMethods: []+apiEnabled:true→ 全 405(in-repo 零影响,[]对象均配apiEnabled:false,404 先于 405)。bulk原语(四对象已补;三方缺bulk会 405)。allowed由原始白名单改为 effective 集。测试
api-derivation.test.ts(25)、restrest-api-derivation-gates.test.ts、honoeffective-api-operations.test.ts、export FLS 列投影阻塞性两条。api-exposure.test.ts(翻转[]=deny-all + 嵌套回归)、rest 曝露套件(405 = effective / bulk∧child)、rest-batch-endpoint、spec permission/protocol。pnpm build71/71 通过;涉及包全量测试通过(spec 6880 / runtime 605 / objectql 1073 / rest 372 / hono 107 / plugin-security 540 / platform-objects 215)。后续(另开 issue,不在本 PR)
用户级 export 权限轴(接
userExportAllowed槽)、元数据不可解析 fail-open 残余风险、detail/form 面 edit/delete 接 effective、security 服务getReadableFields查询面、P2 枚举收缩、objectui 侧接线(PR-4)。Closes 部分 #3391(P1)。
🤖 Generated with Claude Code
https://claude.ai/code/session_012L8EfEa157Pe6C73qRnaJH
Generated by Claude Code