feat(webhook): per-user webhook receiver, on by default (#101)

[defangdevs]

Closes #101. Ships the local-channels local-webhook plugin as a per-user webhook channel, so an agent session gets told when CI finishes or a review lands instead of looping on gh pr checks + sleep — which is slow and burns context re-reading state it already had.

Prerequisite defangdevs/local-channels#3 is merged (local-webhook 0.7.0: CLI mode; gh-webhook alias deleted — its only consumer is gone). webhook.rev pins that merge commit.

What a session sees

agent-box-webhook setup                     # one-time: mint HMAC secret, print URL
agent-box-webhook subscribe OWNER/REPO --note "PR 146: waiting on CI"
agent-box-webhook ls

Three discovery paths, so no session has to be told this exists:

1. agent-box-webhook on every agent's PATH (and only when there's an endpoint to talk about).
2. A "Getting told, instead of polling" section in the seeded AGENTS.md, which leads with prefer this over polling.
3. In Claude Code sessions, webhook_subscribe / _unsubscribe / _subscriptions as MCP tools. The CLI and the tools share one subscription list, so codex and shell sessions aren't second-class.

Design

• Daemon: agent-box-webhook-<user> runs webhook.mjs with LOCAL_WEBHOOK_RECEIVER_ONLY=1, owning a socket-activated UNIX ingress at /run/agent-box-webhook/<user>.sock, bound 0660 <user>:caddy by a .socket unit — same isolation model as the settings socket (Settings daemon is unauthenticated on localhost: any local user can tamper with another agent's keys #49). No MCP session of its own, so the box's one endpoint stays up regardless of which sessions exist.
• Caddy: handle /<user>/webhook* reverse-proxies to that socket without basic_auth — GitHub can't authenticate, so webhook.mjs's per-source HMAC-SHA256 check is the trust boundary. Emitted before /<user>/*. A bad-signature 401 can't feed the fail2ban jail: its failregex also requires an Authorization header, which no webhook sender sends.
• Sessions: the plugin is registered + enabled non-interactively via seeded ~/.claude/settings.json; each session gets LOCAL_WEBHOOK_SESSION/STATE_DIR/PORT=0 through tmux new-session -e, so the vars land in the session environment and are inherited by anything the agent runs — which is why the CLI needs no arguments. Subscriptions never leak between sessions.
• Pin: builtins.fetchurl of the single local-webhook/webhook.mjs from raw.githubusercontent — the same host and mechanism agent-box.nix itself is deployed with (Deploy regression: module no longer single-file — 1-click first boot and self-update break on master #51), so an IPv6-only box reaches it via NAT64 with no unpack step.

Default ON (changed from the draft)

An opt-in needing a root /etc/nixos edit plus a rebuild — which the agent user cannot do — would be discovered by nobody. It fails closed: with no sources.json every POST is answered 404, and a configured source rejects anything unsigned with 401, so a box where nobody ran agent-box-webhook setup accepts nothing at all. No-op without web.enable. webhook.enable = false removes the daemon, socket and public path entirely.

The README's security-model bullet claiming every path on the vhost sits behind the login is corrected — this is the one deliberate exception, and it says why.

Bugs found in the draft wiring (checked against a live claude)

• enabledPlugins is an object keyed "<plugin>@<marketplace>", not a list of {marketplace, plugin} records. The draft's seed would never have enabled the plugin. Verified that with only extraKnownMarketplaces + enabledPlugins seeded, a fresh session clones the marketplace, populates the plugin cache and connects the MCP server with no /plugin prompt — and that the three tools are then reachable in a session.
• The sha256 "placeholder" was actually correct for the old tarball pin — confirmed by a real fetch of both revs before switching to the single-file pin.
• The conditional Caddy block flattened the terminal block's indentation. A column-0 interpolation inside a Nix indented string resets what gets stripped, so the whole per-user block was emitted 8 columns off. Moved into its own webhookCaddyBlock, composed through the existing indent helper.

Tests

• tests/webhook.nix (new VM test, wired into CI): units exist with nobody setting webhook.enable; socket is 0660 agent:caddy; the public path answers while /agent/ still 401s; 404 before setup; setup writes a 0600 secret and merges sources.json; bad/missing signature → 401, unknown source → 404, correct HMAC → 200 (and a bare POST → default source); the daemon fans out to a stand-in session peer — the same webhook.mjs on stdio that claude runs — which prints the channel notification with the subscription note echoed, and stays silent for a repo nobody subscribed to; plus the discovery surface (CLI on PATH, AGENT_BOX_WEBHOOK_URL, per-session LOCAL_WEBHOOK_SESSION, seeded plugin settings).
• webhook-route (cheap eval check, wired into CI): the real generated Caddyfile routes the path to the ingress socket, before the catch-all, with no basic_auth anywhere in that handle's body.

Verified locally on this box: full system closure builds with the feature on; generated units / Caddyfile / AGENTS.md / CLI all inspected from a real build; the CLI exercised end-to-end; and daemon → HMAC verify → IPC fan-out → channel notification confirmed by hand (bad signature → 401). The VM test itself could not run here — this box has no /dev/kvm (nested EC2) — so CI is the first place it executes.

🤖 Generated with Claude Code

https://claude.ai/code/session_01PsqGhkpjsb4kKAdVz25xKN