diff --git a/.beads/interactions.jsonl b/.beads/interactions.jsonl index 31dd675a7..51f465436 100644 --- a/.beads/interactions.jsonl +++ b/.beads/interactions.jsonl @@ -24,3 +24,5 @@ {"id":"int-0e6d7b43d42215a9a41b1736f4b049d7","kind":"field_change","created_at":"2026-08-20T12:57:02.748858938Z","actor":"Sam Catlow","issue_id":"archie-core-1786637501009-424-5b8332dd","extra":{"field":"status","new_value":"in_progress","old_value":"open"}} {"id":"int-dec9f9d1307c51147ea510842ef80d1a","kind":"field_change","created_at":"2026-08-20T13:02:18.330112565Z","actor":"Sam Catlow","issue_id":"archie-core-1786637501009-424-5b8332dd","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Fixed in fix/label-dispatch-empty-label (31efdcf): pollIssuesWithConfig/pollEitherWithConfig now refuse the label poll when cfg.Label is empty, and validateDispatch rejects the misconfiguration at load time. Adversarially reviewed; one weak test strengthened to actually verify assignee matches survive."}} {"id":"int-c00194f10222de956f7ad8987d09a9fb","kind":"field_change","created_at":"2026-08-20T13:24:15.962276702Z","actor":"Sam Catlow","issue_id":"archie-core-1786637500602-410-7a461d4d","extra":{"field":"status","new_value":"closed","old_value":"open","reason":"Already delivered as a compiled-in engine, not a plugin. internal/secret/bws.go implements secret.Engine and shells out to the bws CLI via os/exec (commit 3ae59c9, 2026-07-31); NewRegistry/DefaultRegistry register it under the name \"bws\" alongside \"env\". It is documented in config.example.toml and ARCHITECTURE.md:208, and config.example.toml:64 uses it as the worked example. Shipping a second yaegi implementation under examples/secret-engines/ would register the same name \"bws\", and Registry.Register is last-write-wins over LoadDir, so the plugin would silently shadow the compiled-in engine -- two authoritative paths for one behaviour, which the architecture contract prohibits. Reopen only if the intent is to REPLACE the compiled-in engine with a plugin (which would also need bws removed from NewRegistry and the docs updated)."}} +{"id":"int-907fab8ee9218dfc52e1b312ccdde513","kind":"field_change","created_at":"2026-08-21T15:00:54.642569071Z","actor":"Sam Catlow","issue_id":"archie-core-7d5u.1","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Decided and documented in docs/prds/event-sources-and-reactions.md, satisfying this bead's own acceptance criterion (a one-page decision naming the packages it touches and stating whether plugins-and-extensions.md needs amending -- it does not).\n\nAnswers: (1) in-process typed families, no out-of-process dispatch -- archie has no existing extension-process boundary and neither epic's stated payoff needs one. (2) Reaction delivery reuses internal/eventbus's Publisher/Consumer contract (PublishUnique + Ack/Nak already provide at-least-once with dedup), but NOT the existing nats.Client as-is: it hardcodes Retention: jetstream.WorkQueuePolicy (client.go:65) for the competing-consumer ARCHIE_TASKS stream, which silently starves a second consumer on overlapping subjects per CLAUDE.md's documented trap -- reactions need fan-out, so retention needs to become a Config field and reactions get their own stream. (3) Reactions in these two epics are producer-only (cheap wake via curator's WakeOnPrimaryInput pattern, or produce real work via the existing pollNATS->publishTask path) -- no veto/mutate-in-flight-work capability is being built here; that belongs to archie-core-h019 if it's ever needed. (4) No single generic Source interface -- forge intake reuses workintake.TaskEnvelope unchanged (its IdempotencyKey is already keyed on owner/repo/number, not delivery source, so a webhook-sourced envelope naturally dedups against a poll-discovered one for free); chat webhook stays internal/channels/webhook, unmodified; what's genuinely new and shared is a small cross-cutting package for HMAC/rate-limit/approval/capture mechanics, owned by neither domain."}} +{"id":"int-15527c6640daf7df72a4876d8e82864c","kind":"field_change","created_at":"2026-08-21T15:26:01.152938969Z","actor":"Sam Catlow","issue_id":"archie-core-7d5u.3","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Built internal/webhookguard: VerifyHMAC (behavior-preserving extraction from internal/channels/webhook, which now calls it instead of keeping a private copy), RateLimiter (per-source token bucket, independent budgets, observable rejection), RedactPayload (key-name heuristic matching gateway/stream.go's marker list, but -- deliberately unlike that function -- redacts only values under sensitive keys and leaves ordinary strings/numbers/bools untouched, since a captured payload exists to be inspected for field mapping in t2db.3).\n\nAll four acceptance criteria met and independently confirmed by a fresh adversarial review with zero surviving findings: HMAC extraction is byte-for-byte behavior-preserving (diffed against the deleted function); rate limiter hand-traced correct on two scenarios plus race-clean under -race; redaction's divergence from gateway/stream.go verified by reading both functions side by side; zero non-stdlib imports confirmed by grep. The reviewer also mutation-tested both the redaction and rate-limit guards (disabled each in turn) and confirmed the test suite catches both, then reverted and re-verified go test -race and git status were clean.\n\ntask check exit 0, golangci-lint 0 issues (one forcetypeassert finding was caught and fixed properly during build, not suppressed), gofumpt clean. All 10 pre-existing internal/channels/webhook tests pass unmodified; the one now-redundant unit test was removed with a comment pointing to where its coverage relocated."}} diff --git a/.beads/issues.jsonl b/.beads/issues.jsonl index 90df216ab..363795bf5 100644 --- a/.beads/issues.jsonl +++ b/.beads/issues.jsonl @@ -1,14 +1,14 @@ -{"_type":"issue","id":"archie-core-t2db.5","title":"Security: an unauthenticated endpoint must not be able to run an agent","description":"P0 within this epic because the feature's own pitch is the threat model: a public intake surface whose output is an agent with tool access and a repo. Get this wrong and a webhook URL is remote code execution with extra steps.\n\nNon-negotiables to design:\n\n- Per-source authentication. A source registers with a secret (HMAC, as internal/channels/webhook already does per route) before its events can trigger anything. Capture-only for unknown senders is acceptable; triggering is not.\n- Human approval before a binding goes live. An operator authoring a binding is a deliberate act; an event arriving is not. Nothing should self-arm.\n- Rate and volume limits per source, so capture cannot be used to exhaust disk or drown the inspector.\n- Payload content is untrusted input flowing into an agent prompt. Treat prompt injection as expected, not exceptional -- the sender controls that text, and the agent has tools. Bound what a playbook-triggered workflow may do.\n- Captured payloads may contain secrets from the sending system. Decide retention, redaction and who can view them; internal/memory/scrubber may already have applicable prior art.\n\nArchie's own principle applies: environmental enforcement over prompt rules. 'The agent should ignore instructions in the payload' is not a control.","acceptance_criteria":"An event from an unauthenticated source can be captured but cannot trigger a workflow; a new binding requires explicit human approval before it arms; per-source rate limits exist; the blast radius of a playbook-triggered workflow is bounded by code rather than by prompt text; retention and visibility of captured payloads is decided and documented.","status":"open","priority":0,"issue_type":"feature","owner":"sam@catlow.tech","created_at":"2026-08-21T13:45:46Z","created_by":"Sam Catlow","updated_at":"2026-08-21T13:45:46Z","dependencies":[{"issue_id":"archie-core-t2db.5","depends_on_id":"archie-core-t2db","type":"parent-child","created_at":"2026-08-21T23:45:45Z","created_by":"Sam Catlow","metadata":"{}"}],"dependency_count":0,"dependent_count":1,"comment_count":0} -{"_type":"issue","id":"archie-core-t2db.4","title":"Playbook binding: matcher + mapping + workflow, editable at runtime","description":"The object that ties it together. A binding is: a matcher (which inbound events does this apply to), a mapping (which fields the workflow receives), and a target agentic workflow.\n\nRuntime-editable is the whole point -- creating or changing a binding must not require a redeploy or a daemon restart. That has real consequences the design must face:\n\n- Bindings are persisted state, not config. They live in the store, not config.toml, because operators create them from the UI while the daemon runs.\n- They need versioning. A binding that starts a task should record WHICH version ran, or a later edit makes historical task provenance a lie.\n- Matcher ambiguity needs a defined resolution: two bindings matching one event either both run, or the more specific wins, or it is an error. Pick one and say so.\n- A binding referencing a workflow that no longer exists must fail visibly at bind time, not at 3am when the event arrives.","acceptance_criteria":"A binding can be created, edited and disabled from the UI while the daemon runs; a task records the binding version that started it; overlapping matchers resolve by a defined and documented rule; a binding naming a missing workflow is rejected when saved.","status":"open","priority":1,"issue_type":"feature","owner":"sam@catlow.tech","created_at":"2026-08-21T13:45:45Z","created_by":"Sam Catlow","updated_at":"2026-08-21T13:45:45Z","dependencies":[{"issue_id":"archie-core-t2db.4","depends_on_id":"archie-core-t2db.5","type":"blocks","created_at":"2026-08-21T23:45:53Z","created_by":"Sam Catlow","metadata":"{}"},{"issue_id":"archie-core-t2db.4","depends_on_id":"archie-core-t2db.3","type":"blocks","created_at":"2026-08-21T23:45:53Z","created_by":"Sam Catlow","metadata":"{}"},{"issue_id":"archie-core-t2db.4","depends_on_id":"archie-core-t2db","type":"parent-child","created_at":"2026-08-21T23:45:45Z","created_by":"Sam Catlow","metadata":"{}"}],"dependency_count":2,"dependent_count":1,"comment_count":0} -{"_type":"issue","id":"archie-core-t2db.1","title":"Capture inbound events archie does not yet understand","description":"The precondition for everything else. Today an unrecognised inbound request is rejected; for schema-by-example it must be RECORDED, because you cannot map a payload you have never seen.\n\nAccept, store and retain inbound events with no binding: raw body, headers, source, arrival time, and the identity that sent it. Retention must be bounded -- an open capture endpoint is an unbounded disk write, and this is exactly the kind of surface an attacker fills.\n\nStrong argument for NATS JetStream as the store rather than the in-process events.Bus: durable, replayable, retention-bounded natively, already deployed. Note the constraint though -- internal/infrastructure/eventbus/nats/doc.go states 'when no NATS URL is configured the daemon uses its local SQLite claim flow instead; nothing here is required for single-process operation'. NATS is currently OPTIONAL. Decide deliberately whether capture requires it (making this feature unavailable in single-process deployments) or degrades to SQLite, and record which -- do not let it become a hard dependency by accident.","acceptance_criteria":"An unbound webhook POST is captured and visible rather than rejected; capture is retention-bounded with a documented limit; the single-process (no NATS) behaviour is a deliberate, recorded decision; capture cannot exhaust disk.","status":"open","priority":1,"issue_type":"feature","owner":"sam@catlow.tech","created_at":"2026-08-21T13:45:18Z","created_by":"Sam Catlow","updated_at":"2026-08-21T13:45:18Z","dependencies":[{"issue_id":"archie-core-t2db.1","depends_on_id":"archie-core-7d5u.4","type":"blocks","created_at":"2026-08-21T23:45:54Z","created_by":"Sam Catlow","metadata":"{}"},{"issue_id":"archie-core-t2db.1","depends_on_id":"archie-core-t2db","type":"parent-child","created_at":"2026-08-21T23:45:17Z","created_by":"Sam Catlow","metadata":"{}"}],"dependency_count":1,"dependent_count":2,"comment_count":0} +{"_type":"issue","id":"archie-core-t2db.5","title":"Security: an unauthenticated endpoint must not be able to run an agent","description":"P0 within this epic because the feature's own pitch is the threat model: a public intake surface whose output is an agent with tool access and a repo. Get this wrong and a webhook URL is remote code execution with extra steps.\n\nNon-negotiables to design:\n\n- Per-source authentication. A source registers with a secret (HMAC, as internal/channels/webhook already does per route) before its events can trigger anything. Capture-only for unknown senders is acceptable; triggering is not.\n- Human approval before a binding goes live. An operator authoring a binding is a deliberate act; an event arriving is not. Nothing should self-arm.\n- Rate and volume limits per source, so capture cannot be used to exhaust disk or drown the inspector.\n- Payload content is untrusted input flowing into an agent prompt. Treat prompt injection as expected, not exceptional -- the sender controls that text, and the agent has tools. Bound what a playbook-triggered workflow may do.\n- Captured payloads may contain secrets from the sending system. Decide retention, redaction and who can view them; internal/memory/scrubber may already have applicable prior art.\n\nArchie's own principle applies: environmental enforcement over prompt rules. 'The agent should ignore instructions in the payload' is not a control.","acceptance_criteria":"An event from an unauthenticated source can be captured but cannot trigger a workflow; a new binding requires explicit human approval before it arms; per-source rate limits exist; the blast radius of a playbook-triggered workflow is bounded by code rather than by prompt text; retention and visibility of captured payloads is decided and documented.","notes":"2026-08-22: security design decided and documented in docs/prds/webhook-intake-security.md, covering all five non-negotiables from this bead's description:\n1. Per-source auth reuses internal/channels/webhook's existing HMAC-SHA256 scheme; capture accepts unsigned events (visible, marked unauthenticated), only authenticated events can ever match a binding.\n2. Bindings gain a draft -\u003e pending_approval -\u003e armed state machine; any edit to an armed binding drops it back to pending_approval so approval can't be bypassed by editing. Modeled on telegram's existing dangerousAction/pendingApproval flow (dangerous.go/approval.go).\n3. Per-source token-bucket rate limiting (precedent: pairing/store.go's MaxPendingPerPlatform); limit-exceeded is an observable 429, not a silent drop.\n4. Blast radius bounded by the SAME code-level controls every task already gets -- gate, diff_cap_lines, sandboxed container, worktree isolation -- no new relaxation for playbook-triggered work, and payload text is ordinary untrusted prompt input, never a trusted instruction.\n5. 7-day configurable retention on captured payloads; best-effort redaction reusing gateway/stream.go's sensitiveParameterKey heuristic before persisting; visibility gated by the same dashboard auth as every other webui surface.\n\nThis bead's code-level acceptance criteria (capture-can't-trigger, rate limits exist, blast-radius bounded, approval gate) cannot be implemented yet: they constrain t2db.1 (capture), 7d5u.3 (intake family) and t2db.4 (binding), none of which have landed. This document is the contract those beads build against -- do not build any of them without satisfying it. Leaving this bead in_progress rather than closing it; it closes when t2db.1/7d5u.3/t2db.4 land and demonstrably satisfy points 1-5, not before.","status":"in_progress","priority":0,"issue_type":"feature","assignee":"Sam Catlow","owner":"sam@catlow.tech","created_at":"2026-08-21T13:45:46Z","created_by":"Sam Catlow","updated_at":"2026-08-21T14:53:33Z","started_at":"2026-08-21T14:51:26Z","dependencies":[{"issue_id":"archie-core-t2db.5","depends_on_id":"archie-core-t2db","type":"parent-child","created_at":"2026-08-21T23:45:45Z","created_by":"Sam Catlow","metadata":"{}"}],"dependency_count":0,"dependent_count":1,"comment_count":0} +{"_type":"issue","id":"archie-core-t2db.4","title":"Playbook binding: matcher + mapping + workflow, editable at runtime","description":"The object that ties it together. A binding is: a matcher (which inbound events does this apply to), a mapping (which fields the workflow receives), and a target agentic workflow.\n\nRuntime-editable is the whole point -- creating or changing a binding must not require a redeploy or a daemon restart. That has real consequences the design must face:\n\n- Bindings are persisted state, not config. They live in the store, not config.toml, because operators create them from the UI while the daemon runs.\n- They need versioning. A binding that starts a task should record WHICH version ran, or a later edit makes historical task provenance a lie.\n- Matcher ambiguity needs a defined resolution: two bindings matching one event either both run, or the more specific wins, or it is an error. Pick one and say so.\n- A binding referencing a workflow that no longer exists must fail visibly at bind time, not at 3am when the event arrives.","acceptance_criteria":"A binding can be created, edited and disabled from the UI while the daemon runs; a task records the binding version that started it; overlapping matchers resolve by a defined and documented rule; a binding naming a missing workflow is rejected when saved.","notes":"2026-08-22: the draft -\u003e pending_approval -\u003e armed state machine from t2db.5's decision belongs to the binding entity this bead defines, not to a shared package -- 7d5u.3 was narrowed to exclude it since there is exactly one consumer today. Implement the state transitions here.","status":"open","priority":1,"issue_type":"feature","owner":"sam@catlow.tech","created_at":"2026-08-21T13:45:45Z","created_by":"Sam Catlow","updated_at":"2026-08-21T15:19:05Z","dependencies":[{"issue_id":"archie-core-t2db.4","depends_on_id":"archie-core-t2db.5","type":"blocks","created_at":"2026-08-21T23:45:53Z","created_by":"Sam Catlow","metadata":"{}"},{"issue_id":"archie-core-t2db.4","depends_on_id":"archie-core-t2db.3","type":"blocks","created_at":"2026-08-21T23:45:53Z","created_by":"Sam Catlow","metadata":"{}"},{"issue_id":"archie-core-t2db.4","depends_on_id":"archie-core-t2db","type":"parent-child","created_at":"2026-08-21T23:45:45Z","created_by":"Sam Catlow","metadata":"{}"}],"dependency_count":2,"dependent_count":1,"comment_count":0} +{"_type":"issue","id":"archie-core-t2db.1","title":"Capture inbound events archie does not yet understand","description":"The precondition for everything else. Today an unrecognised inbound request is rejected; for schema-by-example it must be RECORDED, because you cannot map a payload you have never seen.\n\nAccept, store and retain inbound events with no binding: raw body, headers, source, arrival time, and the identity that sent it. Retention must be bounded -- an open capture endpoint is an unbounded disk write, and this is exactly the kind of surface an attacker fills.\n\nStrong argument for NATS JetStream as the store rather than the in-process events.Bus: durable, replayable, retention-bounded natively, already deployed. Note the constraint though -- internal/infrastructure/eventbus/nats/doc.go states 'when no NATS URL is configured the daemon uses its local SQLite claim flow instead; nothing here is required for single-process operation'. NATS is currently OPTIONAL. Decide deliberately whether capture requires it (making this feature unavailable in single-process deployments) or degrades to SQLite, and record which -- do not let it become a hard dependency by accident.","acceptance_criteria":"An unbound webhook POST is captured and visible rather than rejected; capture is retention-bounded with a documented limit; the single-process (no NATS) behaviour is a deliberate, recorded decision; capture cannot exhaust disk.","notes":"2026-08-22: capture-storage ownership confirmed here (not in 7d5u.3, which was narrowed to storage-agnostic HMAC/rate-limit/redaction mechanics only). This bead's capture path should call webhookguard's redaction before persisting and its rate limiter at the HTTP boundary, but owns its own storage engine and the NATS-vs-SQLite decision.","status":"open","priority":1,"issue_type":"feature","owner":"sam@catlow.tech","created_at":"2026-08-21T13:45:18Z","created_by":"Sam Catlow","updated_at":"2026-08-21T15:19:05Z","dependencies":[{"issue_id":"archie-core-t2db.1","depends_on_id":"archie-core-7d5u.4","type":"relates-to","created_at":"2026-08-22T01:01:02Z","created_by":"Sam Catlow","metadata":"{}"},{"issue_id":"archie-core-t2db.1","depends_on_id":"archie-core-t2db","type":"parent-child","created_at":"2026-08-21T23:45:17Z","created_by":"Sam Catlow","metadata":"{}"}],"dependency_count":0,"dependent_count":2,"comment_count":0} {"_type":"issue","id":"archie-core-t2db.2","title":"Event inspector: see real inbound payloads in the dashboard","description":"The operator-facing half of capture. A live view of recent inbound events: source, arrival time, and the actual payload, pretty-printed and explorable.\n\nThis is the screen that makes the feature feel like magic: you hit 'send test webhook' in the other app, alt-tab to archie, and the event is sitting there. Latency from arrival to visible matters more than it looks -- it is the difference between a design loop and a guessing game.\n\nShow unbound events prominently. An event nothing is listening to is not noise here, it is the queue of integrations waiting to be built.","acceptance_criteria":"Recent inbound events are listed with source, time and full payload; unbound events are distinguishable from bound ones; a newly arrived event appears without a manual refresh; payloads are explorable rather than a wall of text.","status":"open","priority":1,"issue_type":"feature","owner":"sam@catlow.tech","created_at":"2026-08-21T13:45:18Z","created_by":"Sam Catlow","updated_at":"2026-08-21T13:45:18Z","dependencies":[{"issue_id":"archie-core-t2db.2","depends_on_id":"archie-core-t2db.1","type":"blocks","created_at":"2026-08-21T23:45:53Z","created_by":"Sam Catlow","metadata":"{}"},{"issue_id":"archie-core-t2db.2","depends_on_id":"archie-core-t2db","type":"parent-child","created_at":"2026-08-21T23:45:17Z","created_by":"Sam Catlow","metadata":"{}"}],"dependency_count":1,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"archie-core-t2db.3","title":"Map payload fields by example, from a real captured event","description":"Pick a captured event, click through its payload, and bind JSON paths to named fields the workflow will receive. Schema by example, not schema by specification.\n\nThe hard part is not the happy path, it is drift. A mapping authored against one payload will eventually meet a payload where the path is missing, null, or a different type -- the sending app shipped a change nobody told you about. That must fail LOUDLY and land somewhere the operator sees, not silently pass an empty string into an agent prompt. An agent handed a blank field will confabulate around it, which turns a schema change into an agent doing confident nonsense in a repo.\n\nSupport a preview: given this mapping and this captured event, show exactly what the workflow would receive. Never ship a mapping the operator has not seen resolve against real data.","acceptance_criteria":"Fields are mappable from a captured payload without writing code; a mapping preview resolves against a real event before saving; a missing, null or type-changed path at runtime produces a visible failure rather than an empty value; the failure names the path and the event.","status":"open","priority":1,"issue_type":"feature","owner":"sam@catlow.tech","created_at":"2026-08-21T13:45:18Z","created_by":"Sam Catlow","updated_at":"2026-08-21T13:45:18Z","dependencies":[{"issue_id":"archie-core-t2db.3","depends_on_id":"archie-core-t2db","type":"parent-child","created_at":"2026-08-21T23:45:18Z","created_by":"Sam Catlow","metadata":"{}"},{"issue_id":"archie-core-t2db.3","depends_on_id":"archie-core-t2db.1","type":"blocks","created_at":"2026-08-21T23:45:53Z","created_by":"Sam Catlow","metadata":"{}"}],"dependency_count":1,"dependent_count":1,"comment_count":0} {"_type":"issue","id":"archie-core-t2db","title":"[EPIC] Event capture and no-code playbooks: turn any inbound webhook into an agentic workflow","description":"The pitch, in the operator's words: point any app's outgoing webhook at archie, open archie, SEE the event that just arrived with its real payload, map the fields you care about, bind them to an agentic workflow, save. No code change, no redeploy, no restart. Adding a new integration stops being a development task.\n\nWhy this is different from n8n or Power Automate rather than a copy of them: their terminal node is a deterministic connector. Archie's is an AGENT with a repo, a worktree, tools and a gate. 'When Sentry reports a new issue in this project, open a PR that fixes it' is one binding here and an entire product elsewhere.\n\nThe design insight that makes it buildable: you cannot write a payload mapper against a payload you have not seen. Schema-by-example requires real recent events to map against, which means archie must CAPTURE events it does not yet understand -- including ones with no binding at all -- and retain them long enough to design against. That is also the strongest argument for putting inbound events on NATS JetStream rather than the lossy in-process bus: durable, replayable, retention-bounded, and already deployed. The capture requirement and the transport choice are the same decision.\n\nSequence: capture unrecognised events -\u003e inspect real payloads in the UI -\u003e map fields by example -\u003e bind matcher+mapping to a workflow -\u003e the next matching event runs it.\n\nThis is a public, unauthenticated-by-default intake surface whose output is an agent with tool access. Security is not a later hardening pass; it is a first-class child of this epic.","acceptance_criteria":"An operator can point a new external webhook at archie, see its payload in the UI without writing code, map fields, bind it to a workflow, and have the next matching event run that workflow -- with no redeploy and no daemon restart. A binding cannot go live without explicit human approval.","status":"open","priority":1,"issue_type":"epic","owner":"sam@catlow.tech","created_at":"2026-08-21T13:44:56Z","created_by":"Sam Catlow","updated_at":"2026-08-21T13:44:56Z","dependency_count":0,"dependent_count":0,"comment_count":0} -{"_type":"issue","id":"archie-core-7d5u.4","title":"GitHub forge webhook receiver behind a feature flag","description":"The concrete autonomy win: react to an issue being assigned or labelled the moment it happens, instead of up to poll_interval (default 60s) later.\n\nVerified absent on 2026-08-21: internal/forge/ and internal/daemon/ contain zero webhook references, and no bead tracked forge-event intake before this epic. internal/channels/webhook exists but is a CHAT channel -- it routes inbound text through gateway.Router for LLM processing, a peer of Telegram and email. It is not forge intake and should not be bent into it.\n\nShip as a source in the typed intake family, off by default: [forge] intake = 'poll' (default) | 'webhook' | 'both'. Verify GitHub's HMAC signature. Reuse the label/assignee dispatch predicate the poller already uses -- do NOT reimplement it, since it just took a fix (3209a1f, refusing to poll on an empty label match) and two implementations will drift.\n\nDeployment reality from CLAUDE.md: archied may run on a host, in a container, or behind no public ingress at all. A webhook receiver that assumes a reachable public URL will not fit every profile, which is exactly why polling has to remain a first-class option rather than a legacy fallback.","acceptance_criteria":"With intake='webhook', a labelled issue starts a task without waiting for the poll interval; an invalid HMAC is rejected and logged; intake='poll' behaves exactly as today; the dispatch predicate is shared with the poller, not duplicated; the flag defaults to poll.","status":"open","priority":1,"issue_type":"feature","owner":"sam@catlow.tech","created_at":"2026-08-21T13:26:52Z","created_by":"Sam Catlow","updated_at":"2026-08-21T13:26:52Z","dependencies":[{"issue_id":"archie-core-7d5u.4","depends_on_id":"archie-core-7d5u","type":"parent-child","created_at":"2026-08-21T23:26:51Z","created_by":"Sam Catlow","metadata":"{}"},{"issue_id":"archie-core-7d5u.4","depends_on_id":"archie-core-7d5u.1","type":"blocks","created_at":"2026-08-21T23:26:58Z","created_by":"Sam Catlow","metadata":"{}"},{"issue_id":"archie-core-7d5u.4","depends_on_id":"archie-core-7d5u.3","type":"blocks","created_at":"2026-08-21T23:26:58Z","created_by":"Sam Catlow","metadata":"{}"}],"dependency_count":2,"dependent_count":3,"comment_count":0} +{"_type":"issue","id":"archie-core-7d5u.4","title":"GitHub forge webhook receiver behind a feature flag","description":"The concrete autonomy win: react to an issue being assigned or labelled the moment it happens, instead of up to poll_interval (default 60s) later.\n\nVerified absent on 2026-08-21: internal/forge/ and internal/daemon/ contain zero webhook references, and no bead tracked forge-event intake before this epic. internal/channels/webhook exists but is a CHAT channel -- it routes inbound text through gateway.Router for LLM processing, a peer of Telegram and email. It is not forge intake and should not be bent into it.\n\nShip as a source in the typed intake family, off by default: [forge] intake = 'poll' (default) | 'webhook' | 'both'. Verify GitHub's HMAC signature. Reuse the label/assignee dispatch predicate the poller already uses -- do NOT reimplement it, since it just took a fix (3209a1f, refusing to poll on an empty label match) and two implementations will drift.\n\nDeployment reality from CLAUDE.md: archied may run on a host, in a container, or behind no public ingress at all. A webhook receiver that assumes a reachable public URL will not fit every profile, which is exactly why polling has to remain a first-class option rather than a legacy fallback.","acceptance_criteria":"With intake='webhook', a labelled issue starts a task without waiting for the poll interval; an invalid HMAC is rejected and logged; intake='poll' behaves exactly as today; the dispatch predicate is shared with the poller, not duplicated; the flag defaults to poll.","status":"open","priority":1,"issue_type":"feature","owner":"sam@catlow.tech","created_at":"2026-08-21T13:26:52Z","created_by":"Sam Catlow","updated_at":"2026-08-21T13:26:52Z","dependencies":[{"issue_id":"archie-core-7d5u.4","depends_on_id":"archie-core-7d5u","type":"parent-child","created_at":"2026-08-21T23:26:51Z","created_by":"Sam Catlow","metadata":"{}"},{"issue_id":"archie-core-7d5u.4","depends_on_id":"archie-core-t2db.1","type":"relates-to","created_at":"2026-08-22T01:01:02Z","created_by":"Sam Catlow","metadata":"{}"},{"issue_id":"archie-core-7d5u.4","depends_on_id":"archie-core-7d5u.1","type":"blocks","created_at":"2026-08-21T23:26:58Z","created_by":"Sam Catlow","metadata":"{}"},{"issue_id":"archie-core-7d5u.4","depends_on_id":"archie-core-7d5u.3","type":"blocks","created_at":"2026-08-21T23:26:58Z","created_by":"Sam Catlow","metadata":"{}"}],"dependency_count":2,"dependent_count":2,"comment_count":0} {"_type":"issue","id":"archie-core-7d5u.5","title":"Idempotency and poll/webhook parity: never double-dispatch, never lose work","description":"Webhooks deliver at-least-once, out of order, and sometimes not at all. Polling is the opposite: slow but eventually consistent. Running both (intake='both') is the honest production configuration, and it is also where the two failure modes meet.\n\nTwo things must hold. A single issue event must not start two tasks because the webhook and the next poll both saw it. And a webhook outage must not silently stop work -- if the receiver is wedged or the ingress is down, polling has to pick the work up, which is the entire argument for keeping it.\n\nNote archie-core-...-286 (WebhookAdapter: idempotency cache) already exists for the chat adapter. Decide whether that mechanism generalises to intake or whether forge dispatch needs its own key; do not build a second one by accident.\n\nThe silent-failure shape to design against is the one this codebase keeps hitting: a path that looks like it is working because nothing errors. A webhook receiver that has silently stopped delivering looks identical to a repo with no activity.","acceptance_criteria":"A duplicate delivery of the same forge event starts exactly one task; with intake='both', disabling the webhook path still results in the work being picked up by polling; a wedged or non-delivering webhook receiver is observable rather than indistinguishable from an idle repo.","status":"open","priority":1,"issue_type":"feature","owner":"sam@catlow.tech","created_at":"2026-08-21T13:26:52Z","created_by":"Sam Catlow","updated_at":"2026-08-21T13:26:52Z","dependencies":[{"issue_id":"archie-core-7d5u.5","depends_on_id":"archie-core-7d5u","type":"parent-child","created_at":"2026-08-21T23:26:51Z","created_by":"Sam Catlow","metadata":"{}"},{"issue_id":"archie-core-7d5u.5","depends_on_id":"archie-core-7d5u.1","type":"blocks","created_at":"2026-08-21T23:26:58Z","created_by":"Sam Catlow","metadata":"{}"},{"issue_id":"archie-core-7d5u.5","depends_on_id":"archie-core-7d5u.4","type":"blocks","created_at":"2026-08-21T23:26:58Z","created_by":"Sam Catlow","metadata":"{}"},{"issue_id":"archie-core-7d5u.5","depends_on_id":"archie-core-1786637497328-286-9c985f28","type":"relates-to","created_at":"2026-08-21T23:27:06Z","created_by":"Sam Catlow","metadata":"{}"}],"dependency_count":2,"dependent_count":0,"comment_count":0} -{"_type":"issue","id":"archie-core-7d5u.1","title":"Design: event sources, reaction delivery, and how extensions hook them","description":"No settled design covers this. docs/architecture/plugins-and-extensions.md settles the PLUGIN FRAMEWORK (metadata-only contract, typed capability families, owning registries) but says nothing about event sources, reaction delivery, or intake. Under the scope-discipline rule merged as PR #533, that means design first -- one page, decisive -- then a diff.\n\nDecide and record in docs/prds/:\n\n1. THE HEADLINE QUESTION, which changes everything downstream: do extensions react in-process through typed capability families (what the approved rule mandates), or out-of-process like tau's generic DispatchEvent? If out-of-process generic dispatch is genuinely wanted, docs/architecture/plugins-and-extensions.md is an APPROVED document and must be amended first -- CLAUDE.md's organisation rule is explicit that you change the doc before the rule it states. Do not quietly work around it.\n\n2. Reaction delivery. events.Bus drops on overflow by design and must stay that way for the dashboard. Decide whether reactions get a second in-process bus with at-least-once delivery, or ride the existing NATS eventbus (internal/infrastructure/eventbus), which already has durable semantics and the work-queue traps documented in CLAUDE.md.\n\n3. Whether a reaction may INFLUENCE an outcome (veto, mutate, add work) or only observe. This is the difference between a hook and a subscriber, and it determines whether ordering and failure semantics matter. If a reaction can block, decide what a slow or crashed extension does -- tau's answer was a dispatch timeout, and it still deadlocked unload once.\n\n4. The typed source/intake family: its interface, its owning registry, and how a source declares what it produces.\n\nRespect dependency direction: cmd -\u003e app -\u003e {domain, infrastructure}. A domain declares the contract; app wires implementations. Cross-cutting packages may be imported by any layer and import none.","acceptance_criteria":"A one-page decision in docs/prds/ answering all four questions, naming the packages it will touch, and stating explicitly whether plugins-and-extensions.md needs amending. It decides rather than surveys.","notes":"CORRECTION 2026-08-22 (second): decision question 2 in this bead's description asked whether reactions get a second in-process bus or ride the existing NATS eventbus. That framing is wrong -- there is no 'or'. NATS is the settled transport; the only open axis is external-server vs embedded, not NATS vs something else. Do not design a second bus. See archie-core-7d5u and archie-core-7d5u.2 for the corrected framing and the verified state of github.com/nats-io/nats-server/v2 as an already-present, test-proven, production-unwired dependency.","status":"open","priority":1,"issue_type":"decision","owner":"sam@catlow.tech","created_at":"2026-08-21T13:26:26Z","created_by":"Sam Catlow","updated_at":"2026-08-21T14:28:35Z","dependencies":[{"issue_id":"archie-core-7d5u.1","depends_on_id":"archie-core-7d5u","type":"parent-child","created_at":"2026-08-21T23:26:25Z","created_by":"Sam Catlow","metadata":"{}"}],"dependency_count":0,"dependent_count":4,"comment_count":0} -{"_type":"issue","id":"archie-core-7d5u.2","title":"Reaction delivery via embedded NATS, no external server required","description":"Reactions need at-least-once delivery distinct from the lossy events.Bus (see epic description). The delivery mechanism is NATS -- that part is settled, not a design question. What's open is deployment shape.\n\nVERIFIED 2026-08-22: config.NATSConfig.URL empty currently means 'no NATS, use SQLite ClaimNext' (internal/config/config.go:573-582). That fallback was designed for task distribution working without a broker at all. It was never meant to generalise to 'archie has no NATS' as a permanent architectural stance -- the intended second deployment shape alongside an external NATS server was always NATS EMBEDDED (in-process), not a different eventbus.\n\ngithub.com/nats-io/nats-server/v2 is already a direct dependency and is proven to work in this codebase: internal/infrastructure/agenttransport/nats/transport_test.go and others already start a real embedded server via nats-server/v2/test for tests. It has just never been wired into production startup -- cmd/archied only knows 'external URL configured' vs 'fall back to SQLite'. No new library, no new bus, no architectural gap to design around: this is 'wire the dependency we already have and already test against into the daemon's own startup path.'\n\nDesign questions that remain, now correctly scoped: does an embedded NATS instance replace the SQLite fallback outright for single-process deployments, or run alongside it; what config controls embedded vs external vs disabled; does the daemon own the embedded server's lifecycle the same way it owns everything else (start/stop paired with daemon start/stop, per the shutdown-ordering rules in ARCHITECTURE.md).","acceptance_criteria":"A single-process deployment with no external NATS URL configured still gets reaction delivery via an embedded NATS instance; the daemon starts and stops the embedded server as part of its own lifecycle; no second eventbus type is introduced; internal/infrastructure/eventbus/nats is reused as the transport rather than duplicated.","status":"open","priority":1,"issue_type":"feature","owner":"sam@catlow.tech","created_at":"2026-08-21T13:26:26Z","created_by":"Sam Catlow","updated_at":"2026-08-21T14:28:25Z","dependencies":[{"issue_id":"archie-core-7d5u.2","depends_on_id":"archie-core-7d5u.1","type":"blocks","created_at":"2026-08-21T23:26:57Z","created_by":"Sam Catlow","metadata":"{}"},{"issue_id":"archie-core-7d5u.2","depends_on_id":"archie-core-7d5u","type":"parent-child","created_at":"2026-08-21T23:26:26Z","created_by":"Sam Catlow","metadata":"{}"}],"dependency_count":1,"dependent_count":0,"comment_count":0} -{"_type":"issue","id":"archie-core-7d5u.3","title":"Typed intake family: one registry for every kind of inbound caller","description":"Today each inbound path is wired bespoke. internal/channels/webhook is an HTTP server with per-route HMAC that routes text into gateway.Router for LLM processing; forge work arrives only by polling; cron is tracked separately (archie-core-...-249). Nothing gives them a common shape, so every new caller means new wiring in the composition root.\n\nIntroduce the typed source/intake capability family from the design: an interface a source implements, an owning registry that registers and returns the source type (the shape internal/plugin/architecture_test.go already enforces for engine families), and a declaration of what each source produces.\n\nThis is the 'align webhooks to types of callers' idea made concrete. A forge webhook, a chat webhook, a cron tick and a channel message are all sources; what differs is what they produce, not how they are wired.\n\nExisting webhook adapter work (archie-core-...-275 and children: HMAC server, declarative filters, prompt templates, script transforms, idempotency cache) should be reconciled with this family rather than duplicated -- check those beads before building.","acceptance_criteria":"A source registry exists with a typed contract and family owner; at least two sources are registered through it; adding a source requires no bespoke composition-root wiring; internal/plugin/architecture_test.go still passes.","status":"open","priority":1,"issue_type":"feature","owner":"sam@catlow.tech","created_at":"2026-08-21T13:26:26Z","created_by":"Sam Catlow","updated_at":"2026-08-21T13:26:26Z","dependencies":[{"issue_id":"archie-core-7d5u.3","depends_on_id":"archie-core-1786637497036-275-8838629e","type":"relates-to","created_at":"2026-08-21T23:27:06Z","created_by":"Sam Catlow","metadata":"{}"},{"issue_id":"archie-core-7d5u.3","depends_on_id":"archie-core-7d5u","type":"parent-child","created_at":"2026-08-21T23:26:26Z","created_by":"Sam Catlow","metadata":"{}"},{"issue_id":"archie-core-7d5u.3","depends_on_id":"archie-core-7d5u.1","type":"blocks","created_at":"2026-08-21T23:26:58Z","created_by":"Sam Catlow","metadata":"{}"}],"dependency_count":1,"dependent_count":1,"comment_count":0} +{"_type":"issue","id":"archie-core-7d5u.1","title":"Design: event sources, reaction delivery, and how extensions hook them","description":"No settled design covers this. docs/architecture/plugins-and-extensions.md settles the PLUGIN FRAMEWORK (metadata-only contract, typed capability families, owning registries) but says nothing about event sources, reaction delivery, or intake. Under the scope-discipline rule merged as PR #533, that means design first -- one page, decisive -- then a diff.\n\nDecide and record in docs/prds/:\n\n1. THE HEADLINE QUESTION, which changes everything downstream: do extensions react in-process through typed capability families (what the approved rule mandates), or out-of-process like tau's generic DispatchEvent? If out-of-process generic dispatch is genuinely wanted, docs/architecture/plugins-and-extensions.md is an APPROVED document and must be amended first -- CLAUDE.md's organisation rule is explicit that you change the doc before the rule it states. Do not quietly work around it.\n\n2. Reaction delivery. events.Bus drops on overflow by design and must stay that way for the dashboard. Decide whether reactions get a second in-process bus with at-least-once delivery, or ride the existing NATS eventbus (internal/infrastructure/eventbus), which already has durable semantics and the work-queue traps documented in CLAUDE.md.\n\n3. Whether a reaction may INFLUENCE an outcome (veto, mutate, add work) or only observe. This is the difference between a hook and a subscriber, and it determines whether ordering and failure semantics matter. If a reaction can block, decide what a slow or crashed extension does -- tau's answer was a dispatch timeout, and it still deadlocked unload once.\n\n4. The typed source/intake family: its interface, its owning registry, and how a source declares what it produces.\n\nRespect dependency direction: cmd -\u003e app -\u003e {domain, infrastructure}. A domain declares the contract; app wires implementations. Cross-cutting packages may be imported by any layer and import none.","acceptance_criteria":"A one-page decision in docs/prds/ answering all four questions, naming the packages it will touch, and stating explicitly whether plugins-and-extensions.md needs amending. It decides rather than surveys.","notes":"CORRECTION 2026-08-22 (second): decision question 2 in this bead's description asked whether reactions get a second in-process bus or ride the existing NATS eventbus. That framing is wrong -- there is no 'or'. NATS is the settled transport; the only open axis is external-server vs embedded, not NATS vs something else. Do not design a second bus. See archie-core-7d5u and archie-core-7d5u.2 for the corrected framing and the verified state of github.com/nats-io/nats-server/v2 as an already-present, test-proven, production-unwired dependency.","status":"closed","priority":1,"issue_type":"decision","assignee":"Sam Catlow","owner":"sam@catlow.tech","created_at":"2026-08-21T13:26:26Z","created_by":"Sam Catlow","updated_at":"2026-08-21T15:00:55Z","started_at":"2026-08-21T14:56:21Z","closed_at":"2026-08-21T15:00:55Z","close_reason":"Decided and documented in docs/prds/event-sources-and-reactions.md, satisfying this bead's own acceptance criterion (a one-page decision naming the packages it touches and stating whether plugins-and-extensions.md needs amending -- it does not).\n\nAnswers: (1) in-process typed families, no out-of-process dispatch -- archie has no existing extension-process boundary and neither epic's stated payoff needs one. (2) Reaction delivery reuses internal/eventbus's Publisher/Consumer contract (PublishUnique + Ack/Nak already provide at-least-once with dedup), but NOT the existing nats.Client as-is: it hardcodes Retention: jetstream.WorkQueuePolicy (client.go:65) for the competing-consumer ARCHIE_TASKS stream, which silently starves a second consumer on overlapping subjects per CLAUDE.md's documented trap -- reactions need fan-out, so retention needs to become a Config field and reactions get their own stream. (3) Reactions in these two epics are producer-only (cheap wake via curator's WakeOnPrimaryInput pattern, or produce real work via the existing pollNATS-\u003epublishTask path) -- no veto/mutate-in-flight-work capability is being built here; that belongs to archie-core-h019 if it's ever needed. (4) No single generic Source interface -- forge intake reuses workintake.TaskEnvelope unchanged (its IdempotencyKey is already keyed on owner/repo/number, not delivery source, so a webhook-sourced envelope naturally dedups against a poll-discovered one for free); chat webhook stays internal/channels/webhook, unmodified; what's genuinely new and shared is a small cross-cutting package for HMAC/rate-limit/approval/capture mechanics, owned by neither domain.","dependencies":[{"issue_id":"archie-core-7d5u.1","depends_on_id":"archie-core-7d5u","type":"parent-child","created_at":"2026-08-21T23:26:25Z","created_by":"Sam Catlow","metadata":"{}"}],"dependency_count":0,"dependent_count":4,"comment_count":0} +{"_type":"issue","id":"archie-core-7d5u.2","title":"Reaction delivery via embedded NATS, no external server required","description":"Reactions need at-least-once delivery distinct from the lossy events.Bus (see epic description). The delivery mechanism is NATS -- that part is settled, not a design question. What's open is deployment shape.\n\nVERIFIED 2026-08-22: config.NATSConfig.URL empty currently means 'no NATS, use SQLite ClaimNext' (internal/config/config.go:573-582). That fallback was designed for task distribution working without a broker at all. It was never meant to generalise to 'archie has no NATS' as a permanent architectural stance -- the intended second deployment shape alongside an external NATS server was always NATS EMBEDDED (in-process), not a different eventbus.\n\ngithub.com/nats-io/nats-server/v2 is already a direct dependency and is proven to work in this codebase: internal/infrastructure/agenttransport/nats/transport_test.go and others already start a real embedded server via nats-server/v2/test for tests. It has just never been wired into production startup -- cmd/archied only knows 'external URL configured' vs 'fall back to SQLite'. No new library, no new bus, no architectural gap to design around: this is 'wire the dependency we already have and already test against into the daemon's own startup path.'\n\nDesign questions that remain, now correctly scoped: does an embedded NATS instance replace the SQLite fallback outright for single-process deployments, or run alongside it; what config controls embedded vs external vs disabled; does the daemon own the embedded server's lifecycle the same way it owns everything else (start/stop paired with daemon start/stop, per the shutdown-ordering rules in ARCHITECTURE.md).","acceptance_criteria":"A single-process deployment with no external NATS URL configured still gets reaction delivery via an embedded NATS instance; the daemon starts and stops the embedded server as part of its own lifecycle; no second eventbus type is introduced; internal/infrastructure/eventbus/nats is reused as the transport rather than duplicated.","notes":"2026-08-22, from docs/prds/event-sources-and-reactions.md: do not reuse the existing nats.Client's stream creation as-is. internal/infrastructure/eventbus/nats/client.go:65 hardcodes Retention: jetstream.WorkQueuePolicy -- correct for ARCHIE_TASKS (task distribution, one consumer claims each message) and wrong for reactions, which need fan-out (every registered reaction sees every matching event). Two reactions on overlapping subjects under WorkQueuePolicy hit the exact trap CLAUDE.md documents: the second consumer silently gets nothing. Config.StreamName/Config.Subjects are already composition-supplied (config.go:30-38); Retention is not parameterized and needs to become a Config field, defaulting to today's WorkQueuePolicy so ARCHIE_TASKS is unaffected, with reactions getting a second stream under a fan-out-capable policy and their own subject namespace.","status":"open","priority":1,"issue_type":"feature","owner":"sam@catlow.tech","created_at":"2026-08-21T13:26:26Z","created_by":"Sam Catlow","updated_at":"2026-08-21T15:01:29Z","dependencies":[{"issue_id":"archie-core-7d5u.2","depends_on_id":"archie-core-7d5u.1","type":"blocks","created_at":"2026-08-21T23:26:57Z","created_by":"Sam Catlow","metadata":"{}"},{"issue_id":"archie-core-7d5u.2","depends_on_id":"archie-core-7d5u","type":"parent-child","created_at":"2026-08-21T23:26:26Z","created_by":"Sam Catlow","metadata":"{}"}],"dependency_count":1,"dependent_count":0,"comment_count":0} +{"_type":"issue","id":"archie-core-7d5u.3","title":"Shared webhook mechanics: HMAC verification, per-source rate limiting, payload redaction","description":"NARROWED 2026-08-22 from this bead's prior scope, which bundled capture-storage and an approval state machine into a single 'shared mechanics' package. On reflection those are not genuinely shared yet:\n\n- Capture STORAGE is t2db.1's job -- it depends on the NATS-vs-SQLite decision 7d5u.2 owns, and building a storage engine here would either duplicate or contradict that. This package may be USED by t2db.1's capture path, but does not own persistence.\n- The draft/pending_approval/armed state machine belongs to the entity that has that state -- t2db.4's binding -- not a generic package. There is exactly one consumer (bindings) today; per 'extract into a shared primitive on the second real consumer, never in anticipation of one,' building it here now would be speculative.\n\nWhat remains, and is genuinely storage-agnostic and reusable by any inbound HTTP source regardless of what consumes it:\n\n1. HMAC-SHA256 verification -- generalize internal/channels/webhook/webhook.go's existing unexported validateHMAC into an exported function here, and have that package call into it instead of keeping its own copy. One implementation of signature checking, not two that can drift.\n2. Per-source rate limiting -- a token bucket keyed by source ID (not global), so one noisy sender cannot exhaust another's budget. Limit-exceeded is an observable rejection, not a silent drop, per t2db.5's decision.\n3. Payload redaction -- generalize internal/gateway/stream.go's unexported sensitiveParameterKey/redactToolParameters heuristic (matches token/secret/password/passwd/api_key/apikey/authorization/credential/cookie/private_key against normalized JSON keys) into a reusable, storage-agnostic transform any capture path can apply before persisting.","acceptance_criteria":"webhookguard.VerifyHMAC replaces internal/channels/webhook's private copy with no behaviour change (its existing tests still pass); a per-source rate limiter rejects over-budget requests observably; a redaction function matches the same key heuristic already proven in gateway/stream.go; the package has zero imports of any domain, infrastructure or app package.","status":"closed","priority":1,"issue_type":"feature","assignee":"Sam Catlow","owner":"sam@catlow.tech","created_at":"2026-08-21T13:26:26Z","created_by":"Sam Catlow","updated_at":"2026-08-21T15:26:01Z","started_at":"2026-08-21T15:19:09Z","closed_at":"2026-08-21T15:26:01Z","close_reason":"Built internal/webhookguard: VerifyHMAC (behavior-preserving extraction from internal/channels/webhook, which now calls it instead of keeping a private copy), RateLimiter (per-source token bucket, independent budgets, observable rejection), RedactPayload (key-name heuristic matching gateway/stream.go's marker list, but -- deliberately unlike that function -- redacts only values under sensitive keys and leaves ordinary strings/numbers/bools untouched, since a captured payload exists to be inspected for field mapping in t2db.3).\n\nAll four acceptance criteria met and independently confirmed by a fresh adversarial review with zero surviving findings: HMAC extraction is byte-for-byte behavior-preserving (diffed against the deleted function); rate limiter hand-traced correct on two scenarios plus race-clean under -race; redaction's divergence from gateway/stream.go verified by reading both functions side by side; zero non-stdlib imports confirmed by grep. The reviewer also mutation-tested both the redaction and rate-limit guards (disabled each in turn) and confirmed the test suite catches both, then reverted and re-verified go test -race and git status were clean.\n\ntask check exit 0, golangci-lint 0 issues (one forcetypeassert finding was caught and fixed properly during build, not suppressed), gofumpt clean. All 10 pre-existing internal/channels/webhook tests pass unmodified; the one now-redundant unit test was removed with a comment pointing to where its coverage relocated.","dependencies":[{"issue_id":"archie-core-7d5u.3","depends_on_id":"archie-core-1786637497036-275-8838629e","type":"relates-to","created_at":"2026-08-21T23:27:06Z","created_by":"Sam Catlow","metadata":"{}"},{"issue_id":"archie-core-7d5u.3","depends_on_id":"archie-core-7d5u","type":"parent-child","created_at":"2026-08-21T23:26:26Z","created_by":"Sam Catlow","metadata":"{}"},{"issue_id":"archie-core-7d5u.3","depends_on_id":"archie-core-7d5u.1","type":"blocks","created_at":"2026-08-21T23:26:58Z","created_by":"Sam Catlow","metadata":"{}"}],"dependency_count":1,"dependent_count":1,"comment_count":0} {"_type":"issue","id":"archie-core-7d5u","title":"[EPIC] Event sources and typed reactions: archie as an extensible platform","description":"Goal: let archie react to things happening -- forge activity, inbound callers, schedules -- and let extensions hook those reactions, without a generic untyped event bus.\n\nTwo findings shape this, both verified in the tree on 2026-08-21.\n\n1. ARCHIE HAS TWO EVENT NEEDS AND ONE BUS. internal/events is documented as 'archied's in-process observability stream' with 'bounded per-subscriber buffers that DROP on overflow, so a stalled dashboard connection can never apply backpressure to the task engine'. Publish is fire-and-forget; subscribers get a read-only channel and cannot influence anything. Correct for the dashboard, wrong for reactions: a hook that silently misses events under load and cannot affect an outcome is worse than no hook, because it looks like it ran. Reactions need at-least-once delivery and the ability to change what happens. Do not bolt reactions onto events.Bus.\n\n2. THE OBVIOUS DESIGN IS PROHIBITED, DELIBERATELY. The tau model this is drawn from dispatches generically: DispatchEvent(ctx, eventName string, sessionID, ...) to out-of-process gRPC plugins. archie's approved foundation (docs/architecture/plugins-and-extensions.md) forbids that shape -- the generic plugin contract stays metadata-only and MUST NOT expose untyped hooks. plugin.Plugin is Name()/Version() only, enforced by internal/plugin/architecture_test.go and by the plugin engine rule in ARCHITECTURE.md. tau already carries the scar the rule avoids: TestUnload_DoesNotWaitForInFlightDispatch exists because a stuck plugin blocked plugin unload.\n\nThe reconciliation, and why this is an epic rather than a feature: separate INBOUND (callers push work in -- forge webhook, chat webhook, cron, channel) from REACTION (extensions respond to something that happened). Inbound becomes a typed source/intake capability family with an owning registry. Reactions become typed capability families owned by the domain whose semantics they affect. 'Webhooks aligned to types of callers' is exactly the typed-family model applied to intake: the instinct is right, the generic bus is what has to go.\n\nNear-term payoff: archie reacts to an issue being labelled the moment it happens, instead of up to poll_interval later.","acceptance_criteria":"A forge webhook triggers work behind a feature flag with polling still available as a backstop; inbound callers register through one typed family rather than bespoke wiring per caller; reactions have delivery guarantees distinct from the lossy observability bus; the generic plugin contract remains metadata-only and internal/plugin/architecture_test.go still passes.","notes":"CORRECTION 2026-08-22 (second): the earlier summary I gave characterized 'NATS is currently optional' as an open architectural gap for this epic to navigate around. That's wrong, and Sam corrected it directly: NATS was never meant to be optional as a technology. What's optional is running a standalone NATS SERVER -- config.NATSConfig.URL empty falls back to the existing SQLite ClaimNext flow (internal/config/config.go:573-582, internal/infrastructure/eventbus/nats/doc.go:24). The intended second deployment shape is NATS EMBEDDED (in-process, no external server to stand up), not 'no NATS, use some other eventbus'. There is no other eventbus in scope, was never meant to be one, and this epic must not introduce one.\n\nCurrent code state, verified: github.com/nats-io/nats-server/v2 (the embeddable NATS server package) is already a direct, non-indirect dependency, and is genuinely used to spin up an in-process server -- but only inside _test.go files (internal/infrastructure/agenttransport/nats/transport_test.go and others use github.com/nats-io/nats-server/v2/test to run tests against a real embedded server). It has never been wired into production as an actual deployment mode. So embedded NATS is proven to work in this codebase's own test harness, and the gap is purely that production startup only knows 'external URL configured' vs 'no NATS, fall back to SQLite' -- there is no production code path that starts nats-server in-process.\n\nThis changes 7d5u.2 (reaction delivery) materially: 'ride the existing NATS eventbus, or a second in-process bus' was the wrong framing. The actual question is whether reaction delivery requires an external NATS deployment or can run on an embedded NATS instance so single-process deployments still get it -- not whether to use NATS at all versus some other bus. If embedded NATS is wired for reaction delivery, capture (t2db.1) gets it too essentially for free, since they were flagged as needing the same underlying decision.","status":"open","priority":1,"issue_type":"epic","owner":"sam@catlow.tech","created_at":"2026-08-21T13:25:57Z","created_by":"Sam Catlow","updated_at":"2026-08-21T14:28:13Z","dependency_count":0,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"archie-core-h019.3","title":"Reviewer runs in a context that provably never saw the implementation","description":"This is the whole feature. A reviewer that shares the implementer's context is a second opinion from the same mind, and it will rationalise the same mistakes -- which is exactly the failure mode CLAUDE.md's 'never self-certified by the implementer' rule exists to prevent.\n\nArchie already has the machinery: each task runs in an isolated container against its own worktree. Launch the reviewer the same way, seeded only with the diff and the originating issue. It must not receive the implementer's conversation, its notes, its reasoning, or its own claims about what it did.\n\nPer 'environmental enforcement over prompt rules', isolation must be a property of construction, not a sentence in the prompt. The agent cannot talk its way out of a context it was never given. Assert it in a test rather than assuming it: a test that would fail if implementer context were threaded through.","acceptance_criteria":"The reviewer is launched with only diff + issue; a test fails if implementer context reaches it; the reviewer's prompt instructs it to assume every line is wrong until proven correct; the mechanism reuses the existing container/worktree isolation rather than inventing a second one.","status":"open","priority":1,"issue_type":"feature","owner":"sam@catlow.tech","created_at":"2026-08-21T13:02:54Z","created_by":"Sam Catlow","updated_at":"2026-08-21T13:02:54Z","dependencies":[{"issue_id":"archie-core-h019.3","depends_on_id":"archie-core-h019.1","type":"blocks","created_at":"2026-08-21T13:03:25Z","created_by":"Sam Catlow","metadata":"{}"},{"issue_id":"archie-core-h019.3","depends_on_id":"archie-core-h019","type":"parent-child","created_at":"2026-08-21T13:02:54Z","created_by":"Sam Catlow","metadata":"{}"}],"dependency_count":1,"dependent_count":1,"comment_count":0} {"_type":"issue","id":"archie-core-h019.4","title":"Wire review as an implement-workflow stage: after gates, before PR open","description":"Sequence matters. The review runs after gates pass -- there is no point reviewing code that does not build or test -- and before the PR is opened, because the point is to not spend the operator's attention on a PR that is not ready.\n\nA surviving CONFIRMED finding must not open a PR. It parks the task as waiting_human with the findings attached, which is the existing lifecycle state for 'a human needs to look at this' and needs no new state. Per CLAUDE.md, a finding that survives blocks closing the work; it does not get waved through.\n\nScope to the implement workflow first. Routing to tdd/bootstrap/feasibility is a later decision -- feasibility in particular produces a document rather than a diff, so 'review the diff' may not even apply.","acceptance_criteria":"An implement task with a clean gate and no confirmed findings opens a PR as it does today; one with a surviving confirmed finding parks as waiting_human with findings recorded and opens no PR; the stage is observable in the task's running(workflow:stage) status; retry after operator action re-runs the review.","status":"open","priority":1,"issue_type":"feature","owner":"sam@catlow.tech","created_at":"2026-08-21T13:02:54Z","created_by":"Sam Catlow","updated_at":"2026-08-21T13:02:54Z","dependencies":[{"issue_id":"archie-core-h019.4","depends_on_id":"archie-core-h019.1","type":"blocks","created_at":"2026-08-21T13:03:25Z","created_by":"Sam Catlow","metadata":"{}"},{"issue_id":"archie-core-h019.4","depends_on_id":"archie-core-h019.3","type":"blocks","created_at":"2026-08-21T13:03:26Z","created_by":"Sam Catlow","metadata":"{}"},{"issue_id":"archie-core-h019.4","depends_on_id":"archie-core-h019.2","type":"blocks","created_at":"2026-08-21T13:03:25Z","created_by":"Sam Catlow","metadata":"{}"},{"issue_id":"archie-core-h019.4","depends_on_id":"archie-core-h019","type":"parent-child","created_at":"2026-08-21T13:02:54Z","created_by":"Sam Catlow","metadata":"{}"}],"dependency_count":3,"dependent_count":1,"comment_count":0} diff --git a/docs/prds/event-sources-and-reactions.md b/docs/prds/event-sources-and-reactions.md new file mode 100644 index 000000000..bf9226d81 --- /dev/null +++ b/docs/prds/event-sources-and-reactions.md @@ -0,0 +1,132 @@ +# Event sources and reactions -- decision + +**Status:** Decided, not yet implemented +**Date:** 2026-08-22 +**Beads issue:** `archie-core-7d5u.1`, blocks `7d5u.2/.3/.4/.5` + +Answers the four questions in `7d5u.1`'s description. Investigated against +the actual tree, not designed from scratch: three mechanisms already in this +codebase answer most of this, and the job here is picking the right one for +each question and saying which packages change. + +## 1. In-process typed families, not out-of-process dispatch + +Archie has no out-of-process extension mechanism today. The plugin engine +rule (`ARCHITECTURE.md#plugin-engine-rule-strict`, mechanically checked by +`internal/plugin/architecture_test.go`) keeps every capability family +in-process behind a narrow typed registrar; NATS RPC exists for +daemon<->agentexec, a different actor with a different trust boundary (task +execution, not third-party extension code), not a precedent for generic +plugin dispatch. Neither epic's near-term payoff -- react to a labelled +issue, bind a captured webhook to a workflow -- needs extension code in +another language or process. Building out-of-process dispatch now would be +designing for a requirement neither epic states. + +`docs/architecture/plugins-and-extensions.md` does **not** need amending. +The line that looked like a blanket ban on hooks (`archie-core-7d5u`'s notes +record the correction) is scoped to Workflow semantics specifically, and +nothing decided here touches Workflow's ownership of its own contracts. + +## 2. Reaction delivery: `internal/eventbus`'s contract, a NEW stream + +`internal/eventbus.Publisher`/`Consumer` already has everything a reaction +needs: `PublishUnique(subject, idempotencyKey, payload)` for at-least-once +without duplicate enqueue, `Ack`/`Nak` with "a handler returning an error +causes redelivery." Do not design new delivery semantics; use this contract. + +**Do not reuse the existing `nats.Client` as-is.** `Config.StreamName` and +`Config.Subjects` are already composition-supplied ("the bus must not know +which subjects belong to which domain," `config.go:35-38`), but the +retention policy is not parameterized: `New` hardcodes +`Retention: jetstream.WorkQueuePolicy` (`client.go:65`), the competing-consumer +policy correct for `ARCHIE_TASKS` task distribution -- one message, claimed by +exactly one consumer -- and wrong for reactions. Two independent reactions +both wanting to see the same event under `WorkQueuePolicy` hit exactly the +trap `CLAUDE.md` already documents: overlapping filter subjects on a +work-queue stream mean the second consumer silently gets nothing. Reactions +need fan-out, not claim-once, so the client needs retention made a `Config` +field (defaulting to today's `WorkQueuePolicy` so `ARCHIE_TASKS` is +unaffected), and a second stream (`ARCHIE_REACTIONS` or similar) configured +under a fan-out-capable policy, alongside the existing task-distribution +stream -- not instead of it. + +This is where `7d5u.2`'s embedded-vs-external axis attaches: whichever NATS +instance backs `ARCHIE_TASKS` also backs the reaction stream. Confirmed with +Sam 2026-08-22: NATS was never meant to be optional as a technology -- only +whether it runs as an external server or embedded in-process +(`github.com/nats-io/nats-server/v2` is already a direct, test-proven +dependency, just never wired into production startup). `7d5u.2` wires that; +this document does not re-decide it. + +## 3. Reactions in these two epics are producer-only + +No veto, no mutation of in-flight work. Two existing shapes cover everything +either epic actually needs, and neither is a hook that can block something +else: + +- **Cheap wake, no payload.** `internal/domain/curator/wake.go`'s + `WakeOnPrimaryInput` subscribes to the lossy `events.Bus` and nudges a + runtime to check sooner; a dropped event only delays a check-in, never + loses work, because the trigger decision is a deterministic state read at + pass time, not the event payload. Model any "check something sooner" + reaction on this, unchanged. +- **Produce new work, real payload.** `daemon.go`'s existing `pollNATS` -> + `publishTask` path is already exactly a reaction that observes forge state + and produces a `workintake.TaskEnvelope`. A webhook source is a second + producer into the same path, not a new capability -- see question 4. + +A reaction that can veto or mutate an *in-flight* task (block a PR from +opening, alter a running stage) is a different, harder problem with its own +ordering and failure semantics, and belongs to `archie-core-h019` (adversarial +self-review) if and when that epic needs one -- not here. Do not build a +general block-capable hook mechanism for either epic; nothing in their stated +scope requires it, and it would duplicate whatever h019 eventually needs. + +## 4. No single generic intake interface; each domain keeps its own + +A `Source` interface generic enough to cover a forge issue, a chat message, +and a cron tick would need an `any` payload -- the untyped-hook shape the +plugin engine rule exists to prevent, just moved into a new package instead +of the old one. + +**What's genuinely shared, and belongs in a small cross-cutting package** +(imports nothing per the cross-cutting rule): the mechanics from +`archie-core-t2db.5` that apply to any inbound HTTP source regardless of what +consumes it -- HMAC verification (already a standalone function, +`internal/channels/webhook/webhook.go`'s `validateHMAC`), per-source rate +limiting, capture/audit, and the draft/pending_approval/armed gate. This +package owns none of forge, chat, or workintake's vocabulary. + +**What stays domain-owned, per existing convention:** +- Forge-issue intake needs no new type. `internal/domain/workintake.TaskEnvelope` + already is the typed contract -- `Subject()`, `IdempotencyKey()` (keyed on + `owner/repo/number`, not on delivery source), `Encode()`. A webhook-sourced + envelope for the same issue produces the *same* idempotency key as a + poll-discovered one, so `PublishUnique` dedups the two paths for free. This + is `7d5u.5`'s answer, not a new mechanism: reuse `TaskEnvelope` and + `publishTask`, don't invent a second envelope shape. +- Chat-webhook intake stays exactly what it is: + `internal/channels/webhook`'s `RouteConfig` routes into `gateway.Router`, + documented as chat-scoped ("External services push messages into + archie-core's gateway for LLM processing"). Do not generalize this package + into a multi-domain receiver -- it already does one thing per "a package + owns its own format end to end." +- A forge webhook receiver (`7d5u.4`) is new: it builds on the shared + mechanics above, decodes a GitHub payload into the *same* + `workintake.TaskEnvelope`, and calls the *same* `publishTask` the poller + calls. It does not get its own dispatch predicate -- `7d5u.4`'s bead + already requires reusing the poller's label/assignee predicate rather than + reimplementing it, and this decision extends that to the envelope and + publish path too. + +## Packages this touches + +- New: a cross-cutting intake-mechanics package (HMAC, rate limit, capture, + approval state machine) -- name and exact location decided in `t2db.1`/`t2db.5`. +- `internal/infrastructure/eventbus/nats`: a second stream/consumer + configuration for reactions, distinct retention policy from `ARCHIE_TASKS`. +- `internal/domain/workintake`: unchanged in shape; `TaskEnvelope` is reused, + not extended. +- `internal/daemon`: gains a webhook-sourced call path into the existing + `publishTask`, alongside the existing poll-sourced one. +- `internal/channels/webhook`: unchanged. Not the forge receiver. diff --git a/docs/prds/webhook-intake-security.md b/docs/prds/webhook-intake-security.md new file mode 100644 index 000000000..346a35f52 --- /dev/null +++ b/docs/prds/webhook-intake-security.md @@ -0,0 +1,101 @@ +# Webhook intake security -- decision + +**Status:** Decided, not yet implemented +**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 today, 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 +`ARCHITECTURE.md`'s environmental-enforcement-over-prompt-rules principle, +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. diff --git a/internal/channels/webhook/webhook.go b/internal/channels/webhook/webhook.go index 93d6e551a..222091cd4 100644 --- a/internal/channels/webhook/webhook.go +++ b/internal/channels/webhook/webhook.go @@ -5,9 +5,6 @@ package webhook import ( "context" - "crypto/hmac" - "crypto/sha256" - "encoding/hex" "encoding/json" "fmt" "io" @@ -19,6 +16,7 @@ import ( "github.com/samcharles93/archie-core/internal/channels" "github.com/samcharles93/archie-core/internal/gateway" + "github.com/samcharles93/archie-core/internal/webhookguard" ) // Gateway is a deliver-only webhook gateway. It listens for HTTP POST @@ -137,7 +135,7 @@ func (g *Gateway) handleWebhook(route *RouteConfig) http.HandlerFunc { if sig == "" { sig = r.Header.Get("X-Signature-256") } - if !validateHMAC(body, sig, route.Secret) { + if !webhookguard.VerifyHMAC(body, sig, route.Secret) { g.log.Warn("webhook invalid signature", "path", route.Path) http.Error(w, "invalid signature", http.StatusUnauthorized) return @@ -182,19 +180,6 @@ func (g *Gateway) handleWebhook(route *RouteConfig) http.HandlerFunc { } } -// validateHMAC checks a SHA-256 HMAC signature against the body. -func validateHMAC(body []byte, signature, secret string) bool { - if signature == "" { - return false - } - // Strip "sha256=" prefix if present. - sigHex := strings.TrimPrefix(signature, "sha256=") - mac := hmac.New(sha256.New, []byte(secret)) - mac.Write(body) - expected := hex.EncodeToString(mac.Sum(nil)) - return hmac.Equal([]byte(sigHex), []byte(expected)) -} - // ConfigSchema returns the JSON Schema for the webhook channel config. func (g *Gateway) ConfigSchema() json.RawMessage { return json.RawMessage(`{ diff --git a/internal/channels/webhook/webhook_test.go b/internal/channels/webhook/webhook_test.go index 64b020a38..abd433eef 100644 --- a/internal/channels/webhook/webhook_test.go +++ b/internal/channels/webhook/webhook_test.go @@ -23,24 +23,11 @@ func TestName(t *testing.T) { } } -func TestValidateHMAC(t *testing.T) { - secret := "test-secret" - body := []byte(`{"key":"value"}`) - - mac := hmac.New(sha256.New, []byte(secret)) - mac.Write(body) - validSig := "sha256=" + hex.EncodeToString(mac.Sum(nil)) - - if !validateHMAC(body, validSig, secret) { - t.Error("valid signature should pass") - } - if validateHMAC(body, validSig, "wrong-secret") { - t.Error("wrong secret should fail") - } - if validateHMAC(body, "", secret) { - t.Error("empty signature should fail") - } -} +// HMAC signature verification itself is now internal/webhookguard.VerifyHMAC +// and tested there; TestWebhookHandlerValidSignature and +// TestWebhookHandlerInvalidSignature below cover this package's own +// responsibility -- that the handler actually calls it and reacts correctly +// to the result. func TestExtractText(t *testing.T) { body := []byte(`{"issue":{"title":"fix bug","body":"details"}}`) diff --git a/internal/webhookguard/doc.go b/internal/webhookguard/doc.go new file mode 100644 index 000000000..466cba805 --- /dev/null +++ b/internal/webhookguard/doc.go @@ -0,0 +1,12 @@ +// Package webhookguard provides storage-agnostic mechanics for vetting +// inbound webhook-shaped HTTP requests before anything trusts them: +// signature verification, per-source rate limiting, and payload redaction. +// +// It is cross-cutting per docs/architecture/organisation.md: importable by +// any layer, and it imports none of domain, infrastructure, or app. It owns +// none of a caller's vocabulary -- not what a "source" is, not how a +// captured event is stored, not what a binding's approval state means. Those +// stay with the packages that own that state (see +// docs/prds/event-sources-and-reactions.md for why a generic Source +// interface was rejected). +package webhookguard diff --git a/internal/webhookguard/hmac.go b/internal/webhookguard/hmac.go new file mode 100644 index 000000000..1c36190c1 --- /dev/null +++ b/internal/webhookguard/hmac.go @@ -0,0 +1,24 @@ +package webhookguard + +import ( + "crypto/hmac" + "crypto/sha256" + "encoding/hex" + "strings" +) + +// VerifyHMAC checks a SHA-256 HMAC signature against body using secret, +// accepting a signature with or without the "sha256=" prefix GitHub and +// similar senders use. An empty signature is never valid, even against an +// empty secret -- the absence of a signature must never be mistaken for one +// that happens to match. +func VerifyHMAC(body []byte, signature, secret string) bool { + if signature == "" { + return false + } + sigHex := strings.TrimPrefix(signature, "sha256=") + mac := hmac.New(sha256.New, []byte(secret)) + mac.Write(body) + expected := hex.EncodeToString(mac.Sum(nil)) + return hmac.Equal([]byte(sigHex), []byte(expected)) +} diff --git a/internal/webhookguard/hmac_test.go b/internal/webhookguard/hmac_test.go new file mode 100644 index 000000000..85b32baa8 --- /dev/null +++ b/internal/webhookguard/hmac_test.go @@ -0,0 +1,47 @@ +package webhookguard_test + +import ( + "crypto/hmac" + "crypto/sha256" + "encoding/hex" + "testing" + + "github.com/samcharles93/archie-core/internal/webhookguard" +) + +func sign(secret string, body []byte) string { + mac := hmac.New(sha256.New, []byte(secret)) + mac.Write(body) + return hex.EncodeToString(mac.Sum(nil)) +} + +func TestVerifyHMAC(t *testing.T) { + const secret = "shared-secret" + body := []byte(`{"issue":{"number":42}}`) + validSig := sign(secret, body) + + tests := []struct { + name string + body []byte + signature string + secret string + want bool + }{ + {"valid signature", body, validSig, secret, true}, + {"valid signature with sha256= prefix", body, "sha256=" + validSig, secret, true}, + {"wrong secret", body, validSig, "different-secret", false}, + {"tampered body", []byte(`{"issue":{"number":99}}`), validSig, secret, false}, + {"empty signature", body, "", secret, false}, + {"empty signature against empty secret", body, "", "", false}, + {"garbage signature", body, "not-a-hex-signature", secret, false}, + } + + for _, test := range tests { + t.Run(test.name, func(t *testing.T) { + got := webhookguard.VerifyHMAC(test.body, test.signature, test.secret) + if got != test.want { + t.Errorf("VerifyHMAC() = %v, want %v", got, test.want) + } + }) + } +} diff --git a/internal/webhookguard/ratelimit.go b/internal/webhookguard/ratelimit.go new file mode 100644 index 000000000..aaf6f50a4 --- /dev/null +++ b/internal/webhookguard/ratelimit.go @@ -0,0 +1,69 @@ +package webhookguard + +import ( + "sync" + "time" +) + +// RateLimiter caps request volume per source using a token bucket per +// source ID. Source IDs are assumed to come from a registered, operator- +// controlled set (per docs/prds/webhook-intake-security.md's "a source +// registers with a secret before its events can trigger anything"), not +// from unbounded attacker-supplied request data -- the bucket map is not +// itself bounded, because the key space is bounded by registration. +// +// A rejected request must be surfaced as an observable rejection by the +// caller (HTTP 429), never silently dropped -- see +// docs/prds/webhook-intake-security.md point 3. +type RateLimiter struct { + mu sync.Mutex + rate float64 // tokens added per second + burst float64 // bucket capacity, also the starting balance + now func() time.Time + buckets map[string]*tokenBucket +} + +type tokenBucket struct { + tokens float64 + lastSeen time.Time +} + +// NewRateLimiter returns a limiter refilling at ratePerSecond tokens per +// second up to burst tokens. now is the clock to use; pass time.Now for +// production callers and an injected clock in tests. +func NewRateLimiter(ratePerSecond float64, burst int, now func() time.Time) *RateLimiter { + return &RateLimiter{ + rate: ratePerSecond, + burst: float64(burst), + now: now, + buckets: make(map[string]*tokenBucket), + } +} + +// Allow reports whether a request from source may proceed, consuming one +// token if so. A source seen for the first time starts with a full bucket +// (burst tokens) rather than empty, so the initial request from a newly +// registered source is never rejected outright. +func (r *RateLimiter) Allow(source string) bool { + r.mu.Lock() + defer r.mu.Unlock() + + now := r.now() + b, ok := r.buckets[source] + if !ok { + b = &tokenBucket{tokens: r.burst, lastSeen: now} + r.buckets[source] = b + } else { + elapsed := now.Sub(b.lastSeen).Seconds() + if elapsed > 0 { + b.tokens = min(r.burst, b.tokens+elapsed*r.rate) + b.lastSeen = now + } + } + + if b.tokens < 1 { + return false + } + b.tokens-- + return true +} diff --git a/internal/webhookguard/ratelimit_test.go b/internal/webhookguard/ratelimit_test.go new file mode 100644 index 000000000..a1248cb12 --- /dev/null +++ b/internal/webhookguard/ratelimit_test.go @@ -0,0 +1,70 @@ +package webhookguard_test + +import ( + "testing" + "time" + + "github.com/samcharles93/archie-core/internal/webhookguard" +) + +// fakeClock lets tests advance time deterministically instead of sleeping. +type fakeClock struct{ now time.Time } + +func (c *fakeClock) Now() time.Time { return c.now } +func (c *fakeClock) advance(d time.Duration) { c.now = c.now.Add(d) } + +func TestRateLimiterAllowsUpToBurstThenDenies(t *testing.T) { + clock := &fakeClock{now: time.Unix(0, 0)} + limiter := webhookguard.NewRateLimiter(1, 3, clock.Now) // 1/s refill, burst 3 + + for i := range 3 { + if !limiter.Allow("source-a") { + t.Fatalf("request %d: Allow() = false, want true (within burst)", i) + } + } + if limiter.Allow("source-a") { + t.Fatal("Allow() = true, want false (burst exhausted)") + } +} + +func TestRateLimiterRefillsOverTime(t *testing.T) { + clock := &fakeClock{now: time.Unix(0, 0)} + limiter := webhookguard.NewRateLimiter(1, 1, clock.Now) // 1/s refill, burst 1 + + if !limiter.Allow("source-a") { + t.Fatal("first request denied, want allowed") + } + if limiter.Allow("source-a") { + t.Fatal("second immediate request allowed, want denied") + } + clock.advance(time.Second) + if !limiter.Allow("source-a") { + t.Fatal("request after refill window denied, want allowed") + } +} + +func TestRateLimiterSourcesAreIndependent(t *testing.T) { + clock := &fakeClock{now: time.Unix(0, 0)} + limiter := webhookguard.NewRateLimiter(1, 1, clock.Now) + + if !limiter.Allow("source-a") { + t.Fatal("source-a first request denied, want allowed") + } + if limiter.Allow("source-a") { + t.Fatal("source-a burst exhausted request allowed, want denied") + } + if !limiter.Allow("source-b") { + t.Fatal("source-b denied by source-a's exhausted budget, want independent") + } +} + +func TestRateLimiterUnknownSourceStartsWithFullBurst(t *testing.T) { + clock := &fakeClock{now: time.Unix(0, 0)} + limiter := webhookguard.NewRateLimiter(1, 5, clock.Now) + + for i := range 5 { + if !limiter.Allow("first-time-source") { + t.Fatalf("request %d for a never-seen source denied, want allowed within burst", i) + } + } +} diff --git a/internal/webhookguard/redact.go b/internal/webhookguard/redact.go new file mode 100644 index 000000000..62060872c --- /dev/null +++ b/internal/webhookguard/redact.go @@ -0,0 +1,79 @@ +package webhookguard + +import ( + "encoding/json" + "fmt" + "strings" +) + +// redactedValue replaces a value whose key looks sensitive. +const redactedValue = "[redacted]" + +// sensitiveKeyMarkers is the key-name heuristic, matching +// internal/gateway/stream.go's sensitiveParameterKey exactly so the two +// redaction paths agree on what counts as sensitive. +var sensitiveKeyMarkers = []string{ + "token", "secret", "password", "passwd", "api_key", "apikey", + "authorization", "credential", "cookie", "private_key", +} + +// RedactPayload replaces values under sensitive-looking JSON keys with a +// redaction marker and returns the re-encoded payload, for capturing an +// inbound webhook body before persisting it. +// +// This intentionally does NOT reuse internal/gateway/stream.go's +// SummarizeToolParameters shape unchanged: that function replaces every +// string value regardless of key, which produces a bounded one-line summary +// for a chat transcript. A captured webhook payload exists to be inspected +// and mapped field-by-field (see docs/prds/event-sources-and-reactions.md +// and t2db.3's schema-by-example mapping) -- redacting every string would +// make that impossible. Only a value whose key matches the marker list is +// touched; everything else is returned exactly as decoded. +// +// A key match redacts its entire value, including a nested object or array +// -- "credentials": {"host": ..., "user": ...} is wholesale replaced, not +// recursed into, matching the intent of the key name. +func RedactPayload(payload []byte) ([]byte, error) { + var value any + decoder := json.NewDecoder(strings.NewReader(string(payload))) + decoder.UseNumber() + if err := decoder.Decode(&value); err != nil { + return nil, fmt.Errorf("redact payload: decode: %w", err) + } + redacted := redactValue(value) + encoded, err := json.Marshal(redacted) + if err != nil { + return nil, fmt.Errorf("redact payload: encode: %w", err) + } + return encoded, nil +} + +func redactValue(value any) any { + m, ok := value.(map[string]any) + if !ok { + if arr, ok := value.([]any); ok { + for i, child := range arr { + arr[i] = redactValue(child) + } + } + return value + } + for key, child := range m { + if sensitiveKey(key) { + m[key] = redactedValue + continue + } + m[key] = redactValue(child) + } + return m +} + +func sensitiveKey(key string) bool { + normalized := strings.NewReplacer("-", "_", " ", "_").Replace(strings.ToLower(key)) + for _, marker := range sensitiveKeyMarkers { + if strings.Contains(normalized, marker) { + return true + } + } + return false +} diff --git a/internal/webhookguard/redact_test.go b/internal/webhookguard/redact_test.go new file mode 100644 index 000000000..b9dc01175 --- /dev/null +++ b/internal/webhookguard/redact_test.go @@ -0,0 +1,127 @@ +package webhookguard_test + +import ( + "encoding/json" + "testing" + + "github.com/samcharles93/archie-core/internal/webhookguard" +) + +// TestRedactPayloadPreservesNonSensitiveValues is the regression test for +// the defect a naive port of gateway/stream.go's redaction would introduce: +// that function replaces every string value regardless of key, which is +// correct for a bounded chat-transcript summary but would make a captured +// webhook payload useless for schema-by-example mapping (t2db.3) -- an +// operator cannot map a field they cannot see. Only values under a +// sensitive-looking key may be redacted; everything else must survive +// byte-for-byte. +func TestRedactPayloadPreservesNonSensitiveValues(t *testing.T) { + input := []byte(`{"issue":{"number":42,"title":"Fix the thing","open":true}}`) + + got, err := webhookguard.RedactPayload(input) + if err != nil { + t.Fatalf("RedactPayload() error = %v", err) + } + + var decoded map[string]any + if err := json.Unmarshal(got, &decoded); err != nil { + t.Fatalf("redacted output is not valid JSON: %v", err) + } + issue, ok := decoded["issue"].(map[string]any) + if !ok { + t.Fatalf("decoded[%q] = %#v, want map[string]any", "issue", decoded["issue"]) + } + if issue["title"] != "Fix the thing" { + t.Errorf("title = %v, want unredacted %q", issue["title"], "Fix the thing") + } + if issue["number"] != float64(42) { + t.Errorf("number = %v, want unredacted 42", issue["number"]) + } + if issue["open"] != true { + t.Errorf("open = %v, want unredacted true", issue["open"]) + } +} + +func TestRedactPayloadRedactsSensitiveKeys(t *testing.T) { + tests := []struct { + name string + key string + }{ + {"exact match", "token"}, + {"api_key", "api_key"}, + {"apikey no separator", "apikey"}, + {"hyphenated", "api-key"}, + {"spaced", "API Key"}, + {"mixed case", "Authorization"}, + {"substring match", "access_token"}, + {"password", "password"}, + {"passwd abbreviation", "passwd"}, + {"private key", "private_key"}, + {"cookie", "cookie"}, + {"credential", "credential"}, + } + + for _, test := range tests { + t.Run(test.name, func(t *testing.T) { + input, err := json.Marshal(map[string]string{test.key: "super-secret-value"}) + if err != nil { + t.Fatal(err) + } + got, err := webhookguard.RedactPayload(input) + if err != nil { + t.Fatalf("RedactPayload() error = %v", err) + } + if string(got) == string(input) { + t.Fatalf("payload unchanged, want %q redacted", test.key) + } + var decoded map[string]any + if err := json.Unmarshal(got, &decoded); err != nil { + t.Fatalf("redacted output is not valid JSON: %v", err) + } + if decoded[test.key] == "super-secret-value" { + t.Errorf("value under key %q survived redaction", test.key) + } + }) + } +} + +func TestRedactPayloadRedactsNestedObjectsWholesale(t *testing.T) { + input := []byte(`{"credentials":{"host":"db.internal","user":"admin"}}`) + + got, err := webhookguard.RedactPayload(input) + if err != nil { + t.Fatalf("RedactPayload() error = %v", err) + } + var decoded map[string]any + if err := json.Unmarshal(got, &decoded); err != nil { + t.Fatalf("redacted output is not valid JSON: %v", err) + } + if _, stillObject := decoded["credentials"].(map[string]any); stillObject { + t.Errorf("credentials still an object, want wholesale redaction: %v", decoded["credentials"]) + } +} + +func TestRedactPayloadHandlesArraysAndScalarsAtTopLevel(t *testing.T) { + tests := []struct { + name string + input string + }{ + {"array", `[{"title":"a"},{"title":"b"}]`}, + {"bare string", `"just a string"`}, + {"bare number", `42`}, + {"null", `null`}, + } + for _, test := range tests { + t.Run(test.name, func(t *testing.T) { + if _, err := webhookguard.RedactPayload([]byte(test.input)); err != nil { + t.Errorf("RedactPayload(%s) error = %v, want no error", test.input, err) + } + }) + } +} + +func TestRedactPayloadRejectsInvalidJSON(t *testing.T) { + if _, err := webhookguard.RedactPayload([]byte("{not valid json")); err == nil { + t.Error("RedactPayload() succeeded on invalid JSON, want error") + } +}