Documentation
¶
Overview ¶
Package webbotauth implements the verification path of the draft-ietf-webbotauth-httpsig-protocol-01 profile of RFC 9421 HTTP Message Signatures: header parsing, profile enforcement, signature-base reconstruction and cryptographic verification against keys supplied by a caller-provided KeySource.
Design: docs/superpowers/backlog-designs/09-web-bot-auth-verifier.md. This package performs NO network I/O; key resolution (JWKS fetch + cache) lives in the caller (M15b Task 3). All draft-version-specific knowledge is confined to profile.go (design §8).
Security posture (design §9/§12):
- Every failure path returns a structured Verdict; the package must never panic on adversarial input (fuzz-enforced, design §7.1/§10) — internal panics that would escape are recovered, counted (PanicsInternal) and reported as unverified.
- Only draft-01 profile parameters are accepted; unknown parameters, components and algorithms fail closed.
- The RFC 9421 Appendix B.1 test keys are rejected by RFC 7638 thumbprint blocklist (draft §6.8, pinned by design §7.1).
- Key selection follows the (agent URL, key label) pair the signature covers — never keyid alone (draft §5.4 anti-laundering) — and never reorders that pair.
Index ¶
- Constants
- func PanicsInternal() uint64
- type FetchMetrics
- type Fetcher
- func (f *Fetcher) CachedKeys(agentURL string, _ string) (rsaKeys []*rsa.PublicKey, edKeys []*ed25519.PublicKey, ok bool)
- func (f *Fetcher) Close()
- func (f *Fetcher) CloseIdleConnections()
- func (f *Fetcher) Entries() int
- func (f *Fetcher) Keys(agentURL string, _ string) (rsaKeys []*rsa.PublicKey, edKeys []*ed25519.PublicKey, ok bool)
- type FetcherConfig
- type KeySource
- type LogSink
- type Outcome
- type ProbeRequest
- type ProbeResult
- type PubKey
- type Verdict
Constants ¶
const ( // ProfileWebBotTag is the required Signature-Input `tag` value // (draft §5.2; the -01 profile mandates tag="web-bot-auth"). ProfileWebBotTag = "web-bot-auth" // ProfileDraft is the frozen protocol-draft string this build accepts // (design 09 §7.6: the admin probe reports it so operators can check // their client against the verifier's expectations). ProfileDraft = profileDraftName // createdPastWindow bounds how old `created` may be (design §7.1: )
const ( FetchResultOK = "ok" FetchResultError = "error" FetchResultBlocked = "blocked" FetchResultTooBig = "too_big" )
Fetch tick labels (closed enum; docs/usage/metrics.md mirrors these — the ONLY legal values of merlon_webbotauth_directory_fetches_total{result=…}).
const ErrProbeNoKeys = "" /* 138-byte string literal not displayed */
ErrProbeNoKeys is the human guidance appended to the unverified verdict when the agent's directory has no cached keys: the operator must send one real signed request through merlon before the probe can verify against that directory (the probe itself never fetches).
Variables ¶
This section is empty.
Functions ¶
func PanicsInternal ¶
func PanicsInternal() uint64
PanicsInternal returns recovered internal panics since process start. It must be 0 in production; any non-zero value is a security-grade bug (attacker input reached a panic site).
Types ¶
type FetchMetrics ¶
type FetchMetrics interface {
DirectoryFetch(result string)
DirectoryCacheEntries(n int)
DirectoryLastSuccess(unixSeconds int64)
}
FetchMetrics receives the directory cache/fetcher instruments (frozen names: docs/usage/metrics.md). Implemented structurally by internal/metricx (Task 4 wires it), keeping this package stdlib-only.
type Fetcher ¶
type Fetcher struct {
// contains filtered or unexported fields
}
Fetcher is the directory cache + guarded fetcher and the production KeySource for Verify (compile-time pin below).
func NewFetcher ¶
func NewFetcher(cfg FetcherConfig) *Fetcher
NewFetcher builds a Fetcher from settings-KV-shaped config, applying the frozen defaults (cache_size 64, cache_ttl 24h, neg_ttl 5m, fetch_timeout 3s clamped to 250ms..10s) to zero/unset values. Close it on shutdown.
func (*Fetcher) CachedKeys ¶
func (f *Fetcher) CachedKeys(agentURL string, _ string) (rsaKeys []*rsa.PublicKey, edKeys []*ed25519.PublicKey, ok bool)
CachedKeys is the PROBE read of the directory cache: the same answer Keys() gives — including the admission gate and the stale-serving window — minus every side effect: no LRU touch, no eviction, and above all no scheduled refresh (design 09 §7.6: the admin probe never egresses and never writes the cache). A cold directory is simply a miss (ok=false), same as the request path's first sight.
func (*Fetcher) Close ¶
func (f *Fetcher) Close()
Close stops scheduling and waits for queued/in-flight work to drain. Idempotent. The request path never calls it; Task 4 wires it to shutdown.
func (*Fetcher) CloseIdleConnections ¶
func (f *Fetcher) CloseIdleConnections()
CloseIdleConnections drops the fetch client's idle keep-alives. It is the T3 carry #2 ("CloseIdleConnections on Fetcher.Close: idle keep-alives outlive Close"), landed at the LIFECYCLE OWNER's request instead of inside Close: the resolver's Shutdown calls Close (drain) then this (drop sockets), which keeps Close's drain semantics untouched and still guarantees a lane that was switched off stops holding a directory's connection for the life of the process. Safe at any time, including before the first fetch (the client is built on demand and holds no sockets until one is dialed) and while other work is in flight: the client pointer is read through clientOnce — the same path the fetches use, so there is no torn read — and http.Client documents CloseIdleConnections as safe to call concurrently, closing only IDLE connections and never one in use.
func (*Fetcher) Keys ¶
func (f *Fetcher) Keys(agentURL string, _ string) (rsaKeys []*rsa.PublicKey, edKeys []*ed25519.PublicKey, ok bool)
Keys implements KeySource. The request path is cache-only: map lookups, no I/O, no blocking. First sight (and stale-beyond-window, and negative, and refused) answers ok=false = unverified, never invalid. keyLabel is deliberately not an input to the directory lookup: keys are scoped per directory, and Verify enforces the (URL, label) PAIR by only ever calling with the covered label (draft §5.4, webbotauth.go KeySource).
type FetcherConfig ¶
type FetcherConfig struct {
DirectoryAllow []string // exact lowercase hosts; "*" = open mode; empty = never fetch
DirectoryDir string // test-only file hook base (see hookFilePath)
CacheSize int // cache_size
CacheTTL time.Duration
// NegTTL is the negative-cache throttle AND the stale-serving window
// (0 = defaultNegTTL). The settings key exists (frozen §13), trust
// validates it, and the trust→fetcher wire hands it HERE — the M15-T8
// flow's stale/negative legs only pass because this field is not the
// 5-minute default it was before (the row lies if it does not run).
NegTTL time.Duration
FetchTimeout time.Duration
Now func() time.Time
Metrics FetchMetrics
Log LogSink
}
FetcherConfig is the Task 4 settings-KV surface for the fetcher. DirectoryDir (the file hook) is intentionally NOT part of any settings key: production wiring never sets it, which is what keeps the hook inert in production (the hook exists so the entire cache matrix can run hermetically without a socket, following feeds' SourceCfg.File precedent).
type KeySource ¶
type KeySource interface {
Keys(agentURL, keyLabel string) (rsaKeys []*rsa.PublicKey, edKeys []*ed25519.PublicKey, ok bool)
}
KeySource resolves candidate public keys for an agent (design §7.1). The bool is false when the agent URL is unknown or carries no usable key material — that is unverified, never invalid.
Implementations MUST resolve under agentURL (the URL the signature's signature-agent component covers); a key learned for URL A must never be returned for URL B (draft §5.4 anti-laundering; pinned by TestNoLaundering).
agentURL is the NORMALIZED identifier (draft §5.5; normalizeAgentURL): lowercase scheme/host, no explicit port, no query. The Task 3 fetcher derives the directory URL it fetches from THIS string (one spelling per key set is the whole point — an un-normalized URL would fragment the fetch cache per spelling); note that draft §5.5's "fetch the member value as sent" then only matters for the exotic query-bearing member URL, whose fetch Merlon sends query-less — documented as such in docs/usage/webbotauth.md.
type LogSink ¶
type LogSink func(msg, host, reason string)
LogSink receives every cache/fetcher log line: fixed message, hostname, closed reason token. There is deliberately no field that could carry a URL query, a header value, or key material (design §7.8).
type Outcome ¶
type Outcome int
Outcome is the closed three-state verification vocabulary (draft-01 App. C.1; design §8 keeps it as the only vocabulary crossing the package boundary). Its zero value is OutcomeUnverified: a zero Verdict is always fail-closed.
const ( // OutcomeUnverified: nothing was verified (no signature, unknown // agent, no key material). NOT a failure signal. OutcomeUnverified Outcome = iota // OutcomeInvalid: a signature claim failed verification. OutcomeInvalid // OutcomeVerified: a signature verified against a key the covered // agent URL publishes. OutcomeVerified )
The three closed outcomes.
type ProbeRequest ¶
type ProbeRequest struct {
Method string `json:"method"`
Path string `json:"path"`
Authority string `json:"authority"`
Signature string `json:"signature"`
SignatureInput string `json:"signature_input"`
SignatureAgent string `json:"signature_agent"`
SignatureSignature string `json:"signature_signature"`
SignatureParameters string `json:"signature_parameters"`
}
ProbeRequest is the admin probe payload: the request the pasted signature headers were captured for, plus those headers verbatim. Method and Path are required — the signature covers them — and Authority names the request host (part of the covered components when signed).
type ProbeResult ¶
type ProbeResult struct {
Outcome string `json:"outcome"`
Reason string `json:"reason"`
Agent string `json:"agent,omitempty"`
Host string `json:"host,omitempty"`
KeyID string `json:"keyid,omitempty"`
ProtocolDraft string `json:"protocol_draft"`
}
ProbeResult is the probe response. Outcome and Reason speak the data plane's closed vocabulary (verified / invalid / unverified, §13), so the chip, the signals, and the probe never disagree about what a word means.
func VerifyProbe ¶
func VerifyProbe(preq *ProbeRequest, keys KeySource, now time.Time) (*ProbeResult, error)
VerifyProbe verifies the pasted headers via Verify against the keys the cache-only KeySource yields. lookupErr-worthiness: a cold cache is ok=false (unverified/keys_unavailable), never an error. Caller input errors (missing method/path, whitespace injection) are returned as errors — the admin layer maps them to 400s.
type PubKey ¶
PubKey is one parsed candidate public key; exactly one key member is non-nil. KID is the JWK `kid` when present (attribution only — key SELECTION uses RFC 7638 thumbprints, never kid). EC is parsed solely for the draft §6.8 blocklist reject path: the frozen KeySource interface (design §7.1) carries no EC keys, so an EC key can only ever arrive through a directory whose material we then refuse to use.
func ParseJWKS ¶
ParseJWKS parses a JWKS document (RFC 7517 §5) strictly: the `keys` member is required; every key must be a usable RSA / OKP-Ed25519 / EC key with strict base64url-no-pad members; unknown members, foreign members, unknown kty/curve and trailing garbage all error; more than maxJWKSCount keys error with errTooManyKeys. Duplicate keys are kept (dedup adds no security; thumbprint selection and the draft §6.8 blocklist neutralize them).
The count is measured on the DECODED `keys` array, which is the only spelling-independent count there is: RFC 8259 §7.4 makes the member name `"\u006bty"` identical to `"kty"`, so no byte-level scan of a document can bound the number of keys it parses into.
type Verdict ¶
type Verdict struct {
Outcome Outcome
AgentURL string // normalized agent-URL IDENTIFIER (draft §5.5; see normalizeAgentURL) the signature covers
Host string // normalized agent HOST (lowercase, no port) — the frozen signal payload (R-9-signal-host)
KeyID string // keyid parameter (may be empty on early errors)
Reason string // e.g. `expired`, `signature_mismatch`; `;warn:expires_gt_24h` suffix
}
Verdict is the structured result of Verify (design §7.1). Reason carries machine-readable snake_case tokens for signals/observability — never secret or attacker-controlled material.