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>
262 lines
10 KiB
Go
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
|
|
}
|