@open-everywhere/provider-notion 0.1.0

package/agent/channels/notion-webhook-timing.ts

@@ -0,0 +1,131 @@
+// 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";
+
+export type NotionWebhookTimingPhase =
+  | "credential"
+  | "botTriggerPage"
+  | "ancestorSiblingTrust"
+  | "engagementDedupe"
+  /** Inclusive dispatch span. The public detail subtracts the nested Eve and final-audit spans. */
+  | "dispatch"
+  | "eveSend"
+  | "finalAudit";
+
+export interface NotionWebhookTimingDetail {
+  readonly [key: string]: unknown;
+  readonly outcome: string;
+  readonly failedPhase?: NotionWebhookTimingPhase;
+  readonly hmacCredentialMs?: number;
+  readonly botTriggerPageMs?: number;
+  readonly ancestorSiblingTrustMs?: number;
+  readonly engagementStoreDedupeMs?: number;
+  readonly dispatchPreflightCatchUpMs?: number;
+  readonly eveSendMs?: number;
+  readonly finalAuditMs?: number;
+  readonly totalMs: number;
+}
+
+export interface NotionWebhookTimingRecorder {
+  readonly measure: <T>(phase: NotionWebhookTimingPhase, operation: () => Promise<T>) => Promise<T>;
+  readonly measureSync: <T>(phase: NotionWebhookTimingPhase, operation: () => T) => T;
+  readonly detail: (outcome: string) => NotionWebhookTimingDetail;
+}
+
+/**
+ * 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<T>(
+  timing: NotionWebhookTimingRecorder,
+  emit: (detail: NotionWebhookTimingDetail) => void,
+  operation: (finish: (outcome: string) => void) => Promise<T>,
+): Promise<T> {
+  let emitted = false;
+  const finish = (outcome: string): void => {
+    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: number, end: number): number {
+  const elapsed = end - start;
+  return Number.isFinite(elapsed) && elapsed > 0 ? elapsed : 0;
+}
+
+const millis = (elapsed: number): number => 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: () => number = () => performance.now()): NotionWebhookTimingRecorder {
+  const startedAt = now();
+  const elapsed = new Map<NotionWebhookTimingPhase, number>();
+  let failedPhase: NotionWebhookTimingPhase | undefined;
+  const add = (phase: NotionWebhookTimingPhase, start: number): void => {
+    elapsed.set(phase, (elapsed.get(phase) ?? 0) + duration(start, now()));
+  };
+
+  return {
+    async measure<T>(phase: NotionWebhookTimingPhase, operation: () => Promise<T>): Promise<T> {
+      const start = now();
+      try {
+        return await operation();
+      } catch (err) {
+        failedPhase ??= phase;
+        throw err;
+      } finally {
+        add(phase, start);
+      }
+    },
+    measureSync<T>(phase: NotionWebhookTimingPhase, operation: () => T): T {
+      const start = now();
+      try {
+        return operation();
+      } catch (err) {
+        failedPhase ??= phase;
+        throw err;
+      } finally {
+        add(phase, start);
+      }
+    },
+    detail(outcome: string): NotionWebhookTimingDetail {
+      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())),
+      };
+    },
+  };
+}

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

@@ -0,0 +1,55 @@
+// 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";
+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 const NOTION_WEBHOOK_SOURCE = "notion";
+
+const NOTION_SIGNATURE_HEADER = "x-notion-signature";
+
+export const notionWebhookVerifier: WebhookVerifier = {
+  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" };
+  },
+};