@open-everywhere/core 0.1.0

package/dist/agent/webhooks/reveal-page.js

@@ -0,0 +1,443 @@
+// THE ONE-SHOT SECRET REVEAL PAGE (OPE-150) — the READ half of the credential front door, and the
+// inverse of everything credentials/intake-page.ts does.
+//
+// ⚠️ THE INVERSION, which is the whole reason this file is not a mode of the intake page. An API
+// key is a COLLECT surface: the human holds a secret and gives it to us, so the worst outcome of a
+// wrong holder is that a credential gets STORED (witnessed, audited, ref-bearing). A webhook is a
+// REVEAL surface: WE mint the signing secret and the external system needs it, so the worst outcome
+// of a wrong holder is that a live secret is DISCLOSED. `intake-page.ts` pre-registered this exact
+// flip condition in its own header, verbatim: its channel-posted-link trade is accepted *"because
+// the capability is strictly WRITE-ONLY … What would change this: making the page identity-bearing,
+// which is the right move the moment the page ever grows a READ affordance."* This is that moment,
+// so the rules here are strictly stronger than the intake page's, on every axis.
+//
+// 🔴 THE SECRET IS NEVER RENDERED AS TEXT ON ANY CONVERSATIONAL SURFACE — EVER. Not in a message,
+// not in an ephemeral message, not in an approval card, not in a tool result, not in an audit
+// detail. It exists on exactly one page, behind one single-use link, and after that it is
+// unrecoverable. That decision (Tommy, 2026-07-27) works on every surface including the ones with
+// no ephemeral concept at all (GitHub, Notion, Linear), leaves NOTHING in scrollback that a later
+// membership change could expose, and reduces "ephemeral messaging" from a second way of handling
+// the secret to merely a nicer way of delivering the LINK where a surface supports it.
+//
+// 🔴 GET MUST NOT CONSUME — POST DOES. THIS IS THE MOST LIKELY THING A FUTURE EDITOR "SIMPLIFIES",
+// AND ITS FAILURE IS SILENT.
+//
+//   Slack unfurls links. Link scanners, browser prefetchers, corporate antivirus proxies and
+//   security-mail gateways all GET a URL the moment it appears anywhere. A consume-on-GET reveal is
+//   therefore BURNED before the human ever clicks — and what the human then sees is the generic
+//   404, which is indistinguishable from "expired", so the failure reads as a bug and the recovery
+//   (rotate, admin-gated) is expensive. So:
+//
+//     GET  — verify the token, confirm the grant is still open, render a CONFIRM PAGE with a button
+//            and NO SECRET. Zero side effects. Idempotent. Safe for any bot to fetch N times.
+//     POST — verify the token, CAS-CONSUME THE GRANT FIRST, and only THEN read the vault.
+//
+//   CONSUME-BEFORE-DECRYPT is what makes the grant genuinely one-shot rather than
+//   probably-one-shot: a burned row can never reach the vault, so there is no window in which a
+//   racing second POST reads a value it then fails to record having read. It also means a vault
+//   read that fails leaves the grant SPENT — deliberately. "The reveal failed, rotate and try
+//   again" is the safe direction; "the reveal failed, so have another go at reading the secret" is
+//   a retry loop on a disclosure oracle.
+//
+// FAIL CLOSED WITH NO ORACLE. Bad/expired/tampered token, wrong audience, unknown/consumed/expired
+// grant, wrong bound principal, vault miss, decrypt failure — ALL of them render the ONE generic
+// 404 page with identical copy, so a holder learns nothing about what exists. No signing key
+// configured ⇒ both routes 404 (the endpoint effectively does not exist), the same posture as the
+// intake page and oe-oauth-callback.
+//
+// HEADERS. `Cache-Control: no-store` and `noindex,nofollow` as the intake page has, PLUS
+// `Referrer-Policy: no-referrer` — NEW here and load-bearing: a page that renders a secret must not
+// leak its own token in a `Referer` header if anything on it is ever clicked. There are no outbound
+// links on the page for exactly the same reason; the header is the belt.
+//
+// THE SECRET APPEARS EXACTLY ONCE IN THE RENDERED HTML, as escaped text inside one <code> element.
+// Never in a URL, never in an attribute, never in a hidden field, never in an error string. A test
+// asserts the count and the absence from every attribute position, because "it is only in the body"
+// is the kind of claim that stops being true one refactor later.
+//
+// ⭐ THE SUCCESS PAGE ALSO SAYS HOW TO SEND (OPE-198 S3's second owed item). Until 2026-07-27 this
+// page handed over a signing secret and an endpoint URL and said nothing about what to DO with them
+// — which headers, what the signature covers, how fresh the timestamp must be — so a person holding
+// the one thing this page exists to give them still could not finish the job. The copy is the HOOK'S
+// OWN SCHEME's (`WebhookVerifier.senderGuidance`), never a generic blob: the two schemes we ship
+// agree on no header name, no basestring and no digest encoding, so one paragraph for both would be
+// wrong for at least one of them. SUCCESS PATH ONLY, and it is not an oracle — see `guidanceHtml`.
+//
+// NO RE-REVEAL PATH EXISTS IN THIS CODE, and that is a design decision rather than an omission. A
+// re-reveal would make every hook row a standing disclosure oracle any admin can tap with one
+// click — and in the audit log a re-reveal is INDISTINGUISHABLE from an attacker-driven
+// exfiltration of a live production secret. Rotation costs the human identical work, bounds
+// disclosure to material minted FOR that disclosure, and invalidates what was previously disclosed.
+// Lost secret ⇒ rotate.
+//
+// ⭐ THE REDEMPTION IS AUDITED (OPE-199). `webhook.created`'s `revealDelivered` records only that a
+// link was SENT; without a row here, "did anyone actually collect that secret, and when?" is
+// unanswerable for the one act in this subsystem that puts a live signing key in front of a human.
+//
+// 🔴 IT IS THE **OUTWARD** HALF OF A PAIR AND CURRENTLY THE ONLY ONE (OPE-207). Its twin,
+// `webhook.secret_captured`, recorded a key crossing INWARD — a vendor's own value pasted through a
+// setup page — and that page is deleted, so every hook's key is minted host-side and this outward
+// crossing is the only one left. If an inward arm ever returns, its row returns with it: the operator
+// question is "how did this key get in or out, and who was standing there", and half an answer to
+// that reads like a whole one.
+//
+// ⚠️ NECESSARY BUT NOT SUFFICIENT, in those words. `appendAudit` is BEST-EFFORT BY CONTRACT (it
+// never throws — audit/audit.ts), so "every disclosure leaves a row" is a property of the code path,
+// not a guarantee about the log. It cannot be made fail-closed here either, because a failure is not
+// observable to this caller. Do not upgrade the sentence.
+import { randomUUID } from "node:crypto";
+import { appendAudit } from "../audit/audit.js";
+import { getOperationalStore } from "../operational/provider.js";
+import { getConfig } from "../access/config.js";
+import { escapeHtml as esc, securePageResponse, BUTTON_STYLE, CODE_BLOCK_STYLE } from "../credentials/page-chrome.js";
+import { mintPageToken, pageBaseUrl, verifyPageToken, PAGE_TOKEN_KEY_ENV, REVEAL_GRANT_CONNECTOR } from "../credentials/page-token.js";
+import { getOrMintSelfSecret, selfSecretsArmed } from "../credentials/self-secrets.js";
+import { webhookVerifier } from "./verifier.js";
+/** The mounted route path — GET renders the confirm page, POST reveals. Same path for both. */
+export 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 const REVEAL_GRANT_TTL_MS = 15 * 60_000;
+const TOKEN_FIELD = "t";
+/** 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 function revealPageAvailable(env = process.env) {
+    return selfSecretsArmed() && pageBaseUrl(env) !== undefined;
+}
+/**
+ * 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 async function issueRevealLink(input, deps = {}) {
+    const env = deps.env ?? process.env;
+    const base = pageBaseUrl(env);
+    if (!base || !selfSecretsArmed())
+        return undefined;
+    const secret = await getOrMintSelfSecret(PAGE_TOKEN_KEY_ENV, { env });
+    const now = (deps.now ?? (() => new Date()))();
+    const expiresAt = new Date(now.getTime() + REVEAL_GRANT_TTL_MS).toISOString();
+    const id = (deps.newId ?? randomUUID)();
+    await (deps.getStore ?? getOperationalStore)().addCredentialIntake({
+        org: input.org,
+        id,
+        ref: input.ref,
+        connector: REVEAL_GRANT_CONNECTOR,
+        domain: input.label,
+        requestedBy: input.revealTo,
+        // `channel_id` is NOT NULL on the row and exists for the intake flow's wrong-clicker notice.
+        // A reveal has no channel affordance at all — the secret never touches a conversation — so it
+        // is stamped with the route rather than a real surface. Deliberately not a channel id: nothing
+        // must ever be tempted to post here.
+        channelId: REVEAL_PAGE_PATH,
+        createdAt: now.toISOString(),
+        expiresAt,
+    });
+    const token = mintPageToken({ v: 1, aud: "reveal", org: input.org, id, rb: input.revealTo, exp: Date.parse(expiresAt) }, secret);
+    return { id, url: `${base}${REVEAL_PAGE_PATH}?${TOKEN_FIELD}=${encodeURIComponent(token)}` };
+}
+// --- page rendering (self-contained, no external assets, no outbound links) ------------------------
+//
+// The skeleton, the escape and the three security headers now live in `credentials/page-chrome.ts`
+// — extracted VERBATIM from this file when the collect/endpoint pages arrived (OPE-198 S6), so this
+// page's bytes are unchanged. What deliberately did NOT move is the COPY below: each route's
+// generic-failure body is its own, because "every failure on THIS route renders identically" is a
+// per-route property and one shared body would say nothing extra while being less useful to the
+// human who legitimately hit it.
+const htmlResponse = securePageResponse;
+/** THE ONE generic failure — identical copy for every reason, so a holder learns nothing (no
+ *  oracle). Always 404. */
+function invalidPage() {
+    return htmlResponse(404, "This link is not valid", `<p>This link is not valid, or it has already been used or expired. Secrets are shown once and cannot be shown again — ` +
+        `ask for the webhook to be <strong>rotated</strong>, which issues a fresh secret and a fresh link.</p>`);
+}
+/** The GET confirm page: a button and NO SECRET. Rendering this has ZERO side effects, so an
+ *  unfurler, prefetcher or scanner fetching the URL cannot burn the grant. */
+function confirmPage(token, label) {
+    const inner = `<p>You're about to see the signing secret for the <strong>${esc(label)}</strong> webhook.</p>` +
+        `<p><strong>It is shown once.</strong> Nothing here or anywhere else can show it to you again — if you lose it, ` +
+        `the webhook has to be rotated, which issues a new secret. Have the place you're pasting it into open before you continue.</p>` +
+        `<form method="post" action="${esc(REVEAL_PAGE_PATH)}" autocomplete="off">` +
+        `<input type="hidden" name="${TOKEN_FIELD}" value="${esc(token)}">` +
+        `<button type="submit" style="${BUTTON_STYLE}">Show the secret</button>` +
+        `</form>`;
+    return htmlResponse(200, "Show a webhook signing secret", inner);
+}
+/**
+ * ⭐ HOW TO ACTUALLY SEND — the gap this page had until OPE-198 S3's second owed item.
+ *
+ * The page's entire job is to put a human in a position to configure a sender, and it was handing
+ * over a secret and an endpoint URL with NOTHING about which headers to set, what the signature
+ * covers, or how fresh the timestamp has to be. Those facts are unguessable and scheme-specific:
+ * Two registered schemes typically share not one header name, signed content or digest encoding
+ * between them. A generic blob would therefore be worse than nothing — it would be wrong for at
+ * least one scheme — so the copy comes from THE HOOK'S OWN SCHEME
+ * ({@link WebhookSenderGuidance}, declared next to the verifier that enforces it).
+ *
+ * 🔴 THIS IS NOT AN ORACLE, AND THE PROPERTY IS WORTH STATING BECAUSE THE PAGE'S FAILURE MODES ARE
+ * DELIBERATELY UNIFORM. It renders ONLY on the success path — after a validly-signed token, an open
+ * grant, the bound principal, a won CAS and a successful vault read. Whoever sees it is already
+ * holding this hook's live signing secret, so "which scheme is it" is strictly less than they have.
+ * Nothing here is reachable from any failure, and every failure on this route still renders the ONE
+ * generic 404 with byte-identical copy.
+ *
+ * ABSENT GUIDANCE RENDERS NOTHING AT ALL — a vendor-issued scheme has no instructions we are
+ * entitled to give, and an unresolvable hook (revoked between mint and redemption, a store hiccup,
+ * a `notion-handshake:` ref that names no hook) must still show the secret rather than 404 a
+ * disclosure that has already been paid for. The block is additive; its absence is the old page.
+ */
+function guidanceHtml(g) {
+    const headers = g.headers.map((h) => `<li><code>${esc(h.name)}</code>: ${esc(h.value)}</li>`).join("");
+    const notes = g.notes.map((t) => `<li style="margin-bottom:.35rem">${esc(t)}</li>`).join("");
+    return (`<p style="margin-top:1.5rem">…and make it send these headers on every delivery:</p>` +
+        `<ul style="padding-left:1.2rem">${headers}</ul>` +
+        `<p>The signature is computed over exactly this, with no separator or whitespace of its own:</p>` +
+        `<pre style="${CODE_BLOCK_STYLE}"><code>${esc(g.signedContent)}</code></pre>` +
+        `<ul style="padding-left:1.2rem">${notes}</ul>`);
+}
+/**
+ * The reveal page. The secret appears EXACTLY ONCE, as escaped text inside one <code> element —
+ * never in a URL, an attribute, a hidden field or a link. There are no outbound links on this page.
+ *
+ * ⚠️ THE GUIDANCE BLOCK MUST NEVER INTERPOLATE `secret`. Everything {@link WebhookSenderGuidance}
+ * carries is a TEMPLATE, and the "exactly once" test is what holds that line: a guidance string that
+ * echoed the value would make the count two and go red.
+ */
+function secretPage(label, endpointUrl, secret, guidance) {
+    const endpoint = endpointUrl
+        ? `<p style="margin-top:1.5rem">Point the sender at this URL:</p>` +
+            `<pre style="${CODE_BLOCK_STYLE}"><code>${esc(endpointUrl)}</code></pre>`
+        : "";
+    const inner = `<p>The signing secret for the <strong>${esc(label)}</strong> webhook. <strong>Copy it now</strong> — this page cannot be reloaded ` +
+        `and the secret cannot be shown again.</p>` +
+        `<pre style="${CODE_BLOCK_STYLE}"><code>${esc(secret)}</code></pre>` +
+        endpoint +
+        (guidance ? guidanceHtml(guidance) : "") +
+        `<p style="margin-top:1.5rem;color:#666">This link is now used up. You can close this tab.</p>`;
+    return htmlResponse(200, "Webhook signing secret", inner);
+}
+/** Is this grant row still redeemable at `nowMs` by the token's bound principal? */
+function grantOpen(row, boundTo, nowMs) {
+    return (row !== null &&
+        !row.usedAt &&
+        row.connector === REVEAL_GRANT_CONNECTOR && // a reveal token may only ever redeem a REVEAL grant
+        row.requestedBy === boundTo &&
+        Date.parse(row.expiresAt) > nowMs);
+}
+/**
+ * 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 async function handleRevealGet(req, deps = {}) {
+    const env = deps.env ?? process.env;
+    if (!selfSecretsArmed())
+        return new Response("not found", { status: 404 });
+    const secret = await getOrMintSelfSecret(PAGE_TOKEN_KEY_ENV, { env });
+    const nowMs = (deps.now ?? (() => new Date()))().getTime();
+    const token = new URL(req.url).searchParams.get(TOKEN_FIELD) ?? "";
+    const claims = verifyPageToken(token, secret, "reveal", nowMs);
+    if (!claims)
+        return invalidPage();
+    const row = await (deps.getStore ?? getOperationalStore)().getCredentialIntake(claims.org, claims.id);
+    if (!grantOpen(row, claims.rb, nowMs))
+        return invalidPage();
+    // `domain` carries the display label (the hook's `source`); never the id.
+    return confirmPage(token, row.domain ?? "webhook");
+}
+/**
+ * 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 async function handleRevealPost(req, deps = {}) {
+    const env = deps.env ?? process.env;
+    if (!selfSecretsArmed())
+        return new Response("not found", { status: 404 });
+    const signingKey = await getOrMintSelfSecret(PAGE_TOKEN_KEY_ENV, { env });
+    const now = (deps.now ?? (() => new Date()))();
+    const nowMs = now.getTime();
+    let form;
+    try {
+        form = await req.formData();
+    }
+    catch {
+        return invalidPage();
+    }
+    const token = typeof form.get(TOKEN_FIELD) === "string" ? form.get(TOKEN_FIELD) : "";
+    const claims = verifyPageToken(token, signingKey, "reveal", nowMs);
+    if (!claims)
+        return invalidPage();
+    const store = (deps.getStore ?? getOperationalStore)();
+    const row = await store.getCredentialIntake(claims.org, claims.id);
+    if (!grantOpen(row, claims.rb, nowMs))
+        return invalidPage();
+    // 🔴 CONSUME BEFORE DECRYPT. The CAS is the single-use guarantee; doing it first means a burned
+    // row can never reach the vault, and a lost race is refused with the same generic page.
+    const won = await store.consumeCredentialIntake(claims.org, claims.id, now.toISOString());
+    if (!won)
+        return invalidPage();
+    const readSecret = deps.readSecret ?? liveReadSecret;
+    let value;
+    try {
+        value = await readSecret(row.ref);
+    }
+    catch {
+        // A decrypt/store failure leaves the grant SPENT, deliberately (see the header). Same generic
+        // page — the failure reason is never an oracle, and never surfaced to the holder.
+        return invalidPage();
+    }
+    if (!value)
+        return invalidPage();
+    // 🔴 THE DISCLOSURE ROW (OPE-199). The hook id is recovered SERVER-SIDE from the grant's own ref —
+    // the derivation `revealEndpointUrl` already does — so it never had to ride in the token, the URL
+    // or the page. `grantId` is here because it is what makes two rows for one hook distinguishable
+    // (a rotation issues a second grant), and because it is the join back to who the link was minted
+    // for. THE VALUE IS NOT HERE, and no field derived from it is: this file's whole thesis is that
+    // the secret exists on one page and nowhere else, and an audit detail is "nowhere else".
+    const hookId = revealedHookId(row.ref);
+    await appendAudit({
+        org: claims.org,
+        // There is no conversational surface behind a page redemption — the grant's `channel_id` is the
+        // ROUTE, deliberately (see `issueRevealLink`). So the audit partition names the route too,
+        // exactly as the intake page's does, rather than borrowing a channel that was never involved.
+        platform: "web",
+        workspace: "reveal-page",
+        surface: REVEAL_PAGE_PATH,
+        // The BOUND principal — the ASKER the link was minted for (OPE-327). The page has no login, so this is
+        // an attribution to whoever the grant was bound to, not proof of who was at the keyboard. That
+        // is the same claim `rb` carries everywhere else and it is not upgraded here.
+        principalId: row.requestedBy,
+        action: "webhook.secret_revealed",
+        detail: {
+            ...(hookId ? { hookId } : {}),
+            ref: row.ref,
+            grantId: claims.id,
+            revealedAt: now.toISOString(),
+        },
+    });
+    // 🔴 LAST, AND SWALLOWED. The grant is already burned and the value is already in hand, so from
+    // here the ONLY safe direction is "render the secret". A store failure or a hook that vanished
+    // between mint and redemption costs the INSTRUCTIONS; it must never cost the disclosure the human
+    // spent their one-shot link on, and it must never become a 404 — that would be the page's generic
+    // failure telling a truthful holder their link was invalid.
+    let guidance;
+    try {
+        guidance = await (deps.senderGuidance ?? liveSenderGuidance)(row.ref, claims.org);
+    }
+    catch {
+        guidance = undefined;
+    }
+    return secretPage(row.domain ?? "webhook", (deps.endpointUrl ?? ((r) => revealEndpointUrl(r, env)))(row.ref), value, guidance);
+}
+/**
+ * The live scheme→guidance resolution: the grant's ref names a hook, the hook declares a scheme, the
+ * scheme's verifier declares what a sender must send.
+ *
+ * READ-ONLY AND SIDE-EFFECT-FREE, and it runs AFTER the disclosure is committed — see the call site
+ * for why its failure is swallowed rather than surfaced.
+ *
+ * The config registry is the whole answer, and it needs no org test: the registry IS this
+ * deployment's.
+ *
+ * WRAPPED, because the app-config seam is not guaranteed to be armed in every process that can serve
+ * this route (`getConfig` THROWS when nothing registered it) — the same treatment `achievabilityNote`
+ * gives it, and for the same reason: an unarmed registry must degrade to "we have nothing to say",
+ * never take out a disclosure the human already spent their one link on.
+ */
+async function liveSenderGuidance(ref, _org) {
+    const hookId = revealedHookId(ref);
+    if (!hookId)
+        return undefined; // a `notion-handshake:` ref names no hook — normal
+    let declared;
+    try {
+        declared = (getConfig().loadWebhooks?.() ?? []).find((h) => h.id === hookId);
+    }
+    catch {
+        declared = undefined;
+    }
+    return declared ? webhookVerifier(declared.source)?.senderGuidance?.() : undefined;
+}
+/**
+ * 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 function revealEndpointUrl(ref, env = process.env) {
+    const base = pageBaseUrl(env);
+    // ONE derivation, shared with the audit row: a ROTATION's `hook:<id>:prev` ref must never resolve
+    // to an endpoint (a reveal only ever discloses the CURRENT key), and a non-`hook:` ref names no
+    // hook at all. {@link revealedHookId} holds both rules so the two consumers cannot disagree.
+    const hookId = revealedHookId(ref);
+    return base && hookId ? `${base}/webhooks/${hookId}` : 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 function revealedHookId(ref) {
+    // ⭐ THE CONFIG-HOOK GRAMMAR (OPE-224) — `db:webhook:<id>`, the ref `declare_webhook` derives for a
+    // `broker: "db"` declaration. ONE derivation serves both grammars so a reveal cannot render its
+    // endpoint from one rule and audit its id from another. A hand-written ref matches neither and
+    // yields undefined, which is the honest answer.
+    //
+    // 🔴 SURFACING THIS ID IS NOT A DISCLOSURE: a declared hook's id is the path segment of a URL that
+    // lives in a merged, human-reviewed diff — public by construction.
+    const dbHook = "db:webhook:";
+    if (ref.startsWith(dbHook)) {
+        const rest = ref.slice(dbHook.length);
+        return rest.length > 0 && !rest.includes(":") ? rest : undefined;
+    }
+    if (!ref.startsWith("hook:"))
+        return undefined;
+    const rest = ref.slice("hook:".length);
+    return rest.length > 0 && !rest.includes(":") ? rest : undefined;
+}
+/** The live vault read. Imported lazily so this module stays unit-testable without the AES key
+ *  environment — the reveal handlers take `readSecret` as a dep and tests always supply it. */
+async function liveReadSecret(ref) {
+    const { encryptedKvVault } = await import("../credentials/kv-vault.js");
+    return encryptedKvVault().read(ref);
+}
+//# sourceMappingURL=reveal-page.js.map

package/dist/agent/webhooks/reveal-page.js.map

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

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

@@ -0,0 +1,17 @@
+import { type WebhookHook } from "./config.js";
+/** Injectable edges — the live default is `getSecretVia` + console. */
+export interface ResolveHookKeysDeps {
+    readonly getSecret?: (broker: string, ref: string) => Promise<string>;
+    readonly log?: (msg: string) => void;
+}
+/**
+ * Resolve a hook's shared HMAC key(s) through its ONE home broker, in declaration order
+ * (current first). Returns an empty list when the current key can't be resolved — see the
+ * module doc for why that discards any previous key too.
+ *
+ * Never throws: a broker that isn't registered, a ref with nothing behind it, and a broker
+ * that errors mid-read are all the same answer to this surface — "we cannot authenticate this
+ * sender", which is the gate's 401.
+ */
+export declare function resolveHookKeys(hook: WebhookHook, deps?: ResolveHookKeysDeps): Promise<readonly string[]>;
+//# sourceMappingURL=secrets.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"secrets.d.ts","sourceRoot":"","sources":["../../../agent/webhooks/secrets.ts"],"names":[],"mappings":"AA0BA,OAAO,EAAkB,KAAK,WAAW,EAAE,MAAM,aAAa,CAAC;AAM/D,uEAAuE;AACvE,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACtE,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CACtC;AAED;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,WAAW,EAAE,IAAI,GAAE,mBAAwB,GAAG,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,CAiCnH"}

package/dist/agent/webhooks/secrets.js

@@ -0,0 +1,73 @@
+// Hook secret resolution — the ONE place a webhook's shared HMAC key(s) come from (OPE-158).
+//
+// ONE MECHANISM, NOT TWO. A hook's key rides `secretRef` + `broker` (access/bundle.ts:85-99) and
+// resolves through `getSecretVia` (access/credentials.ts), which looks the named home broker up in
+// the registry and FAILS CLOSED when it isn't there rather than guessing — exactly like every other
+// secret in this tree. There is NO bare-env path and no compatibility shim: `broker: "env"` is the
+// env broker (`process.env[ref]`, credentials.ts:54-60), and any other registered home works the
+// same way, e.g. `broker: "db"` for a secret held in our own AES vault (credentials/db-broker.ts)
+// where a config diff cannot reach it.
+//
+// ORDERED KEYS, CURRENT FIRST. `secretRef` is a list (webhooks/config.ts) so a key rotation has
+// an overlap window: new key at index 0, outgoing key at index 1 until every sender has moved.
+// Resolution keeps that order, and the gate verifies against each key in turn.
+//
+// FAILURE POLICY — asymmetric ON PURPOSE:
+//   - index 0 (the CURRENT key) unresolvable  -> return NO keys at all. The config is broken (or
+//     a rotation was botched); accepting deliveries on the outgoing key alone would silently run
+//     the ingress on a key the operator believes they have retired. No keys -> the gate's
+//     existing fail-closed 401.
+//   - index >0 (a PREVIOUS key) unresolvable  -> NORMAL: the rotation finished and the var/row
+//     was deleted. Drop it, preserve the order of what remains, debug-log only.
+//
+// NEVER LOGS A SECRET VALUE. Refs and broker names are pointers (the same class of information
+// the 401 reason has always carried); resolved values are returned and never printed.
+import { getSecretVia } from "../access/credentials.js";
+import { hookSecretRefs } from "./config.js";
+function debug(msg) {
+    console.log(`[open-everywhere:webhooks] ${msg}`);
+}
+/**
+ * Resolve a hook's shared HMAC key(s) through its ONE home broker, in declaration order
+ * (current first). Returns an empty list when the current key can't be resolved — see the
+ * module doc for why that discards any previous key too.
+ *
+ * Never throws: a broker that isn't registered, a ref with nothing behind it, and a broker
+ * that errors mid-read are all the same answer to this surface — "we cannot authenticate this
+ * sender", which is the gate's 401.
+ */
+export async function resolveHookKeys(hook, deps = {}) {
+    const getSecret = deps.getSecret ?? ((broker, ref) => getSecretVia(broker, ref));
+    const log = deps.log ?? debug;
+    const refs = hookSecretRefs(hook);
+    const keys = [];
+    for (const [i, ref] of refs.entries()) {
+        let value;
+        try {
+            value = await getSecret(hook.broker, ref);
+        }
+        catch (err) {
+            // The message names the broker/ref (pointers), never a value — and `getSecretVia`'s own
+            // errors are the same shape, so a missing home broker reads as clearly as a missing ref.
+            if (i === 0) {
+                log(`hook "${hook.id}": current secret (secretRef[0], broker "${hook.broker}") did not resolve — no keys, deliveries will 401: ${String(err instanceof Error ? err.message : err)}`);
+                return [];
+            }
+            log(`hook "${hook.id}": previous secret (secretRef[${i}], broker "${hook.broker}") did not resolve — treating the rotation as complete`);
+            continue;
+        }
+        // A broker that resolves to empty string is indistinguishable from "not set" for HMAC
+        // purposes; treat it exactly like an unresolved ref rather than HMAC-ing with "".
+        if (!value) {
+            if (i === 0) {
+                log(`hook "${hook.id}": current secret (secretRef[0], broker "${hook.broker}") resolved empty — no keys, deliveries will 401`);
+                return [];
+            }
+            log(`hook "${hook.id}": previous secret (secretRef[${i}], broker "${hook.broker}") resolved empty — dropping it`);
+            continue;
+        }
+        keys.push(value);
+    }
+    return keys;
+}
+//# sourceMappingURL=secrets.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"secrets.js","sourceRoot":"","sources":["../../../agent/webhooks/secrets.ts"],"names":[],"mappings":"AAAA,6FAA6F;AAC7F,EAAE;AACF,iGAAiG;AACjG,mGAAmG;AACnG,oGAAoG;AACpG,mGAAmG;AACnG,iGAAiG;AACjG,kGAAkG;AAClG,uCAAuC;AACvC,EAAE;AACF,gGAAgG;AAChG,+FAA+F;AAC/F,+EAA+E;AAC/E,EAAE;AACF,0CAA0C;AAC1C,iGAAiG;AACjG,iGAAiG;AACjG,0FAA0F;AAC1F,gCAAgC;AAChC,+FAA+F;AAC/F,gFAAgF;AAChF,EAAE;AACF,+FAA+F;AAC/F,sFAAsF;AAEtF,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EAAE,cAAc,EAAoB,MAAM,aAAa,CAAC;AAE/D,SAAS,KAAK,CAAC,GAAW;IACxB,OAAO,CAAC,GAAG,CAAC,8BAA8B,GAAG,EAAE,CAAC,CAAC;AACnD,CAAC;AAQD;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,IAAiB,EAAE,IAAI,GAAwB,EAAE;IACrF,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,CAAC,CAAC,MAAc,EAAE,GAAW,EAAE,EAAE,CAAC,YAAY,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC;IACjG,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,KAAK,CAAC;IAC9B,MAAM,IAAI,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;IAClC,MAAM,IAAI,GAAa,EAAE,CAAC;IAE1B,KAAK,MAAM,CAAC,CAAC,EAAE,GAAG,CAAC,IAAI,IAAI,CAAC,OAAO,EAAE,EAAE,CAAC;QACtC,IAAI,KAAyB,CAAC;QAC9B,IAAI,CAAC;YACH,KAAK,GAAG,MAAM,SAAS,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QAC5C,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,wFAAwF;YACxF,yFAAyF;YACzF,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;gBACZ,GAAG,CAAC,SAAS,IAAI,CAAC,EAAE,4CAA4C,IAAI,CAAC,MAAM,sDAAsD,MAAM,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;gBACrL,OAAO,EAAE,CAAC;YACZ,CAAC;YACD,GAAG,CAAC,SAAS,IAAI,CAAC,EAAE,iCAAiC,CAAC,cAAc,IAAI,CAAC,MAAM,wDAAwD,CAAC,CAAC;YACzI,SAAS;QACX,CAAC;QACD,sFAAsF;QACtF,kFAAkF;QAClF,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;gBACZ,GAAG,CAAC,SAAS,IAAI,CAAC,EAAE,4CAA4C,IAAI,CAAC,MAAM,kDAAkD,CAAC,CAAC;gBAC/H,OAAO,EAAE,CAAC;YACZ,CAAC;YACD,GAAG,CAAC,SAAS,IAAI,CAAC,EAAE,iCAAiC,CAAC,cAAc,IAAI,CAAC,MAAM,iCAAiC,CAAC,CAAC;YAClH,SAAS;QACX,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACnB,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}