@oomol-lab/open-connector 1.6.5 → 1.7.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/server/api/openapi.js

@@ -42,6 +42,9 @@ const oauthClientConfigRequestSchema = jsonSchema.object({
         minItems: 1,
         description: "Non-empty provider-declared scope subset to request. Omit to use every provider default.",
     }),
+    redirectUri: jsonSchema.string({
+        description: "Absolute redirect URI registered with the provider instead of the runtime callback, such as a native app's custom scheme. Must not carry user info or a fragment; javascript, vbscript, data, file, blob, and about schemes are rejected. Omit or send an empty string to use the runtime callback.",
+    }),
     extra: {
         type: "object",
         additionalProperties: { type: "string" },
@@ -457,8 +460,11 @@ export function createOpenApiDocument(providers, options = {}) {
                     }),
                     clientId: jsonSchema.nullable(jsonSchema.string({ description: "Configured OAuth client id." })),
                     expectedRedirectUri: jsonSchema.string({
-                        description: "Callback URL to configure in the provider OAuth app.",
+                        description: "Callback URL to configure in the provider OAuth app: the configured override, else the runtime callback.",
                     }),
+                    redirectUri: jsonSchema.nullable(jsonSchema.string({
+                        description: "Configured redirect URI override, or null when the runtime callback is used.",
+                    })),
                     auth: jsonSchema.unknownObject("Provider OAuth capability metadata."),
                     requestedScopes: jsonSchema.nullable(jsonSchema.array(jsonSchema.string(), {
                         description: "Configured scope subset, or null when provider defaults are used.",
@@ -473,6 +479,7 @@ export function createOpenApiDocument(providers, options = {}) {
                         "customClientAvailable",
                         "clientId",
                         "expectedRedirectUri",
+                        "redirectUri",
                         "auth",
                         "requestedScopes",
                         "effectiveScopes",
@@ -1082,6 +1089,9 @@ function createOAuthAuthorizationPath() {
                                 minItems: 1,
                                 description: "Optional non-empty provider-declared scope subset to request.",
                             }),
+                            redirectUri: jsonSchema.string({
+                                description: "Optional redirect URI registered with the connection-scoped OAuth app instead of the runtime callback. Same rules as OAuthClientConfigRequest.redirectUri.",
+                            }),
                             authorizationOptionIds: jsonSchema.array(jsonSchema.string(), {
                                 description: "Optional provider authorization option ids selected for this connection.",
                             }),
@@ -1342,7 +1352,7 @@ function connectionManagementPaths() {
         oauthClient: jsonSchema.optional(jsonSchema.object("OAuth client configuration state; present when the provider supports OAuth.", {
             configured: jsonSchema.boolean(),
             customClientAvailable: jsonSchema.boolean("Whether connections may carry their own OAuth client."),
-            expectedRedirectUri: jsonSchema.string("Callback URL to register with the provider."),
+            expectedRedirectUri: jsonSchema.string("Callback URL to register with the provider: the configured override, else the runtime callback."),
             missingFields: jsonSchema.stringArray("Required client inputs absent from the stored configuration."),
         })),
     });

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

@@ -100,7 +100,13 @@ export declare function serializeRuntimeFailure(input: RuntimeFailureInput): Run
 export declare function serializeRuntimeActionResult(input: RuntimeActionResultInput): RuntimeActionHttpResult;
 /** Validate an action response decoded from persistent storage. */
 export declare function parseRuntimeActionHttpResult(value: unknown): RuntimeActionHttpResult;
-/** Write a newly serialized or replayed action response. */
+/**
+ * Write a newly serialized or replayed action response; runtime failures,
+ * including proxy failures, go through here as well. A 429 whose provider
+ * details carry `retryAfterSeconds` also answers with the `Retry-After`
+ * header, so HTTP callers pace on the provider's own hint; the body keeps it,
+ * which is what an idempotent replay re-emits the header from.
+ */
 export declare function writeRuntimeActionHttpResult(context: Context, result: RuntimeActionHttpResult): Response;
 export declare function mapConnectionErrorStatus(error: ConnectionError): 400 | 404 | 409;
 /**
@@ -129,6 +135,7 @@ export interface RuntimeProviderSetup {
 interface RuntimeOAuthClientSetup {
     configured: boolean;
     customClientAvailable: boolean;
+    /** Redirect URI to register with the provider: the configured override, else the runtime callback. */
     expectedRedirectUri: string;
     missingFields: string[];
 }

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

@@ -128,10 +128,28 @@ export function parseRuntimeActionHttpResult(value) {
     }
     throw invalid("status and body envelope do not match");
 }
-/** Write a newly serialized or replayed action response. */
+/**
+ * Write a newly serialized or replayed action response; runtime failures,
+ * including proxy failures, go through here as well. A 429 whose provider
+ * details carry `retryAfterSeconds` also answers with the `Retry-After`
+ * header, so HTTP callers pace on the provider's own hint; the body keeps it,
+ * which is what an idempotent replay re-emits the header from.
+ */
 export function writeRuntimeActionHttpResult(context, result) {
+    const retryAfterSeconds = readRuntimeRetryAfterSeconds(result);
+    if (retryAfterSeconds !== undefined) {
+        context.header("Retry-After", String(retryAfterSeconds));
+    }
     return context.json(result.body, result.status);
 }
+function readRuntimeRetryAfterSeconds(result) {
+    if (result.status !== 429) {
+        return undefined;
+    }
+    const seconds = optionalInteger(optionalRecord(optionalRecord(result.body.data)?.details)?.retryAfterSeconds);
+    // A safe integer is what keeps String() in plain delay-seconds digits: 1e21 would print as "1e+21".
+    return seconds !== undefined && Number.isSafeInteger(seconds) && seconds >= 0 ? seconds : undefined;
+}
 export function mapConnectionErrorStatus(error) {
     if (error.code === "unknown_service" || error.code === "connection_not_found") {
         return 404;

package/src/server/connect-server.js

@@ -3,7 +3,7 @@ import { compress } from "hono/compress";
 import { ConnectionError, defaultConnectionName } from "../connection-service.js";
 import { ActionPolicyService, emptyPolicyRules } from "../core/action-policy.js";
 import { DEFAULT_ACTION_SEARCH_LIMIT, createActionSearchIndexProvider, searchActions } from "../core/action-search.js";
-import { optionalRecord, optionalString, requiredString, requiredStringArray } from "../core/cast.js";
+import { optionalRecord, optionalString, requiredRawString, requiredString, requiredStringArray, } from "../core/cast.js";
 import { PromiseCache } from "../core/promise-cache.js";
 import { MarketplaceError } from "../marketplace/marketplace-service.js";
 import { OAuthClientConfigError, OAuthClientConfigService } from "../oauth/oauth-client-config-service.js";
@@ -845,6 +845,7 @@ export class ConnectServer {
             clientId: optionalString(body.clientId) ?? "",
             clientSecret: optionalString(body.clientSecret) ?? "",
             requestedScopes: readOptionalStringArray(body, "requestedScopes"),
+            redirectUri: readOptionalRawString(body, "redirectUri"),
             extra: optionalRecord(body.extra),
             secretExtra: optionalRecord(body.secretExtra),
         }));
@@ -981,7 +982,7 @@ export class ConnectServer {
     }
 }
 function readOAuthClientConfigInput(body) {
-    const keys = ["clientId", "clientSecret", "requestedScopes", "extra", "secretExtra"];
+    const keys = ["clientId", "clientSecret", "requestedScopes", "redirectUri", "extra", "secretExtra"];
     if (!keys.some((key) => key in body)) {
         return undefined;
     }
@@ -989,10 +990,17 @@ function readOAuthClientConfigInput(body) {
         clientId: optionalString(body.clientId) ?? "",
         clientSecret: optionalString(body.clientSecret) ?? "",
         requestedScopes: readOptionalStringArray(body, "requestedScopes"),
+        redirectUri: readOptionalRawString(body, "redirectUri"),
         extra: optionalRecord(body.extra),
         secretExtra: optionalRecord(body.secretExtra),
     };
 }
+/** An absent field is undefined; a present one, null included, must be a string (blank is kept for the caller to read as unset). */
+function readOptionalRawString(body, fieldName) {
+    if (!(fieldName in body))
+        return undefined;
+    return requiredRawString(body[fieldName], fieldName, (message) => new HttpRequestError("invalid_input", `${message}.`));
+}
 function readOptionalStringArray(body, fieldName) {
     if (!(fieldName in body))
         return undefined;

package/src/providers/sentry/scopes.d.ts

@@ -1 +0,0 @@
-export declare const sentryProviderScopes: string[];

package/src/providers/sentry/scopes.js

@@ -1,7 +0,0 @@
-export const sentryProviderScopes = [
-    "org:read",
-    "project:read",
-    "project:releases",
-    "event:read",
-    "event:write",
-];