@open-everywhere/provider-notion 0.1.0

package/dist/agent/channels/notion-webhook-timing.js

@@ -0,0 +1,99 @@
+// notion-webhook-timing — WHERE A NOTION WEBHOOK ACK'S SECONDS WENT (OPE-1929).
+//
+// Notion's comment route deliberately acknowledges only after the wake has been durably accepted.
+// That makes every REST/store/queue wait on the path part of the webhook's observed latency. Keep
+// this collector pure and injectable: production records one content-free sample, while a fake
+// clock can prove the attribution without sleeping or calling a service.
+export const NOTION_WEBHOOK_TIMING_ACTION = "notion.webhook_timing";
+/**
+ * Run one whole route request and emit exactly one final sample. The caller decides when a normal
+ * outcome is final; any throw before that point becomes `threw` and is rethrown unchanged. Emission
+ * itself is telemetry and therefore fail-soft — it can never replace the HTTP result or error.
+ */
+export async function runNotionWebhookTimed(timing, emit, operation) {
+    let emitted = false;
+    const finish = (outcome) => {
+        if (emitted)
+            return;
+        emitted = true;
+        try {
+            emit(timing.detail(outcome));
+        }
+        catch {
+            // Timing telemetry never changes the route's own result.
+        }
+    };
+    try {
+        return await operation(finish);
+    }
+    catch (err) {
+        finish("threw");
+        throw err;
+    }
+}
+function duration(start, end) {
+    const elapsed = end - start;
+    return Number.isFinite(elapsed) && elapsed > 0 ? elapsed : 0;
+}
+const millis = (elapsed) => Math.round(elapsed);
+/**
+ * Create one request-scoped recorder. Phases accumulate because some operations in a phase are
+ * separated by gates. `dispatch` deliberately contains `eveSend` and `finalAudit`; detail() removes
+ * those nested spans so the published buckets are mutually exclusive rather than double-counted.
+ */
+export function createNotionWebhookTiming(now = () => performance.now()) {
+    const startedAt = now();
+    const elapsed = new Map();
+    let failedPhase;
+    const add = (phase, start) => {
+        elapsed.set(phase, (elapsed.get(phase) ?? 0) + duration(start, now()));
+    };
+    return {
+        async measure(phase, operation) {
+            const start = now();
+            try {
+                return await operation();
+            }
+            catch (err) {
+                failedPhase ??= phase;
+                throw err;
+            }
+            finally {
+                add(phase, start);
+            }
+        },
+        measureSync(phase, operation) {
+            const start = now();
+            try {
+                return operation();
+            }
+            catch (err) {
+                failedPhase ??= phase;
+                throw err;
+            }
+            finally {
+                add(phase, start);
+            }
+        },
+        detail(outcome) {
+            const eveSendMs = elapsed.get("eveSend");
+            const finalAuditMs = elapsed.get("finalAudit");
+            const dispatchMs = elapsed.get("dispatch");
+            return {
+                outcome,
+                ...(failedPhase ? { failedPhase } : {}),
+                ...(elapsed.has("credential") ? { hmacCredentialMs: millis(elapsed.get("credential")) } : {}),
+                ...(elapsed.has("botTriggerPage") ? { botTriggerPageMs: millis(elapsed.get("botTriggerPage")) } : {}),
+                ...(elapsed.has("ancestorSiblingTrust") ? { ancestorSiblingTrustMs: millis(elapsed.get("ancestorSiblingTrust")) } : {}),
+                ...(elapsed.has("engagementDedupe") ? { engagementStoreDedupeMs: millis(elapsed.get("engagementDedupe")) } : {}),
+                ...(dispatchMs === undefined
+                    ? {}
+                    : { dispatchPreflightCatchUpMs: millis(Math.max(0, dispatchMs - (eveSendMs ?? 0) - (finalAuditMs ?? 0))) }),
+                ...(eveSendMs === undefined ? {} : { eveSendMs: millis(eveSendMs) }),
+                ...(finalAuditMs === undefined ? {} : { finalAuditMs: millis(finalAuditMs) }),
+                totalMs: millis(duration(startedAt, now())),
+            };
+        },
+    };
+}
+//# sourceMappingURL=notion-webhook-timing.js.map

package/dist/agent/channels/notion-webhook-timing.js.map

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

package/dist/agent/channels/notion-webhook-verifier.d.ts

@@ -0,0 +1,5 @@
+import type { WebhookVerifier } from "@open-everywhere/core/agent/adapter-api.js";
+/** The registry key — what a generic hook declares as its `source` to be verified as Notion. */
+export declare const NOTION_WEBHOOK_SOURCE = "notion";
+export declare const notionWebhookVerifier: WebhookVerifier;
+//# sourceMappingURL=notion-webhook-verifier.d.ts.map

package/dist/agent/channels/notion-webhook-verifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notion-webhook-verifier.d.ts","sourceRoot":"","sources":["../../../agent/channels/notion-webhook-verifier.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4CAA4C,CAAC;AAElF,gGAAgG;AAChG,eAAO,MAAM,qBAAqB,WAAW,CAAC;AAI9C,eAAO,MAAM,qBAAqB,EAAE,eAyBnC,CAAC"}

package/dist/agent/channels/notion-webhook-verifier.js

@@ -0,0 +1,53 @@
+// Notion's webhook signature scheme, as a registry entry (OPE-164) — what lets a GENERIC hook
+// (`POST /webhooks/<id>`) declare `source: "notion"` and be verified the way Notion signs.
+//
+// ZERO NEW CRYPTO. The digest is this bundle's own `verifyNotionSignature` (channels/notion-api.ts),
+// the same function the native notion webhook route uses — one implementation of Notion's scheme in
+// the tree, not two.
+//
+// THE SCHEME (https://developers.notion.com/reference/webhooks):
+//   X-Notion-Signature: sha256=<hex>   HMAC-SHA256 of the RAW body, keyed by the ONE-TIME
+//   `verification_token` Notion hands over during subscription setup.
+// Notion, verbatim, on why the raw bytes matter: *"Pass the raw request body exactly as it arrived
+// (re-serialized JSON produces different bytes and fails verification)"*.
+//
+// 🔴 `signedTimestamp: false` — nothing in the signature binds freshness. Notion's payloads carry a
+// timestamp FIELD, but it is not covered in a way that bounds replay, so replay against a notion
+// hook is undefended and is declared as such on the reviewed allowlist.
+//
+// ROTATION: Notion documents no overlap window — *"If you ever rotate or recreate your webhook
+// subscription, be sure to update your stored verification_token"* — so the `keys[]` list is how an
+// operator gets one on our side (new token at index 0, outgoing at index 1 until the switch).
+import { verifyNotionSignature } from "./notion-api.js";
+/** The registry key — what a generic hook declares as its `source` to be verified as Notion. */
+export const NOTION_WEBHOOK_SOURCE = "notion";
+const NOTION_SIGNATURE_HEADER = "x-notion-signature";
+export const notionWebhookVerifier = {
+    source: NOTION_WEBHOOK_SOURCE,
+    provider: "notion",
+    keyKind: "shared-secret",
+    // 🔴 `keyOrigin: "vendor-issued"` (OPE-186) — the key is the `verification_token` NOTION mints and
+    // posts to us once during subscription setup. We cannot choose it, so a secret WE minted can never
+    // verify a Notion delivery. This is what keeps `notion` OUT of the chat-mintable source vocabulary
+    // (`webhooks/source-vocabulary.ts` → `acceptsMintedSecret`). 🔴 THAT CONDITIONAL IS NO LONGER
+    // HYPOTHETICAL: OPE-189 added `notion-event-normalizer.ts`, so `notion` now has BOTH halves the
+    // vocabulary derivation looks for and `keyOrigin` is the ONLY thing excluding it. The exclusion is
+    // pinned live rather than asserted here — `scripts/webhook-source-vocabulary-live-test.ts` §6a
+    // fails any mintable source whose normalizer declares no `deliveryIdHeader`, and Notion's declares
+    // none (its delivery id is in the body). Flip this field and that test goes red. Only an
+    // OPERATOR-DECLARED hook (`loadWebhooks`, whose secret ref the operator points at the stored token)
+    // can use this verifier.
+    keyOrigin: "vendor-issued",
+    signedTimestamp: false,
+    verify({ rawBody, headers, keys }) {
+        const signature = headers.get(NOTION_SIGNATURE_HEADER);
+        if (!signature)
+            return { ok: false, failure: "missing-signature" };
+        for (const [i, key] of keys.entries()) {
+            if (verifyNotionSignature(key, rawBody, signature))
+                return { ok: true, keyIndex: i };
+        }
+        return { ok: false, failure: "signature-mismatch" };
+    },
+};
+//# sourceMappingURL=notion-webhook-verifier.js.map

package/dist/agent/channels/notion-webhook-verifier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"notion-webhook-verifier.js","sourceRoot":"","sources":["../../../agent/channels/notion-webhook-verifier.ts"],"names":[],"mappings":"AAAA,8FAA8F;AAC9F,2FAA2F;AAC3F,EAAE;AACF,qGAAqG;AACrG,oGAAoG;AACpG,qBAAqB;AACrB,EAAE;AACF,iEAAiE;AACjE,0FAA0F;AAC1F,sEAAsE;AACtE,mGAAmG;AACnG,0EAA0E;AAC1E,EAAE;AACF,oGAAoG;AACpG,iGAAiG;AACjG,wEAAwE;AACxE,EAAE;AACF,+FAA+F;AAC/F,oGAAoG;AACpG,8FAA8F;AAE9F,OAAO,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAGxD,gGAAgG;AAChG,MAAM,CAAC,MAAM,qBAAqB,GAAG,QAAQ,CAAC;AAE9C,MAAM,uBAAuB,GAAG,oBAAoB,CAAC;AAErD,MAAM,CAAC,MAAM,qBAAqB,GAAoB;IACpD,MAAM,EAAE,qBAAqB;IAC7B,QAAQ,EAAE,QAAQ;IAClB,OAAO,EAAE,eAAe;IACxB,mGAAmG;IACnG,mGAAmG;IACnG,mGAAmG;IACnG,8FAA8F;IAC9F,gGAAgG;IAChG,mGAAmG;IACnG,+FAA+F;IAC/F,mGAAmG;IACnG,yFAAyF;IACzF,oGAAoG;IACpG,yBAAyB;IACzB,SAAS,EAAE,eAAe;IAC1B,eAAe,EAAE,KAAK;IACtB,MAAM,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE;QAC/B,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,uBAAuB,CAAC,CAAC;QACvD,IAAI,CAAC,SAAS;YAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,mBAAmB,EAAE,CAAC;QACnE,KAAK,MAAM,CAAC,CAAC,EAAE,GAAG,CAAC,IAAI,IAAI,CAAC,OAAO,EAAE,EAAE,CAAC;YACtC,IAAI,qBAAqB,CAAC,GAAG,EAAE,OAAO,EAAE,SAAS,CAAC;gBAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC;QACvF,CAAC;QACD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,oBAAoB,EAAE,CAAC;IACtD,CAAC;CACF,CAAC"}

package/dist/agent/channels/notion-webhook.d.ts

@@ -0,0 +1,242 @@
+import { type FetchLike, type NotionComment, type NotionSigningKey, type NotionCallOpts, type ResolvedNotionCredential } from "./notion-api.js";
+import { type NotionTrustRoots } from "./notion-ancestry-trust.js";
+import { type NotionUntieredSupervisorDispatch } from "./notion-supervisor.js";
+import { type NotionEngagementDeps } from "./notion-engagement.js";
+import type { NotionWebhookTimingRecorder } from "./notion-webhook-timing.js";
+import type { NotionCommentDispatchGuard } from "./notion-ingress-drain.js";
+import { type AttachSessionForCancel, type Domain } from "@open-everywhere/core/agent/adapter-api.js";
+/** The per-TURN reply target the channel snapshots at `turn.started` (see notion.ts). */
+export interface NotionReplyTarget {
+    readonly discussionId: string;
+    readonly pageId?: string;
+    readonly workspaceId?: string;
+    /** The Notion integration THIS delivery verified under (OPE-467) — snapshotted with the rest of
+     *  the target so the terminal reply posts under the credential that fetched the comment. Absent
+     *  on a turn whose auth predates the stamp ⇒ the post falls back to the page's domain binding. */
+    readonly credentialId?: string;
+}
+/** The per-session state the channel stashes so `message.completed` can post the reply into
+ *  the SAME discussion thread (see notion.ts's context factory). */
+export interface NotionSessionState {
+    readonly discussionId: string | null;
+    readonly pageId: string | null;
+    readonly workspaceId: string | null;
+    /**
+     * The PER-TURN reply target, snapshotted at `turn.started` from the delivery's auth
+     * attributes — NOT the seeded fields above. eve applies a `send({ state })` seed only when
+     * it CREATES a session; a resumed (standing supervisor) session keeps its original state, so
+     * the seeded `discussionId` goes stale after the first wake and every later reply would land
+     * in the FIRST discussion. eve rewrites `session.auth.current` from the delivery's auth on
+     * every delivery, so the auth attributes ARE this turn's real trigger — the same snapshot
+     * pattern slack.ts's supervisor turn.started uses (T1.4). Mutable by design (assigned per
+     * turn); `undefined` = no resolvable target, and message.completed FAILS SAFE (posts nothing).
+     */
+    oeReplyTarget?: NotionReplyTarget;
+    /**
+     * True iff this session was CREATED as a UNIFIED (org, domain) supervisor session
+     * (notion-supervisor.ts seeds it; eve applies the seed at creation only, and a session's grain
+     * is fixed for its lifetime — the token shape can't change mid-generation). notion.ts's
+     * message.completed keys the message-tool-only silence gate on it — Notion has a WORKING
+     * `reply` tool on supervisor turns, so a unified turn's terminal prose is DROPPED (never
+     * posted) and a stray leak is audited. Absent/false on every per-doc session ⇒ the gate never
+     * fires ⇒ byte-identical flag-off behaviour.
+     */
+    readonly oeUnified?: boolean;
+}
+export interface HandleNotionDeliveryDeps {
+    /**
+     * EVERY configured Notion integration's inbound signing key, org default first
+     * (channels/notion-credentials.ts notionIntegrations). The gate tries each in turn and the one
+     * that verifies IDENTIFIES the sending integration — see gateNotionDeliveryAcross. A single-
+     * integration deployment passes a one-entry list and behaves exactly as it did before OPE-467.
+     */
+    readonly signingKeys: readonly NotionSigningKey[];
+    /** The `webhooks.allowUnverifiedNotion` setting — dev escape hatch only. */
+    readonly allowUnverified: boolean;
+    /** Resolve one Notion channel credential to its integration token AND that credential's endpoint
+     *  rules (resolveNotionCredential). Called with the credential id the VERIFYING integration named
+     *  (else {@link credentialForPage}), so a delivery's REST calls run under the integration that
+     *  actually sent it. Undefined ⇒ unconfigured, and the delivery is acked without a dispatch (never
+     *  a retry storm over a config bug).
+     *
+     *  🔴 The PAIR, never the bare key (OPE-505). Every REST call in this file spreads the result, so
+     *  the credential's endpoint fence rides along; handing on only the token would return an unfenced
+     *  fetch and silently disable the check on the whole webhook two-step. */
+    readonly credentialFor: (credentialId: string) => Promise<ResolvedNotionCredential | undefined>;
+    /** The credential the PAGE'S DOMAIN binds, or undefined when it binds none — see
+     *  channels/notion-credentials.ts. It decides the credential for READS and REPLIES the agent
+     *  initiates. On an INBOUND delivery it is only the fallback: the HMAC has already proven which
+     *  integration sent this body, and a page id read off an unauthenticated payload never overrides
+     *  a proof (step 5). */
+    readonly credentialForPage: (workspaceId: string | undefined, pageId: string | undefined) => string | undefined;
+    /**
+     * The domain registry, passed as DATA rather than as a resolved verdict (OPE-502).
+     *
+     * 🔴 THE FENCE ITSELF STAYS INSIDE THIS CORE ON PURPOSE. Step 8b's decision is a security
+     * boundary, so it must not be a closure a caller supplies — a caller that passed a permissive one,
+     * or forgot the field, would reopen the whole vector with nothing to notice it. `domains` is inert
+     * config, so the only thing a caller can get wrong is passing an EMPTY list, and an empty list
+     * fences nothing because it owns nothing. Required, never optional, for the same reason.
+     *
+     * The route hands it `getConfig().loadDomains()`, fail-soft to `[]` — the same value it already
+     * closes over for {@link credentialForPage} and {@link ambientEnabled}.
+     */
+    readonly domains: readonly Domain[];
+    /**
+     * The operator's declared Notion TRUST ROOTS, prepared (OPE-492) — the route passes
+     * `notionTrustRoots()`, the register core's `subtree: true` trust entries fill at boot (OPE-539).
+     *
+     * OPTIONAL, and that is safe where {@link HandleNotionDeliveryDeps.domains} is not: a missing
+     * roots list can only ever LOSE a promotion. Absent (or empty) ⇒ every page resolves `no-roots`,
+     * with no API call and no probe, and the delivery keeps the fail-closed `external` binding it had
+     * before this seam existed. `domains` is required for the opposite reason — a missing one would
+     * weaken a fence.
+     */
+    readonly trustRoots?: NotionTrustRoots;
+    /** Resolve the bot's own Notion user id FOR ONE INTEGRATION (cached per credential; env override
+     *  or GET /v1/users/me). An unresolved id makes classifyNotionComment fail CLOSED (drop, never
+     *  wake) — the loop guard. 🔴 It is per-integration on purpose: each Notion integration has its
+     *  OWN bot user id, so one cached id shared across integrations would compare a reply against the
+     *  wrong identity and break the loop guard in both directions.
+     *  🔴 THE CORE CALLS IT ONCE PER CONFIGURED INTEGRATION, not once per delivery (OPE-1921): step 7
+     *  walks {@link signingKeys} to build the deployment's whole own-id set. There is deliberately no
+     *  separate "all the ids" dep — the set is DERIVED here from a required one, so no caller can
+     *  omit it and silently reopen the sibling loop, exactly as {@link domains} is required. */
+    readonly resolveBotUserId: (credentialId: string) => Promise<string | undefined>;
+    /** Resolve the bot's own display name for one integration (Step 4) — a judge input (the
+     *  channel-watch preamble's "names you"), never a bypass. Optional so the core works before name
+     *  capture is wired. */
+    readonly resolveBotName?: (credentialId: string) => Promise<string | undefined>;
+    /** Is the ambient supervisor enabled for this doc's surfaceKey? Fail-closed OFF (per-domain
+     *  opt-in, ambientSupervisorEnabled). The WHOLE ambient path is gated behind this. */
+    readonly ambientEnabled: (surfaceKey: string) => boolean;
+    /** Resolve the doc's engagement calibration tier (memory/domain.ts engagementTierFor) for the
+     *  judged preamble. Optional + fail-soft: absent/throwing ⇒ neutral (byte-identical). */
+    readonly engagementTier?: (surfaceKey: string) => "aggressive" | "neutral" | "reserved";
+    /** The §2.5 engagement seam's store seams (OPE-1501) — see channels/notion-engagement.ts.
+     *  Optional: absent ⇒ the live operational store. Injected so a test drives an engaged or a
+     *  stood-down page without one. */
+    readonly engagement?: NotionEngagementDeps;
+    /** Durable comment-level dispatch lease used only by the authenticated inbox processor. The
+     * synchronous development path keeps the legacy event_dedupe guard. */
+    readonly dispatchGuard?: NotionCommentDispatchGuard;
+    /** Injectable fetch (tests pass a mock; prod omits → global fetch). */
+    readonly fetch?: FetchLike;
+    readonly version?: string;
+    /** OVERLAY on the 429 policy every REST call of this delivery takes (OPE-1254). Live code passes
+     *  none and gets {@link NOTION_INGRESS_RETRY} whole — the policy sized against the ingress
+     *  function's 300 s ceiling. A test passes `{ sleep }` alone, which keeps the shipped numbers and
+     *  only makes the waits instant. */
+    readonly retry?: NotionCallOpts["retry"];
+    /** Request-scoped, content-free latency attribution. Absent keeps non-route callers unchanged. */
+    readonly timing?: NotionWebhookTimingRecorder;
+    /** Route the classified comment to the standing doc supervisor (notion-supervisor.ts). The
+     *  dispatch it receives is UNTIERED (OPE-596): this core holds no binding context, so the route
+     *  leg resolves each author's tier before the supervisor core renders anything. */
+    readonly dispatch: (d: NotionUntieredSupervisorDispatch) => Promise<void>;
+    /** Called with the one-time verification token on the handshake POST (channel logs it). */
+    readonly onHandshakeToken?: (token: string) => void;
+    /** eve's cancel door, channel-agnostic (the route's own `args.attachSession`) — what the STOP LEG
+     *  (OPE-989, step 8d below) calls through {@link routeNotionStopComment}. */
+    readonly attachSession: AttachSessionForCancel;
+}
+export interface NotionDeliveryOutcome {
+    readonly status: number;
+    readonly body: string;
+    readonly action: "handshake" | "rejected" | "bad-json" | "ignored" | "ambient-disabled" | "skipped-self" | "skipped-bot" | "dropped" | "dispatched" | "no-api-key" | "unresolved-page"
+    /** A bare `stop` comment from a genuine, distinct human (OPE-989) — the turn on this page was
+     *  handed to `cancelAnchoredTurn`. `detail` carries the cancel outcome, never a refusal reason. */
+     | "stopped"
+    /** A plain comment on a page `stand_down` marked (OPE-1501) — suppressed by the §2.5 engagement
+     *  registry, whatever the ambient opt-in says. `detail` carries the engagement anchor. Naming
+     *  the agent again clears the flag, so this is never the outcome of an addressed comment. */
+     | "stood-down"
+    /** The signer does not serve the domain that owns this delivery's page (OPE-502, step 8b). */
+     | "scope-refused"
+    /** This comment id already woke a turn inside the dedupe window (OPE-1906, step 12) — a vendor
+     *  retry, or a page two subscriptions both deliver. `detail` carries the comment id. Acked 200:
+     *  the delivery was handled the first time, so Notion has nothing to retry. */
+     | "duplicate-delivery" | "error";
+    readonly detail?: string;
+    /**
+     * 🔴 A REAL `x-notion-signature` WAS CHECKED AGAINST A CONFIGURED SECRET (OPE-189).
+     *
+     * NOT the same as "the gate let it through". `gateNotionDelivery` also returns "accepted" when no
+     * secret is set AND `webhooks.allowUnverifiedNotion` is on — a local-dev hatch whose only proof is
+     * possession of the URL. This flag is false in that case, and the route uses it to decide whether
+     * the delivery may enter the ROUTING plane at all.
+     *
+     * Why the two consumers differ, deliberately: the ambient supervisor reads a comment and judges
+     * whether to reply, which is what the hatch exists to let you exercise on a laptop. `admitTrigger`
+     * fires member-authored, human-approved routines — so an unsigned acceptance must not reach it, or
+     * a dev hatch becomes a production capability the moment the env var is set on a real deployment.
+     * Same narrowing S0b applied to runtime hooks, for the same reason.
+     *
+     * False for the handshake (it arrives BEFORE any secret exists and is correctly unverified) and
+     * for every rejection.
+     */
+    readonly verified: boolean;
+    /**
+     * The Notion channel credential this delivery ran under (OPE-467) — the integration whose secret
+     * verified the signature, else (dev hatch only) the page's domain binding. Absent when the
+     * delivery never reached credential selection (handshake, rejection, bad json, ignored event).
+     * Reported so the route can audit WHICH integration served a page without a second resolution.
+     */
+    readonly credentialId?: string;
+    /**
+     * 🔴 THE INTEGRATION WHOSE SECRET VERIFIED THIS BODY (OPE-500) — the ONE authenticated identity a
+     * delivery carries, and a strict subset of {@link NotionDeliveryOutcome.credentialId}.
+     *
+     * NOT the same field. `credentialId` is "which integration SERVED this delivery", which falls back
+     * to the page binding and then to the first configured key on the dev-hatch arm — so it can name an
+     * integration that proved nothing. This one is set at exactly one place, from the HMAC verdict, and
+     * is absent whenever no secret verified (handshake, rejection, the unverified dev hatch).
+     *
+     * Present on EVERY arm past the gate, `ignored` included. The event plane needs it precisely on the
+     * arm the comment path drops: a `page.*` delivery never reaches credential selection, and
+     * `notionTriggerScopeVerdict` cannot fence a scope without knowing who signed for it.
+     */
+    readonly signerCredentialId?: string;
+}
+/**
+ * Run the whole inbound loop for one Notion webhook delivery. Returns the HTTP outcome the
+ * route should send AND the semantic action (for the audit row). Pure w.r.t. eve — every
+ * external effect is injected (fetch, resolveBotUserId, resolveBotName, ambientEnabled, dispatch,
+ * onHandshakeToken).
+ */
+export declare function handleNotionDelivery(rawBody: string, signatureHeader: string | null, deps: HandleNotionDeliveryDeps): Promise<NotionDeliveryOutcome>;
+/**
+ * Process a row that crossed {@link handleNotionDelivery}'s HMAC gate before it was committed to
+ * the durable ingress inbox. This is intentionally a separate entrypoint: the public route cannot
+ * pass an optional "already verified" flag, and the internal drain must supply the immutable signer
+ * identity from the row key. A deleted integration is not retargeted to another credential.
+ */
+export declare function handleAcceptedNotionDelivery(rawBody: string, signerCredentialId: string, deps: HandleNotionDeliveryDeps): Promise<NotionDeliveryOutcome>;
+/** {@link resolveDeliveryPage}'s answer. Exactly one field is set: `pageId` when the page is
+ *  established, `reason` when it is not. A `reason` is a REFUSAL — never a page id the caller may
+ *  substitute. */
+export interface ResolvedDeliveryPage {
+    readonly pageId?: string;
+    readonly reason?: string;
+}
+/**
+ * The page a delivery's comment REALLY lives on, established from the comment Notion returned under
+ * the verified credential (OPE-496). The webhook's step 8 explains why the payload's own `page_id`
+ * may not answer this; this function is the answer that replaces it.
+ *
+ * Two shapes, one credential:
+ *   • a PAGE-level comment carries `parent.page_id` — already the answer, and already authenticated
+ *     (the fetch that returned it ran under the integration whose secret verified the delivery);
+ *   • an INLINE comment carries `parent.block_id` instead, so the block's owning page is walked under
+ *     the SAME credential ({@link resolveBlockOwningPage}, bounded at BLOCK_PARENT_MAX_HOPS).
+ *
+ * Every other outcome is a refusal with a reason: no parent at all, a parent that is neither a page
+ * nor a block, or a block whose walk ends anywhere but a page (a database or workspace parent, an id
+ * the integration cannot see, or too many hops). The caller must treat a reason as "do nothing" —
+ * `resolveBlockOwningPage` already states the same rule for the read fence, and both callers keep it.
+ *
+ * Exported so the delivery test can drive each shape directly, with the mock fetch counting the
+ * block-walk calls.
+ */
+export declare function resolveDeliveryPage(comment: NotionComment, opts: NotionCallOpts): Promise<ResolvedDeliveryPage>;
+//# sourceMappingURL=notion-webhook.d.ts.map

package/dist/agent/channels/notion-webhook.d.ts.map

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