Files
archie/docs/prds/webhook-intake-security.md
T

102 lines
5.2 KiB
Markdown

# Webhook intake security -- decision
**Status:** Approved
**Date:** 2026-08-22
**Beads issue:** `archie-core-t2db.5`, blocks `archie-core-t2db.4`
## Why this is decided ahead of the code it constrains
`archie-core-t2db` (no-code playbooks) and `archie-core-7d5u` (typed event
sources) both land a public intake surface whose eventual output is an agent
with tool access and a repo. Neither capture (`t2db.1`) nor the intake family
(`7d5u.3`) has shipped yet, so this decision exists to be a contract the two
epics build against, not a retrofit once the surface exists. A webhook URL
that can start an agent is remote code execution with extra steps if any of
the five points below is missing on day one.
## 1. Per-source authentication
Reuse the per-route HMAC-SHA256 scheme already in
`internal/channels/webhook/webhook.go` (`validateHMAC`), unchanged: a source
registers with a shared secret; the signature is checked against the raw
body. Do not invent a second scheme for intake.
**Capture and triggering split at the signature, not at a separate flag.** An
event with a missing or invalid signature is still captured (visible in the
inspector, marked unauthenticated) so an operator can diagnose a
misconfigured sender -- but an unauthenticated event can never be matched
against a binding. Authentication is what promotes an event from "something
arrived" to "something that can run a workflow."
## 2. Human approval before a binding arms
A binding has three states: `draft -> pending_approval -> armed`. Only
`armed` bindings are evaluated against incoming events. Creating or editing a
binding's matcher, mapping, or target workflow always sets it to
`pending_approval`, including edits to an already-armed binding -- an edit is
not silently re-armed, or the approval gate is decorative. Approval requires
an authenticated dashboard session; there is no unattended approval path.
Model: `internal/channels/telegram`'s dangerous-command approval flow
(`dangerousAction` / `pendingApproval` in `dangerous.go` / `approval.go`) is
the existing precedent for "a human decision gates code from running" in this
codebase -- follow its shape rather than designing a new approval primitive.
## 3. Rate and volume limits, per source
A token-bucket limiter keyed by source ID, not global -- one noisy or hostile
sender must not exhaust another source's capture budget. Precedent for
per-key volume capping: `internal/pairing/store.go`'s `MaxPendingPerPlatform`.
On limit exceeded, the request is rejected (HTTP 429), not silently dropped.
A silently dropped event is indistinguishable from a sender that never fired
-- the same invisible-failure shape the update-verification work
(`archie-core-522`) exists to prevent. The rejection itself is observable in
the inspector as a distinct outcome from "not received."
## 4. Blast radius bounded by code, not by prompt wording
A playbook-triggered task runs through exactly the same enforcement as every
other task: the `[[repos.gate]]` quality gate, `diff_cap_lines`, the
sandboxed per-task container (`internal/container`), worktree isolation, and
"the model never runs git." No new relaxation is introduced for
playbook-triggered work, and none is needed -- the existing constraints are
the control.
Mapped payload fields are treated as ordinary user-controlled text inside an
agent prompt, exactly like an inbound chat message never as trusted
instructions. "The agent should ignore instructions in the payload" is not a
control and must not appear as one anywhere in this feature -- per the
environmental-enforcement principle (`docs/architecture/agent-system.md`,
"Existing invariants to preserve"), the boundary is the gate and the sandbox,
not a sentence in the system prompt.
## 5. Retention and redaction of captured payloads
**Retention:** captured events (bound or not) are purged after 7 days,
configurable per deployment. Unbound events exist to be mapped against; nothing
justifies keeping them indefinitely once that window has passed, and an
unbounded capture store is the same disk-exhaustion risk item 3 addresses at
the request-rate level.
**Redaction:** before a captured payload is persisted, apply the same
key-name heuristic `internal/gateway/stream.go`'s `sensitiveParameterKey`
already uses for tool-call parameters (matches `token`, `secret`, `password`,
`passwd`, `api_key`, `apikey`, `authorization`, `credential`, `cookie`,
`private_key` against normalised JSON keys) and replace matching values with
the same `[redacted]` marker. This is best-effort, not a guarantee -- a
sender that names a secret field something the heuristic misses will still
have it captured. Document that limitation where captured payloads are
displayed, rather than implying the redaction is complete.
**Visibility:** captured payloads, redacted or not, are visible only to an
authenticated dashboard operator -- the same authorisation boundary as every
other webui surface, not a separate or lower bar.
## What this does not decide
The intake family's registration interface (`7d5u.3`), the capture storage
mechanism (`7d5u.2`, embedded NATS), and the binding data model's persistence
and versioning (`t2db.4`) are separate decisions. This document constrains
all three: whatever they build must satisfy points 1-5 above.