feat: impl proxy (#45)

Author: l1shen

docs/runtime-api.md

@@ -132,8 +132,25 @@ under `OOMOL_CONNECT_DATA_DIR/files` and are cleaned up by age.
 - `GET /v1/apps/authenticated`
 - `POST /v1/proxy/:service`
 
-`POST /v1/proxy/:service` currently returns `proxy_not_supported` until a provider proxy runtime is
-implemented.
+`POST /v1/proxy/:service` proxies one provider API request when that provider has a registered or
+provider-specific local proxy executor. Providers without a proxy executor return `proxy_not_supported`.
+
+Request body:
+
+```json
+{
+  "endpoint": "/provider/path",
+  "method": "GET",
+  "query": { "limit": "10" },
+  "headers": { "accept": "application/json" },
+  "body": { "name": "example" }
+}
+```
+
+`endpoint` must be a relative path beginning with `/`; absolute URLs are rejected. The runtime keeps
+stored credentials local and lets the provider proxy executor apply provider-specific authentication.
+Successful responses use the standard `/v1` success envelope with `data.status`, `data.headers`, and
+`data.data`.
 
 ## Local Admin Endpoints
 

package.json

@@ -11,14 +11,18 @@
     "dev": "node scripts/dev-local.ts",
     "dev:api": "node scripts/ensure-generated.ts && node src/server/index.ts",
     "build": "npm run typecheck",
+    "build:cloudflare": "npm run generate:catalog && npm run build:web && npm run copy:catalog-assets && wrangler deploy --dry-run --config wrangler.local.jsonc --minify",
     "build:web": "npm run build --workspace web",
-    "dev:cloudflare": "npm run generate:catalog && npm run build:web && node scripts/copy-catalog-assets.ts && wrangler dev --config wrangler.local.jsonc",
-    "deploy:cloudflare": "npm run generate:catalog && npm run build:web && node scripts/copy-catalog-assets.ts && wrangler deploy --config wrangler.local.jsonc",
+    "dev:web": "npm run dev --workspace web",
+    "dev:cloudflare": "npm run generate:catalog && npm run build:web && npm run copy:catalog-assets && wrangler dev --config wrangler.local.jsonc",
+    "deploy:cloudflare": "npm run generate:catalog && npm run build:web && npm run copy:catalog-assets && wrangler deploy --config wrangler.local.jsonc --minify",
     "start": "node scripts/ensure-generated.ts && node src/server/index.ts",
     "test": "vitest run",
     "typecheck": "npm run generate:registry && node scripts/typecheck.ts src scripts-all examples",
     "generate:registry": "node scripts/generate-provider-registry.ts",
     "generate:catalog": "npm run generate:registry && node scripts/generate-catalog.ts",
+    "copy:catalog-assets": "node scripts/copy-catalog-assets.ts",
+    "search:actions": "node scripts/ensure-generated.ts && node scripts/search-actions.ts",
     "runtime:data": "node scripts/runtime-data.ts",
     "lint": "oxlint .",
     "lint:fix": "oxlint . --fix",

scripts/generate-provider-registry.ts

@@ -16,13 +16,14 @@ function propertyName(service: string): string {
   return /^[A-Za-z_$][\w$]*$/.test(service) ? service : JSON.stringify(service);
 }
 
-const lines = [
-  'import type { CredentialValidators, ProviderExecutors } from "../core/types.ts";',
+const registryLines = [
+  'import type { CredentialValidators, ProviderExecutors, ProviderProxyExecutor } from "../core/types.ts";',
   "",
   "/** Lazy-loaded provider executor module shape. */",
   "export type ExecutorModule = {",
   "  credentialValidators?: CredentialValidators;",
   "  executors: ProviderExecutors;",
+  "  proxy?: ProviderProxyExecutor;",
   "};",
   "",
   "/** Generated lazy imports for provider executors. Do not hand-edit. */",
@@ -43,7 +44,7 @@ const lines = [
 ];
 
 const registryPath = join(providersDir, "registry.generated.ts");
-const registryContent = `${lines.join("\n")}\n`;
+const registryContent = `${registryLines.join("\n")}\n`;
 const existingContent = await readTextFile(registryPath);
 if (existingContent !== registryContent) {
   await writeFile(registryPath, registryContent);

src/connection-service.test.ts

@@ -497,6 +497,10 @@ class FakeProviderLoader implements IProviderLoader {
     return undefined;
   }
 
+  async loadProxyExecutor(): Promise<undefined> {
+    return undefined;
+  }
+
   async loadCredentialValidators(_service: string): Promise<CredentialValidators | undefined> {
     return this.validators;
   }

src/core/types.ts

@@ -402,6 +402,40 @@ export type ActionExecutor<TInput = unknown, TOutput = unknown> = (
   context: ExecutionContext,
 ) => Promise<ExecutionResult<TOutput>>;
 
+export interface ProxyRequestInput {
+  endpoint: string;
+  method: string;
+  query?: Record<string, unknown>;
+  headers?: Record<string, unknown>;
+  body?: unknown;
+}
+
+export interface ProxyResponse {
+  status: number;
+  headers: Record<string, string>;
+  bodyEncoding?: "base64";
+  data: unknown;
+}
+
+export type ProxyExecutionResult =
+  | {
+      ok: true;
+      response: ProxyResponse;
+    }
+  | {
+      ok: false;
+      error: {
+        code: string;
+        message: string;
+        details?: unknown;
+      };
+    };
+
+export type ProviderProxyExecutor = (
+  input: ProxyRequestInput,
+  context: ExecutionContext,
+) => Promise<ProxyExecutionResult>;
+
 /**
  * Executor map for one provider.
  *

src/mcp.test.ts

@@ -159,6 +159,10 @@ class EchoProviderLoader implements IProviderLoader {
     return async (input) => ({ ok: true, output: input });
   }
 
+  async loadProxyExecutor(): Promise<undefined> {
+    return undefined;
+  }
+
   async loadCredentialValidators(): Promise<undefined> {
     return undefined;
   }

src/oauth/oauth-flow-service.test.ts

@@ -565,6 +565,10 @@ class EmptyProviderLoader implements IProviderLoader {
     return undefined;
   }
 
+  async loadProxyExecutor(): Promise<undefined> {
+    return undefined;
+  }
+
   async loadCredentialValidators(_service: string): Promise<CredentialValidators | undefined> {
     return undefined;
   }

src/providers/adobe_commerce/executors.ts

@@ -1,4 +1,9 @@
-import type { CredentialValidators, ExecutionContext, ProviderExecutors } from "../../core/types.ts";
+import type {
+  CredentialValidators,
+  ExecutionContext,
+  ProviderExecutors,
+  ProviderProxyExecutor,
+} from "../../core/types.ts";
 import type { AdobeCommerceActionName } from "./actions.ts";
 
 import {
@@ -11,6 +16,7 @@ import {
 } from "../../core/cast.ts";
 import { assertPublicHttpUrl } from "../../core/request.ts";
 import {
+  defineProviderProxy,
   defineProviderExecutors,
   providerUserAgent,
   ProviderRequestError,
@@ -134,6 +140,20 @@ export const executors: ProviderExecutors = defineProviderExecutors<AdobeCommerc
   },
 });
 
+export const proxy: ProviderProxyExecutor = defineProviderProxy({
+  service,
+  baseUrl: async (context) => {
+    const credential = await requireApiKeyCredential(context, service);
+    const baseUrl = normalizeAdobeCommerceBaseUrl(credential.metadata.baseUrl ?? credential.values.baseUrl);
+    const storeCode = normalizeOptionalStoreCode(credential.metadata.storeCode ?? credential.values.storeCode);
+    const url = new URL(baseUrl);
+    const segments = [...splitPathSegments(url.pathname), "rest", ...(storeCode ? [storeCode] : []), "V1"];
+    url.pathname = `/${segments.map((segment) => encodeURIComponent(segment)).join("/")}`;
+    return url.toString();
+  },
+  auth: { type: "api_key_authorization", prefix: "Bearer " },
+});
+
 export const credentialValidators: CredentialValidators = {
   async apiKey(input, { fetcher, signal }) {
     const baseUrl = normalizeAdobeCommerceBaseUrl(input.values.baseUrl);

src/providers/adyen/executors.ts

@@ -1,8 +1,14 @@
-import type { CredentialValidators, ExecutionContext, ProviderExecutors } from "../../core/types.ts";
+import type {
+  CredentialValidators,
+  ExecutionContext,
+  ProviderExecutors,
+  ProviderProxyExecutor,
+} from "../../core/types.ts";
 import type { AdyenActionName } from "./actions.ts";
 
 import { compactObject, nullableString, optionalInteger, optionalRecord, optionalString } from "../../core/cast.ts";
 import {
+  defineProviderProxy,
   defineProviderExecutors,
   providerUserAgent,
   ProviderRequestError,
@@ -69,6 +75,15 @@ export const executors: ProviderExecutors = defineProviderExecutors<AdyenActionC
   },
 });
 
+export const proxy: ProviderProxyExecutor = defineProviderProxy({
+  service,
+  baseUrl: async (context) => {
+    const credential = await requireApiKeyCredential(context, service);
+    return buildAdyenApiBaseUrl(readStoredEnvironment(credential.values, credential.metadata));
+  },
+  auth: { type: "api_key_header", name: "x-api-key" },
+});
+
 export const credentialValidators: CredentialValidators = {
   async apiKey(input, { fetcher, signal }) {
     const environment = normalizeAdyenEnvironment(input.values.environment);

src/providers/agora/executors.ts

@@ -1,7 +1,24 @@
-import type { CredentialValidators, ExecutionContext, ProviderExecutors } from "../../core/types.ts";
+import type {
+  CredentialValidators,
+  ExecutionContext,
+  ProviderExecutors,
+  ProviderProxyExecutor,
+  ProxyExecutionResult,
+} from "../../core/types.ts";
 
-import { defineProviderExecutors, requireApiKeyCredential } from "../provider-runtime.ts";
-import { agoraActionHandlers, readAgoraCustomerId, validateAgoraCredential } from "./runtime.ts";
+import { Buffer } from "node:buffer";
+import {
+  createProviderProxyUrl,
+  defineProviderExecutors,
+  normalizeProviderProxyHeaders,
+  providerUserAgent,
+  ProviderRequestError,
+  readProviderProxyErrorMessage,
+  readProviderProxyResponse,
+  requireApiKeyCredential,
+  toProviderProxyError,
+} from "../provider-runtime.ts";
+import { agoraActionHandlers, agoraApiBaseUrl, readAgoraCustomerId, validateAgoraCredential } from "./runtime.ts";
 
 const service = "agora";
 
@@ -19,6 +36,35 @@ export const executors: ProviderExecutors = defineProviderExecutors({
   },
 });
 
+export const proxy: ProviderProxyExecutor = async (input, context): Promise<ProxyExecutionResult> => {
+  try {
+    const credential = await requireApiKeyCredential(context, service);
+    const customerId = readAgoraCustomerId(credential.values);
+    const url = createProviderProxyUrl(agoraApiBaseUrl, input.endpoint, input.query);
+    const headers = normalizeProviderProxyHeaders(input.headers);
+    headers.set("authorization", `Basic ${Buffer.from(`${customerId}:${credential.apiKey}`).toString("base64")}`);
+    headers.set("user-agent", providerUserAgent);
+    if (input.body !== undefined && !headers.has("content-type") && typeof input.body !== "string") {
+      headers.set("content-type", "application/json");
+    }
+
+    const response = await fetch(url, {
+      method: input.method,
+      headers,
+      body:
+        input.body === undefined ? undefined : typeof input.body === "string" ? input.body : JSON.stringify(input.body),
+      signal: context.signal,
+    });
+    if (!response.ok) {
+      const text = await readProviderProxyErrorMessage(response, "");
+      throw new ProviderRequestError(response.status, text || `provider request failed with HTTP ${response.status}`);
+    }
+    return { ok: true, response: await readProviderProxyResponse(response) };
+  } catch (error) {
+    return toProviderProxyError(error, "provider request failed");
+  }
+};
+
 export const credentialValidators: CredentialValidators = {
   async apiKey(input, { fetcher, signal }) {
     return validateAgoraCredential(