@opengeni/core 3.0.0-canary.0 → 3.0.1-canary.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/core",
-  "version": "3.0.0-canary.0",
+  "version": "3.0.1-canary.0",
   "description": "OpenGeni framework-agnostic core: the domain, access, and billing layers (neutral access, off-HTTP V2 surface). Behavior-preserving extraction from apps/api — keeps Hono's HTTPException for error throwing (typed-errors cleanup deferred).",
   "license": "Apache-2.0",
   "repository": {
@@ -58,17 +58,17 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@opengeni/capabilities": "^0.3.3-canary.15",
-    "@opengeni/codex": "^0.2.23-canary.0",
-    "@opengeni/config": "^1.2.1-canary.0",
-    "@opengeni/contracts": "^4.0.0-canary.0",
-    "@opengeni/db": "^5.0.0-canary.0",
-    "@opengeni/documents": "^0.8.29-canary.0",
-    "@opengeni/events": "^0.4.27-canary.0",
-    "@opengeni/network": "^0.3.1-canary.15",
-    "@opengeni/observability": "^0.8.28-canary.0",
-    "@opengeni/runtime": "^3.0.0-canary.0",
-    "@opengeni/storage": "^0.2.129-canary.0",
+    "@opengeni/capabilities": "^0.3.4-canary.0",
+    "@opengeni/codex": "^0.2.23-canary.2",
+    "@opengeni/config": "^1.2.2-canary.0",
+    "@opengeni/contracts": "^4.1.0-canary.0",
+    "@opengeni/db": "^5.0.1-canary.0",
+    "@opengeni/documents": "^0.8.30-canary.0",
+    "@opengeni/events": "^0.4.28-canary.0",
+    "@opengeni/network": "^0.3.1-canary.17",
+    "@opengeni/observability": "^0.8.29-canary.0",
+    "@opengeni/runtime": "^3.0.1-canary.0",
+    "@opengeni/storage": "^0.2.130-canary.0",
     "hono": "^4.12.18",
     "zod": "^4.2.1"
   },

package/src/application/connect-operation.ts

@@ -1,4 +1,7 @@
 import type { ConnectAttempt } from "@opengeni/contracts/connect";
+import { assertOrganizationIntegrationAllowed } from "@opengeni/contracts";
+import { withOrganizationIntegrationPolicyFence } from "@opengeni/db/organization-integration-policy";
+import { integrationKeyForConnectProvider } from "../domain/organization-integration-catalog";
 import {
   claimConnectOperation,
   finishConnectOperation,
@@ -31,11 +34,14 @@ export async function executeConnectOperation(input: {
   operationId: string;
   /** Caller computes a stable keyed digest if input contains low-entropy secrets. */
   inputDigest: string;
+  /** Trusted server adapter classification, never derived from request data.
+   * Cancellation releases pending setup; it acquires no integration authority. */
+  purpose?: "acquisition" | "cancellation";
   authorize: ConnectOperationAuthorization;
   execute: (attempt: ConnectAttempt) => Promise<PreparedConnectOperation>;
 }): Promise<ConnectAttempt> {
   // Snapshot caller-controlled identity before the first asynchronous boundary.
-  const { db, authorize, execute } = input;
+  const { db, authorize, execute, purpose = "acquisition" } = input;
   const scope = { ...input.scope };
   const operation = {
     attemptId: input.attemptId,
@@ -44,8 +50,31 @@ export async function executeConnectOperation(input: {
     inputDigest: input.inputDigest,
     authorize,
   };
-  const claim = await claimConnectOperation(db, scope, operation);
+  const claim = await withOrganizationIntegrationPolicyFence(db, scope, async (tx, policy) =>
+    claimConnectOperation(tx, scope, {
+      ...operation,
+      authorizeAcquisition: async (_tx, attempt) => {
+        if (purpose === "cancellation") return;
+        assertOrganizationIntegrationAllowed(
+          policy,
+          integrationKeyForConnectProvider(attempt.providerId),
+        );
+      },
+    }),
+  );
   if (claim.status === "replayed") return claim.attempt;
   const prepared = await execute(structuredClone(claim.attempt));
-  return finishConnectOperation(db, scope, { ...operation, commit: prepared.commit });
+  return withOrganizationIntegrationPolicyFence(db, scope, async (tx, policy) =>
+    finishConnectOperation(tx, scope, {
+      ...operation,
+      commit: prepared.commit,
+      authorizeAcquisition: async (_tx, attempt) => {
+        if (purpose === "cancellation") return;
+        assertOrganizationIntegrationAllowed(
+          policy,
+          integrationKeyForConnectProvider(attempt.providerId),
+        );
+      },
+    }),
+  );
 }

package/src/domain/capabilities.ts

@@ -1,6 +1,8 @@
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+import { isDeepStrictEqual } from "node:util";
+import { withLockedCapabilityInstallation } from "@opengeni/db/capability-reconciliation";
 import { environmentsEncryptionKeyBytes, type Settings } from "@opengeni/config";
 import {
   CapabilityCatalogItem,
@@ -17,6 +19,7 @@ import {
   type McpServerConnectionRef,
   type McpPersonalConnectionDelegation,
   OPENGENI_PERSONAL_SLACK_MCP_URL,
+  assertOrganizationIntegrationAllowed,
   type SocialConnection,
 } from "@opengeni/contracts";
 import {
@@ -53,6 +56,10 @@ import {
   type InstalledSkillSummary,
 } from "@opengeni/db";
 import { HTTPException } from "hono/http-exception";
+import {
+  withOrganizationIntegrationAcquisition,
+  withOrganizationIntegrationPolicyFence,
+} from "@opengeni/db/organization-integration-policy";
 import { hasPermission } from "../access";
 import { isFikenConnection, preferredFikenConnection } from "./fiken";
 import { listSkillLibraryEntries, type SkillLibraryEntry } from "@opengeni/runtime/skill-library";
@@ -252,6 +259,7 @@ export async function enableCapability(
 /** Probe outside a durable Connect commit; persist the exact prepared settings
  * inside the caller's authorized receipt transaction. Native enable uses this too. */
 export async function prepareCapabilityEnable(input: EnableCapabilityInput) {
+  input = { ...input, payload: structuredClone(input.payload) };
   const item = await requireCatalogItem(
     input.db,
     input.workspaceId,
@@ -297,6 +305,40 @@ export async function prepareCapabilityEnable(input: EnableCapabilityInput) {
   delete installationConfig.headerNames;
   delete installationConfig.connectionRef;
   if (item.kind === "mcp") {
+    // This generic, potentially workspace-authored catalog is not proof of a
+    // curated provider identity. Dedicated Connect adapters classify separately.
+    const unchanged = await withOrganizationIntegrationPolicyFence(
+      input.db,
+      input,
+      async (tx, policy) => {
+        const existing = await unchangedMcpInstallation(
+          { ...input, db: tx },
+          item,
+          installationConfig,
+        );
+        if (existing) return existing;
+        assertOrganizationIntegrationAllowed(policy, "custom:mcp");
+        return null;
+      },
+    );
+    if (unchanged) {
+      return {
+        commit: (db: Database) =>
+          withOrganizationIntegrationPolicyFence(db, input, async (tx) => {
+            const current = await unchangedMcpInstallation(
+              { ...input, db: tx },
+              item,
+              installationConfig,
+            );
+            if (!current || !isDeepStrictEqual(current, unchanged)) {
+              throw new HTTPException(409, {
+                message: "Capability installation changed; reload before reconciling",
+              });
+            }
+            return current;
+          }),
+      };
+    }
     const headers = await resolveMcpCredentialHeaders(input, item);
     const connectionRef = input.payload.connectionRef
       ? await validateMcpCapabilityConnectionRef(input, item, input.payload.connectionRef)
@@ -326,7 +368,57 @@ export async function prepareCapabilityEnable(input: EnableCapabilityInput) {
     config: installationConfig,
     metadata: installationMetadata,
   };
-  return { commit: (db: Database) => enableCapabilityInstallation(db, installation) };
+  return {
+    commit: (db: Database) =>
+      item.kind === "mcp"
+        ? withOrganizationIntegrationAcquisition(db, installation, ["custom:mcp"], (tx) =>
+            enableCapabilityInstallation(tx, installation),
+          )
+        : enableCapabilityInstallation(db, installation),
+  };
+}
+
+/** A no-effect reconciliation is not a new acquisition. Validate ordinary
+ * connection visibility before locking the installation, and compare actual
+ * stored credentials rather than trusting caller-supplied identity hints. */
+async function unchangedMcpInstallation(
+  input: EnableCapabilityInput,
+  item: CapabilityCatalogItem,
+  requestedConfig: Record<string, unknown>,
+): Promise<CapabilityInstallation | null> {
+  const connectionRef = input.payload.connectionRef
+    ? await validateMcpCapabilityConnectionRef(input, item, input.payload.connectionRef)
+    : null;
+  const existing = await withLockedCapabilityInstallation(
+    input.db,
+    input.workspaceId,
+    item.id,
+    (tx) => getCapabilityInstallation(tx, input.workspaceId, item.id),
+  );
+  if (!existing || existing.kind !== "mcp" || existing.status !== "active") return null;
+  const {
+    headerNames: _names,
+    headersEncrypted: _encrypted,
+    headers: _headers,
+    ...storedConfig
+  } = existing.config;
+  const config = { ...requestedConfig, ...(connectionRef ? { connectionRef } : {}) };
+  const { mcpConnectivity: _storedConnectivity, ...storedMetadata } = existing.metadata;
+  const { mcpConnectivity: _requestedConnectivity, ...requestedMetadata } = input.payload.metadata;
+  if (
+    !isDeepStrictEqual(config, storedConfig) ||
+    !isDeepStrictEqual(requestedMetadata, storedMetadata)
+  )
+    return null;
+  const provided = normalizedMcpCredentialHeaders(input.payload.headers);
+  if (provided) {
+    const stored = await resolveMcpCredentialHeaders(
+      { ...input, payload: { ...input.payload, headers: {} } },
+      item,
+    );
+    if (!isDeepStrictEqual(provided, stored)) return null;
+  }
+  return existing;
 }
 
 /**

package/src/domain/connector-tool-permissions.ts

@@ -0,0 +1,297 @@
+import { createHash } from "node:crypto";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+import {
+  boundMcpResponseBody,
+  MCP_MAX_RESPONSE_BYTES,
+  assertMcpToolListWithinBounds,
+} from "@opengeni/runtime/mcp-network";
+import { createPinnedIntegrationTransport } from "@opengeni/capabilities";
+import type { Settings } from "@opengeni/config";
+import type {
+  AccessGrant,
+  ConnectorToolPermission,
+  ConnectorToolPermissionEntry,
+  ConnectorToolPermissionsResponse,
+  UpdateConnectorToolPermissionsRequest,
+} from "@opengeni/contracts";
+import {
+  buildConnectionTokenResolver,
+  getConnectionMetadata,
+  listConnectionsMetadata,
+  listEnabledMcpCapabilityServers,
+  listConnectorToolPermissionPolicies,
+  updateConnectorToolPermissionPolicies,
+  resolveConnectorActionPolicy,
+  type Database,
+} from "@opengeni/db";
+import { HTTPException } from "hono/http-exception";
+import { hasPermission } from "../access";
+import { buildCapabilityCatalog, settingsWithMcpCapabilityServers } from "./capabilities";
+
+type Input = {
+  db: Database;
+  settings: Settings;
+  workspaceId: string;
+  grant: AccessGrant;
+  capabilityId: string;
+  personalOwnerVerified: boolean;
+};
+type ListedTool = {
+  name: string;
+  title?: string | undefined;
+  description?: string | undefined;
+  annotations?:
+    | {
+        readOnlyHint?: boolean | undefined;
+        destructiveHint?: boolean | undefined;
+        title?: string | undefined;
+      }
+    | undefined;
+};
+
+export function connectorToolGroup(tool: ListedTool): "read" | "write" | "other" {
+  if (tool.annotations?.destructiveHint === true || tool.annotations?.readOnlyHint === false)
+    return "write";
+  if (tool.annotations?.readOnlyHint === true) return "read";
+  return "other";
+}
+
+async function resolveTarget(input: Input) {
+  const catalog = await buildCapabilityCatalog(input);
+  const item = catalog.items.find((candidate) => candidate.id === input.capabilityId);
+  if (
+    !item ||
+    !item.enabled ||
+    item.kind !== "mcp" ||
+    !item.runtime.mcpServerId ||
+    item.source === "built_in"
+  ) {
+    throw new HTTPException(404, { message: "Connected MCP connector not found" });
+  }
+  const enabled = await listEnabledMcpCapabilityServers(input.db, input.workspaceId);
+  const settings = settingsWithMcpCapabilityServers(input.settings, enabled);
+  const server = settings.mcpServers.find((candidate) => candidate.id === item.runtime.mcpServerId);
+  if (!server || server.url !== item.endpointUrl)
+    throw new HTTPException(409, { message: "Connector configuration is unavailable" });
+  const ref = server.connectionRef;
+  if (ref?.authoritySource === "host")
+    throw new HTTPException(409, {
+      message: "Tool permissions for this connection are managed by its host",
+    });
+  let connection = ref?.connectionId
+    ? await getConnectionMetadata(
+        input.db,
+        input.workspaceId,
+        ref.connectionId,
+        input.grant.subjectId,
+      )
+    : null;
+  if (ref?.subjectScope === "subject" && !ref.connectionId) {
+    const visible = await listConnectionsMetadata(
+      input.db,
+      input.workspaceId,
+      input.grant.subjectId,
+    );
+    connection =
+      visible.find(
+        (candidate) =>
+          candidate.subjectId === input.grant.subjectId &&
+          candidate.providerDomain === ref.providerDomain &&
+          (!ref.kind || candidate.kind === ref.kind) &&
+          candidate.status === "active",
+      ) ?? null;
+  }
+  if (
+    ref &&
+    (!connection ||
+      connection.providerDomain !== ref.providerDomain ||
+      (ref.kind && connection.kind !== ref.kind) ||
+      (ref.subjectScope === "subject"
+        ? connection.subjectId !== input.grant.subjectId
+        : connection.subjectId !== null))
+  ) {
+    throw new HTTPException(409, { message: "Reconnect this connector to manage its tools" });
+  }
+  if (connection?.subjectId && !input.personalOwnerVerified)
+    throw new HTTPException(403, {
+      message: "Only the authenticated connection owner may manage personal tool permissions",
+    });
+  // Same secret-free target identity used by runtime sessionMcpApprovalConnectionId.
+  const connectionId =
+    connection?.id ??
+    `session-mcp:${server.id}:${createHash("sha256").update(server.url, "utf8").digest("hex")}`;
+  return { server, connection, connectionId };
+}
+
+async function listTools(
+  input: Input,
+  target: Awaited<ReturnType<typeof resolveTarget>>,
+): Promise<ListedTool[]> {
+  let headers = { ...target.server.headers };
+  if (target.server.connectionRef) {
+    const result = await buildConnectionTokenResolver(
+      input.db,
+      input.settings,
+    )({
+      workspaceId: input.workspaceId,
+      ...(target.connection?.subjectId ? { subjectId: input.grant.subjectId } : {}),
+      serverId: target.server.id,
+      toolName: "tools/list",
+      connectionRef: { ...target.server.connectionRef, connectionId: target.connectionId },
+      destinationUrl: target.server.url,
+    });
+    if (result.status !== "ok") throw new Error("Reconnect this connector to load its tools.");
+    headers = { ...headers, ...result.headers };
+  }
+  const pinned = createPinnedIntegrationTransport({ network: input.settings });
+  const deadline = AbortSignal.timeout(15_000);
+  const client = new Client(
+    { name: "opengeni-tool-permissions", version: "0.1.0" },
+    { capabilities: {} },
+  );
+  try {
+    const transport = new StreamableHTTPClientTransport(new URL(target.server.url), {
+      requestInit: { headers },
+      fetch: async (url, init) =>
+        boundMcpResponseBody(
+          await pinned.fetch(url.toString(), {
+            ...init,
+            signal: init?.signal ? AbortSignal.any([deadline, init.signal]) : deadline,
+          }),
+          MCP_MAX_RESPONSE_BYTES,
+        ),
+    });
+    await client.connect(transport as unknown as Transport, {
+      timeout: 15_000,
+      maxTotalTimeout: 15_000,
+    });
+    const tools: ListedTool[] = [];
+    const cursors = new Set<string>();
+    let cursor: string | undefined;
+    do {
+      const page = await client.listTools(cursor ? { cursor } : undefined, {
+        timeout: 15_000,
+        maxTotalTimeout: 15_000,
+        signal: deadline,
+      });
+      tools.push(...page.tools);
+      assertMcpToolListWithinBounds(tools);
+      if (new Set(tools.map((tool) => tool.name)).size !== tools.length)
+        throw new Error("The connector returned duplicate tool names.");
+      cursor = page.nextCursor;
+      if (tools.length > 2048 || (cursor && cursors.has(cursor)))
+        throw new Error("The connector returned an invalid or oversized tool catalog.");
+      if (cursor) cursors.add(cursor);
+    } while (cursor);
+    return tools.filter(
+      (tool) => !target.server.allowedTools || target.server.allowedTools.includes(tool.name),
+    );
+  } finally {
+    await client.close().catch(() => undefined);
+  }
+}
+
+export async function getConnectorToolPermissions(
+  input: Input,
+): Promise<ConnectorToolPermissionsResponse> {
+  const target = await resolveTarget(input);
+  const policies = await listConnectorToolPermissionPolicies(input.db, {
+    accountId: input.grant.accountId,
+    workspaceId: input.workspaceId,
+    connectionId: target.connectionId,
+  });
+  const permission = (
+    name: string,
+  ): { permission: ConnectorToolPermission; inherited: boolean } => {
+    const resolved = resolveConnectorActionPolicy(policies, {
+      connectionId: target.connectionId,
+      serverId: target.server.id,
+      toolName: name,
+      actionName: "*",
+    });
+    if (!resolved.managed) return { permission: "allow", inherited: true };
+    return {
+      permission: resolved.entry?.policy ?? "block",
+      inherited: resolved.entry?.toolName !== name,
+    };
+  };
+  const defaultPolicy = policies.find(
+    (row) => row.serverId === target.server.id && row.toolName === "*" && row.actionName === "*",
+  );
+  let tools: ListedTool[] = [];
+  let discoveryError: string | null = null;
+  try {
+    tools = await listTools(input, target);
+    if (tools.some((tool) => tool.name === "*" || tool.name !== tool.name.trim())) {
+      tools = tools.filter((tool) => tool.name !== "*" && tool.name === tool.name.trim());
+      discoveryError =
+        "The connector exposes a reserved or whitespace-padded tool name. Individual permissions for these names are unsupported, so they are omitted from tool groups. The connector default still applies.";
+    }
+  } catch {
+    discoveryError =
+      "Could not load the connector's tools. Try again or reconnect. Your saved permissions still apply.";
+  }
+  return {
+    connectionId: target.connectionId,
+    serverId: target.server.id,
+    defaultPermission: defaultPolicy?.policy ?? null,
+    tools: tools.map(
+      (tool): ConnectorToolPermissionEntry => ({
+        name: tool.name,
+        ...((tool.title ?? tool.annotations?.title)
+          ? { title: tool.title ?? tool.annotations?.title }
+          : {}),
+        ...(tool.description ? { description: tool.description } : {}),
+        group: connectorToolGroup(tool),
+        ...permission(tool.name),
+        approvalRequired:
+          target.server.requireApproval === true ||
+          (Array.isArray(target.server.requireApproval) &&
+            target.server.requireApproval.includes(tool.name)),
+      }),
+    ),
+    discoveryError,
+    canManage: canManageConnectorPermissions(input.grant),
+  };
+}
+
+function canManageConnectorPermissions(grant: AccessGrant): boolean {
+  return (
+    hasPermission(grant.permissions, "capabilities:manage") &&
+    grant.principalKind !== "agent_attempt" &&
+    grant.principalKind !== "service" &&
+    !grant.serviceInitiator &&
+    !grant.serviceInitiatorContext
+  );
+}
+
+export async function updateConnectorToolPermissions(
+  input: Input & { payload: UpdateConnectorToolPermissionsRequest },
+): Promise<void> {
+  if (!canManageConnectorPermissions(input.grant))
+    throw new HTTPException(403, { message: "Connector management permission required" });
+  if (
+    input.payload.target === "tools" &&
+    input.payload.toolNames.some((name) => name === "*" || name !== name.trim())
+  )
+    throw new HTTPException(400, {
+      message: "Tool names must be exact and cannot use the connector-default wildcard.",
+    });
+  const target = await resolveTarget(input);
+  // Prevent a reconnect while the sheet is open from applying old choices to a new account.
+  if (target.connectionId !== input.payload.connectionId)
+    throw new HTTPException(409, {
+      message: "The connector account changed. Reload its permissions.",
+    });
+  await updateConnectorToolPermissionPolicies(input.db, {
+    accountId: input.grant.accountId,
+    workspaceId: input.workspaceId,
+    subjectId: input.grant.subjectId,
+    connectionId: target.connectionId,
+    serverId: target.server.id,
+    toolNames: input.payload.target === "default" ? ["*"] : input.payload.toolNames,
+    policy: input.payload.permission,
+  });
+}

package/src/domain/knowledge-files.ts

@@ -12,6 +12,7 @@ export async function prepareKnowledgeFile(
   deps: Pick<ApiRouteDeps, "db" | "objectStorage" | "getDocumentServices">,
   context: KnowledgeContext,
   fileId: string,
+  purpose: "evidence" | "reference" = "evidence",
 ) {
   const inspected = await inspectKnowledgeFilePreparation(deps.db, context, fileId);
   if (inspected.status !== "prepare") return inspected;
@@ -27,13 +28,19 @@ export async function prepareKnowledgeFile(
   ) {
     throw new Error("The original file no longer matches its retained metadata");
   }
-  const parsed = await deps.getDocumentServices().parser.parse(object.bytes, inspected.file);
-  // Empty extraction is a visible failure, not a searchable-ready receipt.
-  if (!parsed.text.trim()) throw new Error("No searchable text could be extracted from this file");
+  // A screenshot/diagram can support a visual finding without containing text.
+  // Keep its exact original; OCR is neither required evidence nor the finding.
+  const originalOnly = purpose === "evidence" && inspected.file.contentType.startsWith("image/");
+  const parsed = originalOnly
+    ? { text: "" }
+    : await deps.getDocumentServices().parser.parse(object.bytes, inspected.file);
+  if (!originalOnly && !parsed.text.trim())
+    throw new Error("No searchable text could be extracted from this file");
   return completeKnowledgeFilePreparation(deps.db, context, {
     fileId,
     title: inspected.file.filename,
     sourceVersion,
     content: parsed.text,
+    purpose,
   });
 }

package/src/domain/knowledge-messages.ts

@@ -82,6 +82,7 @@ export async function retainKnowledgeMessage(
         content: text,
         source: {
           kind: "conversation",
+          purpose: "evidence",
           sessionId: event.sessionId,
           externalId: event.id,
           capturedAt: event.occurredAt,