@oomol-lab/open-connector 1.8.0 → 1.9.0

package/src/server/api/openapi.js

@@ -47,7 +47,7 @@ const oauthClientConfigRequestSchema = jsonSchema.object({
     }),
     requestedScopes: jsonSchema.array(jsonSchema.string(), {
         minItems: 1,
-        description: "Non-empty provider-declared scope subset to request. Omit to use every provider default.",
+        description: "Complete non-empty scope list replacing the provider defaults. Each scope must be declared in scopes or optionalScopes. Omit to request every default scope and no optional scopes.",
     }),
     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.",
@@ -1138,6 +1138,21 @@ function createConnectionPath() {
         delete: {
             tags: ["Connections"],
             summary: "Disconnect a provider.",
+            requestBody: {
+                required: false,
+                content: {
+                    "application/json": {
+                        schema: jsonSchema.object({
+                            connectionName: jsonSchema.string("Named connection. Defaults to default."),
+                            revoke: {
+                                type: "boolean",
+                                default: false,
+                                description: "Also request OAuth token revocation after deleting the local credential. Related connections may lose authorization depending on the provider's revocation policy.",
+                            },
+                        }),
+                    },
+                },
+            },
             responses: {
                 200: jsonResponse({
                     anyOf: [
@@ -1145,8 +1160,9 @@ function createConnectionPath() {
                         jsonSchema.object({
                             service: jsonSchema.string(),
                             configured: { const: false, type: "boolean" },
+                            revoked: jsonSchema.stringEnum("What the disconnect did about the grant at the provider: done (its revocation endpoint accepted the token), failed (it refused or could not be reached; the credential is deleted here regardless), unsupported (no revocation endpoint declared, no OAuth token held, or a SaaS connection) or skipped (the request body did not set revoke: true, the default).", ["done", "failed", "unsupported", "skipped"]),
                         }, {
-                            required: ["service", "configured"],
+                            required: ["service", "configured", "revoked"],
                             description: "Disconnected provider summary.",
                         }),
                     ],
@@ -1177,7 +1193,7 @@ function createOAuthAuthorizationPath() {
                             }),
                             requestedScopes: jsonSchema.array(jsonSchema.string(), {
                                 minItems: 1,
-                                description: "Optional non-empty provider-declared scope subset to request.",
+                                description: "Optional complete non-empty scope list replacing the provider defaults. Each scope must be declared in scopes or optionalScopes; default scopes are not added automatically.",
                             }),
                             redirectUri: jsonSchema.string({
                                 description: "Optional redirect URI registered with the connection-scoped OAuth app instead of the runtime callback. Same rules as OAuthClientConfigRequest.redirectUri.",
@@ -1222,7 +1238,7 @@ function createOAuthConfigPath() {
         put: {
             tags: ["OAuth"],
             summary: "Upsert local OAuth client configuration.",
-            description: "Open-source users provide their own OAuth app. requestedScopes may narrow the provider-declared defaults but cannot add scopes. Additional extra fields are declared by provider catalog auth metadata.",
+            description: "Open-source users provide their own OAuth app. requestedScopes replaces the default scope list with an explicit selection from the provider's scopes and optionalScopes; default scopes are not added automatically. Omit it to use the defaults without optional scopes. Undeclared scopes are refused. Additional extra fields are declared by provider catalog auth metadata.",
             requestBody: {
                 required: true,
                 content: {
@@ -1440,7 +1456,8 @@ function connectionManagementPaths() {
                 docsUrl: jsonSchema.optional(jsonSchema.string("Provider page where the OAuth app is registered.")),
                 steps: jsonSchema.stringArray("Ordered setup steps."),
             })),
-            scopes: jsonSchema.optional(jsonSchema.stringArray("Provider scopes the connector requests.")),
+            scopes: jsonSchema.optional(jsonSchema.stringArray("Default provider scopes when no explicit selection is made.")),
+            optionalScopes: jsonSchema.optional(jsonSchema.stringArray("Additional provider scopes for explicit selection. requestedScopes replaces the default scope list.")),
             authorizationOptions: jsonSchema.optional(jsonSchema.array(authorizationOption)),
         })),
         oauthClient: jsonSchema.optional(jsonSchema.object("Default OAuth source configuration; present when the provider supports OAuth.", {

package/src/server/api/pattern-example.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Conservative pattern sampler for action-guide examples.
+ *
+ * A JSON Schema `pattern` is a validation contract; an example that does not
+ * match it is rejected by the runtime. This module turns the common shapes
+ * (digit runs, fixed-width identifiers, dates, times, literal prefixes, and
+ * alternations of them) into a short literal that matches, and returns
+ * `undefined` for constructs it cannot sample safely (lookbehind,
+ * backreferences, Unicode property escapes) so the caller can fall back.
+ */
+/**
+ * Sample a short literal that matches `pattern`, or `undefined` when the
+ * pattern uses constructs this sampler does not support. Lookaheads are checked against the result, without searching for a match.
+ *
+ * `minLength` grows unbounded quantifiers (`+`, `*`, `{n,}`) until the sample
+ * reaches the schema's minimum, when the pattern allows it. A `minLength`
+ * beyond the sample bound returns `undefined` so the caller can fall back to a
+ * placeholder that still honors it.
+ */
+export declare function samplePattern(pattern: string, options?: {
+    minLength?: number;
+}): string | undefined;

package/src/server/api/pattern-example.js

@@ -0,0 +1,413 @@
+/**
+ * Conservative pattern sampler for action-guide examples.
+ *
+ * A JSON Schema `pattern` is a validation contract; an example that does not
+ * match it is rejected by the runtime. This module turns the common shapes
+ * (digit runs, fixed-width identifiers, dates, times, literal prefixes, and
+ * alternations of them) into a short literal that matches, and returns
+ * `undefined` for constructs it cannot sample safely (lookbehind,
+ * backreferences, Unicode property escapes) so the caller can fall back.
+ */
+const negatedClassCandidates = ["a", "0", "A", "z", "_", "-", "+", ".", ":", "1", "x", "q", "/", "?", "#"];
+/** Longer samples are not useful as guide examples and can come from pathological quantifiers. */
+const maximumSampleLength = 512;
+/**
+ * Sample a short literal that matches `pattern`, or `undefined` when the
+ * pattern uses constructs this sampler does not support. Lookaheads are checked against the result, without searching for a match.
+ *
+ * `minLength` grows unbounded quantifiers (`+`, `*`, `{n,}`) until the sample
+ * reaches the schema's minimum, when the pattern allows it. A `minLength`
+ * beyond the sample bound returns `undefined` so the caller can fall back to a
+ * placeholder that still honors it.
+ */
+export function samplePattern(pattern, options = {}) {
+    const requestedMinLength = options.minLength ?? 0;
+    if (requestedMinLength > maximumSampleLength) {
+        return undefined;
+    }
+    try {
+        const root = new PatternParser(pattern).parse();
+        const minLength = requestedMinLength;
+        const growth = new Map();
+        const budget = { remaining: maximumSampleLength };
+        let sample = generateSample(root, minLength, growth, budget);
+        const growthLimit = minLength * 2 + 8;
+        for (let step = 0; sample.length < minLength && step < growthLimit; step += 1) {
+            const growable = findGrowable(root, growth);
+            if (!growable) {
+                break;
+            }
+            growth.set(growable, (growth.get(growable) ?? 0) + 1);
+            budget.remaining = maximumSampleLength;
+            sample = generateSample(root, minLength, growth, budget);
+        }
+        // Unanchored patterns and prefix patterns can satisfy minLength by padding.
+        if (sample.length < minLength) {
+            const padded = sample.padEnd(minLength, "a");
+            if (matchesPattern(pattern, padded)) {
+                sample = padded;
+            }
+        }
+        if (sample.length > maximumSampleLength) {
+            return undefined;
+        }
+        return matchesPattern(pattern, sample) ? sample : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function matchesPattern(pattern, sample) {
+    try {
+        // The runtime validator compiles patterns with the `u` flag (@cfworker/json-schema).
+        return new RegExp(pattern, "u").test(sample);
+    }
+    catch {
+        return false;
+    }
+}
+function generateSample(node, targetLength, growth, budget) {
+    switch (node.kind) {
+        case "literal": {
+            if (node.value.length > budget.remaining) {
+                throw new PatternTooLongError();
+            }
+            budget.remaining -= node.value.length;
+            return node.value;
+        }
+        case "sequence":
+            return node.nodes.map((child) => generateSample(child, targetLength, growth, budget)).join("");
+        case "alternation": {
+            // Prefer the shortest branch that already reaches the target, so a
+            // minimum length can pick a longer alternative instead of failing.
+            const start = budget.remaining;
+            const samples = [];
+            for (const branch of node.branches) {
+                budget.remaining = start;
+                try {
+                    samples.push(generateSample(branch, targetLength, growth, budget));
+                }
+                catch (error) {
+                    if (!(error instanceof PatternTooLongError)) {
+                        throw error;
+                    }
+                }
+            }
+            if (samples.length === 0) {
+                throw new PatternTooLongError();
+            }
+            const longEnough = samples.filter((candidate) => candidate.length >= targetLength);
+            const chosen = (longEnough.length > 0 ? longEnough : samples).reduce((best, candidate) => candidate.length < best.length ? candidate : best);
+            budget.remaining = start - chosen.length;
+            return chosen;
+        }
+        case "repeat": {
+            const count = Math.min(node.max, node.min + (growth.get(node) ?? 0));
+            const atom = generateSample(node.node, 0, growth, { remaining: maximumSampleLength });
+            const total = atom.length * count;
+            if (total > budget.remaining) {
+                throw new PatternTooLongError();
+            }
+            budget.remaining -= total;
+            return atom.repeat(count);
+        }
+    }
+}
+/** The first repeat that can still grow and would add characters. */
+function findGrowable(node, growth) {
+    switch (node.kind) {
+        case "literal":
+            return undefined;
+        case "sequence":
+            for (const child of node.nodes) {
+                const growable = findGrowable(child, growth);
+                if (growable) {
+                    return growable;
+                }
+            }
+            return undefined;
+        case "alternation":
+            for (const branch of node.branches) {
+                const growable = findGrowable(branch, growth);
+                if (growable) {
+                    return growable;
+                }
+            }
+            return undefined;
+        case "repeat": {
+            if (node.min + (growth.get(node) ?? 0) >= node.max) {
+                return undefined;
+            }
+            return generateSample(node.node, 0, growth, { remaining: maximumSampleLength }).length > 0 ? node : undefined;
+        }
+    }
+}
+class PatternTooLongError extends Error {
+}
+class PatternParser {
+    pattern;
+    index = 0;
+    constructor(pattern) {
+        this.pattern = pattern;
+    }
+    parse() {
+        const node = this.parseAlternation();
+        if (this.index < this.pattern.length) {
+            throw new Error("unexpected token");
+        }
+        return node;
+    }
+    parseAlternation() {
+        const branches = [this.parseSequence()];
+        while (this.peek() === "|") {
+            this.index += 1;
+            branches.push(this.parseSequence());
+        }
+        return branches.length === 1 ? branches[0] : { kind: "alternation", branches };
+    }
+    parseSequence() {
+        const nodes = [];
+        while (this.index < this.pattern.length) {
+            const character = this.pattern[this.index];
+            if (character === "|" || character === ")") {
+                break;
+            }
+            nodes.push(this.parseQuantified());
+        }
+        return nodes.length === 1 ? nodes[0] : { kind: "sequence", nodes };
+    }
+    parseQuantified() {
+        const atom = this.parseAtom();
+        const quantifier = this.parseQuantifier();
+        return quantifier ? { kind: "repeat", node: atom, ...quantifier } : atom;
+    }
+    parseAtom() {
+        const character = this.pattern[this.index];
+        if (character === undefined) {
+            throw new Error("unexpected end of pattern");
+        }
+        if (character === "(") {
+            this.index += 1;
+            if (this.pattern.startsWith("?=", this.index) || this.pattern.startsWith("?!", this.index)) {
+                // Assertions contribute no characters. The final regex check still decides
+                // whether the sample is usable; there is no search to satisfy an assertion.
+                this.index += 2;
+                this.parseAlternation();
+                this.expect(")");
+                return { kind: "literal", value: "" };
+            }
+            if (this.pattern.startsWith("?:", this.index)) {
+                this.index += 2;
+            }
+            else if (this.pattern[this.index] === "?") {
+                throw new Error("unsupported group");
+            }
+            const node = this.parseAlternation();
+            this.expect(")");
+            return node;
+        }
+        if (character === "[") {
+            return this.parseClass();
+        }
+        if (character === ".") {
+            this.index += 1;
+            return { kind: "literal", value: "a" };
+        }
+        if (character === "^" || character === "$") {
+            this.index += 1;
+            return { kind: "literal", value: "" };
+        }
+        if (character === "\\") {
+            return this.parseEscape();
+        }
+        if (character === "*" || character === "+" || character === "?") {
+            throw new Error("quantifier without atom");
+        }
+        this.index += 1;
+        return { kind: "literal", value: character };
+    }
+    parseQuantifier() {
+        const character = this.peek();
+        if (character === "?") {
+            this.index += 1;
+            return { min: 0, max: 1 };
+        }
+        if (character === "*") {
+            this.index += 1;
+            return { min: 0, max: Number.POSITIVE_INFINITY };
+        }
+        if (character === "+") {
+            this.index += 1;
+            return { min: 1, max: Number.POSITIVE_INFINITY };
+        }
+        if (character !== "{") {
+            return undefined;
+        }
+        const match = /^\{(\d+)(,(\d*))?\}/.exec(this.pattern.slice(this.index));
+        if (!match) {
+            return undefined;
+        }
+        this.index += match[0].length;
+        const min = Number(match[1]);
+        if (match[2] === undefined) {
+            return { min, max: min };
+        }
+        const max = match[3] ? Number(match[3]) : Number.POSITIVE_INFINITY;
+        if (max < min) {
+            throw new Error("invalid quantifier range");
+        }
+        return { min, max };
+    }
+    parseEscape() {
+        this.index += 1;
+        const character = this.pattern[this.index];
+        if (character === undefined) {
+            throw new Error("dangling escape");
+        }
+        this.index += 1;
+        return { kind: "literal", value: readEscape(character, this) };
+    }
+    parseClass() {
+        this.expect("[");
+        let negated = false;
+        if (this.peek() === "^") {
+            negated = true;
+            this.index += 1;
+        }
+        const items = [];
+        let first = true;
+        while (true) {
+            if (this.index >= this.pattern.length) {
+                throw new Error("unterminated class");
+            }
+            if (this.pattern[this.index] === "]" && !first) {
+                this.index += 1;
+                break;
+            }
+            first = false;
+            const item = this.parseClassItem();
+            const next = this.pattern[this.index + 1];
+            if (this.pattern[this.index] === "-" && next !== undefined && next !== "]" && item.character !== undefined) {
+                this.index += 1;
+                const end = this.parseClassItem();
+                if (end.character === undefined || end.character < item.character) {
+                    throw new Error("invalid character range");
+                }
+                items.push(classRange(item.character, end.character));
+            }
+            else {
+                items.push(item);
+            }
+        }
+        if (items.length === 0) {
+            throw new Error("empty class");
+        }
+        if (!negated) {
+            return { kind: "literal", value: items[0].sample };
+        }
+        const value = negatedClassCandidates.find((candidate) => !items.some((item) => item.test(candidate)));
+        if (value === undefined) {
+            throw new Error("no sample for negated class");
+        }
+        return { kind: "literal", value };
+    }
+    parseClassItem() {
+        const character = this.pattern[this.index];
+        if (character === undefined) {
+            throw new Error("unexpected end of class");
+        }
+        if (character !== "\\") {
+            this.index += 1;
+            return classLiteral(character);
+        }
+        this.index += 1;
+        const escaped = this.pattern[this.index];
+        if (escaped === undefined) {
+            throw new Error("dangling class escape");
+        }
+        this.index += 1;
+        const sets = {
+            d: classSet("0", (value) => /\d/.test(value)),
+            D: classSet("a", (value) => !/\d/.test(value)),
+            w: classSet("a", (value) => /[A-Za-z0-9_]/.test(value)),
+            W: classSet("-", (value) => !/[A-Za-z0-9_]/.test(value)),
+            s: classSet(" ", (value) => /\s/.test(value)),
+            S: classSet("a", (value) => !/\s/.test(value)),
+        };
+        const set = sets[escaped];
+        if (set) {
+            return set;
+        }
+        return classLiteral(readEscape(escaped, this));
+    }
+    /** Read `length` hex digits at the cursor, or `undefined` when they are absent. */
+    readHex(length) {
+        const digits = this.pattern.slice(this.index, this.index + length);
+        if (digits.length !== length || !/^[0-9a-fA-F]+$/.test(digits)) {
+            return undefined;
+        }
+        this.index += length;
+        return digits;
+    }
+    peek() {
+        return this.pattern[this.index];
+    }
+    expect(character) {
+        if (this.pattern[this.index] !== character) {
+            throw new Error(`expected ${character}`);
+        }
+        this.index += 1;
+    }
+}
+function readEscape(character, parser) {
+    const single = {
+        d: "0",
+        D: "a",
+        w: "a",
+        W: "-",
+        s: " ",
+        S: "a",
+        n: "\n",
+        t: "\t",
+        r: "\r",
+        f: "\f",
+        v: "\v",
+    };
+    const value = single[character];
+    if (value !== undefined) {
+        return value;
+    }
+    if (/[1-9]/.test(character)) {
+        throw new Error("backreference");
+    }
+    if (character === "p" || character === "P") {
+        throw new Error("unicode property escape");
+    }
+    if (character === "b" || character === "B") {
+        throw new Error("word boundary");
+    }
+    if (character === "k") {
+        throw new Error("named backreference");
+    }
+    if (character === "c") {
+        throw new Error("control escape");
+    }
+    if (character === "u" || character === "x") {
+        const length = character === "u" ? 4 : 2;
+        const digits = parser.readHex(length);
+        if (digits === undefined) {
+            throw new Error("invalid hex escape");
+        }
+        return String.fromCodePoint(Number.parseInt(digits, 16));
+    }
+    return character;
+}
+function classLiteral(character) {
+    return { sample: character, character, test: (value) => value === character };
+}
+function classRange(from, to) {
+    return { sample: from, test: (value) => value >= from && value <= to };
+}
+function classSet(sample, test) {
+    return { sample, test };
+}

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

@@ -158,7 +158,10 @@ export function mapConnectionErrorStatus(error) {
     if (error.code === "unknown_service" || error.code === "connection_not_found") {
         return 404;
     }
-    if (error.code === "oauth_token_expired" || error.code === "oauth_refresh_unavailable") {
+    if (error.code === "oauth_token_expired" ||
+        error.code === "oauth_reauth_required" ||
+        error.code === "oauth_refresh_unavailable" ||
+        error.code === "oauth_token_refresh_failed") {
         return 409;
     }
     return 400;
@@ -190,7 +193,10 @@ function mapExecutionErrorStatus(code, details) {
     if (code === "internal_error" || code === "provider_error" || code === "executor_unavailable") {
         return 500;
     }
-    if (code === "oauth_token_expired" || code === "oauth_refresh_unavailable") {
+    if (code === "oauth_token_expired" ||
+        code === "oauth_reauth_required" ||
+        code === "oauth_refresh_unavailable" ||
+        code === "oauth_token_refresh_failed") {
         return 409;
     }
     if (code === "connection_not_found" || code === "unknown_service" || code === "unknown_action") {

package/src/server/connect-app.d.ts

@@ -1,5 +1,6 @@
 import type { CatalogStore } from "../catalog-store.ts";
 import type { ActionPolicyService } from "../core/action-policy.ts";
+import type { ProviderHttpDispatchOptions } from "../core/provider-http-dispatch.ts";
 import type { RuntimeLogger, TransitFileUpload } from "../core/types.ts";
 import type { IProviderLoader } from "../providers/provider-loader.ts";
 import type { RuntimeJwtVerifier } from "./api/runtime-jwt.ts";
@@ -12,6 +13,7 @@ import { TriggerMaintenance } from "../triggers/maintenance.ts";
 export interface ConnectAppOptions {
     catalog: CatalogStore;
     providerLoader: IProviderLoader;
+    providerHttpDispatch?: ProviderHttpDispatchOptions;
     runtimeDatabase: RuntimeDatabase;
     transitFiles: ITransitFileService;
     uploadTransitFile?: (request: Request) => Promise<TransitFileUpload>;
@@ -28,6 +30,7 @@ export interface ConnectAppOptions {
     computeRuntimeAuthConfigured?: boolean;
     compressApiResponses?: boolean;
     serveDocumentation?: boolean;
+    oauthCloseDelaySeconds?: number;
 }
 export interface ConnectApp {
     saasCleanup: SaasCleanupService;

package/src/server/connect-app.js

@@ -46,6 +46,7 @@ export async function createConnectApp(options) {
         isCustomClientConfigAvailable: (service) => options.secretCodec.encrypted && isCustomClientConfigAllowed(service),
     });
     const connections = new ConnectionService({
+        providerHttpDispatch: options.providerHttpDispatch,
         catalog: options.catalog,
         oauthCredentials: new OAuthCredentialRefreshService(oauthClientConfigs, options.providerLoader),
         providerLoader: options.providerLoader,
@@ -54,6 +55,7 @@ export async function createConnectApp(options) {
         marketplace,
     });
     const actions = new ActionRunner({
+        providerHttpDispatch: options.providerHttpDispatch,
         catalog: options.catalog,
         providerLoader: options.providerLoader,
         connections,
@@ -64,6 +66,7 @@ export async function createConnectApp(options) {
         marketplace,
     });
     const triggers = new TriggerRunner({
+        providerHttpDispatch: options.providerHttpDispatch,
         catalog: options.catalog,
         providerLoader: options.providerLoader,
         connections,
@@ -86,6 +89,7 @@ export async function createConnectApp(options) {
             logger: options.logger,
         }),
         app: new ConnectServer({
+            providerHttpDispatch: options.providerHttpDispatch,
             catalog: options.catalog,
             publicOrigin: options.publicOrigin,
             providerLoader: options.providerLoader,
@@ -125,6 +129,7 @@ export async function createConnectApp(options) {
             saasOAuth,
             compressApiResponses: options.compressApiResponses,
             serveDocumentation: options.serveDocumentation,
+            oauthCloseDelaySeconds: options.oauthCloseDelaySeconds,
         }).createApp(),
         runtimeAuthConfigured: Boolean(options.runtimeToken) ||
             Boolean(options.verifyRuntimeJwt) ||

package/src/server/connect-server.d.ts

@@ -1,6 +1,7 @@
 import type { CatalogStore } from "../catalog-store.ts";
 import type { ConnectionService } from "../connection-service.ts";
 import type { ActionSearchIndexProvider } from "../core/action-search.ts";
+import type { ProviderHttpDispatchOptions } from "../core/provider-http-dispatch.ts";
 import type { RuntimeLogger, TransitFileUpload } from "../core/types.ts";
 import type { MarketplaceService } from "../marketplace/marketplace-service.ts";
 import type { IProviderLoader } from "../providers/provider-loader.ts";
@@ -29,6 +30,7 @@ export declare function preloadOptionalServerModules(): Promise<void>;
  * Dependencies required to construct the local connector server.
  */
 export interface IConnectServerOptions {
+    providerHttpDispatch?: ProviderHttpDispatchOptions;
     catalog: CatalogStore;
     /** Public origin of this runtime, used for the HTTP request examples in Action guides. */
     publicOrigin: string;
@@ -51,6 +53,8 @@ export interface IConnectServerOptions {
     logger?: RuntimeLogger;
     compressApiResponses?: boolean;
     serveDocumentation?: boolean;
+    /** Seconds the OAuth completion page waits before closing its window. `0` closes it as soon as it loads. */
+    oauthCloseDelaySeconds?: number;
     marketplace?: MarketplaceService;
     saasProject?: SaasProjectService;
     saas?: SaasExecutionService;
@@ -70,6 +74,8 @@ export declare class ConnectServer {
     createApp(): Hono;
     private listProviderSummaries;
     private configureMarketplace;
+    private getMarketplaceDiscovery;
+    private writeMarketplaceError;
     private deleteMarketplace;
     private updateProviderPreference;
     private getRuntimeProviderSetup;