feat(auth): IP allow-list — network gating on auth routes (ADR-0069 D5, P2)

[os-zhuang]

ADR-0069 P2 / D5 — IP allow-list (network gating).

What

New allowed_ip_ranges auth setting (CIDR ranges or exact IPs, one per line / comma-separated; empty = no restriction). A Hono middleware registered ahead of the better-auth handler in the auth-route registration rejects auth requests from a client IP outside the ranges with 403 IP_NOT_ALLOWED — the exact seam ADR-0069 D5 names.

• Client IP is read trust-proxy-aware: x-forwarded-for (first hop) → cf-connecting-ip → x-real-ip.
• /config + /bootstrap-status are exempt so a blocked client still gets a clean login page + a clear error (rather than a broken page).
• Fails OPEN when the client IP can't be determined (no proxy header) — a misconfigured proxy is a no-op, not a lockout. An admin enabling this must ensure forwarded headers are trusted.
• IPv4 CIDR (a.b.c.d/n) + exact IPv4/IPv6 matching (ipMatchesRange / isClientIpAllowed, unit-tested).

ADR-0049

Default-off / additive (no upgrade behavior change); the setting ships with its enforcement.

Verification

• Unit: plugin-auth 208 + service-settings 129 green; full build incl. strict DTS green. Tests cover CIDR/exact matching, in-range vs out-of-range, no-ranges-allows-all, and fail-open on undetermined IP.
• Live dogfood (allowed_ip_ranges=203.0.113.0/24):
  • sign-in with X-Forwarded-For: 8.8.8.8 → 403 IP_NOT_ALLOWED
  • sign-in with X-Forwarded-For: 203.0.113.50 → 200 + token
  • /config from a disallowed IP → 200 (login still renders)
  • no proxy header → 200 (fail-open; admin not locked out)

Scope / follow-ups (#2375)

This gates the auth routes (sign-in / session), per the ADR's D5 seam. Gating all data requests by IP, per-org sys_organization.allowed_ip_ranges, and the require_ip_match session-pinning toggle are follow-ups. Remaining ADR-0069 work: P3 SAML (needs a @better-auth/sso vs custom plugin decision). (OIDC trust-list UI / D6 verified already shipped via the SSO-provider surface.)

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
spec	Ready	Preview, Comment	Jun 27, 2026 6:21pm

[github-actions]

📓 Docs Drift Check

This PR changes 2 package(s): @objectstack/plugin-auth, packages/services.

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

• content/docs/concepts/implementation-status.mdx(via @objectstack/plugin-auth)
• content/docs/concepts/packages.mdx(via @objectstack/plugin-auth)
• content/docs/getting-started/cli.mdx(via @objectstack/plugin-auth)
• content/docs/guides/auth-sso.mdx(via @objectstack/plugin-auth)
• content/docs/guides/authentication.mdx(via @objectstack/plugin-auth)
• content/docs/guides/kernel-services.mdx(via @objectstack/plugin-auth)
• content/docs/guides/packages.mdx(via @objectstack/plugin-auth, packages/services)
• content/docs/guides/plugins.mdx(via @objectstack/plugin-auth)
• content/docs/guides/production-readiness.mdx(via @objectstack/plugin-auth)
• content/docs/guides/runtime-services/audit-service.mdx(via packages/services)
• content/docs/guides/runtime-services/index.mdx(via packages/services)
• content/docs/guides/runtime-services/settings-service.mdx(via packages/services)
• content/docs/protocol/objectos/i18n-standard.mdx(via packages/services)
• content/docs/releases/v9.mdx(via @objectstack/plugin-auth)

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.