feat(runtime,rest): /packages 域补齐授权门 —— 写要 manage_metadata、读要 D4 读集、全域匿名门,两 transport 各一份 (#7033) (#7023)

[os-project-manager]

Fixes #7033
Fixes #7023

背景

/packages 是最后一个零授权判据的路由域(packages.ts 739 行授权命中数 0,且不在 authz-conformance.matrix.ts,也没有其五个同族域都有的 shouldDenyAnonymous)。#7023 的只读普查实测:一个连 userId 都没有(身份解析产出 principalKind: 'guest')的调用方,对下面四条路由一律 200 并真的调进目标函数,其中两条破坏性。本 PR 按维护者 2026-08-09 裁定,单 PR 关掉两卡。

门的位置(在解析之前)

所有门都在 deps.resolveService(_context, 'protocol') / metadata 服务解析之前,且在改动 registry 之前。原因两条:(1) 拒绝时不写不删——「先删后拒」是本域最该防的形态;(2) 不让未授权调用方拿 501-vs-200 / 401-vs-503 的差别去指纹探测部署装了哪些能力。isSystem(不可从线上伪造)旁路,CORS OPTIONS 放行。

四路由 × 每 transport 的 before/after

零能力已认证调用方 {userId:'u_portal', systemPermissions:[]},及匿名调用方:

路由	transport	before(匿名 / 零能力)	after(匿名 / 零能力)
GET /packages(枚举面)	dispatcher	200 / 200	401 / 403(需 studio.access 或 setup.access)
GET /packages/:id/export(整包 27 类)	dispatcher	200 / 200	401 / 403(读集)
POST /packages/:id/discard-drafts(破坏性)	dispatcher	200 / 200	401 / 403(需 manage_metadata)
POST /packages/:id/publish-drafts(#7023)	dispatcher	200 / 200	401 / 403(manage_metadata)
其余写/破坏性(install/enable/disable/publish/commit-revert/rollback/revert/adopt-orphans/duplicate/manifest-PATCH/DELETE)	dispatcher	无门	401 / 403(manage_metadata)
GET /packages/:id/commits	dispatcher	无门	401 / 403(读集)
POST /api/v1/packages/publish	REST direct-mount	无门	401 / 403(manage_metadata)
GET /api/v1/packages	REST direct-mount	无门	401 / 403(读集)
GET /api/v1/packages/:id	REST direct-mount	无门	401 / 403(读集)
DELETE /api/v1/packages/:id	REST direct-mount	无门	401 / 403(manage_metadata)

两 transport 各一份门(别重演 /meta 早期只加一侧):

• dispatcher:runtime/src/domains/packages.ts —— 全域 shouldDenyAnonymous 为 handlePackagesRequest 第一条语句 + 每路由 requireManageMetadata / requireReadCapability。
• REST direct-mount:rest/src/package-routes.ts 的 refusePackageRequest,经 RestServer.resolvePackageRouteExecutionContext(与 /meta REST 门同一身份解析)取上下文;缺 resolver 失败即关(401),不留裸露回退。

读集引用常量,不复制:requireReadCapability 引用 OBJECT_SCHEMA_MASK_EXEMPT_CAPABILITIES({studio.access, setup.access},ADR-0106 D4),使 package 读 cohort 不会与 metadata 掩码豁免集漂移。

信封:dispatcher 走 deps.error(...)(wrapped {success:false, error:{code, message, httpStatus}});REST direct-mount 该面 DECLARES 的是 wrapped BaseResponseSchema,故 401/403 均经共享 sendError 发出(check:route-envelope 把该模块钉在零手写 body),不是 flat ANONYMOUS_DENY_BODY。两者都断 status + code(ADR-0112)。

pin 覆盖(每路由 × 每 transport)

• dispatcher:runtime/src/domains/packages-capability-gate.test.ts(76 例)—— 匿名 401 且 registry/目标 spy 未进、OPTIONS 不被误判 401、写门每路由(零能力 403 且目标 spy 未进、读集 cohort 403、manage_metadata 放行、isSystem 放行)、读门每路由、两 cohort 互不越界;discard-drafts 直接读库断言草稿未删(零能力 403 与匿名 401 两档,drafts 数组不变)。
• REST direct-mount:rest/src/package-envelope.conformance.test.ts 的 packages authz describe —— 四路由 × 匿名 401 / 缺 resolver 失败即关 / 零能力 403 / 错 cohort 403 / 对 cohort 放行 / isSystem 放行,拒绝断 status+code 且 service spy 未进。
• 反向验证:禁用 dispatcher 三处门 → 该测 76 例中 40 例(拒绝类)转红;禁用 REST refusePackageRequest → conformance 44 例中 16 例(拒绝类)转红;allow-path 保持绿。方向如预期(usual RED)。
• matrix:authz-conformance.matrix.ts 加 anonymous-deny-packages 行 + authz-conformance.test.ts 加 probe(shouldDenyAnonymous 命中 → key)+ high-risk;dogfood showcase-anonymous-deny-surfaces.dogfood.test.ts 加四条匿名 401 + member teeth(该 showcase 无 package 服务,/packages 由 dispatcher 服务,故归 wrapped 族)。

收尾侧

• 既有测试 boot 桩:http-dispatcher.test.ts / domain-handler-registry.test.ts / dispatcher-validation-error(.real).test.ts / error-passthrough.test.ts 原以匿名 {request:{}} 驱动 /packages,现注入持能力调用方(经 timedResolveExecutionContext 或直传 executionContext),使其继续命中各自 pin 的路由/错误映射,未削弱。
• 前 dev 中断遗留的 3 个 REST 测试(package-routes-query-multiplicity / direct-mount-base-follows-apipath / discovery-advertised-direct-mounts.parity)驱动被门路由却未过门:composition 侧注入门放行 resolver 恢复 200;plugin-boot 侧(真实 resolver、无 auth 服务)匿名探针如实断 401(路由仍已挂载)。
• changeset:两包 minor。

盲区(明说)

cloud 仓在本会话与前序普查会话中均未挂载(add_repo 两次被拒),调用方普查不覆盖该仓。若 cloud 内存在直打 /api/v1/packages/* 或 dispatcher /packages、且今天不持 manage_metadata / D4 读集的生产调用方,本门可能将其 403 —— 落地后需在 cloud 补一次调用方普查复核。#7020 记录的「门能力集 ≠ D4 掩码豁免集」对齐方向仍归维护者,本 PR 不动。

验证

• pnpm --filter @objectstack/runtime test → 117 files / 1829 passed;--filter @objectstack/rest test → 76 / 1218 passed。
• typecheck runtime + rest 均 0 error。
• check:route-envelope / check:authz-resolver / check:error-code-casing / check:empty-changeset / check:nul-bytes 均 pass;authz-conformance.test.ts 9 passed;eslint 改动文件 0 问题。

---

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		Aug 9, 2026 3:05pm

[github-actions]

📓 Docs Drift Check

This PR changes 3 package(s): @objectstack/dogfood, @objectstack/rest, @objectstack/runtime.

25 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/ai/connect-mcp.mdx (via @objectstack/rest)
• content/docs/api/client-sdk.mdx (via packages/runtime)
• content/docs/api/error-handling-server.mdx (via @objectstack/rest)
• content/docs/api/index.mdx (via @objectstack/rest, @objectstack/runtime)
• content/docs/api/wire-format.mdx (via @objectstack/runtime)
• content/docs/automation/hook-bodies.mdx (via @objectstack/runtime)
• content/docs/concepts/metadata-lifecycle.mdx (via @objectstack/runtime)
• content/docs/concepts/north-star.mdx (via packages/runtime)
• content/docs/data-modeling/drivers.mdx (via @objectstack/runtime)
• content/docs/deployment/index.mdx (via @objectstack/runtime)
• content/docs/deployment/production-readiness.mdx (via @objectstack/runtime)
• content/docs/deployment/single-project-mode.mdx (via @objectstack/runtime)
• content/docs/deployment/vercel.mdx (via @objectstack/runtime)
• content/docs/getting-started/your-first-project.mdx (via @objectstack/runtime)
• content/docs/kernel/cluster.mdx (via @objectstack/runtime)
• content/docs/permissions/authentication.mdx (via @objectstack/rest, @objectstack/runtime)
• content/docs/permissions/authorization.mdx (via packages/qa/dogfood, packages/runtime)
• content/docs/permissions/delegated-administration.mdx (via packages/qa/dogfood)
• content/docs/permissions/system-context.mdx (via packages/rest, packages/runtime)
• content/docs/plugins/index.mdx (via @objectstack/rest)
• content/docs/plugins/packages.mdx (via @objectstack/rest, @objectstack/runtime)
• content/docs/protocol/kernel/http-protocol.mdx (via @objectstack/rest, @objectstack/runtime)
• content/docs/protocol/kernel/i18n-standard.mdx (via packages/rest)
• content/docs/protocol/kernel/index.mdx (via @objectstack/runtime)
• content/docs/protocol/kernel/lifecycle.mdx (via @objectstack/runtime)

⛔ 3 release-owned page(s) also reference the affected code. These are read-only:

• content/docs/releases/implementation-status.mdx (via @objectstack/rest, @objectstack/runtime)
• content/docs/releases/v12.mdx (via @objectstack/rest)
• content/docs/releases/v17.mdx (via @objectstack/rest, @objectstack/runtime)

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.

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.