Files
archie/docs/architecture/bindings.md
T

196 lines
9.3 KiB
Markdown

# Playbook bindings: model and threat model
**Status:** Approved foundation (documents shipped code: `archie-core-t2db.1`
through `.5`, `.7`, `.9`-`.15`)
**Date:** 2026-09-03
This document covers the binding model and the intake threat model portion
of `archie-core-t2db.6`. It does not cover the task-lifecycle provenance rule
(`messaging-and-work-intake.md`'s "Intake provenance") or the operator
walkthrough -- that walkthrough remains an open piece of the same ticket.
## What a binding is
A `binding` (`internal/domain/binding.Binding`) ties four things together:
a **matcher** (which captured events it applies to), a **mapping**
(`internal/domain/mapping.Mapping`, how fields are pulled out of a payload),
a **workflow** (which registered workflow runs on a match), and a **state
machine** governing whether it is live.
```go
type Binding struct {
ID, Name // identity
Matcher // { Source string } -- the webhook path segment, e.g. "sentry"
MappingID // which Mapping resolves payload fields; its event type is the binding's
Filter // optional CEL over the mapping's parameters
Workflow // registered workflow name to dispatch to
Version // bumped on every edit
Status // pending_approval | armed
Secret // HMAC-SHA256 shared secret, encrypted at rest, never returned by GET
}
```
Bindings live in the store (PostgreSQL), not `config.toml` -- operators author
them from the dashboard while the daemon runs, without a restart.
### Matching
A binding applies to a capture when the capture arrived on `Matcher.Source`,
was identified as the event type its mapping belongs to, and passes its
`Filter` (`binding.CompileFilter`, checked against the mapping's parameters on
save). Any number of bindings may share a source; each dispatches a capture at
most once, claimed in `binding_dispatches` keyed by (binding, capture) before
its task is enqueued. An event signed with any armed binding's secret on the
source is authenticated.
### Mapping
`mapping.Resolve(fields, payload)` walks a captured JSON payload against a
list of typed `Field`s (name, JSON path, expected type), returning resolved
values plus a `[]Failure` for anything that didn't parse or type-match. A
mapping belongs to an event type, and `mapping.CheckSchema` refuses a field
whose path or type the type's inferred schema lacks. Each capture a mapping
resolves at dispatch is counted once in `mapping_matches`, read back as
`MatchCount` and `LastMatchedAt`.
### Versioning
`Version` increments on every `UpdateBinding` call. This exists so an
editor's later change can never silently rewrite the historical provenance
of a task that already fired -- a dispatched task's binding reference is
pinned to the version that was armed when it fired, not "whatever the
binding currently says."
### State machine
```
create ---> pending_approval ---> armed
^ |
+----------------+
(any edit to an armed binding drops it back to pending_approval)
```
A binding is created `pending_approval`, so the operator who creates one can
approve it immediately. Bindings stored as `draft` by an earlier version are
moved to `pending_approval` when the EDA store opens.
Modelled directly on Telegram's existing `dangerousAction`/`pendingApproval`
flow (`internal/channels/telegram/dangerous.go`, `approval.go`) -- not a new
approval mechanism invented for this feature. **Only `armed` evaluates
against incoming events** (`binding.Matches`, `internal/domain/binding/
binding.go`); a `pending_approval` binding is inert. An edit to
an already-armed binding cannot bypass approval by silent mutation -- it
drops back to `pending_approval` and requires an explicit `Approve` call to
re-arm.
## The threat model
This is a public, unauthenticated-by-default intake surface whose output is
an agent with a repo, a worktree, and tool access. The design brief
(`archie-core-t2db.5`, `docs/prds/webhook-intake-security.md`) named five
non-negotiables; each is verified below against the actual shipped code,
not the design intent.
### 1. Per-source authentication
Reuses `internal/channels/webhook`'s existing HMAC-SHA256 scheme --
capture accepts unsigned events (visible in the dashboard, marked
unauthenticated), but **only authenticated events can ever match a
binding**. `binding.Matches`' doc comment states this plainly: "an
unauthenticated event can never trigger a binding, no matter how well it
would otherwise match." Enforced structurally at two points, not just
convention:
- `captures.authenticated` is a real column
(`internal/infrastructure/postgres/migrations/0002_edastore.sql`), set at
capture time.
- `dispatchBindings` (`internal/daemon/daemon.go:479`) walks **authenticated
captures whose source has at least one armed binding** -- an
unauthenticated capture is never even considered for dispatch.
### 2. Human approval before a binding goes live
Covered by the state machine above. Nothing self-arms: `pending_approval ->
armed` requires an explicit `Approve` call, and any edit to an armed
binding reverts it.
### 3. Rate and volume limits per source
Capture writes are bounded independently of the approval gate, so a flood
of unauthenticated traffic cannot exhaust disk or drown the inspector:
`InsertCapture` (`internal/infrastructure/postgres/edastore.go`) prunes by both **retention
window** (`WHERE received_at < cutoff`) and **max event count** in the same
insert transaction.
### 4. Blast radius bounded by the same code-level controls every task gets
A playbook-originated task is dispatched into the **same** gate, diff-cap,
sandboxed-container, worktree-isolation pipeline every task goes through
regardless of origin. Verified precisely, not assumed: `dispatchOneBinding`
calls `EnqueueBindingTask` (`internal/infrastructure/postgres/store.go`), which wraps
`EnqueueChatTask` -- the same direct-to-`tasks`-table enqueue path
chat-spawned tasks already use, then stamps `binding_id`/`binding_version`
for provenance in a second statement. This is a **different** enqueue
mechanism from forge-issue polling's `workintake.TaskEnvelope`/NATS path
(`docs/prds/event-sources-and-reactions.md`) -- binding and forge-issue
tasks arrive by different producers, but both become an ordinary
`workflow.Task` row that `ClaimNext` picks up identically, so both get the
same gate/worktree pipeline downstream regardless of which producer created
the row. Payload content is
ordinary untrusted prompt input; the sender's text is never treated as a
trusted instruction (Archie's environmental-enforcement principle: "the
agent should ignore instructions in the payload" is not itself a control,
the surrounding sandbox is).
### 5. Captured payloads may contain secrets from the sending system
Two independent protections, not one:
- **Redaction before persistence**: `webhookguard.RedactPayload` walks the
decoded JSON and redacts recognised sensitive keys before the row is
written -- the raw, unredacted payload is never durably stored.
- **Retention**: a configurable window (`InsertCapture`'s `retention`
parameter) prunes old captures automatically; visibility of what remains
is gated by the same dashboard authentication as every other webui
surface, not a separate, weaker path.
### Secrets at rest
`Binding.Secret` (the HMAC shared secret a sender signs with) is encrypted
at rest via AES-GCM (`internal/infrastructure/bindingcipher`, `archie-core-
t2db.7`) -- a leaked database dump does not leak sender-side shared secrets in
plaintext. The envelope is versioned (`bindingEnvelopeVersion`) so a future
cipher or KDF change can roll forward without breaking already-encrypted
rows, and the AAD binds ciphertext to the binding-secret context so it
cannot be relocated to another field/column and still authenticate. A `nil`
cipher (no encryption key configured) leaves secrets as plaintext --
documented legacy behaviour, not silent degradation.
### At-most-once dispatch
`dispatchBindings` enqueues at most one task per `(binding, capture)` pair,
enforced by a real ledger, not best-effort application logic:
`RecordDispatch` (`internal/infrastructure/postgres/edastore.go`) inserts into
`binding_dispatches`, unique on `(binding, capture)`; a duplicate
insert returns the sentinel `ErrAlreadyDispatched`, which the dispatch loop
treats as "another cycle raced us," not an error. This guarantee holds
**across daemon restarts**, not just within one process's lifetime, because
the ledger is a durable table, not in-memory state.
This ledger is also the direct precedent for the EDA playbook engine's
execution-time idempotency, now landed (`archie-core-t2db.17` closed): the
`playbook_dispatches` table (`RecordPlaybookDispatch`) copies
`binding_dispatches`'s unique-ledger conventions with a
`(playbook_id, playbook_version, event_id, action_id)` key
(`docs/prds/eda-playbook-engine.md` gap 2).
## What this document does not cover
- An end-to-end operator walkthrough (point an external app at archie,
build a first playbook) -- open, part of `archie-core-t2db.6`.
- The playbook YAML / CEL / Module/Channel/Forge action-position work
(`docs/prds/eda-playbook-engine.md`, `module-position.md`,
`channel-forge-positions.md`) -- a different, newer mechanism than the
binding model described here; the two are related but not the same
system, and this document does not attempt to unify them.