@oomol-lab/open-connector 1.6.5 → 1.8.0

package/src/providers/zerotier/runtime.js

@@ -0,0 +1,207 @@
+import { looseArray, optionalRecord, optionalString } from "../../core/cast.js";
+import { encodePathSegment } from "../../core/request.js";
+import { providerInputError, providerUserAgent, ProviderRequestError, readProviderJsonBody, runProviderRequest, } from "../provider-runtime.js";
+/** Legacy Central base URL; requests authenticate with `Authorization: token <key>`. */
+export const zerotierV1BaseUrl = "https://api.zerotier.com/api/v1";
+/** New Central base URL; requests authenticate with `Authorization: Bearer <key>`. */
+export const zerotierV2BaseUrl = "https://central.zerotier.com/api/v2";
+const zerotierV2BetaBaseUrl = "https://central.zerotier.com/api/v2beta";
+export function parseZerotierApiVersion(value) {
+    const version = optionalString(value)?.toLowerCase();
+    if (version === "v1" || version === "v2") {
+        return version;
+    }
+    throw providerInputError('zerotier apiVersion must be "v1" (Legacy Central) or "v2" (New Central).');
+}
+export function createZerotierContext(values, fetcher, signal) {
+    const apiVersion = parseZerotierApiVersion(values.apiVersion);
+    const apiKey = optionalString(values.apiKey);
+    if (!apiKey) {
+        throw providerInputError("zerotier apiKey is required.");
+    }
+    return {
+        apiVersion,
+        apiKey,
+        orgId: optionalString(values.orgId),
+        fetcher,
+        signal,
+    };
+}
+/**
+ * Encode one ID as a single path segment. encodeURIComponent leaves "." and
+ * ".." intact and new URL() collapses them, so memberId ".." would turn
+ * delete_member into DELETE /network/{id}; reject dot segments and separators.
+ */
+export function zerotierPathSegment(value, field) {
+    if (value === "." || value === ".." || value.includes("/") || value.includes("\\")) {
+        throw providerInputError(`${field} must be a single path segment.`);
+    }
+    return encodePathSegment(value);
+}
+export function zerotierAuthorizationHeader(credential) {
+    return credential.apiVersion === "v2" ? `Bearer ${credential.apiKey}` : `token ${credential.apiKey}`;
+}
+function zerotierBaseUrl(context, beta) {
+    if (context.apiVersion === "v1") {
+        if (beta) {
+            throw providerInputError("ZeroTier beta endpoints are only available on the v2 (New Central) API.");
+        }
+        return zerotierV1BaseUrl;
+    }
+    return beta ? zerotierV2BetaBaseUrl : zerotierV2BaseUrl;
+}
+/** Run one ZeroTier Central API request and return the parsed JSON payload, or null for empty bodies. */
+export async function zerotierRequest(context, options) {
+    return runProviderRequest({ signal: context.signal, label: "ZeroTier" }, async (signal) => {
+        const url = new URL(zerotierBaseUrl(context, options.beta) + options.path);
+        if (options.query) {
+            for (const [key, value] of Object.entries(options.query)) {
+                if (value === undefined)
+                    continue;
+                if (Array.isArray(value)) {
+                    for (const item of value) {
+                        url.searchParams.append(key, item);
+                    }
+                }
+                else {
+                    url.searchParams.set(key, value);
+                }
+            }
+        }
+        const response = await context.fetcher(url, {
+            method: options.method ?? "GET",
+            headers: {
+                accept: "application/json",
+                authorization: zerotierAuthorizationHeader(context),
+                "content-type": "application/json",
+                "user-agent": providerUserAgent,
+            },
+            body: options.body === undefined ? undefined : JSON.stringify(options.body),
+            signal,
+        });
+        const payload = await readProviderJsonBody(response, {
+            emptyBody: null,
+            invalidJsonMessage: "ZeroTier returned invalid JSON",
+            // A non-JSON error body (such as a proxy's HTML page) keeps the upstream
+            // status instead of becoming a 502 parse failure; only its start is kept.
+            invalidJsonFallback: response.ok ? undefined : (text) => ({ message: text.trim().slice(0, 500) }),
+        });
+        if (!response.ok) {
+            const record = optionalRecord(payload);
+            const summary = optionalString(record?.message) ?? `ZeroTier request failed with status ${response.status}`;
+            // v2 validation failures list the offending fields under details[{field, message}].
+            const details = looseArray(record?.details).flatMap((item) => {
+                const detail = optionalRecord(item);
+                const field = optionalString(detail?.field);
+                const reason = optionalString(detail?.message);
+                return reason ? [field ? `${field}: ${reason}` : reason] : [];
+            });
+            const message = details.length > 0 ? `${summary}: ${details.join("; ")}` : summary;
+            throw new ProviderRequestError(response.status, message);
+        }
+        return payload;
+    });
+}
+/** Require a specific ZeroTier API version on the connection. */
+export function requireZerotierApiVersion(context, version) {
+    if (context.apiVersion !== version) {
+        throw providerInputError(`This action requires a ${version} ZeroTier connection; the connection is configured for ${context.apiVersion}.`);
+    }
+}
+/**
+ * Wrap a ZeroTier array response into the action list envelope. v2 list
+ * endpoints answer `{ items, stats? }`; the aggregate `stats` requested with
+ * `stats=true` is kept next to the items.
+ */
+export function zerotierList(payload) {
+    if (payload === null || payload === undefined) {
+        return { items: [] };
+    }
+    if (Array.isArray(payload)) {
+        return { items: payload };
+    }
+    const record = optionalRecord(payload);
+    if (record && Array.isArray(record.items)) {
+        return { items: record.items, stats: record.stats };
+    }
+    return { items: [payload] };
+}
+/** Wrap a ZeroTier object response into the action single-resource envelope. */
+export function zerotierResult(payload) {
+    return { result: payload };
+}
+/** Wrap a mutating ZeroTier response that may have an empty body. */
+export function zerotierStatus(payload) {
+    return { ok: true, result: payload };
+}
+/** Organization ID from the action input, falling back to the connection's orgId field. */
+export function zerotierOrgId(context, input) {
+    return optionalString(input.orgId) ?? context.orgId;
+}
+const v1ValidationEndpoint = "/status";
+const v2ValidationEndpoint = "/org";
+/**
+ * Legacy Central reports the token's user under `user` on GET /status. The
+ * status document itself is not an authorization check, so a response without
+ * a user means the token did not authenticate.
+ */
+function readV1Account(payload) {
+    const user = optionalRecord(optionalRecord(payload)?.user);
+    const accountId = optionalString(user?.id);
+    if (!accountId) {
+        throw new ProviderRequestError(401, "ZeroTier did not return a user for this API token.");
+    }
+    return {
+        accountId,
+        displayName: optionalString(user?.displayName) ?? optionalString(user?.email) ?? "ZeroTier Central v1",
+    };
+}
+/**
+ * New Central GET /org lists the organizations the service account can reach.
+ * A service account belongs to one organization, which identifies the account.
+ * A configured orgId must name an organization the key can reach, because the
+ * list actions and get_org keep using it; one missing from the list is looked
+ * up directly so the upstream 403/404 rejects a mistyped id. Without an orgId,
+ * a single listed organization identifies the account, otherwise the runtime
+ * default account id applies.
+ */
+async function readV2Account(context, payload) {
+    const orgs = looseArray(optionalRecord(payload)?.items).map((item) => optionalRecord(item));
+    const orgId = context.orgId;
+    if (!orgId) {
+        const onlyOrg = orgs.length === 1 ? orgs[0] : undefined;
+        return {
+            accountId: optionalString(onlyOrg?.id),
+            displayName: optionalString(onlyOrg?.name) ?? "ZeroTier New Central v2",
+        };
+    }
+    const org = orgs.find((item) => optionalString(item?.id) === orgId) ??
+        optionalRecord(await zerotierRequest(context, { path: `/org/${zerotierPathSegment(orgId, "orgId")}` }));
+    return {
+        accountId: optionalString(org?.id) ?? orgId,
+        displayName: optionalString(org?.name) ?? "ZeroTier New Central v2",
+    };
+}
+/**
+ * Verify a ZeroTier credential against the API generation it selects: v1 calls
+ * GET /status on Legacy Central, v2 calls GET /org on New Central (plus
+ * GET /org/{orgId} when the configured orgId is not in that list).
+ */
+export async function validateZerotierCredential(values, fetcher, signal) {
+    const context = createZerotierContext(values, fetcher, signal);
+    const path = context.apiVersion === "v1" ? v1ValidationEndpoint : v2ValidationEndpoint;
+    const payload = await zerotierRequest(context, { path });
+    const account = context.apiVersion === "v1" ? readV1Account(payload) : await readV2Account(context, payload);
+    return {
+        profile: {
+            accountId: account.accountId,
+            displayName: account.displayName,
+        },
+        grantedScopes: [],
+        metadata: {
+            apiVersion: context.apiVersion,
+            apiBaseUrl: context.apiVersion === "v1" ? zerotierV1BaseUrl : zerotierV2BaseUrl,
+            validationEndpoint: path,
+        },
+    };
+}

package/src/saas/saas-cleanup-service.d.ts

@@ -0,0 +1,26 @@
+import type { RuntimeLogger } from "../core/types.ts";
+import type { ConnectionRequestStore } from "../server/storage/connection-request-store.ts";
+import type { SaasProjectStore } from "../server/storage/saas-project-store.ts";
+import { SaasClient } from "./saas-client.ts";
+export interface SaasCleanupServiceOptions {
+    store: SaasProjectStore;
+    requests: ConnectionRequestStore;
+    client?: SaasClient;
+    logger?: RuntimeLogger;
+}
+/** Resumable deletion of ordinary SaaS accounts; never creates or reconnects an account. */
+export declare class SaasCleanupService {
+    private readonly options;
+    private readonly client;
+    private readonly shutdown;
+    private pending?;
+    private timer?;
+    private started;
+    constructor(options: SaasCleanupServiceOptions);
+    run(): Promise<void>;
+    /** Node owns this timer; Workers invoke run from their scheduled entry point instead. */
+    start(): void;
+    close(): Promise<void>;
+    private runBatch;
+    private nextAttempt;
+}

package/src/saas/saas-cleanup-service.js

@@ -0,0 +1,124 @@
+import { SaasClient, SaasError } from "./saas-client.js";
+/** Resumable deletion of ordinary SaaS accounts; never creates or reconnects an account. */
+export class SaasCleanupService {
+    options;
+    client;
+    shutdown = new AbortController();
+    pending;
+    timer;
+    started = false;
+    constructor(options) {
+        this.options = options;
+        this.client = options.client ?? new SaasClient();
+    }
+    run() {
+        if (this.shutdown.signal.aborted)
+            return Promise.resolve();
+        this.pending ??= this.runBatch()
+            .catch(() => {
+            this.options.logger?.warn({ errorCode: "saas_cleanup_failed" }, "SaaS cleanup batch failed; pending work is retained");
+        })
+            .finally(() => {
+            this.pending = undefined;
+        });
+        return this.pending;
+    }
+    /** Node owns this timer; Workers invoke run from their scheduled entry point instead. */
+    start() {
+        if (this.started || this.shutdown.signal.aborted)
+            return;
+        this.started = true;
+        const tick = () => {
+            void this.run().finally(() => {
+                if (this.shutdown.signal.aborted)
+                    return;
+                this.timer = setTimeout(tick, 60_000);
+                this.timer.unref?.();
+            });
+        };
+        tick();
+    }
+    async close() {
+        this.shutdown.abort();
+        clearTimeout(this.timer);
+        await this.pending;
+    }
+    async runBatch() {
+        await this.options.requests.expireSaas();
+        const deadline = Date.now() + 50_000;
+        for (let count = 0; count < 10 && Date.now() < deadline && !this.shutdown.signal.aborted; count++) {
+            const project = await this.options.store.getProject();
+            if (!project)
+                return;
+            const task = await this.options.store.claimCleanup(Date.now());
+            if (!task)
+                return;
+            const signal = AbortSignal.any([
+                this.shutdown.signal,
+                AbortSignal.timeout(Math.max(1, Math.min(30_000, deadline - Date.now()))),
+            ]);
+            try {
+                if (project.id !== task.managedProjectId)
+                    throw new SaasError("oauth_source_mismatch", "Cleanup project identity does not match.", 409);
+                let accountId = task.connectedAccountId;
+                if (!accountId) {
+                    if (!task.remoteRequestId) {
+                        await this.options.store.retryCleanup(task, Date.now(), "oauth_source_result_unknown", true);
+                        continue;
+                    }
+                    const result = await this.client.getRequest(project, task.remoteRequestId, signal);
+                    if (result.providerConfigId !== task.providerConfigId ||
+                        result.externalUserId !== task.externalUserId ||
+                        result.service !== task.service ||
+                        result.alias !== `connect-${task.id.slice("request:".length)}`)
+                        throw new SaasError("oauth_source_mismatch", "Cleanup request identity does not match.", 409);
+                    if (result.status === "initiated") {
+                        const expired = Date.now() >= Date.parse(task.requestExpiresAt ?? result.expiresAt) + 86_400_000;
+                        await this.options.store.retryCleanup(task, Date.now() + 60_000, expired ? "oauth_source_result_unknown" : "authorization_pending", expired);
+                        continue;
+                    }
+                    if (result.status !== "connected") {
+                        await this.options.store.finishCleanup(task);
+                        continue;
+                    }
+                    accountId = result.connectedAccountId;
+                    if (!(await this.options.store.saveCleanupAccount(task, accountId)))
+                        continue;
+                    task.connectedAccountId = accountId;
+                }
+                signal.throwIfAborted();
+                await this.client.deleteAccount(project, {
+                    providerConfigId: task.providerConfigId,
+                    externalUserId: task.externalUserId,
+                    connectedAccountId: accountId,
+                }, signal);
+                await this.options.store.finishCleanup(task);
+            }
+            catch (error) {
+                const code = error instanceof SaasError ? error.code : "saas_cleanup_failed";
+                if (code === "oauth_source_unauthorized")
+                    await this.options.store.pauseCleanup(task, project.apiKey);
+                const manual = code === "oauth_source_mismatch" ||
+                    code === "oauth_source_protocol_error" ||
+                    (code === "oauth_source_not_found" && !task.connectedAccountId);
+                await this.options.store.retryCleanup(task, this.nextAttempt(task, error), code === "oauth_source_not_found" && !task.connectedAccountId ? "oauth_source_result_unknown" : code, manual);
+                if (!this.shutdown.signal.aborted)
+                    this.options.logger?.warn({ taskId: task.id, errorCode: code, manual }, code === "oauth_source_unauthorized"
+                        ? "SaaS cleanup paused; update the project key to resume"
+                        : "SaaS cleanup deferred");
+                if (code === "oauth_source_unauthorized" || this.shutdown.signal.aborted)
+                    return;
+            }
+        }
+    }
+    nextAttempt(task, error) {
+        let delay = Math.min(300_000, 60_000 * 2 ** Math.min(task.attempts, 3));
+        if (error instanceof SaasError && error.retryAfter) {
+            const seconds = Number(error.retryAfter);
+            const until = Number.isFinite(seconds) ? Date.now() + seconds * 1_000 : Date.parse(error.retryAfter);
+            if (Number.isFinite(until))
+                delay = Math.max(delay, until - Date.now());
+        }
+        return Date.now() + delay;
+    }
+}

package/src/saas/saas-client.d.ts

@@ -0,0 +1,86 @@
+import type { ProxyRequestInput, ProxyResponse } from "../core/types.ts";
+import type { ManagedProject } from "../server/storage/saas-project-store.ts";
+export interface SaasProviderConfig {
+    id: string;
+    service: string;
+    displayName: string;
+    callbackUrl: string;
+    effectiveScopes: string[];
+    actionIds: string[];
+    proxyAvailable: boolean;
+}
+export interface SaasDiscovery {
+    projectId: string;
+    providerConfigs: SaasProviderConfig[];
+}
+export interface SaasAccount extends SaasAccountSelector {
+    projectId: string;
+    service: string;
+    alias: string | null;
+    status: "active" | "reauth_required" | "error" | "disconnected";
+    providerAccountId: string | null;
+    accountLabel: string | null;
+    scopes: string[];
+}
+export interface SaasConnectionRequest {
+    id: string;
+    status: "initiated" | "connected" | "failed" | "expired";
+    projectId: string;
+    providerConfigId: string;
+    externalUserId: string;
+    service: string;
+    alias: string | null;
+    authorizationUrl: string;
+    connectedAccountId: string | null;
+    errorCode: string | null;
+    errorMessage: string | null;
+    expiresAt: string;
+    createdAt: number;
+    updatedAt: number;
+}
+export declare class SaasError extends Error {
+    readonly code: string;
+    readonly status: 400 | 402 | 403 | 404 | 409 | 413 | 429 | 500 | 501 | 502 | 503 | 504;
+    readonly retryAfter?: string;
+    readonly reason?: string;
+    connectionRequestId?: string;
+    remoteExecutionId?: string;
+    constructor(code: string, message: string, status?: SaasError["status"], retryAfter?: string, reason?: string);
+}
+export interface SaasAccountSelector {
+    providerConfigId: string;
+    externalUserId: string;
+    connectedAccountId: string;
+}
+export interface SaasLinkInput {
+    providerConfigId: string;
+    externalUserId: string;
+    alias: string;
+    returnUri: string;
+}
+export interface SaasActionResult {
+    executionId: string;
+    actionId: string;
+    output: unknown;
+}
+export interface SaasProxyResult {
+    executionId: string;
+    response: ProxyResponse;
+}
+/** Reject values that the project proxy protocol cannot represent before any remote request. */
+export declare function parseSaasProxyRequest(input: unknown): Promise<ProxyRequestInput>;
+/** The project API never supplies credentials to the local provider runtime. */
+export declare class SaasClient {
+    private readonly fetcher?;
+    constructor(fetcher?: typeof fetch);
+    discover(project: Pick<ManagedProject, "baseUrl" | "apiKey">, signal?: AbortSignal): Promise<SaasDiscovery>;
+    getAccount(project: ManagedProject, selector: SaasAccountSelector, service: string, signal?: AbortSignal): Promise<SaasAccount>;
+    getRequest(project: ManagedProject, id: string, signal?: AbortSignal): Promise<SaasConnectionRequest>;
+    createLink(project: ManagedProject, input: SaasLinkInput, signal?: AbortSignal): Promise<SaasConnectionRequest>;
+    deleteAccount(project: ManagedProject, selector: SaasAccountSelector, signal?: AbortSignal): Promise<void>;
+    executeAction(project: ManagedProject, selector: SaasAccountSelector, actionId: string, input: unknown, signal?: AbortSignal): Promise<SaasActionResult>;
+    executeProxy(project: ManagedProject, selector: SaasAccountSelector, service: string, request: ProxyRequestInput, signal?: AbortSignal): Promise<SaasProxyResult>;
+    private request;
+    private requestEnvelope;
+}
+export declare function normalizeSaasBaseUrl(value: string): string;