Files
archie/internal/infrastructure/captureintake/receiver.go
T
sam 6adbdc55a9 feat(eda): sources own signing, with UUIDv7 paths and approved unsigned option
A source is the capture endpoint: a UUIDv7 path by default or a unique
URL-safe custom path, signed by default with an Archie-generated secret
(encrypted via the bindings cipher), or unsigned after an approval.
Intake verifies X-Hub-Signature-256/X-Signature-256 against the source
secret before redaction; an unauthenticated event on a signed source is
captured but never dispatched, an event on an approved unsigned source
dispatches and is marked unsigned. The binding secret is retired; migration
0006 derives sources from existing binding and capture source strings,
moving each binding's secret onto its source. SourceStore crosses the
State Store gRPC contract. The dashboard gains a sources panel and flags
unsigned in the capture inspector, binding list and task timeline.
2026-09-24 14:26:21 +10:00

232 lines
8.9 KiB
Go

// Package captureintake is the HTTP receiver for inbound webhooks archie has
// no binding for yet: it persists what arrives so an operator can inspect it
// and build one (docs/prds/event-capture-storage.md).
//
// It belongs to the process that owns work intake, not to the dashboard that
// displays captures. It served from the dashboard's listener while the two
// shared a process; the split gives the read to the dashboard, over the State
// Store, and keeps the write here (archie-core-8cda.5.4). From the cutover
// change in the same bead it is a persistence shim over the State Store
// contract mounted by the UI process -- the only dashboard listener left --
// while the daemon's binding-dispatch loop consumes captures from the same
// store: the HTTP front door moved without moving work intake.
package captureintake
import (
"context"
"encoding/json"
"io"
"log/slog"
"net"
"net/http"
"time"
"github.com/samcharles93/archie-core/internal/domain/source"
"github.com/samcharles93/archie-core/internal/domain/storecontract"
"github.com/samcharles93/archie-core/internal/events"
"github.com/samcharles93/archie-core/internal/webhookguard"
)
// Path is the route this receiver serves. It is unauthenticated by design:
// the senders it exists to capture have no credential here yet.
const Path = "POST /webhooks/capture/{source}"
// Receiver persists inbound webhook captures.
type Receiver struct {
// Captures persists what arrives. Nil answers 503 rather than failing
// the process it is mounted in: capture is a precondition for the
// no-code playbook epic, not a hard dependency of the daemon.
Captures storecontract.CaptureStore
// Limiter is the per-remote-address token bucket applied before a body
// is read. Nil disables rate limiting, which composition never does in
// production.
Limiter *webhookguard.RateLimiter
// Sources resolves the source a path names and its signing setting.
// Nil disables verification: every event records as neither
// authenticated nor unsigned, so none dispatches.
Sources SourceResolver
// Retention and MaxEvents are passed straight to InsertCapture's
// prune-on-write bounds. See config.CaptureConfig.
Retention time.Duration
MaxEvents int
// MaxBodyBytes rejects (413) a body larger than this before redaction
// or storage sees it.
MaxBodyBytes int64
// Publish puts the capture's arrival on the activity stream, with the
// request's context: the announce happens synchronously inside the
// handler, before the 202 is written, so the request's lifetime bounds
// it. Nil records the capture without announcing it.
Publish func(ctx context.Context, e events.Event)
Log *slog.Logger
}
// SourceResolver is the one SourceStore read intake needs.
type SourceResolver interface {
GetSource(ctx context.Context, path string) (*source.Source, error)
}
// Register mounts the receiver on mux.
func (rc *Receiver) Register(mux *http.ServeMux) {
mux.HandleFunc(Path, rc.ServeHTTP)
}
// ServeHTTP accepts an inbound webhook POST and persists it. On a signed
// source only a valid HMAC under the source's secret marks the event
// authenticated; on an approved unsigned source every event is marked
// unsigned. Anything else is still captured and visible in the inspector,
// but is neither, so the dispatch loop's check (binding.Matcher.Matches over
// CapturedEvent.Dispatchable) never starts a task from it.
func (rc *Receiver) ServeHTTP(w http.ResponseWriter, r *http.Request) {
if rc.Captures == nil {
http.Error(w, "capture not configured", http.StatusServiceUnavailable)
return
}
path := r.PathValue("source")
// webhookguard.RateLimiter's bucket map assumes a bounded, operator-
// registered key space (see its doc comment) -- it is never evicted, and
// a fresh key starts with a full burst allowance. source is an
// unregistered, attacker-chosen URL segment by design (this endpoint
// exists to capture senders archie has no registration for yet), so
// keying on it would let a single attacker rotate a new "source" on
// every request to bypass the limit entirely and grow the bucket map
// without bound. Remote address is the bounded identity available here.
if rc.Limiter != nil && !rc.Limiter.Allow(remoteAddrHost(r)) {
http.Error(w, "rate limit exceeded", http.StatusTooManyRequests)
return
}
src := rc.resolveSource(r, path)
r.Body = http.MaxBytesReader(w, r.Body, maxBodyBytesOrFallback(rc.MaxBodyBytes))
body, err := io.ReadAll(r.Body)
if err != nil {
// The only realistic cause here is MaxBytesReader tripping; any other
// read failure also means there is no usable body to capture.
http.Error(w, "request body too large", http.StatusRequestEntityTooLarge)
return
}
// Verified on the raw bytes, before redaction parses them.
authenticated, unsigned := verify(src, r.Header, body)
headers, _ := json.Marshal(r.Header)
redactedHeaders, err := webhookguard.RedactPayload(headers)
if err != nil {
redactedHeaders = headers
}
// A body that isn't JSON has no key-value structure for the heuristic to
// match against, so there is nothing to redact -- store it as received
// rather than dropping or mangling it. Best-effort, per
// docs/prds/webhook-intake-security.md point 5.
redactedBody, err := webhookguard.RedactPayload(body)
if err != nil {
redactedBody = body
}
c := storecontract.CapturedEvent{
ReceivedAt: time.Now().UTC(),
Source: path,
RemoteAddr: r.RemoteAddr,
ContentType: r.Header.Get("Content-Type"),
Headers: string(redactedHeaders),
Body: string(redactedBody),
Authenticated: authenticated,
Unsigned: unsigned,
}
id, err := rc.Captures.InsertCapture(r.Context(), c, rc.Retention, rc.MaxEvents)
if err != nil {
rc.logger().Error("capture insert", "err", err, "source", path)
http.Error(w, "capture failed", http.StatusInternalServerError)
return
}
// Reuses the existing activity-event pipeline rather than inventing
// separate push plumbing -- see docs/prds/event-capture-storage.md.
// Deliberately LIGHTWEIGHT: the events table this feeds has no retention
// or row-count prune, unlike captured_events, so embedding the full (up
// to MaxBodyBytes) body/headers here would duplicate the payload into an
// unbounded table and defeat InsertCapture's own disk-bound guarantee.
// The captures view treats this purely as an invalidation signal and
// refetches the list for the actual row data.
if rc.Publish != nil {
rc.Publish(r.Context(), events.Event{
Kind: "capture",
Detail: "capture from " + path,
Data: map[string]any{"id": id, "source": path, "unsigned": unsigned},
})
}
w.WriteHeader(http.StatusAccepted)
}
// resolveSource looks up the source a path names. A lookup error is logged
// and treated as an unknown source: the event is still captured but cannot
// dispatch, so failing open here costs no safety, while failing closed would
// turn a transient store hiccup into a capture outage.
func (rc *Receiver) resolveSource(r *http.Request, path string) *source.Source {
if rc.Sources == nil {
return nil
}
src, err := rc.Sources.GetSource(r.Context(), path)
if err != nil {
rc.logger().Warn("source lookup", "source", path, "err", err)
return nil
}
return src
}
// verify decides how an event on src may dispatch. An approved unsigned
// source marks it unsigned. Otherwise a valid HMAC under the source's secret
// authenticates it: X-Hub-Signature-256 first, X-Signature-256 as fallback.
// A source with no secret yet authenticates nothing, since an empty key is
// one anybody can sign with.
func verify(src *source.Source, h http.Header, body []byte) (authenticated, unsigned bool) {
switch {
case src == nil:
return false, false
case src.Unsigned():
return false, true
case src.Secret == "":
return false, false
}
sig := h.Get("X-Hub-Signature-256")
if sig == "" {
sig = h.Get("X-Signature-256")
}
return webhookguard.VerifyHMAC(body, sig, src.Secret), false
}
func (rc *Receiver) logger() *slog.Logger {
if rc.Log == nil {
return slog.New(slog.DiscardHandler)
}
return rc.Log
}
// fallbackMaxBodyBytes bounds a capture body when MaxBodyBytes is left unset
// (zero). The size cap is the only one of the three disk-bound mechanics in
// docs/prds/event-capture-storage.md that limits a SINGLE payload rather than
// total row count or write rate -- a table pruned to maxEvents rows still
// holds one arbitrarily large row if nothing ever bounded that row's size, so
// this must never be skippable by a missing wiring value the way the rate
// limiter (best-effort, not disk-bound-load-bearing on its own) is allowed to
// be.
const fallbackMaxBodyBytes = 256 * 1024
func maxBodyBytesOrFallback(configured int64) int64 {
if configured > 0 {
return configured
}
return fallbackMaxBodyBytes
}
// remoteAddrHost strips the port from r.RemoteAddr for use as a rate-limit
// key, falling back to the raw value if it isn't a host:port pair.
func remoteAddrHost(r *http.Request) string {
host, _, err := net.SplitHostPort(r.RemoteAddr)
if err != nil {
return r.RemoteAddr
}
return host
}