@agent-native/core 0.98.5 → 0.98.7

package/corpus/core/src/integrations/identity-links-store.ts

@@ -0,0 +1,210 @@
+/**
+ * Durable links between a verified provider identity and an Agent Native user.
+ * Provider credentials and raw provider payloads never belong in this table.
+ */
+
+import { randomUUID } from "node:crypto";
+
+import {
+  getDbExec,
+  intType,
+  isPostgres,
+  isUniqueViolation,
+  retryOnDdlRace,
+} from "../db/client.js";
+import { ensureIndexExists, ensureTableExists } from "../db/ddl-guard.js";
+
+const TABLE = "integration_identity_links";
+let _initPromise: Promise<void> | undefined;
+
+export interface IntegrationIdentityLink {
+  id: string;
+  platform: string;
+  tenantId: string;
+  externalUserId: string;
+  userEmail: string;
+  orgId: string;
+  createdAt: number;
+  updatedAt: number;
+}
+
+function createSql(): string {
+  const integer = intType();
+  return `CREATE TABLE IF NOT EXISTS ${TABLE} (
+    id TEXT PRIMARY KEY,
+    platform TEXT NOT NULL,
+    tenant_id TEXT NOT NULL,
+    external_user_id TEXT NOT NULL,
+    user_email TEXT NOT NULL,
+    org_id TEXT NOT NULL,
+    created_at ${integer} NOT NULL,
+    updated_at ${integer} NOT NULL
+  )`;
+}
+
+const INDEXES = [
+  [
+    "idx_integration_identity_links_external",
+    `CREATE UNIQUE INDEX IF NOT EXISTS idx_integration_identity_links_external
+      ON ${TABLE}(platform, tenant_id, external_user_id)`,
+  ],
+  [
+    "idx_integration_identity_links_account",
+    `CREATE INDEX IF NOT EXISTS idx_integration_identity_links_account
+      ON ${TABLE}(org_id, user_email)`,
+  ],
+] as const;
+
+async function ensureTable(): Promise<void> {
+  if (!_initPromise) {
+    _initPromise = (async () => {
+      const client = getDbExec();
+      if (isPostgres()) {
+        await ensureTableExists(TABLE, createSql());
+        for (const [name, sql] of INDEXES) {
+          await ensureIndexExists(name, sql);
+        }
+        return;
+      }
+      await retryOnDdlRace(() => client.execute(createSql()));
+      for (const [, sql] of INDEXES) {
+        await retryOnDdlRace(() => client.execute(sql));
+      }
+    })().catch((error) => {
+      _initPromise = undefined;
+      throw error;
+    });
+  }
+  return _initPromise;
+}
+
+function required(value: string, name: string): string {
+  const normalized = value.trim();
+  if (!normalized) throw new Error(`${name} is required`);
+  if (normalized.length > 512) throw new Error(`${name} is too long`);
+  return normalized;
+}
+
+function normalizePlatform(value: string): string {
+  return required(value, "platform").toLowerCase();
+}
+
+function normalizeEmail(value: string): string {
+  const normalized = required(value, "userEmail").toLowerCase();
+  if (!normalized.includes("@")) throw new Error("userEmail must be an email");
+  return normalized;
+}
+
+function rowToLink(row: Record<string, unknown>): IntegrationIdentityLink {
+  return {
+    id: String(row.id),
+    platform: String(row.platform),
+    tenantId: String(row.tenant_id),
+    externalUserId: String(row.external_user_id),
+    userEmail: String(row.user_email),
+    orgId: String(row.org_id),
+    createdAt: Number(row.created_at ?? 0),
+    updatedAt: Number(row.updated_at ?? 0),
+  };
+}
+
+async function selectByExternalIdentity(
+  platform: string,
+  tenantId: string,
+  externalUserId: string,
+): Promise<IntegrationIdentityLink | null> {
+  await ensureTable();
+  const { rows } = await getDbExec().execute({
+    sql: `SELECT * FROM ${TABLE}
+      WHERE platform = ? AND tenant_id = ? AND external_user_id = ?
+      LIMIT 1`,
+    args: [platform, tenantId, externalUserId],
+  });
+  return rows[0] ? rowToLink(rows[0] as Record<string, unknown>) : null;
+}
+
+function matchesVerifiedLink(
+  row: IntegrationIdentityLink,
+  input: { userEmail: string; orgId: string },
+): boolean {
+  return row.userEmail === input.userEmail && row.orgId === input.orgId;
+}
+
+/** Persist a verified mapping and fail closed if it changes identity later. */
+export async function upsertVerifiedIntegrationIdentity(input: {
+  platform: string;
+  tenantId: string;
+  externalUserId: string;
+  userEmail: string;
+  orgId: string;
+}): Promise<IntegrationIdentityLink> {
+  const platform = normalizePlatform(input.platform);
+  const tenantId = required(input.tenantId, "tenantId");
+  const externalUserId = required(input.externalUserId, "externalUserId");
+  const userEmail = normalizeEmail(input.userEmail);
+  const orgId = required(input.orgId, "orgId");
+  const existing = await selectByExternalIdentity(
+    platform,
+    tenantId,
+    externalUserId,
+  );
+
+  if (existing) {
+    if (!matchesVerifiedLink(existing, { userEmail, orgId })) {
+      throw new Error(
+        "This provider identity is already linked to a different Agent Native account.",
+      );
+    }
+    const updatedAt = Date.now();
+    await getDbExec().execute({
+      sql: `UPDATE ${TABLE} SET updated_at = ? WHERE id = ?`,
+      args: [updatedAt, existing.id],
+    });
+    return { ...existing, updatedAt };
+  }
+
+  const id = randomUUID();
+  const now = Date.now();
+  try {
+    await getDbExec().execute({
+      sql: `INSERT INTO ${TABLE} (
+        id, platform, tenant_id, external_user_id, user_email, org_id,
+        created_at, updated_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+      args: [
+        id,
+        platform,
+        tenantId,
+        externalUserId,
+        userEmail,
+        orgId,
+        now,
+        now,
+      ],
+    });
+  } catch (error) {
+    if (!isUniqueViolation(error)) throw error;
+    const raced = await selectByExternalIdentity(
+      platform,
+      tenantId,
+      externalUserId,
+    );
+    if (!raced || !matchesVerifiedLink(raced, { userEmail, orgId })) {
+      throw new Error(
+        "This provider identity is already linked to a different Agent Native account.",
+      );
+    }
+    return raced;
+  }
+
+  return {
+    id,
+    platform,
+    tenantId,
+    externalUserId,
+    userEmail,
+    orgId,
+    createdAt: now,
+    updatedAt: now,
+  };
+}

package/corpus/core/src/integrations/identity.ts

@@ -0,0 +1,196 @@
+import { getDbExec } from "../db/client.js";
+import { upsertVerifiedIntegrationIdentity } from "./identity-links-store.js";
+import {
+  getActiveIntegrationInstallationByKey,
+  getActiveIntegrationInstallationForTenant,
+} from "./installations-store.js";
+import { slackInstallationKey } from "./slack-oauth.js";
+import type { IncomingMessage, IntegrationExecutionContext } from "./types.js";
+
+export type IntegrationIdentityDeclineReason =
+  | "unverified"
+  | "guest"
+  | "unlinked-workspace"
+  | "membership-check-failed";
+
+/**
+ * Thrown when the default Slack DM identity ladder declines to run a message.
+ * `reason` is a stable machine-readable discriminator (used e.g. to dedupe
+ * decline replies); `userFacingMessage` is safe to send back to the sender as
+ * a polite reply; `message` stays log-only.
+ */
+export class IntegrationIdentityDeclinedError extends Error {
+  readonly reason: IntegrationIdentityDeclineReason;
+  readonly userFacingMessage: string;
+
+  constructor(
+    reason: IntegrationIdentityDeclineReason,
+    message: string,
+    userFacingMessage: string,
+  ) {
+    super(message);
+    this.name = "IntegrationIdentityDeclinedError";
+    this.reason = reason;
+    this.userFacingMessage = userFacingMessage;
+  }
+}
+
+function serviceOwner(platform: string): string {
+  return `integration@${platform}`;
+}
+
+function normalizedEmail(value: unknown): string | null {
+  if (typeof value !== "string") return null;
+  const email = value.trim().toLowerCase();
+  if (!email || email.length > 320 || !email.includes("@")) return null;
+  return email;
+}
+
+async function resolveSlackInstallation(incoming: IncomingMessage) {
+  const teamId =
+    typeof incoming.platformContext.teamId === "string"
+      ? incoming.platformContext.teamId
+      : incoming.tenantId;
+  const enterpriseId =
+    typeof incoming.platformContext.enterpriseId === "string"
+      ? incoming.platformContext.enterpriseId
+      : undefined;
+  const apiAppId =
+    typeof incoming.platformContext.apiAppId === "string"
+      ? incoming.platformContext.apiAppId
+      : undefined;
+  if (apiAppId && (teamId || enterpriseId)) {
+    const byKey = await getActiveIntegrationInstallationByKey(
+      "slack",
+      slackInstallationKey({ teamId, enterpriseId, apiAppId }),
+    );
+    if (byKey) return byKey;
+  }
+  return teamId || enterpriseId
+    ? getActiveIntegrationInstallationForTenant(
+        "slack",
+        teamId ?? enterpriseId!,
+      )
+    : null;
+}
+
+async function isMemberOfOrg(email: string, orgId: string): Promise<boolean> {
+  const { rows } = await getDbExec().execute({
+    sql: `SELECT 1 FROM org_members
+        WHERE org_id = ? AND LOWER(email) = ?
+        LIMIT 1`,
+    args: [orgId, email],
+  });
+  return rows.length > 0;
+}
+
+/**
+ * Resolve the default integration principal.
+ *
+ * Slack DMs become a user principal only after the adapter has verified the
+ * sender email and the email is already a member of the managed installation's
+ * Agent Native organization. Hydrated full workspace members whose email is
+ * missing, unverified, or not an organization member run as an anonymous
+ * org-scoped service principal instead — the same visibility shared channels
+ * get. Hydration failures, guests/external members, and workspaces without a
+ * connected organization are declined with a user-facing message. Shared
+ * channels deliberately stay service-scoped so a channel message cannot borrow
+ * one participant's private permissions.
+ */
+export async function resolveDefaultIntegrationExecutionContext(
+  incoming: IncomingMessage,
+): Promise<IntegrationExecutionContext> {
+  const installation =
+    incoming.platform === "slack"
+      ? await resolveSlackInstallation(incoming)
+      : null;
+
+  if (incoming.platform !== "slack" || incoming.conversationType !== "dm") {
+    return {
+      ownerEmail: serviceOwner(incoming.platform),
+      orgId: installation?.orgId ?? null,
+      principalType: "service",
+      ...(installation?.id ? { installationId: installation.id } : {}),
+    };
+  }
+
+  // Hydration check first: a transient users.info failure must land on the
+  // retry decline here, never on the anonymous org-scoped tier below.
+  if (incoming.actorTrust?.verified !== true) {
+    throw new IntegrationIdentityDeclinedError(
+      "unverified",
+      "Slack DM sender identity could not be hydrated; declining instead of guessing a principal.",
+      "I couldn't verify your Slack identity just now, so I can't run this request. Please try again in a moment.",
+    );
+  }
+  if (
+    incoming.actorTrust.memberType === "guest" ||
+    incoming.actorTrust.memberType === "external"
+  ) {
+    throw new IntegrationIdentityDeclinedError(
+      "guest",
+      "External or guest Slack members cannot use this integration.",
+      "This assistant is only available to members of this workspace's organization.",
+    );
+  }
+  if (!installation?.orgId) {
+    throw new IntegrationIdentityDeclinedError(
+      "unlinked-workspace",
+      "Slack workspace is not connected to an Agent Native organization.",
+      "This Slack workspace isn't connected to an organization yet.",
+    );
+  }
+
+  const email = normalizedEmail(incoming.senderEmail);
+  let isOrgMember = false;
+  if (
+    email &&
+    incoming.senderVerified === true &&
+    incoming.senderId &&
+    incoming.tenantId
+  ) {
+    try {
+      isOrgMember = await isMemberOfOrg(email, installation.orgId);
+    } catch {
+      // A membership-store outage is not evidence that the sender is merely
+      // unlinked. Fail closed instead of widening them to org-wide access.
+      throw new IntegrationIdentityDeclinedError(
+        "membership-check-failed",
+        "Slack DM organization membership could not be verified.",
+        "I couldn't verify your organization membership just now, so I can't run this request. Please try again in a moment.",
+      );
+    }
+  }
+  if (isOrgMember && email && incoming.senderId && incoming.tenantId) {
+    const link = await upsertVerifiedIntegrationIdentity({
+      platform: incoming.platform,
+      tenantId: incoming.tenantId,
+      externalUserId: incoming.senderId,
+      userEmail: email,
+      orgId: installation.orgId,
+    });
+    return {
+      ownerEmail: link.userEmail,
+      orgId: link.orgId,
+      principalType: "user",
+      installationId: installation.id,
+    };
+  }
+
+  // Hydrated full workspace member (member/admin/owner) whose email is
+  // unverified, missing (legacy install without users:read.email), or not an
+  // organization member: run with the anonymous org-scoped service principal —
+  // the same visibility shared channels get. Nothing user-private is
+  // accessible. One structured line keeps 100%-anonymous workspaces (legacy
+  // scope missing) visible in logs.
+  console.warn(
+    `[integrations] anonymous org-scoped principal used: platform=${incoming.platform} teamId=${incoming.tenantId ?? "unknown"} emailPresent=${Boolean(email)} memberType=${incoming.actorTrust.memberType}`,
+  );
+  return {
+    ownerEmail: serviceOwner(incoming.platform),
+    orgId: installation.orgId,
+    principalType: "service",
+    installationId: installation.id,
+    anonymousMember: true,
+  };
+}

package/corpus/core/src/integrations/index.ts

@@ -18,6 +18,12 @@ export type {
 } from "./types.js";
 export { assertPlatformCapability } from "./types.js";
 
+export { resolveDefaultIntegrationExecutionContext } from "./identity.js";
+export {
+  upsertVerifiedIntegrationIdentity,
+  type IntegrationIdentityLink,
+} from "./identity-links-store.js";
+
 export {
   BUILT_IN_INTEGRATION_CATALOG,
   INTEGRATION_CATEGORIES,

package/corpus/core/src/integrations/plugin.ts

@@ -53,6 +53,10 @@ import {
   startGoogleDocsPoller,
   handlePushNotification,
 } from "./google-docs-poller.js";
+import {
+  IntegrationIdentityDeclinedError,
+  resolveDefaultIntegrationExecutionContext,
+} from "./identity.js";
 import {
   disconnectIntegrationInstallation,
   listIntegrationInstallations,
@@ -251,6 +255,11 @@ type IntegrationCredentialContext = {
 
 const REMOTE_DEVICE_ONLINE_MS = 90_000;
 
+// One decline reply per sender + decline reason per window: during a Slack
+// API outage every message would otherwise get another identical "try again"
+// reply. Short enough that a persistent condition still reminds the sender.
+const DECLINE_NOTICE_DEDUPE_TTL_MS = 5 * 60 * 1_000;
+
 export async function enqueueRemoteCommand(
   envelope: RemoteCodeCommandEnvelope,
 ): Promise<Record<string, unknown>> {
@@ -2343,13 +2352,87 @@ export function createIntegrationsPlugin(
             return { error: `Integration ${platform} is not enabled` };
           }
 
-          const incoming = await withCredentialContext(credentialContext, () =>
+          let incoming = await withCredentialContext(credentialContext, () =>
             adapter.parseIncomingMessage(event),
           );
           if (!incoming) {
             setResponseStatus(event, 200);
             return "ok";
           }
+          if (adapter.hydrateIncomingIdentity) {
+            try {
+              incoming = await withCredentialContext(credentialContext, () =>
+                adapter.hydrateIncomingIdentity!(incoming!),
+              );
+            } catch (err) {
+              // Identity hydration is best-effort for platforms that have an
+              // app-specific resolver. Slack's default DM resolver below will
+              // still fail closed when the identity is absent or unverified.
+              console.warn(
+                `[integrations] Could not hydrate ${platform} sender identity:`,
+                err instanceof Error ? err.message : err,
+              );
+            }
+          }
+          let defaultExecutionContext: IntegrationExecutionContext | null =
+            null;
+          if (
+            incoming.platform === "slack" &&
+            incoming.conversationType === "dm"
+          ) {
+            try {
+              defaultExecutionContext = await withCredentialContext(
+                credentialContext,
+                () => resolveDefaultIntegrationExecutionContext(incoming!),
+              );
+            } catch (err) {
+              // Only an explicit execution-context resolver may override the
+              // default Slack identity ladder. The legacy owner-only resolver
+              // predates org-bound identities and must not turn a rejected DM
+              // into an authenticated owner run.
+              if (!options?.resolveExecutionContext) {
+                const declined =
+                  err instanceof IntegrationIdentityDeclinedError ? err : null;
+                if (declined) {
+                  console.warn(
+                    `[integrations] default Slack DM identity declined message:`,
+                    declined.message,
+                  );
+                  // Best-effort polite reply back to the DM, deduped per
+                  // sender + reason so an outage doesn't produce an identical
+                  // reply for every message. Do not await Slack's API: webhook
+                  // acknowledgement has a stricter deadline than notice
+                  // delivery and must not be delayed by a slow postMessage.
+                  void withCredentialContext(credentialContext, () =>
+                    adapter.sendSystemNotice
+                      ? adapter.sendSystemNotice(
+                          incoming!,
+                          declined.userFacingMessage,
+                          {
+                            dedupeKey: `decline:${incoming!.tenantId ?? "unknown"}:${incoming!.senderId ?? "unknown"}:${declined.reason}`,
+                            dedupeTtlMs: DECLINE_NOTICE_DEDUPE_TTL_MS,
+                          },
+                        )
+                      : Promise.resolve(),
+                  ).catch((noticeErr) => {
+                    console.warn(
+                      `[integrations] decline notice failed:`,
+                      noticeErr instanceof Error
+                        ? noticeErr.message
+                        : noticeErr,
+                    );
+                  });
+                } else {
+                  console.error(
+                    `[integrations] default Slack DM identity denied message:`,
+                    err,
+                  );
+                }
+                setResponseStatus(event, 200);
+                return "ok";
+              }
+            }
+          }
           let executionContext: IntegrationExecutionContext = {
             ownerEmail: `integration@${platform}`,
             orgId: null as string | null,
@@ -2370,6 +2453,38 @@ export function createIntegrationsPlugin(
               setResponseStatus(event, 200);
               return "ok";
             }
+          } else if (defaultExecutionContext) {
+            executionContext = defaultExecutionContext;
+            if (defaultExecutionContext.anonymousMember) {
+              // The anonymous tier must never be silent. (1) The agent run
+              // can tell: the note rides the serialized `incoming` into the
+              // queued task and surfaces via <integration-context>.
+              incoming.identityNote =
+                "Caller is an unlinked Slack workspace member running with organization-wide visibility only; personal or privately-shared data is not accessible. They can get personal access by having an admin add their Slack email to the organization (or by reconnecting Slack with the users:read.email scope).";
+              // (2) The sender gets a one-time heads-up (adapter-throttled per
+              // sender). Fire-and-forget so it never delays or replaces the
+              // normal agent run.
+              if (adapter.sendSystemNotice) {
+                const senderEmail =
+                  typeof incoming.senderEmail === "string" &&
+                  incoming.senderEmail.trim()
+                    ? incoming.senderEmail.trim()
+                    : null;
+                const noticeText = senderEmail
+                  ? `Heads up: I couldn't match your Slack account to an organization member, so I can only use org-wide data. Ask an admin to add ${senderEmail} to the organization for personal access.`
+                  : "Heads up: I couldn't verify your Slack account's email, so I can only use org-wide data. Ask an admin to update the Slack connection with the users:read.email scope for personal access.";
+                void withCredentialContext(credentialContext, () =>
+                  adapter.sendSystemNotice!(incoming!, noticeText, {
+                    dedupeKey: `anonymous-tier:${incoming.tenantId ?? "unknown"}:${incoming.senderId ?? "unknown"}`,
+                  }),
+                ).catch((noticeErr) => {
+                  console.warn(
+                    `[integrations] anonymous-tier notice failed:`,
+                    noticeErr instanceof Error ? noticeErr.message : noticeErr,
+                  );
+                });
+              }
+            }
           } else if (options?.resolveOwner) {
             try {
               executionContext.ownerEmail = await withCredentialContext(
@@ -2382,6 +2497,20 @@ export function createIntegrationsPlugin(
                 err,
               );
             }
+          } else {
+            try {
+              executionContext = await withCredentialContext(
+                credentialContext,
+                () => resolveDefaultIntegrationExecutionContext(incoming!),
+              );
+            } catch (err) {
+              console.error(
+                `[integrations] default execution identity denied message:`,
+                err,
+              );
+              setResponseStatus(event, 200);
+              return "ok";
+            }
           }
           if (executionContext.scopeId) {
             incoming.integrationScopeId = executionContext.scopeId;

package/corpus/core/src/integrations/types.ts

@@ -104,6 +104,13 @@ export interface IncomingMessage {
     targetAgent?: string;
     instruction: string;
   };
+  /**
+   * Trusted app-side note about the caller's identity/visibility tier, set
+   * after execution-context resolution (e.g. an anonymous org-scoped Slack
+   * member). Surfaced to the agent as integration context. Adapters must not
+   * copy this from user-controlled webhook payload fields.
+   */
+  identityNote?: string;
   /** Provider-native message/activity reference for contextual replies. */
   replyRef?: string;
   /** Message timestamp (epoch ms) */
@@ -274,6 +281,13 @@ export interface PlatformAdapter {
    */
   hydrateIncomingMessage?(incoming: IncomingMessage): Promise<IncomingMessage>;
 
+  /**
+   * Hydrate only verified sender identity before execution-context selection.
+   * This runs on the provider acknowledgement path and must avoid fetching
+   * conversation history or file bodies.
+   */
+  hydrateIncomingIdentity?(incoming: IncomingMessage): Promise<IncomingMessage>;
+
   /**
    * Provider-specific response returned only after a message is verified and
    * durably enqueued. Discord uses this to return a type-5 deferred response
@@ -304,6 +318,23 @@ export interface PlatformAdapter {
     opts?: { placeholderRef?: string },
   ): Promise<void>;
 
+  /**
+   * Send a short best-effort system notice to the conversation the incoming
+   * message arrived on (polite identity declines, one-time access guidance).
+   * Bypasses agent formatting. When `dedupeKey` is provided, the adapter may
+   * drop the notice if the same key was sent recently. Callers must treat
+   * failures as non-fatal.
+   */
+  sendSystemNotice?(
+    incoming: IncomingMessage,
+    text: string,
+    opts?: {
+      dedupeKey?: string;
+      /** Dedupe window for `dedupeKey`. Adapters pick a default when omitted. */
+      dedupeTtlMs?: number;
+    },
+  ): Promise<void>;
+
   /**
    * Optionally post a "working on it…" placeholder message immediately when a
    * webhook arrives, before the agent loop runs. Adapters that support
@@ -429,4 +460,10 @@ export interface IntegrationExecutionContext {
   principalType: "user" | "service";
   installationId?: string;
   scopeId?: string;
+  /**
+   * True when a hydrated full workspace member could not be matched to an
+   * organization member and runs with the anonymous org-scoped service
+   * principal (org-wide visibility only, nothing user-private).
+   */
+  anonymousMember?: boolean;
 }

package/corpus/core/src/integrations/webhook-handler.ts

@@ -745,6 +745,7 @@ async function processIncomingMessage(
     incoming.senderName ? `Sender name: ${incoming.senderName}` : null,
     incoming.senderEmail ? `Sender email: ${incoming.senderEmail}` : null,
     incoming.senderId ? `Sender ID: ${incoming.senderId}` : null,
+    incoming.identityNote ? `Caller identity: ${incoming.identityNote}` : null,
     incoming.sourceUrl ? `Source thread: ${incoming.sourceUrl}` : null,
     incoming.routingHint?.targetAgent
       ? `Required target agent: ${incoming.routingHint.targetAgent}`