@open-everywhere/core 0.1.0

package/dist/agent/webhooks/source-vocabulary.d.ts

@@ -0,0 +1,131 @@
+import { type WebhookVerifier } from "./verifier.js";
+/** The shared shape both vocabularies take. Injectable so the derivation LOGIC is unit-testable
+ *  against synthetic registries; the LIVE answer is measured by
+ *  `scripts/webhook-source-vocabulary-live-test.ts`. */
+export interface SourceVocabularyDeps {
+    readonly verifiers?: () => readonly WebhookVerifier[];
+    readonly normalizers?: () => readonly string[];
+    readonly declared?: () => readonly string[] | undefined;
+}
+/**
+ * The sources a hook may NAME on this deployment at all, sorted — question (1) in the header.
+ *
+ * (registered verifiers ∩ registered normalizers) ∩ the operator's optional narrowing. NO key-family
+ * condition: a member of this set whose verifier is `vendor-issued` or asymmetric is perfectly
+ * declarable, it just has to name a `broker` whose value an operator sets rather than one this
+ * deployment mints. That is not a workaround — `docs/extending/webhook-ingress.md` §5 calls it the
+ * general case ("Build for vendor-issued as the general case, and route it through config"), and the
+ * 20-vendor survey recorded there found only 3 of 20 vendors let the receiver choose the secret.
+ *
+ * 🔴 IT IS STILL A REFUSAL AND STILL FAIL-CLOSED. Both remaining conditions are the ones whose
+ * absence is silent and permanent (a 401 forever, or a hook nothing can subscribe to), and neither
+ * is waived anywhere. A source outside THIS set needs a merged PR exactly as before, and no click of
+ * any tier substitutes for one.
+ */
+export declare function declarableSourceVocabulary(deps?: SourceVocabularyDeps): readonly string[];
+/**
+ * The GENERAL-PURPOSE contracts among the declarable sources, sorted — the ones where WE define the
+ * envelope and the sender implements it, so anything a caller controls or can script can speak one.
+ *
+ * DERIVED FROM `provider` BEING ABSENT, which is already the structural signal for exactly this:
+ * `WebhookVerifier.provider` is set iff the entry belongs to a vendor BUNDLE and is gated by that
+ * bundle's selection, and core's own contract deliberately leaves it unset (verifier.ts says so in
+ * those words). So "not a named vendor's scheme" needs no second registry and no new flag.
+ *
+ * Exists because the alternative was worse: the hint in `tools/declare_webhook.ts` used to offer the
+ * whole vocabulary as general-purpose contracts, which named `github` — advice that would have a CI
+ * job try to sign the way GitHub signs.
+ */
+export declare function generalPurposeSchemes(deps?: SourceVocabularyDeps): readonly string[];
+/**
+ * The sources a hook may name on THIS deployment **and have its key MINTED for**, sorted.
+ *
+ * Composed, never hand-listed: (registered verifiers that accept an OE-minted key ∩ registered
+ * normalizers) ∩ the operator's optional narrowing. Every input is already a reviewed, merged fact —
+ * a provider bundle's registration, a declared field on a verifier, or a config array — so this
+ * function invents nothing.
+ *
+ * `verifiers` yields the VERIFIER ENTRIES, not their keys, because the key-family condition is a
+ * property of the entry — keys alone would make that condition unexpressible.
+ *
+ * ⚠️ NAMED FOR THE CONDITION IT ENFORCES, NOT FOR A HOOK CLASS (OPE-230). It was
+ * `runtimeHookSourceVocabulary` while a "runtime" hook class existed — a hook minted from a card,
+ * deleted by OPE-224 — and the name outlived the thing. `mintable` is the honest word because the
+ * third condition IS mintability (`acceptsMintedSecret`): this set is the sources for which THIS
+ * deployment can produce a key that will actually authenticate.
+ *
+ * ⚠️ AND SINCE OPE-238 THE NAME IS LOAD-BEARING, NOT MERELY HONEST. This is the answer to "may WE
+ * hold the key", which is the question a `broker: "db"` declaration asks and the only question it is
+ * entitled to decide. It is NOT the answer to "may this hook exist" — that is
+ * {@link declarableSourceVocabulary}, and asking this one in its place is the defect OPE-238 fixed.
+ */
+export declare function mintableSourceVocabulary(deps?: SourceVocabularyDeps): readonly string[];
+/**
+ * The refusal copy for a source outside the vocabulary — the ONLY place a caller learns the legal
+ * set, so the error message IS the vocabulary (the house pattern: `create_routine` does the same
+ * for filter keys, and for the same reason — a static tool description cannot read a registry).
+ *
+ * It names the PR path explicitly rather than gesturing at one, because "an admin needs to add
+ * this" without saying WHAT to add is the shape of a dead end.
+ *
+ * 🔴 THE VENDOR-ISSUED SENTENCE IS STILL UNCONDITIONAL (OPE-207), BUT IT NO LONGER SAYS "NEVER"
+ * (OPE-238). OPE-207 deleted a branch here for a reason that was right at the time and is worth
+ * keeping: *copy that branches on a capability no caller can reach is the worst kind, because a
+ * reader cannot tell it from a live one.* The branch it deleted offered a "paste the vendor's secret"
+ * arm that no deployment had ever declared itself into.
+ *
+ * What changed is the PREMISE, not the principle. OPE-207's antecedent was "there is no arm through
+ * which chat can set up a key a vendor generates" — true while the only creating path MINTED. The
+ * only creating path is now `tools/declare_webhook.ts`, whose `secretHome` DEFAULTS to `"env"`, i.e.
+ * the operator-sets-the-value arm is not merely reachable, it is the default. So the sentence stays
+ * unconditional (no branch, one spelling, always shown) and states the fact that is now true: such a
+ * source can be declared, but its secret is never one we issue. Nothing here branches on anything.
+ */
+export declare function unknownSourceRefusal(source: string, vocabulary: readonly string[]): string;
+/**
+ * 🔴 THE REFUSAL THAT NAMES A LIVE ESCAPE INSTEAD OF POINTING AT ITSELF (OPE-238) — for a source that
+ * IS declarable but whose key this deployment cannot mint, asked for with `secretHome: "db"`.
+ *
+ * This is the case that produced the ticket. It used to fall through {@link unknownSourceRefusal},
+ * whose closing line sent the caller away to have "an operator declare the hook in configuration
+ * instead" — which is precisely what `declare_webhook` does. The requester was told to go and use the
+ * tool they were already using, and the one field that would have worked was never mentioned.
+ *
+ * So the copy's whole job is the opposite: name the field, name the variable, and say what the
+ * operator does with it. The escape is one parameter away and reachable from this same call, so the
+ * message must be actionable without a code change, a PR for one, or a second person — the config PR
+ * this tool already opens is the only merge involved, exactly as for any other declaration.
+ *
+ * PURE and exported so a test pins the words. A refusal that points at a dead end is a class of bug
+ * no gate catches: everything type-checks, nothing throws, and the only evidence is the sentence.
+ */
+export declare function unmintableSourceRefusal(source: string, envRef: string): string;
+/**
+ * 🔴 THE SAME FACT, SAID AT THE MINT SITE, TO SOMEBODY WHO ALREADY HAS A MERGED DECLARATION (OPE-244)
+ * — for an EXISTING `broker: "db"` hook whose source signs with a key the vendor issues.
+ *
+ * WHY IT IS NOT {@link unmintableSourceRefusal}. That message's whole escape is *"ask me again with
+ * `secretHome: "env"`"*, and there is nothing to ask again here: the hook exists, in a file a human
+ * merged, and the person reading this clicked approve on a card. Handing them a parameter for a call
+ * they are not making is the dead-end shape OPE-238 exists to prevent, wearing different words. So
+ * this one names the DECLARATION change and who performs it, which is the only action that exists at
+ * this point in the flow.
+ *
+ * ⭐ IT SAYS "PR" ON PURPOSE, where {@link unmintableSourceRefusal} deliberately must not. There the
+ * fix was one field in the same conversation and mentioning a merge would have overstated the cost;
+ * here the thing to change is config, and config is only ever changed by a merged diff — so omitting
+ * it would understate the cost instead. Same principle, opposite word, and a test pins each.
+ *
+ * ⚠️ IT DOES NOT CLAIM `broker: "db"` IS MEANINGLESS FOR SUCH A SOURCE — only that WE cannot produce
+ * the value. A vendor-issued secret sitting in a home this deployment can read verifies perfectly;
+ * what is impossible is CHOOSING it. Writing the stronger sentence would have been a claim about
+ * which homes can be armed and by what, which is not a fact this module holds — and it would be the
+ * first thing to go false if a capture path ever writes a declared hook's ref (`webhooks/handshake-
+ * capture.ts` already does exactly that for Notion, under a reserved namespace and outside the
+ * declared-hook plane).
+ *
+ * PURE and exported so a test pins the words, for the reason its sibling gives: a refusal that points
+ * nowhere type-checks, throws nothing, and leaves the sentence as the only evidence.
+ */
+export declare function unmintableRotationRefusal(hookId: string, source: string, ref: string): string;
+//# sourceMappingURL=source-vocabulary.d.ts.map

package/dist/agent/webhooks/source-vocabulary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-vocabulary.d.ts","sourceRoot":"","sources":["../../../agent/webhooks/source-vocabulary.ts"],"names":[],"mappings":"AAoIA,OAAO,EAAmD,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC;AAGtG;;wDAEwD;AACxD,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,SAAS,eAAe,EAAE,CAAC;IACtD,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,SAAS,MAAM,EAAE,CAAC;IAC/C,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;CACzD;AAyBD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,GAAE,oBAAyB,GAAG,SAAS,MAAM,EAAE,CAE7F;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,GAAE,oBAAyB,GAAG,SAAS,MAAM,EAAE,CAGxF;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,GAAE,oBAAyB,GAAG,SAAS,MAAM,EAAE,CAE3F;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAe1F;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAQ9E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAU7F"}

package/dist/agent/webhooks/source-vocabulary.js

@@ -0,0 +1,315 @@
+// THE WEBHOOK SOURCE VOCABULARIES (OPE-159) — which `source` a hook may name on THIS deployment,
+// and separately, which of those this deployment can MINT A KEY FOR.
+//
+// The admin decision is the SOURCE CLASS, made once in a merged diff. Once a source is admissible,
+// the tenth hook from it costs no further click: there is nothing left for a per-instance approver
+// to decide that the registration did not already decide.
+//
+// ⚠️ THE APPROVER TIER IS NOT DECIDED HERE, AND DELIBERATELY HAS NO HOME OF ITS OWN (OPE-230). This
+// module used to export a `posture → tier` table that no production path ever called, because
+// `ApproverPolicy` is a PER-KIND CONSTANT on `ActionKind` (approvals/types.ts), read at click time
+// off the registered kind (`approvals/flow.ts`'s `resolveApprovalClick`) and never derived from a
+// pending row's args. A function from a per-INSTANCE property to that field cannot be honoured by
+// the approval plane at all — so shipping one asserted a control the plane structurally cannot
+// enforce. The tier now lives exactly where it takes effect, on each kind: `approvals/webhook.ts`
+// (`webhook.rotate`) and `approvals/webhook-declare.ts` (`webhook.declare`), each with its OWN
+// reason for `member`, and each reconciled against its `access/consequence.ts` row by
+// `checkConsequenceRegistry`'s action-kind arm. Two kinds, two arguments, two enforced spellings —
+// not one decision written twice.
+//
+// WHAT THE VOCABULARY DOES DECIDE ABOUT TIERS is the negative: it is a REFUSAL, never a tier. A
+// source outside it needs a merged PR, and no click of any tier can substitute for one.
+//
+// 🔴🔴 TWO QUESTIONS, TWO SETS, AND CONFLATING THEM WAS A REAL BUG (OPE-238). The questions are:
+//
+//   (1) CAN THIS DEPLOYMENT ACCEPT A DELIVERY ON THIS SOURCE AT ALL? — {@link declarableSourceVocabulary}.
+//   (2) CAN THIS DEPLOYMENT PRODUCE A KEY THE SOURCE WOULD ACCEPT? — {@link mintableSourceVocabulary}.
+//
+// (2) ⊂ (1), always: mintability is (1)'s conditions PLUS one more. The conditions are INDEPENDENT,
+// and the invariant is that satisfying one contributes NOTHING, because they are satisfied in
+// different places (a verifier usually ships in a provider bundle; a normalizer ships wherever the
+// payload shape is owned; the key-family condition is invisible in both registries and only a
+// declared field can express it). "Provider bundle X is selected" does not imply "source X is
+// mintable" (OPE-186).
+//
+// SET (1) — DECLARABLE. Both halves must be registered, or the hook is inert in one of two silent,
+// permanent ways:
+//   • a registered VERIFIER (webhooks/verifier.ts) — without one, every delivery 401s.
+//   • a registered NORMALIZER (routines/event-model.ts) — without one, nothing can ever subscribe:
+//     the hook authenticates and then dies at `normalizeDelivery` returning null.
+//   • …then the operator's optional narrowing, below.
+//
+// SET (2) — MINTABLE. All of the above, PLUS:
+//   • `acceptsMintedSecret` on that verifier — a minted key is the random secret
+//     `approvals/webhook.ts` produces, so a scheme keyed on a VENDOR-ISSUED token or on a public key
+//     can never authenticate one.
+//
+// 🔴 WHY THE THIRD CONDITION IS *NOT* AN EXISTENCE CONDITION, WHICH IS THE WHOLE OF OPE-238.
+// OPE-186's argument is intact and is not weakened by a single word here: a hook whose key WE minted,
+// on a scheme that cannot take one, is approved, revealed, and then 401s every delivery forever with
+// nothing in the flow explaining why. That argument has one antecedent — *we minted the key* — and it
+// is FALSE for `broker: "env"`, where the operator sets the value from whatever the vendor gave them
+// and no OE code path mints anything. The mint site enforces this from its own side: `webhook.rotate`
+// (approvals/webhook.ts) refuses any `broker !== "db"` hook by name, so there is provably no arm
+// through which an env-brokered hook acquires a minted key.
+//
+// 🔴 …AND THE ANTECEDENT IS NOW CHECKED AT THE MINT SITE TOO, WHICH IS OPE-244. Narrowing a check to
+// where its antecedent holds is only sound if something ENFORCES the antecedent, and until OPE-244
+// only half of it was enforced. `webhook.rotate` refused the wrong BROKER by name but never asked
+// about KEY PROVENANCE, so a hook a human hand-wrote into the hooks overlay as
+// `{ source: <vendor-issued>, broker: "db" }` was minted a random secret that could not verify a
+// single delivery — OPE-186's exact failure, on the one path where its antecedent genuinely holds.
+// The check below never ran on it, because `declare_webhook` is not the only author of a declaration:
+// a merged diff is. So `approvals/webhook.ts` now asks `acceptsMintedSecret` for itself, through
+// {@link unmintableRotationRefusal}, and the two sites answer to ONE predicate rather than one site
+// trusting the other to have asked.
+//
+// THAT IS NOT A SECOND COPY OF THE RULE, and the distinction is worth being exact about: this module
+// decides which sources may be NAMED (a set question, over registries); the mint site decides whether
+// THIS act may produce a key (an instance question, over one declaration). They share the predicate,
+// not the decision. A declaration reaches the mint site by routes that never touch a vocabulary at
+// all, and `webhooks/config.ts`'s validator deliberately cannot close the gap either — it runs at
+// module import, when no verifier has registered yet, so it checks the SHAPE of a hook and never its
+// source's registration (see `assertWebhooksValid`'s own note). A guard at the act is the only one
+// that sees an armed registry.
+//
+// Applying condition 3 to an env-brokered declaration therefore refused a hook that would have worked
+// perfectly — and refused it with copy telling the caller "an operator has to declare the hook in
+// configuration instead", which is the very thing `tools/declare_webhook.ts` does. The refusal pointed
+// at itself. Both vendor verifiers say in their own headers that an OPERATOR-DECLARED hook is their
+// intended use (notion-webhook-verifier.ts, slack-webhook-verifier.ts, each verbatim), and
+// `docs/extending/webhook-ingress.md` §5 has shipped the corrected rule as prose since OPE-224:
+// *"not may this exist, but may we be the one holding the key"*. The code was the half that never
+// followed.
+//
+// So condition 3 is asked EXACTLY WHERE ITS ANTECEDENT HOLDS — at `secretHome: "db"` — and nowhere
+// else. This is a NARROWING of where a check applies, not a relaxation of what it decides: no source
+// that could not previously hold a minted key can hold one now.
+//
+// 🔴 HTTP-ORIGIN ALLOWLISTING IS NOT DEFERRED WORK AND NOTHING HERE IS A PLACEHOLDER FOR IT. The
+// per-hook shared secret already IS the origin control and is strictly stronger — the verifier HMACs
+// the RAW BODY (webhooks/gate.ts), cryptographically binding every accepted delivery to whoever
+// holds THAT hook's secret. `Origin`, vendor marker headers and source-IP ranges are each either
+// absent on every legitimate delivery or supplied by the attacker. Full argument:
+// a design note §6.1.
+//
+// THE OPTIONAL NARROWING (`loadWebhookSources`) is the operator's own further restriction on top,
+// and it governs BOTH sets — deliberately, and it is the one place OPE-238 chose the conservative
+// reading. An operator's list is "these are the source classes a conversation may name", which is a
+// question about the DECLARATION and not about who holds the key; dropping it for the env arm would
+// have let chat name a source the operator had explicitly excluded. It is NARROWING-ONLY, so
+// applying it to the wider set can never widen anything. Absent means
+// PERMISSIVE-WITHIN-WHAT-IS-REGISTERED, matching every other optional loader on the app-config seam
+// (`loadWebhooks`, `loadSpendBudgets`, `loadModelPolicy`).
+//
+// A BARE SIGNATURE SCHEME IS NEVER MINTABLE HERE, AND A NORMALIZER FOR ONE IS NOT THE FIX: a
+// signature scheme names how bytes were SIGNED, not an event vocabulary, so there is no payload
+// shape to normalize and a normalizer would have to invent one. A contract WE DEFINE is different in
+// kind — we specify the ENVELOPE too, so the normalizer is ours to write and it reads fields we
+// published; `webhooks/oe-standard-webhook.ts` is that contract and states the inversion in full.
+// Register a bare signature scheme and it belongs on the CONFIG hook path, where an operator's
+// merged declaration supplies the meaning the scheme cannot.
+//
+// ⚠️ THE REPLAY POSTURE IS TWO INDEPENDENT LAYERS, AND A SOURCE GETS EACH ONLY ON A CONDITION:
+//
+//   1. THE DURABLE DELIVERY DEDUPE (`routines/ingress.ts`) — armed iff the source's NORMALIZER
+//      declares a `deliveryIdHeader` and the sender actually sent it. TTL-windowed, FAIL-OPEN on a
+//      store error, and its own module doc declines to call it a security boundary ("dedupe prevents
+//      an annoyance (a double fire), not a security boundary"). Best-effort.
+//   2. THE SIGNED SINGLE-USE 409 (`webhooks/replay-dedupe.ts`) — armed iff the source's VERIFIER
+//      declares `signedTimestamp: true`, because `gate.ts` strips `replayKey` otherwise. This is the
+//      real bound.
+//
+// So the honest statement is now PER SOURCE, not global: every mintable source has the best-effort
+// bound (layer 1 is asserted for all of them), and AT LEAST ONE — but NOT necessarily the one you
+// are looking at — also has the signed single-use bound. Which sources have
+// layer 2 is a fact about registry state, so it is MEASURED rather than written here:
+// `scripts/webhook-source-vocabulary-live-test.ts` measures both conditions against the live
+// registries, names which sources hold layer 2, and fails if these sentences and the code part
+// company. Any specific claim here about WHICH vendors are in the vocabulary would be a fact about a
+// registry state written once and never measured — which is exactly how an earlier version of this
+// paragraph came to be false.
+import { getConfig } from "../access/config.js";
+import { acceptsMintedSecret, registeredWebhookVerifiers } from "./verifier.js";
+import { registeredEventSources } from "../routines/event-model.js";
+/**
+ * 🔴 EVERY CONDITION, IN ONE PLACE, so nothing can be added that routes around any of them — and so
+ * the two vocabularies cannot drift into two derivations. They are the header's, in the header's
+ * order: key provenance (mintable only), a normalizer, the operator's narrowing.
+ *
+ * `requireMintable` is the ONLY difference between the two sets, which is what makes
+ * `mintable ⊆ declarable` a property of the code rather than a comment.
+ */
+function admissibleSchemes(deps, requireMintable) {
+    const verifiers = (deps.verifiers ?? registeredWebhookVerifiers)();
+    const normalizers = new Set((deps.normalizers ?? registeredEventSources)());
+    const declared = (deps.declared ?? (() => getConfig().loadWebhookSources?.()))();
+    const narrowing = declared === undefined ? undefined : new Set(declared);
+    const out = new Set();
+    for (const v of verifiers) {
+        if (requireMintable && !acceptsMintedSecret(v))
+            continue;
+        if (!normalizers.has(v.source))
+            continue;
+        if (narrowing && !narrowing.has(v.source))
+            continue;
+        out.add(v.source);
+    }
+    return [...out].sort();
+}
+/**
+ * The sources a hook may NAME on this deployment at all, sorted — question (1) in the header.
+ *
+ * (registered verifiers ∩ registered normalizers) ∩ the operator's optional narrowing. NO key-family
+ * condition: a member of this set whose verifier is `vendor-issued` or asymmetric is perfectly
+ * declarable, it just has to name a `broker` whose value an operator sets rather than one this
+ * deployment mints. That is not a workaround — `docs/extending/webhook-ingress.md` §5 calls it the
+ * general case ("Build for vendor-issued as the general case, and route it through config"), and the
+ * 20-vendor survey recorded there found only 3 of 20 vendors let the receiver choose the secret.
+ *
+ * 🔴 IT IS STILL A REFUSAL AND STILL FAIL-CLOSED. Both remaining conditions are the ones whose
+ * absence is silent and permanent (a 401 forever, or a hook nothing can subscribe to), and neither
+ * is waived anywhere. A source outside THIS set needs a merged PR exactly as before, and no click of
+ * any tier substitutes for one.
+ */
+export function declarableSourceVocabulary(deps = {}) {
+    return admissibleSchemes(deps, false);
+}
+/**
+ * The GENERAL-PURPOSE contracts among the declarable sources, sorted — the ones where WE define the
+ * envelope and the sender implements it, so anything a caller controls or can script can speak one.
+ *
+ * DERIVED FROM `provider` BEING ABSENT, which is already the structural signal for exactly this:
+ * `WebhookVerifier.provider` is set iff the entry belongs to a vendor BUNDLE and is gated by that
+ * bundle's selection, and core's own contract deliberately leaves it unset (verifier.ts says so in
+ * those words). So "not a named vendor's scheme" needs no second registry and no new flag.
+ *
+ * Exists because the alternative was worse: the hint in `tools/declare_webhook.ts` used to offer the
+ * whole vocabulary as general-purpose contracts, which named `github` — advice that would have a CI
+ * job try to sign the way GitHub signs.
+ */
+export function generalPurposeSchemes(deps = {}) {
+    const byName = new Map((deps.verifiers ?? registeredWebhookVerifiers)().map((v) => [v.source, v]));
+    return declarableSourceVocabulary(deps).filter((s) => byName.get(s)?.provider === undefined);
+}
+/**
+ * The sources a hook may name on THIS deployment **and have its key MINTED for**, sorted.
+ *
+ * Composed, never hand-listed: (registered verifiers that accept an OE-minted key ∩ registered
+ * normalizers) ∩ the operator's optional narrowing. Every input is already a reviewed, merged fact —
+ * a provider bundle's registration, a declared field on a verifier, or a config array — so this
+ * function invents nothing.
+ *
+ * `verifiers` yields the VERIFIER ENTRIES, not their keys, because the key-family condition is a
+ * property of the entry — keys alone would make that condition unexpressible.
+ *
+ * ⚠️ NAMED FOR THE CONDITION IT ENFORCES, NOT FOR A HOOK CLASS (OPE-230). It was
+ * `runtimeHookSourceVocabulary` while a "runtime" hook class existed — a hook minted from a card,
+ * deleted by OPE-224 — and the name outlived the thing. `mintable` is the honest word because the
+ * third condition IS mintability (`acceptsMintedSecret`): this set is the sources for which THIS
+ * deployment can produce a key that will actually authenticate.
+ *
+ * ⚠️ AND SINCE OPE-238 THE NAME IS LOAD-BEARING, NOT MERELY HONEST. This is the answer to "may WE
+ * hold the key", which is the question a `broker: "db"` declaration asks and the only question it is
+ * entitled to decide. It is NOT the answer to "may this hook exist" — that is
+ * {@link declarableSourceVocabulary}, and asking this one in its place is the defect OPE-238 fixed.
+ */
+export function mintableSourceVocabulary(deps = {}) {
+    return admissibleSchemes(deps, true);
+}
+/**
+ * The refusal copy for a source outside the vocabulary — the ONLY place a caller learns the legal
+ * set, so the error message IS the vocabulary (the house pattern: `create_routine` does the same
+ * for filter keys, and for the same reason — a static tool description cannot read a registry).
+ *
+ * It names the PR path explicitly rather than gesturing at one, because "an admin needs to add
+ * this" without saying WHAT to add is the shape of a dead end.
+ *
+ * 🔴 THE VENDOR-ISSUED SENTENCE IS STILL UNCONDITIONAL (OPE-207), BUT IT NO LONGER SAYS "NEVER"
+ * (OPE-238). OPE-207 deleted a branch here for a reason that was right at the time and is worth
+ * keeping: *copy that branches on a capability no caller can reach is the worst kind, because a
+ * reader cannot tell it from a live one.* The branch it deleted offered a "paste the vendor's secret"
+ * arm that no deployment had ever declared itself into.
+ *
+ * What changed is the PREMISE, not the principle. OPE-207's antecedent was "there is no arm through
+ * which chat can set up a key a vendor generates" — true while the only creating path MINTED. The
+ * only creating path is now `tools/declare_webhook.ts`, whose `secretHome` DEFAULTS to `"env"`, i.e.
+ * the operator-sets-the-value arm is not merely reachable, it is the default. So the sentence stays
+ * unconditional (no branch, one spelling, always shown) and states the fact that is now true: such a
+ * source can be declared, but its secret is never one we issue. Nothing here branches on anything.
+ */
+export function unknownSourceRefusal(source, vocabulary) {
+    // The key-provenance condition is still named, because it still changes what the admin gets: doing
+    // the work lands the source in the DECLARABLE set but never in the mintable one, so the hook will
+    // want an operator-set secret forever. Saying so costs one sentence and saves a merged PR whose
+    // author expected `rotate_webhook` to work on it.
+    return (`"${source}" isn't a webhook source this deployment can accept. ` +
+        (vocabulary.length > 0 ? `Available right now: ${vocabulary.join(", ")}. ` : `No sources are available on this deployment yet. `) +
+        `Adding one isn't something I can do from here — it needs a code change an admin merges: the source needs a ` +
+        `signature verifier (so deliveries can be authenticated) and an event normalizer (so routines can subscribe to it), ` +
+        `and for a vendor we already support that usually just means selecting its provider bundle. ` +
+        `Some systems sign with a secret THEY generate rather than one we choose — once one of those has both halves it can be declared ` +
+        `normally, but its secret has to be set by an operator (\`secretHome: "env"\`) because I can never issue that kind myself. ` +
+        `Ask an admin to open that PR.`);
+}
+/**
+ * 🔴 THE REFUSAL THAT NAMES A LIVE ESCAPE INSTEAD OF POINTING AT ITSELF (OPE-238) — for a source that
+ * IS declarable but whose key this deployment cannot mint, asked for with `secretHome: "db"`.
+ *
+ * This is the case that produced the ticket. It used to fall through {@link unknownSourceRefusal},
+ * whose closing line sent the caller away to have "an operator declare the hook in configuration
+ * instead" — which is precisely what `declare_webhook` does. The requester was told to go and use the
+ * tool they were already using, and the one field that would have worked was never mentioned.
+ *
+ * So the copy's whole job is the opposite: name the field, name the variable, and say what the
+ * operator does with it. The escape is one parameter away and reachable from this same call, so the
+ * message must be actionable without a code change, a PR for one, or a second person — the config PR
+ * this tool already opens is the only merge involved, exactly as for any other declaration.
+ *
+ * PURE and exported so a test pins the words. A refusal that points at a dead end is a class of bug
+ * no gate catches: everything type-checks, nothing throws, and the only evidence is the sentence.
+ */
+export function unmintableSourceRefusal(source, envRef) {
+    return (`I can declare a "${source}" webhook, but not with \`secretHome: "db"\`. ` +
+        `"${source}" signs with a secret IT generates and hands to you, so a secret minted here would never verify a single delivery — ` +
+        `the hook would be approved, its secret revealed, and then every delivery would 401 forever with nothing saying why. ` +
+        `Ask me again with \`secretHome: "env"\` and this works: the declaration names the variable \`${envRef}\`, an operator puts ` +
+        `the value "${source}" gave them into it and redeploys, and the hook authenticates. Nothing else about the request has to change.`);
+}
+/**
+ * 🔴 THE SAME FACT, SAID AT THE MINT SITE, TO SOMEBODY WHO ALREADY HAS A MERGED DECLARATION (OPE-244)
+ * — for an EXISTING `broker: "db"` hook whose source signs with a key the vendor issues.
+ *
+ * WHY IT IS NOT {@link unmintableSourceRefusal}. That message's whole escape is *"ask me again with
+ * `secretHome: "env"`"*, and there is nothing to ask again here: the hook exists, in a file a human
+ * merged, and the person reading this clicked approve on a card. Handing them a parameter for a call
+ * they are not making is the dead-end shape OPE-238 exists to prevent, wearing different words. So
+ * this one names the DECLARATION change and who performs it, which is the only action that exists at
+ * this point in the flow.
+ *
+ * ⭐ IT SAYS "PR" ON PURPOSE, where {@link unmintableSourceRefusal} deliberately must not. There the
+ * fix was one field in the same conversation and mentioning a merge would have overstated the cost;
+ * here the thing to change is config, and config is only ever changed by a merged diff — so omitting
+ * it would understate the cost instead. Same principle, opposite word, and a test pins each.
+ *
+ * ⚠️ IT DOES NOT CLAIM `broker: "db"` IS MEANINGLESS FOR SUCH A SOURCE — only that WE cannot produce
+ * the value. A vendor-issued secret sitting in a home this deployment can read verifies perfectly;
+ * what is impossible is CHOOSING it. Writing the stronger sentence would have been a claim about
+ * which homes can be armed and by what, which is not a fact this module holds — and it would be the
+ * first thing to go false if a capture path ever writes a declared hook's ref (`webhooks/handshake-
+ * capture.ts` already does exactly that for Notion, under a reserved namespace and outside the
+ * declared-hook plane).
+ *
+ * PURE and exported so a test pins the words, for the reason its sibling gives: a refusal that points
+ * nowhere type-checks, throws nothing, and leaves the sentence as the only evidence.
+ */
+export function unmintableRotationRefusal(hookId, source, ref) {
+    return (`I can't issue a secret for "${hookId}" — it declares \`source: "${source}"\`, and "${source}" signs with a secret IT generates ` +
+        `and hands to you. Anything minted here would be a value "${source}" has never seen, so the secret would be revealed once and then ` +
+        `every delivery would 401 forever with nothing saying why. Nothing was minted and nothing changed. ` +
+        `The fix is one line in the declaration, by PR: give it \`broker: "env"\` with \`secretRef\` naming an environment variable ` +
+        `(it names \`${ref}\` today), then an operator sets that variable to the value "${source}" gave them and redeploys, and the hook ` +
+        `authenticates. If the value already lives in a home this deployment can read, name THAT home as the \`broker\` instead — ` +
+        `what I can never do is choose the value myself.`);
+}
+//# sourceMappingURL=source-vocabulary.js.map

package/dist/agent/webhooks/source-vocabulary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-vocabulary.js","sourceRoot":"","sources":["../../../agent/webhooks/source-vocabulary.ts"],"names":[],"mappings":"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"}