Files
archie/docs/architecture/bindings.md
T
sam 7bbd6dff71 docs(architecture): document the playbook binding model and threat model
Partial completion of archie-core-t2db.6 -- covers the binding model
(matcher/mapping/versioning/state machine) and verifies each of the
five threat-model non-negotiables from archie-core-t2db.5 against the
actual shipped code (not just the design intent), plus the AES-GCM
secret-at-rest encryption from t2db.7 and the binding_dispatches
at-most-once ledger.

Every claim checked against real code before writing, not assumed --
caught and corrected one wrong claim in-flight: binding-originated
tasks enqueue via EnqueueChatTask (the same direct-to-store.Task path
chat-spawned tasks use), NOT workintake.TaskEnvelope/NATS the way
forge-polled tasks do. Both converge on the same tasks table and
downstream gate/worktree pipeline, but by genuinely different enqueue
mechanisms -- worth noting for t2db.6's still-open ARCHITECTURE.md
task-lifecycle section, since this is exactly the provenance
distinction that section needs to state.

Explicitly does not cover: the ARCHITECTURE.md lifecycle addendum or
the operator walkthrough, both still open pieces of t2db.6.
2026-09-03 04:24:27 +10:00

8.8 KiB

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 ARCHITECTURE.md task-lifecycle addendum or the operator walkthrough -- those remain separate, open pieces 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.

type Binding struct {
    ID, Name           // identity
    Matcher            // { Source string } -- the webhook path segment, e.g. "sentry"
    MappingID          // which Mapping resolves payload fields
    Workflow           // registered workflow name to dispatch to
    Version            // bumped on every edit
    Status             // draft | pending_approval | armed
    Secret             // HMAC-SHA256 shared secret, encrypted at rest, never returned by GET
}

Bindings live in the store (SQLite), not config.toml -- operators author them from the dashboard while the daemon runs, without a restart.

Matching

Matcher.Source is the only predicate today: the path segment a sender POSTs to (e.g. a webhook hitting .../sentry matches bindings with Matcher.Source == "sentry"). The storage column is plain TEXT, so adding predicates later is non-breaking -- extend Matcher, don't invent a second matcher shape.

Mapping

mapping.Resolve(fields, payload) walks a captured JSON payload against a list of typed Fields (name, JSON path, expected type), returning resolved values plus a []Failure for anything that didn't parse or type-match. This is schema-by-example in practice: a mapping is authored by pointing at a real captured payload in the dashboard, not by guessing a schema in advance.

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

draft ---> pending_approval ---> armed
  ^              ^                 |
  |              |                 |
  +--------------+-----------------+
        (any edit to an armed binding drops it back to pending_approval)

Modeled 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); draft and pending_approval bindings are 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:

  • captured_events.authenticated is a real column (internal/store/ captures.go), 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/store/captures.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/store/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 store.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/store/binding_cipher.go, archie-core- t2db.7) -- a leaked SQLite file 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/store/bindings.go) does INSERT OR IGNORE into binding_dispatches, unique on (binding_id, capture_id); 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 still-open EDA playbook engine idempotency question (archie-core-t2db.17, docs/prds/eda-playbook- engine.md's execution-time gap 2) -- the same (owner, event)-keyed INSERT OR IGNORE shape almost certainly generalizes to playbook-run idempotency rather than needing a new mechanism invented from scratch.

What this document does not cover

  • The ARCHITECTURE.md task-lifecycle section noting that a playbook-originated task has different provenance from a forge-issue task -- open, part of archie-core-t2db.6.
  • 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.