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

335 lines
11 KiB
Go

package httpapi
import (
"bytes"
"fmt"
"os"
"path/filepath"
"strings"
"sync"
"sync/atomic"
"testing"
"time"
)
// These tests are pure: a token file in t.TempDir and an injected clock. The
// rotation property they pin — a token added to the file is accepted without a
// restart, and one removed from it stops being accepted — is the whole reason
// the accepted set is not a startup snapshot.
// fakeClock is the injected time source. Verify's reload gate is the one place
// this package reads a wall clock, so a test that wants to cross the gate moves
// this rather than sleeping a real second.
type fakeClock struct{ nanos atomic.Int64 }
func (c *fakeClock) now() time.Time { return time.Unix(0, c.nanos.Load()) }
func (c *fakeClock) advance(d time.Duration) { c.nanos.Add(int64(d)) }
// writeTokenFile writes content and returns the path. Every rewrite moves the
// modification time forward explicitly: a test that rewrites a file twice
// inside one filesystem timestamp tick would otherwise be asserting against
// the stat cache rather than against the reload.
func writeTokenFile(t *testing.T, path, content string) {
t.Helper()
if err := os.WriteFile(path, []byte(content), 0o600); err != nil {
t.Fatalf("write %s: %v", path, err)
}
touch(t, path, time.Now())
}
func touch(t *testing.T, path string, mod time.Time) {
t.Helper()
if err := os.Chtimes(path, mod, mod); err != nil {
t.Fatalf("chtimes %s: %v", path, err)
}
}
func newAuthForTest(t *testing.T, content string) (*TokenFileAuth, string, *fakeClock) {
t.Helper()
path := filepath.Join(t.TempDir(), "tokens")
writeTokenFile(t, path, content)
auth, err := NewTokenFileAuth(path)
if err != nil {
t.Fatalf("NewTokenFileAuth: %v", err)
}
clock := &fakeClock{}
clock.nanos.Store(int64(time.Hour))
auth.now = clock.now
auth.reloadGate = time.Second
return auth, path, clock
}
func mustVerify(t *testing.T, a *TokenFileAuth, token string) bool {
t.Helper()
ok, err := a.Verify(token)
if err != nil {
t.Fatalf("Verify(%q): unexpected reload error: %v", token, err)
}
return ok
}
// TestTokenFileAcceptsEveryLine is the rotation mechanism stated as a parse
// rule: every non-empty line is a token and all of them are accepted, which is
// what lets an operator write {new,old}, roll clients, and drop old.
func TestTokenFileAcceptsEveryLine(t *testing.T) {
auth, _, _ := newAuthForTest(t, "alpha\r\n bravo \n\n\ncharlie\n")
for _, tok := range []string{"alpha", "bravo", "charlie"} {
if !mustVerify(t, auth, tok) {
t.Errorf("token %q from the file was refused", tok)
}
}
for _, tok := range []string{"", " ", "delta", "alpha ", "ALPHA"} {
if mustVerify(t, auth, tok) {
t.Errorf("token %q is not in the file but was accepted", tok)
}
}
}
// TestNewTokenFileAuthRefusesAnUnusableFile: a server whose token file cannot
// be read must not start. Failing open serves the whole surface
// unauthenticated; failing silently closed answers 401 to every client with
// nothing on stderr saying why.
func TestNewTokenFileAuthRefusesAnUnusableFile(t *testing.T) {
dir := t.TempDir()
empty := filepath.Join(dir, "empty")
writeTokenFile(t, empty, "")
blank := filepath.Join(dir, "blank")
writeTokenFile(t, blank, "\n \n\r\n")
fat := filepath.Join(dir, "fat")
writeTokenFile(t, fat, strings.Repeat("a", maxTokenFileBytes+1))
for _, tc := range []struct{ name, path, want string }{
{"missing", filepath.Join(dir, "nope"), "no such file"},
{"empty", empty, "no tokens"},
{"blank lines only", blank, "no tokens"},
{"oversized", fat, "larger than"},
{"unnamed", "", "no token file"},
{"directory", dir, ""},
} {
t.Run(tc.name, func(t *testing.T) {
_, err := NewTokenFileAuth(tc.path)
if err == nil {
t.Fatalf("NewTokenFileAuth(%q) = nil error, want a startup refusal", tc.path)
}
if tc.want != "" && !strings.Contains(err.Error(), tc.want) {
t.Errorf("error %q does not explain the refusal (want %q in it)", err, tc.want)
}
if !strings.Contains(err.Error(), "token") && !strings.Contains(err.Error(), tc.path) {
t.Errorf("error %q names neither the token file nor its path", err)
}
})
}
}
// TestTokenRotatesWithoutARestart is the CRITICAL property. A snapshot taken at
// startup would make rotation a pod restart and would make a leaked token
// unrevokable for the life of the process.
func TestTokenRotatesWithoutARestart(t *testing.T) {
auth, path, clock := newAuthForTest(t, "old-token\n")
if !mustVerify(t, auth, "old-token") {
t.Fatal("the token the server started with was refused")
}
// Overlap window: both tokens are live, so clients roll one at a time.
writeTokenFile(t, path, "new-token-value\nold-token\n")
clock.advance(2 * time.Second)
if !mustVerify(t, auth, "new-token-value") {
t.Error("a token added to the file was refused; rotation would need a restart")
}
if !mustVerify(t, auth, "old-token") {
t.Error("the overlapping old token was refused mid-rotation")
}
// Revocation: drop the old token and it stops being accepted, with no
// restart and no window longer than the reload gate.
writeTokenFile(t, path, "new-token-value\n")
clock.advance(2 * time.Second)
if mustVerify(t, auth, "old-token") {
t.Error("a token removed from the file is still accepted; a leaked token would be unrevokable")
}
if !mustVerify(t, auth, "new-token-value") {
t.Error("the surviving token was refused after revocation")
}
}
// TestReloadIsStatGated bounds what a 401 storm can cost: at most one stat per
// gate interval, whatever the request rate.
func TestReloadIsStatGated(t *testing.T) {
auth, path, clock := newAuthForTest(t, "first\n")
// First mismatch claims the reload slot and finds nothing new.
if mustVerify(t, auth, "second-token") {
t.Fatal("an unknown token was accepted")
}
// The file now carries it, but the gate has not elapsed, so the second
// mismatch must not even stat.
writeTokenFile(t, path, "first\nsecond-token\n")
if mustVerify(t, auth, "second-token") {
t.Error("a reload ran inside the gate window; a 401 storm would stat the file per request")
}
clock.advance(2 * time.Second)
if !mustVerify(t, auth, "second-token") {
t.Error("the reload did not run after the gate elapsed")
}
}
// TestUnchangedFileIsNotReread is the cheap branch a wrong-token storm actually
// hits: the gate elapses, the server stats, nothing moved, and it stops there.
// Rewriting the bytes while restoring mtime and size makes a re-read
// observable — if one happened, the new token would be accepted.
func TestUnchangedFileIsNotReread(t *testing.T) {
auth, path, clock := newAuthForTest(t, "aaaaa\n")
fi, err := os.Stat(path)
if err != nil {
t.Fatalf("stat: %v", err)
}
writeTokenFile(t, path, "bbbbb\n") // same length
touch(t, path, fi.ModTime())
clock.advance(2 * time.Second)
if mustVerify(t, auth, "bbbbb") {
t.Error("the file was re-read despite an unchanged mtime and size")
}
if !mustVerify(t, auth, "aaaaa") {
t.Error("the cached set was dropped by a reload that should not have happened")
}
}
// TestBadReloadKeepsTheLastGoodSet: a writer that truncates before writing must
// not lock every client out of the server for the duration of its write. The
// error is reported to the caller so it reaches the log, and the next mismatch
// past the gate re-reads.
func TestBadReloadKeepsTheLastGoodSet(t *testing.T) {
for _, tc := range []struct {
name string
break_ func(t *testing.T, path string)
}{
{"truncated mid-write", func(t *testing.T, path string) { writeTokenFile(t, path, "") }},
{"deleted", func(t *testing.T, path string) {
if err := os.Remove(path); err != nil {
t.Fatalf("remove: %v", err)
}
}},
} {
t.Run(tc.name, func(t *testing.T) {
auth, path, clock := newAuthForTest(t, "live-token\n")
tc.break_(t, path)
clock.advance(2 * time.Second)
ok, err := auth.Verify("unknown")
if ok {
t.Error("an unknown token was accepted")
}
if err == nil {
t.Error("a failed reload was silent; the operator gets no log line for a broken token file")
}
if !mustVerify(t, auth, "live-token") {
t.Error("the last-good set was dropped, locking every client out on a writer race")
}
// Self-healing: the stat cache was not updated, so the next
// attempt past the gate re-reads.
writeTokenFile(t, path, "live-token\nsecond-token\n")
clock.advance(2 * time.Second)
if !mustVerify(t, auth, "second-token") {
t.Error("the reload did not recover after the file was restored")
}
})
}
}
// TestVerifyIsRaceFree hammers the accepted-token fast path and the reload path
// together. Run under -race this is the guard on the atomic swap.
func TestVerifyIsRaceFree(t *testing.T) {
auth, _, clock := newAuthForTest(t, "good\n")
var wg sync.WaitGroup
for i := range 8 {
wg.Add(1)
go func(i int) {
defer wg.Done()
for j := range 200 {
if i%2 == 0 {
if ok, _ := auth.Verify("good"); !ok {
t.Errorf("the accepted token was refused under concurrency")
return
}
continue
}
if ok, _ := auth.Verify(fmt.Sprintf("bad-%d-%d", i, j)); ok {
t.Error("an unknown token was accepted under concurrency")
return
}
clock.advance(400 * time.Millisecond)
}
}(i)
}
wg.Wait()
}
// TestValidateAuthPosture pins the default: loopback with no token file is
// today's behavior, and every other combination either enables auth or is
// refused at startup. --allow-non-loopback without a credential is the one that
// mattered — reachability was full read and claim authority.
func TestValidateAuthPosture(t *testing.T) {
for _, tc := range []struct {
name string
nonLoopback, hasToken, insecureNoAuth bool
wantErr string
}{
{name: "loopback, no token: unchanged"},
{name: "loopback with a token", hasToken: true},
{name: "non-loopback with a token", nonLoopback: true, hasToken: true},
{
name: "non-loopback with no credential", nonLoopback: true,
wantErr: "--auth-token-file",
},
{
name: "non-loopback waived explicitly", nonLoopback: true, insecureNoAuth: true,
},
{
name: "waiver contradicts a token file", nonLoopback: true, hasToken: true, insecureNoAuth: true,
wantErr: "--insecure-no-auth",
},
{
name: "waiver on loopback is meaningless", insecureNoAuth: true,
wantErr: "--allow-non-loopback",
},
} {
t.Run(tc.name, func(t *testing.T) {
err := ValidateAuthPosture(tc.nonLoopback, tc.hasToken, tc.insecureNoAuth)
if tc.wantErr == "" {
if err != nil {
t.Fatalf("ValidateAuthPosture = %v, want nil", err)
}
return
}
if err == nil {
t.Fatalf("ValidateAuthPosture = nil, want a refusal naming %s", tc.wantErr)
}
if !strings.Contains(err.Error(), tc.wantErr) {
t.Errorf("refusal %q does not name %s, so it does not say how to proceed", err, tc.wantErr)
}
})
}
}
// TestTokenFileAuthNeverHoldsRawTokens: the accepted set in memory is digests.
// A core dump or a heap profile of a running server discloses no credential.
func TestTokenFileAuthNeverHoldsRawTokens(t *testing.T) {
const secret = "s3cret-token-value"
auth, _, _ := newAuthForTest(t, secret+"\n")
if !mustVerify(t, auth, secret) {
t.Fatal("token refused")
}
for _, d := range *auth.digests.Load() {
if bytes.Contains(d[:], []byte(secret)) {
t.Error("the cached accepted set carries the raw token")
}
}
}