@opengeni/capabilities 0.1.1 → 0.3.0-canary.0

package/src/mcp-bridge.ts

@@ -0,0 +1,117 @@
+import type { MCPServer } from "@openai/agents";
+
+export const LOCAL_MCP_BRIDGE_CONTRACT_VERSION = 1 as const;
+
+export type LocalMcpBridgeAuthority = "connection" | "host" | "none";
+export type LocalMcpBridgeToolSurface = "static_reviewed";
+
+export type LocalMcpBridgeDestination = Readonly<{
+  origin: string;
+  pathPrefix: string;
+}>;
+
+/**
+ * Secret-free description of an in-process provider-to-MCP adapter.
+ *
+ * This is observability and registration metadata, not authorization. The
+ * adapter must still revalidate its named authority before each physical
+ * provider request and keep credentials outside tool results and schemas.
+ */
+export type LocalMcpBridgeDescriptor = Readonly<{
+  contractVersion: typeof LOCAL_MCP_BRIDGE_CONTRACT_VERSION;
+  adapterId: string;
+  providerId: string;
+  catalogIdentity: string;
+  transport: "in_process";
+  authority: LocalMcpBridgeAuthority;
+  toolSurface: LocalMcpBridgeToolSurface;
+  mutationReplay: "safe_reads_only";
+  destinations: readonly LocalMcpBridgeDestination[];
+}>;
+
+export interface LocalMcpBridgeServer extends MCPServer {
+  readonly bridge: LocalMcpBridgeDescriptor;
+}
+
+export interface LocalMcpBridgeAdapter<TConfig, TContext> {
+  readonly adapterId: string;
+  matches(config: TConfig): boolean;
+  create(config: TConfig, context: TContext): LocalMcpBridgeServer;
+}
+
+export function defineLocalMcpBridgeDescriptor(
+  input: Omit<LocalMcpBridgeDescriptor, "contractVersion" | "transport">,
+): LocalMcpBridgeDescriptor {
+  const adapterId = boundedIdentity(input.adapterId, "adapterId");
+  const providerId = boundedIdentity(input.providerId, "providerId");
+  const catalogIdentity = boundedIdentity(input.catalogIdentity, "catalogIdentity", 512);
+  if (input.destinations.length === 0 || input.destinations.length > 32) {
+    throw new Error("Local MCP bridge must declare 1-32 provider destinations");
+  }
+  const destinations = input.destinations.map((destination) => {
+    const url = new URL(destination.origin);
+    if (url.protocol !== "https:" || url.origin !== destination.origin) {
+      throw new Error("Local MCP bridge destinations must be exact HTTPS origins");
+    }
+    if (
+      !destination.pathPrefix.startsWith("/") ||
+      destination.pathPrefix.includes("\\") ||
+      destination.pathPrefix.includes("?") ||
+      destination.pathPrefix.includes("#") ||
+      new URL(destination.pathPrefix, url.origin).pathname !== destination.pathPrefix
+    ) {
+      throw new Error("Local MCP bridge destination pathPrefix must be an absolute URL path");
+    }
+    return Object.freeze({ origin: url.origin, pathPrefix: destination.pathPrefix });
+  });
+  return Object.freeze({
+    contractVersion: LOCAL_MCP_BRIDGE_CONTRACT_VERSION,
+    adapterId,
+    providerId,
+    catalogIdentity,
+    transport: "in_process",
+    authority: input.authority,
+    toolSurface: input.toolSurface,
+    mutationReplay: input.mutationReplay,
+    destinations: Object.freeze(destinations),
+  });
+}
+
+export function isLocalMcpBridgeServer(server: MCPServer): server is LocalMcpBridgeServer {
+  const bridge = (server as Partial<LocalMcpBridgeServer>).bridge;
+  return (
+    bridge?.contractVersion === LOCAL_MCP_BRIDGE_CONTRACT_VERSION &&
+    bridge.transport === "in_process"
+  );
+}
+
+/**
+ * Select exactly one adapter for a runtime catalog row. Ambiguous matches fail
+ * closed so adding a bridge cannot silently replace another provider route.
+ */
+export function createLocalMcpBridgeFromAdapters<TConfig, TContext>(
+  adapters: readonly LocalMcpBridgeAdapter<TConfig, TContext>[],
+  config: TConfig,
+  context: TContext,
+): LocalMcpBridgeServer | null {
+  const matches = adapters.filter((adapter) => adapter.matches(config));
+  if (matches.length === 0) return null;
+  if (matches.length > 1) {
+    throw new Error(
+      `Multiple local MCP bridge adapters matched: ${matches.map((entry) => entry.adapterId).join(", ")}`,
+    );
+  }
+  const adapter = matches[0]!;
+  const server = adapter.create(config, context);
+  if (server.bridge.adapterId !== adapter.adapterId) {
+    throw new Error(`Local MCP bridge adapter ${adapter.adapterId} returned mismatched metadata`);
+  }
+  return server;
+}
+
+function boundedIdentity(value: string, name: string, max = 128): string {
+  if (value.length === 0 || value.length > max || /[\u0000-\u001f\u007f]/u.test(value)) {
+    throw new Error(`Local MCP bridge ${name} is invalid`);
+  }
+  return value;
+}

package/src/openapi.ts

@@ -55,7 +55,7 @@ export interface OpenApiOperationBinding {
 export type OpenApiRevision = IntegrationRevision<OpenApiOperationBinding, "openapi">;
 
 export interface CompileOpenApiOptions {
-  readonly integrationId: string;
+  readonly definitionId: string;
   readonly sourceUrl?: string;
   readonly baseUrl?: string;
   readonly provider?: string;
@@ -212,13 +212,13 @@ export function compileOpenApiRevision(
   return {
     id: revisionId,
     protocol: "openapi",
-    integrationId: options.integrationId,
+    definitionId: options.definitionId,
     contentSha256,
     source: {
       ...(options.sourceUrl ? { url: options.sourceUrl } : {}),
       ...(options.provider ? { provider: options.provider } : {}),
     },
-    title: stringValue(info.title) ?? options.integrationId,
+    title: stringValue(info.title) ?? options.definitionId,
     ...(stringValue(info.description) ? { description: stringValue(info.description)! } : {}),
     ...(stringValue(info.version) ? { version: stringValue(info.version)! } : {}),
     tools,
@@ -261,7 +261,7 @@ export class OpenApiMcpServer implements MCPServer {
   readonly name: string;
 
   constructor(private readonly options: OpenApiServerOptions) {
-    this.name = `openapi:${stableToolId(options.revision.integrationId)}`;
+    this.name = `openapi:${stableToolId(options.revision.definitionId)}`;
   }
 
   async connect(): Promise<void> {}
@@ -395,7 +395,7 @@ async function resolveOpenApiCredential(
   const credential = await options.credentialResolver.resolve({
     ...options.authority,
     protocol: "openapi",
-    integrationId: options.revision.integrationId,
+    definitionId: options.revision.definitionId,
     revisionId: options.revision.id,
     operationKey: toolId,
     destinationUrl,
@@ -426,6 +426,22 @@ async function sendOpenApiRequest(
   const headers = buildOperationHeaders(binding, args);
   const body = buildOperationBody(binding, args, headers);
   if (credential) applyCredentialPlacements(url, headers, credential);
+  if (credential?.authorizeProviderRequest) {
+    let authorized = false;
+    try {
+      authorized = await credential.authorizeProviderRequest();
+    } catch {
+      authorized = false;
+    }
+    if (!authorized) {
+      throw new IntegrationInvocationError(
+        "authorization_rejected",
+        "The connected account is no longer authorized for this operation",
+        "not_started",
+        false,
+      );
+    }
+  }
   return await fetchWithDeadline(
     options.transport,
     url,

package/src/types.ts

@@ -37,6 +37,8 @@ export interface IntegrationCredentialAudience {
 export interface ResolvedIntegrationCredential {
   readonly audience: IntegrationCredentialAudience;
   readonly placements: readonly IntegrationCredentialPlacement[];
+  /** Exact accepted-attempt fence invoked immediately before one HTTP request. */
+  readonly authorizeProviderRequest?: () => Promise<boolean>;
   readonly expiresAt?: string;
   readonly scope?: readonly string[];
 }
@@ -54,7 +56,7 @@ export interface IntegrationInvocationAuthority {
 
 export interface ResolveIntegrationCredentialRequest extends IntegrationInvocationAuthority {
   readonly protocol: Exclude<IntegrationProtocol, "mcp">;
-  readonly integrationId: string;
+  readonly definitionId: string;
   readonly revisionId: string;
   readonly operationKey: string;
   readonly destinationUrl: string;
@@ -90,7 +92,7 @@ export interface IntegrationRevision<
 > {
   readonly id: string;
   readonly protocol: TProtocol;
-  readonly integrationId: string;
+  readonly definitionId: string;
   readonly contentSha256: string;
   readonly source: IntegrationRevisionSource;
   readonly title: string;

package/dist/providers.d.ts

@@ -1,44 +0,0 @@
-export interface OAuthProviderPreset {
-    readonly authorizationUrl: string;
-    readonly tokenUrl: string;
-    readonly scopes: readonly string[];
-    readonly tokenPlacement: {
-        readonly carrier: "header";
-        readonly name: "Authorization";
-        readonly prefix: "Bearer ";
-    };
-}
-export interface OpenApiProviderPreset {
-    readonly id: string;
-    readonly name: string;
-    readonly summary: string;
-    readonly family: "google" | "microsoft";
-    readonly sourceFormat: "google-discovery" | "openapi";
-    readonly sourceUrl: string;
-    readonly baseUrl: string;
-    readonly oauth: OAuthProviderPreset;
-    readonly pathPrefixes?: readonly string[];
-    readonly healthOperation?: string;
-    readonly healthArgs?: Readonly<Record<string, unknown>>;
-    readonly features: readonly IntegrationFeatureDefinition[];
-}
-export interface IntegrationFeatureDefinition {
-    readonly featureKey: string;
-    readonly kind: "knowledge_source" | "inbound_trigger" | "delivery_destination" | "identity_link";
-    readonly configSchema: Readonly<Record<string, unknown>>;
-    readonly capabilities: Readonly<Record<string, unknown>>;
-}
-export declare const GOOGLE_DRIVE_PRESET: OpenApiProviderPreset;
-export declare const GOOGLE_GMAIL_PRESET: OpenApiProviderPreset;
-export declare const MICROSOFT_GRAPH_OPENAPI_URL = "https://raw.githubusercontent.com/microsoftgraph/msgraph-metadata/master/openapi/v1.0/openapi.yaml";
-export declare const MICROSOFT_GRAPH_BASE_URL = "https://graph.microsoft.com/v1.0";
-export declare const MICROSOFT_OUTLOOK_MAIL_PRESET: OpenApiProviderPreset;
-export declare const MICROSOFT_OUTLOOK_CALENDAR_PRESET: OpenApiProviderPreset;
-export declare const MICROSOFT_OUTLOOK_CONTACTS_PRESET: OpenApiProviderPreset;
-export declare const MICROSOFT_ONEDRIVE_PRESET: OpenApiProviderPreset;
-export declare const CORE_PROVIDER_PRESETS: readonly OpenApiProviderPreset[];
-export declare function providerPresetById(id: string): OpenApiProviderPreset | undefined;
-export declare function providerDomainForPreset(preset: OpenApiProviderPreset): string;
-export declare function integrationFeaturesForPreset(presetId: string | null | undefined): readonly IntegrationFeatureDefinition[];
-export declare function filterOpenApiDocumentForPreset(document: Record<string, unknown>, preset: OpenApiProviderPreset): Record<string, unknown>;
-export declare function googleDiscoveryToOpenApi(discovery: unknown): Record<string, unknown>;