@open-everywhere/core 0.1.0

package/dist/agent/webhooks/reject-audit.js

@@ -0,0 +1,99 @@
+// Throttled rejection audit for the inbound-webhook surface (OPE-142).
+//
+// THE DEFECT. `POST /webhooks/:id` is a PUBLIC, UNAUTHENTICATED endpoint by construction — an
+// unknown id 404s and a bad signature 401s, and neither can be authenticated first. channels/
+// webhooks.ts wrote an audit row for EVERY such rejection, unthrottled, into `audit_entry` — an
+// APPEND-ONLY, HASH-CHAINED, per-org-serialised table (audit/chain.ts). So anyone who could reach
+// the URL could make the deployment write unbounded rows to its own tamper-evident log at their
+// chosen rate: an audit-write amplifier that costs the attacker one HTTP request and the operator
+// a chained insert (plus a lock hold that serialises the org's REAL audit writes behind it).
+//
+// THE FIX. Collapse a burst to at most ~one row per identity per {@link REJECTION_WINDOW_MS},
+// using the same durable `markEventSeen` first-sighting primitive the inbound dedupes use, and
+// carry a `suppressed` count on the NEXT emitted row so the throttling is VISIBLE. Rate-limiting
+// that hides its own existence would just move the blind spot; a row saying "and 4 872 more like
+// this in the last minute" is strictly more informative than 4 873 identical rows.
+//
+// ⚠️ THE THROTTLE KEY MUST NOT CONTAIN AN ATTACKER-CHOSEN STRING. Keying on the raw `:id` path
+// param would be no throttle at all — an unknown id is by definition whatever the caller typed, so
+// a scanner varying the path gets a fresh key (and a fresh row) every request. UNKNOWN ids
+// therefore collapse onto ONE constant key. A KNOWN hook's id is operator-configured and bounded,
+// so it keys per hook, which is what makes a real "this hook's secret drifted" signal legible
+// instead of being lost in a scan. The raw id still rides in `detail` (length-capped) so a
+// specific probe is still findable — it just no longer controls how many rows get written.
+//
+// ⚠️ THE ROW'S SURFACE IS LIKEWISE SYNTHETIC FOR AN UNKNOWN ID. Putting the caller-supplied id into
+// the `surface` column would let a stranger choose a partition label in the audit log. Only a
+// configured hook's own target ever names a real surface.
+import { appendAudit } from "../audit/audit.js";
+import { getOperationalStore } from "../operational/provider.js";
+import { webhookOrg } from "./dispatch.js";
+/** At most ~one rejection row per identity per window. */
+export const REJECTION_WINDOW_MS = 60_000;
+/** How much of a caller-supplied hook id is preserved in `detail` (the row must stay bounded —
+ *  the whole point is that this input is hostile and unbounded). */
+export const REJECTION_ID_MAX_CHARS = 100;
+/** The throttle identity: per-hook for a KNOWN hook (bounded, operator- or host-owned), a single
+ *  constant for anything unknown (unbounded, caller-owned). Status is included either way — there
+ *  are only a handful of them, and a 401 on a real hook is a very different story from a 404 scan. */
+export function rejectionThrottleKey(hook, status) {
+    return hook ? `hookrej:${hook.id}:${status}` : `hookrej:unknown:${status}`;
+}
+/** Suppressed-since-last-row counts, per throttle identity. In-process by design: it is a
+ *  best-effort visibility annotation on a best-effort log, and a durable counter would reintroduce
+ *  the per-request write this module exists to remove. On serverless each instance reports its own
+ *  share, which is the same granularity the rest of the throttle has. */
+const suppressed = new Map();
+/** Test seam — drop all in-process suppression counters. */
+export function resetRejectionThrottle() {
+    suppressed.clear();
+}
+/**
+ * Best-effort, THROTTLED audit for a rejected delivery. `hook` may be undefined (unknown id) — in
+ * that case there is no configured target to attribute the row to, so it is logged under a
+ * synthetic workspace/surface (still findable by the length-capped `hookId` in `detail`).
+ *
+ * Returns true when a row was emitted, false when it was suppressed (counted onto the next one).
+ */
+export async function auditWebhookRejection(id, hook, rejection, deps = {}) {
+    const org = deps.org ?? webhookOrg();
+    const audit = deps.audit ?? appendAudit;
+    const nowIso = (deps.now?.() ?? new Date()).toISOString();
+    const key = rejectionThrottleKey(hook, rejection.status);
+    // FAIL-OPEN on a throttle-store error: emit the row. The throttle and the audit write hit the
+    // SAME operational store, so a markEventSeen failure means the appendAudit below is about to
+    // fail too (harmlessly — audit is best-effort by contract). Failing closed here would instead
+    // silence genuine rejection auditing on any transient store blip.
+    let first = true;
+    try {
+        const markSeen = deps.markSeen ?? ((o, k, at, ttl) => getOperationalStore().markEventSeen(o, k, at, ttl));
+        first = await markSeen(org, key, nowIso, REJECTION_WINDOW_MS);
+    }
+    catch {
+        first = true;
+    }
+    if (!first) {
+        suppressed.set(key, (suppressed.get(key) ?? 0) + 1);
+        return false;
+    }
+    const carried = suppressed.get(key) ?? 0;
+    suppressed.delete(key);
+    const target = hook?.target?.split("/") ?? [];
+    await audit({
+        org,
+        platform: "slack",
+        workspace: target[1] ?? "unknown",
+        // Only a CONFIGURED hook names a real surface; an unknown id must never choose its own label.
+        surface: target[2] ?? "unknown",
+        action: "webhook.rejected",
+        detail: {
+            hookId: id.slice(0, REJECTION_ID_MAX_CHARS),
+            status: rejection.status,
+            reason: rejection.reason,
+            // Present only when this row is standing in for others — its absence means "exactly one".
+            ...(carried > 0 ? { suppressed: carried, windowMs: REJECTION_WINDOW_MS } : {}),
+        },
+    });
+    return true;
+}
+//# sourceMappingURL=reject-audit.js.map

package/dist/agent/webhooks/reject-audit.js.map

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

package/dist/agent/webhooks/replay-dedupe.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Retention for a nonce mark. A `signedTimestamp` verifier accepts any delivery whose timestamp
+ * sits in `[now - skew, now + skew]`, so the SAME (ts, signature) pair can still pass the GATE up
+ * to `2 * skew` seconds of wall-clock time after the earliest moment it could have been presented
+ * (send it stamped `now + skew` and it stays gate-acceptable until real time reaches `ts + skew`,
+ * i.e. `2 * skew` later). Retention must outlive that whole span, not just one skew width, or a
+ * replay could succeed again after the nonce mark expires but *before* the signature itself goes
+ * stale at the gate — which would be worse than not deduping at all (a false sense of single-use).
+ * The `+60s` is slack for store latency / clock drift, the same shape `webhookMaxSkewSeconds`
+ * itself carries over eve's tighter Linear default.
+ */
+export declare function webhookReplayNonceTtlMs(): number;
+/**
+ * Namespaces a verifier's opaque `replayKey` by the HOOK id. `webhooks/config.ts` places no
+ * cross-hook uniqueness constraint on `secretRef` — two DIFFERENT hooks can legitimately share a
+ * secret (e.g. the same CI job fanning the same signed payload out to two Slack channels via two
+ * hook ids), and no registered scheme signs the hook id: `oe-standard-webhook` covers
+ * `<id>.<timestamp>.<rawBody>` and nothing else. Nothing in the signed bytes distinguishes hooks. Without
+ * this namespace, hook B's first-ever delivery would collide with hook A's identical one and be
+ * silently dropped as a "replay" it never was. Keying by hook id makes each hook's single-use
+ * guarantee independent of every other hook's traffic.
+ */
+export declare function webhookReplayStoreKey(hookId: string, replayKey: string): string;
+/** Injectable mark-seen edge, matching every other durable-dedupe caller's shape in this tree
+ *  (routines/github-fanout.ts, webhooks/reject-audit.ts, channels/unified-redrive.ts). */
+export type MarkWebhookReplaySeen = (org: string, key: string, atIso: string, ttlMs: number) => Promise<boolean>;
+/** Test seam: forget the warn-once latch (mirrors resetRejectionThrottle's posture). */
+export declare function resetWebhookReplayWarnLatchForTest(): void;
+export interface WebhookReplayDeps {
+    readonly markSeen?: MarkWebhookReplaySeen;
+    readonly now?: () => Date;
+}
+/**
+ * TRUE = first sighting of this (hook, replayKey) pair within the retention window — the route
+ * should proceed to fire. FALSE = a duplicate — the route should reject it as a replay.
+ *
+ * FAILS OPEN (returns true) on ANY error from `markSeen` — the live default (the operational
+ * store's `markEventSeen`) or an injected one, same posture reject-audit.ts's own throttle takes
+ * (its try/catch wraps the injected edge too, not just its own default), which is why a test can
+ * exercise the fail-open path by injecting a throwing `markSeen` directly rather than having to
+ * break the real store to prove it.
+ *
+ * Called from channels/webhooks.ts between the gate's accepted outcome and `deliver`, and ONLY
+ * when the gate's outcome carried a `replayKey` (i.e. the resolved verifier declares
+ * `signedTimestamp: true`) — an untimestamped source never reaches this function at all.
+ */
+export declare function firstSightingOfWebhookDelivery(org: string, hookId: string, replayKey: string, deps?: WebhookReplayDeps): Promise<boolean>;
+/** The nonce-mark key's namespace prefix, exported only so a test can assert against it without
+ *  re-deriving the format inline. Not meant to be parsed by anything else. */
+export declare const WEBHOOK_REPLAY_KEY_PREFIX = "webhook-replay:";
+/** OPERATOR-FACING. The full text, unchanged — it goes into the throttled `auditRejection` row's
+ *  `detail.reason`, which is where a rejection's detail lives now. The operator loses nothing. */
+export declare const REPLAYED_DELIVERY_AUDIT_REASON = "duplicate delivery rejected \u2014 an already-accepted delivery was replayed inside its skew window";
+/** CALLER-FACING. A CONSTANT, and deliberately not a summary of the one above: it must be true of a
+ *  refusal without confirming that any earlier delivery was accepted. Anything of the form
+ *  "duplicate"/"replay"/"already" would re-state the oracle in fewer words. */
+export declare const REPLAYED_DELIVERY_CALLER_BODY = "delivery refused";
+//# sourceMappingURL=replay-dedupe.d.ts.map

package/dist/agent/webhooks/replay-dedupe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay-dedupe.d.ts","sourceRoot":"","sources":["../../../agent/webhooks/replay-dedupe.ts"],"names":[],"mappings":"AA6DA;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,CAEhD;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAE/E;AAED;0FAC0F;AAC1F,MAAM,MAAM,qBAAqB,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAIjH,wFAAwF;AACxF,wBAAgB,kCAAkC,IAAI,IAAI,CAEzD;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,QAAQ,CAAC,EAAE,qBAAqB,CAAC;IAC1C,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAC3B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,8BAA8B,CAClD,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,IAAI,GAAE,iBAAsB,GAC3B,OAAO,CAAC,OAAO,CAAC,CAelB;AAED;8EAC8E;AAC9E,eAAO,MAAM,yBAAyB,oBAAoB,CAAC;AA+B3D;kGACkG;AAClG,eAAO,MAAM,8BAA8B,wGAAmG,CAAC;AAE/I;;+EAE+E;AAC/E,eAAO,MAAM,6BAA6B,qBAAqB,CAAC"}

package/dist/agent/webhooks/replay-dedupe.js

@@ -0,0 +1,159 @@
+// Durable, restart-surviving SINGLE-USE replay dedupe for the generic webhook surface (OPE-176).
+// A timestamped scheme enforces a 300s skew window (`webhookMaxSkewSeconds`), which BOUNDS replay:
+// inside the window a captured, validly-signed delivery still re-POSTs successfully and fires the
+// hook again. This module marks the delivery identity a verifier accepted as SEEN, so a second
+// presentation of the SAME delivery is rejected even while its signature is still fresh — turning
+// the window from bounded into single-use.
+//
+// 🔴 NOT `channels/front-queue.ts`'s `EventDedupe`, even though OPE-164's own module doc named it
+// as the mechanism to wire up. That class's OWN doc says so: "In-memory per instance … a retry
+// landing on a DIFFERENT instance isn't caught here". It exists for Slack/Teams RETRY suppression,
+// where losing an entry on a cold start or a concurrently-scaled sibling instance is a harmless
+// double-wake, not a security property. A replay defence has to survive exactly the failure modes
+// EventDedupe was built to shrug off — a captured delivery re-POSTed after this instance recycled,
+// or routed to a sibling instance by the platform's own load balancing (this deployment runs on
+// Vercel; a cold Lambda starts with an EMPTY EventDedupe map every time). Reusing it here would
+// look like single-use while only actually holding within one warm instance — a false sense of
+// defence, the exact failure shape this ticket exists to close.
+//
+// `markEventSeen` (operational/store.ts) IS the mechanism: it is DB-backed, atomic across
+// instances, and is already the tree's settled answer to "has this key been durably seen before" —
+// routines/github-fanout.ts's delivery-id dedupe, channels/unified-redrive.ts's loop guard,
+// channels/session-park.ts's throttle, tools/run_routine_now.ts's window, routines/fire-audit.ts
+// and webhooks/reject-audit.ts's own throttles all already use it for this exact class of
+// question. `EventDedupe` and `markEventSeen` are TWO DIFFERENT mechanisms in this tree (ephemeral
+// in-process vs. durable cross-instance), not two names for one thing — this module deliberately
+// reuses the durable one rather than adding a third variant.
+//
+// ONLY TIMESTAMPED SOURCES PARTICIPATE. The gate (webhooks/gate.ts) hands the route a `replayKey`
+// ONLY when the resolved verifier declares `signedTimestamp: true`. WHICH sources those are is
+// registry state, so it is not enumerated here — this line used to say "currently just
+// `oe-standard-webhook`" and OPE-197 falsified it by registering Slack's `v0=` scheme, which signs
+// its timestamp too. What is stable is the RULE and the reason a source falls either side of it:
+// `github` and `notion` declare `signedTimestamp: false` because they sign the body alone, so there
+// is no freshness claim to bound a nonce's retention against. Dedupe-by-vendor-delivery-id
+// (`x-github-delivery` and Notion's equivalent) was considered as a substitute bound for those and
+// REJECTED: the delivery id rides inside the SAME captured HTTP request as the signature, so an
+// attacker who has one has the other, and a delivery-id-keyed store would still need an EXPIRY —
+// with no signed timestamp to derive one from, that expiry is exactly as arbitrary as inventing one
+// for the raw signature would be. It would convert "replay forever" into "replay for however long
+// we arbitrarily decided to remember", which is a real improvement in degree but NOT the same
+// GUARANTEE "single-use" claims for a timestamped source: there the bound comes from the SENDER's
+// own signed, verified claim (the signature itself goes invalid at the gate once skew is exceeded,
+// entirely independent of this store), not from an unaudited retention policy we picked ourselves.
+// Shipping it under this ticket's name would be a different guarantee wearing "single-use"'s label.
+// The honest shape stays what OPE-164's own doc concluded: dedupe timestamped sources only, and
+// leave github/notion on the reviewed `UNDEFENDED_REPLAY_SOURCES` allowlist (webhook-verifier-
+// test.ts, and each provider bundle's own verifier test asserts `signedTimestamp === false` for
+// its scheme) — visible, on the record, not silently "fixed" by a control that doesn't hold.
+//
+// FAIL-OPEN on a store error — same posture, same reasoning, as routines/github-fanout.ts's
+// `liveMarkSeen` and webhooks/reject-audit.ts's own throttle: this dedupe guards an ANNOYANCE (a
+// hook firing twice for one captured delivery inside the skew window), not the authentication
+// boundary itself — the HMAC already ran and passed before this ever executes. Failing CLOSED
+// here would hand an attacker who can degrade the operational store (or simply cause a transient
+// blip) a way to silence every webhook in the deployment by breaking or exhausting the dedupe
+// store — the same trade-off OPE-163 made for the veto judge's budget exhaustion (fail open,
+// because failing closed lets an attacker silence the very thing meant to protect against them).
+import { getOperationalStore } from "../operational/provider.js";
+import { webhookMaxSkewSeconds } from "./gate.js";
+/**
+ * Retention for a nonce mark. A `signedTimestamp` verifier accepts any delivery whose timestamp
+ * sits in `[now - skew, now + skew]`, so the SAME (ts, signature) pair can still pass the GATE up
+ * to `2 * skew` seconds of wall-clock time after the earliest moment it could have been presented
+ * (send it stamped `now + skew` and it stays gate-acceptable until real time reaches `ts + skew`,
+ * i.e. `2 * skew` later). Retention must outlive that whole span, not just one skew width, or a
+ * replay could succeed again after the nonce mark expires but *before* the signature itself goes
+ * stale at the gate — which would be worse than not deduping at all (a false sense of single-use).
+ * The `+60s` is slack for store latency / clock drift, the same shape `webhookMaxSkewSeconds`
+ * itself carries over eve's tighter Linear default.
+ */
+export function webhookReplayNonceTtlMs() {
+    return (webhookMaxSkewSeconds() * 2 + 60) * 1000;
+}
+/**
+ * Namespaces a verifier's opaque `replayKey` by the HOOK id. `webhooks/config.ts` places no
+ * cross-hook uniqueness constraint on `secretRef` — two DIFFERENT hooks can legitimately share a
+ * secret (e.g. the same CI job fanning the same signed payload out to two Slack channels via two
+ * hook ids), and no registered scheme signs the hook id: `oe-standard-webhook` covers
+ * `<id>.<timestamp>.<rawBody>` and nothing else. Nothing in the signed bytes distinguishes hooks. Without
+ * this namespace, hook B's first-ever delivery would collide with hook A's identical one and be
+ * silently dropped as a "replay" it never was. Keying by hook id makes each hook's single-use
+ * guarantee independent of every other hook's traffic.
+ */
+export function webhookReplayStoreKey(hookId, replayKey) {
+    return `webhook-replay:${hookId}:${replayKey}`;
+}
+let warnedReplayStore = false;
+/** Test seam: forget the warn-once latch (mirrors resetRejectionThrottle's posture). */
+export function resetWebhookReplayWarnLatchForTest() {
+    warnedReplayStore = false;
+}
+/**
+ * TRUE = first sighting of this (hook, replayKey) pair within the retention window — the route
+ * should proceed to fire. FALSE = a duplicate — the route should reject it as a replay.
+ *
+ * FAILS OPEN (returns true) on ANY error from `markSeen` — the live default (the operational
+ * store's `markEventSeen`) or an injected one, same posture reject-audit.ts's own throttle takes
+ * (its try/catch wraps the injected edge too, not just its own default), which is why a test can
+ * exercise the fail-open path by injecting a throwing `markSeen` directly rather than having to
+ * break the real store to prove it.
+ *
+ * Called from channels/webhooks.ts between the gate's accepted outcome and `deliver`, and ONLY
+ * when the gate's outcome carried a `replayKey` (i.e. the resolved verifier declares
+ * `signedTimestamp: true`) — an untimestamped source never reaches this function at all.
+ */
+export async function firstSightingOfWebhookDelivery(org, hookId, replayKey, deps = {}) {
+    const markSeen = deps.markSeen ?? ((o, k, at, ttl) => getOperationalStore().markEventSeen(o, k, at, ttl));
+    const nowIso = (deps.now?.() ?? new Date()).toISOString();
+    const key = webhookReplayStoreKey(hookId, replayKey);
+    try {
+        return await markSeen(org, key, nowIso, webhookReplayNonceTtlMs());
+    }
+    catch (err) {
+        if (!warnedReplayStore) {
+            warnedReplayStore = true;
+            console.warn(`[open-everywhere:webhooks] durable replay dedupe unavailable — a captured, validly-signed delivery could re-fire inside the skew window until the store recovers: ${String(err)}`);
+        }
+        return true; // fail OPEN: an availability blip must never silence a genuine delivery.
+    }
+}
+/** The nonce-mark key's namespace prefix, exported only so a test can assert against it without
+ *  re-deriving the format inline. Not meant to be parsed by anything else. */
+export const WEBHOOK_REPLAY_KEY_PREFIX = "webhook-replay:";
+// ═══ THE REFUSAL IS TWO STRINGS, NOT ONE (OPE-202, narrowed) ═══════════════════════════════════
+//
+// The other refusals on this surface answer an unauthenticated caller and deliberately say what
+// went wrong — a missing secret ref by name, the registered source list, the verifier's own throw
+// text. That posture is DEFENSIBLE and stays: every hook is config-declared in a merged PR
+// (OPE-224), so the audience for a 401 is the operator who wrote the hook and is looking at the
+// response to find out why their delivery bounced.
+//
+// This one is different in KIND, and that difference does not depend on who creates hooks. A
+// caller reaching this branch has already presented a VALID SIGNATURE — the replay check runs
+// downstream of the gate — so it is not an inventory disclosure to a stranger. It is an ORACLE:
+// the response tells whoever holds a captured delivery whether the ORIGINAL of that delivery
+// reached this deployment. That is a fact about someone else's traffic, and it is the one thing
+// on this surface a refusal has no reason to answer.
+//
+// ⚠️ THE STATUS IS STILL A COARSE ORACLE, AND THIS SPLIT DOES NOT CLOSE IT — read that plainly
+// rather than reading "the body is a constant" as "the oracle is gone". 409-vs-200 still separates
+// "already seen" from "first sighting". Closing it fully means answering a replay with the SAME
+// 200 a fresh delivery gets, which is defensible (a sender's only actionable question is "must I
+// retry", and the answer to both is no) — but it is a change to a PUBLISHED ingress contract:
+// `docs/capabilities/proactivity-and-routines.md` and `docs/extending/webhook-ingress.md` both
+// state the 409 to senders, the e2e driver exposes a pinned `deliveryId` for exactly that leg
+// (`scripts/e2e/webhook.ts` — the capability is there even though no scenario drives it yet), and
+// it would leave a legitimate sender unable to tell a deduped delivery from a processed one. So it
+// is a published-contract change with an observability cost on the operator's side — an operator's
+// posture call, not a cleanup. What this split buys is narrower and real: the refusal no longer
+// EXPLAINS the mechanism (a skew window exists, this hook dedupes, the original was accepted) to
+// the one caller positioned to use it.
+/** OPERATOR-FACING. The full text, unchanged — it goes into the throttled `auditRejection` row's
+ *  `detail.reason`, which is where a rejection's detail lives now. The operator loses nothing. */
+export const REPLAYED_DELIVERY_AUDIT_REASON = "duplicate delivery rejected — an already-accepted delivery was replayed inside its skew window";
+/** CALLER-FACING. A CONSTANT, and deliberately not a summary of the one above: it must be true of a
+ *  refusal without confirming that any earlier delivery was accepted. Anything of the form
+ *  "duplicate"/"replay"/"already" would re-state the oracle in fewer words. */
+export const REPLAYED_DELIVERY_CALLER_BODY = "delivery refused";
+//# sourceMappingURL=replay-dedupe.js.map

package/dist/agent/webhooks/replay-dedupe.js.map

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

package/dist/agent/webhooks/reveal-page.d.ts

@@ -0,0 +1,116 @@
+import { getOperationalStore } from "../operational/provider.js";
+import { REVEAL_GRANT_CONNECTOR } from "../credentials/page-token.js";
+import { type WebhookSenderGuidance } from "./verifier.js";
+/** The mounted route path — GET renders the confirm page, POST reveals. Same path for both. */
+export declare const REVEAL_PAGE_PATH = "/connect/v1/reveal";
+/** The `connector` label stamped on a reveal grant row, so a grant minted for a REVEAL can never be
+ *  mistaken for (or completed as) a credential INTAKE even though both live in `credential_intake`.
+ *  The audience claim already separates the tokens; this separates the ROWS.
+ *
+ *  DECLARED IN `credentials/page-token.ts` and re-exported here, where it is stamped. Both walls are
+ *  one separation and the intake side reads the SAME constant to refuse this class — two copies of
+ *  the string would open the wall in one direction the day they drift. */
+export { REVEAL_GRANT_CONNECTOR };
+/** How long a reveal link lives. Short on purpose — the human is standing at the keyboard, having
+ *  just clicked an approval card. */
+export declare const REVEAL_GRANT_TTL_MS: number;
+/** Can this deployment mint + serve reveal links? BOTH halves are required, and this is the
+ *  PROPOSE-TIME precondition: a tool that cannot deliver the secret must refuse to mint the hook
+ *  rather than mint one whose secret is unreachable. */
+export declare function revealPageAvailable(env?: NodeJS.ProcessEnv): boolean;
+/** Injectable edges — the live defaults are the real store + clock. */
+export interface RevealGrantDeps {
+    readonly getStore?: () => Pick<ReturnType<typeof getOperationalStore>, "addCredentialIntake" | "getCredentialIntake" | "consumeCredentialIntake" | "getStoredCredential">;
+    readonly now?: () => Date;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly newId?: () => string;
+}
+export interface IssueRevealLinkInput {
+    readonly org: string;
+    /** The vault ref the secret was just written under (`hook:<hookId>`). */
+    readonly ref: string;
+    /** The ONLY principal this reveal is bound to — the ASKER who requested the rotation, never the
+     *  approver who clicked (OPE-327). */
+    readonly revealTo: string;
+    /** Display-only label for the page copy (the hook's `source` handle). NEVER the hook id. */
+    readonly label: string;
+}
+/**
+ * Mint ONE reveal grant + the browser link that redeems it. Returns `undefined` when the page is not
+ * available on this deployment — the caller then refuses rather than handing out a dead link.
+ *
+ * NO NEW GRANT TABLE. This reuses `credential_intake` verbatim: same single-use CAS
+ * (`consumeCredentialIntake`), same TTL column, same bound-principal column. A second table modelling
+ * "an opaque, single-use, TTL'd, principal-bound capability" would be the same row with a different
+ * name plus a third backend triple to keep in sync — and the CAS is the ONE piece of this whose
+ * correctness genuinely matters, so sharing it is the point.
+ *
+ * The URL is CAPABILITY-BEARING. The caller delivers it privately and NEVER logs or audits it.
+ */
+export declare function issueRevealLink(input: IssueRevealLinkInput, deps?: RevealGrantDeps): Promise<{
+    id: string;
+    url: string;
+} | undefined>;
+/** Injectable deps for the handlers. `readSecret` is the vault read — injected so a test can drive
+ *  the ORDER (consume-then-read) rather than trusting the comment that says so. */
+export interface RevealPageDeps extends RevealGrantDeps {
+    /** Decrypted plaintext for a vault ref, or null. Live default: the encrypted KV vault. */
+    readonly readSecret?: (ref: string) => Promise<string | null>;
+    /** The public `POST /webhooks/<id>` URL for the hook this grant reveals, or undefined. Derived
+     *  from the grant's own REF, so the hook id never has to ride in the token or the page URL.
+     *  Live default: {@link revealEndpointUrl}. */
+    readonly endpointUrl?: (ref: string) => string | undefined;
+    /** What a sender must send for THIS hook's scheme, or undefined when we have nothing to say.
+     *  Resolved from the grant's own ref (ref ⇒ hook id ⇒ row ⇒ scheme ⇒ verifier), so nothing extra
+     *  rides in the token. Live default: {@link liveSenderGuidance}. */
+    readonly senderGuidance?: (ref: string, org: string) => Promise<WebhookSenderGuidance | undefined>;
+}
+/**
+ * GET {@link REVEAL_PAGE_PATH}?t=<token> — render the confirm page for a valid, unredeemed grant,
+ * else the generic 404.
+ *
+ * 🔴 ZERO SIDE EFFECTS. This function performs exactly two reads (the token verify and one store
+ * GET) and writes nothing, anywhere. Do not add a consume, a counter, an audit row, or a "seen"
+ * mark here: an unfurler fetching this URL must leave the grant exactly as it found it. A test
+ * drives three GETs and then asserts the POST still succeeds.
+ */
+export declare function handleRevealGet(req: Request, deps?: RevealPageDeps): Promise<Response>;
+/**
+ * POST {@link REVEAL_PAGE_PATH} (form-encoded `t`) — redeem the grant and show the secret once.
+ *
+ * ORDER IS THE SECURITY PROPERTY: verify → CONSUME (compare-and-set) → read the vault → AUDIT →
+ * render. A losing racer's CAS returns false and it never reaches the vault at all. There is no
+ * empty-input retry arm here (unlike the intake page's, which exists because a human can mistype a
+ * value): there is nothing for the human to type, so every POST that gets past verification is a
+ * genuine redemption and must burn the grant.
+ *
+ * ⭐ THE AUDIT ROW IS WRITTEN ON THE SUCCESS PATH ONLY (OPE-199), and only AFTER the value is in
+ * hand. A row written before the vault read would claim a disclosure that a decrypt failure then
+ * prevented — the one direction an audit log must never be wrong in. A redemption that dies at the
+ * vault leaves a SPENT grant and no `secret_revealed` row, which is the honest record: nothing was
+ * shown to anybody.
+ */
+export declare function handleRevealPost(req: Request, deps?: RevealPageDeps): Promise<Response>;
+/**
+ * The public ingress URL for the hook a reveal grant names — `<base>/webhooks/<hookId>`, derived
+ * from the grant's `hook:<hookId>` ref. This is the ONE place the hook id becomes visible, and it
+ * is visible only on the reveal page itself, beside the secret it has to be pasted next to. It
+ * inherits every one of that page's protections for free, and it still never enters model context,
+ * a channel, or a tool result. (Since OPE-199 the id DOES appear in one audit detail — the operator
+ * plane, where "which ingress is this?" has to be answerable, exactly as `webhook.created` already
+ * carried it. Model-facing surfaces are unchanged.)
+ */
+export declare function revealEndpointUrl(ref: string, env?: NodeJS.ProcessEnv): string | undefined;
+/**
+ * The RUNTIME HOOK id a grant's ref names, or undefined — recovered server-side from the ref, the
+ * same derivation {@link revealEndpointUrl} performs for the endpoint URL, and the reason neither the
+ * token nor the page URL ever has to carry an id.
+ *
+ * Undefined is a NORMAL answer, not a failure: a reveal grant can also carry a
+ * `notion-handshake:<workspaceId>` ref (OPE-195), which is not a runtime hook at all and has no id to
+ * report — the audit row then stands on `ref` alone, which is why it carries both fields. A
+ * ROTATION's `hook:<id>:prev` is likewise not a CURRENT hook ref and yields undefined, for the
+ * identical reason the endpoint URL refuses it.
+ */
+export declare function revealedHookId(ref: string): string | undefined;
+//# sourceMappingURL=reveal-page.d.ts.map

package/dist/agent/webhooks/reveal-page.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reveal-page.d.ts","sourceRoot":"","sources":["../../../agent/webhooks/reveal-page.ts"],"names":[],"mappings":"AA0FA,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAGjE,OAAO,EAAmE,sBAAsB,EAAE,MAAM,8BAA8B,CAAC;AAEvI,OAAO,EAAmB,KAAK,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAG5E,+FAA+F;AAC/F,eAAO,MAAM,gBAAgB,uBAAuB,CAAC;AAErD;;;;;;0EAM0E;AAC1E,OAAO,EAAE,sBAAsB,EAAE,CAAC;AAElC;qCACqC;AACrC,eAAO,MAAM,mBAAmB,QAAc,CAAC;AAI/C;;wDAEwD;AACxD,wBAAgB,mBAAmB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAEjF;AAID,uEAAuE;AACvE,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC,UAAU,CAAC,OAAO,mBAAmB,CAAC,EAAE,qBAAqB,GAAG,qBAAqB,GAAG,yBAAyB,GAAG,qBAAqB,CAAC,CAAC;IAC1K,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IAC1B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACjC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,yEAAyE;IACzE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB;0CACsC;IACtC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,4FAA4F;IAC5F,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,eAAe,CAAC,KAAK,EAAE,oBAAoB,EAAE,IAAI,GAAE,eAAoB,GAAG,OAAO,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAAC,CA0B/I;AAkGD;mFACmF;AACnF,MAAM,WAAW,cAAe,SAAQ,eAAe;IACrD,0FAA0F;IAC1F,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC9D;;mDAE+C;IAC/C,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;IAC3D;;wEAEoE;IACpE,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,qBAAqB,GAAG,SAAS,CAAC,CAAC;CACpG;AAaD;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,GAAE,cAAmB,GAAG,OAAO,CAAC,QAAQ,CAAC,CAchG;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,GAAE,cAAmB,GAAG,OAAO,CAAC,QAAQ,CAAC,CA+EjG;AA6BD;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,GAAG,SAAS,CAOvG;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAgB9D"}