beads/internal/httpapi/auth.go
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

262 lines
10 KiB
Go

package httpapi
import (
"crypto/sha256"
"crypto/subtle"
"errors"
"fmt"
"io"
"os"
"strings"
"sync"
"sync/atomic"
"time"
)
// Bearer authentication over a file of accepted tokens.
//
// The whole design is one rule: every non-empty line of the file is an accepted
// token, and the file is re-read while the server runs. That single rule is
// what makes rotation hitless and revocation possible without a restart —
// write {new,old}, roll the clients, drop old — and it is why there is no
// second mechanism here. A startup snapshot would instead make rotation a
// process restart and leave a leaked token live for as long as the process is.
//
// There is no token MINTING here and no identity: a token is a shared secret
// that grants the whole surface. Per-client identity, scopes and TLS are
// separate concerns that this file deliberately does not pretend to have.
const (
// authReloadInterval is the floor between two reload ATTEMPTS, and so both
// the cost bound and the staleness bound: one stat(2) per interval for the
// whole server whatever the request rate, and a token added to or removed
// from the file taking effect within one interval of the next request.
authReloadInterval = time.Second
// maxTokenFileBytes refuses to slurp a mis-pointed path. A token file is a
// handful of lines; anything at this size is a wrong argument, and reading
// it into memory on every reload would be the actual damage.
maxTokenFileBytes = 1 << 20
)
// TokenFileAuth verifies presented bearer tokens against a file of accepted
// tokens, one per line, all accepted.
//
// The accepted set is held as SHA-256 digests, never as the tokens themselves,
// so a heap profile or core dump of a running server discloses no credential.
// Verification hashes the presented token and compares digests in constant
// time; hashing both sides also makes the compared lengths uniform, which is
// what subtle.ConstantTimeCompare requires to be constant-time at all.
//
// The zero value is not usable — build one with NewTokenFileAuth.
type TokenFileAuth struct {
path string
// reloadGate and now are the two test seams: they let the reload behavior
// be exercised in milliseconds of fake time instead of real seconds. Both
// fall back to the constants above when unset.
reloadGate time.Duration
now func() time.Time
// digests is the last-good accepted set, swapped as a whole. Readers take
// it with a single atomic load, so the hot path takes no lock and a reload
// never makes the server briefly accept nothing.
digests atomic.Pointer[[][sha256.Size]byte]
// lastAttempt is the unix-nanos of the last reload ATTEMPT — attempt, not
// success, because the point is to bound the rate at which a storm of
// unknown tokens can touch the filesystem.
lastAttempt atomic.Int64
// mu serializes stat + read + swap. modTime and size are the stat cache
// that lets an unchanged file cost a stat and no read.
mu sync.Mutex
modTime time.Time
size int64
}
// NewTokenFileAuth reads path and returns the verifier for it.
//
// It is deliberately eager and strict: an unreadable, oversized or
// token-less file is an error here rather than a server that starts anyway.
// Both silent alternatives are worse than not starting — failing open serves
// the whole surface with no credential, and failing closed answers 401 to
// every client with nothing on stderr that says why.
func NewTokenFileAuth(path string) (*TokenFileAuth, error) {
if strings.TrimSpace(path) == "" {
return nil, errors.New("no token file path given")
}
a := &TokenFileAuth{path: path}
digests, modTime, size, err := readTokenFile(path)
if err != nil {
return nil, err
}
a.digests.Store(&digests)
a.modTime, a.size = modTime, size
return a, nil
}
// Verify reports whether token is currently accepted, and returns any error
// from a reload it triggered so the caller can log it. A reload error is not a
// verification result: the last-good set stays in force, and ok is simply the
// answer that set gives.
//
// Freshness is checked BEFORE the comparison and on every call, not only on a
// mismatch, because those two are not the same property. A mismatch-triggered
// reload gives rotation — a client that rolled to a new token 401s once and
// succeeds on the retry — but it cannot give REVOCATION: a token the operator
// has just deleted from the file still matches the cached set, so it triggers
// nothing and stays accepted until some unrelated unknown token happens to
// arrive. Since revocation without a restart is the point, the check runs on
// the accepting path too.
//
// The cost of that is bounded by the same gate, so it is one stat(2) per
// interval for the whole server whatever the request rate — and an unchanged
// file stops at the stat, so the steady state reads nothing. There is no
// background goroutine and no work at all while the server is idle: the check
// rides the requests that care about it.
func (a *TokenFileAuth) Verify(token string) (ok bool, reloadErr error) {
if token == "" {
return false, nil
}
// A caller that loses the gate to a concurrent reload compares against the
// set that reload is about to replace, rather than blocking on it. That is
// a bounded staleness of one gate interval, which is the window this whole
// mechanism is specified in; blocking every request behind one stat is not
// a trade worth making.
if a.claimReloadSlot() {
reloadErr = a.reload()
}
return a.accepts(sha256.Sum256([]byte(token))), reloadErr
}
// accepts compares want against every cached digest with no early exit, so the
// time taken says nothing about WHICH token was closest.
func (a *TokenFileAuth) accepts(want [sha256.Size]byte) bool {
match := 0
for _, d := range *a.digests.Load() {
match |= subtle.ConstantTimeCompare(d[:], want[:])
}
return match == 1
}
// claimReloadSlot admits at most one reload attempt per gate interval across
// all goroutines. It records the ATTEMPT, not the success, because what needs
// bounding is how often the filesystem is touched. The compare-and-swap is
// what makes a loser return immediately instead of queueing behind the
// winner's stat.
func (a *TokenFileAuth) claimReloadSlot() bool {
gate := a.reloadGate
if gate <= 0 {
gate = authReloadInterval
}
clock := a.now
if clock == nil {
clock = time.Now
}
now := clock().UnixNano()
last := a.lastAttempt.Load()
if now-last < int64(gate) {
return false
}
return a.lastAttempt.CompareAndSwap(last, now)
}
// reload re-reads the token file if it has changed, and swaps the accepted set.
//
// A failed read or a file that parses to zero tokens KEEPS the last-good set
// and reports the error. A writer that truncates before writing must not lock
// every client out of the server for the duration of its write — and because
// the stat cache is only updated on success, the next attempt past the gate
// re-reads and recovers by itself. (Operators should still write the file
// atomically, temp file plus rename; a Kubernetes secret mount already does.)
func (a *TokenFileAuth) reload() error {
a.mu.Lock()
defer a.mu.Unlock()
fi, err := os.Stat(a.path)
if err != nil {
return fmt.Errorf("token file %s: %w", a.path, err)
}
if fi.ModTime().Equal(a.modTime) && fi.Size() == a.size {
return nil
}
digests, modTime, size, err := readTokenFile(a.path)
if err != nil {
return err
}
a.digests.Store(&digests)
a.modTime, a.size = modTime, size
return nil
}
// readTokenFile reads and parses the whole file, returning the stat it read it
// under so the caller's cache describes the bytes it actually holds.
func readTokenFile(path string) (digests [][sha256.Size]byte, modTime time.Time, size int64, err error) {
// #nosec G304 -- opening an operator-named path IS the feature: the path
// comes from --auth-token-file (or its BEADS_SERVE_* alias), which only the
// person starting the process supplies. No request influences it.
f, err := os.Open(path)
if err != nil {
return nil, time.Time{}, 0, fmt.Errorf("token file %s: %w", path, err)
}
defer func() { _ = f.Close() }()
fi, err := f.Stat()
if err != nil {
return nil, time.Time{}, 0, fmt.Errorf("token file %s: %w", path, err)
}
if fi.IsDir() {
return nil, time.Time{}, 0, fmt.Errorf("token file %s is a directory", path)
}
// One byte past the cap, so an oversized file is detected rather than
// silently truncated into an accepted set missing its last token.
data, err := io.ReadAll(io.LimitReader(f, maxTokenFileBytes+1))
if err != nil {
return nil, time.Time{}, 0, fmt.Errorf("token file %s: %w", path, err)
}
if len(data) > maxTokenFileBytes {
return nil, time.Time{}, 0, fmt.Errorf("token file %s is larger than %d bytes; that is a mis-pointed path, not a token file",
path, maxTokenFileBytes)
}
digests = parseTokens(data)
if len(digests) == 0 {
return nil, time.Time{}, 0, fmt.Errorf("token file %s contains no tokens", path)
}
return digests, fi.ModTime(), fi.Size(), nil
}
// parseTokens turns the file into the accepted digest set: every non-empty
// line, trimmed, is one token. Trimming handles CRLF and stray indentation; no
// comment syntax is invented, because a "#" line would be a token an operator
// believed was disabled.
func parseTokens(data []byte) [][sha256.Size]byte {
var out [][sha256.Size]byte
for line := range strings.SplitSeq(string(data), "\n") {
tok := strings.TrimSpace(line)
if tok == "" {
continue
}
out = append(out, sha256.Sum256([]byte(tok)))
}
return out
}
// ValidateAuthPosture refuses the flag combinations that would ship a server
// nobody meant to ship. It is called from the CLI so the refusal is immediate,
// and again from Listen so the library cannot be misused by a second caller.
//
// The rule the whole slice turns on: loopback with no token file is today's
// behavior, byte for byte. Everything else is either authenticated or refused,
// with one explicitly-named escape hatch.
func ValidateAuthPosture(allowNonLoopback, hasTokenFile, insecureNoAuth bool) error {
if insecureNoAuth && hasTokenFile {
return errors.New("--insecure-no-auth contradicts --auth-token-file; pass one or the other")
}
if insecureNoAuth && !allowNonLoopback {
return errors.New("--insecure-no-auth applies only to a bind beyond loopback; on loopback there is nothing to waive, so pass --allow-non-loopback or drop the flag")
}
if allowNonLoopback && !hasTokenFile && !insecureNoAuth {
return errors.New("--allow-non-loopback requires --auth-token-file (or the explicit --insecure-no-auth): every peer that can reach the address gets full read and claim access")
}
return nil
}