@open-everywhere/core 0.1.0

package/dist/agent/webhooks/verifier.d.ts

@@ -0,0 +1,251 @@
+/** What a verifier is handed. DELIBERATELY has no `signatureHeader`, and no `parsed`/`json`. */
+export interface WebhookVerifyInput {
+    /**
+     * The EXACT bytes as received — the single `await req.text()` of the ingress, never a
+     * reserialised parse. Re-serialising JSON changes key order, float spelling, escape form and
+     * whitespace, so every vendor scheme breaks on it (Notion, verbatim: *"Pass the raw request
+     * body exactly as it arrived (re-serialized JSON produces different bytes and fails
+     * verification)"*). The invariant is pinned by tests, not by this comment.
+     */
+    readonly rawBody: string;
+    /**
+     * The FULL request headers. A verifier picks its OWN names — there is no "the signature
+     * header" to pre-extract: Linear's freshness timestamp is not in a header at all, and Stripe
+     * packs a timestamp AND N signatures into one. Narrowing this to a single string was the
+     * lowest-common-denominator trap, refuted by three real vendors.
+     */
+    readonly headers: Headers;
+    /**
+     * Ordered candidate keys, CURRENT FIRST, then any previous keys during a rotation overlap
+     * (`webhooks/secrets.ts` resolveHookKeys). A shared secret for `keyKind: "shared-secret"`, a
+     * public key / app identifier for `"public-key"`. Never empty — the gate rejects a keyless
+     * hook before a verifier is ever called.
+     */
+    readonly keys: readonly string[];
+    /** Injected clock (epoch ms), so skew windows are unit-testable without faking Date. */
+    readonly nowMs: number;
+}
+/** Why a verification failed — a closed set, so the 401 reason can never carry vendor detail. */
+export type WebhookVerifyFailure = "missing-signature" | "malformed-signature" | "signature-mismatch" | "missing-timestamp" | "malformed-timestamp" | "stale-timestamp" | "unsupported-scheme";
+/** `keyIndex > 0` ⇒ the delivery verified against a PREVIOUS key (a live rotation overlap) and
+ *  is audited as such — the operator's "the old key is still in use" signal.
+ *
+ *  `replayKey` (OPE-176) — an OPAQUE, already-hashed nonce identity for the durable single-use
+ *  dedupe store (webhooks/replay-dedupe.ts), set ONLY by a verifier whose {@link
+ *  WebhookVerifier.signedTimestamp} is true. (WHICH sources those are is registry state and is
+ *  deliberately not written down here — it was, as "currently just `oe-standard-webhook`", and
+ *  OPE-197 falsified it by registering a second one. `scripts/webhook-source-vocabulary-live-test.ts`
+ *  MEASURES the set instead.) The gate (webhooks/gate.ts)
+ *  enforces this itself — it strips `replayKey` from the outcome unless the RESOLVED verifier
+ *  declares `signedTimestamp: true`, so a careless or malicious `signedTimestamp: false` verifier
+ *  cannot smuggle dedupe protection it has no freshness claim to back (an untimestamped source's
+ *  replay window would then be bounded only by an ARBITRARY retention policy dressed up as a real
+ *  guarantee — see the module doc on webhooks/replay-dedupe.ts for why that was rejected). A
+ *  `signedTimestamp: true` verifier that forgets to set `replayKey` on an accepted verdict silently
+ *  loses dedupe for its source — pinned by a test per verifier, not caught structurally here. */
+export type WebhookVerdict = {
+    readonly ok: true;
+    readonly keyIndex: number;
+    readonly replayKey?: string;
+} | {
+    readonly ok: false;
+    readonly failure: WebhookVerifyFailure;
+};
+/**
+ * ⭐ HOW A HUMAN MAKES A SENDER SPEAK THIS SCHEME — structured, never HTML, and rendered by whoever
+ * is showing it (today: `webhooks/reveal-page.ts`, beside the secret it belongs to).
+ *
+ * 🔴 IT LIVES ON THE VERIFIER, NOT IN THE PAGE, because it and {@link verify} are one fact stated
+ * twice — the verifier says what is ACCEPTED, this says what to SEND — and the facts are unguessable
+ * and PER SCHEME (two registered schemes typically agree on no header name, no signed content and no
+ * digest encoding, so one generic paragraph would be wrong for one of them). Any other home drifts
+ * the first time a scheme changes, and drift here is SILENT: a sender follows stale instructions and
+ * gets a 401 with a deliberately reasonless body. `scripts/standard-webhook-test.ts` pins each field
+ * against the exported constants and basestring builders rather than against a copy of the words.
+ *
+ * OPTIONAL, and absence is meaningful rather than lazy: a `vendor-issued` scheme has no instructions
+ * WE are entitled to give (the vendor's own console is the interface, and its docs are authoritative
+ * about its own headers). A renderer shows nothing extra for such a scheme.
+ *
+ * 🔴 EVERY STRING HERE IS A TEMPLATE AND MUST STAY ONE. No live value, no secret, nothing
+ * request-derived. A renderer escapes these, but escaping is not confidentiality — the reason
+ * nothing sensitive is in here is that nothing sensitive is ever PUT in here.
+ */
+export interface WebhookSenderGuidance {
+    /** The headers a delivery must carry, in the order a human should read them. `value` describes the
+     *  SHAPE (`v1,<base64 signature>`), never an instance. */
+    readonly headers: readonly {
+        readonly name: string;
+        readonly value: string;
+    }[];
+    /** Exactly what the signature is computed over, written the way the basestring builder builds it. */
+    readonly signedContent: string;
+    /** One short sentence each: key derivation, digest encoding, freshness, replay. Rendered as a list. */
+    readonly notes: readonly string[];
+}
+/** One registered signature scheme. */
+export interface WebhookVerifier {
+    /** Registry key = exactly what a hook declares as its `source` (webhooks/config.ts). */
+    readonly source: string;
+    /** Set ⇒ this entry belongs to a provider BUNDLE and its registration is routed through
+     *  `admitProviderRegistration`, so a de-selected provider contributes nothing. Core's own
+     *  verifier leaves it UNSET — `"oe-standard-webhook"` will never appear in a deployment's provider
+     *  selection and must not be gated by it. */
+    readonly provider?: string;
+    /** `"shared-secret"` (HMAC-class) or `"public-key"` (Discord's Ed25519, a JWT issuer's key
+     *  identifier). The field exists so an asymmetric scheme is expressible without reshaping the
+     *  interface later — verified against Discord (Ed25519) and Teams (Bot Connector JWT). */
+    readonly keyKind: "shared-secret" | "public-key";
+    /**
+     * WHO CHOOSES THE KEY — the axis {@link keyKind} does NOT cover, and the one that decides whether
+     * a source's key can be MINTED BY THIS DEPLOYMENT at all (OPE-186).
+     *
+     *   • `"receiver-minted"` — the key is whatever the RECEIVING side puts into the sender's
+     *     configuration, so an arbitrary random secret works. That is the precondition a minted key
+     *     depends on: `approvals/webhook.ts` mints one with `mintSecret()` at the click and a human
+     *     pastes it into the sender.
+     *   • `"vendor-issued"` — the vendor GENERATES the key and hands it to us (Notion's one-time
+     *     `verification_token`; an asymmetric scheme's public key or JWKS). A secret WE minted can
+     *     never verify against it, so a hook that had its key minted here would 401 every delivery for
+     *     as long as it existed — and nothing downstream would say why.
+     *
+     * DECLARED, NOT INFERRED, and required — the {@link signedTimestamp} posture, for the same
+     * reason: the fact lives in a vendor's docs, so a field somebody had to fill in is the only place
+     * it can be reviewed. Read through {@link acceptsMintedSecret} by
+     * `webhooks/source-vocabulary.ts`, so a vendor-issued source is structurally ABSENT from what
+     * chat can mint rather than mintable-and-permanently-broken.
+     */
+    readonly keyOrigin: "receiver-minted" | "vendor-issued";
+    /**
+     * TRUE iff the scheme covers a timestamp AND this verifier enforces a skew window. This is a
+     * DECLARATION, allowlist-tested: a `false` means replay against that source is undefended, and
+     * saying so out loud turns an unwritten fact into a reviewed entry. Since OPE-176, `true` also
+     * turns the accepted verdict's `replayKey` into a durable single-use mark (webhooks/replay-
+     * dedupe.ts, keyed on the durable `markEventSeen` store — NOT `EventDedupe`, which is in-memory
+     * per instance and does not survive a cold start or a sibling instance). A `false` source stays
+     * bounded by nothing at all — see replay-dedupe.ts's module doc for why a vendor delivery id
+     * was rejected as a substitute bound for those.
+     */
+    readonly signedTimestamp: boolean;
+    /**
+     * Async so a JWKS-fetching (Teams-class) verifier fits. MUST NOT throw for a bad signature —
+     * a bad signature is `{ ok: false }`. A throw means a BROKEN verifier; the gate catches it and
+     * turns it into a 401 rather than a 500, so a broken verifier fails closed too.
+     *
+     * ORDERING RULE: a verifier may parse the body ONLY AFTER its digest matches. Parse-before-
+     * verify feeds attacker bytes to an unauthenticated parser. (Linear's scheme needs the body for
+     * its timestamp — it parses second, after the HMAC.)
+     */
+    verify(input: WebhookVerifyInput): Promise<WebhookVerdict> | WebhookVerdict;
+    /**
+     * ⭐ THIS SCHEME'S OWN SECRET FORMAT, when it has one — the minter `approvals/webhook.ts` uses at
+     * the approval click instead of its generic random.
+     *
+     * 🔴 WHY THE SCHEME OWNS THIS AND THE MINT SITE DOES NOT. A stored secret is a STRING; what a
+     * verifier HMACs is BYTES; and the function from one to the other is the scheme's, not the mint
+     * site's (`oe-standard-webhook`'s `standardWebhookKey` base64-decodes a `whsec_` secret and takes
+     * the UTF-8 bytes of anything else). A mint site that picked the string format would be choosing
+     * key material for a derivation it cannot see — the exact shape of a silent signature break.
+     *
+     * ABSENT ⇒ the generic random the mint site has always used. Absence is the DEFAULT, not a gap.
+     *
+     * ⚠️ RESOLVED THROUGH THIS REGISTRY, SO IT DEPENDS ON THE SCHEME'S MODULE BEING ARMED. An UNARMED
+     * registry degrades to the generic mint, which for `oe-standard-webhook` still verifies (its key
+     * rule accepts both forms), so the failure mode is a secret that loses a convention rather than a
+     * hook that cannot authenticate. Stated because the degradation is otherwise invisible;
+     * `scripts/standard-webhook-test.ts` pins the declaration.
+     *
+     * MUST return a fresh, high-entropy value per call — it is a KEY, not an identifier.
+     */
+    readonly mintSecret?: () => string;
+    /** What a human must make their sender send, for a scheme where we are entitled to say. See
+     *  {@link WebhookSenderGuidance} for why this is the verifier's to declare. */
+    readonly senderGuidance?: () => WebhookSenderGuidance;
+}
+/**
+ * Register (or replace) the verifier for one source. A verifier carrying `provider` is routed
+ * through the provider-selection gate first, so a de-selected bundle writes ZERO rows here and
+ * every hook declaring that source then fails closed at resolution — no new refusal path needed.
+ * Returns whether the row landed.
+ */
+export declare function registerWebhookVerifier(verifier: WebhookVerifier): boolean;
+/** The verifier for `source`, or `undefined` when none is registered — the caller (the gate)
+ *  turns that into a 401 naming the registered set. NEVER a fallback to another scheme. */
+export declare function webhookVerifier(source: string | undefined): WebhookVerifier | undefined;
+/** Every registered source, sorted — for the fail-closed refusal copy and the boundary guard. */
+export declare function registeredWebhookVerifierSources(): readonly string[];
+/** Every registered verifier — for the `signedTimestamp` allowlist guard and the vocabulary
+ *  derivation (`webhooks/source-vocabulary.ts`, which needs the ENTRIES, not just their keys). */
+export declare function registeredWebhookVerifiers(): readonly WebhookVerifier[];
+/**
+ * Can this scheme authenticate a delivery signed with a secret WE minted at random? (OPE-186)
+ *
+ * THE precondition for a hook whose key this deployment mints, which is always `approvals/webhook.ts`'s
+ * `mintSecret()` — never a value handed to us. BOTH clauses are load-bearing: an asymmetric scheme
+ * has no shared secret for us to mint even if something declared its key receiver-chosen, and a
+ * vendor-issued shared secret is a value we RECEIVE rather than choose.
+ *
+ * ONE definition, shared by the vocabulary derivation and the test that pins it against the live
+ * registries. Two copies of this predicate is precisely how the two would drift.
+ */
+export declare function acceptsMintedSecret(verifier: WebhookVerifier): boolean;
+/**
+ * ⭐⭐ THE AUTHENTICATION-STRENGTH LADDER (OPE-203) — how strongly a delivery was authenticated,
+ * as an ORDERED vocabulary, so a hook can declare a FLOOR and the gate can refuse anything under it.
+ *
+ * 🔴 THREE VALUES, EACH ANCHORED TO SOMETHING THAT ALREADY SHIPS. Nothing here is a new axis:
+ *
+ *   • `"unverified"`  — NO signature was checked at all. The delivery's only proof is possession of
+ *                       the hook URL. Reachable exactly once in this tree, through the local-dev
+ *                       hatch, and already named by `webhooks/gate.ts`'s {@link
+ *                       import("./gate.js").acceptedUnverified}.
+ *   • `"signed"`      — a signature verified against a resolvable key, on a scheme that covers NO
+ *                       timestamp. `signedTimestamp: false`. Ships today for github and notion.
+ *   • `"signed-fresh"`— the above PLUS a scheme-covered timestamp with an enforced skew window, i.e.
+ *                       {@link WebhookVerifier.signedTimestamp}. Ships today for
+ *                       `oe-standard-webhook` and (since OPE-197) slack. This is the SAME bit that
+ *                       already decides whether `gate.ts` lets `replayKey` through, which is the
+ *                       one live grade→consequence edge this ladder generalises.
+ *
+ * 🔴 WHAT IS DELIBERATELY *NOT* ON THE LADDER, because a ladder is a TOTAL ORDER and these are not
+ * points on one. Putting them here would be inventing an ordering nothing in the tree supports:
+ *
+ *   • {@link WebhookVerifier.keyKind} / {@link WebhookVerifier.keyOrigin} — WHO CHOOSES THE KEY, not
+ *     how well a delivery was authenticated. A `vendor-issued` key is not weaker than a
+ *     `receiver-minted` one; an asymmetric `public-key` scheme is arguably STRONGER, and no
+ *     registered verifier declares one today, so ordering it would be a guess dressed as a rule.
+ *     Those two axes have their own derived predicate — {@link acceptsMintedSecret} — answering
+ *     their own question, and that is the shape this one copies rather than absorbs.
+ *   • `keyIndex > 0` (a rotation-overlap acceptance) — KEY CURRENCY, orthogonal to scheme strength,
+ *     and the one fact here a SENDER picks: it chooses which key to sign with. A floor that moved
+ *     with it would be inferred from the delivery, which is the downgrade primitive this whole
+ *     design exists to refuse. It also stays audited-but-unconstraining by explicit decision
+ *     ("No auto-expiry rides on this", channels/webhooks.ts) and this ticket does not reopen that.
+ *
+ * PURE, TOTAL AND ORDERED BY INDEX. The array IS the order; a fourth grade is inserted at its rank
+ * and every comparison below follows, with no switch anywhere to forget to update.
+ */
+export type WebhookAuthGrade = "unverified" | "signed" | "signed-fresh";
+/** The ladder, WEAKEST FIRST. Order is semantic — {@link meetsWebhookAuthFloor} compares indices. */
+export declare const WEBHOOK_AUTH_GRADES: readonly WebhookAuthGrade[];
+/**
+ * THE STRONGEST GRADE ANY DELIVERY ON THIS SCHEME CAN EVER REACH — a derived predicate over the
+ * verifier's own declared strength fields, exactly as {@link acceptsMintedSecret} is.
+ *
+ * 🔴 IT IS A PROPERTY OF THE REGISTERED SCHEME, NOT OF A REQUEST, AND THAT IS THE WHOLE POINT. The
+ * input is the verifier the hook's DECLARED source resolved to (`webhooks/gate.ts`), never a header,
+ * never a verdict. So "how strong is this hook" has one answer for every delivery it will ever take,
+ * and a sender cannot move it in either direction by choosing what to send.
+ *
+ * NEVER RETURNS `"unverified"`: a resolved verifier means a signature WILL be checked. `unverified`
+ * is not a scheme's ceiling, it is what an acceptance that skipped the check attained — which is why
+ * the gate supplies that value from the hatch branch and this function cannot.
+ */
+export declare function webhookAuthCeiling(verifier: WebhookVerifier): WebhookAuthGrade;
+/** Is `achieved` at least as strong as `floor`? Index comparison over {@link WEBHOOK_AUTH_GRADES} —
+ *  ONE definition, shared by the gate's two refusal arms and the tests that pin them. */
+export declare function meetsWebhookAuthFloor(achieved: WebhookAuthGrade, floor: WebhookAuthGrade): boolean;
+/** Test seam: forget every registered verifier (mirrors resetCredentialHomes). No auto-restore —
+ *  a verifier module re-registers on its next load, and a test file owns its own process. */
+export declare function resetWebhookVerifiersForTest(): void;
+//# sourceMappingURL=verifier.d.ts.map

package/dist/agent/webhooks/verifier.d.ts.map

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

package/dist/agent/webhooks/verifier.js

@@ -0,0 +1,109 @@
+// The WEBHOOK VERIFIER REGISTRY (OPE-164) — WHICH signature scheme authenticates an inbound
+// delivery, resolved from the hook's DECLARED source, never sniffed off the request.
+//
+// WHAT IT BUYS: a hook can declare a VENDOR's source and be verified in that vendor's scheme, so one
+// generic ingress takes a third-party system's webhooks unmodified (one-ingress-per-system). Schemes
+// vary on EVERY axis — header name, basestring, digest, encoding, whether a timestamp participates
+// and WHERE it lives — and this tree already verifies a hex HMAC over the body alone; a hex HMAC over
+// `<version>:<ts>:<body>` with a skew window; an ASYMMETRIC Ed25519 signature over `<ts><body>`; a
+// signature whose freshness timestamp lives INSIDE THE JSON BODY; and a bearer JWT validated against
+// the issuer's rotating public keys. This registry is the seam all of them share.
+//
+// PURE REGISTRY LEAF — the `credentials/home.ts` posture. Types + a Map + five functions; no
+// crypto, no vendor strings, no store, no eve. Verifier IMPLEMENTATIONS live with the code that
+// owns the scheme (core's own in `webhooks/oe-standard-webhook.ts`; a vendor's in its provider bundle, which
+// is also where that vendor's header names and literals stay).
+//
+// RESOLUTION IS BY THE HOOK'S DECLARED SOURCE. NEVER SNIFFED. Three reasons, worst first:
+//   1. Sniffing hands the ATTACKER verifier selection. With N verifiers, "whichever header is
+//      present wins" lets the sender choose which scheme authenticates them — and the moment one
+//      registered verifier is weaker than another (some vendors declare `signedTimestamp: false`;
+//      our own contract is timestamped) that is a live DOWNGRADE PRIMITIVE: present the WEAKER
+//      scheme's header instead of ours and the replay defence evaporates. Verifiers of both
+//      strengths are registered in a normal deployment, so this is not hypothetical.
+//   2. It makes the no-header case ambiguous. Today "no signature header" is unambiguously 401.
+//      Under sniffing it becomes "no verifier selected" — a different branch, and the classic
+//      place a fail-open creeps in.
+//   3. A key is bound to a SCHEME, not to an endpoint. Feeding a Notion verification_token to the
+//      GitHub verifier is a category error the CONFIG must decide, not the request — the same
+//      doctrine `brokerFor` follows: a coincidental value from the wrong resolver is worse than a
+//      clear error.
+//
+// UNREGISTERED SOURCE ⇒ FAIL CLOSED, taking `brokerFor`'s STRENGTH with `credentialHome`'s
+// MECHANISM: {@link webhookVerifier} returns `undefined` (a leaf must not throw) and the gate
+// converts that into a 401 naming the registered set. NOT a throw — a module-load throw on a
+// serverless cold start is the shape of the 12h dark-prod incident, and
+// `access/provider-selection.ts` already fixes "REFUSE, DON'T THROW" as house doctrine.
+// `webhooks.allowUnverified` does NOT waive this: the dev hatch exists for "the secret isn't
+// set on my laptop", not for "this deployment cannot authenticate this scheme at all".
+import { admitProviderRegistration } from "../access/provider-selection.js";
+const VERIFIERS = new Map();
+/**
+ * Register (or replace) the verifier for one source. A verifier carrying `provider` is routed
+ * through the provider-selection gate first, so a de-selected bundle writes ZERO rows here and
+ * every hook declaring that source then fails closed at resolution — no new refusal path needed.
+ * Returns whether the row landed.
+ */
+export function registerWebhookVerifier(verifier) {
+    if (verifier.provider !== undefined && !admitProviderRegistration(verifier.provider, "webhook-verifier"))
+        return false;
+    VERIFIERS.set(verifier.source, verifier);
+    return true;
+}
+/** The verifier for `source`, or `undefined` when none is registered — the caller (the gate)
+ *  turns that into a 401 naming the registered set. NEVER a fallback to another scheme. */
+export function webhookVerifier(source) {
+    return source === undefined ? undefined : VERIFIERS.get(source);
+}
+/** Every registered source, sorted — for the fail-closed refusal copy and the boundary guard. */
+export function registeredWebhookVerifierSources() {
+    return [...VERIFIERS.keys()].sort();
+}
+/** Every registered verifier — for the `signedTimestamp` allowlist guard and the vocabulary
+ *  derivation (`webhooks/source-vocabulary.ts`, which needs the ENTRIES, not just their keys). */
+export function registeredWebhookVerifiers() {
+    return [...VERIFIERS.values()];
+}
+/**
+ * Can this scheme authenticate a delivery signed with a secret WE minted at random? (OPE-186)
+ *
+ * THE precondition for a hook whose key this deployment mints, which is always `approvals/webhook.ts`'s
+ * `mintSecret()` — never a value handed to us. BOTH clauses are load-bearing: an asymmetric scheme
+ * has no shared secret for us to mint even if something declared its key receiver-chosen, and a
+ * vendor-issued shared secret is a value we RECEIVE rather than choose.
+ *
+ * ONE definition, shared by the vocabulary derivation and the test that pins it against the live
+ * registries. Two copies of this predicate is precisely how the two would drift.
+ */
+export function acceptsMintedSecret(verifier) {
+    return verifier.keyOrigin === "receiver-minted" && verifier.keyKind === "shared-secret";
+}
+/** The ladder, WEAKEST FIRST. Order is semantic — {@link meetsWebhookAuthFloor} compares indices. */
+export const WEBHOOK_AUTH_GRADES = ["unverified", "signed", "signed-fresh"];
+/**
+ * THE STRONGEST GRADE ANY DELIVERY ON THIS SCHEME CAN EVER REACH — a derived predicate over the
+ * verifier's own declared strength fields, exactly as {@link acceptsMintedSecret} is.
+ *
+ * 🔴 IT IS A PROPERTY OF THE REGISTERED SCHEME, NOT OF A REQUEST, AND THAT IS THE WHOLE POINT. The
+ * input is the verifier the hook's DECLARED source resolved to (`webhooks/gate.ts`), never a header,
+ * never a verdict. So "how strong is this hook" has one answer for every delivery it will ever take,
+ * and a sender cannot move it in either direction by choosing what to send.
+ *
+ * NEVER RETURNS `"unverified"`: a resolved verifier means a signature WILL be checked. `unverified`
+ * is not a scheme's ceiling, it is what an acceptance that skipped the check attained — which is why
+ * the gate supplies that value from the hatch branch and this function cannot.
+ */
+export function webhookAuthCeiling(verifier) {
+    return verifier.signedTimestamp ? "signed-fresh" : "signed";
+}
+/** Is `achieved` at least as strong as `floor`? Index comparison over {@link WEBHOOK_AUTH_GRADES} —
+ *  ONE definition, shared by the gate's two refusal arms and the tests that pin them. */
+export function meetsWebhookAuthFloor(achieved, floor) {
+    return WEBHOOK_AUTH_GRADES.indexOf(achieved) >= WEBHOOK_AUTH_GRADES.indexOf(floor);
+}
+/** Test seam: forget every registered verifier (mirrors resetCredentialHomes). No auto-restore —
+ *  a verifier module re-registers on its next load, and a test file owns its own process. */
+export function resetWebhookVerifiersForTest() {
+    VERIFIERS.clear();
+}
+//# sourceMappingURL=verifier.js.map

package/dist/agent/webhooks/verifier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verifier.js","sourceRoot":"","sources":["../../../agent/webhooks/verifier.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,qFAAqF;AACrF,EAAE;AACF,qGAAqG;AACrG,qGAAqG;AACrG,mGAAmG;AACnG,sGAAsG;AACtG,mGAAmG;AACnG,qGAAqG;AACrG,kFAAkF;AAClF,EAAE;AACF,6FAA6F;AAC7F,gGAAgG;AAChG,6GAA6G;AAC7G,+DAA+D;AAC/D,EAAE;AACF,0FAA0F;AAC1F,8FAA8F;AAC9F,iGAAiG;AACjG,kGAAkG;AAClG,+FAA+F;AAC/F,4FAA4F;AAC5F,qFAAqF;AACrF,gGAAgG;AAChG,8FAA8F;AAC9F,oCAAoC;AACpC,kGAAkG;AAClG,8FAA8F;AAC9F,kGAAkG;AAClG,oBAAoB;AACpB,EAAE;AACF,2FAA2F;AAC3F,8FAA8F;AAC9F,6FAA6F;AAC7F,wEAAwE;AACxE,wFAAwF;AACxF,6FAA6F;AAC7F,uFAAuF;AAEvF,OAAO,EAAE,yBAAyB,EAAE,MAAM,iCAAiC,CAAC;AA0K5E,MAAM,SAAS,GAAG,IAAI,GAAG,EAA2B,CAAC;AAErD;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CAAC,QAAyB;IAC/D,IAAI,QAAQ,CAAC,QAAQ,KAAK,SAAS,IAAI,CAAC,yBAAyB,CAAC,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAC;QAAE,OAAO,KAAK,CAAC;IACvH,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IACzC,OAAO,IAAI,CAAC;AACd,CAAC;AAED;2FAC2F;AAC3F,MAAM,UAAU,eAAe,CAAC,MAA0B;IACxD,OAAO,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;AAClE,CAAC;AAED,iGAAiG;AACjG,MAAM,UAAU,gCAAgC;IAC9C,OAAO,CAAC,GAAG,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;AACtC,CAAC;AAED;kGACkG;AAClG,MAAM,UAAU,0BAA0B;IACxC,OAAO,CAAC,GAAG,SAAS,CAAC,MAAM,EAAE,CAAC,CAAC;AACjC,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,mBAAmB,CAAC,QAAyB;IAC3D,OAAO,QAAQ,CAAC,SAAS,KAAK,iBAAiB,IAAI,QAAQ,CAAC,OAAO,KAAK,eAAe,CAAC;AAC1F,CAAC;AAwCD,qGAAqG;AACrG,MAAM,CAAC,MAAM,mBAAmB,GAAgC,CAAC,YAAY,EAAE,QAAQ,EAAE,cAAc,CAAU,CAAC;AAElH;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,kBAAkB,CAAC,QAAyB;IAC1D,OAAO,QAAQ,CAAC,eAAe,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,QAAQ,CAAC;AAC9D,CAAC;AAED;yFACyF;AACzF,MAAM,UAAU,qBAAqB,CAAC,QAA0B,EAAE,KAAuB;IACvF,OAAO,mBAAmB,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,mBAAmB,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AACrF,CAAC;AAED;6FAC6F;AAC7F,MAAM,UAAU,4BAA4B;IAC1C,SAAS,CAAC,KAAK,EAAE,CAAC;AACpB,CAAC"}

package/dist/scripts/operator-store-connect.d.ts

@@ -0,0 +1,86 @@
+/** How a skin opens the store. */
+export interface OperatorStoreOpts {
+    /** Skip `initOperationalSchema` — for a command that only READS. See connectOperatorStore. */
+    readonly readOnly?: boolean;
+}
+/** What the skins print: which store this process just wired, in operator words. */
+export interface OperatorStoreTarget {
+    /** The provider id the runtime rule resolved (`postgres` / `sqlite` / a registered id). */
+    readonly id: string;
+    /** A one-line human description, e.g. `hosted Postgres (DATABASE_URL)`. Carries NO connection string. */
+    readonly label: string;
+}
+/**
+ * Load the root-of-trust env from a `.env` file into `process.env` — ONLY the
+ * {@link SECRET_STORE_ENV_KEYS} allowlist, and only for keys not already set in the process (an
+ * explicitly exported var always wins, so `DATABASE_URL=… oe secret set` behaves as typed).
+ *
+ * This exists because the operator's `DATABASE_URL` + `OE_CREDENTIAL_ENCRYPTION_KEY` normally sit in
+ * an untracked `.env.local` rather than the shell — and an MCP server started by an agent inherits
+ * neither. Copying the WHOLE file would re-create the env-as-secret-home this ticket deletes, so the
+ * allowlist is the mechanism, not a convenience.
+ *
+ * Returns the names it set (never values). Missing file ⇒ empty list, no error.
+ */
+export declare function loadRootOfTrustEnv(path: string): readonly string[];
+/**
+ * Wire the operational store for THIS process and return what was wired. Idempotent — the second
+ * call returns the first call's target without re-opening anything (the ops MCP server calls it on
+ * every tool invocation).
+ *
+ * Postgres (hosted) is reached with the same `@neondatabase/serverless` pool the deployed adapter
+ * builds, imported name-as-variable so core stays install-safe without the driver. `initOperationalSchema`
+ * runs on that client: it is idempotent `CREATE TABLE IF NOT EXISTS` DDL and it makes the day-0 story
+ * work — an operator can load secrets BEFORE the app has ever booted. Under a non-owner runtime role
+ * it skips DDL and verifies instead (the schema init is role-aware), so pointing this at a two-role
+ * deployment's runtime URL is safe.
+ *
+ * 🔴 `readOnly` SKIPS that schema init, and a command that only READS must pass it (OPE-1636).
+ * Under an OWNER credential `initOperationalSchema` is not passive: it drops unexpected policies
+ * and triggers, re-applies the DDL, and appends an `audit.integrity` row. A verifier that
+ * connected that way would repair the posture it was asked to inspect and write into the chain it
+ * was asked to walk. Idempotence is not the question — a read command must not act at all.
+ *
+ * The flag reaches BOTH store branches. The embedded floor defers the same `initOperationalSchema`
+ * to its lazy client's first query, so a floor branch that ignored `readOnly` would write exactly
+ * what the hosted branch is careful not to. What no branch can promise is an untouched file: the
+ * floor still takes its single-writer lock and opens the data dir. `readOnly` means "appends no
+ * row and changes no posture".
+ */
+export declare function connectOperatorStore(opts?: OperatorStoreOpts): Promise<OperatorStoreTarget>;
+/**
+ * The one line an operator CLI runs before its FIRST read or write: lift the allowlisted
+ * root-of-trust keys out of `.env.local` (or `--root-env PATH`), then open the store the RUNTIME's
+ * own rule selects. Returns the target so the CLI can print its label in its header.
+ *
+ * 🔴 A READ NEEDS THIS AS MUCH AS A WRITE (OPE-1434). `readAudit`, `listAllRoutines` and the spend
+ * views all resolve the store lazily, so a CLI that never connects reads whatever
+ * `getOperationalStore()` falls back to. Measured on the default env (nothing set): the configured
+ * store is the embedded Postgres floor, the floor is never armed in these processes, and the fallback
+ * is the synchronous sqlite stand-in. The operator then gets a confident, empty answer about a
+ * deployment whose rows live somewhere else — and an empty audit log during an incident reads as
+ * "nothing happened".
+ */
+export declare function connectOperatorStoreForCli(argv?: readonly string[], opts?: OperatorStoreOpts): Promise<OperatorStoreTarget>;
+/**
+ * Declare the org THIS operator process acts for, before it opens the store.
+ *
+ * 🔴 AN OPERATOR PROCESS NEVER LOADS THE DEPLOYMENT'S CONFIG, so it cannot learn the org by itself
+ * (OPE-1545). The org is a tracked literal in the app's `agent/identity/surfaces.ts`, and a core
+ * script may not import an app module — the whole point of the core/app split. Every operator CLI
+ * therefore resolves `deploymentOrg()` to the shipped `"default"` unless the operator names the org
+ * on the command line.
+ *
+ * That is not cosmetic. `connectOperatorStore()` runs `initOperationalSchema`, which writes the
+ * `audit.integrity` row through `deploymentOrg()` (operational/postgres.ts). On a deployment whose
+ * declaration is NOT `"default"`, an undeclared operator process would file that row in a partition
+ * the running agent never queries and chain-link it into the wrong chain — the OPE-1438 split
+ * exactly. Registering here keeps the ONE spelling: `deploymentOrg()` answers the same string for
+ * the integrity row, the reads, and the rows a skin writes.
+ *
+ * An absent or blank value leaves the register alone, so `"default"` deployments type nothing.
+ */
+export declare function declareOperatorOrg(org: string | undefined): void;
+/** Test seam: forget the wired target so a later call re-resolves, and drop the floor refusal. */
+export declare function resetOperatorStoreConnection(): void;
+//# sourceMappingURL=operator-store-connect.d.ts.map

package/dist/scripts/operator-store-connect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operator-store-connect.d.ts","sourceRoot":"","sources":["../../scripts/operator-store-connect.ts"],"names":[],"mappings":"AAiCA,kCAAkC;AAClC,MAAM,WAAW,iBAAiB;IAChC,8FAA8F;IAC9F,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,oFAAoF;AACpF,MAAM,WAAW,mBAAmB;IAClC,2FAA2F;IAC3F,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,yGAAyG;IACzG,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAID;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAoBlE;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,oBAAoB,CAAC,IAAI,GAAE,iBAAsB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CA6CrG;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,0BAA0B,CAAC,IAAI,GAAE,SAAS,MAAM,EAAiB,EAAE,IAAI,GAAE,iBAAsB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAMnJ;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAKhE;AAED,kGAAkG;AAClG,wBAAgB,4BAA4B,IAAI,IAAI,CAGnD"}