@oomol-lab/open-connector 1.9.0 → 1.9.2

package/src/server/api/policy-routes.d.ts

@@ -0,0 +1,13 @@
+import type { ActionPolicySnapshot } from "../../core/action-policy.ts";
+import type { IRuntimePolicyStore } from "../storage/runtime-policy-store.ts";
+import type { RuntimeTokenService } from "../storage/runtime-token-service.ts";
+import type { Context } from "hono";
+import { Hono } from "hono";
+export interface PolicyRoutesOptions {
+    runtimeTokens: RuntimeTokenService;
+    runtimePolicyStore: IRuntimePolicyStore;
+    deploymentPolicyRules: unknown;
+    getPolicySnapshot: (context: Context) => Promise<ActionPolicySnapshot>;
+}
+/** Runtime token management and runtime policy administration routes. */
+export declare function createPolicyRoutes({ runtimeTokens, runtimePolicyStore, deploymentPolicyRules, getPolicySnapshot, }: PolicyRoutesOptions): Hono;

package/src/server/api/policy-routes.js

@@ -0,0 +1,50 @@
+import { Hono } from "hono";
+import { optionalString } from "../../core/cast.js";
+import { summarizeRuntimeToken } from "../storage/runtime-token-service.js";
+import { jsonError, readJsonBody } from "./http-utils.js";
+import { policyRequestMaxBytes, readRuntimePolicyRules, readTokenPolicy } from "./policy-input.js";
+/** Runtime token management and runtime policy administration routes. */
+export function createPolicyRoutes({ runtimeTokens, runtimePolicyStore, deploymentPolicyRules, getPolicySnapshot, }) {
+    const app = new Hono();
+    app.get("/runtime-tokens", async (context) => context.json(await runtimeTokens.listTokens()));
+    app.post("/runtime-tokens", async (context) => {
+        const body = await readJsonBody(context, policyRequestMaxBytes);
+        const name = optionalString(body.name);
+        if (!name) {
+            return jsonError(context, 400, "invalid_input", "name is required.");
+        }
+        const created = await runtimeTokens.createToken(name, readTokenPolicy(body, true));
+        return context.json({
+            token: created.token,
+            record: summarizeRuntimeToken(created.record),
+        });
+    });
+    app.put("/runtime-tokens/:id", async (context) => {
+        const id = context.req.param("id");
+        const body = await readJsonBody(context, policyRequestMaxBytes);
+        const token = await runtimeTokens.updateTokenPolicy(id, readTokenPolicy(body));
+        return token
+            ? context.json(token)
+            : jsonError(context, 404, "runtime_token_not_found", `Runtime token not found: ${id}.`);
+    });
+    app.delete("/runtime-tokens/:id", async (context) => {
+        const id = context.req.param("id");
+        if (!(await runtimeTokens.revokeToken(id))) {
+            return jsonError(context, 404, "runtime_token_not_found", `Runtime token not found: ${id}.`);
+        }
+        return context.json({ id, revoked: true });
+    });
+    app.get("/runtime-policy", async (context) => context.json((await getPolicySnapshot(context)).state));
+    app.put("/runtime-policy", async (context) => {
+        const body = await readJsonBody(context, policyRequestMaxBytes);
+        const rules = readRuntimePolicyRules(body);
+        const updatedAt = new Date().toISOString();
+        await runtimePolicyStore.set({ rules, updatedAt });
+        return context.json({
+            deployment: deploymentPolicyRules,
+            runtime: rules,
+            updatedAt,
+        });
+    });
+    return app;
+}

package/src/server/api/policy-snapshot.d.ts

@@ -0,0 +1,14 @@
+import type { ActionPolicyService, ActionPolicySnapshot } from "../../core/action-policy.ts";
+import type { RuntimeLogger } from "../../core/types.ts";
+import type { IRuntimePolicyStore } from "../storage/runtime-policy-store.ts";
+import type { Context } from "hono";
+export interface PolicySnapshotProviderOptions {
+    actionPolicy: ActionPolicyService;
+    runtimePolicyStore: IRuntimePolicyStore;
+    logger?: RuntimeLogger;
+}
+export type PolicySnapshotProvider = (context: Context) => Promise<ActionPolicySnapshot>;
+/**
+ * Creates a request-scoped cached ActionPolicySnapshot provider backed by a WeakMap.
+ */
+export declare function createPolicySnapshotProvider({ actionPolicy, runtimePolicyStore, logger, }: PolicySnapshotProviderOptions): PolicySnapshotProvider;

package/src/server/api/policy-snapshot.js

@@ -0,0 +1,30 @@
+import { emptyPolicyRules } from "../../core/action-policy.js";
+import { readRuntimeGrant } from "./auth.js";
+/**
+ * Creates a request-scoped cached ActionPolicySnapshot provider backed by a WeakMap.
+ */
+export function createPolicySnapshotProvider({ actionPolicy, runtimePolicyStore, logger, }) {
+    const policySnapshots = new WeakMap();
+    async function loadPolicySnapshot(context) {
+        try {
+            const record = await runtimePolicyStore.get();
+            return actionPolicy.createSnapshot(record?.rules ?? emptyPolicyRules(), readRuntimeGrant(context), record?.updatedAt);
+        }
+        catch {
+            logger?.error({
+                method: context.req.method,
+                path: context.req.path,
+            }, "runtime policy load failed");
+            throw new Error("Runtime policy is unavailable.");
+        }
+    }
+    return (context) => {
+        const request = context.req.raw;
+        let snapshot = policySnapshots.get(request);
+        if (!snapshot) {
+            snapshot = loadPolicySnapshot(context);
+            policySnapshots.set(request, snapshot);
+        }
+        return snapshot;
+    };
+}

package/src/server/api/run-log-routes.d.ts

@@ -0,0 +1,7 @@
+import type { ActionRunner } from "../actions/action-runner.ts";
+import { Hono } from "hono";
+export interface RunLogRoutesOptions {
+    actions: ActionRunner;
+}
+/** Action execution run log query and inspection routes. */
+export declare function createRunLogRoutes({ actions }: RunLogRoutesOptions): Hono;

package/src/server/api/run-log-routes.js

@@ -0,0 +1,70 @@
+import { Hono } from "hono";
+import { optionalString } from "../../core/cast.js";
+import { decodeRunLogCursor } from "../storage/runtime-store.js";
+import { jsonError } from "./http-utils.js";
+function isRunLogCaller(value) {
+    return value === "http" || value === "mcp" || value === "web";
+}
+function readRunLogListInput(context) {
+    const rawLimit = optionalString(context.req.query("limit"));
+    const limit = rawLimit === undefined ? 50 : Number(rawLimit);
+    if (!Number.isInteger(limit) || limit < 1 || limit > 100) {
+        return { ok: false, message: "limit must be an integer between 1 and 100." };
+    }
+    const cursor = optionalString(context.req.query("cursor"));
+    if (cursor !== undefined) {
+        try {
+            decodeRunLogCursor(cursor);
+        }
+        catch {
+            return { ok: false, message: "cursor is invalid." };
+        }
+    }
+    const input = { limit };
+    if (cursor !== undefined) {
+        input.cursor = cursor;
+    }
+    const service = optionalString(context.req.query("service"));
+    if (service !== undefined) {
+        input.service = service;
+    }
+    const actionId = optionalString(context.req.query("actionId"));
+    if (actionId !== undefined) {
+        if (actionId.length > 256) {
+            return { ok: false, message: "actionId must be at most 256 characters." };
+        }
+        input.actionId = actionId;
+    }
+    const caller = optionalString(context.req.query("caller"));
+    if (caller !== undefined) {
+        if (!isRunLogCaller(caller)) {
+            return { ok: false, message: "caller must be one of http, mcp, or web." };
+        }
+        input.caller = caller;
+    }
+    const ok = optionalString(context.req.query("ok"));
+    if (ok !== undefined) {
+        if (ok !== "true" && ok !== "false") {
+            return { ok: false, message: "ok must be true or false." };
+        }
+        input.ok = ok === "true";
+    }
+    return { ok: true, input };
+}
+/** Action execution run log query and inspection routes. */
+export function createRunLogRoutes({ actions }) {
+    const app = new Hono();
+    app.get("/runs", async (context) => {
+        const query = readRunLogListInput(context);
+        if (!query.ok) {
+            return jsonError(context, 400, "invalid_input", query.message);
+        }
+        return context.json(await actions.listRuns(query.input));
+    });
+    app.get("/runs/:id", async (context) => {
+        const id = context.req.param("id");
+        const run = await actions.getRun(id);
+        return run ? context.json(run) : jsonError(context, 404, "run_not_found", `Run not found: ${id}.`);
+    });
+    return app;
+}

package/src/server/api/runtime-api.d.ts

@@ -114,13 +114,6 @@ export declare function parseRuntimeActionHttpResult(value: unknown): RuntimeAct
  */
 export declare function writeRuntimeActionHttpResult(context: Context, result: RuntimeActionHttpResult): Response;
 export declare function mapConnectionErrorStatus(error: ConnectionError): 400 | 404 | 409;
-/**
- * The error codes a provider may put in `ProviderRequestError`'s `code`
- * argument. Every other code `mapExecutionErrorStatus` knows is raised by the
- * connection, policy or dispatch layer, and a provider that borrowed one would
- * answer with a status that has nothing to do with what its upstream said.
- */
-export declare const providerErrorCodes: readonly string[];
 /** Management view adds stored account metadata without exposing credentials. */
 export declare function serializeManagedConnection(connection: ManagedConnectionSummary): Omit<RuntimeConnectedApp, "status"> & {
     status: ManagedConnectionSummary["status"];

package/src/server/api/runtime-api.js

@@ -166,19 +166,6 @@ export function mapConnectionErrorStatus(error) {
     }
     return 400;
 }
-/**
- * The error codes a provider may put in `ProviderRequestError`'s `code`
- * argument. Every other code `mapExecutionErrorStatus` knows is raised by the
- * connection, policy or dispatch layer, and a provider that borrowed one would
- * answer with a status that has nothing to do with what its upstream said.
- */
-export const providerErrorCodes = [
-    "authorization_failed",
-    "insufficient_credit",
-    "invalid_input",
-    "provider_error",
-    "rate_limited",
-];
 function mapExecutionErrorStatus(code, details) {
     const upstreamStatus = optionalInteger(optionalRecord(details)?.status);
     if (upstreamStatus === 413) {

package/src/server/api/runtime-app-routes.d.ts

@@ -0,0 +1,10 @@
+import type { ConnectionService } from "../../connection-service.ts";
+import type { ActionPolicySnapshot } from "../../core/action-policy.ts";
+import type { Context } from "hono";
+import { Hono } from "hono";
+export interface RuntimeAppRoutesOptions {
+    connections: ConnectionService;
+    getPolicySnapshot: (context: Context) => Promise<ActionPolicySnapshot>;
+}
+/** Connected runtime apps discovery and permission evaluation routes. */
+export declare function createRuntimeAppRoutes({ connections, getPolicySnapshot }: RuntimeAppRoutesOptions): Hono;

package/src/server/api/runtime-app-routes.js

@@ -0,0 +1,72 @@
+import { Hono } from "hono";
+import { ConnectionError } from "../../connection-service.js";
+import { mapConnectionErrorStatus, serializeRuntimeConnectedApp, writeRuntimeFailure, writeRuntimeSuccess, } from "./runtime-api.js";
+function filterAllowedConnections(policy, connections) {
+    return connections.filter((connection) => connection.authType === "no_auth" || policy.evaluateConnection(connection.id).allowed);
+}
+/** Connected runtime apps discovery and permission evaluation routes. */
+export function createRuntimeAppRoutes({ connections, getPolicySnapshot }) {
+    const app = new Hono();
+    app.get("/apps", async (context) => {
+        let policy;
+        try {
+            policy = await getPolicySnapshot(context);
+        }
+        catch {
+            return writeRuntimeFailure(context, {
+                status: 500,
+                errorCode: "internal_error",
+                message: "Runtime policy is unavailable.",
+            });
+        }
+        return writeRuntimeSuccess(context, filterAllowedConnections(policy, await connections.listConnections()).map(serializeRuntimeConnectedApp));
+    });
+    app.get("/apps/authenticated", async (context) => {
+        const services = context.req.queries("service") ?? [];
+        let policy;
+        try {
+            policy = await getPolicySnapshot(context);
+        }
+        catch {
+            return writeRuntimeFailure(context, {
+                status: 500,
+                errorCode: "internal_error",
+                message: "Runtime policy is unavailable.",
+            });
+        }
+        const authenticated = new Set(filterAllowedConnections(policy, await connections.listConnections())
+            .filter((connection) => connection.configured && connection.authType !== "no_auth")
+            .map((connection) => connection.service));
+        return writeRuntimeSuccess(context, services.filter((service) => authenticated.has(service)));
+    });
+    app.get("/apps/services/:service", async (context) => {
+        const service = context.req.param("service");
+        let policy;
+        try {
+            policy = await getPolicySnapshot(context);
+        }
+        catch {
+            return writeRuntimeFailure(context, {
+                status: 500,
+                errorCode: "internal_error",
+                message: "Runtime policy is unavailable.",
+                meta: { service },
+            });
+        }
+        try {
+            return writeRuntimeSuccess(context, filterAllowedConnections(policy, await connections.listConnectionsByService(service)).map(serializeRuntimeConnectedApp));
+        }
+        catch (error) {
+            if (error instanceof ConnectionError) {
+                return writeRuntimeFailure(context, {
+                    status: mapConnectionErrorStatus(error),
+                    errorCode: error.code,
+                    message: error.message,
+                    meta: { service },
+                });
+            }
+            throw error;
+        }
+    });
+    return app;
+}

package/src/server/api/runtime-catalog-routes.d.ts

@@ -0,0 +1,37 @@
+import type { CatalogStore, RuntimeActionDefinition } from "../../catalog-store.ts";
+import type { ConnectionService } from "../../connection-service.ts";
+import type { ActionSearchDocument, ActionSearchIndexProvider } from "../../core/action-search.ts";
+import type { OAuthClientConfigService } from "../../oauth/oauth-client-config-service.ts";
+import type { SaasProjectService } from "../../saas/saas-project-service.ts";
+import type { Context } from "hono";
+import { Hono } from "hono";
+export interface RuntimeActionSearchResult {
+    id: string;
+    service: string;
+    name: string;
+    description: string;
+    operationType: RuntimeActionDefinition["operationType"];
+    authenticated: boolean;
+    inputSchema: RuntimeActionDefinition["inputSchema"];
+    outputSchema: RuntimeActionDefinition["outputSchema"];
+}
+export declare function serializeActionSearchResult(result: ActionSearchDocument, action: RuntimeActionDefinition, authenticated: boolean): RuntimeActionSearchResult;
+export type SearchQuery = {
+    ok: true;
+    q: string;
+    service?: string;
+    limit: number;
+} | {
+    ok: false;
+    message: string;
+};
+export declare function readSearchQuery(context: Context, defaultLimit?: number): SearchQuery;
+export interface RuntimeCatalogRoutesOptions {
+    catalog: CatalogStore;
+    connections: ConnectionService;
+    actionSearch: ActionSearchIndexProvider;
+    oauthClientConfigs: OAuthClientConfigService;
+    saasProject?: SaasProjectService;
+}
+/** Provider and action discovery, inspection and search routes under /v1. */
+export declare function createRuntimeCatalogRoutes({ catalog, connections, actionSearch, oauthClientConfigs, saasProject, }: RuntimeCatalogRoutesOptions): Hono;

package/src/server/api/runtime-catalog-routes.js

@@ -0,0 +1,133 @@
+import { Hono } from "hono";
+import { DEFAULT_ACTION_SEARCH_LIMIT, searchActions } from "../../core/action-search.js";
+import { optionalString } from "../../core/cast.js";
+import { serializeRuntimeAction, serializeRuntimeActionService, serializeRuntimeProvider, serializeRuntimeProviderSetup, unknownActionFailure, unknownServiceFailure, writeRuntimeFailure, writeRuntimeSuccess, } from "./runtime-api.js";
+export function serializeActionSearchResult(result, action, authenticated) {
+    return {
+        id: result.id,
+        service: result.service,
+        name: result.name,
+        description: result.description,
+        operationType: action.operationType,
+        authenticated,
+        inputSchema: action.inputSchema,
+        outputSchema: action.outputSchema,
+    };
+}
+export function readSearchQuery(context, defaultLimit = DEFAULT_ACTION_SEARCH_LIMIT) {
+    const q = optionalString(context.req.query("q") ?? context.req.query("query"));
+    if (!q || q.length > 256) {
+        return { ok: false, message: "q must be a non-empty string of at most 256 characters." };
+    }
+    const rawLimit = optionalString(context.req.query("limit"));
+    if (!rawLimit) {
+        return {
+            ok: true,
+            q,
+            service: optionalString(context.req.query("service")),
+            limit: defaultLimit,
+        };
+    }
+    const limit = Number(rawLimit);
+    if (!Number.isInteger(limit) || limit < 1 || limit > 50) {
+        return { ok: false, message: "limit must be an integer between 1 and 50." };
+    }
+    return {
+        ok: true,
+        q,
+        service: optionalString(context.req.query("service")),
+        limit,
+    };
+}
+/** Provider and action discovery, inspection and search routes under /v1. */
+export function createRuntimeCatalogRoutes({ catalog, connections, actionSearch, oauthClientConfigs, saasProject, }) {
+    const app = new Hono();
+    const serializeSearchResults = async (results) => {
+        const authenticated = new Set(await connections.listAuthenticatedServices([...new Set(results.map((result) => result.service))]));
+        return results.flatMap((result) => {
+            const action = catalog.actionsById.get(result.id);
+            if (!action) {
+                return [];
+            }
+            return [serializeActionSearchResult(result, action, authenticated.has(action.service))];
+        });
+    };
+    app.get("/providers/:service/setup", async (context) => {
+        const service = context.req.param("service");
+        const provider = catalog.providers.find((p) => p.service === service);
+        if (!provider)
+            return writeRuntimeFailure(context, unknownServiceFailure(service));
+        let oauth = provider.auth.some((auth) => auth.type === "oauth2")
+            ? await oauthClientConfigs.getSummary(service)
+            : undefined;
+        const source = oauth ? await saasProject?.getSource(service) : undefined;
+        if (oauth && source?.mode === "saas") {
+            const { config } = await saasProject.resolveConfig(service, source.providerConfigId, source.managedProjectId, context.req.raw.signal);
+            oauth = {
+                ...oauth,
+                configured: true,
+                customClientAvailable: false,
+                expectedRedirectUri: config.callbackUrl,
+                missingFields: [],
+            };
+        }
+        return writeRuntimeSuccess(context, serializeRuntimeProviderSetup(provider, oauth));
+    });
+    app.get("/providers", (context) => {
+        const services = context.req.queries("service") ?? [];
+        const query = optionalString(context.req.query("q"))?.toLowerCase();
+        const providers = catalog.providers.filter((provider) => {
+            if (services.length > 0 && !services.includes(provider.service)) {
+                return false;
+            }
+            if (!query) {
+                return true;
+            }
+            return [
+                provider.service,
+                provider.displayName,
+                provider.categories.join(" "),
+                provider.scenario,
+                provider.authTypes.join(" "),
+            ]
+                .join(" ")
+                .toLowerCase()
+                .includes(query);
+        });
+        return writeRuntimeSuccess(context, providers.map(serializeRuntimeProvider));
+    });
+    app.get("/actions", (context) => {
+        const service = optionalString(context.req.query("service"));
+        if (!service) {
+            const services = [...new Set(catalog.actions.map((action) => action.service))];
+            return writeRuntimeSuccess(context, services.map(serializeRuntimeActionService));
+        }
+        const actions = catalog.actions.filter((action) => action.service === service);
+        return writeRuntimeSuccess(context, actions.map(serializeRuntimeAction));
+    });
+    app.get("/actions/search", async (context) => {
+        const query = readSearchQuery(context, 10);
+        if (!query.ok) {
+            return writeRuntimeFailure(context, {
+                status: 400,
+                errorCode: "invalid_input",
+                message: query.message,
+            });
+        }
+        const index = await actionSearch.get();
+        const results = searchActions(index, query.q, {
+            service: query.service,
+            limit: query.limit,
+        });
+        return writeRuntimeSuccess(context, await serializeSearchResults(results));
+    });
+    app.get("/actions/:actionId", (context) => {
+        const actionId = context.req.param("actionId");
+        const action = catalog.actionsById.get(actionId);
+        if (!action) {
+            return writeRuntimeFailure(context, unknownActionFailure(actionId));
+        }
+        return writeRuntimeSuccess(context, serializeRuntimeAction(action));
+    });
+    return app;
+}

package/src/server/api/runtime-execution-routes.d.ts

@@ -0,0 +1,16 @@
+import type { CatalogStore } from "../../catalog-store.ts";
+import type { ActionPolicySnapshot } from "../../core/action-policy.ts";
+import type { ActionRunner } from "../actions/action-runner.ts";
+import type { ProxyRunner } from "../proxy/proxy-runner.ts";
+import type { IIdempotencyStore } from "../storage/idempotency-store.ts";
+import type { Context } from "hono";
+import { Hono } from "hono";
+export interface RuntimeExecutionRoutesOptions {
+    catalog: CatalogStore;
+    actions: ActionRunner;
+    idempotency: IIdempotencyStore;
+    proxyRunner: ProxyRunner;
+    getPolicySnapshot: (context: Context) => Promise<ActionPolicySnapshot>;
+}
+/** Action execution and proxy dispatch routes under /v1. */
+export declare function createRuntimeExecutionRoutes({ catalog, actions, idempotency, proxyRunner, getPolicySnapshot, }: RuntimeExecutionRoutesOptions): Hono;