[objectstack-fleet]

Requested by Elon · project thread

domain:server#3 · os-elon-musk · session_016WV4d1MkJvadehWmrLUUT1

Fixes #28217

Clause-②: no (a call that was already refused now says why and is refused before its target is called; no credential is newly accepted anywhere, and no error code, status name, answer member or package export is added)
Metadata-protocol: none

维护者速读

• 改了什么：用 API key 调用的 type: 'api' 动作，如果目标是身份路由(/api/v1/auth/…,比如 Ban User),两个动作门(REST /actions 和 MCP run_action)在转发前就按名拒绝:401 UNAUTHENTICATED,说明这个端点只接受已登录会话，不接受 API key。目标不会被调用。
• 为什么改：身份路由只认自己的会话，从不认 API key,所以以前这个调用到了目标那里就成了匿名，拿回一句 "Sign in first",而调用方其实已经认证过了。
• 没变的：身份路由接受哪些凭据不变;会话(token 或 cookie)照旧转发;API key 调其他目标(数据门、声明的端点)照旧转发并成功。
• 先看:packages/runtime/src/action-execution.ts 的 forwardApiAction 开头和 apiActionIdentityRouteKeyRefusal。
• 需要你做的：无;Tier S,席位验收后落地。

What changes

forwardApiAction (packages/runtime/src/action-execution.ts), the one forward both action doors call, now refuses one combination before it calls the target: a caller the door admitted by API key, running an action whose target is an identity route (under /api/v1/auth/). The answer is 401 with the standard UNAUTHENTICATED code and a sentence that names the action and its identity endpoint, says the endpoint accepts a signed-in session only and not an API key, and says the action was not run. Both doors relay it the way they relay a target's own refusal: the REST door answers it, and MCP run_action throws it with the same status and code.

• The identity-route reading is one private predicate, isIdentityRouteTarget, which the existing organizationId stamp in buildApiActionRequest now reads too, so the two rules cannot disagree about which targets are identity routes.
• The sentence lives in apiActionIdentityRouteKeyRefusal, a module export like the file's other refusal sentences (@objectstack/runtime exports only its root entry, which does not re-export this module).
• Docs: content/docs/ai/actions-as-tools.mdx, the api row of the dispatch table, says an API-key caller of an identity-route target is refused 401 before the forward.

Unchanged: which credentials an identity route accepts. A signed-in session (session token or cookie) is forwarded to it exactly as before. An API-key caller is still forwarded to every target that is not an identity route, and served. This does not touch #28178 (the OAuth-agent lane), which is waiting on its own decision.

Why

An api action's forward carries the caller's own credentials so the target authorizes the same principal the door admitted. An identity route reads its caller from its own signed-in session only, so a key-admitted caller arrived there as nobody, and the target answered its anonymous 401 ("Sign in first") to a caller that had authenticated. It failed closed (triage 6530162284: a broken function, not a hole). Triage ruled that refusing by name before the forward, and pinning it, needs no decision, and that any change to which credentials an identity route accepts does.

Verification

Premise re-checked on main 86cf7cef before the change; it held as the card states.

• packages/runtime/src/domains/api-action-forward.test.ts (+5): REST door, key-admitted caller of an identity-route action: the named 401, the target never called; the same action for a session-admitted caller: forwarded as before; a key-admitted caller of a data-door target: forwarded with the key carried across. MCP run_action: the key-admitted identity-route call throws the same refusal and forwards nothing; a key-admitted non-identity target is forwarded. 42/42.
• packages/qa/dogfood/test/api-action-door-forward.dogfood.test.ts (+2, booted showcase): an admin's API key running ban_user gets the named refusal, not "Sign in first", and nobody is banned; the same admin's API key running an api action whose target is the data door is served and the row changes. 10/10.
• Ablations: refusal removed ⇒ the two identity-route key pins red in the unit file, and the dogfood key pin red (it answered "Sign in first"); refusal keyed on the target alone ⇒ 13 red, the session lane among them; keyed on the credential alone ⇒ the two non-identity key pins red. With the fix, all green.
• pnpm --filter @objectstack/runtime typecheck green; the runtime suite green (487 files, 7912 passed); the dogfood package compiles with no error in the touched file.
• Every family dispatch-gates --commands derives (91) ran and exited 0, reconciled with --ran (0 NOT-MEASURED, after a whole-tree build); pnpm lint exits 0.

Skills-docs: grep -rniE "forward|api.?key" skills content/docs read for api-action forwarding and API-key callers: content/docs/ai/actions-as-tools.mdx describes the forward and gains the sentence above; no skill describes the forward or API-key callers of actions.

Human Minimum

• 1. Schemas start as Zod; packages/spec holds no runtime logic.
• 2. Every name I added uses the casing for its kind.
• 3. No formatter ran; pnpm lint passes.
• 4. One issue, one branch off an up-to-date main, one pull request.
• 5. A change that publishes carries a changeset, and both declaration lines are filled in here and in the changeset.
• 6. packages/spec touched: its generated artifacts are regenerated and committed. (Not touched.)
• 7. No hand edits to content/docs/references/, packages/*/CHANGELOG.md or content/docs/releases/.
• 8. Title, body and comments are in English (the 维护者速读 block is the lane's maintainer summary).

🤖 Generated with Claude Code

https://claude.ai/code/session_016WV4d1MkJvadehWmrLUUT1

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/runtime, touching 6 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 99a6a781b391083ed143ac8953041732dc745512.

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

What this run could not see

• the SDK route bridge reached 58 of 210 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 — 28 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 99a6a781b391083ed143ac8953041732dc745512 → packageMentionDocs.

Which tree this was computed on

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

node scripts/docs-audit/affected-docs.mjs --json 99a6a781b391083ed143ac8953041732dc745512

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

[objectstack-fleet]

domain:server#3 · os-elon-musk · session_016WV4czuTWNgKR22fKv7jia

Seat ACCEPT · PR #28263 · head cf29292bf3ffa037981a8b10886843e113f72734 · 2026-10-30T21:26Z

维护者速读

• 改了什么： 用 API key 调用一个转发到身份接口（/api/v1/auth/…，例如封禁用户）的 api 动作时，动作门在转发前就以 401 UNAUTHENTICATED 拒绝，并说明原因：该接口只认已登录会话、读不了 API key，动作没有执行（runtime: an api action that forwards to an identity (better-auth) route fails for an API-key caller, and nothing pins it #28217）。
• 为什么改： 以前请求被转发出去，再被目标以匿名身份退回「请先登录」，对一个已经认证过的调用方是误导。
• 风险与回滚： 不放宽任何东西：身份接口接受哪些凭据不变；已登录会话照旧转发；API key 转发到其他目标（数据门等）照旧放行。状态码与原来相同（401），只是改在转发前、并带上原因。回滚即还原 action-execution.ts。
• 先看： action-execution.ts 的 forwardApiAction 开头新增的判断，和 apiActionIdentityRouteKeyRefusal。
• 两分钟验证： 跑 api-action-forward.test.ts 与 api-action-door-forward.dogfood.test.ts。
• 需要你做的： 无（Tier S；无需契约复核，按本期落地授权由席位落地）。

席位核对

• Shape: draft → main, Fixes #28217. 5 files (+219/−8): action-execution.ts, one new unit test file, the door-forward dogfood (API-key lane added), one docs row (content/docs/ai/actions-as-tools.mdx), one changeset. check-governed-merges --pr 28263: NOT governed.
• Premise: measured by the runtime(mcp): an OAuth-token agent's api action forward carries a bearer the target door does not accept (acceptOAuthAccessToken matches /mcp paths only), so the target likely resolves the caller as anonymous #28178 card thread on main @ 6fd87b7e; re-checked on main before the fix.
• File surface: within the claim (6531967204), plus the one docs row (the Skills-docs line). Worktree was objectstack-issue-28178 (the card thread's), not the claimed objectstack-issue-28217; recorded here.
• Declarations: Clause-②: no (seat re-derived from the diff: same 401 status, the existing UNAUTHENTICATED code, no answer member added, the new helper is not exported from the package entry, no credential newly accepted). Metadata-protocol: none. @objectstack/runtime patch. No contract review is owed: not a narrowing of anything that served, no packages/spec path.
• Boundary (triage 6530162284): which credentials an identity route accepts is unchanged; the refusal is by name before the forward, which triage said needs no ruling. runtime(mcp): an OAuth-token agent's api action forward carries a bearer the target door does not accept (acceptOAuthAccessToken matches /mcp paths only), so the target likely resolves the caller as anonymous #28178 (the OAuth lane) stays parked on its ruling and is not touched here.
• Local (card thread): dispatch-gates 91/91 green, 0 NOT-MEASURED; pnpm lint 0; runtime suite green; door-forward dogfood 10/10. 5 unit pins and 2 dogfood pins, each ablated. Report 6533476338.
• Gate check-runs on this head: 50 total, 38 success, 12 skipped by the path filter, 0 failed. mergeable_state: clean.
• Landing: Tier S, under the maintainer's landing grant for this term (2026-10-29 22:05Z, seat thread). Ready + auto-merge through the relay.

ACCEPT