[objectstack-fleet]

Requested by Bill · project thread

domain:server#2 · os-bill · session_01Utp6CZbTJpa9PNbpp3fdB7

Fixes #30398

Clause-②: yes (widening) — a new authenticated HTTP read, GET /api/v1/auth/admin/client-address, ledgered server-only in the plugin's auth route ledger; no spec schema, SDK method or package export moves.
Metadata-protocol: none

维护者速读

• 改了什么：新增一个只读接口 GET /api/v1/auth/admin/client-address，平台管理员在保存「允许的 IP 段」之前，就能看到服务器会拿哪个地址去判（clientAddress），以及是否信任代理转发头（trustProxy）。
• 为什么改：这个地址以前只出现在保存被拒的提示里，管理员只有先被拒一次才知道服务器认的是哪个地址；控制台也不能自己猜，因为放在代理后面时浏览器看到的地址不是服务器判的那个。
• 风险与回滚：只加不改。地址取自保存校验自己的那一次调用，两边不会说法不一；只有平台管理员能读，未登录 401、非管理员 403，匿名的 /config 不变；响应带 no-store。保存校验和登录闸门的判法一字未变。回滚即撤本 PR。
• 先看：packages/plugins/plugin-auth/src/allowed-ip-ranges.ts 的 judgedClientAddress（两扇门共用的取址）；client-address-read.ts（接口本体）；allowed-ip-ranges.pin.test.ts 末尾 #30398 用例（同一连接分别问接口和保存，结果逐字相等）；两个 dogfood 的 /admin/ 路由清点各加一行归类。
• 两分钟验证：pnpm --filter @objectstack/plugin-auth exec vitest run src/allowed-ip-ranges.pin.test.ts，预期 1 个文件、21 条全绿。
• 需要你做的：无，席位落地。

What changes

The rule: the address shown to an administrator before a save is the address that save is judged by, because both come from one call.

• judgedClientAddress (allowed-ip-ranges.ts). The save check's inline call to AuthManager.resolveClientAddress moves into an exported helper: the request's peer address plus only the forwarded-address headers the rule reads (FORWARDED_CLIENT_ADDRESS_HEADERS, the narrowing the settings service already applies to the save check's input, so on that path it is idempotent), server.trustProxy read inside the manager as before. The save check calls it with the same input it had; its refusal copy is untouched. The transport type it takes, formerly the file-private WriteTransport, is exported as RequestTransport (package-internal: allowed-ip-ranges.ts is not on the package's exports).
• GET /api/v1/auth/admin/client-address (client-address-read.ts, mounted in auth-plugin.ts). Answers 200 { success: true, data: { clientAddress, trustProxy } } with Cache-Control: no-store. clientAddress is judgedClientAddress on this request's headers and transport peer, in the rule's own text (an IPv4-mapped peer reads ::ffff:127.0.0.1, as the save refusal's constraint.clientAddress names it), null when no address can be established. trustProxy is AuthManager.trustsForwardedHeaders(). Closed, empty query set: any parameter is refused 400 VALIDATION_ERROR before the address is read (AGENTS.md route rule 5). No body is read.
• Who may read it. The shared gateAdmin every ObjectStack /admin/* auth mount calls (ADR-0068 D2 judge, platform-admin-gate.ts): no session 401 UNAUTHENTICATED, a held session (ADR-0069 D3) 403 with the posture's code, any other non-platform-admin 403 PERMISSION_DENIED, each before the read runs. Not on the anonymous GET /api/v1/auth/config.
• Ledger. One objectstack-mount row, server-only, in auth-route-ledger.ts, and the conformance pin's hand-written objectstack set gains the route. pnpm check:auth-mount-ledger: 25 mounts, all accounted for.
• The two /admin/ route sweeps (dogfood). A mounted /admin/ route is in scope of both at once, so each classifies it: admin-platform-admin-standing.dogfood.test.ts lists it in ADMITTED (the platform admin is not refused), admin-route-nonadmin-refusal.dogfood.test.ts as objectstack-gate (anonymous 401, member 403, admin not refused). No payload is needed: nothing is read before the gate.
• For the ui half (Allowed IP ranges console field: show the caller's current address before saving, and show the refusal's address when a save would lock the admin out #30313 item 1). Call GET /api/v1/auth/admin/client-address (same-origin, session cookie) on the Authentication settings page and show data.clientAddress beside the Allowed IP ranges field; null means the server cannot establish the address (any non-empty list would then be refused). A 403 IP_NOT_ALLOWED from it means the caller's address is already outside the list in force (the D5 gate answers it, see Acceptance notes).
• Not changed: the save check's verdict and copy, the sign-in gate, resolveClientAddress, service-settings, packages/spec, the SDK.

Why

#30398: the save check from #30309 refuses a list that leaves out the saving request's address and names it, but nothing served that address before a save, so an administrator learned it only by being refused, and the console had no correct way to show it (triage 6655147452: the served address must come from the function the save check judges with; the client never guesses its own address).

Verification

Measured first, at 6fa842af: no auth route, no /api/v1/auth/config field and no GET /api/settings/auth field answers resolveClientAddress; the save check (allowed-ip-ranges.ts) is its only settings-side caller. get-session serves the session row's ip_address, which is a different fact (see Acceptance notes).

Tests

allowed-ip-ranges.pin.test.ts › #30398 (the shared harness: real AuthPlugin, real SettingsService with the shipped auth manifest, real settings routes for the save, and now the plugin's real auth routes on a real Hono app for the read, the transport peer supplied the way @hono/node-server supplies it). Each address case asks the read and then saves 192.0.2.0/24 from the same connection, and asserts the read's clientAddress equals the refusal's constraint.clientAddress:

• direct peer 203.0.113.9; IPv4-mapped peer ::ffff:127.0.0.1 (not rewritten to dotted); trustProxy declared with X-Forwarded-For: 198.51.100.7, 10.0.0.2 (leftmost entry); trustProxy not declared with forged X-Forwarded-For and X-Real-IP (the peer 10.0.0.1 at both doors); no peer at all (null at both doors).
• Cache-Control: no-store.
• refusals before any address is read (trustsForwardedHeaders never called, no data): no session 401 UNAUTHENTICATED; a signed-in non-admin 403 PERMISSION_DENIED; a held platform admin 403 MFA_REQUIRED; an unknown query parameter 400 VALIDATION_ERROR.

auth-route-ledger.conformance.test.ts: the objectstack-sourced set includes the route, and better-auth does not serve it.

pnpm --filter @objectstack/plugin-auth test on the merged head 889cbec8: Test Files 224 passed (224), Tests 3961 passed | 10 skipped (3971); again after merging main f7afab86 (tree of 5db8d66e, closure rebuilt): Test Files 224 passed (224), Tests 3964 passed | 10 skipped (3974). pnpm --filter @objectstack/plugin-auth typecheck: exit 0 (check:test-typecheck OK, debt ledger unchanged).

Dogfood: the full suite under the verify lock on the tree of 5db8d66e (closure built, no shard) went red on exactly the two /admin/ sweeps, each naming GET /api/v1/auth/admin/client-address as unclassified (Test Files 2 failed | 417 passed | 3 skipped (422), Tests 2 failed | 3490 passed | 36 skipped (3528)). That run is the red leg for the two classifications above; with them, both files pass (Test Files 2 passed (2), Tests 15 passed (15)). On the final head 843cf4fe (main f273c9fe merged, closure rebuilt): pnpm --filter @objectstack/plugin-auth test Test Files 224 passed (224), Tests 3964 passed | 10 skipped (3974); full dogfood under the verify lock (pnpm --filter @objectstack/dogfood test, no shard), lock verdict command-exit 0: Test Files 419 passed | 3 skipped (422), Tests 3492 passed | 36 skipped (3528).

Ablations (scripts/ablation-replace.mjs; the suite imports src directly, no build between legs)

#	Mutation	Red
A1	read answers clientAddress: null	direct peer, mapped peer, trustProxy, forged XFF (4 failed)
A2	read strips ::ffff: (the session row's canonical text)	mapped peer (1 failed)
A3	read answers the transport peer only, ignoring trustProxy	trustProxy declared (1 failed)
A4	read believes X-Forwarded-For without trustProxy	forged XFF ignored (1 failed)
A5	read invents 0.0.0.0 for an undetermined address	undetermined reads null (1 failed)
A6	Cache-Control header dropped	no-store (1 failed)
A7	the route ignores the gateAdmin verdict	401, 403 non-admin, 403 held (3 failed)
A8	closed query set opened	query refusal (1 failed)
A9	the save check judges the peer alone (drifts from the shared helper)	the #30203 trustProxy save pin and the #30398 trustProxy equality pin (2 failed)

Each mutation landed (anchor 1 to 0, blob changed) and each restore leg reported blob equal to HEAD and git diff HEAD empty. A7's first attempt was refused by the tool before running anything (its replacement was a substring of its anchor, so the replacement count could not rise); it was re-run with a replacement that lands, and only that run is in the table.

Gates (head 843cf4f)

• Final change set (9 paths): node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack derived 68 families at 510dffb6; each ran with its exit code written to a file before any pipe, after a build of every package; --ran with :: exit <code> on every line: 68 derived famil(ies) accounted for — 68 run, 0 NOT-MEASURED (a DERIVED zero — all 68 recorded an exit code and none of them is 3). All 68 exit 0. pnpm lint exit 0.
• Then main f273c9fe was merged (head 843cf4fe, no conflict, nothing under plugin-auth or the two dogfood sweeps). The gate list re-derived there is byte-identical (68); the two gates whose inputs the merge touched (scripts/cross-package-test-inputs.mjs reads the changed codemod) re-ran, exit 0: check:cross-package-test-inputs, check:ci-filter-parity.
• Earlier rounds, for the record: at 889cbec8 three families first exited 3 on an unmet prerequisite and passed on re-run (check-plugin-teardown-shape.mjs --self-test after fetching its fixture commit 621a4876; check:dual-build-cjs-loads after a whole-closure build; check:type-check-debt after a lock queue timeout behind this card's own build). In the 510dffb6 round all three exited 0 first time.

Acceptance notes

• Gate population. The read uses the /admin/* family's one judge (platform admin), not a fresh manage_platform_settings check through the settings door's composition. With the shipped permission sets the two populations are the same callers: platform-admin standing is derived from holding admin_full_access (resolveAuthzContext), which carries manage_platform_settings, the auth namespace's read and write capability, and organization_admin withholds that capability. They part only at two edges: a custom permission set granting manage_platform_settings without admin_full_access may save but is refused the read (it loses only the hint; the save check still names the address), and the judge's legacy role === 'admin' fallback may read its own address without being able to save. Judging the settings capability exactly would mean re-composing the settings door's resolver call, held-session and outage relays inside plugin-auth, a second copy of a door; not done here.
• The session row's address is not this address. get-session serves session.ipAddress, stamped at sign-in in its canonical text (client-address-canonical.ts: an IPv4-mapped peer is stored dotted). It can differ from the current connection (the address changed since sign-in) and from the judged text, so it was not reused; ablation A2 pins the text difference.
• The read is behind the allow-list in force. It sits under the auth mount, where the ADR-0069 D5 middleware judges every route except /config and /bootstrap-status. A caller whose address is already outside the list in force gets 403 IP_NOT_ALLOWED from the read; no exemption is added to the gate.
• Docs. content/docs/permissions/authentication.mdx › Saving, clearing and lockout recovery does not mention the read yet; it is outside this card's declared file surface. A one-line addition fits there once the ui half shows the address. Carrier: the seat.
• Serial: allowed-ip-ranges.ts's refusal copy (COPY, copyFor) is byte-untouched, for this seat's Allowed IP ranges: the documented env recovery cannot clear the stored list, so removing OS_AUTH_ALLOWED_IP_RANGES locks the admin out again at the next restart #30385.

Human Minimum

• 1. Schemas start as Zod; packages/spec holds no runtime logic (untouched).
• 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: n/a.
• 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 Chinese by the Communication rule).

🤖 Generated with Claude Code

https://claude.ai/code/session_01Utp6CZbTJpa9PNbpp3fdB7

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/plugin-auth, touching 19 documentable anchor(s).

23 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 a1d0b1ee9e428402399f91808923c508c84e0957.

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

What this run could not see

• 4 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 61 of 219 client-bound route-ledger rows — the other 158 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 158: 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; 103 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 — 22 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 a1d0b1ee9e428402399f91808923c508c84e0957 → packageMentionDocs.

Which tree this was computed on

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

node scripts/docs-audit/affected-docs.mjs --json a1d0b1ee9e428402399f91808923c508c84e0957

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

[objectstack-fleet]

domain:server#2 · os-bill · session_01Utp6Cbvcmv8YWFhFJwzjKL

维护者速读

• 改了什么： 新增只读接口 GET /api/v1/auth/admin/client-address，平台管理员保存「允许的 IP 范围」之前，就能看到服务器认定的自己的地址（clientAddress），以及是否信任代理头（trustProxy）。这个地址和保存校验用的是同一个函数算出来的。
• 为什么改： 原来只有被拒存时才知道服务器认的是哪个地址，控制台也没有正确的办法显示它（Allowed IP ranges: no route serves the caller's address as the server resolves it, so the console cannot show an admin which address the lock-out check will judge before they save #30398，Allowed IP ranges console field: show the caller's current address before saving, and show the refusal's address when a save would lock the admin out #30313 第 1 项的 server 半边）。
• 风险与回滚： 只是新增一个接口，平台管理员才能读，no-store，不收查询参数；保存校验的判定和提示文案不变。回滚即撤本 PR。
• 先看： packages/plugins/plugin-auth/src/client-address-read.ts，再看 allowed-ip-ranges.ts 的 judgedClientAddress。
• 两分钟验证： pnpm --filter @objectstack/plugin-auth exec vitest run src/allowed-ip-ranges.pin.test.ts -t 30398。
• 需要您做的： 无，席位经合并队列落地（非受管面，350 行，非 BREAKING）。
• 席位意见： ACCEPT。读数和保存校验共用 judgedClientAddress，显示的地址就是判定的地址；闸门用 /admin/* 惯例 gateAdmin，按出厂权限集与能存设置的人群相同，两个边角只影响能否看到自己的地址。

席位核对 — ACCEPT · domain:server#2 · head 843cf4fecd534b83ea05e6f58e1f96aaa0bd525a

• 形态: draft, author objectstack-fleet[bot] (relay pr_create), no assignee, no review request; 9 files, +339 −11 against merge base f273c9fe; check-governed-merges --pr 30483: NOT governed (0 of 9 paths), 350 lines ≤ 3000. Title has no !.
• Review face: TIER_DEFAULT (declaration face: Clause-②: yes (widening) — a new served route and one server-only ledger row; no packages/spec path, no governed path, no narrowing), written here by the seat.
• Seat read: judgedClientAddress is now the one call both doors make: the save predicate (allowedIpRangesWritePredicate, verdict and COPY / copyFor byte-unchanged) and the new read. It hands resolveClientAddress only FORWARDED_CLIENT_ADDRESS_HEADERS plus the transport peer — the same narrowing the settings service applies before the predicate, so the save's input is unchanged. The route is mounted under the auth base path behind gateAdmin (401 / held 403 / non-admin 403 before any address is read), answers { clientAddress, trustProxy } with Cache-Control: no-store, closed empty query set (400 VALIDATION_ERROR), no body read; the ADR-0069 D5 gate runs ahead of it like every other auth route. WriteTransport → exported RequestTransport is a rename inside the package (not re-exported from index.ts).
• Gate population (dev's open point) — accepted as built. The read uses the /admin/* family's judge (platform admin) instead of re-composing the settings door's manage_platform_settings check inside plugin-auth. With the shipped permission sets the populations are identical; the two edges (a custom set holding manage_platform_settings without admin_full_access loses only the hint, the save still names the address; the legacy role === 'admin' fallback reads only its own connection's address) disclose nothing about anyone else. A second copy of the settings door's resolver would cost more than it protects.
• Deviation accepted: two dogfood /admin/ sweeps (admin-platform-admin-standing, admin-route-nonadmin-refusal) gain a 5-line classification each — they name any new /admin/ route as unclassified by design; red leg recorded before the classification. Outside the ordered list, outside the forbidden set.
• Serial: Allowed IP ranges: the documented env recovery cannot clear the stored list, so removing OS_AUTH_ALLOWED_IP_RANGES locks the admin out again at the next restart #30385 (PR fix(service-settings): a clear goes through an env pin, so the allowed-IP lockout recovery survives removing the variable #30448) owns the refusal copy in allowed-ip-ranges.ts — untouched here; Authentication settings: clearing a key (or resetting the namespace) answers saved, but the running value keeps the last stored one until a restart (lockout threshold, max sessions per user and siblings) #30312 (PR fix(plugin-auth)!: clearing an authentication setting, or resetting the namespace, takes effect at once (#30312) #30447) owns applySettings — untouched here. Organization require MFA: the save refusal is English only, the grace period is unreadable by the console, and the field help does not say two-factor must be on #30411 also edits auth-plugin.ts elsewhere; the later lander merges main.
• Pins: the real AuthPlugin + real SettingsService + real routes; each address case reads then saves from the same connection and asserts the read's clientAddress equals the refusal's constraint.clientAddress (direct, IPv4-mapped, trustProxy leftmost XFF, forged XFF ignored without trustProxy, no peer → null); no-store; four refusals before any address read. Ablations A1–A9 each red as listed, restored.
• Declarations: Clause-②: yes (widening), Metadata-protocol: none, line-initial in PR body and changeset; patch for @objectstack/plugin-auth.
• Dev readings (843cf4fe): plugin-auth 224 files / 3964 passed, typecheck 0, derived gates 68/68 exit 0 (0 NOT-MEASURED), pnpm lint 0, full dogfood under the verify lock 419 files / 3492 passed. os-dev-report 6658914828.
• Follow-up (carrier: seat): content/docs/permissions/authentication.mdx › Saving, clearing and lockout recovery gains a line on this read once the ui half (Allowed IP ranges console field: show the caller's current address before saving, and show the refusal's address when a save would lock the admin out #30313 item 1) shows the address.
• 门禁 check-runs: in progress at ACCEPT; auto-merge waits on the required contexts.
• 落地条款: Fixes Allowed IP ranges: no route serves the caller's address as the server resolves it, so the console cannot show an admin which address the lock-out check will judge before they save #30398. Ordinary queue landing by this seat: pr_ready + automerge_enable on this head.