Skip to content

feat(server): opt-in DOCSIQ_SERVER_ALLOW_UNAUTHENTICATED to bind non-loopback without api key#98

Merged
aksOps merged 2 commits intomainfrom
feat/server-allow-unauth-override
May 4, 2026
Merged

feat(server): opt-in DOCSIQ_SERVER_ALLOW_UNAUTHENTICATED to bind non-loopback without api key#98
aksOps merged 2 commits intomainfrom
feat/server-allow-unauth-override

Conversation

@aksOps
Copy link
Copy Markdown
Contributor

@aksOps aksOps commented May 4, 2026

Summary

  • Today docsiq refuses to start when server.api_key is empty and the bind host is anything other than loopback. That's the right safe default for any host that might be on a public network, but it makes every deployment to a trusted private network require an api key purely as a boot-gate ritual.
  • This PR adds server.allow_unauthenticated (env: DOCSIQ_SERVER_ALLOW_UNAUTHENTICATED=true) that downgrades the non-loopback refusal to a loud warning. Default is false — every existing install boots identically.
  • The boot-time error messages now mention the override env var, so anyone hitting the refusal sees both escape hatches (set a key OR set the override) without searching docs.

Why opt-in instead of removing the gate

Just deleting the safety check would mean someone running docsiq serve --host 0.0.0.0 on a vps gets a fully unauthenticated docsiq exposed to the public internet — no warning, no error, full document corpus and LLM proxy reachable. The opt-in keeps that footgun closed for downstream users while letting operators on trusted networks set one env var and move on.

When the override is active the warning explicitly names the exposure and tells operators not to enable it on the public internet:

⚠️ auth disabled and server.allow_unauthenticated=true — anyone reachable on
this network can read all data and use the LLM proxy; do NOT enable on the
public internet  host=0.0.0.0 port=8080

Test plan

  • go vet -tags sqlite_fts5 ./cmd/... ./internal/config/... clean
  • go test -tags sqlite_fts5 ./cmd/... ./internal/config/... 82/82 pass
  • New TestValidateServeSecurity_AllowsNonLoopbackWithOverride — override allows '', 0.0.0.0, 10.0.0.5, 192.168.1.42 to boot
  • New TestValidateServeSecurity_OverrideHintAppearsInErrors — error message mentions DOCSIQ_SERVER_ALLOW_UNAUTHENTICATED
  • New TestLoad_EnvOverridesServerAllowUnauthenticated — env var actually reaches cfg.Server.AllowUnauthenticated
  • Post-merge: smoke test in v0.1.6 by setting the env var and binding a release binary to 0.0.0.0:37793

Compatibility

Drop-in. Default value of the new key is false so behavior is identical for everyone who hasn't explicitly opted in.

🤖 Generated with Claude Code

aksOps added 2 commits May 4, 2026 06:17
…ride

Today docsiq refuses to start when server.api_key is empty and the bind
host is anything other than loopback. That's the right safe default,
but it makes deployments to trusted private networks (homelabs,
air-gapped clusters, single-tenant LANs) require an api key just for
the boot gate, with no real adversary on the network.

Add server.allow_unauthenticated (DOCSIQ_SERVER_ALLOW_UNAUTHENTICATED=true)
that downgrades the non-loopback refusal to a loud warning. Default is
false — every existing install behaves identically. Operators who set
the override get a prominent boot-time warning naming the bound host
and port plus an explicit "do NOT enable on the public internet" line.

The boot-time error messages now mention the override env var so
anyone hitting the refusal sees both escape hatches (set a key OR set
the override) without grepping the docs.

Tests: 2 new cmd-level cases (override allows non-loopback bind across
'', 0.0.0.0, RFC1918 hosts; error messages mention the override env
var) and 1 new config-level case proving DOCSIQ_SERVER_ALLOW_UNAUTHENTICATED
is reachable via env (regression guard for viper #761 if BindEnv loop
ever regresses).
@aksOps aksOps enabled auto-merge (squash) May 4, 2026 06:23
@aksOps aksOps merged commit 213121e into main May 4, 2026
16 of 17 checks passed
@aksOps aksOps deleted the feat/server-allow-unauth-override branch May 4, 2026 06:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant