Skip to content

feat(plugin-auth): a platform admin can read the address the allowed IP ranges save check will judge (#30398) - #30483

Merged
objectstack-fleet[bot] merged 6 commits into
mainfrom
claude/project-thread-i4mjun
Nov 5, 2026
Merged

objectstack-fleet[bot] merged 6 commits into
mainfrom
claude/project-thread-i4mjun

Conversation

@objectstack-fleet

Copy link
Copy Markdown
Contributor

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 github-actions Bot added size/m documentation Improvements or additions to documentation tests tooling Fix lands in tooling, not a product package — enters pm:queue only with Unblocks: or a named surface labels Nov 5, 2026
@github-actions

github-actions Bot commented Nov 5, 2026

Copy link
Copy Markdown
Contributor

📓 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

objectstack-fleet Bot commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor Author

domain:server#2 · os-bill · session_01Utp6Cbvcmv8YWFhFJwzjKL

维护者速读

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation size/m tests tooling Fix lands in tooling, not a product package — enters pm:queue only with Unblocks: or a named surface

Projects

None yet

1 participant