@open-everywhere/provider-notion 0.1.0

package/agent/channels/notion-event-normalizer.ts

@@ -0,0 +1,587 @@
+// Notion's `EventNormalizer` + `EventScopeGrant` (OPE-189) — the FIRST event-plane registration
+// contributed by a provider BUNDLE rather than by core. It became possible only at OPE-193, which
+// put `registerEventNormalizer`/`registerEventScopeGrant` on the adapter barrel; before that
+// `boundary-test.ts` rule 4 hard-failed the deep import, which is the whole reason the tree's only
+// other normalizer (`routines/github-normalizer.ts`) lives in core.
+//
+// The ingress it feeds ALREADY EXISTS and is already verified: `POST /eve/v1/notion` (channels/
+// notion.ts) HMACs every delivery against the subscription's `verification_token`. This module is
+// what turns that verified delivery into something the routing plane can match a routine against.
+//
+// ════════════════════════════════════════════════════════════════════════════════════════════════
+// 🔴 THE PARTITION: COMMENTS ARE CONVERSATION, STRUCTURAL CHANGES ARE WORK.
+// ════════════════════════════════════════════════════════════════════════════════════════════════
+//
+// One Notion delivery now reaches TWO consumers on the same route — the ambient comment supervisor
+// and `admitTrigger`. They are DISJOINT BY EVENT TYPE, not duplicative, and that is a decision
+// rather than a consequence of wiring order:
+//
+//   • `comment.created` / `comment.updated` / `comment.deleted` are a CONVERSATION the agent is a
+//     participant in. That is the ambient supervisor's job, it already works, and a routine firing
+//     on the same comment would be a second, dumber reader of a thread the supervisor is reading
+//     properly. {@link notionEventNormalizer.normalize} returns **null** for the whole `comment.*`
+//     family, so a comment delivery never reaches the matcher and can never fire a routine.
+//
+//   • `page.*` / `database.*` / `data_source.*` are WORK — a page created, properties updated, a
+//     schema changed, something moved or deleted. Those are what routines subscribe to. The
+//     supervisor never sees them: `handleNotionDelivery` (channels/notion-webhook.ts) returns
+//     `ignored` for every type that is not `comment.created`, so a structural delivery cannot
+//     double-drive it.
+//
+// The two halves are enforced in two INDEPENDENT places, each one-sided, so neither can silently
+// widen into the other's territory. The rule is stated here because this is the module that owns
+// the vocabulary; the supervisor's half is a shipped `notionEventType(ev) !== "comment.created"`
+// check that predates it.
+//
+// UNRECOGNISED FAMILIES ARE NOT ROUTED. `file_upload.*` — and anything Notion adds after this was
+// written — normalizes to null. That is the fail-closed direction: a new family silently not firing
+// is a missing feature, while a new family silently firing is an unreviewed subscription surface.
+// The vocabulary below is therefore a REVIEWED ALLOWLIST, the same posture as the verifier registry.
+//
+// ════════════════════════════════════════════════════════════════════════════════════════════════
+// 🔴 THE SCOPE PATH IS PAYLOAD-DERIVED, AND THE PAYLOAD IS NOT AUTHENTICATED (OPE-500)
+// ════════════════════════════════════════════════════════════════════════════════════════════════
+//
+// The rule is NOT "hook-constant, never payload-derived". It is:
+//
+//   Scope may be derived from the payload ONLY to the extent the VERIFIER makes the sender
+//   authoritative over that namespace.
+//
+// 🔴 THE HMAC PROVES ONE FACT, AND IT IS NOT THAT ONE. A Notion delivery's signature proves WHICH
+// SUBSCRIPTION'S `verification_token` signed these bytes. It does not prove that Notion composed
+// them. This file used to claim the opposite — "Notion is authoritative about which workspace /
+// teamspace / database / page an event came from" — and that claim is FALSE on the deployment shape
+// OPE-467 introduced: per-domain subscription tokens are DISTRIBUTED by design, so one operator per
+// domain holds their own domain's token. That holder can sign a body whose `workspace_id`,
+// `data.parent.id` and `entity.id` name ANY namespace they choose. {@link notionScopePath} then
+// emits those choices as the trigger plane's scope path.
+//
+// SO THE PATH BELOW IS A CLAIM, NOT A PROOF, AND TWO GATES STAND BETWEEN THE CLAIM AND A FIRE:
+//
+//   1. THE INGRESS FENCE — {@link notionTriggerScopeVerdict}, run by `channels/notion.ts` BEFORE
+//      `admitTrigger` sees the delivery. It refuses any delivery whose granting step belongs to a
+//      domain the SIGNING integration does not serve. Read that function for what it can and cannot
+//      separate; the short form is that it fences a domain iff that domain runs its own inbound
+//      secret.
+//   2. THE READ GRANT — {@link notionEventScopeGrant}, which still requires the routine's own domain
+//      to own the affected surface. It was never a defence against a forged path, because a forged
+//      path names the VICTIM domain's surface and therefore satisfies the victim's own grant.
+//
+// A cross-check against Notion's REST API was considered and NOT taken (OPE-500). Retrieving
+// `entity.id` under the verifying credential proves the integration can SEE that object, which is a
+// weaker statement than the fence makes, and it leaves the `workspace_id` step unchecked: Notion's
+// REST surface returns no workspace id on any object, so no fetch can confirm the tenant. The fence
+// needs no fetch and closes the tenant route too, because a forged tenant only moves the granting
+// step onto a different domain and the fence then reads that domain's credential.
+//
+//   tenant    — `workspace_id`. Present on every delivery.
+//   group     — `data.parent.id` when `data.parent.type === "space"` (a TEAMSPACE).
+//   container — `data.parent.id` when the parent is a `database` / `data_source` / `page` / `block`.
+//   entity    — `entity.id` when the entity is a `page` / `database` / `data_source`.
+//   sub       — the ONE changed block, when `data.updated_blocks` names exactly one.
+//
+// 🔴 MEASURED CORRECTION TO THE TICKET'S PREMISE. OPE-189 expected this to be the first delivery
+// that exercises all FIVE `ScopeKind` levels at once. It cannot be, and no Notion delivery can:
+// `event-model.ts`'s five kinds were sized against Notion's PRODUCT hierarchy (workspace →
+// teamspace → database → page → block), but Notion's WEBHOOK ENVELOPE carries exactly ONE parent
+// object. `data.parent` is either the teamspace or the database/page — never both — so `group` and
+// `container` are mutually exclusive on any single delivery and the deepest real path is FOUR
+// steps. All five kinds ARE reachable across the vocabulary (a teamspace-parented page proves
+// tenant→group→entity→sub; a database-parented page proves tenant→container→entity→sub), which is
+// why all five are declared in `scopeKinds`. Emitting a fabricated fifth step to hit the number
+// would be inventing containment the delivery does not prove.
+//
+// A shorter path makes matching COARSER, never wrongly narrower (`event-model.ts:18-21`), so every
+// omission above is safe by construction.
+//
+// ════════════════════════════════════════════════════════════════════════════════════════════════
+// THE DELIVERY ID IS IN THE BODY, NOT A HEADER
+// ════════════════════════════════════════════════════════════════════════════════════════════════
+//
+// {@link EventNormalizer.deliveryIdHeader} is deliberately ABSENT: Notion sends no delivery-id
+// header at all — the event's unique id is the payload's top-level `id`. `declaredDeliveryId` (the
+// header mechanism) therefore cannot serve this source, and {@link notionEventDeliveryId} is the
+// supported way for the ingress to obtain one. It lives in this module for the same structural
+// reason `deliveryIdHeader` does: the delivery ENVELOPE is a fact about the vendor's contract, and
+// the normalizer is the one module that owns it.
+//
+// ⚠️ ONE SIDE EFFECT OF EXISTING AT ALL. `webhooks/source-vocabulary.ts` derives the CHAT-MINTABLE
+// source set from "has a verifier AND has a normalizer", so this module supplies the half `notion`
+// was missing. `notion` stays UNMINTABLE anyway — its verifier declares
+// `keyOrigin: "vendor-issued"`, so `acceptsMintedSecret` is false and a runtime hook on this source
+// would 401 forever. That is now the ONLY thing excluding it, and it is pinned by a live test
+// rather than by this comment: `scripts/webhook-source-vocabulary-live-test.ts` §6a refuses any
+// mintable source whose normalizer declares no `deliveryIdHeader`, and this one declares none.
+
+import {
+  scopeIdOf,
+  getConfig,
+  type Domain,
+  type EventNormalizer,
+  type EventScopeGrant,
+  type NormalizedEvent,
+  type ScopeStep,
+  type TriggerDelivery,
+} from "@open-everywhere/core/agent/adapter-api.js";
+import { NOTION_WEBHOOK_SOURCE } from "./notion-webhook-verifier.js";
+import { notionWorkspaceKey } from "./notion-identity.js";
+import { notionIntegrations, notionSignerServesDomain } from "./notion-credentials.js";
+
+/**
+ * The registry key for BOTH halves of the event plane, and it is the SAME string the webhook
+ * verifier registers under — one contract, spelled once. (Since OPE-198 S2 this key is the
+ * delivery's SCHEME; on the native Notion route the scheme and the hook name coincide.)
+ */
+export const NOTION_EVENT_SOURCE = NOTION_WEBHOOK_SOURCE;
+
+/** Event-type families that are WORK — routed into the event plane. Prefix-matched on the
+ *  verbatim `type` discriminator (`page.properties_updated`, `data_source.schema_updated`, …). */
+export const NOTION_STRUCTURAL_PREFIXES: readonly string[] = ["page.", "database.", "data_source."];
+
+/** Event-type families that are CONVERSATION — the ambient supervisor's, never a routine's.
+ *  Named explicitly (rather than falling into the unrecognised bucket) so the partition is a
+ *  reviewed statement in code and a reader can see that the omission is deliberate. */
+export const NOTION_CONVERSATIONAL_PREFIXES: readonly string[] = ["comment."];
+
+/** Notion's webhook envelope, probed defensively — a mis-shaped payload must yield `null`, never a
+ *  throw (a normalizer that throws is caught by `normalizeDelivery`, but an ingress should not rely
+ *  on that to avoid a 500). Mirrors `notion-api.ts`'s loose typing of the same envelope. */
+export interface NotionEventEnvelope {
+  readonly id?: unknown;
+  readonly timestamp?: unknown;
+  readonly workspace_id?: unknown;
+  readonly type?: unknown;
+  readonly event_type?: unknown;
+  readonly authors?: unknown;
+  readonly entity?: { readonly id?: unknown; readonly type?: unknown };
+  readonly data?: {
+    readonly parent?: { readonly id?: unknown; readonly type?: unknown };
+    readonly updated_blocks?: unknown;
+  };
+}
+
+function str(v: unknown): string | undefined {
+  return typeof v === "string" && v.length > 0 ? v : undefined;
+}
+
+function parse(body: string): NotionEventEnvelope | undefined {
+  try {
+    const p: unknown = JSON.parse(body);
+    return p && typeof p === "object" ? (p as NotionEventEnvelope) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** The verbatim event type, tolerating both spellings the REST surface uses (`notion-api.ts`'s
+ *  `notionEventType` does the same for the comment path; duplicated rather than imported because
+ *  that helper is typed against the comment-path envelope). */
+function eventTypeOf(ev: NotionEventEnvelope): string | undefined {
+  return str(ev.type) ?? str(ev.event_type);
+}
+
+/** Is this event type WORK (routable), CONVERSATION (the supervisor's), or unrecognised? Exported
+ *  so the disjointness can be asserted directly rather than inferred from `normalize` returning
+ *  null for two different reasons. */
+export function notionEventClass(type: string | undefined): "structural" | "conversational" | "unrecognised" {
+  if (!type) return "unrecognised";
+  if (NOTION_CONVERSATIONAL_PREFIXES.some((p) => type.startsWith(p))) return "conversational";
+  if (NOTION_STRUCTURAL_PREFIXES.some((p) => type.startsWith(p))) return "structural";
+  return "unrecognised";
+}
+
+/**
+ * The delivery id Notion carries for one event — its top-level `id`, which is in the BODY (Notion
+ * publishes no delivery-id header). THE supported way for the Notion ingress to populate
+ * {@link TriggerDelivery.deliveryId}, which is what arms `admitTrigger`'s durable replay dedupe.
+ * Returns undefined for an unparseable body and for a blank id alike — both are "this delivery has
+ * no id", which the plane already models as not-deduped rather than dropped.
+ */
+export function notionEventDeliveryId(rawBody: string): string | undefined {
+  return str(parse(rawBody)?.id);
+}
+
+/** The scope path one envelope proves. Exported for the unit test, which drives it directly. */
+export function notionScopePath(ev: NotionEventEnvelope): ScopeStep[] {
+  const scope: ScopeStep[] = [];
+  const workspace = str(ev.workspace_id);
+  if (workspace) scope.push({ kind: "tenant", id: workspace });
+
+  const parentId = str(ev.data?.parent?.id);
+  const parentType = str(ev.data?.parent?.type);
+  if (parentId && parentType) {
+    // `space` is Notion's word for a TEAMSPACE — the only level between a workspace and a
+    // database/page, and therefore the only thing `group` can ever mean here.
+    if (parentType === "space") scope.push({ kind: "group", id: parentId });
+    else if (parentType === "database" || parentType === "data_source" || parentType === "page" || parentType === "block") {
+      scope.push({ kind: "container", id: parentId });
+    }
+    // Any other parent type is left OUT rather than guessed into a kind — a shorter path is coarse,
+    // a wrong path is a mis-authorization.
+  }
+
+  const entityId = str(ev.entity?.id);
+  const entityType = str(ev.entity?.type);
+  if (entityId && (entityType === "page" || entityType === "database" || entityType === "data_source")) {
+    scope.push({ kind: "entity", id: entityId });
+  }
+
+  // `sub` ONLY when the delivery proves exactly ONE block. `page.content_updated` carries an ARRAY;
+  // picking the first of several would assert containment in a block the event is not (only) about,
+  // and the path holds at most one step per kind so there is no honest way to carry several.
+  const blocks = ev.data?.updated_blocks;
+  if (Array.isArray(blocks) && blocks.length === 1) {
+    const id = str((blocks[0] as { id?: unknown } | undefined)?.id);
+    if (id) scope.push({ kind: "sub", id });
+  }
+  return scope;
+}
+
+/** Lift one Notion envelope onto the v2 event model, or null when it is not ours to route.
+ *  Exported for the unit test, which drives it directly rather than through the registry. */
+export function liftNotionEvent(ev: NotionEventEnvelope, declaredSource: string): NormalizedEvent | null {
+  const type = eventTypeOf(ev);
+  if (notionEventClass(type) !== "structural") return null;
+  const eventType = type as string;
+
+  // `page.properties_updated` ⇒ event = the verbatim type, action = `properties_updated`. The
+  // vendor's name is carried VERBATIM (never re-spelled) and the verb is ADDITIONALLY split out,
+  // because "anything created, in any family" is a subscription people actually want and the filter
+  // language has no prefix operator to express it with.
+  const dot = eventType.indexOf(".");
+  const family = dot > 0 ? eventType.slice(0, dot) : eventType;
+  const action = dot > 0 ? eventType.slice(dot + 1) : undefined;
+
+  const scope = notionScopePath(ev);
+  const workspace = scopeIdOf(scope, "tenant");
+  const parent = scopeIdOf(scope, "container") ?? scopeIdOf(scope, "group");
+  const entity = scopeIdOf(scope, "entity");
+
+  const fields: Record<string, string> = { event: eventType, entity_type: family };
+  if (action) fields["action"] = action;
+  if (workspace) fields["workspace"] = workspace;
+  if (parent) fields["parent"] = parent;
+  if (entity) fields["entity"] = entity;
+
+  // TERMINAL, from Notion's OWN signal — never inferred from a failed fetch. `*.deleted` is the
+  // vendor's word for a trashed page/database; `*.undeleted` is its restore and is NOT terminal.
+  const gone = action === "deleted";
+
+  // SUMMARY IS BUILT FROM IDS AND THE EVENT TYPE ONLY. Notion's envelope also carries
+  // `workspace_name` (member-authored prose); it is deliberately never read, so this line contains
+  // no attacker-chosen characters even though it is emitted through `access/untrusted.ts`'s fence.
+  const summary = `notion ${eventType}${entity ? ` on ${entity}` : ""}${workspace ? ` (workspace ${workspace})` : ""}`;
+
+  // ACTOR: emitted only when the payload names exactly ONE author. `authors` is an ARRAY (a batched
+  // content update can carry several) and `actor` is a single slot, so picking the first of many
+  // would attribute the event to one of its authors as though they were the only one.
+  const authors: ReadonlyArray<{ id?: unknown }> = Array.isArray(ev.authors) ? (ev.authors as ReadonlyArray<{ id?: unknown }>) : [];
+  const soleAuthor = authors.length === 1 ? str(authors[0]?.id) : undefined;
+  const deliveryId = str(ev.id);
+  const occurredAt = str(ev.timestamp);
+
+  return {
+    source: declaredSource,
+    event: eventType,
+    ...(action ? { action } : {}),
+    scope,
+    ...(soleAuthor ? { actor: { id: soleAuthor } } : {}),
+    fields,
+    ...(deliveryId ? { deliveryId } : {}),
+    ...(occurredAt ? { occurredAt } : {}),
+    summary,
+    // POINTER: named for the day a Notion `EntityReadAdapter` exists. There is none today, so
+    // `hydratePointer` reports `unsupported` and the fire renders unhydrated — a documented no-op,
+    // not a claim that a re-fetch happens. `gone` short-circuits hydration entirely.
+    ...(entity ? { pointer: { platform: "notion", id: entity, ...(gone ? { gone: true } : {}) } } : {}),
+  };
+}
+
+export const notionEventNormalizer: EventNormalizer = {
+  source: NOTION_EVENT_SOURCE,
+  provider: "notion",
+  // `author` is DELIBERATELY NOT FILTERABLE even though the payload carries it. `authors` is an
+  // ARRAY, and the match language pins "an absent field makes every `in` FALSE and every `notIn`
+  // TRUE" — so on a multi-author event an `author notIn [bot]` clause would evaluate TRUE, i.e. the
+  // one motivating use of `notIn` (do not re-trigger on our own writes) would fail OPEN on exactly
+  // the deliveries where the bot co-authored. Shipping a filter key whose guard silently inverts is
+  // worse than not shipping it. `actor` still carries a sole author for rendering/audit.
+  matchKeys: ["event", "action", "entity_type", "workspace", "parent", "entity"],
+  // 🔴 `workspace` IS NOT A SCOPE KEY, on purpose. `scopeKeys` feeds the MANDATORY-NARROWING rule
+  // (event-match.ts): an `in` clause on one of these counts as "this subscription narrowed". If
+  // `workspace` were listed, `{ all: [{ key: "workspace", in: [ws] }] }` would satisfy the rule
+  // while subscribing to EVERY event in the entire workspace — precisely the default the rule
+  // exists to refuse. GitHub makes the same call (`scopeKeys: ["repo"]`, never the owner).
+  scopeKeys: ["parent", "entity"],
+  // All five, because all five are reachable across the vocabulary — but see the module header:
+  // no SINGLE delivery proves more than four, because Notion's envelope carries one parent.
+  scopeKinds: ["tenant", "group", "container", "entity", "sub"],
+  // Notion's `authors[]` genuinely identifies who caused the event (`{id, type: person|bot|agent}`),
+  // so the honest answer is yes — even though nothing reads this field today (OPE-192).
+  resolvesActor: true,
+  // ABSENT ON PURPOSE — Notion publishes no delivery-id header; see the module header and
+  // {@link notionEventDeliveryId}.
+  normalize(d: TriggerDelivery): NormalizedEvent | null {
+    const ev = parse(d.body);
+    if (!ev) return null; // an unparseable body is not routable; the ingress logs its own reason
+    return liftNotionEvent(ev, d.source);
+  },
+};
+
+/**
+ * ════════════════════════════════════════════════════════════════════════════════════════════════
+ * 🔴 NOTION'S READ GRANT — AND THE BOUNDARY IT IS *NOT*.
+ * ════════════════════════════════════════════════════════════════════════════════════════════════
+ *
+ * WHAT OE ACTUALLY HOLDS, MEASURED (a design note §1, §6; `notion-api.ts`
+ * `resolveNotionCredential`): an INTERNAL INTEGRATION SECRET (`db:notion:channel-key`, broker `db`) —
+ * one for the whole deployment by default, or one per domain that binds its own (OPE-467). Each is
+ * bearer-token-flat: there is no scopes string, it is bound to a single workspace at creation, and
+ * what it can see is a SHARE LIST maintained on NOTION'S side, page by page, by workspace members.
+ *
+ * 🔴 THEREFORE THE CREDENTIAL CANNOT BE THE BOUNDARY, AND THIS ADAPTER DOES NOT PRETEND IT IS.
+ * Three properties make that unavoidable, and each one alone would be enough:
+ *   1. A domain need not bind its own integration, and by default none does — ten domains then
+ *      reach Notion with the same bytes, so nothing credential-derived can differ between them.
+ *      A grant rule that held only for BOUND domains would be a rule with a config-shaped hole.
+ *   2. The share list is invisible to OE — it is not in any config we hold and there is no API that
+ *      would let a PURE, SYNC `grantsRead` consult it even if it were.
+ *   3. `EffectiveAccess` has no Notion-shaped granted resource to express it over (`repos` is a
+ *      hardcoded GitHub `string[]`), and inventing one for a credential nobody varies per domain
+ *      would be schema for a distinction that does not exist.
+ * A `grantsRead: () => true` with those facts in a comment is the failure class this tree has a
+ * name for — a documented absence of a boundary that LOOKS like a boundary — so it is not what
+ * ships here.
+ *
+ * WHAT *IS* A REAL, PER-DOMAIN, DEPLOYER-OWNED NOTION BOUNDARY: which domain a Notion surface
+ * belongs to. `domainsForSurface` reads the static `domains` registry in the app tree — deployer
+ * config, merged by PR, validated at module load, with a surface belonging to at most ONE domain.
+ * It is the SAME authority, over the SAME `notion/<workspace>/<page>` surface key, that already
+ * gates whether the ambient supervisor may engage on that page at all (`notion.ts`
+ * `notionAmbientEnabled`). So the rule is:
+ *
+ *   A routine may be triggered by a Notion event iff the routine's partition is in a domain the
+ *   deployer put the affected Notion surface in.
+ *
+ * It REFUSES things that are real: a routine in domain `payments` cannot subscribe to a page the
+ * deployer put in `security`; a page in NO domain cannot trigger anything anywhere; a delivery
+ * proving only a workspace is refused outright, because a workspace is not a surface anybody
+ * configured.
+ *
+ * INNERMOST-CONFIGURED-WINS, AND IT NEVER FALLS THROUGH A REFUSAL. The walk goes inwards→outwards
+ * and the FIRST step the registry knows about is authoritative: it grants or it refuses, and the
+ * walk stops. A step the registry says nothing about is skipped (deployers configure pages and
+ * databases, not every descendant), which is what makes the rule usable — but continuing PAST a
+ * refusal would let a parent-database grant authorize a child page the deployer deliberately put
+ * somewhere else, which is the widening this ordering exists to prevent.
+ *
+ * ⚠️ TWO ASSUMPTIONS, STATED BECAUSE THEY ARE THE ONES MOST LIKELY TO SHIFT.
+ *   • `loadDomains` is explicitly a swappable seam ("the seam a DB/dashboard would swap behind",
+ *     memory/config/domains.ts). This grant's authority class is TIED to that seam staying deployer-owned:
+ *     the day a dashboard lets a non-deployer edit domain membership, this rule silently weakens to
+ *     whatever authorizes that editor.
+ *   • Notion's own share list is a SECOND fence underneath this one, not a substitute for it: a
+ *     subscription only delivers events for objects the connection was shared onto, so a delivery
+ *     arriving at all already proves OE can see the object. That fact is OE-wide, never per-domain,
+ *     which is exactly why it cannot be the grant.
+ *
+ * ⚠️ IT READS CONFIG, WHICH GITHUB'S GRANT DOES NOT NEED TO. `grantsRead` is documented PURE — no
+ * I/O, no ctx, no fetch — and this stays inside that: `getConfig()` is a registry read and
+ * `domainsForSurface` reads static, module-load-validated config. It is the SAME read
+ * `requestForPartition` (event-authz.ts) already performs on this exact fire path, so it introduces
+ * no new authority class and no new I/O. An unregistered config throws, `checkEventReadGrant`
+ * catches it as `unresolvable`, and the delivery fails CLOSED.
+ */
+/**
+ * The scope steps that can DECIDE a Notion delivery, innermost first. The first step any domain owns
+ * is authoritative — it grants or it refuses, and the walk stops there.
+ *
+ * ⭐ ONE LIST, TWO READERS, ON PURPOSE. {@link notionEventScopeGrant} walks it to find the step that
+ * AUTHORIZES, and {@link notionTriggerScopeVerdict} walks it to find the step it must check the
+ * SIGNER against. If the two walked different orders, the fence would check one step and the grant
+ * would authorize another, which is the exact shape of a fence that looks applied and is not.
+ *
+ * 🔴 `tenant` IS DELIBERATELY ABSENT. The grant's own comment holds the standing reason; the fence
+ * inherits it, and inherits the consequence too — a forged `workspace_id` is never checked directly.
+ * It does not need to be. The tenant only changes WHICH domain a step below resolves to, and the
+ * fence then reads that domain's credential.
+ */
+export const NOTION_GRANT_STEPS = ["sub", "entity", "container", "group"] as const;
+
+export const notionEventScopeGrant: EventScopeGrant = {
+  source: NOTION_EVENT_SOURCE,
+  provider: "notion",
+  grantsRead(scope, access) {
+    const workspace = scopeIdOf(scope, "tenant");
+    if (workspace === undefined) return false;
+    const workspaceKey = notionWorkspaceKey(workspace);
+    const cfg = getConfig();
+    // INNERMOST-FIRST. `tenant` is deliberately absent from this list. The reason has been REWRITTEN
+    // (OPE-223, 2026-07-28) because OPE-205 falsified the original one, which read: "a workspace id
+    // is not a surface anybody configures, and admitting it would turn 'the deployer named this
+    // workspace once' into a grant over every page in it."
+    //
+    // Both halves of that are now out of date. A deployer CAN configure a workspace id — that is
+    // exactly what `containers: ["notion/<ws>"]` is — and a grant over every page in it is precisely
+    // what such a claim is FOR. Worse, the widening the old sentence feared has already happened by
+    // a route it never mentions: `domainsForSurface` composes `notion/<ws>/<stepId>` and
+    // `resolveDomainForChannel` falls back on that key's two-segment PREFIX, which for every step
+    // here IS `notion/<ws>`. So under a workspace claim EVERY step below resolves to the claiming
+    // domain, and the loop grants at the innermost proved step without `tenant` being admitted at
+    // all. (Pinned in notion-event-normalizer-test.ts §5b.)
+    //
+    // THE STANDING REASON, which none of that touches: admitting `tenant` would not extend the
+    // claim's reach by a single page — reach is already total — it would only change the verdict on
+    // a delivery that identifies NO surface, i.e. one whose subject is unknown. That is a change in
+    // what counts as PROOF, not in how far a grant reaches, and it is the one thing this walk should
+    // never concede: it would make Notion the only provider where "I cannot tell you what this is
+    // about" authorizes a wake, against GitHub's refusal of owner-only deliveries
+    // (github-normalizer.ts) and core's own `no-scope` arm, and it would convert a legible
+    // `grant_refused` audit row into a silent fire. So `tenant` stays out, on the narrower and more
+    // durable ground.
+    for (const kind of NOTION_GRANT_STEPS) {
+      const id = scopeIdOf(scope, kind);
+      if (id === undefined) continue;
+      const owning = cfg.domainsForSurface({ workspaceKey, surface: id });
+      if (owning.length === 0) continue; // the registry says nothing about this step — ask the next one out
+      return owning.some((d) => access.domains.includes(d));
+    }
+    return false; // no step of the proved path is a surface the deployer put in any domain
+  },
+};
+
+/**
+ * One id, safe to put in a log line. The fence's `reason` names the SCOPE STEP that refused, and a
+ * scope step id is a payload field the SENDER chose — the very thing this whole function exists
+ * because nothing authenticates. A raw newline in it would forge a second log line, so the value is
+ * bounded and stripped of every control character before it is quoted.
+ *
+ * Notion ids are UUIDs, so 64 characters is far more than a real one needs and is short enough that
+ * a padded id cannot push the rest of the line out of a truncated log.
+ */
+function quote(id: string | undefined): string {
+  if (id === undefined) return '"(none)"';
+  // The class is written in \u escapes on purpose: a raw control byte in a source file is its own
+  // defect class in this tree (`lint:invisible-bytes`).
+  return JSON.stringify(id.slice(0, 64).replace(/[\u0000-\u001f\u007f\u2028\u2029]/g, "?"));
+}
+
+/** {@link notionTriggerScopeVerdict}'s answer. `ok` is the ONLY field a caller may branch on; the
+ *  `reason` is operator-facing prose for the log line and carries no control flow. */
+export type NotionTriggerScopeVerdict =
+  | { readonly ok: true; readonly detail: string }
+  | { readonly ok: false; readonly reason: string };
+
+/**
+ * ════════════════════════════════════════════════════════════════════════════════════════════════
+ * 🔴 THE INGRESS FENCE (OPE-500) — MAY THIS SIGNER ROUTE A DELIVERY ABOUT THIS SCOPE?
+ * ════════════════════════════════════════════════════════════════════════════════════════════════
+ *
+ * `channels/notion.ts` calls this on every VERIFIED structural delivery, BEFORE `admitTrigger`. A
+ * refusal drops the delivery out of the trigger plane. It never affects the ambient comment path,
+ * which has its own OPE-496 resolution and never reaches this function.
+ *
+ * THE RULE, in one sentence:
+ *
+ *   A delivery may arm a routine on a scope only when the domain that owns that scope is a domain
+ *   the SIGNING integration serves.
+ *
+ * WHY THAT IS THE RIGHT AUTHORITY. The signing integration is the ONE authenticated fact a delivery
+ * carries (`gateNotionDeliveryAcross` — the secret that verifies identifies the sender). The scope
+ * path is not authenticated at all. `notion-credentials.ts` already establishes which integration a
+ * domain binds, and that binding is deployer config merged by PR. So this asks the payload's claim
+ * one question the payload cannot answer for itself, and answers it from config.
+ *
+ * WORKED THROUGH, because the point is what it REFUSES. Domain `payments` binds integration
+ * `notion-payments` with its own inbound secret. A holder of `notion-payments`'s `verification_token`
+ * signs a body naming a `security` page. The granting step resolves to `security`, whose credential
+ * is `notion-security` (or the org default). That is not the signer, and the two do not share an
+ * inbound secret, so the delivery routes nothing.
+ *
+ * 🔴 THE ONE THING IT CANNOT SEPARATE, STATED PLAINLY. Two integrations that share an INBOUND SECRET
+ * are indistinguishable to the HMAC gate — `connectorIntegrations` defaults a domain's
+ * `inboundSecret` to the deployment default, so a domain that binds a credential WITHOUT declaring
+ * its own inbound secret signs exactly like the org default. This function accepts that case rather
+ * than refusing it, because refusing would break a supported config in which the domain runs no
+ * subscription of its own. The honest statement of the property is therefore:
+ *
+ *   A domain is fenced from another domain's forged deliveries IFF it runs its own inbound secret.
+ *
+ * That is the same condition `notion-credentials.ts` already states for the read boundary, and the
+ * runbook already tells operators to satisfy it. It is not a hole this function opens; it is the
+ * limit of what the HMAC can tell one sender from another.
+ *
+ * FAIL CLOSED, AND THE REFUSALS ARE REAL. No signer (the dev hatch), an unparseable body, and a path
+ * no domain owns all refuse. The last one costs nothing: {@link notionEventScopeGrant} would refuse
+ * the same delivery a moment later, so dropping it here only makes the refusal legible.
+ *
+ * PURE. `resolveSurface` defaults to the same `getConfig().domainsForSurface` the grant reads, and is
+ * injectable so the test drives every arm with no registry.
+ */
+export function notionTriggerScopeVerdict(
+  rawBody: string,
+  signerCredentialId: string | undefined,
+  domains: readonly Domain[],
+  resolveSurface: (p: { workspaceKey: string; surface: string }) => readonly string[] = (p) => getConfig().domainsForSurface(p),
+): NotionTriggerScopeVerdict {
+  const ev = parse(rawBody);
+  if (!ev) return { ok: false, reason: "the delivery body did not parse" };
+
+  // NOT OURS TO JUDGE. A `comment.*` or unrecognised body normalizes to null, so it can never fire a
+  // routine — refusing it here would log a security refusal for every ordinary comment.
+  if (notionEventClass(eventTypeOf(ev)) !== "structural") return { ok: true, detail: "not a structural event" };
+
+  if (!signerCredentialId) return { ok: false, reason: "no integration's secret identified this delivery" };
+
+  const scope = notionScopePath(ev);
+  const workspace = scopeIdOf(scope, "tenant");
+  if (workspace === undefined) return { ok: false, reason: "the delivery names no workspace" };
+  const workspaceKey = notionWorkspaceKey(workspace);
+
+  // The inbound secret each integration signs with. Two entries sharing one name sign identically,
+  // which is what the "cannot separate" paragraph above is about. The comparison itself lives in
+  // `notion-credentials.ts` (notionSignerServesDomain) because the COMMENT plane's fence
+  // (notionDeliveryScopeVerdict, OPE-502) asks the identical question, and two implementations of
+  // "does this signer serve that domain?" is how one plane would come to answer it differently.
+  const integrations = notionIntegrations(domains);
+
+  for (const kind of NOTION_GRANT_STEPS) {
+    const id = scopeIdOf(scope, kind);
+    if (id === undefined) continue;
+    const owning = resolveSurface({ workspaceKey, surface: id });
+    if (owning.length === 0) continue; // the registry says nothing about this step — ask the next one out
+
+    // THE STEP THAT WILL AUTHORIZE. EVERY domain that owns it has to be one the signer serves.
+    // Exclusivity makes this list at most one entry, but the fence does not lean on that: `some`
+    // here would let a second owner carry a delivery the first owner's credential never signed for.
+    let viaSharedSecret = false;
+    for (const name of owning) {
+      const owner = domains.find((d) => d.name === name);
+      if (!owner) {
+        // The surface resolver named a domain the registry passed here does not hold. That is a
+        // config seam, and on a fence the only safe reading of "I cannot resolve this" is no.
+        return { ok: false, reason: `${kind} ${quote(id)} resolved to domain ${quote(name)}, which this registry does not hold` };
+      }
+      // The one thing the HMAC cannot separate: two integrations sharing one inbound secret sign
+      // identically. Accepted, and named in the detail so the log says which limit was hit.
+      const served = notionSignerServesDomain(owner, signerCredentialId, integrations);
+      if (served.served) {
+        if (served.via === "shared-secret") viaSharedSecret = true;
+        continue;
+      }
+      return {
+        ok: false,
+        reason:
+          `${kind} ${quote(id)} belongs to domain ${quote(name)}, which is served by notion credential ${quote(served.expected)} — ` +
+          `this delivery was signed by ${quote(signerCredentialId)}. A signed body cannot arm another domain's routines.`,
+      };
+    }
+    return {
+      ok: true,
+      detail: viaSharedSecret
+        ? `${kind} ${quote(id)} is served by an integration that shares this deployment's inbound secret`
+        : `${kind} ${quote(id)} is served by ${quote(signerCredentialId)}`,
+    };
+  }
+  return { ok: false, reason: "no step of the claimed path is a surface the deployer put in any domain" };
+}