@oomol-lab/open-connector 1.9.1 → 1.9.3

package/src/server/connect-server.js

@@ -4,6 +4,7 @@ import { ActionPolicyService } from "../core/action-policy.js";
 import { createActionSearchIndexProvider } from "../core/action-search.js";
 import { optionalRecord } from "../core/cast.js";
 import { withProviderHttpDispatch } from "../core/provider-http-dispatch.js";
+import { withProviderNetworkPolicy } from "../core/provider-network-policy.js";
 import { ProviderDispatchRequestError, toProviderExecutionError } from "../providers/provider-runtime.js";
 import { SaasError } from "../saas/saas-client.js";
 import { ActionRunner } from "./actions/action-runner.js";
@@ -28,6 +29,7 @@ import { createSaasProjectRoutes } from "./api/saas-project-routes.js";
 import { createTransitFileRoutes } from "./api/transit-file-routes.js";
 import { createTriggerRoutes } from "./api/trigger-routes.js";
 import { ProxyRunner } from "./proxy/proxy-runner.js";
+import { readSlackEventRequestBody, verifySlackEventRequest } from "./slack-event-verification.js";
 /**
  * Import and evaluate the modules the /mcp and /docs routes defer to their first request. The Node server never
  * calls this, so its startup graph stays small; Cloudflare Workers call it at app creation so an isolate keeps
@@ -68,7 +70,7 @@ export class ConnectServer {
         const app = new Hono();
         const auth = this.options.auth ?? {};
         app.use("*", async (_context, next) => {
-            await withProviderHttpDispatch({ operation: "runtime" }, next, this.options.providerHttpDispatch);
+            await withProviderNetworkPolicy(this.options.network ?? {}, () => withProviderHttpDispatch({ operation: "runtime" }, next, this.options.providerHttpDispatch));
         });
         app.use("*", async (context, next) => {
             await next();
@@ -92,6 +94,84 @@ export class ConnectServer {
             app.use("/api/*", compress());
         }
         app.use("*", createLocalAuthMiddleware(auth));
+        // Inbound provider event verification. This route authenticates with a dedicated token
+        // so a host ingress can delegate signature verification without receiving the admin token.
+        app.post("/v1/providers/slackbot/events/verify", async (context) => {
+            const expected = this.options.eventVerifyToken?.trim();
+            if (!expected)
+                return writeRuntimeFailure(context, {
+                    status: 404,
+                    errorCode: "event_verification_disabled",
+                    message: "Event verification is disabled.",
+                });
+            const authorization = context.req.header("authorization") ?? "";
+            const provided = authorization.startsWith("Bearer ") ? authorization.slice(7).trim() : "";
+            if (!(await sameSecret(provided, expected)))
+                return writeRuntimeFailure(context, {
+                    status: 401,
+                    errorCode: "unauthorized",
+                    message: "A valid event verification token is required.",
+                });
+            const config = await this.options.oauthClientConfigs.getConfig("slackbot");
+            const appId = String(config?.extra?.appId ?? "").trim();
+            const signingSecret = String(config?.secretExtra?.signingSecret ?? "").trim();
+            if (!appId || !signingSecret)
+                return writeRuntimeFailure(context, {
+                    status: 409,
+                    errorCode: "event_verification_not_configured",
+                    message: "Configure the default Slack App ID and Signing Secret.",
+                });
+            const rawBody = await readSlackEventRequestBody(context.req.raw);
+            if (!rawBody)
+                return writeRuntimeFailure(context, {
+                    status: 413,
+                    errorCode: "webhook_request_too_large",
+                    message: "Slack request body exceeds 64 KiB.",
+                });
+            const result = await verifySlackEventRequest({
+                timestamp: context.req.header("x-slack-request-timestamp") ?? "",
+                signature: context.req.header("x-slack-signature") ?? "",
+                rawBody,
+                configuredAppId: appId,
+                signingSecret,
+                contentType: context.req.header("content-type") ?? "",
+            });
+            if (!result.valid) {
+                switch (result.reason) {
+                    case "body_too_large":
+                        return writeRuntimeFailure(context, {
+                            status: 413,
+                            errorCode: "webhook_request_too_large",
+                            message: "Slack request body exceeds 64 KiB.",
+                        });
+                    case "payload":
+                        return writeRuntimeFailure(context, {
+                            status: 400,
+                            errorCode: "invalid_event_payload",
+                            message: "Invalid Slack event envelope.",
+                        });
+                    case "app":
+                        return writeRuntimeFailure(context, {
+                            status: 403,
+                            errorCode: "webhook_app_mismatch",
+                            message: "Slack App ID does not match the configured application.",
+                        });
+                    case "timestamp":
+                        return writeRuntimeFailure(context, {
+                            status: 401,
+                            errorCode: "invalid_webhook_timestamp",
+                            message: "Invalid or expired Slack request timestamp.",
+                        });
+                    case "signature":
+                        return writeRuntimeFailure(context, {
+                            status: 401,
+                            errorCode: "invalid_webhook_signature",
+                            message: "Invalid Slack request signature.",
+                        });
+                }
+            }
+            return writeRuntimeSuccess(context, result);
+        });
         // Health and runtime discovery / execution endpoints
         app.get("/v1/health", (context) => writeRuntimeSuccess(context, { ok: true, runtime: "oomol-connect" }));
         app.route("/v1", createRuntimeCatalogRoutes({
@@ -162,7 +242,10 @@ export class ConnectServer {
             app.route("/api", createSaasProjectRoutes({ saasProject: saas }));
         }
         if (saas && this.options.saasOAuth) {
-            app.route("/", createSaasOAuthRoutes({ saasProject: saas, saasOAuth: this.options.saasOAuth }));
+            app.route("/", createSaasOAuthRoutes({
+                saasProject: saas,
+                saasOAuth: this.options.saasOAuth,
+            }));
         }
         app.route("/", createConsoleOAuthRoutes({
             connections: this.options.connections,
@@ -171,6 +254,7 @@ export class ConnectServer {
             saasProject: this.options.saasProject,
             logger: this.options.logger,
             oauthCloseDelaySeconds: this.options.oauthCloseDelaySeconds,
+            oauthResultOrigins: this.options.oauthResultOrigins,
         }));
         // Without a console the API owns every unknown path; a console host layers its fallback over these 404s.
         if (this.options.registerStaticRoutes)
@@ -202,8 +286,18 @@ export class ConnectServer {
                 if (error.retryAfter)
                     context.header("Retry-After", error.retryAfter);
                 if (context.req.path.startsWith("/v1/"))
-                    return writeRuntimeFailure(context, { status: error.status, errorCode: error.code, message: error.message });
-                return context.json({ error: { code: error.code, message: error.message, reason: error.reason } }, error.status);
+                    return writeRuntimeFailure(context, {
+                        status: error.status,
+                        errorCode: error.code,
+                        message: error.message,
+                    });
+                return context.json({
+                    error: {
+                        code: error.code,
+                        message: error.message,
+                        reason: error.reason,
+                    },
+                }, error.status);
             }
             if (error instanceof HttpRequestError) {
                 if (context.req.path.startsWith("/v1/")) {
@@ -232,3 +326,19 @@ export class ConnectServer {
         return app;
     }
 }
+/** Hash both values before a constant-time comparison so length never leaks. */
+async function sameSecret(provided, expected) {
+    if (!provided || !expected)
+        return false;
+    const encoder = new TextEncoder();
+    const [left, right] = await Promise.all([
+        crypto.subtle.digest("SHA-256", encoder.encode(provided)),
+        crypto.subtle.digest("SHA-256", encoder.encode(expected)),
+    ]);
+    const a = new Uint8Array(left);
+    const b = new Uint8Array(right);
+    let difference = 0;
+    for (let index = 0; index < a.length; index += 1)
+        difference |= a[index] ^ b[index];
+    return difference === 0;
+}

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

@@ -1,5 +1,6 @@
 import type { ActionPolicyConfig } from "../core/action-policy.ts";
 import type { ProviderHttpDispatchOptions } from "../core/provider-http-dispatch.ts";
+import type { ProviderNetworkPolicy } from "../core/provider-network-policy.ts";
 import type { RuntimeLogger } from "../core/types.ts";
 import type { RuntimeJwtConfig } from "./api/runtime-jwt.ts";
 import type { S3TransitClientOptions } from "./files/s3-transit-files.ts";
@@ -20,13 +21,6 @@ export interface ConnectorPostgresOptions {
     /** Time allowed to establish one connection. */
     connectionTimeoutMs?: number;
 }
-/** Provider egress policy. It is process-wide, which is why one runtime may be active per process. */
-export interface ConnectorNetworkOptions {
-    /** Let self-hosted providers reach instance hosts on private networks; loopback, link-local and cloud metadata stay blocked. */
-    allowPrivateNetwork?: boolean;
-    /** Hosts exempt from resolved-address validation, for domains a corporate VPN resolves to placeholder addresses. */
-    trustedHosts?: readonly string[];
-}
 export interface ConnectorS3Options extends S3TransitClientOptions {
     bucket: string;
 }
@@ -53,10 +47,12 @@ export interface ConnectorRuntimeOptions {
     adminToken?: string;
     /** Static bearer token for the /v1 and /mcp execution API. JWT verification and console-issued tokens are the alternatives. */
     runtimeToken?: string;
+    /** Dedicated bearer token for inbound provider event verification. Kept separate from the admin token. */
+    eventVerifyToken?: string;
     /** Verify /v1 bearer tokens as JWTs against a JWKS endpoint. */
     jwt?: RuntimeJwtConfig;
     postgres?: ConnectorPostgresOptions;
-    network?: ConnectorNetworkOptions;
+    network?: ProviderNetworkPolicy;
     /** Opt-in admission and result feedback for every provider HTTP transport attempt. */
     providerHttpDispatch?: ProviderHttpDispatchOptions;
     /** Allow or block actions, proxies and Triggers by name. */
@@ -78,6 +74,8 @@ export interface ConnectorRuntimeOptions {
     apiReference?: boolean;
     /** Seconds the OAuth completion page waits before closing its window. Defaults to 5; `0` closes it as soon as it loads. */
     oauthCloseDelaySeconds?: number;
+    /** Exact origins a provider-refusal callback page may post its result to. Never `*`. */
+    oauthResultOrigins?: string[];
 }
 /** Standard web requests are the host boundary; credentials, databases and framework objects stay private. */
 export interface ConnectorRuntime {

package/src/server/connector-runtime.js

@@ -2,10 +2,9 @@ import { mkdir } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import { loadCatalog } from "../catalog-store.js";
 import { ActionPolicyService } from "../core/action-policy.js";
-import { setEgressTrustedHosts, setPrivateNetworkAccessAllowed } from "../core/request.js";
 import { ProviderLoader } from "../providers/provider-loader.js";
 import { executorModules } from "../providers/registry.generated.js";
-import { DEFAULT_OAUTH_CLOSE_DELAY_SECONDS } from "./api/oauth-completion-page.js";
+import { DEFAULT_OAUTH_CLOSE_DELAY_SECONDS, normalizeOAuthResultOrigins } from "./api/oauth-completion-page.js";
 import { createRuntimeJwtVerifier } from "./api/runtime-jwt.js";
 import { createConnectApp } from "./connect-app.js";
 import { getConnectorAssetDirectory } from "./connector-assets.js";
@@ -15,22 +14,9 @@ import { createSecretCodec } from "./secrets/secret-codec.js";
 import { createDirectoryMigrationSource } from "./storage/migration-source.js";
 import { createNodeRuntimeDatabase } from "./storage/node-runtime-database.js";
 import { DEFAULT_RUN_LIMIT } from "./storage/runtime-store.js";
-let runtimeActive = false;
 export { getConnectorAssetDirectory } from "./connector-assets.js";
 /** Create a headless runtime without opening a listener or installing process signal handlers. */
 export async function createConnectorRuntime(options) {
-    if (runtimeActive)
-        throw new Error("Only one Open Connector runtime may be active per process. Close it before creating another.");
-    runtimeActive = true;
-    try {
-        return await openRuntime(options);
-    }
-    catch (error) {
-        releaseRuntime();
-        throw error;
-    }
-}
-async function openRuntime(options) {
     const publicUrl = new URL(options.publicOrigin);
     if (!["http:", "https:"].includes(publicUrl.protocol) ||
         publicUrl.username ||
@@ -52,14 +38,15 @@ async function openRuntime(options) {
     const oauthCloseDelaySeconds = options.oauthCloseDelaySeconds ?? DEFAULT_OAUTH_CLOSE_DELAY_SECONDS;
     if (!Number.isInteger(oauthCloseDelaySeconds) || oauthCloseDelaySeconds < 0)
         throw new Error("oauthCloseDelaySeconds must be a non-negative integer of seconds.");
+    // The same rules as `OOMOL_CONNECT_OAUTH_RESULT_ORIGINS`: a host passing the option directly must not be able
+    // to make the refusal page post OAuth state to `*` or to a value that is not an origin.
+    const oauthResultOrigins = normalizeOAuthResultOrigins(options.oauthResultOrigins ?? []);
     const assetDirectory = getConnectorAssetDirectory();
     const assets = options.assets ?? {
         catalogDir: join(assetDirectory, "catalog/apps"),
         catalogIndexFile: join(assetDirectory, "catalog/apps-index.json"),
         migrationDirectory: join(assetDirectory, "migrations"),
     };
-    setPrivateNetworkAccessAllowed(options.network?.allowPrivateNetwork ?? false);
-    setEgressTrustedHosts(options.network?.trustedHosts ?? []);
     const secretCodec = createSecretCodec(options.encryptionKey);
     const verifyRuntimeJwt = await createRuntimeJwtVerifier(options.jwt ?? {});
     const lazySchemas = options.lazySchemas ?? true;
@@ -110,6 +97,7 @@ async function openRuntime(options) {
         await cleanupStagedTransitFiles(tempDir, ttlSeconds * 1000);
         const { app, runtimeAuthConfigured, saasCleanup, triggerMaintenance } = await createConnectApp({
             catalog,
+            network: options.network,
             providerLoader: new ProviderLoader(executorModules),
             providerHttpDispatch: options.providerHttpDispatch,
             runtimeDatabase: database,
@@ -120,12 +108,14 @@ async function openRuntime(options) {
             secretCodec,
             adminToken: options.adminToken,
             runtimeToken: options.runtimeToken,
+            eventVerifyToken: options.eventVerifyToken,
             verifyRuntimeJwt,
             actionPolicy: new ActionPolicyService(options.actionPolicy),
             allowedCustomOAuth: options.allowedCustomOAuth,
             logger: options.logger,
             serveDocumentation: options.apiReference ?? false,
             oauthCloseDelaySeconds,
+            oauthResultOrigins,
         });
         saasCleanup.start();
         triggerMaintenance.start();
@@ -156,12 +146,7 @@ async function openRuntime(options) {
                             await database.close();
                         }
                         finally {
-                            try {
-                                closeFiles();
-                            }
-                            finally {
-                                releaseRuntime();
-                            }
+                            closeFiles();
                         }
                     });
                 }
@@ -179,8 +164,3 @@ async function openRuntime(options) {
         throw error;
     }
 }
-function releaseRuntime() {
-    setPrivateNetworkAccessAllowed(false);
-    setEgressTrustedHosts([]);
-    runtimeActive = false;
-}

package/src/server/proxy/proxy-runner.js

@@ -1,4 +1,4 @@
-import { ConnectionError } from "../../connection-service.js";
+import { ConnectionError } from "../../connection-error.js";
 import { optionalInteger, optionalRecord, requiredRecord, requiredString } from "../../core/cast.js";
 import { withProviderHttpDispatch } from "../../core/provider-http-dispatch.js";
 import { ProviderDispatchRequestError, toProviderExecutionError, withProviderHttpDispatchResult, } from "../../providers/provider-runtime.js";

package/src/server/slack-event-verification.d.ts

@@ -0,0 +1,37 @@
+export interface SlackEventVerificationInput {
+    /** Value of the X-Slack-Request-Timestamp header. */
+    timestamp: string;
+    /** Value of the X-Slack-Signature header. */
+    signature: string;
+    /** Raw request body bytes; they must not be re-serialized. */
+    rawBody: Uint8Array;
+    /** App ID of the Slack application configured in this runtime. */
+    configuredAppId: string;
+    /** Signing secret of the Slack application configured in this runtime. */
+    signingSecret: string;
+    /** Request Content-Type. Form-urlencoded Slack interactions are verified without parsing. */
+    contentType?: string;
+    /** Current time in milliseconds; injectable for tests. */
+    now?: number;
+}
+export type SlackEventVerificationResult = {
+    valid: true;
+    appId: string;
+    challenge: string | null;
+} | {
+    valid: false;
+    reason: "signature" | "timestamp" | "payload" | "app" | "body_too_large";
+};
+/**
+ * Reads a request body without buffering more than the Slack event limit.
+ *
+ * Returns undefined when the request exceeds the limit. The actual stream size is
+ * enforced even when Content-Length is absent or understated.
+ */
+export declare function readSlackEventRequestBody(request: Request): Promise<Uint8Array | undefined>;
+/**
+ * Verifies the signature, timestamp window, and App ID of an inbound Slack request.
+ *
+ * Verification only: this function does not persist, deduplicate, or schedule events.
+ */
+export declare function verifySlackEventRequest(input: SlackEventVerificationInput): Promise<SlackEventVerificationResult>;

package/src/server/slack-event-verification.js

@@ -0,0 +1,91 @@
+import { verifySlackSignature } from "../triggers/sources/slack-signature.js";
+/** Maximum request body size, consistent with existing event sources. */
+const slackEventMaximumBodyBytes = 64 * 1024;
+/**
+ * Reads a request body without buffering more than the Slack event limit.
+ *
+ * Returns undefined when the request exceeds the limit. The actual stream size is
+ * enforced even when Content-Length is absent or understated.
+ */
+export async function readSlackEventRequestBody(request) {
+    const declaredLength = request.headers.get("content-length");
+    if (declaredLength && /^\d+$/.test(declaredLength) && Number(declaredLength) > slackEventMaximumBodyBytes) {
+        return undefined;
+    }
+    if (!request.body)
+        return new Uint8Array();
+    const reader = request.body.getReader();
+    const chunks = [];
+    let totalBytes = 0;
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            if (!value)
+                continue;
+            totalBytes += value.byteLength;
+            if (totalBytes > slackEventMaximumBodyBytes) {
+                await reader.cancel().catch(() => undefined);
+                return undefined;
+            }
+            chunks.push(value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    const body = new Uint8Array(totalBytes);
+    let offset = 0;
+    for (const chunk of chunks) {
+        body.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return body;
+}
+/**
+ * Verifies the signature, timestamp window, and App ID of an inbound Slack request.
+ *
+ * Verification only: this function does not persist, deduplicate, or schedule events.
+ */
+export async function verifySlackEventRequest(input) {
+    const now = input.now ?? Date.now();
+    if (input.rawBody.byteLength > slackEventMaximumBodyBytes) {
+        return { valid: false, reason: "body_too_large" };
+    }
+    const reason = await verifySlackSignature({ ...input, now });
+    if (reason)
+        return { valid: false, reason };
+    // Slack interaction callbacks are form-urlencoded and do not contain api_app_id.
+    // The app-scoped signing secret already proves which application sent the request.
+    if (contentType(input.contentType) === "application/x-www-form-urlencoded") {
+        return { valid: true, appId: input.configuredAppId, challenge: null };
+    }
+    // Only parse the body after its signature is trusted.
+    let payload;
+    try {
+        payload = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(input.rawBody));
+    }
+    catch {
+        return { valid: false, reason: "payload" };
+    }
+    if (payload === null || typeof payload !== "object" || Array.isArray(payload)) {
+        return { valid: false, reason: "payload" };
+    }
+    const record = payload;
+    const isChallenge = record.type === "url_verification";
+    if (!isChallenge && record.type !== "event_callback")
+        return { valid: false, reason: "payload" };
+    if ((!isChallenge || record.api_app_id !== undefined) && record.api_app_id !== input.configuredAppId)
+        return { valid: false, reason: "app" };
+    if (isChallenge && (typeof record.challenge !== "string" || !record.challenge || record.challenge.length > 1024))
+        return { valid: false, reason: "payload" };
+    return {
+        valid: true,
+        appId: input.configuredAppId,
+        challenge: isChallenge ? record.challenge : null,
+    };
+}
+function contentType(value) {
+    return value?.split(";", 1)[0]?.trim().toLowerCase() ?? "";
+}

package/src/server/storage/connection-request-store.d.ts

@@ -1,4 +1,4 @@
-import type { StoredConnection, StoredSaasConnection } from "../../connection-service.ts";
+import type { StoredConnection, StoredSaasConnection } from "../../connection-store.ts";
 import type { ResolvedCredential } from "../../core/types.ts";
 import type { OAuthAuthorizationState } from "../../oauth/oauth-flow-service.ts";
 import type { ISecretCodec } from "../secrets/secret-codec-core.ts";

package/src/server/storage/connection-store.d.ts

@@ -1,4 +1,4 @@
-import type { IConnectionStore, StoredConnection, StoredLocalConnection } from "../../connection-service.ts";
+import type { IConnectionStore, StoredConnection, StoredLocalConnection } from "../../connection-store.ts";
 import type { ResolvedCredential } from "../../core/types.ts";
 import type { ISecretCodec } from "../secrets/secret-codec-core.ts";
 import type { RequestTransaction } from "./connection-request-store.ts";

package/src/server/storage/postgres/runtime-store.d.ts

@@ -1,4 +1,4 @@
-import type { IConnectionStore } from "../../../connection-service.ts";
+import type { IConnectionStore } from "../../../connection-store.ts";
 import type { RuntimeLogger } from "../../../core/types.ts";
 import type { IMarketplaceStore } from "../../../marketplace/marketplace-service.ts";
 import type { IOAuthClientConfigStore } from "../../../oauth/oauth-client-config-service.ts";

package/src/server/storage/runtime-database.d.ts

@@ -1,4 +1,4 @@
-import type { IConnectionStore } from "../../connection-service.ts";
+import type { IConnectionStore } from "../../connection-store.ts";
 import type { IMarketplaceStore } from "../../marketplace/marketplace-service.ts";
 import type { IOAuthClientConfigStore } from "../../oauth/oauth-client-config-service.ts";
 import type { IOAuthStateStore } from "../../oauth/oauth-flow-service.ts";

package/src/server/storage/saas-project-store.d.ts

@@ -1,4 +1,4 @@
-import type { StoredSaasConnection } from "../../connection-service.ts";
+import type { StoredSaasConnection } from "../../connection-store.ts";
 import type { ISecretCodec } from "../secrets/secret-codec-core.ts";
 import type { RequestStatement, RequestTransaction } from "./connection-request-store.ts";
 import type { RuntimeRow } from "./runtime-sql.ts";

package/src/triggers/common/integration.d.ts

@@ -1,3 +1,5 @@
+import type { CreateEventSource, UpdateEventSource, EventSource } from "../sources/configuration.ts";
+import type { EventSourceDefinition } from "../sources/definition.ts";
 import type { TriggerConfigOption, TriggerConfigOptionsContext } from "./configOptions.ts";
 import type { ConnectorProxyRequest, ConnectorProxyResult, ConnectorProxy } from "./proxy.ts";
 import type { IntegrationEndpointMethod, JsonValue, TriggerKeySnapshot } from "./types.ts";
@@ -85,13 +87,21 @@ export interface ResourceSubscription {
     readonly unsubscribe: ConnectorProxyRequest;
     readonly inspect?: ConnectorProxyRequest;
 }
-export interface ResourceDefinition {
+export type ResourceDefinition = {
     readonly subscriptions: (config: Readonly<Record<string, JsonValue>>) => readonly ResourceSubscription[];
     readonly response: (result: ConnectorProxyResult) => Readonly<Record<string, JsonValue>>;
-}
+} | {
+    readonly reconcile: (context: IntegrationReconcileContext) => Promise<IntegrationReconcileResult>;
+};
 export interface IntegrationDefinition {
+    readonly source?: EventSourceDefinition<CreateEventSource, UpdateEventSource, Partial<EventSource>>;
+    readonly sourceReceive?: (context: Omit<ListenerReadContext, "checkpoint"> & {
+        readonly headers: Readonly<Record<string, string>>;
+        readonly rawBody: string;
+    }) => Promise<Readonly<Record<string, JsonValue>>>;
+    readonly sourceIdentity?: (context: Omit<ListenerReadContext, "checkpoint">) => Promise<Readonly<Record<string, JsonValue>>>;
     readonly resources?: ResourceDefinition;
-    readonly eventSource?: "feishu";
+    readonly eventSource?: "feishu" | "slack" | "intercom" | "sentry" | "zoom" | "fireflies" | "jira";
     readonly configOptions?: (context: TriggerConfigOptionsContext) => Promise<readonly TriggerConfigOption[]>;
     readonly listener?: ListenerSource;
     readonly initialState?: {
@@ -109,6 +119,8 @@ export declare class IntegrationConnectionError extends Error {
 }
 export declare class PermanentIntegrationError extends Error {
     readonly name = "PermanentIntegrationError";
+    readonly reason: "trigger_quota_exceeded" | "trigger_subscription_uncertain" | undefined;
+    constructor(message: string, reason?: "trigger_quota_exceeded" | "trigger_subscription_uncertain");
 }
 export declare class TransientIntegrationError extends Error {
     readonly name = "TransientIntegrationError";

package/src/triggers/common/integration.js

@@ -25,6 +25,11 @@ export class IntegrationConnectionError extends Error {
 }
 export class PermanentIntegrationError extends Error {
     name = "PermanentIntegrationError";
+    reason;
+    constructor(message, reason) {
+        super(message);
+        this.reason = reason;
+    }
 }
 export class TransientIntegrationError extends Error {
     name = "TransientIntegrationError";

package/src/triggers/common/proxy.d.ts

@@ -6,9 +6,16 @@ export interface ConnectorProxyRequest {
     readonly query?: Readonly<Record<string, boolean | number | string | null>>;
 }
 export interface ConnectorProxyResult {
+    readonly headers?: Readonly<Record<string, string>>;
     readonly data: unknown;
     readonly status: number;
 }
 export interface ConnectorProxy {
+    readonly oauthClientConfig?: {
+        readonly clientId: string;
+        readonly clientSecret?: string;
+    };
+    readonly providerAccountId?: string;
+    readonly authType?: string;
     execute(request: ConnectorProxyRequest, signal?: AbortSignal): Promise<ConnectorProxyResult>;
 }

package/src/triggers/maintenance.d.ts

@@ -1,4 +1,5 @@
 import type { ActionPolicyService } from "../core/action-policy.ts";
+import type { ProviderNetworkPolicy } from "../core/provider-network-policy.ts";
 import type { RuntimeLogger } from "../core/types.ts";
 import type { IRuntimePolicyStore } from "../server/storage/runtime-policy-store.ts";
 import type { IRuntimeTokenStore } from "../server/storage/runtime-token-service.ts";
@@ -16,6 +17,7 @@ export interface TriggerSubscriptionSummary {
     reconcileAt: number;
 }
 interface TriggerMaintenanceOptions {
+    network?: ProviderNetworkPolicy;
     store: TriggerStore;
     runner: TriggerRunner;
     tokens: IRuntimeTokenStore;

package/src/triggers/maintenance.js

@@ -1,3 +1,4 @@
+import { withProviderNetworkPolicy } from "../core/provider-network-policy.js";
 import { HttpRequestError } from "../server/api/http-utils.js";
 import { withSubscription } from "./subscriptions.js";
 export class TriggerMaintenance {
@@ -49,7 +50,7 @@ export class TriggerMaintenance {
     run() {
         if (this.shutdown.signal.aborted)
             return Promise.resolve();
-        this.pending ??= this.runBatch()
+        this.pending ??= withProviderNetworkPolicy(this.options.network ?? {}, () => this.runBatch())
             .catch(() => {
             this.options.logger?.warn({ errorCode: "trigger_cleanup_failed" }, "Trigger cleanup batch failed; pending work is retained");
         })

package/src/triggers/managed-webhook.d.ts

@@ -0,0 +1,13 @@
+import type { IntegrationReconcileContext, IntegrationReconcileResult } from "./common/integration.ts";
+import type { ConnectorProxyRequest, ConnectorProxyResult } from "./common/proxy.ts";
+export interface ManagedWebhook {
+    readonly id: string;
+    readonly secret: string;
+}
+export declare function webhookRequest(context: Pick<IntegrationReconcileContext, "connector" | "signal">, request: ConnectorProxyRequest): Promise<ConnectorProxyResult>;
+export declare function reconcileManagedWebhook(context: IntegrationReconcileContext, operations: {
+    readonly find: () => Promise<readonly ManagedWebhook[]>;
+    readonly create: () => Promise<ManagedWebhook>;
+    readonly remove: (id: string) => Promise<void>;
+    readonly align?: (id: string) => Promise<void>;
+}): Promise<IntegrationReconcileResult>;

package/src/triggers/managed-webhook.js

@@ -0,0 +1,48 @@
+import { PermanentIntegrationError, TransientIntegrationError } from "./common/integration.js";
+export async function webhookRequest(context, request) {
+    context.signal?.throwIfAborted();
+    const result = await context.connector.execute(request, context.signal);
+    context.signal?.throwIfAborted();
+    if ((result.status >= 200 && result.status < 300) || (request.method == "DELETE" && result.status == 404))
+        return result;
+    const message = `Webhook ${request.method} request failed (HTTP ${result.status}). Check resource access and webhook permissions.`;
+    if (result.status >= 400 && result.status < 500 && result.status != 429)
+        throw new PermanentIntegrationError(message);
+    throw new TransientIntegrationError(message);
+}
+export async function reconcileManagedWebhook(context, operations) {
+    const state = context.state;
+    if (state == null)
+        throw new PermanentIntegrationError("Webhook subscription state is missing.");
+    const matches = await operations.find();
+    if (matches.length > 1)
+        throw new PermanentIntegrationError("Multiple webhooks match this subscription. Remove duplicates before retrying.");
+    let hook = matches[0];
+    if (!context.active) {
+        if (hook != null)
+            await operations.remove(hook.id);
+        else if (state.subscription.creating === true)
+            throw new PermanentIntegrationError("Webhook creation has an uncertain outcome. Verify the remote subscription before cleanup.");
+        await state.saveSubscription({}, new Date(context.now.getTime() + 86_400_000));
+        return { outcome: "ready" };
+    }
+    if (hook == null) {
+        if (state.subscription.creating === true)
+            throw new PermanentIntegrationError("Webhook creation has an uncertain outcome. Verify the remote subscription before retrying.");
+        await state.saveSubscription({ creating: true }, context.now);
+        try {
+            hook = await operations.create();
+        }
+        catch (error) {
+            // A definite rejection did not create a resource; transport and malformed-response errors remain uncertain.
+            if (error instanceof PermanentIntegrationError)
+                await state.saveSubscription({}, context.now);
+            throw error;
+        }
+    }
+    const subscription = { hookId: hook.id, secret: hook.secret };
+    await state.saveSubscription(subscription, context.now);
+    await operations.align?.(hook.id);
+    await state.saveSubscription(subscription, new Date(context.now.getTime() + 86_400_000));
+    return { outcome: "ready" };
+}