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.
102 lines
5.2 KiB
Markdown
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.
|