Files
archie/docs/prds/webhook-intake-security.md
T
sam e95a77c2f7 docs: delete ARCHITECTURE.md, move its normative content into docs/architecture
ARCHITECTURE.md duplicated the docs/architecture tree and had drifted badly
against it: "internal/ holds ~36" against 112 packages, two of the seven
binaries listed, a Forge table listing `RepliesAfter` (deleted from the tree),
and a stated invariant ("No daemon-internal cron") contradicted by the
scheduling engine that internal/app/archied/scheduling.go composes and
main.go starts.

It was also the sole home of three pieces of still-authoritative content, so
those move rather than disappear:

- plugin engine rule (strict), the memory engine family, and the
  internal/plugin/architecture_test.go enforcement note ->
  docs/architecture/plugins-and-extensions.md
- intake provenance: forge poll/webhook dedup through
  TaskEnvelope.IdempotencyKey, binding-stamped chat/playbook enqueue, and the
  single-identity webhook-intake rejection ->
  docs/architecture/messaging-and-work-intake.md

Live references are repointed from CLAUDE.md (AGENTS.md is a symlink to it),
docs/architecture, docs/guides, seven PRDs, and four .agents skills. The
heading "## Plugin engine rule (strict)" is preserved in its new home so the
existing #plugin-engine-rule-strict citations keep resolving. Generated docs
artifacts regenerated.
2026-09-22 23:49:53 +10:00

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 normalized 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 authorization 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.