@opengeni/api-router 0.30.1 → 1.0.0

package/src/routes/api-integrations.ts

@@ -1,11 +1,15 @@
 import {
   CORE_INTEGRATION_DEFINITIONS,
+  INTEGRATION_DEFINITION_PRESENTATIONS,
+  autoApprovalForbidden,
   createPinnedIntegrationTransport,
+  integrationDefinitionById,
   integrationFacetDefinitions,
   type IntegrationCredentialResolver,
 } from "@opengeni/capabilities";
 import {
   ApiIntegrationPreview,
+  OrganizationIntegrationDeniedError,
   ListIntegrationDefinitionsResponse,
   ApiIntegrationUninstallPreview,
   InstallApiIntegrationRequest,
@@ -14,13 +18,21 @@ import {
   PreviewApiIntegrationRequest,
   UninstallApiIntegrationRequest,
   UninstallApiIntegrationResult,
+  type AccessGrant,
 } from "@opengeni/contracts";
-import { requireAccessGrant, type ApiRouteDeps } from "@opengeni/core";
 import {
+  requireAccessGrant,
+  integrationSourceForOrganizationPolicy,
+  type ApiRouteDeps,
+} from "@opengeni/core";
+import { withOrganizationIntegrationPolicyFence } from "@opengeni/db/organization-integration-policy";
+import {
+  ApiIntegrationConnectionReferenceError,
   ApiIntegrationInstallationVersionConflictError,
   buildConnectionTokenResolver,
   getApiIntegrationUninstallPreview,
   getConnectionMetadata,
+  getApiIntegrationReconciliationSnapshot,
   installApiIntegration,
   IntegrationFacetBindingOwnershipConflictError,
   IntegrationFacetBindingVersionConflictError,
@@ -36,7 +48,10 @@ import { HTTPException } from "hono/http-exception";
 import {
   resolveApiIntegrationPreview,
   type ApiIntegrationConnectionDescriptor,
+  type ResolvedApiIntegrationPreview,
 } from "../integrations/api-integrations";
+import { ApiHttpError } from "../http/api-error";
+import { parseRequestJson } from "../http/request-body";
 
 export type ApiIntegrationRouteOverrides = Readonly<{ fetchImpl?: FetchLike }>;
 
@@ -45,6 +60,146 @@ export function apiIntegrationRequiresConnection(authScheme: Record<string, unkn
   return typeof authKind === "string" && authKind !== "none";
 }
 
+/** Shared native/embedded install validation. The caller must still authorize
+ * capabilities:manage and commit under its own live-authority boundary. */
+export function validatedIntegrationInstallInput(
+  grant: AccessGrant,
+  workspaceId: string,
+  payload: InstallApiIntegrationRequest,
+  resolved: ResolvedApiIntegrationPreview,
+): Parameters<typeof installApiIntegration>[1] {
+  if (
+    resolved.preview.revisionId !== payload.expectedRevisionId ||
+    resolved.preview.contentSha256 !== payload.expectedContentSha256
+  ) {
+    throw new HTTPException(409, {
+      message:
+        "The Integration source changed after preview. Review the new tools and permissions before installing.",
+    });
+  }
+  if (resolved.preview.auth.kind !== "none" && !payload.connectionId)
+    throw new HTTPException(422, {
+      message: "Connect an account before installing this Integration.",
+    });
+  if (
+    payload.ownership &&
+    resolved.preview.connectionOwnership &&
+    payload.ownership !== resolved.preview.connectionOwnership
+  )
+    throw new HTTPException(422, {
+      message: "The selected Connection ownership does not match this install request.",
+    });
+  if (payload.ownership === "personal" && !resolved.preview.connectionOwnership)
+    throw new HTTPException(422, {
+      message: "Choose a Personal Connection before installing for yourself.",
+    });
+  if (payload.autoApprovedTools?.length) {
+    const selected = new Set(payload.allowedTools ?? resolved.preview.tools.map((tool) => tool.id));
+    const outside = payload.autoApprovedTools.find((tool) => !selected.has(tool));
+    if (outside)
+      throw new HTTPException(422, {
+        message: `autoApprovedTools must name selected Integration tools: ${outside.slice(0, 200)}`,
+      });
+    // Curated and custom Integrations share one rule (capabilities:manage plus
+    // the organization acquisition recheck in the installer); only a curated
+    // definition's reviewed governance can forbid an exemption.
+    if (resolved.preview.definitionProvenance === "curated") {
+      const definition = integrationDefinitionById(resolved.preview.definitionId);
+      const forbidden = resolved.preview.tools.find(
+        (tool) =>
+          payload.autoApprovedTools!.includes(tool.id) &&
+          autoApprovalForbidden(definition, tool.operationKey),
+      );
+      if (forbidden)
+        throw new HTTPException(422, {
+          message: `This Integration requires human approval for ${forbidden.id.slice(0, 200)}; it cannot be auto-approved.`,
+        });
+    }
+  }
+  return {
+    accountId: grant.accountId,
+    workspaceId,
+    subjectId: grant.subjectId,
+    capabilityId: resolved.preview.capabilityId,
+    pluginKey: resolved.preview.pluginKey,
+    serverId: resolved.preview.serverId,
+    name: resolved.preview.name,
+    description: resolved.preview.description,
+    category: "integrations",
+    tags: [resolved.preview.protocol, resolved.preview.provider ?? "custom"],
+    definitionId: resolved.preview.definitionId,
+    definitionProvenance: resolved.preview.definitionProvenance,
+    ...(resolved.provider ? { provider: resolved.provider } : {}),
+    providerDomain: resolved.preview.providerDomain,
+    protocol: resolved.preview.protocol,
+    baseUrl: resolved.preview.baseUrl,
+    sourceUrl: resolved.preview.sourceUrl,
+    authScheme: resolved.authScheme,
+    ...(payload.connectionId ? { connectionId: payload.connectionId } : {}),
+    ...(payload.instanceKey ? { instanceKey: payload.instanceKey } : {}),
+    ...(payload.displayName ? { displayName: payload.displayName } : {}),
+    ...(payload.expectedInstanceVersion !== undefined
+      ? { expectedInstanceVersion: payload.expectedInstanceVersion }
+      : {}),
+    requiredScopes: resolved.requiredScopes,
+    ownership: resolved.preview.connectionOwnership === "personal" ? "subject" : "workspace",
+    ...(payload.allowedTools
+      ? { allowedTools: validatedAllowedToolIds(payload.allowedTools, resolved.revision.tools) }
+      : {}),
+    ...(payload.autoApprovedTools ? { autoApprovedTools: payload.autoApprovedTools } : {}),
+    facetDefinitions: integrationFacetDefinitions(resolved.preview.definitionId),
+    revision: resolved.revision,
+  };
+}
+
+const MAX_REPORTED_TOOL_IDS = 50;
+
+/**
+ * `allowedTools` names tools by their preview `id`, the stable identity the
+ * install persists. Reject anything else as a client error that lists the
+ * valid ids; a caller that sent a preview `operationKey` is told which id it
+ * maps to rather than having it silently reinterpreted.
+ */
+export function validatedAllowedToolIds(
+  allowedTools: readonly string[],
+  tools: readonly { id: string; operationKey: string }[],
+): string[] {
+  const ids = new Set(tools.map((tool) => tool.id));
+  const unknown = [
+    ...new Set(allowedTools.map((tool) => tool.trim()).filter((tool) => !ids.has(tool))),
+  ];
+  if (unknown.length === 0) return [...allowedTools];
+  const operationKeyMatches = unknown.flatMap((value) => {
+    const tool = tools.find((candidate) => candidate.operationKey === value);
+    return tool ? [{ operationKey: value, id: tool.id }] : [];
+  });
+  const validToolIds = tools.map((tool) => tool.id);
+  const shownUnknown = unknown.slice(0, 10);
+  const hint =
+    operationKeyMatches.length > 0
+      ? ` allowedTools takes tool ids, not operationKeys: ${operationKeyMatches
+          .slice(0, 5)
+          .map((match) => `${match.operationKey} -> ${match.id}`)
+          .join(", ")}.`
+      : "";
+  throw new ApiHttpError(422, {
+    code: "validation_failed",
+    message: `allowedTools contains unknown tool ids: ${shownUnknown.join(", ")}${
+      unknown.length > shownUnknown.length
+        ? `, and ${unknown.length - shownUnknown.length} more`
+        : ""
+    }. Use the \`id\` of each tool in the Integration preview.${hint}`,
+    retryable: false,
+    details: {
+      code: "unknown_integration_tools",
+      unknownTools: shownUnknown,
+      operationKeyMatches: operationKeyMatches.slice(0, MAX_REPORTED_TOOL_IDS),
+      validToolIds: validToolIds.slice(0, MAX_REPORTED_TOOL_IDS),
+      validToolIdCount: validToolIds.length,
+    },
+  });
+}
+
 export function registerApiIntegrationRoutes(
   app: Hono,
   deps: ApiRouteDeps,
@@ -52,7 +207,9 @@ export function registerApiIntegrationRoutes(
 ): void {
   const transport = createPinnedIntegrationTransport({
     network: deps.settings,
-    ...(overrides.fetchImpl ? { fetchImpl: overrides.fetchImpl } : {}),
+    ...((overrides.fetchImpl ?? deps.apiIntegrationSourceFetch)
+      ? { fetchImpl: overrides.fetchImpl ?? deps.apiIntegrationSourceFetch! }
+      : {}),
   });
 
   app.get("/v1/workspaces/:workspaceId/integrations/definitions", async (c) => {
@@ -70,6 +227,9 @@ export function registerApiIntegrationRoutes(
             kind: definition.authentication.kind,
             scopes: [...definition.authentication.scopes],
           },
+          ...(INTEGRATION_DEFINITION_PRESENTATIONS[definition.id]
+            ? { presentation: INTEGRATION_DEFINITION_PRESENTATIONS[definition.id] }
+            : {}),
           facets: definition.facets.map((facet) => ({
             facetKey: facet.facetKey,
             kind: facet.kind,
@@ -131,95 +291,53 @@ export function registerApiIntegrationRoutes(
   app.post("/v1/workspaces/:workspaceId/integrations/preview", async (c) => {
     const workspaceId = c.req.param("workspaceId");
     const grant = await requireAccessGrant(c, deps, workspaceId, "workspace:read");
-    const payload = PreviewApiIntegrationRequest.parse(await c.req.json());
+    const payload = await parseRequestJson(c, PreviewApiIntegrationRequest);
     const resolved = await resolveForRoute({
       deps,
       transport,
+      accountId: grant.accountId,
       workspaceId,
       subjectId: grant.subjectId,
       payload,
     });
-    return c.json(ApiIntegrationPreview.parse(resolved.preview));
+    const credentialWarnings = await connectionCredentialPlacementWarnings(
+      deps,
+      workspaceId,
+      grant.subjectId,
+      resolved.preview,
+    );
+    return c.json(
+      ApiIntegrationPreview.parse({
+        ...resolved.preview,
+        warnings: [...resolved.preview.warnings, ...credentialWarnings].slice(0, 32),
+      }),
+    );
   });
 
   app.post("/v1/workspaces/:workspaceId/integrations/install", async (c) => {
     const workspaceId = c.req.param("workspaceId");
-    const grant = await requireAccessGrant(c, deps, workspaceId, "workspace:admin");
-    const payload = InstallApiIntegrationRequest.parse(await c.req.json());
+    const grant = await requireAccessGrant(c, deps, workspaceId, "capabilities:manage");
+    const payload = await parseRequestJson(c, InstallApiIntegrationRequest);
     const resolved = await resolveForRoute({
       deps,
       transport,
+      accountId: grant.accountId,
       workspaceId,
       subjectId: grant.subjectId,
       payload,
     });
-    if (
-      resolved.preview.revisionId !== payload.expectedRevisionId ||
-      resolved.preview.contentSha256 !== payload.expectedContentSha256
-    ) {
-      throw new HTTPException(409, {
-        message:
-          "The Integration source changed after preview. Review the new tools and permissions before installing.",
-      });
-    }
-    if (resolved.preview.auth.kind !== "none" && !payload.connectionId) {
-      throw new HTTPException(422, {
-        message: "Connect an account before installing this Integration.",
-      });
-    }
-    if (
-      payload.ownership &&
-      resolved.preview.connectionOwnership &&
-      payload.ownership !== resolved.preview.connectionOwnership
-    ) {
-      throw new HTTPException(422, {
-        message: "The selected Connection ownership does not match this install request.",
-      });
-    }
-    if (payload.ownership === "personal" && !resolved.preview.connectionOwnership) {
-      throw new HTTPException(422, {
-        message: "Choose a Personal Connection before installing for yourself.",
-      });
-    }
+    const installation = validatedIntegrationInstallInput(grant, workspaceId, payload, resolved);
     try {
       return c.json(
-        InstalledApiIntegration.parse(
-          await installApiIntegration(deps.db, {
-            accountId: grant.accountId,
-            workspaceId,
-            subjectId: grant.subjectId,
-            capabilityId: resolved.preview.capabilityId,
-            pluginKey: resolved.preview.pluginKey,
-            serverId: resolved.preview.serverId,
-            name: resolved.preview.name,
-            description: resolved.preview.description,
-            category: "integrations",
-            tags: [resolved.preview.protocol, resolved.preview.provider ?? "custom"],
-            definitionId: resolved.preview.definitionId,
-            definitionProvenance: resolved.preview.definitionProvenance,
-            ...(resolved.provider ? { provider: resolved.provider } : {}),
-            providerDomain: resolved.preview.providerDomain,
-            protocol: resolved.preview.protocol,
-            baseUrl: resolved.preview.baseUrl,
-            sourceUrl: resolved.preview.sourceUrl,
-            authScheme: resolved.authScheme,
-            ...(payload.connectionId ? { connectionId: payload.connectionId } : {}),
-            ...(payload.instanceKey ? { instanceKey: payload.instanceKey } : {}),
-            ...(payload.displayName ? { displayName: payload.displayName } : {}),
-            ...(payload.expectedInstanceVersion !== undefined
-              ? { expectedInstanceVersion: payload.expectedInstanceVersion }
-              : {}),
-            requiredScopes: resolved.requiredScopes,
-            ownership:
-              resolved.preview.connectionOwnership === "personal" ? "subject" : "workspace",
-            ...(payload.allowedTools ? { allowedTools: payload.allowedTools } : {}),
-            facetDefinitions: integrationFacetDefinitions(resolved.preview.definitionId),
-            revision: resolved.revision,
-          }),
-        ),
+        InstalledApiIntegration.parse(await installApiIntegration(deps.db, installation)),
         payload.expectedInstanceVersion === undefined ? 201 : 200,
       );
     } catch (error) {
+      if (error instanceof ApiIntegrationConnectionReferenceError) {
+        throw new HTTPException(error.reason === "not_found" ? 404 : 422, {
+          message: error.reason === "not_found" ? "connection not found" : error.message,
+        });
+      }
       if (
         error instanceof IntegrationFacetBindingVersionConflictError ||
         error instanceof IntegrationFacetBindingVersionRequiredError ||
@@ -257,10 +375,10 @@ export function registerApiIntegrationRoutes(
     "/v1/workspaces/:workspaceId/integrations/:capabilityId/instances/:instanceKey",
     async (c) => {
       const workspaceId = c.req.param("workspaceId");
-      const grant = await requireAccessGrant(c, deps, workspaceId, "workspace:admin");
+      const grant = await requireAccessGrant(c, deps, workspaceId, "capabilities:manage");
       const capabilityId = decodeURIComponent(c.req.param("capabilityId"));
       const instanceKey = decodeURIComponent(c.req.param("instanceKey"));
-      const payload = UninstallApiIntegrationRequest.parse(await c.req.json());
+      const payload = await parseRequestJson(c, UninstallApiIntegrationRequest);
       try {
         return c.json(
           UninstallApiIntegrationResult.parse(
@@ -291,24 +409,48 @@ export function registerApiIntegrationRoutes(
   );
 }
 
-async function resolveForRoute(input: {
+export async function resolveForRoute(input: {
   deps: ApiRouteDeps;
   transport: ReturnType<typeof createPinnedIntegrationTransport>;
+  accountId: string;
   workspaceId: string;
   subjectId: string;
   payload: PreviewApiIntegrationRequest | InstallApiIntegrationRequest;
 }): ReturnType<typeof resolveApiIntegrationPreview> {
+  const payload = structuredClone(input.payload);
+  const preparation = await withOrganizationIntegrationPolicyFence(
+    input.deps.db,
+    input,
+    async (tx, policy) => {
+      try {
+        return { source: integrationSourceForOrganizationPolicy(policy, payload.source) };
+      } catch (error) {
+        if (!(error instanceof OrganizationIntegrationDeniedError)) throw error;
+        const install = InstallApiIntegrationRequest.safeParse(payload);
+        if (install.success) {
+          const resolved = await storedReconciliationPreview(
+            { ...input, deps: { ...input.deps, db: tx } },
+            install.data,
+          );
+          if (resolved) return { resolved };
+        }
+        throw error;
+      }
+    },
+  );
+  if (preparation.resolved) return preparation.resolved;
+  const source = preparation.source!;
   try {
-    const connection = input.payload.connectionId
+    const connection = payload.connectionId
       ? await requireVisibleConnection(
           input.deps,
           input.workspaceId,
           input.subjectId,
-          input.payload.connectionId,
+          payload.connectionId,
         )
       : null;
     return await resolveApiIntegrationPreview({
-      source: input.payload.source,
+      source,
       connection: connectionDescriptor(connection),
       transport: input.transport,
       authority: {
@@ -339,6 +481,154 @@ async function resolveForRoute(input: {
   }
 }
 
+async function storedReconciliationPreview(
+  input: { deps: ApiRouteDeps; accountId: string; workspaceId: string; subjectId: string },
+  payload: InstallApiIntegrationRequest,
+): Promise<ResolvedApiIntegrationPreview | null> {
+  const snapshot = await getApiIntegrationReconciliationSnapshot(input.deps.db, {
+    accountId: input.accountId,
+    workspaceId: input.workspaceId,
+    subjectId: input.subjectId,
+    source: payload.source,
+    expectedRevisionId: payload.expectedRevisionId,
+    expectedContentSha256: payload.expectedContentSha256,
+    ...(payload.connectionId !== undefined ? { connectionId: payload.connectionId } : {}),
+    ...(payload.instanceKey !== undefined ? { instanceKey: payload.instanceKey } : {}),
+    ...(payload.allowedTools !== undefined ? { allowedTools: payload.allowedTools } : {}),
+  });
+  if (!snapshot) return null;
+  const { runtime, baseServerId, name, provider, requiredScopes } = snapshot;
+  const connection = payload.connectionId
+    ? await requireVisibleConnection(
+        input.deps,
+        input.workspaceId,
+        input.subjectId,
+        payload.connectionId,
+      )
+    : null;
+  const scheme = runtime.authScheme;
+  const auth = !apiIntegrationRequiresConnection(scheme)
+    ? { kind: "none" }
+    : scheme.kind === "oauth2"
+      ? { kind: "oauth2", providerDomain: runtime.providerDomain, scopes: requiredScopes }
+      : scheme.kind === "api_key"
+        ? {
+            kind: "api_key",
+            providerDomain: runtime.providerDomain,
+            carrier: scheme.carrier,
+            name: scheme.name,
+          }
+        : scheme.kind === "http"
+          ? { kind: "http", providerDomain: runtime.providerDomain, scheme: scheme.scheme }
+          : null;
+  if (!auth) return null;
+  return {
+    preview: ApiIntegrationPreview.parse({
+      source: payload.source,
+      definitionId: runtime.definitionId,
+      definitionProvenance: runtime.definitionProvenance,
+      protocol: runtime.protocol,
+      capabilityId: runtime.capabilityId,
+      pluginKey: runtime.pluginKey,
+      serverId: baseServerId,
+      name,
+      description: runtime.description,
+      provider,
+      providerDomain: runtime.providerDomain,
+      baseUrl: runtime.baseUrl,
+      sourceUrl: runtime.sourceUrl,
+      revisionId: runtime.revision.id,
+      contentSha256: runtime.revision.contentSha256,
+      auth,
+      connectionId: connection?.id ?? null,
+      connectionOwnership: connection ? (connection.subjectId ? "personal" : "workspace") : null,
+      tools: runtime.revision.tools.map((tool) => ({
+        id: tool.id,
+        operationKey: tool.operationKey,
+        name: tool.name,
+        description: tool.description,
+        safety: tool.safety,
+        approvalMode: tool.approvalMode,
+        deprecated: tool.deprecated,
+      })),
+      warnings: [],
+    }),
+    revision: runtime.revision,
+    provider,
+    requiredScopes,
+    authScheme: runtime.authScheme,
+  };
+}
+
+/**
+ * Advisory preview check that the selected credential Connection delivers
+ * its secret where the API description says the provider reads it. Compares
+ * carrier and name only; never returns or logs a credential value. Install is
+ * unchanged: descriptions are often imprecise, so a mismatch warns instead of
+ * refusing a Connection the provider may actually accept.
+ */
+async function connectionCredentialPlacementWarnings(
+  deps: ApiRouteDeps,
+  workspaceId: string,
+  subjectId: string,
+  preview: ApiIntegrationPreview,
+): Promise<string[]> {
+  if (!preview.connectionId || (preview.auth.kind !== "api_key" && preview.auth.kind !== "http")) {
+    return [];
+  }
+  const connection = await getConnectionMetadata(
+    deps.db,
+    workspaceId,
+    preview.connectionId,
+    subjectId,
+  );
+  if (!connection || connection.kind === "oauth2") return [];
+  let result: Awaited<ReturnType<ReturnType<typeof buildConnectionTokenResolver>>>;
+  try {
+    result = await buildConnectionTokenResolver(
+      deps.db,
+      deps.settings,
+    )({
+      workspaceId,
+      ...(connection.subjectId ? { subjectId } : {}),
+      serverId: `preview_${connection.id}`,
+      connectionRef: {
+        connectionId: connection.id,
+        providerDomain: connection.providerDomain,
+        kind: connection.kind,
+        subjectScope: connection.subjectId ? "subject" : "workspace",
+      },
+      destinationUrl: preview.baseUrl,
+      credentialTarget: "http_api",
+    });
+  } catch {
+    return [];
+  }
+  if (result.status === "auth_needed") return [];
+  const expected =
+    preview.auth.kind === "api_key"
+      ? { carrier: preview.auth.carrier, name: preview.auth.name }
+      : { carrier: "header" as const, name: "Authorization" };
+  const placements =
+    result.placements ??
+    Object.keys(result.headers).map((name) => ({ carrier: "header" as const, name }));
+  const matches = placements.some(
+    (placement) =>
+      placement.carrier === expected.carrier &&
+      (placement.carrier === "header"
+        ? placement.name.toLowerCase() === expected.name.toLowerCase()
+        : placement.name === expected.name),
+  );
+  if (matches) return [];
+  const actual = placements
+    .slice(0, 3)
+    .map((placement) => `${placement.carrier} "${placement.name.slice(0, 64)}"`)
+    .join(", ");
+  return [
+    `The API description expects the credential in ${expected.carrier} "${expected.name.slice(0, 64)}", but the selected Connection sends it in ${actual}. Calls may be rejected as unauthenticated.`,
+  ];
+}
+
 async function requireVisibleConnection(
   deps: ApiRouteDeps,
   workspaceId: string,