@oomol-lab/open-connector 1.8.0 → 1.9.0

package/src/core/provider-http-dispatch.js

@@ -0,0 +1,177 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+const scopes = new AsyncLocalStorage();
+/** Safe retryable denial, including hook/readiness failures; it contains no callback error details. */
+export class ProviderHttpDispatchError extends Error {
+    retryAfterSeconds;
+    constructor(retryAfterSeconds) {
+        super("Provider HTTP dispatch is temporarily unavailable.");
+        this.retryAfterSeconds = retryAfterSeconds;
+    }
+}
+/**
+ * Bind a hook to asynchronous provider work. Nested scopes inherit the configured hook;
+ * concurrent requests stay isolated. Standalone providerFetch users can opt in here too.
+ */
+export function withProviderHttpDispatch(context, run, options) {
+    const parent = scopes.getStore();
+    const configured = options ?? parent?.options;
+    if (!configured)
+        return run();
+    // Copy an explicit allowlist so accidental credential-bearing extra fields cannot escape.
+    const snapshot = Object.freeze({
+        operation: context.operation,
+        service: context.service,
+        actionId: context.actionId,
+        executionId: context.executionId,
+        connectionId: context.connectionId,
+        connectionName: context.connectionName,
+    });
+    return scopes.run({ options: configured, context: snapshot, receipt: parent?.options === configured ? parent.receipt : {} }, run);
+}
+/**
+ * A provider invocation boundary: retain the original denial even if provider code catches,
+ * replaces, or converts it to a result. Each invocation owns its marker, so a sibling's
+ * denial cannot override another invocation's successful retry or fallback.
+ */
+export async function runWithProviderHttpDispatch(context, run, options) {
+    return withProviderHttpDispatch(context, async () => {
+        const inherited = scopes.getStore();
+        if (!inherited)
+            return run();
+        const scope = { ...inherited, receipt: {} };
+        return scopes.run(scope, async () => {
+            try {
+                const result = await run();
+                if (scope.receipt.denial)
+                    throw scope.receipt.denial;
+                return result;
+            }
+            catch (error) {
+                throw scope.receipt.denial ?? error;
+            }
+        });
+    }, options);
+}
+function deny(scope, retryAfterSeconds) {
+    return (scope.receipt.denial ??= Object.freeze(new ProviderHttpDispatchError(retryAfterSeconds)));
+}
+/** Called only at the screened raw-transport seam, once for every HTTP attempt and redirect hop. */
+export const dispatchProviderHttpAttempt = async (target, signal, transport, revalidate) => {
+    const scope = scopes.getStore();
+    if (!scope)
+        return transport();
+    signal?.throwIfAborted();
+    // Denial is terminal for this invocation. A provider may catch it, but must not complete
+    // later side effects that the boundary would then misreport as a retryable denial.
+    if (scope.receipt.denial)
+        throw scope.receipt.denial;
+    let permit;
+    let attempt;
+    try {
+        const authority = await waitForSignal(Promise.resolve(scope.options.bindAuthority?.(scope.context)), signal);
+        signal?.throwIfAborted();
+        if (scope.receipt.denial)
+            throw scope.receipt.denial;
+        attempt = Object.freeze({
+            attemptId: crypto.randomUUID(),
+            requestId: target.requestId,
+            redirectHop: target.redirectHop,
+            method: target.method,
+            origin: target.origin,
+            context: scope.context,
+            authority: Object.freeze({
+                workspaceId: authority?.workspaceId,
+                connectionLineageId: authority?.connectionLineageId,
+                workClass: authority?.workClass,
+            }),
+        });
+        permit = await waitForSignal(Promise.resolve(scope.options.beforeAttempt(attempt, signal)), signal, (late) => {
+            if (late?.allow)
+                void reportFeedback(scope.options, attempt, late, { kind: "not_dispatched", reason: "cancelled" });
+        });
+        if (!permit || typeof permit.allow !== "boolean")
+            throw new ProviderHttpDispatchError();
+    }
+    catch {
+        signal?.throwIfAborted();
+        throw deny(scope);
+    }
+    if (!permit.allow) {
+        const seconds = permit.retryAfterSeconds;
+        throw deny(scope, Number.isSafeInteger(seconds) && seconds >= 0 ? seconds : undefined);
+    }
+    const admitted = permit;
+    const feedback = (result) => reportFeedback(scope.options, attempt, admitted, result);
+    try {
+        signal?.throwIfAborted();
+        if (scope.receipt.denial)
+            throw scope.receipt.denial;
+        await waitForSignal(Promise.resolve(admitted.onDispatch?.()), signal);
+        if (scope.receipt.denial)
+            throw scope.receipt.denial;
+        // Admission can wait arbitrarily long. Re-screen DNS/URL before issuing the admitted hop.
+        await waitForSignal(revalidate(), signal);
+        signal?.throwIfAborted();
+        if (scope.receipt.denial)
+            throw scope.receipt.denial;
+    }
+    catch {
+        const denial = signal?.aborted ? undefined : deny(scope);
+        void feedback({ kind: "not_dispatched", reason: signal?.aborted ? "cancelled" : "dispatch_failed" });
+        signal?.throwIfAborted();
+        throw denial;
+    }
+    let response;
+    try {
+        response = await transport();
+    }
+    catch (error) {
+        void feedback({ kind: "transport_error" });
+        throw error;
+    }
+    // Report every HTTP status, including redirect responses. No response body is read or exposed.
+    void feedback({
+        kind: "response",
+        status: response.status,
+        retryAfter: response.headers.get("retry-after") ?? undefined,
+    });
+    return response;
+};
+async function reportFeedback(options, attempt, permit, result) {
+    try {
+        await permit.onResult?.(Object.freeze(result));
+    }
+    catch {
+        try {
+            await options.onFeedbackError?.(attempt);
+        }
+        catch {
+            // Feedback cannot turn an already-issued request into a failure that a caller might replay.
+        }
+    }
+}
+function waitForSignal(pending, signal, onLate) {
+    if (!signal)
+        return pending;
+    return new Promise((resolve, reject) => {
+        let cancelled = false;
+        const abort = () => {
+            cancelled = true;
+            reject(signal.reason);
+        };
+        if (signal.aborted)
+            abort();
+        else
+            signal.addEventListener("abort", abort, { once: true });
+        void pending.then((value) => {
+            signal.removeEventListener("abort", abort);
+            if (cancelled)
+                onLate?.(value);
+            else
+                resolve(value);
+        }, (error) => {
+            signal.removeEventListener("abort", abort);
+            reject(error);
+        });
+    });
+}

package/src/core/provider-scenarios.js

@@ -118,7 +118,6 @@ const scenarioByService = new Map([
     ["triplewhale", "cross-border-ecommerce"],
     ["vercel", "developer"],
     ["shopify", "cross-border-ecommerce"],
-    ["shopifyadmin", "cross-border-ecommerce"],
     ["shopifypartner", "cross-border-ecommerce"],
     ["shopifystorefront", "cross-border-ecommerce"],
     ["shipbob", "cross-border-ecommerce"],

package/src/core/provider-setup.d.ts

@@ -18,6 +18,8 @@ export type ProviderAuthSetup = {
     clientFields: OAuthClientConfigFieldDefinition[];
     clientSetup?: OAuth2AuthDefinition["clientSetup"];
     scopes: string[];
+    /** Additional scopes for explicit selection; requestedScopes replaces the default list. */
+    optionalScopes?: string[];
     authorizationOptions?: OAuth2AuthDefinition["authorizationOptions"];
 };
 /** Describe the inputs accepted by the existing connection and OAuth-client APIs. */

package/src/core/provider-setup.js

@@ -13,6 +13,7 @@ export function describeProviderAuth(auth) {
                 clientFields: oauthClientFields(auth),
                 clientSetup: auth.clientSetup,
                 scopes: auth.scopes,
+                optionalScopes: auth.optionalScopes,
                 authorizationOptions: auth.authorizationOptions,
             };
     }

package/src/core/request.d.ts

@@ -1,3 +1,4 @@
+import type { TransitFileUpload, TransitFileWriter } from "./types.ts";
 /**
  * Query parameter values accepted by provider HTTP helpers.
  */
@@ -37,6 +38,25 @@ export interface BoundedResponseBytesOptions {
  * Read a response body into memory while enforcing a byte limit.
  */
 export declare function readBoundedResponseBytes(response: Response, options: BoundedResponseBytesOptions): Promise<Uint8Array>;
+export interface TransitResponseOptions {
+    /** Name the stored transit file carries. */
+    name: string;
+    mimeType: string;
+    /** Used in the size-limit error, as in {@link readBoundedResponseBytes}. */
+    fieldName: string;
+    createError: (message: string) => Error;
+    signal?: AbortSignal;
+}
+/**
+ * Store a provider download in transit storage without holding it in memory.
+ *
+ * A backend that accepts unknown-length streams (the filesystem store) gets the
+ * response body piped straight to disk, so memory stays flat whatever the file
+ * size or the number of concurrent downloads; the store enforces `maxBytes` as
+ * the bytes arrive. Any other backend keeps the buffered path, bounded exactly
+ * as before.
+ */
+export declare function storeResponseInTransit(response: Response, transitFiles: TransitFileWriter, options: TransitResponseOptions): Promise<TransitFileUpload>;
 export interface PublicHttpUrlOptions {
     fieldName: string;
     createError: (message: string) => Error;

package/src/core/request.js

@@ -105,6 +105,53 @@ export async function readBoundedResponseBytes(response, options) {
     }
     return bytes;
 }
+/**
+ * Store a provider download in transit storage without holding it in memory.
+ *
+ * A backend that accepts unknown-length streams (the filesystem store) gets the
+ * response body piped straight to disk, so memory stays flat whatever the file
+ * size or the number of concurrent downloads; the store enforces `maxBytes` as
+ * the bytes arrive. Any other backend keeps the buffered path, bounded exactly
+ * as before.
+ */
+export async function storeResponseInTransit(response, transitFiles, options) {
+    const limits = {
+        maxBytes: transitFiles.maxBytes,
+        fieldName: options.fieldName,
+        createError: options.createError,
+        signal: options.signal,
+    };
+    // `File.type` lower-cases the type and empties it entirely when any code
+    // point falls outside U+0020–U+007E. Mirror that so the streamed path stores
+    // exactly what the buffered path does, whatever the server sent.
+    const mimeType = /[^\u0020-\u007e]/.test(options.mimeType) ? "" : options.mimeType.toLowerCase();
+    if (!transitFiles.createFromStream || !response.body) {
+        const bytes = await readBoundedResponseBytes(response, limits);
+        return await transitFiles.create(new File([Uint8Array.from(bytes)], options.name, { type: mimeType }));
+    }
+    options.signal?.throwIfAborted();
+    const contentLength = parseContentLength(response.headers.get("content-length"));
+    if (contentLength !== undefined && contentLength > limits.maxBytes) {
+        void response.body.cancel().catch(() => undefined);
+        assertMaxBytes(contentLength, limits);
+    }
+    try {
+        return await transitFiles.createFromStream({
+            body: response.body,
+            name: options.name.toWellFormed(),
+            mimeType,
+            signal: options.signal,
+        });
+    }
+    catch (error) {
+        // The store reports an over-limit stream as its own `file_too_large`;
+        // callers keep seeing the error they chose, as on the buffered path.
+        if (error?.code === "file_too_large") {
+            throw options.createError(`${options.fieldName} exceeds ${limits.maxBytes} bytes`);
+        }
+        throw error;
+    }
+}
 // Egress targets are classified into three tiers for the SSRF guard:
 //
 //   - "reserved" (localHostnames, cloudMetadataHostnames, localHostnameSuffixes,

package/src/core/types.d.ts

@@ -116,8 +116,20 @@ export type OAuth2AuthDefinition = {
     tokenUrl: string;
     /** Provider token endpoint used to refresh an access token. Defaults to tokenUrl. */
     refreshTokenUrl?: string;
-    /** OAuth scopes joined with spaces into the authorization URL `scope` parameter. */
+    /**
+     * Provider token revocation endpoint (RFC 7009). When set, a disconnect that
+     * asks for it (`revoke: true`) posts the connection's refresh token (else its
+     * access token) there once the credential is deleted, so the grant ends at
+     * the provider as well as here. Inert otherwise.
+     */
+    revocationUrl?: string;
+    /** Default OAuth scopes when no requestedScopes or authorization options are selected. */
     scopes: string[];
+    /**
+     * Additional scopes available for explicit selection through requestedScopes or authorization
+     * options. requestedScopes replaces the default list; default scopes are not added automatically.
+     */
+    optionalScopes?: string[];
     /** Selectable provider-native OAuth scopes for programmatic connections. */
     authorizationOptions?: OAuthAuthorizationOption[];
     /** Separator used when joining OAuth scopes. Defaults to a space. */
@@ -322,6 +334,8 @@ export interface TransitFileStore {
     /** Available only on backends that can store unknown-length streams without buffering the file. */
     createFromStream?(file: TransitFileStream): Promise<TransitFileUpload>;
     read(fileId: string): Promise<TransitFileRead>;
+    /** Stream a stored file for provider uploads without materializing its bytes. */
+    response?(fileId: string): Promise<Response>;
     delete(fileId: string): Promise<boolean>;
 }
 export type TransitFileWriter = TransitFileStore;

package/src/marketplace/marketplace-service.d.ts

@@ -44,6 +44,11 @@ export interface MarketplaceSnapshot {
     compatibleActions: ReadonlySet<string>;
     actionsByService: ReadonlyMap<string, ReadonlySet<string>>;
 }
+export interface MarketplaceDiscoverySummary {
+    version: 1;
+    name: string;
+    actions: string[];
+}
 export interface MarketplaceState {
     configured: boolean;
     enabled: boolean;
@@ -74,6 +79,7 @@ export declare class MarketplaceService {
     initialize(): Promise<void>;
     getState(): MarketplaceState;
     getSnapshot(): MarketplaceSnapshot | undefined;
+    getDefaultDiscovery(signal?: AbortSignal): Promise<MarketplaceDiscoverySummary>;
     supportsAction(actionId: string): boolean;
     configure(input: MarketplaceConfigInput): Promise<MarketplaceState>;
     remove(): Promise<void>;

package/src/marketplace/marketplace-service.js

@@ -58,6 +58,10 @@ export class MarketplaceService {
     getSnapshot() {
         return this.snapshot;
     }
+    async getDefaultDiscovery(signal) {
+        const discovery = await this.discover(defaultMarketplaceDiscoveryUrl, signal);
+        return { version: 1, name: discovery.name, actions: discovery.actions };
+    }
     supportsAction(actionId) {
         return this.snapshot?.compatibleActions.has(actionId) ?? false;
     }
@@ -191,7 +195,7 @@ export class MarketplaceService {
             compatibleProviderCount: 0,
         };
     }
-    async discover(discoveryUrl) {
+    async discover(discoveryUrl, signal) {
         try {
             return await requestRemote({
                 url: discoveryUrl,
@@ -200,7 +204,7 @@ export class MarketplaceService {
                 requireHttps: false,
                 allowTrustedHosts: true,
                 timeoutMs: 15_000,
-                init: { headers: { accept: "application/json" } },
+                init: { headers: { accept: "application/json" }, signal },
             }, async (response, signal) => {
                 if (!response.ok)
                     throw new MarketplaceError("marketplace_unavailable", `Marketplace discovery failed with HTTP ${response.status}.`, 502);

package/src/oauth/oauth-client-config-service.js

@@ -53,7 +53,7 @@ export class OAuthClientConfigService {
             service,
             clientId,
             clientSecret,
-            requestedScopes: normalizeRequestedScopes(service, input.requestedScopes, auth.scopes),
+            requestedScopes: normalizeRequestedScopes(service, input.requestedScopes, requestableScopes(auth)),
             redirectUri: normalizeRedirectUri(input.redirectUri),
             extra: normalizeCredentialValues({
                 fields: filterClientConfigFields(auth.clientConfigFields, "extra"),
@@ -111,7 +111,7 @@ export class OAuthClientConfigService {
     /** Resolve the scopes an authorization request should send. */
     getEffectiveScopes(service, config) {
         const auth = this.getOAuthDefinition(service);
-        return filterDeclaredScopes(config.requestedScopes, auth.scopes) ?? [...auth.scopes];
+        return filterDeclaredScopes(config.requestedScopes, requestableScopes(auth)) ?? [...auth.scopes];
     }
     listOAuthProviders() {
         return this.catalog.providers.flatMap((provider) => {
@@ -141,7 +141,7 @@ export class OAuthClientConfigService {
                 .map((field) => field.key),
             auth,
             requestedScopes: config?.requestedScopes ?? null,
-            effectiveScopes: filterDeclaredScopes(config?.requestedScopes, auth.scopes) ?? [...auth.scopes],
+            effectiveScopes: filterDeclaredScopes(config?.requestedScopes, requestableScopes(auth)) ?? [...auth.scopes],
             extra: config?.extra ?? {},
         };
     }
@@ -286,6 +286,14 @@ function filterDeclaredScopes(requestedScopes, providerScopes) {
     const filtered = [...new Set(requestedScopes.map((scope) => scope.trim()))].filter((scope) => declaredScopes.has(scope));
     return filtered.length > 0 ? filtered : undefined;
 }
+/**
+ * The scopes a client config may request: the provider's declared scopes and
+ * its optional ones. A config that names none is answered with the declared
+ * scopes alone, so an optional scope joins a request only by name.
+ */
+function requestableScopes(auth) {
+    return auth.optionalScopes?.length ? [...auth.scopes, ...auth.optionalScopes] : auth.scopes;
+}
 function readStringRecord(value) {
     const record = optionalRecord(value);
     if (!record) {

package/src/oauth/oauth-credential-refresh-service.d.ts

@@ -4,8 +4,22 @@ import type { OAuthClientConfigService } from "./oauth-client-config-service.ts"
 type OAuthCredential = Extract<ResolvedCredential, {
     authType: "oauth2";
 }>;
+/**
+ * What a disconnect did about the grant at the provider: `done` when the
+ * provider's revocation endpoint accepted the token, `failed` when it did not
+ * (or could not be reached) — the credential is deleted locally either way —
+ * `unsupported` when the provider declares no revocation endpoint or the
+ * connection held no OAuth token to revoke, and `skipped` when the caller
+ * asked to keep the grant (`revoke: false`).
+ */
+export type OAuthRevocationOutcome = "done" | "failed" | "unsupported" | "skipped";
 export interface IOAuthCredentialRefresher {
     refresh(service: string, credential: OAuthCredential): Promise<OAuthCredential>;
+    /**
+     * Revoke the credential at the provider's `revocationUrl`: `done` or
+     * `unsupported` (none declared); a refusal or an unreachable endpoint throws.
+     */
+    revoke?(service: string, credential: OAuthCredential): Promise<"done" | "unsupported">;
 }
 /**
  * Refreshes stored OAuth credentials using the user-provided local OAuth app.
@@ -15,5 +29,11 @@ export declare class OAuthCredentialRefreshService implements IOAuthCredentialRe
     private readonly providerLoader?;
     constructor(clientConfigs: OAuthClientConfigService, providerLoader?: IProviderLoader);
     refresh(service: string, credential: OAuthCredential): Promise<OAuthCredential>;
+    /**
+     * Revoke the refresh token, or the access token when none was issued, using
+     * the client configuration the credential was minted under. The provider
+     * determines whether related tokens and the underlying grant are revoked.
+     */
+    revoke(service: string, credential: OAuthCredential): Promise<"done" | "unsupported">;
 }
 export {};

package/src/oauth/oauth-credential-refresh-service.js

@@ -2,7 +2,7 @@ import { ConnectionError } from "../connection-service.js";
 import { optionalRecord, stringRecord } from "../core/cast.js";
 import { providerFetch } from "../providers/provider-runtime.js";
 import { readOAuthClientConfigMetadata } from "./oauth-client-config-service.js";
-import { expiresAtFromLifetime, requestRefreshToken } from "./oauth-token.js";
+import { expiresAtFromLifetime, requestRefreshToken, requestTokenRevocation } from "./oauth-token.js";
 /**
  * Refreshes stored OAuth credentials using the user-provided local OAuth app.
  */
@@ -20,7 +20,9 @@ export class OAuthCredentialRefreshService {
             throw new ConnectionError("oauth_client_config_required", `Configure an OAuth client for ${service} before refreshing its token.`);
         }
         const refreshToken = credential.refreshToken ?? "";
-        const createError = (message) => new ConnectionError("oauth_token_refresh_failed", message);
+        const createError = (message, failure) => failure?.errorCode === "invalid_grant" && (failure.status === 400 || failure.status === 401)
+            ? new ConnectionError("oauth_reauth_required", `OAuth authorization is no longer valid. Reconnect ${service}.`)
+            : new ConnectionError("oauth_token_refresh_failed", message);
         const providerOAuth = await this.providerLoader?.loadProviderOAuthRuntime?.(service);
         let refreshed;
         if (providerOAuth?.refreshAccessToken) {
@@ -47,7 +49,14 @@ export class OAuthCredentialRefreshService {
                 createError,
             });
         }
-        const expiresIn = refreshed.expiresAt === undefined ? credential.metadata.expires_in : refreshed.metadata.expires_in;
+        // A provider runtime may report an absolute expiry without a lifetime, or a
+        // lifetime without an expiry. Keep a usable lifetime from this response and
+        // fall back to the stored one, so dropping it cannot leave a later refresh
+        // that omits `expires_in` without any expiry to derive. `expiresAtFromLifetime`
+        // is the shared usability rule: non-positive and absurd lifetimes are unusable.
+        const expiresIn = expiresAtFromLifetime(refreshed.metadata.expires_in) === undefined
+            ? credential.metadata.expires_in
+            : refreshed.metadata.expires_in;
         return {
             ...refreshed,
             authType: "oauth2",
@@ -71,6 +80,52 @@ export class OAuthCredentialRefreshService {
             },
         };
     }
+    /**
+     * Revoke the refresh token, or the access token when none was issued, using
+     * the client configuration the credential was minted under. The provider
+     * determines whether related tokens and the underlying grant are revoked.
+     */
+    async revoke(service, credential) {
+        let auth;
+        try {
+            auth = this.clientConfigs.getOAuthDefinition(service);
+        }
+        catch {
+            return "unsupported";
+        }
+        if (!auth.revocationUrl) {
+            return "unsupported";
+        }
+        const token = credential.refreshToken || credential.accessToken;
+        if (!token) {
+            return "unsupported";
+        }
+        const createError = (message) => new ConnectionError("oauth_token_revocation_failed", message);
+        const config = readOAuthClientConfigMetadata(service, credential.metadata) ?? (await this.clientConfigs.getConfig(service));
+        let revocationUrl;
+        if (config) {
+            revocationUrl = this.clientConfigs.resolveEndpointUrl(service, auth.revocationUrl, config);
+        }
+        else if (auth.revocationUrl.includes("{")) {
+            // A templated endpoint ({tenant}) needs the client configuration that
+            // filled it in at sign-in; without one there is nowhere to post to.
+            throw createError(`Configure an OAuth client for ${service} before revoking its token.`);
+        }
+        else {
+            revocationUrl = auth.revocationUrl;
+        }
+        await requestTokenRevocation({
+            revocationUrl,
+            token,
+            tokenTypeHint: credential.refreshToken ? "refresh_token" : "access_token",
+            clientId: config?.clientId,
+            clientSecret: config?.clientSecret,
+            tokenRequestFields: auth.tokenRequestFields,
+            tokenEndpointAuthMethod: auth.tokenEndpointAuthMethod,
+            createError,
+        });
+        return "done";
+    }
 }
 function readOAuthRefreshParameters(providerSecret) {
     const value = optionalRecord(providerSecret?.oauthRefreshParameters);

package/src/oauth/oauth-flow-service.d.ts

@@ -21,6 +21,7 @@ export interface OAuthAuthorizationCompleteInput {
     state: string;
     code: string;
     callbackParameters?: Record<string, string>;
+    callbackQuery?: string;
     signal?: AbortSignal;
 }
 /**
@@ -29,6 +30,7 @@ export interface OAuthAuthorizationCompleteInput {
 export interface OAuthAuthorizationState {
     service: string;
     connectionName?: string;
+    retirementGeneration: string;
     state: string;
     createdAt: string;
     pkceCodeVerifier?: string;