Commit graph

1 commit

Author SHA1 Message Date
Julian Knutsen
2632d57e09
feat(serve): optional bearer auth and a Host allowlist for bd serve (#5516)
bd serve's help says "No authentication and no TLS", and the first half of that
is what stops it being deployed anywhere but a developer's loopback. Two flags
answer it, and both default to the behavior that exists today: a `bd serve` with
no arguments is byte-for-byte the server it has always been.

AUTHENTICATION

  --auth-token-file names a file of accepted tokens, one per line, all
  accepted. There is deliberately no --auth-token: a credential passed as an
  argument is readable by every local user out of ps.

  The accepted set is NOT a startup snapshot. It is re-read while the server
  runs, gated to at most one stat(2) per second for the whole process, and that
  is what makes rotation hitless — write {new,old}, roll the clients, drop old —
  and what makes a leaked token revocable inside a second without a restart.
  The freshness check runs on the ACCEPTING path too, not only on a mismatch:
  a token the operator just deleted still matches the cached set, so a
  mismatch-triggered reload would give rotation and never give revocation.

  A failed or empty re-read keeps the last-good set and logs the error, so a
  writer that truncates before writing cannot lock every client out; the stat
  cache is left untouched, so the next attempt re-reads and recovers.

  The check sits in route(), on a per-operation authExempt column beside
  bypassSemaphore, and runs BEFORE the semaphore — a refusal costs one SHA-256
  and can never occupy the database slots authenticated clients are waiting for.
  /healthz is the one exemption, because a probe carries no credential;
  /v0/beads/context is not, because it reports the repo root, beads directory
  and database name. Tokens are compared as SHA-256 digests in constant time,
  so the process holds no raw credential and the 401 — fixed detail, via the
  staticDetail map — can never echo the one that was presented.

  The wire says so: a bearerToken securityScheme, a 401 on every guarded
  operation, and a spec-parity test that fails if the route table's exemption
  column and the document's security blocks ever disagree. That test is what
  makes a NEW operation inherit the 401 in the same commit that routes it.

HOST ALLOWLIST

  --allowed-host (repeatable) adds Host values the DNS-rebinding check answers
  to. Matching stays exact; there is no wildcard or suffix syntax. Admitting a
  name the operator enumerated does not weaken the defense: a rebound page
  still cannot make a browser send that Host to 127.0.0.1, and the automation
  clients that do send it are not browsers. Without this, a server reached by
  any name other than a loopback spelling or the bind address 400s on every
  request, which is the first thing a non-loopback deployment trips over.

WHY LOOPBACK BEHAVIOR IS UNCHANGED

  Every new field defaults to the value that reproduces the old code path: no
  Auth, no extra hosts. A zero-valued Config is the previous server, and the
  whole pre-existing test suite proves it — none of those tests passes a token
  or a host, and all of them still pass unmodified.

  The one deliberate behavior change is at the other end: --allow-non-loopback
  now REQUIRES --auth-token-file, escapable only by naming --insecure-no-auth.
  Beyond loopback the old default was that reaching the address granted every
  read and every claim. The three places that advertised "no authentication" —
  the help text, the bind refusal and the flag usage — are reworded, since
  leaving any of them would ship a false security statement.

  Still no TLS, deliberately and unchanged. A non-loopback bind now warns that
  the token and the issue data travel in plaintext and belong inside a trusted
  boundary; supplying confidentiality is the deployment's job.

Agent-Signature: claude-opus-5

Co-authored-by: CI Bot <ci@beads.test>
2026-08-09 18:05:56 -07:00