@open-everywhere/provider-notion 0.6.0 → 0.8.0

package/agent/channels/notion-api.ts

@@ -23,6 +23,7 @@ import {
   CredentialError,
   findConnectorCredential,
   guardCredentialFetch,
+  friendlyOutboundText,
   withRetryAfter,
   type CredentialEndpointRules,
   type RateLimitRetryOptions,
@@ -33,7 +34,7 @@ import type { NotionParentLink } from "./notion-ancestry-trust.js";
 /** Notion REST base + the API version header value. The version is a code constant (OPE-2411):
  *  it is a stable version that supports the comment retrieve/create endpoints and rich-text
  *  `mention` objects — everything this surface needs — and a version bump is a code change. */
-export const NOTION_API_BASE = "https://api.notion.com";
+const NOTION_API_BASE = "https://api.notion.com";
 const NOTION_API_VERSION = "2022-06-28";
 
 /**
@@ -421,6 +422,25 @@ export function notionOperation(method: string | undefined, url: string): string
   return `${verb} ${shape}`;
 }
 
+/**
+ * THE FRIENDLY-NAMES GUARD (OPE-2482), on the one Notion transport. A comment create or edit renders
+ * every raw id in its rich-text content as a name or plain words before it leaves. Every other call, and
+ * a body this cannot parse, goes out unchanged.
+ */
+export async function friendlyNotionInit(url: string, init: RequestInit): Promise<RequestInit> {
+  if (typeof init.body !== "string" || !/\/v1\/comments(?:\/|$|\?)/.test(url) || (init.method !== "POST" && init.method !== "PATCH")) return init;
+  try {
+    const parsed = JSON.parse(init.body) as { rich_text?: unknown };
+    if (!Array.isArray(parsed.rich_text)) return init;
+    for (const item of parsed.rich_text as Array<{ text?: { content?: unknown } }>) {
+      if (item?.text && typeof item.text.content === "string") item.text.content = await friendlyOutboundText(item.text.content, "notion");
+    }
+    return { ...init, body: JSON.stringify(parsed) };
+  } catch {
+    return init;
+  }
+}
+
 /**
  * THE ONE PLACE a Notion REST call leaves this host. Every helper below dispatches through here, so
  * the credential's endpoint fence ({@link NotionCallOpts.endpoints}) is applied on every path
@@ -459,9 +479,11 @@ export function notionOperation(method: string | undefined, url: string): string
  * per call, not streams a first attempt would consume. A body that WAS a stream could not be replayed
  * — do not introduce one here without giving `send` a fresh body per attempt.
  */
-function notionFetch(url: string, init: RequestInit, opts: NotionCallOpts): Promise<Response> {
+async function notionFetch(url: string, init: RequestInit, opts: NotionCallOpts): Promise<Response> {
   const base = opts.fetch ?? (globalThis.fetch as FetchLike);
   const send = guardCredentialFetch(opts.endpoints, "notion credential", base);
+  // The friendly-names guard renders a comment body ONCE, so every retry re-sends the same bytes.
+  init = await friendlyNotionInit(url, init);
   return withRetryAfter(() => send(url, init), {
     ...opts.retry,
     surface: "notion",
@@ -584,7 +606,7 @@ export interface NotionBlockParent {
 
 /** GET /v1/blocks/{block_id} — used ONLY to answer "which page owns this block?" for the domain
  *  fence (channels/notion-scope.ts). Throws on a non-2xx response. */
-export async function retrieveBlock(blockId: string, opts: NotionCallOpts): Promise<NotionBlockParent> {
+async function retrieveBlock(blockId: string, opts: NotionCallOpts): Promise<NotionBlockParent> {
   const res = await notionFetch(`${NOTION_API_BASE}/v1/blocks/${encodeURIComponent(blockId)}`, { method: "GET", headers: notionHeaders(opts) }, opts);
   if (!res.ok) throw new Error(`retrieveBlock ${blockId} failed: ${res.status} ${await safeText(res)}`);
   return (await res.json()) as NotionBlockParent;
@@ -602,7 +624,7 @@ export async function retrieveBlock(blockId: string, opts: NotionCallOpts): Prom
  * runs out of hops, or the lookup throws — every one of which the caller must treat as a REFUSAL,
  * never as permission.
  */
-export const BLOCK_PARENT_MAX_HOPS = 5;
+const BLOCK_PARENT_MAX_HOPS = 5;
 export async function resolveBlockOwningPage(blockId: string, opts: NotionCallOpts): Promise<string | undefined> {
   let id = blockId;
   for (let hop = 0; hop < BLOCK_PARENT_MAX_HOPS; hop++) {
@@ -637,7 +659,7 @@ export interface NotionPageParent {
 
 /** GET /v1/pages/{page_id} — used ONLY to answer "what owns this page?" for the ancestor walk
  *  (channels/notion-ancestry-trust.ts). Throws on a non-2xx response. */
-export async function retrievePage(pageId: string, opts: NotionCallOpts): Promise<NotionPageParent> {
+async function retrievePage(pageId: string, opts: NotionCallOpts): Promise<NotionPageParent> {
   const res = await notionFetch(`${NOTION_API_BASE}/v1/pages/${encodeURIComponent(pageId)}`, { method: "GET", headers: notionHeaders(opts) }, opts);
   if (!res.ok) throw new Error(`retrievePage ${pageId} failed: ${res.status} ${await safeText(res)}`);
   return (await res.json()) as NotionPageParent;

package/agent/channels/notion-engagement.ts

@@ -28,6 +28,7 @@ import { buildNotionAuth, notionConversationKey } from "./notion-identity.js";
 // TYPE ONLY — it erases, so the "this module imports only notion-identity.ts and core" note above
 // `markNotionEngaged`'s use in notion-supervisor.ts still holds and no cycle is added.
 import type { NotionVia } from "./notion-scope.js";
+import type { AuditDetail, AuditDetailBuilder } from "@open-everywhere/core/agent/adapter-api.js";
 
 /** The facts one Notion delivery contributes to the seam — everything the anchor and the partition
  *  need, and nothing about the comment's text. */
@@ -363,8 +364,8 @@ export interface NotionDispatchJoinIds {
  * An absent value is OMITTED rather than written as `undefined`: an audit row that carries a key
  * with no value reads, to anyone querying it, like a value that was looked for and found empty.
  */
-export function notionDispatchJoinDetail(ids: NotionDispatchJoinIds): Record<string, string> {
-  const out: Record<string, string> = {};
+export function notionDispatchJoinDetail(ids: NotionDispatchJoinIds): AuditDetail {
+  const out: AuditDetailBuilder = {};
   if (ids.deliveryId) out.deliveryId = ids.deliveryId;
   if (ids.commentId) out.commentId = ids.commentId;
   if (ids.wakeId) out.wakeId = ids.wakeId;

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

@@ -0,0 +1,36 @@
+// DO NOTION'S EVENTS REACH THIS DEPLOYMENT? (OPE-2547) — Notion's probe for core's routines/event-reach.ts.
+//
+// The native Notion route hands a delivery to the event plane only when an integration's inbound secret
+// VERIFIED it (./notion.ts, the event-plane leg is gated on `verified`). The `webhooks.allowUnverifiedNotion`
+// hatch never fires a routine, so it does not count here. With no integration's inbound secret configured,
+// no Notion routine can fire. This probe resolves each integration's secret through `getOperatorSecret`, the
+// resolver the route uses, and keeps only whether one resolved.
+//
+// 🔴 ONLY "NOT SET" IS A NO. `OperatorSecretNotSetError` says the secret is set nowhere, so the answer is
+// false. Every other failure (an unreadable config, a key that is not armed, a decrypt error) is no answer at
+// all, so the probe THROWS and core reads `unknown`. A false "no" would tell every Notion watch's room that it
+// is dead. One case remains: `getOperatorSecret` falls back to the env var when the credential store is
+// unreachable, so a secret kept only in the store reads as not set during a store outage.
+
+import { getConfig, getOperatorSecret, OperatorSecretNotSetError } from "@open-everywhere/core/agent/adapter-api.js";
+import { notionIntegrations } from "./notion-credentials.js";
+
+/**
+ * True when at least one Notion integration's inbound signing secret resolves. The route admits a delivery signed
+ * with ANY key that resolves, so one broken key does not decide: the probe tries every name. It throws only when no
+ * key resolved and at least one failed in a way other than "not set".
+ */
+export async function notionEventsReach(get: typeof getOperatorSecret = getOperatorSecret): Promise<boolean> {
+  // An unreadable config throws through: no answer, never "no integration".
+  const names = [...new Set(notionIntegrations(getConfig().loadDomains()).map((i) => i.inboundSecret))];
+  let failure: unknown;
+  for (const name of names) {
+    try {
+      if ((await get(name)).value.length > 0) return true;
+    } catch (err) {
+      if (!(err instanceof OperatorSecretNotSetError) && failure === undefined) failure = err;
+    }
+  }
+  if (failure !== undefined) throw failure;
+  return false;
+}

package/agent/channels/notion-scope.ts

@@ -44,6 +44,7 @@
 
 import {
   appendAudit,
+  auditSurfaceModeFrom,
   bindFrom,
   domainReachVerdict,
   domainRoster,
@@ -431,6 +432,8 @@ async function auditNotionReadRefusal(
     platform: "notion",
     workspace: foreignCaller ? "unknown" : partition.workspace,
     surface: foreignCaller ? "unknown" : partition.surface,
+    // OPE-1940: the mode belongs to the caller's own surface, so a foreign-caller row carries none.
+    ...(foreignCaller ? {} : auditSurfaceModeFrom(ctx)),
     ...(principalId ? { principalId } : {}),
     action: "read.refused",
     detail: {

package/agent/channels/notion-supervisor.ts

@@ -658,8 +658,8 @@ export function notionIngestedMessages(d: {
 }
 
 /**
- * THE EXTERNAL-AUTHOR DECISION for one Notion dispatch (OPE-507). Pure, exported so the three
- * behaviours are testable without a store or a live wake.
+ * THE EXTERNAL-AUTHOR DECISION for one Notion dispatch (OPE-507). Pure, so the three behaviours
+ * need no store and no live wake.
  *
  * Notion's three answers, and why they are what they are:
  *   • the TRIGGER's author is excluded ⇒ NO WAKE AT ALL (`suppressed`). That covers behaviour 2
@@ -676,7 +676,7 @@ export function notionIngestedMessages(d: {
  * message" into a shared doc is a disclosure, not a notice, so the Notion answer is to do nothing.
  * The surfaces that HAVE a private channel (a Discord DM, a Slack DM) post the notice there.
  */
-export function notionExternalAuthorDecision(d: {
+function notionExternalAuthorDecision(d: {
   readonly trigger: NotionWakeMessage;
   readonly threadComments: readonly NotionWakeMessage[];
   readonly ingested: readonly IngestedChatMessage[];

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

@@ -5,6 +5,8 @@
 // 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.
 
+import type { AuditDetail } from "@open-everywhere/core/agent/adapter-api.js";
+
 export const NOTION_WEBHOOK_TIMING_ACTION = "notion.webhook_timing";
 
 export type NotionWebhookTimingPhase =
@@ -17,8 +19,8 @@ export type NotionWebhookTimingPhase =
   | "eveSend"
   | "finalAudit";
 
-export interface NotionWebhookTimingDetail {
-  readonly [key: string]: unknown;
+/** An audit detail, so its error-named keys carry the OPE-2549 brand guard. It holds none today. */
+export interface NotionWebhookTimingDetail extends AuditDetail {
   readonly outcome: string;
   readonly failedPhase?: NotionWebhookTimingPhase;
   readonly hmacCredentialMs?: number;

package/agent/channels/notion.ts

@@ -58,11 +58,13 @@
 // notion-ambient-surface-design.md Step 5 / the e2e-issue-surfaces driver investigation).
 // ────────────────────────────────────────────────────────────────────────────────────────
 
+import { auditErrorDetail } from "@open-everywhere/core/agent/adapter-api.js";
 import { defineChannel, POST, type RouteHandlerArgs } from "eve/channels";
 import {
   receiptEventTime,
   spreadVendorTs,
   appendAudit,
+  auditSurfaceModeFrom,
   ingressSpendGate,
   auditAmbientSkip,
   deploymentOrg,
@@ -592,7 +594,7 @@ async function deliverNotionAnswer(input: {
       { continuationToken: input.token, context: input.context },
     );
   } catch (err) {
-    const error = (err instanceof Error ? err.message : String(err)).slice(0, 300);
+    const error = auditErrorDetail(err).error;
     log(`answer ${input.answer.requestId} could NOT be delivered (${error}) — falling back to an ordinary wake, the question stays open`);
     await appendAudit({
       org: input.answerOrg,
@@ -841,6 +843,8 @@ const notionWebhookRouteHandler = timedNotionWebhookRoute(
           platform: "notion",
           workspace: d.workspaceId ?? "unknown",
           surface: d.pageId || d.discussionId || "unknown",
+          // OPE-1940: the RESOLVED mode, from the same delivery auth the wake binds.
+          ...auditSurfaceModeFrom({ channel: { kind: "notion" }, session: { auth: { current: d.auth } } } as unknown as Parameters<typeof auditSurfaceModeFrom>[0]),
           principalId: d.auth.principalId || undefined,
           action: "notion.dispatched",
           detail: {