@open-everywhere/provider-notion 0.1.0

package/agent/channels/notion-credentials.ts

@@ -0,0 +1,417 @@
+// WHICH NOTION INTEGRATION SERVES THIS PAGE (OPE-467) — the one place the Notion bundle decides
+// which credential a call runs under, and which integrations may sign an inbound delivery.
+//
+// THE PROBLEM. Notion the vendor supports MANY internal integrations, and each one only sees the
+// page trees a human explicitly shared with it. That is a real, vendor-enforced boundary — the
+// strongest isolation any of OE's six surfaces can buy. Until this module OE wired ONE integration
+// for every domain, so the boundary was app-layer only: `notion-scope.ts` fenced the domain, and
+// the credential underneath could see every page in the workspace. `notion-scope.ts` still says so
+// in its own header, and it stays true for a domain on the org default.
+//
+// THE RULE FOR WORK THE AGENT INITIATES — a read tool, a proactive post: **the domain that owns the
+// page decides the credential.**
+//   • the page's domain declares a `credentials` override for notion `channel-key` ⇒ that credential;
+//   • it declares none (or the page is in no domain) ⇒ the org default `channel-key`.
+//
+// THE RULE FOR A DELIVERY, and for everything downstream of one: **the integration that VERIFIED it
+// serves it.** Each integration signs its deliveries with its OWN vendor-issued
+// `verification_token`, so a second integration's deliveries cannot verify against the first's
+// secret. {@link notionIntegrations} enumerates the configured integrations and the route tries each
+// one's secret in turn — the same "ordered keys, current first" shape `webhooks/secrets.ts` uses for
+// a rotation window — and THE SECRET THAT VERIFIES IDENTIFIES THE INTEGRATION THAT SENT THE
+// DELIVERY. That is the only authenticated fact a delivery carries.
+//
+// 🔴 THAT RULE REACHES THE READS TOO (OPE-499, ruled by Tommy 2026-08-13). A delivery-woken session's
+// READ TOOLS run under the SAME carried credential as its fetch and its reply — never a fresh lookup
+// off the page's domain binding. {@link notionCallerCredential} reads the `credential_id` auth
+// attribute the delivery stowed (notion-identity.ts buildNotionAuth) and prefers it when present. The
+// domain binding stays the rule for an AGENT-INITIATED session — a routine, a proactive post — where
+// no delivery ever ran and there is no carried credential to prefer.
+//
+// WHY THIS CLOSES A REAL GAP. An operator who shares one page with BOTH the org-default integration
+// and a domain's own integration lets either subscription's `verification_token` holder produce a
+// verified delivery for that page. Before this rule, the session that delivery woke still read under
+// the PAGE's domain binding — so a holder of the WEAKER (org) credential could ride a double-shared
+// page into every page the domain's OWN, narrower integration can see. Carrying the delivery's own
+// credential into the reads means a session only ever reads what the credential that actually
+// verified it was shared into — the vendor's own share-list boundary, working as designed.
+//
+// 🔴 WHY A BINDING DOES NOT OUTRANK THE HMAC. A delivery's page id is read off the payload, and
+// nothing authenticates the payload. If the page's binding decided, a forger holding integration
+// A's `verification_token` could name a domain-B page and have the delivery run under B's
+// credential. So what a binding actually buys on ingress is narrower than "this page is served by
+// this integration": **a binding routes the deliveries the bound subscription itself sent.** Both
+// rules meet at one credential id per delivery, and the REPLY carries that id forward (the auth
+// attributes stow it) — so the credential that fetched a comment is the credential that answers it,
+// on every path.
+//
+// A page shared with two integrations produces a delivery on EACH subscription. That is legitimate,
+// and each delivery correctly runs under its own verifying integration — which is why a disagreement
+// between the HMAC and the binding PREFERS the HMAC rather than refusing.
+//
+// 🔴 WHAT THIS DOES NOT BUY. Binding a domain to its own integration only fences the pages that
+// integration was SHARED into. If the operator leaves a payments page shared with the org-default
+// integration as well, that key can still read it — Notion enforces the share list, and OE cannot
+// widen or narrow it. The runbook says this plainly: bind the domain AND unshare the page from
+// every other integration.
+
+import {
+  domainCredentialId,
+  OperatorSecretNotSetError,
+  resolveDomainForChannel,
+  connectorIntegrations,
+  resolvePartition,
+  type BindableContext,
+  type Domain,
+  type ConnectorIntegration,
+} from "@open-everywhere/core/agent/adapter-api.js";
+import { notionSurfaceKey } from "./notion-identity.js";
+import { notionPageDomain } from "./notion-scope.js";
+
+/** The provider name in `agent/access/providers.ts`. */
+export const NOTION_PROVIDER = "notion";
+
+/** The ORG-DEFAULT channel-plumbing credential id — the role a domain override replaces. */
+export const NOTION_CHANNEL_CREDENTIAL = "channel-key";
+
+/** The operator-secret name holding the DEFAULT integration's inbound signing key (Notion's
+ *  subscription `verification_token`). A domain that runs its own subscription names its own with
+ *  `inboundSecret`. Resolved through the operator-secret resolver, so a value stored with
+ *  `oe secret set NOTION_WEBHOOK_SECRET` wins over an env var of the same name. */
+const NOTION_WEBHOOK_SECRET_NAME = "NOTION_WEBHOOK_SECRET";
+
+/**
+ * The notion `channel-key` credential id a page's domain binds, or **undefined when it binds none**.
+ *
+ * Undefined is a load-bearing answer, not a failure: it means "this page's domain asked for no
+ * override", which every caller reads as "use the org default". Keeping it distinct from a resolved
+ * id is what lets the webhook route fall through to its own arms (the verifying integration, then
+ * the org default) instead of treating "no binding" as a refusal.
+ *
+ * Pure — `domains` is injected, exactly like `notionPageDomain`'s, so the whole decision is
+ * unit-testable with no config and no store.
+ */
+export function notionChannelCredentialFor(
+  workspace: string | undefined,
+  pageId: string | undefined,
+  domains: readonly Domain[],
+): string | undefined {
+  if (!pageId) return undefined;
+  const domain = notionPageDomain(workspace, pageId, domains).domain;
+  if (!domain) return undefined;
+  const id = domainCredentialId(domain, NOTION_PROVIDER, NOTION_CHANNEL_CREDENTIAL);
+  return id === NOTION_CHANNEL_CREDENTIAL ? undefined : id;
+}
+
+/**
+ * {@link notionChannelCredentialFor} for a session's own surface key (`notion/<workspace>/<page>`) —
+ * the form `resolvePartition(ctx).surfaceKey` produces.
+ *
+ * The read tools resolve the CALLER'S surface, not the page argument. That is deliberate and it is
+ * not a weaker check: `notion-scope.ts` has already established that an admitted read is either the
+ * caller's own page or a page in the caller's own domain, so the two resolve to the same domain by
+ * construction — and the caller's surface is known BEFORE the fence runs, which the block-resolution
+ * walk needs (it must make a Notion call to find a block's owning page).
+ */
+export function notionChannelCredentialForSurface(surfaceKey: string, domains: readonly Domain[]): string | undefined {
+  const parts = surfaceKey.split("/");
+  if (parts.length !== 3 || parts[0] !== "notion") return undefined;
+  return notionChannelCredentialFor(parts[1] || undefined, parts[2] || undefined, domains);
+}
+
+/**
+ * The `credential_id` auth attribute a DELIVERY stowed on this session (notion-identity.ts
+ * buildNotionAuth), or undefined when there is none — a plain, LOCAL structural read of
+ * `ctx.session.auth`, the same shape notion-identity.ts's own `notionAuthOf`/`notionAttr` probes
+ * read (kept as a separate three-line copy rather than an import for the same reason theirs is not a
+ * barrel port: a mapper/credential decision reads its own platform's attributes itself). `current` is
+ * this turn's auth; `initiator` is the fallback for a context that only carries the session's
+ * original one.
+ */
+function notionDeliveryCredential(ctx: BindableContext): string | undefined {
+  const auth = ctx.session?.auth?.current ?? ctx.session?.auth?.initiator;
+  const v = auth?.attributes?.credential_id;
+  if (typeof v === "string" && v.length > 0) return v;
+  if (Array.isArray(v) && typeof v[0] === "string" && v[0].length > 0) return v[0];
+  return undefined;
+}
+
+/**
+ * The credential a READ TOOL runs under (OPE-499). **The delivery's own carried credential wins**
+ * when this session was woken by one — the same `credential_id` auth attribute the reply arm already
+ * reads (notion-post-arm.ts) — so a session only ever reads what the integration that verified its
+ * delivery was actually shared into, never a wider domain binding a double-shared page could reach.
+ *
+ * Falls back to the CALLING SESSION's own domain binding when no delivery credential rides the
+ * context — an agent-initiated session (a routine, a proactive post) never carried one, and that is
+ * the pre-OPE-499 rule, unchanged. Fail-soft throughout: a synthetic or identity-less ctx has no
+ * partition to read, so it resolves undefined and the caller falls back to the org default, exactly
+ * like an unbound domain. That is the correct direction here: the DOMAIN FENCE (notion-scope.ts) is
+ * what refuses an out-of-scope read, and it runs whether or not a credential was selected.
+ */
+export function notionCallerCredential(ctx: BindableContext, domains: readonly Domain[]): string | undefined {
+  const delivered = notionDeliveryCredential(ctx);
+  if (delivered) return delivered;
+  try {
+    return notionChannelCredentialForSurface(resolvePartition(ctx).surfaceKey, domains);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Every Notion integration this deployment is reachable by — the ORG DEFAULT FIRST, then one per
+ * domain that binds its own. The ingress tries each entry's inbound secret in this order.
+ */
+export function notionIntegrations(domains: readonly Domain[]): readonly ConnectorIntegration[] {
+  return connectorIntegrations(domains, NOTION_PROVIDER, NOTION_CHANNEL_CREDENTIAL, NOTION_WEBHOOK_SECRET_NAME);
+}
+
+/**
+ * Does the integration that SIGNED a delivery serve `owner`? The one comparison behind both signer
+ * fences — the trigger plane's {@link notionTriggerScopeVerdict} and the comment plane's
+ * {@link notionDeliveryScopeVerdict} — extracted so the two can never answer it differently.
+ *
+ * Three outcomes, because the caller's log line needs to tell them apart:
+ *   • `"credential"` — the signer IS the credential this domain binds. The ordinary yes.
+ *   • `"shared-secret"` — a different credential, signed with the SAME inbound secret. Accepted, and
+ *     named, because `connectorIntegrations` defaults a domain's `inboundSecret` to the deployment
+ *     default: a domain that binds a credential without declaring its own secret signs exactly like
+ *     the org default, and refusing would break a supported config in which the domain runs no
+ *     subscription of its own.
+ *   • `served: false` — neither, so the signer cannot speak for this domain.
+ *
+ * 🔴 THE PROPERTY THIS BUYS, STATED HONESTLY: **a domain is fenced from another domain's forged
+ * deliveries IFF it runs its own inbound secret.** That is not a hole either fence opens. It is the
+ * limit of what an HMAC can tell one sender from another when two senders hold the same key.
+ *
+ * `expected` rides on every outcome so a refusal can name the credential that WOULD have served.
+ */
+export type NotionSignerVerdict =
+  | { readonly served: true; readonly via: "credential" | "shared-secret"; readonly expected: string }
+  | { readonly served: false; readonly expected: string };
+
+export function notionSignerServesDomain(
+  owner: Domain,
+  signerCredentialId: string,
+  integrations: readonly ConnectorIntegration[],
+): NotionSignerVerdict {
+  const expected = domainCredentialId(owner, NOTION_PROVIDER, NOTION_CHANNEL_CREDENTIAL);
+  if (expected === signerCredentialId) return { served: true, via: "credential", expected };
+  const secretOf = (credentialId: string): string | undefined => integrations.find((i) => i.credentialId === credentialId)?.inboundSecret;
+  const signerSecret = secretOf(signerCredentialId);
+  if (signerSecret !== undefined && secretOf(expected) === signerSecret) return { served: true, via: "shared-secret", expected };
+  return { served: false, expected };
+}
+
+/**
+ * Every domain a COMMENT delivery reaches THROUGH ITS WORKSPACE CLAIM — the domains the payload's
+ * `workspace_id` can steer, and therefore the only ones {@link notionDeliveryScopeVerdict} fences.
+ *
+ * 🔴 TWO RESOLVERS ANSWER "WHICH DOMAIN?" DOWNSTREAM, AND THEY DO NOT ALWAYS AGREE. Both are
+ * consulted on the session the delivery opens, so a check on one alone would leave the other open:
+ *
+ *   • {@link notionPageDomain} — the credential binding (agent-initiated work) and the read fence
+ *     (notion-scope.ts). Its roster leg compares the PAGE-ID segment alone.
+ *   • `resolveDomainForChannel` — the ambient gate, the engagement tier, the supervisor grain and
+ *     the external-author policy, all keyed on the `notion/<workspace>/<page>` surface key. Its
+ *     roster leg compares the WHOLE key, so a workspace that does not match the `reach` entry
+ *     falls THROUGH to the claim leg.
+ *
+ * 🔴 WHY THE ROSTER LEGS ARE EXEMPT, AND THIS IS THE WHOLE DESIGN. A roster hit is not steerable by
+ * the payload's workspace:
+ *   • {@link notionPageDomain}'s roster leg ignores the workspace outright, and OPE-496 established
+ *     the page id from the comment Notion returned under the verified credential. Authenticated fact
+ *     in, config match out.
+ *   • `resolveDomainForChannel`'s roster leg needs the WHOLE key to appear in `reach`, so the
+ *     workspace it accepts is one the deployer typed themselves.
+ * A claim leg is the opposite: a container entry names a workspace, the payload names a workspace, and a
+ * match hands over every page under it.
+ *
+ * KEEPING THE ROSTER LEGS OUT IS LOAD-BEARING, not a shortcut. A page shared with two integrations
+ * produces a delivery on EACH subscription, and each one must run under its own verifying integration
+ * (the header's "prefer, don't refuse" rule, and the escalation OPE-499 closes by carrying the
+ * delivery's credential into the reads). Fencing a rostered page on the signer would refuse the
+ * second subscription's delivery outright and delete that behaviour.
+ *
+ * Pure — `domains` is injected, exactly like {@link notionPageDomain}'s.
+ */
+export function notionDeliveryClaimedDomains(
+  workspaceId: string | undefined,
+  pageId: string,
+  domains: readonly Domain[],
+): readonly Domain[] {
+  const out: Domain[] = [];
+  const add = (d: Domain | undefined): void => {
+    if (d && !out.some((seen) => seen.name === d.name)) out.push(d);
+  };
+  const page = notionPageDomain(workspaceId, pageId, domains);
+  if (page.via === "container") add(page.domain);
+  const channel = resolveDomainForChannel(notionSurfaceKey(workspaceId, pageId), domains);
+  if (channel.via.startsWith("container:")) add(channel.domain);
+  return out;
+}
+
+/** {@link notionDeliveryScopeVerdict}'s answer. `ok` is the ONLY field a caller may branch on; the
+ *  `reason` and the `detail` are operator-facing prose for the log line and carry no control flow. */
+export type NotionDeliveryScopeVerdict =
+  | { readonly ok: true; readonly detail: string }
+  | { readonly ok: false; readonly reason: string };
+
+/**
+ * ════════════════════════════════════════════════════════════════════════════════════════════════
+ * 🔴 THE COMMENT-PLANE INGRESS FENCE (OPE-502) — MAY THIS SIGNER OPEN A SESSION ON THIS PAGE?
+ * ════════════════════════════════════════════════════════════════════════════════════════════════
+ *
+ * `notion-webhook.ts` calls this after the page is established (OPE-496) and BEFORE the surface key
+ * decides anything. The rule is the trigger plane's rule, on the plane next door:
+ *
+ *   A delivery may open a session on a domain it reaches THROUGH ITS WORKSPACE CLAIM only when that
+ *   domain is one the SIGNING integration serves.
+ *
+ * WHY THE WORKSPACE NEEDS THIS AND THE PAGE DOES NOT. OPE-496 established the PAGE from the comment
+ * Notion returned under the verified credential, so the page is an authenticated fact. It left the
+ * WORKSPACE where it found it — `ev.workspace_id`, a payload field nothing authenticates — and the
+ * two are composed into `notion/<workspace>/<page>`. There is no verified source for the second
+ * half: Notion's REST surface returns no workspace id on any object (`/v1/users/me` gives
+ * `bot.workspace_name`, not an id), so no fetch under any credential can confirm the claim. Pinning
+ * the workspace to a config constant is wrong for a different reason — one deployment may hold
+ * several workspaces. So the claim is fenced instead of proved, exactly as OPE-500 fenced the
+ * trigger plane's scope path.
+ *
+ * WORKED THROUGH, because the point is what it REFUSES. Domain `security` claims workspace
+ * `notion/W-sec` in a container entry and binds integration `notion-security` with its own inbound
+ * secret. A holder of domain `payments`'s `verification_token` comments on a page their OWN
+ * integration can see, then signs a delivery whose `workspace_id` reads `W-sec`. The page reaches
+ * `security` through that claim, so without this fence the session opens on `security` — with
+ * `security`'s ambient flag, `security`'s read scope over every page under the claim, and (for an
+ * agent-initiated call) `security`'s credential. The fence reads that domain's credential, finds
+ * `notion-security` against a `notion-payments` signature, and refuses.
+ *
+ * FAIL CLOSED, AND THE REFUSALS ARE REAL:
+ *   • NO SIGNER ⇒ refuse. `webhooks.allowUnverifiedNotion` accepts a delivery with no secret
+ *     configured anywhere, so nothing identifies a sender and the fence has no fact to read. A fence
+ *     that says yes when it cannot tell is not a fence. The consequence is stated in the runbook: with
+ *     that dev hatch on, a CLAIMED page opens no session. A rostered page is unaffected, so the local
+ *     exercise the hatch exists for still runs.
+ *   • NO CLAIMED DOMAIN ⇒ allow. Either the page is rostered — see
+ *     {@link notionDeliveryClaimedDomains} for why a roster hit is not steerable — or it is in no
+ *     domain at all, where the `org` pseudo-domain answers and no payload field can steer that
+ *     either.
+ *
+ * THE PARTITION IS DECIDED SEPARATELY (OPE-254 §2, folding OPE-537). This fence decides the domain
+ * BOUNDARY; which partition a delivery lands in is notion-webhook.ts's step 8c, which composes the
+ * key from the workspace segment of the `reach` entry that MATCHED — `notionReachWorkspace`, on both
+ * legs. A page named outright therefore keys on config's workspace whatever a delivery claims. A
+ * page reached by a CONTAINER only matches when the payload's workspace equals the container's own
+ * text, so there the derived value equals the payload's by construction; a delivery naming a
+ * workspace no domain reaches matches nothing, and its key belongs to no domain — no memory, no
+ * bundle, and the ambient gate refuses it — rather than opening a second partition inside one.
+ *
+ * 🔴 WHY THE CONTAINER LEG NEEDED A CONFIG RULE, NOT JUST THE SAME READ. The exact-key match is
+ * workspace-BLIND — it finds a page by id alone, so the workspace read back off the matched entry
+ * is a signal INDEPENDENT of whatever the payload said. The container leg is the opposite shape:
+ * `notionPageDomain`'s container match composes `notion/<payload-workspace>/<page>` and only admits
+ * it when a container entry's tenant segment equals THAT SAME payload workspace verbatim
+ * (surface-key-grammar.ts refuses a glob on the tenant segment, so the compare is always exact). So
+ * whenever a container admits a delivery, the matched entry's workspace text and the payload's are,
+ * by construction, the identical string — reading the entry back is a no-op IN VALUE.
+ *
+ * What it is not is a no-op in PROPERTY, and that is the point. The remaining way one page could
+ * still key two ways was a domain reaching MORE THAN ONE Notion workspace: two honestly-signed
+ * deliveries for the same page, one naming each, opened two partitions. memory/domain.ts's
+ * `partitionTenantProblems` now refuses that config at load, so the matched entry names exactly one
+ * workspace per domain and the partition is a fact about config rather than about a delivery.
+ * No live re-keying follows: on every configuration that still loads, the derived value equals the
+ * value the payload carried, so no existing `channel_session` or memory row changes key.
+ *
+ * Pure — `domains` is injected, so the whole decision is unit-testable with no config and no store.
+ */
+export function notionDeliveryScopeVerdict(
+  workspaceId: string | undefined,
+  pageId: string,
+  signerCredentialId: string | undefined,
+  domains: readonly Domain[],
+): NotionDeliveryScopeVerdict {
+  const owners = notionDeliveryClaimedDomains(workspaceId, pageId, domains);
+  if (owners.length === 0) return { ok: true, detail: "no domain reaches this page through a workspace claim" };
+  if (!signerCredentialId) {
+    return {
+      ok: false,
+      reason: `no integration's secret identified this delivery, and page ${quoteNotionId(pageId)} is claimed through workspace ${quoteNotionId(workspaceId)}`,
+    };
+  }
+  const integrations = notionIntegrations(domains);
+  let viaSharedSecret = false;
+  for (const owner of owners) {
+    const verdict = notionSignerServesDomain(owner, signerCredentialId, integrations);
+    if (!verdict.served) {
+      return {
+        ok: false,
+        reason:
+          `page ${quoteNotionId(pageId)} reaches domain ${quoteNotionId(owner.name)} through its claim on workspace ` +
+          `${quoteNotionId(workspaceId)}, and that domain is served by notion credential ${quoteNotionId(verdict.expected)} — ` +
+          `this delivery was signed by ${quoteNotionId(signerCredentialId)}. A signed body cannot open a session on another domain.`,
+      };
+    }
+    if (verdict.via === "shared-secret") viaSharedSecret = true;
+  }
+  const named = owners.map((d) => quoteNotionId(d.name)).join(", ");
+  return {
+    ok: true,
+    detail: viaSharedSecret
+      ? `domain ${named} is served by an integration that shares this deployment's inbound secret`
+      : `domain ${named} is served by ${quoteNotionId(signerCredentialId)}`,
+  };
+}
+
+/**
+ * One id, safe to put in a log line. A refusal names the workspace and the page the SENDER chose —
+ * the very fields nothing authenticates — so a raw newline in one would forge a second log line. 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 short enough that a
+ * padded id cannot push the rest of the line out of a truncated log. Same helper the trigger plane's
+ * fence keeps for the same reason (notion-event-normalizer.ts `quote`); the two are three lines each
+ * and live beside the refusal they protect rather than in a shared string module.
+ */
+function quoteNotionId(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, "?"));
+}
+
+/**
+ * One integration's INBOUND signing key by operator-secret name, or undefined — and the ONE place
+ * that decides whether a failure is REPORTED.
+ *
+ * 🔴 THE FAILURE THAT MUST BE LOUD. "Nobody stored this name" is the ordinary state for an
+ * integration the operator never configured: it contributes no key, a delivery it would have signed
+ * simply fails the gate, and saying so on every POST would be noise. Every OTHER failure — an
+ * unarmed `OE_CREDENTIAL_ENCRYPTION_KEY`, a store that will not open — makes EVERY delivery on that
+ * integration 401 with nothing in the log to explain it. It is reported.
+ *
+ * The two are told apart by the ERROR CLASS ({@link OperatorSecretNotSetError}), never by the
+ * message: the unarmed-key message ALSO contains the words "is not set", so the substring test this
+ * replaces reported neither and a broken credential store went silent.
+ *
+ * `get` and `log` are injected so the decision is testable with no store and no eve boot; the route
+ * passes `getOperatorSecret` and its own channel logger. The report names the SECRET NAME and the
+ * reason, never a value. Both arms return undefined — this function never throws into a webhook.
+ */
+export async function resolveNotionInboundSecret(
+  name: string,
+  get: (secretName: string) => Promise<{ readonly value: string }>,
+  log: (message: string) => void,
+): Promise<string | undefined> {
+  try {
+    const resolved = await get(name);
+    return resolved.value.length > 0 ? resolved.value : undefined;
+  } catch (err) {
+    if (err instanceof OperatorSecretNotSetError) return undefined;
+    const message = err instanceof Error ? err.message : String(err);
+    log(`inbound signing key "${name}" did not resolve — deliveries signed with it will 401: ${message}`);
+    return undefined;
+  }
+}