@open-everywhere/core 0.1.0

package/dist/agent/webhooks/hooks-codemod.js

@@ -0,0 +1,231 @@
+// The deterministic webhook-hooks codemod — the ONLY thing that ever edits the hooks overlay
+// (the data-only `hooks.generated.ts` a deployer app merges into its declared hooks at config load).
+//
+// A SIBLING OF `access/grants-codemod.ts`, ON PURPOSE AND NOT BY COINCIDENCE. That module exists so
+// the access-request flow can promise the diff an admin merges was NEVER model-authored past propose
+// time. A webhook declaration needs the identical promise for the identical reason — it is a
+// STANDING UNATTENDED PROMPT aimed at a named channel, which is the most consequential thing in this
+// system a conversation can ask for — so it gets the same machinery rather than a second, divergent
+// config-PR path. Same properties, deliberately:
+//
+//   • PURE + DETERMINISTIC — no I/O, no clock, no randomness; same inputs ⇒ byte-identical output
+//     (stable key order, canonical array order, 2-space indent, trailing newline).
+//   • IDEMPOTENT — re-applying a declaration whose effect is already present returns
+//     `changed: false` and the identical file, which is what the re-request PR-update path needs.
+//   • REFUSES RATHER THAN GUESSES — anything outside the vocabulary throws `HooksCodemodError`.
+//   • THE CALLER RE-VALIDATES THE MERGED RESULT (code baseline ⊕ overlay) with `assertWebhooksValid`
+//     BEFORE any commit or PR exists, so an invalid declaration never becomes a PR.
+//
+// 🔴 NO SECRET EVER REACHES THIS MODULE, AND THERE IS NO PARAMETER THROUGH WHICH ONE COULD. A
+// declaration carries `secretRef` + `broker` — a POINTER and the home it resolves through. The VALUE
+// is set separately by an operator, after the merge, in a place a diff cannot see. That is not a
+// limitation of the flow; it is the reason the flow is safe to run from chat at all, and it is why
+// an unmerged PR grants nothing while a merged one still authenticates nobody until an operator acts.
+import { overlayModuleHeader, unwrapOverlayModule, wrapOverlayModule } from "../access/overlay-module.js";
+/** A codemod refusal — invalid file, invalid declaration, or an invariant breach. Distinct type so
+ *  callers can tell "refused by design" from an unexpected failure.
+ *  🔴 EXPORT KEPT FOR A CONSUMER OUTSIDE THIS REPO (OPE-1455): a self-host that drives this codemod
+ *  catches this class to make that distinction. No in-repo caller names it. */
+export class HooksCodemodError extends Error {
+}
+export function emptyHooksFile() {
+    return { hooks: [] };
+}
+function isRecord(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function isStringOrStringArray(v) {
+    return typeof v === "string" || (Array.isArray(v) && v.every((x) => typeof x === "string"));
+}
+function isScopeArray(v) {
+    return Array.isArray(v) && v.length > 0 && v.every((x) => isRecord(x) && typeof x.level === "string");
+}
+/**
+ * Parse + shape-check a hooks overlay from unknown JSON. STRICT and fail-loud: unknown top-level
+ * keys, unknown hook fields, or a missing required field all throw — the overlay is machine-written,
+ * so any deviation means a hand-edit went wrong, and a silently mis-parsed hooks file IS the security
+ * bug (the same doctrine `parseGrantsFile` states).
+ *
+ * DEEP SEMANTIC VALIDATION STAYS WITH `assertWebhooksValid` ON THE MERGED RESULT — id grammar,
+ * reserved ref namespaces, target form, `readableBy` well-formedness. This only pins the
+ * overlay-specific rules: shape and no unknown fields. Two checkers, one
+ * authority: this one says "this is a hooks file", that one says "these hooks are legal".
+ */
+export function parseHooksFile(value) {
+    if (!isRecord(value))
+        throw new HooksCodemodError("hooks overlay must be a JSON object with a `hooks` array");
+    const keys = Object.keys(value).filter((k) => k !== "$comment");
+    const unknown = keys.filter((k) => k !== "hooks");
+    if (unknown.length > 0)
+        throw new HooksCodemodError(`hooks overlay has unknown top-level key(s): ${unknown.join(", ")}`);
+    if (!Array.isArray(value.hooks))
+        throw new HooksCodemodError("hooks overlay needs a `hooks` array (use [] when empty)");
+    const hooks = [];
+    for (const h of value.hooks) {
+        if (!isRecord(h) || typeof h.id !== "string" || !h.id)
+            throw new HooksCodemodError("every overlay hook needs a string `id`");
+        for (const k of Object.keys(h)) {
+            if (!HOOK_KEYS.includes(k)) {
+                throw new HooksCodemodError(`overlay hook "${h.id}" has unknown field "${k}" — the overlay carries exactly the declared webhook vocabulary (${HOOK_KEYS.join(", ")})`);
+            }
+        }
+        if (typeof h.source !== "string" || !h.source)
+            throw new HooksCodemodError(`overlay hook "${h.id}" needs a string \`source\` (the signature scheme)`);
+        if (!isStringOrStringArray(h.secretRef))
+            throw new HooksCodemodError(`overlay hook "${h.id}" needs \`secretRef\` (a ref or an ordered list of refs — never a value)`);
+        if (typeof h.broker !== "string" || !h.broker)
+            throw new HooksCodemodError(`overlay hook "${h.id}" needs a string \`broker\``);
+        // `target` + `instruction` are OPTIONAL and PAIRED (OPE-224) — both present is a FUSED hook,
+        // both absent is an EMIT-ONLY one. Only the SHAPE is checked here (a present field must be a
+        // non-empty string); the PAIRING is `assertWebhooksValid`'s on the merged result, like every
+        // other semantic rule, so the two checkers cannot state the pairing two different ways.
+        if (h.target !== undefined && (typeof h.target !== "string" || !h.target)) {
+            throw new HooksCodemodError(`overlay hook "${h.id}" has a non-string \`target\` — omit it entirely to declare an emit-only hook`);
+        }
+        if (h.instruction !== undefined && (typeof h.instruction !== "string" || !h.instruction)) {
+            throw new HooksCodemodError(`overlay hook "${h.id}" has a non-string \`instruction\` — omit it entirely to declare an emit-only hook`);
+        }
+        // readableBy is REQUIRED here and not merely validated later, because "absent" is the exact
+        // shape the zero-domain trap took (OPE-206): a grant that was never stated, read as a default.
+        if (!isScopeArray(h.readableBy)) {
+            throw new HooksCodemodError(`overlay hook "${h.id}" needs a non-empty \`readableBy\` array — who may read this hook's events is required and has no default`);
+        }
+        // POSTURE + PROJECT (OPE-214) are OPTIONAL here, unlike `readableBy`, and the asymmetry is
+        // deliberate. `readableBy` is required because ABSENCE was the bug (a grant nobody stated, read
+        // as a default — OPE-206). Posture's absence is not a bug: it is a fact about when the overlay
+        // was written, and it reads as the `content-bearing` every config hook already was. Demanding it
+        // here would make an existing, valid hooks overlay fail to parse at boot — a silent-hook problem
+        // traded for a dead-deployment one. The VALUE is still shape-checked, so a typo cannot arrive as
+        // a posture; whether it is a REGISTERED posture and whether `project` is coherent with it are
+        // `assertWebhooksValid`'s, on the merged result, like every other semantic rule.
+        if (h.posture !== undefined && typeof h.posture !== "string") {
+            throw new HooksCodemodError(`overlay hook "${h.id}" has a non-string \`posture\` — it names how much of the payload may reach the model`);
+        }
+        if (h.project !== undefined && !(Array.isArray(h.project) && h.project.every((k) => typeof k === "string"))) {
+            throw new HooksCodemodError(`overlay hook "${h.id}" has a malformed \`project\` — it is a list of normalizer field-key names`);
+        }
+        // AUTH FLOOR (OPE-203) — optional and shape-checked only, exactly like `posture` above and for
+        // the same two reasons: absence is a fact about the file's age (an overlay written before the
+        // field existed must keep parsing), and whether the value is a GRADE ON THE LADDER is
+        // `assertWebhooksValid`'s on the merged result, so the two checkers cannot state the vocabulary
+        // two different ways.
+        if (h.authFloor !== undefined && typeof h.authFloor !== "string") {
+            throw new HooksCodemodError(`overlay hook "${h.id}" has a non-string \`authFloor\` — it names the weakest acceptance this hook will take`);
+        }
+        hooks.push(h);
+    }
+    return { hooks };
+}
+// --- stable stringify (codemod-friendly: minimal diffs, deterministic bytes) -------------------
+/** Canonical field order — declaration order, i.e. the order a human reads a hook in: what it IS,
+ *  how it authenticates, where it fires, WHO MAY READ IT, HOW MUCH OF THE PAYLOAD IT DISCLOSES, and
+ *  what it does. `posture`/`project` (OPE-214) sit next to `readableBy` on purpose: those three are
+ *  the whole confidentiality story of a hook, and a reviewer should read them together rather than
+ *  find the disclosure decision buried after the instruction. Unknown keys are impossible (the
+ *  parser refuses them), so there is no tail to sort.
+ *
+ *  `authFloor` (OPE-203) sits immediately after `broker`, closing the AUTHENTICATION run —
+ *  `source`/`secretRef`/`broker` say what authenticates this hook and `authFloor` says how strongly,
+ *  so a reviewer reads the four together. Inserting it there re-orders nothing for an existing hook:
+ *  `orderKeys` skips absent keys, so a declaration without the field serialises byte-identically. */
+const HOOK_KEYS = ["id", "source", "secretRef", "broker", "authFloor", "target", "readableBy", "posture", "project", "instruction"];
+const SCOPE_KEYS = ["level", "tenant", "domain", "surface", "principal"];
+function orderKeys(obj, order) {
+    const out = {};
+    for (const k of order)
+        if (k in obj)
+            out[k] = obj[k];
+    for (const k of Object.keys(obj).sort())
+        if (!(k in out))
+            out[k] = obj[k];
+    return out;
+}
+function canonicalHook(h) {
+    const obj = { ...h };
+    // `secretRef` order is SEMANTIC (current key first — a rotation overlap) and is never sorted.
+    // `readableBy` order is not semantic (union), but it is stabilised so a re-declaration cannot
+    // produce a diff that only reorders lines.
+    obj.readableBy = [...h.readableBy]
+        .map((s) => orderKeys({ ...s }, SCOPE_KEYS))
+        .sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b)));
+    return orderKeys(obj, HOOK_KEYS);
+}
+/**
+ * Canonical, byte-deterministic serialisation of the overlay's DATA: hooks sorted by id, fixed field
+ * order, 2-space indent, trailing newline. This is the body {@link emitHooksModule} wraps the module
+ * grammar around, and `emitHooksModule(parseHooksModule(emitHooksModule(f))) === emitHooksModule(f)`
+ * — the round-trip stability the PR-update path leans on.
+ */
+export function stringifyHooks(file) {
+    const hooks = [...file.hooks].sort((a, b) => a.id.localeCompare(b.id)).map(canonicalHook);
+    return JSON.stringify({ hooks }, null, 2) + "\n";
+}
+// --- the generated module form (the on-disk / Contents-API form) --------------------------------
+//
+// The overlay ships as a machine-owned TS module (`agent/webhooks/hooks.generated.ts`), not as JSON:
+// one authoring language for the whole deployer config. See access/overlay-module.ts for the grammar
+// — and for why the DRIFT LINT, not the file format, is what keeps this data. That matters more here
+// than for either sibling overlay: a hook is a standing unattended prompt, so "the file cannot
+// contain code" was worth something, and `npm run lint:overlays` is what replaces it.
+/** This overlay's fixed module grammar. Constants only: the emitted bytes depend on the data alone. */
+const HOOKS_MODULE = {
+    what: "hooks overlay",
+    header: overlayModuleHeader("webhook-hooks overlay", "packages/core/agent/webhooks/hooks-codemod.ts"),
+    typeImport: 'import type { HooksFile } from "@open-everywhere/core/agent/webhooks/hooks-codemod.js";',
+    typeName: "HooksFile",
+};
+/** The overlay's whole file text: the pinned grammar wrapped around the canonical JSON body. */
+export function emitHooksModule(file) {
+    return wrapOverlayModule(HOOKS_MODULE, stringifyHooks(file));
+}
+/**
+ * Parse an overlay module's text, VERIFYING THE ROUND TRIP. Strip the grammar (refusing if it was
+ * touched at all), parse the data, then re-emit and demand the bytes come back identical.
+ *
+ * A hand-edit that reorders fields, re-indents or leaves a stray comment inside the data REFUSES
+ * here rather than being silently rewritten by the next codemod commit — which would put a diff in
+ * front of an admin that nobody authored. `npm run lint:overlays` is the same check run in CI.
+ */
+export function parseHooksModule(text) {
+    const file = parseHooksFile(unwrapOverlayModule(HOOKS_MODULE, text, (m) => new HooksCodemodError(m)));
+    if (emitHooksModule(file) !== text) {
+        throw new HooksCodemodError("hooks overlay is not in canonical form — re-emitting its own data does not reproduce the file, so it has been hand-edited. Run `npm run overlays:normalize` and commit the result (the codemod refuses to rewrite a file it did not write).");
+    }
+    return file;
+}
+/** LENIENT re-emit for `npm run overlays:normalize`: take whatever well-shaped data the module
+ *  carries and return the canonical module text. The only path allowed to accept a non-canonical
+ *  file — its whole job is to produce the canonical one. */
+export function renormalizeHooksModule(text) {
+    return emitHooksModule(parseHooksFile(unwrapOverlayModule(HOOKS_MODULE, text, (m) => new HooksCodemodError(m))));
+}
+/**
+ * Apply ONE frozen hook declaration to a parsed overlay.
+ *
+ * 🔴 IT ONLY EVER ADDS. A declaration whose id is already present and IDENTICAL is a no-op; a
+ * declaration whose id is present and DIFFERENT is REFUSED, never overwritten. Editing a live hook
+ * means changing where an already-authenticated sender's deliveries land — a different act with a
+ * different blast radius from adding one, and one that a human should perform in the file rather
+ * than have a chat request perform on their behalf. The refusal names the recovery.
+ *
+ * The `baseIds` argument is the CODE-declared hooks (`agent/webhooks/hooks.ts`), which the overlay
+ * merges alongside. A declaration colliding with one of those is refused for the same reason and
+ * more sharply: the overlay cannot edit code, so the collision would surface as a duplicate-id boot
+ * failure after the merge rather than as a refusal now.
+ */
+export function applyHookDeclaration(file, decl, baseIds = []) {
+    if (baseIds.includes(decl.id)) {
+        throw new HooksCodemodError(`a webhook "${decl.id}" is already declared in code (agent/webhooks/hooks.ts) — the overlay cannot edit it, and two hooks with one id is a boot failure. Pick a different id, or edit the code declaration directly in a PR.`);
+    }
+    const existing = file.hooks.find((h) => h.id === decl.id);
+    if (existing) {
+        // Byte comparison through the canonical form, so a re-declaration that differs only in field
+        // order or `readableBy` ordering is correctly a no-op rather than a spurious refusal.
+        if (JSON.stringify(canonicalHook(existing)) === JSON.stringify(canonicalHook(decl))) {
+            return { hooks: file, changed: false };
+        }
+        throw new HooksCodemodError(`a webhook "${decl.id}" is already declared in the overlay with different settings — this codemod only ADDS. Changing a live hook redirects an already-authenticated sender, so it is an edit a human makes in the file (and reviews as its own PR), not something a chat request performs. Pick a new id, or edit agent/webhooks/hooks.generated.ts by hand and run \`npm run overlays:normalize\` (the file is machine-owned, so an un-normalised edit fails \`npm run lint:overlays\`).`);
+    }
+    return { hooks: { hooks: [...file.hooks, decl] }, changed: true };
+}
+//# sourceMappingURL=hooks-codemod.js.map

package/dist/agent/webhooks/hooks-codemod.js.map

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

package/dist/agent/webhooks/oe-standard-webhook.d.ts

@@ -0,0 +1,153 @@
+import { type WebhookSenderGuidance, type WebhookVerifier } from "./verifier.js";
+import { type EventNormalizer, type ScopeStep, type TriggerDelivery } from "../routines/event-model.js";
+/** The registry key — the SCHEME, not a hook's name. A (b) hook is `{ source: "my-ci", scheme: this }`. */
+export declare const OE_STANDARD_WEBHOOK_SCHEME = "oe-standard-webhook";
+/** Spec header names, lower-cased (`Headers.get` is case-insensitive; `TriggerDelivery.headers` is
+ *  lower-keyed, so these serve both). */
+export declare const SW_ID_HEADER = "webhook-id";
+export declare const SW_TIMESTAMP_HEADER = "webhook-timestamp";
+export declare const SW_SIGNATURE_HEADER = "webhook-signature";
+/** The spec's symmetric-signature version tag. A future scheme bumps THIS, never a header name. */
+export declare const SW_SIGNATURE_VERSION = "v1";
+/** The spec's secret prefix. Its presence — and only its presence — selects the spec's base64 key
+ *  encoding. See {@link standardWebhookKey}. */
+export declare const SW_SECRET_PREFIX = "whsec_";
+/**
+ * THE ONE DEFINITION of what this scheme signs: `<id>.<timestamp>.<rawBody>`. Exported so a signer
+ * (a test, the e2e forge, a documented shell snippet) and this verifier can be pinned equal by an
+ * assertion rather than drifting: one definition, never a second spelling of it.
+ */
+export declare function standardWebhookSignedContent(messageId: string, timestamp: string, rawBody: string): string;
+/**
+ * The HMAC key bytes for a stored secret. ONE total rule, discriminated on a prefix that lives in
+ * OUR secret and never in the request:
+ *
+ *   • `whsec_<base64>` — the spec's own encoding, and what {@link mintStandardWebhookSecret} now
+ *                        produces. The remainder is base64-decoded.
+ *   • anything else    — the secret's own UTF-8 bytes: every hook minted BEFORE the prefix landed
+ *                        (a raw `base64url` random), and what `openssl dgst -hmac "$SECRET"` uses.
+ *                        This branch is why minting the prefix broke no live sender.
+ *
+ * 🔴 NOT A FALLBACK CHAIN. There is no "decode, and if the signature fails try the raw bytes":
+ * `webhooks/verifier.ts` refuses request-driven scheme selection as a downgrade primitive, and a
+ * secret-driven one would be the same bug with a longer fuse. A `whsec_` secret whose remainder is
+ * not valid base64 yields the bytes base64 decoding produced for it, and the signature simply does
+ * not match — a clean 401, never a coincidental match through the other branch.
+ */
+export declare function standardWebhookKey(secret: string): Buffer;
+/**
+ * ⭐ MINT A SECRET IN THE SPEC'S OWN FORM: `whsec_<base64>`, whose base64-decoded remainder IS the
+ * HMAC key ({@link standardWebhookKey}). This is the format an off-the-shelf `standard-webhooks`
+ * client library expects, and the format that makes the value self-identifying if it is pasted
+ * somewhere it does not belong.
+ *
+ * STANDARD base64, not `base64url`, and it is not a preference: the reference libraries decode with
+ * a strict standard-alphabet decoder, so a `-` or `_` would either decode to different bytes or
+ * throw. The `+`/`/` that alphabet brings are harmless here — the secret is copied from a page into a
+ * config field, never into a URL.
+ *
+ * `bytes` is injectable ONLY so a test can pin the encoding against a known vector. Every production
+ * call takes the default and gets fresh randomness.
+ */
+export declare function mintStandardWebhookSecret(bytes?: Buffer): string;
+/** The `v1,<base64>` header value one key would produce for this message. Exported for signers. */
+export declare function standardWebhookSignature(secret: string, messageId: string, timestamp: string, rawBody: string): string;
+/**
+ * The durable single-use nonce identity (`webhooks/replay-dedupe.ts`), derived from the SIGNED
+ * message id.
+ *
+ * ⭐ THIS IS THE UPGRADE OVER A SIGNATURE-DERIVED NONCE (`sha256(<source>:<ts>:<signature>)`, which
+ * is what a scheme with no message id is reduced to): it cannot tell two legitimately identical
+ * payloads sent in the same second apart, and drops the second as a replay it never was. A
+ * `webhook-id` is the sender's own idempotency key, covered by
+ * the signature, so it distinguishes messages rather than bytes. The timestamp is deliberately NOT
+ * folded in: re-sending one message id with a fresh timestamp is precisely the replay this is meant
+ * to suppress, and including it would let a re-signer walk around the mark.
+ *
+ * Hashed, like its sibling, so the store holds a fixed-width opaque token rather than a
+ * sender-authored string — and `webhookReplayStoreKey` namespaces it by hook id on top.
+ */
+export declare function standardWebhookReplayKey(messageId: string): string;
+/**
+ * WHAT A SENDER MUST SEND — the human half of {@link standardWebhookVerifier}, rendered beside the
+ * secret on the reveal page. Built from the SAME exported constants and the SAME basestring builder
+ * the verifier reads, so the two cannot drift into disagreement; a test asserts each field against
+ * those symbols rather than against a copy of this prose.
+ *
+ * The key-derivation note states the TOTAL rule rather than assuming which form the reader is
+ * holding: a hook minted before the `whsec_` prefix landed still carries a raw secret, and telling
+ * such a reader to base64-decode it would break every signature they made.
+ */
+export declare function standardWebhookSenderGuidance(): WebhookSenderGuidance;
+/**
+ * THE VERIFIER. `keyOrigin: "receiver-minted"` + `keyKind: "shared-secret"` ⇒ `acceptsMintedSecret`
+ * ⇒ this scheme enters `mintableSourceVocabulary` and is chat-creatable, which is the whole point
+ * of the stage.
+ */
+export declare const standardWebhookVerifier: WebhookVerifier;
+/**
+ * ⭐ THE (b) ENVELOPE. FOUR fields, each justified below, and every one of them OPTIONAL except the
+ * first. A sender that can write JSON and run `openssl` can produce it.
+ *
+ * WHY NOT CLOUDEVENTS — rejected, and not on grounds of taste. Two of its four REQUIRED attributes
+ * (`source`, `subject`) are SENDER-DECLARED IDENTITY fields, which is exactly the payload-scope
+ * hazard this adapter's scope rule exists to prevent. Adopting an envelope whose required fields we
+ * would have to actively ignore is worse than defining four fields we mean, and it would leave a
+ * standing invitation for a later reader to "wire up the fields that are already there". CloudEvents
+ * is an INTEROP surface, not an internal contract: if it is ever wanted it arrives as a category-(a)
+ * bundle that translates inbound, where ignoring an attribute is a documented translation rather
+ * than a silent one.
+ *
+ * UNKNOWN FIELDS ARE IGNORED, NEVER REJECTED. A sender that grows its payload must not start 400ing
+ * against a receiver it did not redeploy — and a strict-shape refusal at this layer would be a
+ * second, weaker copy of the size/shape bounds the gate already enforces.
+ */
+export interface StandardWebhookEnvelope {
+    /**
+     * REQUIRED. The event name, verbatim — `"build"`, `"deploy"`, `"alert"`. It is what a filter keys
+     * on first and what the human-readable summary is built from. Required because an envelope with no
+     * event name cannot be routed at all: `normalizedEventDefect` refuses an empty `event`, so
+     * accepting one here would only move the refusal somewhere less legible.
+     */
+    readonly event: string;
+    /** Optional sub-kind — `"failed"`, `"succeeded"`. Present because "the thing" and "what happened
+     *  to it" is the split EVERY vendor payload in this tree already has (`routines/events.ts`), so a
+     *  contract without it pushes every sender into stringly-concatenating one. */
+    readonly action?: string;
+    /**
+     * Optional flat bag of MATCHABLE scalars — `{ status: "failed", branch: "main" }`. This is the
+     * field that makes the envelope useful rather than ceremonial: it is where a sender puts whatever
+     * its own routines need to discriminate on.
+     *
+     * FLAT AND STRING-VALUED BY CONTRACT. Numbers/booleans are coerced (see {@link mergeScalarFields});
+     * objects and arrays are DROPPED rather than stringified, because a filter compares ids exactly and
+     * `"[object Object]"` matching `"[object Object]"` is a match that means nothing. Nesting is not
+     * supported and is not an oversight: the moment a filter can name a path, the match language
+     * becomes a payload-traversal language, which `routines/event-model.ts` refuses by design.
+     *
+     * Its KEYS are the SENDER's, which is why the normalizer declares `matchKeysOpen` — see there for
+     * what that costs.
+     */
+    readonly fields?: Readonly<Record<string, unknown>>;
+    /** Optional ISO-8601 instant, per the SENDER — distinct from our receive time on purpose, so "this
+     *  says the build failed, about a build that finished an hour ago" stays diagnosable. Carried
+     *  verbatim if it parses and dropped if it does not; a malformed clock is not a reason to drop a
+     *  delivery. */
+    readonly occurredAt?: string;
+}
+/**
+ * THE SCOPE PATH, built from the DELIVERY'S DECLARED NAME AND NOTHING ELSE. The body is not read
+ * here and there is no parameter through which it could be.
+ *
+ * Exported so a test can assert the property directly rather than inferring it from an end-to-end
+ * fixture: the honest test of "a payload cannot change the scope path" is that the function which
+ * builds the path cannot see a payload.
+ *
+ * ROUTING ONLY (OPE-209). This path is what a routine's scope selector matches; it is NOT an
+ * authorization input for this scheme — see the header. It is single-step and always non-empty,
+ * which is what keeps `checkEventReadGrant`'s `no-scope` refusal reserved for genuinely
+ * unattributable deliveries.
+ */
+export declare function standardWebhookScope(d: Pick<TriggerDelivery, "source">): ScopeStep[];
+export declare const standardWebhookNormalizer: EventNormalizer;
+//# sourceMappingURL=oe-standard-webhook.d.ts.map

package/dist/agent/webhooks/oe-standard-webhook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oe-standard-webhook.d.ts","sourceRoot":"","sources":["../../../agent/webhooks/oe-standard-webhook.ts"],"names":[],"mappings":"AAwHA,OAAO,EAA2B,KAAK,qBAAqB,EAAuB,KAAK,eAAe,EAA2B,MAAM,eAAe,CAAC;AAExJ,OAAO,EAGL,KAAK,eAAe,EAEpB,KAAK,SAAS,EACd,KAAK,eAAe,EACrB,MAAM,4BAA4B,CAAC;AAEpC,2GAA2G;AAC3G,eAAO,MAAM,0BAA0B,wBAAwB,CAAC;AAEhE;yCACyC;AACzC,eAAO,MAAM,YAAY,eAAe,CAAC;AACzC,eAAO,MAAM,mBAAmB,sBAAsB,CAAC;AACvD,eAAO,MAAM,mBAAmB,sBAAsB,CAAC;AAEvD,mGAAmG;AACnG,eAAO,MAAM,oBAAoB,OAAO,CAAC;AAEzC;gDACgD;AAChD,eAAO,MAAM,gBAAgB,WAAW,CAAC;AAezC;;;;GAIG;AACH,wBAAgB,4BAA4B,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAE1G;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEzD;AAgBD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,GAAE,MAAqC,GAAG,MAAM,CAE9F;AAED,mGAAmG;AACnG,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAGtH;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAElE;AASD;;;;;;;;;GASG;AACH,wBAAgB,6BAA6B,IAAI,qBAAqB,CAsBrE;AAED;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,EAAE,eAgDrC,CAAC;AAIF;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;mFAE+E;IAC/E,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACpD;;;oBAGgB;IAChB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAgCD;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,IAAI,CAAC,eAAe,EAAE,QAAQ,CAAC,GAAG,SAAS,EAAE,CAEpF;AASD,eAAO,MAAM,yBAAyB,EAAE,eA+DvC,CAAC"}