chore: Security hardening (#9719)

* fix(http): close 0.0.0.0/[::] SSRF bypass in /api/cors-proxy

The CORS proxy carried its own private-network blocklist (RFC 1918 + a
handful of IPv6 ranges) instead of using the same classification as
pkg/utils/urlfetch.go. The hand-rolled list missed 0.0.0.0/8 and ::/128,
both of which Linux routes to localhost — so any user with FeatureMCP
(default-on for new users) could reach LocalAI's own listener and any
other service bound to 0.0.0.0:port via:

  GET /api/cors-proxy?url=http://0.0.0.0:8080/...
  GET /api/cors-proxy?url=http://[::]:8080/...

Replace the custom check with utils.IsPublicIP (Go stdlib IsLoopback /
IsLinkLocalUnicast / IsPrivate / IsUnspecified, plus IPv4-mapped IPv6
unmasking) and add an upfront hostname rejection for localhost, *.local,
and the cloud metadata aliases so split-horizon DNS can't paper over the
IP check.

The IP-pinning DialContext is unchanged: the validated IP from the
single resolution is reused for the connection, so DNS rebinding still
cannot swap a public answer for a private one between validate and dial.

Regression tests cover 0.0.0.0, 0.0.0.0:PORT, [::], ::ffff:127.0.0.1,
::ffff:10.0.0.1, file://, gopher://, ftp://, localhost, 127.0.0.1,
10.0.0.1, 169.254.169.254, metadata.google.internal.

Assisted-by: Claude:claude-opus-4-7 [Claude Code]
Signed-off-by: Richard Palethorpe <io@richiejp.com>

* fix(downloader): verify SHA before promoting temp file to final path

DownloadFileWithContext renamed the .partial file to its final name
*before* checking the streamed SHA, so a hash mismatch returned an
error but left the tampered file at filePath. Subsequent code that
operated on filePath (a backend launcher, a YAML loader, a re-download
that finds the file already present and skips) would consume the
attacker-supplied bytes.

Reorder: verify the streamed hash first, remove the .partial on
mismatch, then rename. The streamed hash is computed during io.Copy
so no second read is needed.

While here, raise the empty-SHA case from a Debug log to a Warn so
"this download had no integrity check" is visible at the default log
level. Backend installs currently pass through with no digest; the
warning makes that footprint observable without changing behaviour.

Regression test asserts os.IsNotExist on the destination after a
deliberate SHA mismatch.

Assisted-by: Claude:claude-opus-4-7 [Claude Code]
Signed-off-by: Richard Palethorpe <io@richiejp.com>

* fix(auth): require email_verified for OIDC admin promotion

extractOIDCUserInfo read the ID token's "email" claim but never
inspected "email_verified". With LOCALAI_ADMIN_EMAIL set, an attacker
who could register on the configured OIDC IdP under that email (some
IdPs accept self-supplied unverified emails) inherited admin role:

  - first login:  AssignRole(tx, email, adminEmail) → RoleAdmin
  - re-login:     MaybePromote(db, user, adminEmail) → flip to RoleAdmin

Add EmailVerified to oauthUserInfo, parse email_verified from the OIDC
claims (default false on absence so an IdP that omits the claim cannot
short-circuit the gate), and substitute "" for the role-decision email
when verified=false via emailForRoleDecision. The user record still
stores the unverified email for display.

GitHub's path defaults EmailVerified=true: GitHub only returns a public
profile email after verification, and fetchGitHubPrimaryEmail explicitly
filters to Verified=true.

Regression tests cover both the helper contract and integration with
AssignRole, including the bootstrap "first user" branch that would
otherwise mask the gate.

Assisted-by: Claude:claude-opus-4-7 [Claude Code]
Signed-off-by: Richard Palethorpe <io@richiejp.com>

* feat(cli): refuse public bind when no auth backend is configured

When neither an auth DB nor a static API key is set, the auth
middleware passes every request through. That is fine for a developer
laptop, a home LAN, or a Tailnet — the network itself is the trust
boundary. It is not fine on a public IP, where every model install,
settings change, and admin endpoint becomes reachable from the
internet.

Refuse to start in that exact configuration. Loopback, RFC 1918,
RFC 4193 ULA, link-local, and RFC 6598 CGNAT (Tailscale's default
range) all count as trusted; wildcard binds (`:port`, `0.0.0.0`,
`[::]`) are accepted only when every host interface is in one of those
ranges. Hostnames are resolved and treated as trusted only when every
answer is.

A new --allow-insecure-public-bind / LOCALAI_ALLOW_INSECURE_PUBLIC_BIND
flag opts out for deployments that gate access externally (a reverse
proxy enforcing auth, a mesh ACL, etc.). The error message lists this
plus the three constructive alternatives (bind a private interface,
enable --auth, set --api-keys).

The interface enumeration goes through a package-level interfaceAddrsFn
var so tests can simulate cloud-VM, home-LAN, Tailscale-only, and
enumeration-failure topologies without poking at the real network
stack.

Assisted-by: Claude:claude-opus-4-7 [Claude Code]
Signed-off-by: Richard Palethorpe <io@richiejp.com>

* test(http): regression-test the localai_assistant admin gate

ChatEndpoint already rejects metadata.localai_assistant=true from a
non-admin caller, but the gate was open-coded inline with no direct
test coverage. The chat route is FeatureChat-gated (default-on), and
the assistant's in-process MCP server can install/delete models and
edit configs — the wrong handler change would silently turn the LLM
into a confused deputy.

Extract the gate into requireAssistantAccess(c, authEnabled) and pin
its behaviour: auth disabled is a no-op, unauthenticated is 403,
RoleUser is 403, RoleAdmin and the synthetic legacy-key admin are
admitted.

No behaviour change in the production path.

Assisted-by: Claude:claude-opus-4-7 [Claude Code]
Signed-off-by: Richard Palethorpe <io@richiejp.com>

* test(http): assert every API route is auth-classified

The auth middleware classifies path prefixes (/api/, /v1/, /models/,
etc.) as protected and treats anything else as a static-asset
passthrough. A new endpoint shipped under a brand-new prefix — or a
new path that simply isn't on the prefix allowlist — would be
reachable anonymously.

Walk every route registered by API() with auth enabled and a fresh
in-memory database (no users, no keys), and assert each API-prefixed
route returns 401 / 404 / 405 to an anonymous request. Public surfaces
(/api/auth/*, /api/branding, /api/node/* token-authenticated routes,
/healthz, branding asset server, generated-content server, static
assets) are explicit allowlist entries with comments justifying them.

Build-tagged 'auth' so it runs against the SQLite-backed auth DB
(matches the existing auth suite).

Assisted-by: Claude:claude-opus-4-7 [Claude Code]
Signed-off-by: Richard Palethorpe <io@richiejp.com>

* test(http): pin agent endpoint per-user isolation contract

agents.go's getUserID / effectiveUserID / canImpersonateUser /
wantsAllUsers helpers are the single trust boundary for cross-user
access on agent, agent-jobs, collections, and skills routes. A
regression there is the difference between "regular user reads their
own data" and "regular user reads anyone's data via ?user_id=victim".

Lock in the contract:
  - effectiveUserID ignores ?user_id= for unauthenticated and RoleUser
  - effectiveUserID honours it for RoleAdmin and ProviderAgentWorker
  - wantsAllUsers requires admin AND the literal "true" string
  - canImpersonateUser is admin OR agent-worker, never plain RoleUser

No production change — this commit only adds tests.

Assisted-by: Claude:claude-opus-4-7 [Claude Code]
Signed-off-by: Richard Palethorpe <io@richiejp.com>

* fix(downloader): drop redundant stat in removePartialFile

The stat-then-remove pattern is a TOCTOU window and a wasted syscall —
os.Remove already returns ErrNotExist for the missing-file case, so trust
that and treat it as a no-op.

Assisted-by: Claude:claude-opus-4-7 [Claude Code]
Signed-off-by: Richard Palethorpe <io@richiejp.com>

* fix(http): redact secrets from trace buffer and distribution-token logs

The /api/traces buffer captured Authorization, Cookie, Set-Cookie, and
API-key headers verbatim from every request when tracing was enabled. The
endpoint is admin-only but the buffer is reachable via any heap-style
introspection and the captured tokens otherwise outlive the request.
Strip those header values at capture time. Body redaction is left to a
follow-up — the prompts are usually the operator's own and JSON-walking
is invasive.

Distribution tokens were also logged in plaintext from
core/explorer/discovery.go; logs forward to syslog/journald and outlive
the token. Redact those to a short prefix/suffix instead.

Assisted-by: Claude:claude-opus-4-7 [Claude Code]
Signed-off-by: Richard Palethorpe <io@richiejp.com>

* feat(auth): rate-limit OAuth callbacks separately from password endpoints

The shared 5/min/IP limit on auth endpoints is right for password-style
flows but too tight for OAuth callbacks: corporate SSO funnels many real
users through one outbound IP and would trip the limit. Add a separate
60/min/IP limiter for /api/auth/{github,oidc}/callback so callbacks are
bounded against floods without breaking shared-IP deployments.

Assisted-by: Claude:claude-opus-4-7 [Claude Code]
Signed-off-by: Richard Palethorpe <io@richiejp.com>

* feat(gallery): verify backend tarball sha256 when set in gallery entry

GalleryBackend gained an optional sha256 field; the install path now
threads it through to the existing downloader hash-verify (which already
streams, verifies, and rolls back on mismatch). Galleries without sha256
keep working; the empty-SHA path still emits the existing
"downloading without integrity check" warning.

Assisted-by: Claude:claude-opus-4-7 [Claude Code]
Signed-off-by: Richard Palethorpe <io@richiejp.com>

* test(http): pin CSRF coverage on multipart endpoints

The CSRF middleware in app.go is global (e.Use) so it covers every
multipart upload route — branding assets, fine-tune datasets, audio
transforms, agent collections. Pin that contract: cross-site multipart
POSTs are rejected; same-origin / same-site / API-key clients are not.
Also pins the SameSite=Lax fallback path the skipper relies on when
Sec-Fetch-Site is absent.

Assisted-by: Claude:claude-opus-4-7 [Claude Code]
Signed-off-by: Richard Palethorpe <io@richiejp.com>

* feat(http): XSS hardening — CSP headers, safe href, base-href escape, SVG sandbox

Several closely related XSS-prevention changes spanning the SPA shell, the
React UI, and the branding asset server:

- New SecurityHeaders middleware sets CSP, X-Content-Type-Options,
  X-Frame-Options, and Referrer-Policy on every response. The CSP keeps
  script-src permissive because the Vite bundle relies on inline + eval'd
  scripts; tightening that requires moving to a nonce-based policy.

- The <base href> injection in the SPA shell escaped attacker-controllable
  Host / X-Forwarded-Host headers — a single quote in the host header
  broke out of the attribute. Pass through SecureBaseHref (html.EscapeString).

- Three React sinks rendering untrusted content via dangerouslySetInnerHTML
  switch to text-node rendering with whiteSpace: pre-wrap: user message
  bodies in Chat.jsx and AgentChat.jsx, and the agent activity log in
  AgentChat.jsx. The hand-rolled escape on the agent user-message variant
  is replaced by the same plain-text path.

- New safeHref util collapses non-allowlisted URI schemes (most
  importantly javascript:) to '#'. Applied to gallery `<a href={url}>`
  links in Models / Backends / Manage and to canvas artifact links —
  these come from gallery JSON or assistant tool calls and must be treated
  as untrusted.

- The branding asset server attaches a sandbox CSP plus same-origin CORP
  to .svg responses. The React UI loads logos via <img>, but the same URL
  is also reachable via direct navigation; this prevents script
  execution if a hostile SVG slipped past upload validation.

Assisted-by: Claude:claude-opus-4-7 [Claude Code]
Signed-off-by: Richard Palethorpe <io@richiejp.com>

* feat(http): bound HTTP server with read-header and idle timeouts

A net/http server with no timeouts is trivially Slowloris-able and leaks
idle keep-alive connections. Set ReadHeaderTimeout (30s) to plug the
slow-headers attack and IdleTimeout (120s) to cap keep-alive sockets.

ReadTimeout and WriteTimeout stay at 0 because request bodies can be
multi-GB model uploads and SSE / chat completions stream for many
minutes; operators who need tighter per-request bounds should terminate
slow clients at a reverse proxy.

Assisted-by: Claude:claude-opus-4-7 [Claude Code]
Signed-off-by: Richard Palethorpe <io@richiejp.com>

* test(auth): pin PUT /api/auth/profile field-tampering contract

The handler uses an explicit local body struct (only name and avatar_url)
plus a gorm Updates(map) with a column allowlist, so an attacker posting
{"role":"admin","email":"...","password_hash":"..."} can't mass-assign
those fields. Lock that down with a regression test so a future
"let's just c.Bind(&user)" refactor breaks loudly.

Assisted-by: Claude:claude-opus-4-7 [Claude Code]
Signed-off-by: Richard Palethorpe <io@richiejp.com>

* fix(services): strip directory components from multipart upload filenames

UploadDataset and UploadToCollectionForUser took the raw multipart
file.Filename and joined it into a destination path. The fine-tune
upload was incidentally safe because of a UUID prefix that fused any
leading '..' to a literal segment, but the protection is fragile.
UploadToCollectionForUser handed the filename to a vendored backend
without sanitising at all.

Strip to filepath.Base at both boundaries and reject the trivial
unsafe values ("", ".", "..", "/").

Assisted-by: Claude:claude-opus-4-7 [Claude Code]
Signed-off-by: Richard Palethorpe <io@richiejp.com>

* fix(react-ui): validate persisted MCP server entries on load

localStorage is shared across same-origin pages; an XSS that lands once
can poison persisted MCP server config to attempt header injection or
to feed a non-http URL into the fetch path on subsequent loads.
Validate every entry: types must match, URL must parse with http(s)
scheme, header keys/values must be control-char-free. Drop anything
that doesn't fit.

Assisted-by: Claude:claude-opus-4-7 [Claude Code]
Signed-off-by: Richard Palethorpe <io@richiejp.com>

* fix(http): close X-Forwarded-Prefix open redirect

The reverse-proxy support concatenated X-Forwarded-Prefix into the
redirect target without validation, so a forged header value of
"//evil.com" turned the SPA-shell redirect helper at /, /browse, and
/browse/* into a 301 to //evil.com/app. The path-strip middleware had
the same shape on its prefix-trailing-slash redirect.

Add SafeForwardedPrefix at the middleware boundary: must start with
a single '/', no protocol-relative '//' opener, no scheme, no
backslash, no control characters. Apply at both consumers; misconfig
trips the validator and the header is dropped.

Assisted-by: Claude:claude-opus-4-7 [Claude Code]
Signed-off-by: Richard Palethorpe <io@richiejp.com>

* fix(http): refuse wildcard CORS when LOCALAI_CORS=true with empty allowlist

When LOCALAI_CORS=true but LOCALAI_CORS_ALLOW_ORIGINS was empty, Echo's
CORSWithConfig saw an empty allow-list and fell back to its default
AllowOrigins=["*"]. An operator who flipped the strict-CORS feature
flag without populating the list got the opposite of what they asked
for. Echo never sets Allow-Credentials: true so this isn't directly
exploitable (cookies aren't sent under wildcard CORS), but the
misconfiguration trap is worth closing. Skip the registration and warn.

Assisted-by: Claude:claude-opus-4-7 [Claude Code]
Signed-off-by: Richard Palethorpe <io@richiejp.com>

* feat(auth): zxcvbn password strength check with user-acknowledged override

The previous policy was len < 8, which let through "Password1" and the
rest of the credential-stuffing corpus. LocalAI has no second factor
yet, so the bar needs to sit higher.

Add ValidatePasswordStrength using github.com/timbutler/zxcvbn (an
actively-maintained fork of the trustelem port; v1.0.4, April 2024):
- min 12 chars, max 72 (bcrypt's truncation point)
- reject NUL bytes (some bcrypt callers truncate at the first NUL)
- require zxcvbn score >= 3 ("safely unguessable, ~10^8 guesses to
  break"); the hint list ["localai", "local-ai", "admin"] penalises
  passwords built from the app's own branding

zxcvbn produces false positives sometimes (a strong-looking password
that happens to match a dictionary word) and operators occasionally
need to set a known-weak password (kiosk demos, CI rigs). Add an
acknowledgement path: PasswordPolicy{AllowWeak: true} skips the
entropy check while still enforcing the hard rules. The structured
PasswordErrorResponse marks weak-password rejections as Overridable
so the UI can surface a "use this anyway" checkbox.

Wired through register, self-service password change, and admin
password reset on both the server and the React UI.

Assisted-by: Claude:claude-opus-4-7 [Claude Code]
Signed-off-by: Richard Palethorpe <io@richiejp.com>

* fix(react-ui): drop HTML5 minLength on new-password inputs

minLength={12} on the new-password input let the browser block the
form submit silently before any JS or network call ran. The browser
focused the field, showed a brief native tooltip, and that was that —
no toast, no fetch, no clue. Reproducible by typing fewer than 12
chars on the second password change of a session.

The JS-level length check in handleSubmit already shows a toast and
the server rejects with a structured error, so the HTML5 attribute
was redundant defence anyway. Drop it.

Assisted-by: Claude:claude-opus-4-7 [Claude Code]
Signed-off-by: Richard Palethorpe <io@richiejp.com>

* fix(react-ui): bundle Geist fonts locally instead of fetching from Google

The new CSP correctly refused to apply styles from
fonts.googleapis.com because style-src is locked to 'self' and
'unsafe-inline'. Loosening the CSP would defeat its purpose; the
right fix is to stop reaching out to a third-party CDN for fonts on
every page load.

Add @fontsource-variable/geist and @fontsource-variable/geist-mono as
npm deps and import them once at boot. Drop the <link rel="preconnect">
and external stylesheet from index.html.

Side benefit: no third-party tracking via Referer / IP on every UI
load, no failure mode when offline / behind a captive portal.

Assisted-by: Claude:claude-opus-4-7 [Claude Code]
Signed-off-by: Richard Palethorpe <io@richiejp.com>

* fix(react-ui): refresh i18n strings to reflect 12-char password minimum

The translations still said "at least 8 characters" everywhere — the
client-side toast on a too-short password change told the user the
wrong floor. Update tooShort and newPasswordPlaceholder /
newPasswordDescription across all five locales (en, es, it, de,
zh-CN) to match the real ValidatePasswordStrength rule.

Assisted-by: Claude:claude-opus-4-7 [Claude Code]
Signed-off-by: Richard Palethorpe <io@richiejp.com>

* feat(auth): make password length-floor overridable like the entropy check

The 12-char minimum was a policy choice, not a technical invariant —
only "non-empty", "<= 72 bytes", and "no NUL bytes" are real bcrypt
constraints. Treating length-12 as a hard rule was inconsistent with
the entropy check (already overridable) and friction for use cases
where the account is just a name on a session, not a security
boundary (single-user kiosk, CI rig, lab demo).

Restructure ValidatePasswordStrength:
- Hard rules (always enforced): non-empty, <= MaxPasswordLength, no NUL byte
- Policy rules (skipped when AllowWeak=true): length >= 12, zxcvbn score >= 3

PasswordError now marks password_too_short as Overridable too. The
React forms generalised from `error_code === 'password_too_weak'` to
`overridable === true`, and the JS-side preflight length checks were
removed (server is source of truth, returns the same checkbox flow).

Assisted-by: Claude:claude-opus-4-7 [Claude Code]
Signed-off-by: Richard Palethorpe <io@richiejp.com>

---------

Signed-off-by: Richard Palethorpe <io@richiejp.com>

core/cli/run.go

@@ -70,6 +70,7 @@ type RunCMD struct {
 	OpaqueErrors                       bool     `env:"LOCALAI_OPAQUE_ERRORS" default:"false" help:"If true, all error responses are replaced with blank 500 errors. This is intended only for hardening against information leaks and is normally not recommended." group:"hardening"`
 	UseSubtleKeyComparison             bool     `env:"LOCALAI_SUBTLE_KEY_COMPARISON" default:"false" help:"If true, API Key validation comparisons will be performed using constant-time comparisons rather than simple equality. This trades off performance on each request for resiliancy against timing attacks." group:"hardening"`
 	DisableApiKeyRequirementForHttpGet bool     `env:"LOCALAI_DISABLE_API_KEY_REQUIREMENT_FOR_HTTP_GET" default:"false" help:"If true, a valid API key is not required to issue GET requests to portions of the web ui. This should only be enabled in secure testing environments" group:"hardening"`
+	AllowInsecurePublicBind            bool     `env:"LOCALAI_ALLOW_INSECURE_PUBLIC_BIND" default:"false" help:"Allow binding the API to a public-internet address without any authentication configured. Without this flag the server refuses to start when the bind address is public (or a wildcard on a host with a public interface) and no auth backend or static API key is set. Loopback, RFC 1918 LAN, ULA, link-local, and CGNAT (Tailscale) ranges are accepted regardless." group:"hardening"`
 	DisableMetricsEndpoint             bool     `env:"LOCALAI_DISABLE_METRICS_ENDPOINT,DISABLE_METRICS_ENDPOINT" default:"false" help:"Disable the /metrics endpoint" group:"api"`
 	HttpGetExemptedEndpoints           []string `env:"LOCALAI_HTTP_GET_EXEMPTED_ENDPOINTS" default:"^/$,^/app(/.*)?$,^/browse(/.*)?$,^/login/?$,^/explorer/?$,^/assets/.*$,^/static/.*$,^/swagger.*$" help:"If LOCALAI_DISABLE_API_KEY_REQUIREMENT_FOR_HTTP_GET is overriden to true, this is the list of endpoints to exempt. Only adjust this in case of a security incident or as a result of a personal security posture review" group:"hardening"`
 	Peer2Peer                          bool     `env:"LOCALAI_P2P,P2P" name:"p2p" default:"false" help:"Enable P2P mode" group:"p2p"`
@@ -516,6 +517,17 @@ func (r *RunCMD) Run(ctx *cliContext.Context) error {
 		return fmt.Errorf("LocalAI failed to start: %w.\nTroubleshooting steps:\n  1. Check that your models directory exists and is accessible: %s\n  2. Verify model config files are valid YAML: 'local-ai util usecase-heuristic <config>'\n  3. Check available disk space and file permissions\n  4. Run with --log-level=debug for more details\nSee https://localai.io/basics/troubleshooting/ for more help", err, r.ModelsPath)
 	}
 
+	// Refuse to bind a public-internet address without authentication unless
+	// the operator has explicitly opted in. The auth middleware degrades to
+	// pass-through when there is no auth DB and no legacy keys; on a loopback,
+	// LAN, or VPN that's the historical "trusted network" deployment, but on
+	// a public IP it makes every model, gallery install, settings change, and
+	// admin endpoint reachable by anyone who can connect to the port.
+	authConfigured := app.AuthDB() != nil || len(r.APIKeys) > 0
+	if err := requireAuthOrTrustedBind(r.Address, authConfigured, r.AllowInsecurePublicBind); err != nil {
+		return err
+	}
+
 	appHTTP, err := http.API(app)
 	if err != nil {
 		xlog.Error("error during HTTP App construction", "error", err)

core/cli/run_safety.go

@@ -0,0 +1,126 @@
+package cli
+
+import (
+	"fmt"
+	"net"
+	"strings"
+
+	"github.com/mudler/LocalAI/pkg/utils"
+)
+
+// interfaceAddrsFn is the host-interface enumeration call. Tests swap it to
+// simulate cloud-VM, home-LAN, and Tailscale-only topologies without poking
+// the real network stack.
+var interfaceAddrsFn = net.InterfaceAddrs
+
+// requireAuthOrTrustedBind fails closed when the server would otherwise bind a
+// public-internet-reachable address with no authentication configured. Loopback,
+// RFC 1918, ULA, link-local, and CGNAT (Tailscale's default range) are all
+// trusted. Wildcard binds are trusted only when every host interface is.
+//
+// Operators with an external gating layer (e.g. a reverse proxy that enforces
+// auth) can opt out via --allow-insecure-public-bind.
+func requireAuthOrTrustedBind(address string, authConfigured, allowInsecurePublicBind bool) error {
+	if authConfigured || allowInsecurePublicBind {
+		return nil
+	}
+	if isTrustedBind(address) {
+		return nil
+	}
+	return fmt.Errorf(`refusing to start: API bound to public address %q with no authentication configured.
+
+When auth is disabled, the server has no idea who is calling it — every model,
+gallery install, settings change, and admin endpoint is reachable by anyone
+who can connect to the port. That is acceptable on a loopback, LAN, or VPN
+address but not on a public IP.
+
+Pick one:
+  1. Bind to a private/LAN/VPN interface only (e.g. --address 10.0.0.5:8080)
+  2. Enable user authentication:   --auth (or LOCALAI_AUTH=true), then sign in
+  3. Set a static API key:         --api-keys <key> (LOCALAI_API_KEY=<key>)
+  4. Allow the public bind anyway: --allow-insecure-public-bind (only when an
+                                   external system is gating access to this
+                                   listener)`, address)
+}
+
+// isTrustedBind reports whether `address` binds only to addresses that are
+// local, on a private LAN, or on a VPN. Hostnames it can't classify cleanly
+// are rejected.
+func isTrustedBind(address string) bool {
+	if address == "" {
+		return false
+	}
+	host, _, err := net.SplitHostPort(address)
+	if err != nil {
+		return false
+	}
+	host = strings.TrimSpace(host)
+	if host == "" {
+		return allInterfacesTrusted()
+	}
+	if ip := net.ParseIP(host); ip != nil {
+		if ip.IsUnspecified() {
+			return allInterfacesTrusted()
+		}
+		return isPrivateOrLocalIP(ip)
+	}
+	// Hostname — every resolved address must be trusted. A name resolving to
+	// a mix of public and private addresses fails closed.
+	addrs, err := net.LookupHost(host)
+	if err != nil || len(addrs) == 0 {
+		return false
+	}
+	for _, a := range addrs {
+		ip := net.ParseIP(a)
+		if ip == nil || !isPrivateOrLocalIP(ip) {
+			return false
+		}
+	}
+	return true
+}
+
+// isPrivateOrLocalIP returns true for loopback, RFC 1918 / RFC 4193 private,
+// link-local, and RFC 6598 CGNAT addresses. CGNAT (100.64/10) gets the
+// special case because the Go stdlib doesn't classify it as private but
+// Tailscale and similar overlay VPNs hand them out.
+func isPrivateOrLocalIP(ip net.IP) bool {
+	if ip.IsUnspecified() {
+		return false
+	}
+	if !utils.IsPublicIP(ip) {
+		return true
+	}
+	ip4 := ip.To4()
+	return ip4 != nil && ip4[0] == 100 && (ip4[1]&0xc0) == 64
+}
+
+// allInterfacesTrusted reports whether every IP assigned to a local interface
+// is private/local. A wildcard bind on a host with even one public interface
+// is genuinely exposing that public interface.
+//
+// Returns false on enumeration failure or when the host has no addresses
+// at all — we can't prove the bind is safe.
+func allInterfacesTrusted() bool {
+	addrs, err := interfaceAddrsFn()
+	if err != nil {
+		return false
+	}
+	sawAny := false
+	for _, a := range addrs {
+		var ip net.IP
+		switch v := a.(type) {
+		case *net.IPNet:
+			ip = v.IP
+		case *net.IPAddr:
+			ip = v.IP
+		}
+		if ip == nil || ip.IsUnspecified() {
+			continue
+		}
+		sawAny = true
+		if !isPrivateOrLocalIP(ip) {
+			return false
+		}
+	}
+	return sawAny
+}

core/cli/run_safety_test.go

@@ -0,0 +1,154 @@
+package cli
+
+import (
+	"errors"
+	"net"
+
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+// withInterfaceAddrs swaps interfaceAddrsFn for the duration of one spec.
+// Ginkgo's DeferCleanup restores the original after the spec finishes, so
+// concurrent specs can each pretend to be running on a different host.
+func withInterfaceAddrs(cidrs ...string) {
+	original := interfaceAddrsFn
+	interfaceAddrsFn = func() ([]net.Addr, error) {
+		out := make([]net.Addr, 0, len(cidrs))
+		for _, c := range cidrs {
+			ip, ipnet, err := net.ParseCIDR(c)
+			Expect(err).ToNot(HaveOccurred())
+			out = append(out, &net.IPNet{IP: ip, Mask: ipnet.Mask})
+		}
+		return out, nil
+	}
+	DeferCleanup(func() { interfaceAddrsFn = original })
+}
+
+func withInterfaceAddrsErr(err error) {
+	original := interfaceAddrsFn
+	interfaceAddrsFn = func() ([]net.Addr, error) { return nil, err }
+	DeferCleanup(func() { interfaceAddrsFn = original })
+}
+
+var _ = Describe("requireAuthOrTrustedBind", func() {
+	BeforeEach(func() {
+		// Default to "host has only loopback" — the literal-IP cases below
+		// don't touch interfaceAddrsFn but the wildcard cases do, and a
+		// loopback-only host is the safest default for those.
+		withInterfaceAddrs("127.0.0.1/8", "::1/128")
+	})
+
+	It("permits any bind when auth is configured", func() {
+		Expect(requireAuthOrTrustedBind("0.0.0.0:8080", true, false)).To(Succeed())
+		Expect(requireAuthOrTrustedBind("203.0.113.5:8080", true, false)).To(Succeed())
+	})
+
+	It("permits any bind when --allow-insecure-public-bind is set", func() {
+		Expect(requireAuthOrTrustedBind("0.0.0.0:8080", false, true)).To(Succeed())
+		Expect(requireAuthOrTrustedBind("203.0.113.5:8080", false, true)).To(Succeed())
+	})
+
+	Context("literal IP binds", func() {
+		It("permits loopback", func() {
+			Expect(requireAuthOrTrustedBind("127.0.0.1:8080", false, false)).To(Succeed())
+			Expect(requireAuthOrTrustedBind("[::1]:8080", false, false)).To(Succeed())
+			Expect(requireAuthOrTrustedBind("127.5.4.3:8080", false, false)).To(Succeed())
+		})
+
+		DescribeTable("permits private LAN ranges",
+			func(addr string) {
+				Expect(requireAuthOrTrustedBind(addr, false, false)).To(Succeed())
+			},
+			Entry("RFC 1918 — 10/8", "10.0.0.5:8080"),
+			Entry("RFC 1918 — 172.16/12", "172.16.5.5:8080"),
+			Entry("RFC 1918 — 192.168/16", "192.168.1.5:8080"),
+			Entry("IPv6 ULA — fc00::/7", "[fc00::1]:8080"),
+			Entry("IPv6 ULA — fd00::/8", "[fd12:3456:789a::1]:8080"),
+		)
+
+		It("permits link-local addresses", func() {
+			Expect(requireAuthOrTrustedBind("169.254.10.10:8080", false, false)).To(Succeed())
+			Expect(requireAuthOrTrustedBind("[fe80::1]:8080", false, false)).To(Succeed())
+		})
+
+		It("permits CGNAT (Tailscale default)", func() {
+			Expect(requireAuthOrTrustedBind("100.64.0.5:8080", false, false)).To(Succeed())
+			Expect(requireAuthOrTrustedBind("100.127.255.1:8080", false, false)).To(Succeed())
+		})
+
+		It("rejects boundary addresses just outside CGNAT", func() {
+			Expect(requireAuthOrTrustedBind("100.63.255.255:8080", false, false)).To(HaveOccurred())
+			Expect(requireAuthOrTrustedBind("100.128.0.0:8080", false, false)).To(HaveOccurred())
+		})
+
+		It("rejects public IPv4", func() {
+			Expect(requireAuthOrTrustedBind("8.8.8.8:8080", false, false)).To(HaveOccurred())
+			Expect(requireAuthOrTrustedBind("203.0.113.5:8080", false, false)).To(HaveOccurred())
+		})
+
+		It("rejects public IPv6", func() {
+			Expect(requireAuthOrTrustedBind("[2001:db8::1]:8080", false, false)).To(HaveOccurred())
+		})
+	})
+
+	Context("wildcard bind (`:port`, 0.0.0.0, ::)", func() {
+		It("permits when every interface is private/loopback", func() {
+			withInterfaceAddrs("127.0.0.1/8", "::1/128", "10.0.0.5/24", "fc00::1/64")
+			Expect(requireAuthOrTrustedBind(":8080", false, false)).To(Succeed())
+			Expect(requireAuthOrTrustedBind("0.0.0.0:8080", false, false)).To(Succeed())
+			Expect(requireAuthOrTrustedBind("[::]:8080", false, false)).To(Succeed())
+		})
+
+		It("permits when interfaces are loopback + Tailscale CGNAT", func() {
+			withInterfaceAddrs("127.0.0.1/8", "::1/128", "100.65.10.20/32")
+			Expect(requireAuthOrTrustedBind("0.0.0.0:8080", false, false)).To(Succeed())
+		})
+
+		It("rejects when ANY interface has a public IP", func() {
+			withInterfaceAddrs("127.0.0.1/8", "::1/128", "10.0.0.5/24", "203.0.113.42/24")
+			Expect(requireAuthOrTrustedBind(":8080", false, false)).To(HaveOccurred())
+			Expect(requireAuthOrTrustedBind("0.0.0.0:8080", false, false)).To(HaveOccurred())
+			Expect(requireAuthOrTrustedBind("[::]:8080", false, false)).To(HaveOccurred())
+		})
+
+		It("fails closed when interface enumeration errors", func() {
+			withInterfaceAddrsErr(errors.New("enumeration disabled"))
+			Expect(requireAuthOrTrustedBind("0.0.0.0:8080", false, false)).To(HaveOccurred())
+		})
+
+		It("fails closed when the host has no addresses at all", func() {
+			withInterfaceAddrs()
+			Expect(requireAuthOrTrustedBind("0.0.0.0:8080", false, false)).To(HaveOccurred())
+		})
+	})
+
+	Context("hostname binds", func() {
+		It("permits 'localhost' (resolves to loopback)", func() {
+			Expect(requireAuthOrTrustedBind("localhost:8080", false, false)).To(Succeed())
+		})
+	})
+
+	Context("malformed input", func() {
+		It("rejects an address with no port", func() {
+			Expect(requireAuthOrTrustedBind("8080", false, false)).To(HaveOccurred())
+		})
+
+		It("rejects an empty address", func() {
+			Expect(requireAuthOrTrustedBind("", false, false)).To(HaveOccurred())
+		})
+	})
+
+	Context("error message", func() {
+		It("guides the operator with all four escape hatches", func() {
+			err := requireAuthOrTrustedBind("203.0.113.5:8080", false, false)
+			Expect(err).To(HaveOccurred())
+			msg := err.Error()
+			Expect(msg).To(ContainSubstring("--auth"))
+			Expect(msg).To(ContainSubstring("--api-keys"))
+			Expect(msg).To(ContainSubstring("--allow-insecure-public-bind"))
+			Expect(msg).To(ContainSubstring("LAN"))
+			Expect(msg).To(ContainSubstring("VPN"))
+		})
+	})
+})