@shipfox/api-integration-core 2.0.0

package/src/presentation/routes/agent-tools-gateway/resolve-authorized-tools.ts

@@ -0,0 +1,245 @@
+import {
+  type MaterializedAgentIntegrationConfigDto,
+  type MaterializedAgentIntegrationToolConfigDto,
+  materializedAgentStepConfigSchema,
+} from '@shipfox/api-agent-dto';
+import {requireLeasedJobContext} from '@shipfox/api-auth-context';
+import {ClientError} from '@shipfox/node-fastify';
+import type {IntegrationConnection} from '#core/entities/connection.js';
+import type {IntegrationProviderKind} from '#core/entities/provider.js';
+import type {AgentToolJsonSchema} from '#core/providers/agent-tools.js';
+import type {IntegrationProviderRegistry} from '#core/providers/registry.js';
+import type {GetIntegrationConnectionByIdFn} from '#db/connections.js';
+
+export type LeasedAgentStepLoader = (params: {
+  request: object;
+  stepId: string;
+  attempt: number;
+}) => Promise<{
+  step: {type: string; config: Record<string, unknown>};
+  workspaceId: string;
+}>;
+
+export interface AuthorizedIntegrationTool {
+  mcpName: string;
+  integration: MaterializedAgentIntegrationConfigDto;
+  tool: MaterializedAgentIntegrationToolConfigDto;
+  connection: IntegrationConnection;
+  description: string;
+  inputSchema: AgentToolJsonSchema;
+  outputSchema?: AgentToolJsonSchema | undefined;
+}
+
+export type AuthorizedIntegrationToolMap = Map<string, AuthorizedIntegrationTool>;
+
+export interface ResolveAuthorizedToolsParams {
+  request: object;
+  loadLeasedAgentStep: LeasedAgentStepLoader;
+  registry: IntegrationProviderRegistry;
+  getIntegrationConnectionById: GetIntegrationConnectionByIdFn;
+}
+
+export async function resolveAuthorizedIntegrationTools(
+  params: ResolveAuthorizedToolsParams,
+): Promise<AuthorizedIntegrationToolMap> {
+  const leasedJob = requireLeasedJobContext(params.request);
+  if (!leasedJob.currentStepId || leasedJob.currentStepAttempt === undefined) {
+    throw new ClientError('Lease does not identify a current step', 'lease-missing-step', {
+      status: 409,
+    });
+  }
+
+  const {step, workspaceId} = await params.loadLeasedAgentStep({
+    request: params.request,
+    stepId: leasedJob.currentStepId,
+    attempt: leasedJob.currentStepAttempt,
+  });
+  if (step.type !== 'agent') {
+    throw new ClientError('Current leased step is not an agent step', 'leased-step-not-agent', {
+      status: 409,
+    });
+  }
+
+  const integrations = parseAgentIntegrations(step.config);
+  const authorizedTools: AuthorizedIntegrationToolMap = new Map();
+
+  for (const integration of integrations) {
+    const connection = await loadAuthorizedConnection({
+      integration,
+      workspaceId,
+      registry: params.registry,
+      getIntegrationConnectionById: params.getIntegrationConnectionById,
+    });
+    const catalog = await params.registry.getAdapter(integration.provider, 'agent_tools').catalog();
+    const catalogByToolId = new Map(catalog.map((entry) => [entry.id, entry]));
+
+    for (const tool of integration.tools) {
+      const catalogTool = catalogByToolId.get(tool.id);
+      const mcpName = mcpToolName(integration.connectionSlug, tool.id);
+      if (authorizedTools.has(mcpName)) {
+        throw new ClientError(
+          'Integration tool names collide after MCP namespacing',
+          'integration-tool-name-collision',
+          {
+            status: 409,
+          },
+        );
+      }
+
+      authorizedTools.set(mcpName, {
+        mcpName,
+        integration,
+        tool,
+        connection,
+        // The live catalog enriches display metadata only. Frozen step config remains the allowlist.
+        description: catalogTool?.description ?? tool.id,
+        inputSchema: tool.methods ? toolInputSchema(tool) : tool.inputSchema,
+        outputSchema: tool.outputSchema ?? catalogTool?.outputSchema,
+      });
+    }
+  }
+
+  return authorizedTools;
+}
+
+export function sanitizeSlug(slug: string): string {
+  return slug.replaceAll('-', '_');
+}
+
+export function mcpToolName(connectionSlug: string, toolId: string): string {
+  return `${sanitizeSlug(connectionSlug)}__${toolId}`;
+}
+
+export function narrowMethodEnum(
+  inputSchema: AgentToolJsonSchema,
+  authorizedMethods: readonly string[],
+): AgentToolJsonSchema {
+  const schema = cloneSchema(inputSchema);
+  const methodSchema = getObjectProperty(schema, 'method');
+  if (methodSchema) {
+    narrowEnumOrConst(methodSchema, authorizedMethods);
+  }
+
+  // Claude rejects MCP tools with a top-level oneOf. The narrowed method enum remains the
+  // authority boundary, while provider validation enforces method-specific argument shapes.
+  delete schema.oneOf;
+
+  return schema;
+}
+
+function toolInputSchema(tool: MaterializedAgentIntegrationToolConfigDto): AgentToolJsonSchema {
+  const authorizedMethods = tool.methods?.map((method) => method.id) ?? [];
+  return narrowMethodEnum(tool.inputSchema, authorizedMethods);
+}
+
+function parseAgentIntegrations(
+  config: Record<string, unknown>,
+): MaterializedAgentIntegrationConfigDto[] {
+  try {
+    return materializedAgentStepConfigSchema.parse(config).integrations ?? [];
+  } catch (error) {
+    throw new ClientError('Agent step config is invalid', 'agent-step-config-invalid', {
+      status: 409,
+      cause: error,
+    });
+  }
+}
+
+async function loadAuthorizedConnection(params: {
+  integration: MaterializedAgentIntegrationConfigDto;
+  workspaceId: string;
+  registry: IntegrationProviderRegistry;
+  getIntegrationConnectionById: GetIntegrationConnectionByIdFn;
+}): Promise<IntegrationConnection> {
+  const connection = await params.getIntegrationConnectionById(params.integration.connectionId);
+  if (!connection) {
+    throw new ClientError(
+      'Integration connection is no longer available',
+      'integration-tool-connection-unavailable',
+      {
+        status: 409,
+      },
+    );
+  }
+  if (connection.workspaceId !== params.workspaceId) {
+    throw new ClientError(
+      'Integration connection does not belong to the leased workspace',
+      'integration-tool-connection-unavailable',
+      {
+        status: 409,
+      },
+    );
+  }
+  if (connection.lifecycleStatus !== 'active') {
+    throw new ClientError(
+      'Integration connection is not active',
+      'integration-tool-connection-unavailable',
+      {
+        status: 409,
+      },
+    );
+  }
+  if (connection.provider !== params.integration.provider) {
+    throw new ClientError(
+      'Integration connection provider changed',
+      'integration-tool-connection-unavailable',
+      {
+        status: 409,
+      },
+    );
+  }
+  if (!providerSupportsAgentTools(params.registry, params.integration.provider)) {
+    throw new ClientError(
+      'Integration provider no longer exposes agent tools',
+      'integration-tool-connection-unavailable',
+      {
+        status: 409,
+      },
+    );
+  }
+
+  return connection;
+}
+
+function providerSupportsAgentTools(
+  registry: IntegrationProviderRegistry,
+  provider: IntegrationProviderKind,
+): boolean {
+  try {
+    return registry.get(provider).capabilities.includes('agent_tools');
+  } catch {
+    return false;
+  }
+}
+
+function cloneSchema(schema: AgentToolJsonSchema): AgentToolJsonSchema {
+  return structuredClone(schema);
+}
+
+function getObjectProperty(
+  schema: AgentToolJsonSchema,
+  property: string,
+): AgentToolJsonSchema | null {
+  const properties = schema.properties;
+  if (!isRecord(properties)) return null;
+  const value = properties[property];
+  return isRecord(value) ? value : null;
+}
+
+function narrowEnumOrConst(
+  schema: AgentToolJsonSchema,
+  authorizedMethods: readonly string[],
+): void {
+  if (Array.isArray(schema.enum)) {
+    schema.enum = schema.enum.filter(
+      (value): value is string => typeof value === 'string' && authorizedMethods.includes(value),
+    );
+  }
+  if (typeof schema.const === 'string' && !authorizedMethods.includes(schema.const)) {
+    delete schema.const;
+  }
+}
+
+function isRecord(value: unknown): value is AgentToolJsonSchema {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/src/presentation/routes/errors.ts

@@ -0,0 +1,63 @@
+import {ClientError} from '@shipfox/node-fastify';
+import {
+  IntegrationCapabilityUnavailableError,
+  IntegrationCheckoutUnsupportedError,
+  IntegrationConnectionInactiveError,
+  IntegrationConnectionNotFoundError,
+  IntegrationConnectionWorkspaceMismatchError,
+  IntegrationProviderError,
+  type IntegrationProviderErrorReason,
+  IntegrationProviderUnavailableError,
+} from '#core/errors.js';
+
+function providerStatus(reason: IntegrationProviderErrorReason): number {
+  if (reason === 'rate-limited') return 429;
+  if (reason === 'timeout' || reason === 'provider-unavailable') return 503;
+  return 422;
+}
+
+function isProviderError(error: unknown): error is IntegrationProviderError {
+  return (
+    error instanceof IntegrationProviderError ||
+    (error instanceof Error &&
+      'reason' in error &&
+      typeof error.reason === 'string' &&
+      (error.reason === 'repository-not-found' ||
+        error.reason === 'file-not-found' ||
+        error.reason === 'access-denied' ||
+        error.reason === 'rate-limited' ||
+        error.reason === 'timeout' ||
+        error.reason === 'provider-unavailable' ||
+        error.reason === 'malformed-provider-response' ||
+        error.reason === 'content-too-large' ||
+        error.reason === 'too-many-files'))
+  );
+}
+
+export function integrationRouteErrorHandler(error: unknown): never {
+  if (error instanceof IntegrationConnectionNotFoundError) {
+    throw new ClientError(error.message, 'integration-connection-not-found', {status: 404});
+  }
+  if (error instanceof IntegrationConnectionInactiveError) {
+    throw new ClientError(error.message, 'integration-connection-inactive', {status: 422});
+  }
+  if (error instanceof IntegrationConnectionWorkspaceMismatchError) {
+    throw new ClientError(error.message, 'forbidden', {status: 403});
+  }
+  if (error instanceof IntegrationProviderUnavailableError) {
+    throw new ClientError(error.message, 'integration-provider-unavailable', {status: 422});
+  }
+  if (error instanceof IntegrationCapabilityUnavailableError) {
+    throw new ClientError(error.message, 'integration-capability-unavailable', {status: 422});
+  }
+  if (error instanceof IntegrationCheckoutUnsupportedError) {
+    throw new ClientError(error.message, 'integration-checkout-unsupported', {status: 422});
+  }
+  if (isProviderError(error)) {
+    throw new ClientError(error.message, error.reason, {
+      details: {retry_after_seconds: error.retryAfterSeconds},
+      status: providerStatus(error.reason),
+    });
+  }
+  throw error;
+}

package/src/presentation/routes/index.ts

@@ -0,0 +1,53 @@
+import type {RouteExport} from '@shipfox/node-fastify';
+import type {IntegrationProviderRegistry} from '#core/providers/registry.js';
+import type {IntegrationSourceControlService} from '#core/source-control-service.js';
+import type {GetIntegrationConnectionByIdFn} from '#db/connections.js';
+import {
+  createAgentToolsGatewayRoutes,
+  type LeasedAgentStepLoader,
+} from './agent-tools-gateway/index.js';
+import {createListIntegrationConnectionsRoute} from './list-connections.js';
+import {createListIntegrationProvidersRoute} from './list-providers.js';
+import {createListRepositoriesRoute} from './list-repositories.js';
+import {
+  createDeleteIntegrationConnectionRoute,
+  createUpdateIntegrationConnectionRoute,
+} from './manage-connections.js';
+
+export type {LeasedAgentStepLoader} from './agent-tools-gateway/index.js';
+
+export interface CreateIntegrationRoutesOptions {
+  agentTools?:
+    | {
+        loadLeasedAgentStep: LeasedAgentStepLoader;
+        getIntegrationConnectionById: GetIntegrationConnectionByIdFn;
+      }
+    | undefined;
+}
+
+export function createIntegrationRoutes(
+  registry: IntegrationProviderRegistry,
+  sourceControl: IntegrationSourceControlService,
+  options: CreateIntegrationRoutesOptions = {},
+): RouteExport[] {
+  const providerRoutes = registry.list().flatMap((provider) => provider.routes ?? []);
+  const agentToolsRoutes = options.agentTools
+    ? [
+        createAgentToolsGatewayRoutes({
+          registry,
+          loadLeasedAgentStep: options.agentTools.loadLeasedAgentStep,
+          getIntegrationConnectionById: options.agentTools.getIntegrationConnectionById,
+        }),
+      ]
+    : [];
+
+  return [
+    createListIntegrationProvidersRoute(registry),
+    createListIntegrationConnectionsRoute(registry),
+    createUpdateIntegrationConnectionRoute(registry),
+    createDeleteIntegrationConnectionRoute(),
+    createListRepositoriesRoute(sourceControl),
+    ...agentToolsRoutes,
+    ...providerRoutes,
+  ];
+}

package/src/presentation/routes/list-connections.test.ts

@@ -0,0 +1,227 @@
+import {upsertIntegrationConnection} from '#db/connections.js';
+import {linearProviderModule} from '#providers/linear.js';
+import {createTestApp, sourceProvider, useIntegrationRouteTest} from '#test/route-utils.js';
+
+describe('GET /integration-connections', () => {
+  const context = useIntegrationRouteTest();
+
+  it('lists workspace connections across all lifecycle statuses', async () => {
+    const app = await createTestApp([sourceProvider()]);
+    await upsertIntegrationConnection({
+      workspaceId: context.workspaceId,
+      provider: 'gitea',
+      externalAccountId: 'debug-active',
+      slug: 'debug_active',
+      displayName: 'Gitea',
+    });
+    await upsertIntegrationConnection({
+      workspaceId: context.workspaceId,
+      provider: 'gitea',
+      externalAccountId: 'debug-error',
+      slug: 'debug_error',
+      displayName: 'Gitea',
+      lifecycleStatus: 'error',
+    });
+
+    const res = await app.inject({
+      method: 'GET',
+      url: `/integration-connections?workspace_id=${context.workspaceId}`,
+      headers: {authorization: 'Bearer user'},
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(
+      res
+        .json()
+        .connections.map((connection: {lifecycle_status: string}) => connection.lifecycle_status),
+    ).toEqual(['active', 'error']);
+  });
+
+  it('drops connections whose provider misses the capability filter', async () => {
+    const app = await createTestApp([sourceProvider()]);
+    await upsertIntegrationConnection({
+      workspaceId: context.workspaceId,
+      provider: 'gitea',
+      externalAccountId: 'gitea-owner',
+      slug: 'gitea_owner',
+      displayName: 'Gitea',
+    });
+    await upsertIntegrationConnection({
+      workspaceId: context.workspaceId,
+      provider: 'github',
+      externalAccountId: 'team-1',
+      slug: 'github_team_1',
+      displayName: 'GitHub',
+    });
+
+    const res = await app.inject({
+      method: 'GET',
+      url: `/integration-connections?workspace_id=${context.workspaceId}&capability=source_control`,
+      headers: {authorization: 'Bearer user'},
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(
+      res.json().connections.map((connection: {provider: string}) => connection.provider),
+    ).toEqual(['gitea']);
+  });
+
+  it('advertises agent tools capability on matching connections', async () => {
+    const app = await createTestApp([
+      {
+        provider: 'github',
+        displayName: 'GitHub',
+        adapters: {
+          agent_tools: {
+            catalog: () => [],
+            selectionCatalog: () => ({selectors: []}),
+            openSession: async () => {
+              await Promise.resolve();
+              return {
+                call: async () => {
+                  await Promise.resolve();
+                  return {};
+                },
+              };
+            },
+          },
+        },
+      },
+    ]);
+    await upsertIntegrationConnection({
+      workspaceId: context.workspaceId,
+      provider: 'github',
+      externalAccountId: 'team-1',
+      slug: 'github_team_1',
+      displayName: 'GitHub',
+    });
+
+    const res = await app.inject({
+      method: 'GET',
+      url: `/integration-connections?workspace_id=${context.workspaceId}&capability=agent_tools`,
+      headers: {authorization: 'Bearer user'},
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json().connections).toMatchObject([
+      {
+        provider: 'github',
+        capabilities: ['agent_tools'],
+      },
+    ]);
+  });
+
+  it('advertises no capabilities on Linear connections before adapters exist', async () => {
+    const app = await createTestApp([{provider: 'linear', displayName: 'Linear', adapters: {}}]);
+    await upsertIntegrationConnection({
+      workspaceId: context.workspaceId,
+      provider: 'linear',
+      externalAccountId: 'org-1',
+      slug: 'linear_org_1',
+      displayName: 'Linear Org',
+    });
+
+    const res = await app.inject({
+      method: 'GET',
+      url: `/integration-connections?workspace_id=${context.workspaceId}`,
+      headers: {authorization: 'Bearer user'},
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json().connections).toMatchObject([
+      {
+        provider: 'linear',
+        capabilities: [],
+      },
+    ]);
+  });
+
+  it('advertises agent tools on Linear module connections', async () => {
+    const {provider} = await linearProviderModule.load();
+    const app = await createTestApp([provider]);
+    await upsertIntegrationConnection({
+      workspaceId: context.workspaceId,
+      provider: 'linear',
+      externalAccountId: 'org-1',
+      slug: 'linear_org_1',
+      displayName: 'Linear Org',
+    });
+
+    const res = await app.inject({
+      method: 'GET',
+      url: `/integration-connections?workspace_id=${context.workspaceId}&capability=agent_tools`,
+      headers: {authorization: 'Bearer user'},
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json().connections).toMatchObject([
+      {
+        provider: 'linear',
+        capabilities: ['agent_tools'],
+      },
+    ]);
+  });
+
+  it('includes external_url when the provider resolves one', async () => {
+    const app = await createTestApp([
+      sourceProvider({
+        connectionExternalUrl: () => Promise.resolve('https://gitea.local/team'),
+      }),
+    ]);
+    await upsertIntegrationConnection({
+      workspaceId: context.workspaceId,
+      provider: 'gitea',
+      externalAccountId: 'gitea-owner',
+      slug: 'gitea_owner',
+      displayName: 'Gitea',
+    });
+
+    const res = await app.inject({
+      method: 'GET',
+      url: `/integration-connections?workspace_id=${context.workspaceId}`,
+      headers: {authorization: 'Bearer user'},
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json().connections[0].external_url).toBe('https://gitea.local/team');
+  });
+
+  it('omits external_url and keeps the list alive when the provider lookup throws', async () => {
+    const app = await createTestApp([
+      sourceProvider({
+        connectionExternalUrl: () => Promise.reject(new Error('installation row missing')),
+      }),
+    ]);
+    await upsertIntegrationConnection({
+      workspaceId: context.workspaceId,
+      provider: 'gitea',
+      externalAccountId: 'gitea-owner',
+      slug: 'gitea_owner',
+      displayName: 'Gitea',
+    });
+
+    const res = await app.inject({
+      method: 'GET',
+      url: `/integration-connections?workspace_id=${context.workspaceId}`,
+      headers: {authorization: 'Bearer user'},
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json().connections).toHaveLength(1);
+    expect(res.json().connections[0].external_url).toBeUndefined();
+  });
+
+  it('returns membership errors', async () => {
+    const app = await createTestApp([sourceProvider()]);
+    const inaccessibleWorkspaceId = crypto.randomUUID();
+
+    const res = await app.inject({
+      method: 'GET',
+      url: `/integration-connections?workspace_id=${inaccessibleWorkspaceId}`,
+      headers: {authorization: 'Bearer user'},
+    });
+
+    expect(res.statusCode).toBe(403);
+    expect(res.json().code).toBe('forbidden');
+  });
+});

package/src/presentation/routes/list-connections.ts

@@ -0,0 +1,56 @@
+import {AUTH_USER, requireWorkspaceAccess} from '@shipfox/api-auth-context';
+import {
+  listIntegrationConnectionsQuerySchema,
+  listIntegrationConnectionsResponseSchema,
+} from '@shipfox/api-integration-core-dto';
+import {defineRoute} from '@shipfox/node-fastify';
+import type {IntegrationProviderRegistry} from '#core/providers/registry.js';
+import {listIntegrationConnections} from '#db/connections.js';
+import {toIntegrationConnectionDto} from '#presentation/dto/integrations.js';
+
+export function createListIntegrationConnectionsRoute(registry: IntegrationProviderRegistry) {
+  return defineRoute({
+    method: 'GET',
+    path: '/integration-connections',
+    auth: AUTH_USER,
+    description: 'List workspace integration connections across all lifecycle statuses.',
+    schema: {
+      querystring: listIntegrationConnectionsQuerySchema,
+      response: {
+        200: listIntegrationConnectionsResponseSchema,
+      },
+    },
+    handler: async (request) => {
+      const {workspace_id: workspaceId, capability} = request.query;
+
+      requireWorkspaceAccess({request, workspaceId});
+      const connections = await listIntegrationConnections({workspaceId});
+      const providers = new Map(
+        registry.list(capability).map((provider) => [provider.provider, provider]),
+      );
+      const connectionDtos = await Promise.all(
+        connections.map(async (connection) => {
+          const provider = providers.get(connection.provider);
+          if (!provider) return undefined;
+          // Best-effort: the external link is cosmetic, so a failing or missing
+          // provider-side lookup must never fail the whole connections list.
+          let externalUrl: string | undefined;
+          try {
+            externalUrl = await provider.connectionExternalUrl?.(connection);
+          } catch (error) {
+            request.log.warn(
+              {connectionId: connection.id, provider: connection.provider, err: error},
+              'Could not resolve integration connection external URL',
+            );
+          }
+          return toIntegrationConnectionDto(connection, {
+            capabilities: provider.capabilities,
+            externalUrl,
+          });
+        }),
+      );
+
+      return {connections: connectionDtos.filter((connection) => connection !== undefined)};
+    },
+  });
+}