Skip to content
SHC Docs

Hookshot phase-0 build readiness: what the measurements changed

Status: open design. This is the readiness record for the matrix notification bus. The bus is deployed (2026-08-15), and the items the banner below does not close are still open.

Companion to 2026-08-09-matrix-notification-bus.md (the proposal) and its §12 evidence appendix (the lab). This document does three things and stops: maps each measurement onto the four owed rulings (§11.1–11.4, the C7 block on the rulings queue); states what the SHC-side surfaces are now, because one half of them stopped being hypothetical while the rulings were still queued; and lists exactly what remains unmeasured. Nothing here builds anything: producer surfaces stay unbuilt until the rulings land.

★ SUPERSEDED IN PART: 2026-08-15. The bus is deployed and all three ruled producers are live. The 2026-08-14 notification-bus ruling (“Hookshot for everything”) settled §11.1 against this document’s recommendation; the three producer plugs shipped, and the first-ever hookshot deployment stands on bitspur corp/prod, bound to the matrix stack, with hooks: glitchtip;wazuh;gitlab. SSRF posture ruled and applied: in-fabric urlBase (empty → http://prod.hookshot.hookshot:9000/webhook) plus GLITCHTIP_ALLOW_PRIVATE_IPS on glitchtip and allow_local_requests_from_web_hooks_and_services on gitlab, both carried as persistent deployment vars; the bearer URLs never leave the fabric. §4’s SHC-side unknown list closes as follows, each proven by a probe fired in this estate on 2026-08-15:

  • #6 (the acceptance ladder as an shc install): CLOSED. The stack renders, boots, converges room membership and serves.
  • #7 (a derived stateKey answering live): CLOSED, the seam that had no runtime evidence at all: the bridge’s rendered connections carry 844abdf5-… / b44ccff9-… / 9ddb6e23-… for glitchtip / wazuh / gitlab, and the URLs the three producers independently derived and stored (glitchtip’s AlertRecipient.url, wazuh’s ossec.conf <hook_url>, gitlab’s Integrations::Slack#webhook) are those same three ids. Four independent implementations of the HMAC/uuidshape recipe agree at runtime.
  • #8 / #9 (GlitchTip auth bootstrap and end-to-end delivery): CLOSED. The plug goes through the ORM (manage.py shell), so no APIToken is minted at all, and a real ingested event reached the room.
  • #10 (two consumers on one registration): STILL OPEN. huly-matrix-notifier remains undeployed; hookshot holds the shared registration alone.

The one thing the plan got wrong, and it is a rendering defect, not a delivery one. All three producers deliver; at the first deployment only wazuh rendered usefully. hookshot’s transformHookData renders a top-level string text and nothing else, and neither of the other two producers put its content there: glitchtip’s text is the constant "GlitchTip Alert" (detail in attachments, which is dropped), and gitlab posted form-encoded payload=<slack json> (so the far end saw {"payload": "…"} and dumped it). §2.1’s “M3 makes the GlitchTip producer plug a clean single-PUT upsert … the edge needs NO transformation function” read the payload dataclass’s field TYPE and not its VALUE.

★ AMENDED LATER THE SAME DAY: one of the two was producer-side after all, and is now GREEN. GitLab’s chat notifiers share one message builder and differ only in body ENCODING: Integrations::Slack goes through the slack-messenger gem (form-encoded payload=), Integrations::Pumble posts Content-Type: application/json with {"text": message.summary}. With both rows live against the same hook id, one issue produced two room messages 15 ms apart: a sentence and a dump. The edge moved to Pumble, the superseded Slack row is destroyed by the same converge job (M12; leaving it was a live double-delivery, not an untidiness), and a fresh issue produced exactly one onGenericHook and one legible line: [<…|Administrator / clone-proof>] Issue <…/work_items/6|#6 …> opened by Administrator (root).

So the RULING OWED now covers ONE edge, not two. glitchtip has no producer-side escape: all eight RecipientTypes were read at the 6.2.5 pin and not one puts issue detail in a top-level string text or html (webhook → constant banner + attachments; discord → content + embeds; googlechat → cardsV2; teams → adaptive card; feishu → interactive card; zulip → form-encoded to an appended /api/v1/messages path; ntfy → raw body, not JSON). Its fix is inside hookshot’s own design: a per-connection transformationFunction; 7.4.4 runs those in quickjs-emscripten (WASM) with a 500 ms interrupt deadline, and on this package only the appservice bot may create a connection, but the package refuses allowJsTransformationFunctions deliberately, so flipping it is RULING OWED. Each affected file carries its own measurement.

And one last-mile gap nobody’s package owns. joined_members on the alerts room returns exactly two accounts: @alerts (the matrix stack’s notification bot) and @_shc_appservice (hookshot’s sender). No human is in the room, and nothing in either package puts one there: matrix-init creates the room as the bot and invites nobody, hookshot’s adminMxid gates chat commands rather than membership, and the ruling names producers, not readers. The bus is live and delivering into a room with no audience. Whose knob that is (a matrix-package var, an estate convergence step, or an operator action) is unowned and worth naming before the next producer is wired.


0. The one fact that reframes everything below

Section titled “0. The one fact that reframes everything below”

★★ The provider half already exists on main. Commit a78b60301 (“the backlog sweep lands”) (an ancestor of origin/main, shipped in v0.0.49, both estates rolled) contains the complete apps/communication/hookshot/ package: app.yaml, compose.yaml (boot render of config.yml + registration.yml, passkey generation, the canonical HMAC/uuidshape derivation), vars.yaml, backup.yaml, webhook.socket.yaml (discovery + detect-and-report integration + retained-hook unintegration jobs), matrix.plug.yaml, matrixAppservice.plug.yaml, hookshot-init.job.yaml (invite + join read-back), and 25 bats guards including the derivation-recipe parity test.

The proposal’s original header (“Nothing here exists”) is therefore stale for the provider half, and §11.1’s question changed shape underneath the queue; see §2.1. What does not exist, anywhere in the catalog:

Terminal window
find apps -name webhook.plug.yaml # → nothing
ls apps/security/wazuh/matrix.plug.yaml # → does not exist
ls apps/devops/gitlab/matrix.plug.yaml # → does not exist

Zero producers. The phase-0 deliverables (§9.1) are unbuilt, the first webhook consumer is unbuilt, and no hookshot stack has ever been deployed; the package’s own bats header says “statics only. Deploy proof needs a live matrix stack …”. The §12 lab proved the upstream (raw containers, hand-written configs); it proved nothing about the package.

One more catalog fact the proposal predates: matrixAppservice no longer has zero consumers; it has two (apps/management/huly-matrix-notifier and apps/communication/hookshot), both deployment-unproven. §2.4.


1. Measurement verdicts, restated with their verification status

Section titled “1. Measurement verdicts, restated with their verification status”
#§10 rowVerdictStatus
M1row 1: does Synapse push to appservice.url?YES. Same-second PUT /_matrix/app/v1/transactions/… to a stub listener on nothing but the registration; same result re-pointed at hookshot 7.4.4, which processed the transactions. Bearer is the hs_token (sha256 cross-tie in the transcript), the credential a consumer-side listener must verify.MEASURED (lab, evidence committed)
M2row 3: static connection without a room state event?YES. Room state enumerates eight events, zero uk.half-shot.*; bridge boots Found 1 connections … (via static config); POST → 202 {"ok":true} and the message lands as the bot; unknown hookId → 404; survives SIGTERM + cold boot. No !hookshot command, no provisioning call, no admin room. The zero-touch declarative story holds.MEASURED (lab, evidence committed)
M3row 5: GlitchTip 6.2.5 AlertRecipient APINo standalone endpoint; recipients nest inside ProjectAlert CRUD at /api/0/projects/{org}/{proj}/alerts/… (django-ninja, router mounted at prefix 0). Auth Authorization: Bearer <APIToken>; scopes checked only for token auth; ORM additionally demands org-ADMIN or team membership. PUT is an upsert (aupdate_or_create keyed on (alert, recipient_type, url)) that deletes absent recipients. SSRF: validate_public_url rejects private-IP URLs at recipient-creation time and _is_url_allowed re-checks at send, redirects refused; GLITCHTIP_ALLOW_PRIVATE_IPS defaults False (settings.py:304).MEASURED as a source read at tag v6.2.5, and independently re-verified against a fresh clone 2026-08-10 (every §12.3 citation checked; all hold)
n/arows 2, 4settled as by-products (see §12.4): SSRF flag default False; the narrow registration + no userIdPrefix boots clean and posts as the botMEASURED
n/arows 6, 7provisioning API unread; MSC4190 unreadOPEN; §4

★ One precision the appendix earns and the acceptance ladder should adopt: the success arm is 202 Accepted, not 200 (waitForComplete: false), and the boot line Room … has no connections and is not an admin room refers to state-sourced connections only; a health probe that greps for it will false-alarm on a working bridge.


2. What each measurement now tells each owed ruling

Section titled “2. What each measurement now tells each owed ruling”

2.1 §11.1: “Is phase 0 the whole answer?”

Section titled “2.1 §11.1: “Is phase 0 the whole answer?””

The ruling’s shape changed twice. First, by measurement: M1 and M2 delete the two risks that made hookshot speculative: the bridge is not inert (the single highest-cost unknown, per §10’s own ranking) and the declarative path needs no chat commands, so the zero-touch story survives. M3 makes the GlitchTip producer plug a clean single-PUT upsert against an API whose semantics already match the plug’s needs. Nothing in the lab argues for routing GitLab or Uptime Kuma through the bridge; §1.2’s native-path verdict stands untouched.

Second, by the catalog: the expensive half of “build hookshot” (the packaged app, the socket, the init job (§7’s cost table)) was already spent in a78b60301, ahead of this ruling. So the live question is no longer “build the bridge or write two small shims”; it is “which producers ride the bridge, and does the package earn a deployment”. The phase-0 deliverables (wazuh custom- script + matrix plug; gitlab native integration driven via its API) are still unbuilt, still the right first move for those two producers, and still bridge-free. GlitchTip remains the only producer that needs the bridge, and the bridge it needs now exists in the catalog, platform-derisked but deployment-unproven.

Recommendation, updated: rule phase 0 as still-first for wazuh/gitlab; rule the GlitchTip edge as the hookshot package’s proving deployment, sequenced after the §2.2/§6.1 posture call, because M3 hardened the SSRF gate from “silently dropped at send” to “rejected at recipient-creation”, which the plug can at least surface as a real API error.

2.2 §11.2: “May the matrix socket’s bot token invite?”

Section titled “2.2 §11.2: “May the matrix socket’s bot token invite?””

M1 informs the mechanism directly: the invite’s membership event is the first transaction Synapse must deliver (measured: the stub’s transaction 1 is exactly that event), which is what makes hookshot-init’s invite the closest consumer-side proxy for “appservice.url is right”. The read-back posture is sound.

Two honesty notes the ruling should see. The landed matrix.plug.yaml header says “recommendation taken here: auto-invite with read-back”, a builder’s decision recorded in a file, not an owner ruling; the ruling is still formally owed, now with landed code on one side of it. And the lab did not exercise hookshot’s auto-accept arm: the bot entered the room during the stub phase, so onRoomInvite → joinRoom under the rendered permissions gate (Bridge.ts:1246/1274) remains source-read-only. The invite→auto-join→ read-back loop as hookshot-init will actually run it has never been observed.

2.3 §11.3: “Where does hookshot live in the tier structure?”

Section titled “2.3 §11.3: “Where does hookshot live in the tier structure?””

The measurements settle the factual predicate: the two-stack ordering is irreducible. The registration’s url is provider policy (authored on the matrix stack’s vars), and M1 shows the only proof of its correctness is a delivered transaction; nothing consumer-side can conjure that. So hookshot structurally cannot meet the flagship zero-touch bar; that is now a measured fact, not an argument. It is infrastructure. The landed app.yaml declares access: open, exposure: lan, no tier gate, consistent with that reading, but the placement itself is still the owner’s to speak.

2.4 §11.4: “Model a second appservice registration now?”

Section titled “2.4 §11.4: “Model a second appservice registration now?””

Sharpened from hypothetical to standing. §3.3’s original calculus was “with hookshot as the only consumer, sharing is free; a second bridge forces the extension”, and the catalog now carries two matrixAppservice consumers (huly-matrix-notifier, hookshot). M1’s token cross-tie makes the cost concrete: both consumers hold the same as_token/hs_token pair, so either can impersonate the other to Synapse and verify the other’s inbound transactions. Today that costs nothing at runtime because neither has ever been deployed; the moment both bind one matrix stack, the impersonation surface is live. The measurements inform urgency, not mechanism; the extension is still the one named in matrixAppservice.socket.yaml, still cheapest while the matrix package is already being touched.


SurfaceProposal §Status on main
apps/communication/hookshot/ package§8.1EXISTS: faithful to spec: no generic.userIdPrefix rendered, mandatory permissions: block, allowJsTransformationFunctions: false, enableHttpGet: false, both bindAddress: 0.0.0.0, image digest-pinned to 7.4.4
webhook.socket.yaml (urlBase/hookSecret/url/dialect; derivation; detect-and-report)§5 / §8.2EXISTS, plus a late-join note measured off 7.4.4 (onRoomJoin → createConnectionsForRoomId builds static connections without a restart)
matrixAppservice.plug.yaml (consumer)§8.1EXISTS: required unless external registration vars are pasted
matrix.plug.yaml (room + inviter)§8.1EXISTS: carries the §11.2 “recommendation taken” note
hookshot-init (passkey assert, invite + read-back, masked URL print)§8.1 jobsEXISTS; never executed against a live stack
glitchtip webhook.plug.yaml§8.3UNBUILT: gated on the SSRF posture call and §11.1
wazuh matrix.plug.yaml + baked custom-shc-webhook§8.3 / §9.1UNBUILT: phase 0
gitlab matrix.plug.yaml (native integration via API)§8.3 / §9.1UNBUILT: phase 0
uptime-kuma§6.4correctly untouched

The build-nothing rule this lane observed: with C7/§11.1–11.4 owed, adding any of the three UNBUILT rows would widen the very surface the rulings are about. The landed provider half is a fact to rule with, not a licence to continue.


4. What remains unmeasured: the exact list

Section titled “4. What remains unmeasured: the exact list”

Platform (upstream) unknowns:

  1. §10 row 6: the provisioning API (src/api/, the widget provisioner) is unread. Static connections are proven sufficient (M2), so this stays a phase-2 revision question, not a gate.
  2. §10 row 7: MSC4190 support (grep -rn msc4190 src/ at the pin). Gates encryption only; nothing queued needs it.
  3. onRoomInvite auto-accept under a rendered permissions block: source-read (five joinRoom retries behind the permission gate), never observed. It is the load-bearing assumption of hookshot-init.
  4. The html arm and the fenced-JSON-dump arm of transformHookData: the {"text": …} arm is measured; the other two render paths are not.
  5. enableHttpGet: false → GET answers 405 (§9.2 acceptance item 6): asserted from source, not exercised.

SHC-side unknowns (all one family: the package has never been deployed):

  1. The full §9.2 acceptance ladder as an shc install: boot render of config.yml/registration.yml from socket data, passkey autogeneration + RSA assert, the two-stack shc update → shc install ordering, the discovery probe, hookshot-init’s invite→auto-accept→read-back, and the idempotent re-run reading M_FORBIDDEN/“already in the room” as converged.
  2. A derived stateKey answering live. The lab’s hookId was hand-written; the HMAC/uuidshape recipe is held identical across its four sites by a bats guard, but a URL derived by the recipe has never been POSTed to a bridge whose config rendered the same recipe. This is the one seam of the zero-touch story with no runtime evidence at all.
  3. GlitchTip plug auth bootstrap. M3 read the AlertRecipient surface, not the APIToken minting surface, how a plug job obtains a project:write token headlessly (glitchtip-init’s manage.py shell pattern is the likely vehicle) is unread and undesigned.
  4. GlitchTip end-to-end delivery: “send test notification” → room, on whichever SSRF posture is ruled.
  5. Two consumers sharing the one registration on a live matrix stack (§2.4): never attempted anywhere.

Ready now: every platform question phase 0 depends on is measured; the phase-0 deliverables (wazuh, gitlab) depend on none of the open unknowns above and are gated only on ruling §11.1.

Gated on rulings: §11.1 (sequencing + whether the landed package earns its proving deployment), §11.2 (formal blessing of the taken recommendation), §11.3 (tier placement of an already-landed package), §11.4 (now with two catalog consumers standing on one registration).

Gated on the SSRF posture call (operator, §6.1): the GlitchTip edge: public urlBase on the hookshot stack vs GLITCHTIP_ALLOW_PRIVATE_IPS on the glitchtip stack. M3 hardened this: the wrong posture now fails loudly at recipient creation instead of silently at send.

Not gating anything: rows 6 and 7, the html/JSON render arms, MSC4190; each is attached to work nobody has queued.


This lane ran no new containers. The three §10 unknowns were already measured by the sibling lane whose evidence is committed in evidence/2026-08-10-hookshot-unknowns/, so re-running the Synapse lab could only have produced a second copy of the same logs. What this lane did instead:

  • read the committed evidence against the claims it supports (the stub transaction log, the Synapse Loaded application service lines (both url values), the hookshot boot log’s (via static config) / Found 1 connections lines, the room-state enumeration, and the 202/404 contrast) and found every §12 claim carried by a log line in the directory;
  • independently re-verified §12.3, the one source-read-only measurement, from a fresh v6.2.5 clone: reverify-glitchtip-v625.md, zero corrections;
  • confirmed the lab is destroyed, as §12 asserts: docker ps -a matches no valab*/synapse/hookshot container and docker network ls matches no valab network on this box;
  • checked the catalog state the proposal describes, which is what turned up §0: the provider half had landed while the proposal still said nothing existed.

★ The correction in §0 is the finding this lane contributes that no measurement could have: the proposal and the catalog had drifted apart, and a ruling made against the proposal’s stated status would have been made against a state of the world that ended on 2026-08-09.