@oomol-lab/open-connector 1.9.0 → 1.9.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oomol-lab/open-connector",
-  "version": "1.9.0",
+  "version": "1.9.2",
   "description": "Embeddable Open Connector runtime for Node.js and Bun.",
   "license": "Apache-2.0",
   "type": "module",
@@ -17,6 +17,7 @@
   "dependencies": {
     "@aws-sdk/client-s3": "^3.1151.0",
     "@cfworker/json-schema": "^4.1.1",
+    "@cloudflare/workers-oauth-provider": "^1.2.3",
     "@hono/node-server": "^2.1.5",
     "@modelcontextprotocol/client": "^2.3.1",
     "@modelcontextprotocol/server": "^2.3.1",

package/src/connection-service.js

@@ -3,6 +3,30 @@ import { apiKeyCredentialFields } from "./core/provider-setup.js";
 import { providerFetch, ProviderDispatchRequestError, withProviderHttpDispatchResult, } from "./providers/provider-runtime.js";
 export const defaultConnectionName = "default";
 const connectionNamePattern = /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/;
+const OAUTH_REFRESH_PERSIST_ATTEMPTS = 3;
+/**
+ * Lays a refresh result onto the connection's current credential. A refresh owns the token
+ * fields and the metadata keys it changed; everything else on `current` belongs to whoever
+ * bumped the revision and is kept.
+ */
+function mergeRefreshedOAuthCredential(current, spent, refreshed) {
+    const metadata = { ...current.metadata };
+    for (const [key, value] of Object.entries(refreshed.metadata)) {
+        if (JSON.stringify(value) !== JSON.stringify(spent.metadata[key]))
+            metadata[key] = value;
+    }
+    // A successful refresh proves the authorization is live, so a concurrent refusal's mark is stale.
+    delete metadata.oauthReauthRequired;
+    return {
+        ...current,
+        accessToken: refreshed.accessToken,
+        tokenType: refreshed.tokenType,
+        expiresAt: refreshed.expiresAt,
+        refreshToken: refreshed.refreshToken,
+        providerSecret: refreshed.providerSecret,
+        metadata,
+    };
+}
 /**
  * Coordinates local provider connection state.
  *
@@ -504,7 +528,15 @@ export class ConnectionService {
         if (!this.oauthCredentials) {
             throw new ConnectionError("oauth_refresh_unavailable", `${service} OAuth access token expired and this runtime cannot refresh it.`);
         }
-        const refreshKey = `${connection.id}:${connection.revision}`;
+        // Single-flight on the refresh token being spent, not the row revision: a single-use
+        // (rotating) refresh token must reach the provider once even when an unrelated write
+        // bumps the revision mid-refresh. A new authorization must refresh independently,
+        // even when the provider reuses the same refresh token across reconnects.
+        const refreshKey = JSON.stringify([
+            connection.id,
+            credential.refreshToken,
+            credential.metadata.oauthAuthorizationId,
+        ]);
         const currentRefresh = this.oauthCredentialRefreshes.get(refreshKey);
         if (currentRefresh) {
             return currentRefresh;
@@ -539,17 +571,29 @@ export class ConnectionService {
             }
             throw error;
         }
-        const updated = await this.store.updateCredential({
-            id,
-            revision,
-            service,
-            connectionName,
-            credential: nextCredential,
-        }, true);
-        if (!updated) {
-            throw new ConnectionError("connection_not_found", `${service} connection changed while its OAuth credential was refreshing. Retry the action.`);
+        // The provider has now spent the old refresh token. With rotating single-use refresh
+        // tokens, discarding `nextCredential` loses the connection for good, so a lost
+        // revision race re-reads the row and lands the refreshed token fields on the latest
+        // revision, as long as that row still holds the credential this refresh spent.
+        let target = { ...connection, source: "local", credential: nextCredential };
+        for (let attempt = 0; attempt < OAUTH_REFRESH_PERSIST_ATTEMPTS; attempt++) {
+            if (await this.store.updateCredential(target, true))
+                return target.credential;
+            const current = await this.store.get(service, connectionName);
+            if (current?.source === "saas" ||
+                current?.id !== id ||
+                current.credential.authType !== "oauth2" ||
+                current.credential.refreshToken !== credential.refreshToken ||
+                current.credential.metadata.oauthAuthorizationId !== credential.metadata.oauthAuthorizationId) {
+                // Deleted, converted, reconnected, or already rotated elsewhere: never overwrite it.
+                break;
+            }
+            target = {
+                ...current,
+                credential: mergeRefreshedOAuthCredential(current.credential, credential, nextCredential),
+            };
         }
-        return nextCredential;
+        throw new ConnectionError("connection_not_found", `${service} connection changed while its OAuth credential was refreshing. Retry the action.`);
     }
     async runCredentialValidator(service, validate, signal) {
         this.assertNotCancelled(signal);

package/src/core/json-schema.d.ts

@@ -6,12 +6,19 @@ export type JsonSchemaOptions = {
     description?: string;
     default?: unknown;
     format?: string;
+    not?: JsonSchema;
 };
 type ObjectOptions = JsonSchemaOptions & {
     required?: string[];
     optional?: readonly string[];
     additionalProperties?: boolean | JsonSchema;
     defs?: Record<string, JsonSchema>;
+    minProperties?: number;
+    maxProperties?: number;
+    propertyNames?: JsonSchema;
+    allOf?: JsonSchema[];
+    anyOf?: JsonSchema[];
+    oneOf?: JsonSchema[];
 };
 type ArrayOptions = JsonSchemaOptions & {
     minItems?: number;
@@ -28,6 +35,7 @@ type NumberOptions = JsonSchemaOptions & {
     minimum?: number;
     maximum?: number;
     exclusiveMinimum?: number;
+    multipleOf?: number;
 };
 /**
  * JSON Schema helpers for provider action contracts.
@@ -48,7 +56,7 @@ export declare const jsonSchema: {
     unknown(description: string): JsonSchema;
     url(description: string): JsonSchema;
     email(description: string, options?: Omit<StringOptions, "description" | "format">): JsonSchema;
-    nullableString(description: string, options?: Omit<JsonSchemaOptions, "description">): JsonSchema;
+    nullableString(description: string, options?: Omit<StringOptions, "description">): JsonSchema;
     nullableInteger(description: string, options?: Omit<NumberOptions, "description">): JsonSchema;
     nullableNumber(description: string, options?: Omit<NumberOptions, "description">): JsonSchema;
     nullableBoolean(description: string, options?: Omit<JsonSchemaOptions, "description">): JsonSchema;
@@ -56,13 +64,13 @@ export declare const jsonSchema: {
     date(description: string, options?: Omit<StringOptions, "description" | "format">): JsonSchema;
     uuid(description: string): JsonSchema;
     stringPattern(pattern: string, options?: JsonSchemaOptions): JsonSchema;
-    stringEnum(valuesOrDescription: readonly string[] | string, optionsOrValues?: JsonSchemaOptions | readonly string[]): JsonSchema;
+    stringEnum(valuesOrDescription: readonly string[] | string, optionsOrValues?: JsonSchemaOptions | readonly string[], maybeOptions?: JsonSchemaOptions): JsonSchema;
     integer(optionsOrDescription?: NumberOptions | string, maybeOptions?: Omit<NumberOptions, "description">): JsonSchema;
     positiveInteger(description: string, options?: Omit<NumberOptions, "description" | "minimum">): JsonSchema;
     nonNegativeInteger(description: string, options?: Omit<NumberOptions, "description" | "minimum">): JsonSchema;
     number(optionsOrDescription?: NumberOptions | string, maybeOptions?: Omit<NumberOptions, "description">): JsonSchema;
     boolean(optionsOrDescription?: JsonSchemaOptions | string): JsonSchema;
-    literal(value: string | number | boolean, options?: JsonSchemaOptions): JsonSchema;
+    literal(value: string | number | boolean | null, options?: JsonSchemaOptions): JsonSchema;
     optional(schema: JsonSchema): JsonSchema;
     describe(schema: JsonSchema, description: string): JsonSchema;
     withDefault(schema: JsonSchema, defaultValue: unknown): JsonSchema;

package/src/core/json-schema.js

@@ -28,6 +28,10 @@ export const jsonSchema = {
             schema.required = required;
         if (options.defs)
             schema.$defs = options.defs;
+        for (const key of ["minProperties", "maxProperties", "propertyNames", "allOf", "anyOf", "oneOf"]) {
+            if (options[key] !== undefined)
+                schema[key] = options[key];
+        }
         return withOptions(schema, options);
     },
     requiredObject(description, properties) {
@@ -110,10 +114,10 @@ export const jsonSchema = {
     stringPattern(pattern, options = {}) {
         return withOptions({ type: "string", pattern }, options);
     },
-    stringEnum(valuesOrDescription, optionsOrValues = {}) {
+    stringEnum(valuesOrDescription, optionsOrValues = {}, maybeOptions = {}) {
         const values = typeof valuesOrDescription === "string" ? optionsOrValues : valuesOrDescription;
         const options = typeof valuesOrDescription === "string"
-            ? { description: valuesOrDescription }
+            ? { ...maybeOptions, description: valuesOrDescription }
             : optionsOrValues;
         return withOptions({ type: "string", enum: values }, options);
     },
@@ -128,6 +132,8 @@ export const jsonSchema = {
             schema.maximum = options.maximum;
         if (options.exclusiveMinimum != null)
             schema.exclusiveMinimum = options.exclusiveMinimum;
+        if (options.multipleOf != null)
+            schema.multipleOf = options.multipleOf;
         return withOptions(schema, options);
     },
     positiveInteger(description, options = {}) {
@@ -147,6 +153,8 @@ export const jsonSchema = {
             schema.maximum = options.maximum;
         if (options.exclusiveMinimum != null)
             schema.exclusiveMinimum = options.exclusiveMinimum;
+        if (options.multipleOf != null)
+            schema.multipleOf = options.multipleOf;
         return withOptions(schema, options);
     },
     boolean(optionsOrDescription = {}) {
@@ -154,7 +162,7 @@ export const jsonSchema = {
         return withOptions({ type: "boolean" }, options);
     },
     literal(value, options = {}) {
-        return withOptions({ const: value, type: typeof value }, options);
+        return withOptions({ const: value, type: value === null ? "null" : typeof value }, options);
     },
     optional(schema) {
         const optionalSchema = { ...schema };
@@ -313,5 +321,7 @@ function withOptions(schema, options) {
         schema.default = options.default;
     if (options.format)
         schema.format = options.format;
+    if (options.not !== undefined)
+        schema.not = options.not;
     return schema;
 }

package/src/core/provider-error-codes.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The error codes a provider may put in `ProviderRequestError`'s `code`
+ * argument. Every other code `mapExecutionErrorStatus` knows is raised by the
+ * connection, policy or dispatch layer, and a provider that borrowed one would
+ * answer with a status that has nothing to do with what its upstream said.
+ */
+export declare const providerErrorCodes: readonly ["authorization_failed", "insufficient_credit", "invalid_input", "provider_error", "rate_limited"];
+/** Error codes owned by provider execution. */
+export type ProviderErrorCode = (typeof providerErrorCodes)[number];

package/src/core/provider-error-codes.js

@@ -0,0 +1,13 @@
+/**
+ * The error codes a provider may put in `ProviderRequestError`'s `code`
+ * argument. Every other code `mapExecutionErrorStatus` knows is raised by the
+ * connection, policy or dispatch layer, and a provider that borrowed one would
+ * answer with a status that has nothing to do with what its upstream said.
+ */
+export const providerErrorCodes = [
+    "authorization_failed",
+    "insufficient_credit",
+    "invalid_input",
+    "provider_error",
+    "rate_limited",
+];

package/src/core/request.d.ts

@@ -39,6 +39,8 @@ export interface BoundedResponseBytesOptions {
  */
 export declare function readBoundedResponseBytes(response: Response, options: BoundedResponseBytesOptions): Promise<Uint8Array>;
 export interface TransitResponseOptions {
+    /** Optional provider limit, further bounded by the storage limit. */
+    maxBytes?: number;
     /** Name the stored transit file carries. */
     name: string;
     mimeType: string;

package/src/core/request.js

@@ -116,7 +116,7 @@ export async function readBoundedResponseBytes(response, options) {
  */
 export async function storeResponseInTransit(response, transitFiles, options) {
     const limits = {
-        maxBytes: transitFiles.maxBytes,
+        maxBytes: Math.min(transitFiles.maxBytes, options.maxBytes ?? transitFiles.maxBytes),
         fieldName: options.fieldName,
         createError: options.createError,
         signal: options.signal,
@@ -135,9 +135,18 @@ export async function storeResponseInTransit(response, transitFiles, options) {
         void response.body.cancel().catch(() => undefined);
         assertMaxBytes(contentLength, limits);
     }
+    let size = 0;
+    const body = response.body.pipeThrough(new TransformStream({
+        transform(chunk, controller) {
+            options.signal?.throwIfAborted();
+            size += chunk.byteLength;
+            assertMaxBytes(size, limits);
+            controller.enqueue(chunk);
+        },
+    }), { signal: options.signal });
     try {
         return await transitFiles.createFromStream({
-            body: response.body,
+            body,
             name: options.name.toWellFormed(),
             mimeType,
             signal: options.signal,

package/src/mail/imap-smtp/protocol.js

@@ -495,15 +495,16 @@ function normalizeAddress(value) {
         email: readString(record?.address) ?? readString(record?.email),
     };
 }
-function collectBodyParts(bodyStructure) {
+function collectBodyParts(bodyStructure, isRoot = true) {
     const record = toRecord(bodyStructure);
     if (!record) {
         return [];
     }
     const childNodes = record.childNodes;
-    const childParts = Array.isArray(childNodes) ? childNodes.flatMap(collectBodyParts) : [];
+    const childParts = Array.isArray(childNodes) ? childNodes.flatMap((child) => collectBodyParts(child, false)) : [];
     const type = readString(record.type)?.toLowerCase();
-    const part = readString(record.part);
+    // IMAP addresses a single-part root as section 1; ImapFlow leaves its part unset.
+    const part = readString(record.part) ?? (isRoot ? "1" : null);
     if (!type || !part || !type.startsWith("text/") || isAttachment(record)) {
         return childParts;
     }

package/src/oauth/oauth-flow-service.js

@@ -178,6 +178,7 @@ export class OAuthFlowService {
                 if (providerOAuth?.exchangeCode) {
                     return providerOAuth.exchangeCode({
                         code: input.code,
+                        codeVerifier: pending.pkceCodeVerifier,
                         state: pending.state,
                         callbackQuery: input.callbackQuery,
                         callbackParameters: input.callbackParameters,

package/src/oauth/oauth-token.d.ts

@@ -12,6 +12,8 @@ export interface OAuthTokenResult {
 }
 export interface OAuthCodeExchangeInput {
     code: string;
+    /** Verifier belonging to the claimed authorization state. */
+    codeVerifier?: string;
     /** State already claimed by the shared OAuth lifecycle. */
     state?: string;
     /** Original query string, preserving duplicate parameters for signature verification. */

package/src/providers/17track/runtime.js

@@ -1,5 +1,5 @@
 import { compactObject, optionalNumber, optionalRecord, optionalString } from "../../core/cast.js";
-import { createProviderTimeout, isAbortLikeError, providerUserAgent, ProviderRequestError, } from "../provider-runtime.js";
+import { createProviderTimeout, isAbortLikeError, providerUserAgent, ProviderRequestError, providerInputError, providerResponseError, } from "../provider-runtime.js";
 export const seventeenTrackApiBaseUrl = "https://api.17track.net/track/v2.4";
 const seventeenTrackMaxResponseBytes = 1_048_576;
 export const seventeenTrackActionHandlers = {
@@ -55,29 +55,26 @@ async function requestSeventeenTrack(path, body, apiKey, context, phase) {
             throw error;
         }
         const timedOut = timeout.didTimeout() || isAbortLikeError(error);
-        throw providerError("provider_error", timedOut ? "17TRACK request timed out" : error instanceof Error ? error.message : "17TRACK request failed", timedOut ? 504 : 502);
+        throw new ProviderRequestError(timedOut ? 504 : 502, timedOut ? "17TRACK request timed out" : error instanceof Error ? error.message : "17TRACK request failed");
     }
     finally {
         timeout.cleanup();
     }
 }
-function providerError(_code, message, status) {
-    return new ProviderRequestError(status, message);
-}
 async function readPayload(response) {
     const text = await readResponseText(response);
     if (!text.trim()) {
         if (!response.ok) {
             return undefined;
         }
-        throw providerError("provider_error", "17TRACK returned an empty response", 502);
+        throw providerResponseError("17TRACK returned an empty response");
     }
     try {
         return JSON.parse(text);
     }
     catch {
         if (response.ok) {
-            throw providerError("provider_error", `17TRACK returned non-JSON response (${response.status})`, 502);
+            throw providerResponseError(`17TRACK returned non-JSON response (${response.status})`);
         }
         return text;
     }
@@ -113,13 +110,13 @@ async function readResponseText(response) {
     }
 }
 function responseTooLargeError() {
-    return providerError("provider_error", `17TRACK response exceeds ${seventeenTrackMaxResponseBytes} bytes`, 502);
+    return providerResponseError(`17TRACK response exceeds ${seventeenTrackMaxResponseBytes} bytes`);
 }
 function assertSuccessfulEnvelope(payload, phase) {
     const raw = readObject(payload, "body");
     const code = optionalNumber(raw.code);
     if (code === undefined) {
-        throw providerError("provider_error", "17TRACK response is missing code", 502);
+        throw providerResponseError("17TRACK response is missing code");
     }
     const data = optionalRecord(raw.data);
     const errors = Array.isArray(data?.errors) ? data.errors : [];
@@ -131,28 +128,28 @@ function assertSuccessfulEnvelope(payload, phase) {
 function createHttpError(response, payload, phase) {
     const message = readErrorMessage(payload) ?? `17TRACK API request failed with status ${response.status}`;
     if (response.status === 429) {
-        return providerError("rate_limited", message, 429);
+        return new ProviderRequestError(429, message);
     }
     if (response.status === 401 || response.status === 403) {
-        return providerError(phase === "validate" ? "invalid_input" : "credential_expired", message, phase === "validate" ? 400 : response.status);
+        return new ProviderRequestError(phase === "validate" ? 400 : response.status, message);
     }
     if (response.status === 400 || response.status === 422) {
-        return providerError("invalid_input", message, response.status);
+        return new ProviderRequestError(response.status, message);
     }
-    return providerError("provider_error", message, response.status || 502);
+    return new ProviderRequestError(response.status || 502, message);
 }
 function createEmbeddedError(code, message, phase) {
     const detail = message ?? `17TRACK API returned error ${code}`;
     if ([-18010001, -18010002, -18010004, -18010005].includes(code)) {
-        return providerError(phase === "validate" ? "invalid_input" : "credential_expired", detail, phase === "validate" ? 400 : 401);
+        return new ProviderRequestError(phase === "validate" ? 400 : 401, detail);
     }
     if (code === -18019907 || code === -18019908) {
-        return providerError("rate_limited", detail, 429);
+        return new ProviderRequestError(429, detail);
     }
     if (code === -18010003 || [-18019815, -18019816, -18019817].includes(code)) {
-        return providerError("provider_error", detail, 502);
+        return providerResponseError(detail);
     }
-    return providerError("invalid_input", detail, 400);
+    return providerInputError(detail);
 }
 function readErrorMessage(payload) {
     if (typeof payload === "string" && payload.trim()) {
@@ -201,21 +198,21 @@ function normalizeQuotaResponse(payload) {
 }
 function readObjectArray(value, fieldName) {
     if (!Array.isArray(value)) {
-        throw providerError("provider_error", `17TRACK response field ${fieldName} is not an array`, 502);
+        throw providerResponseError(`17TRACK response field ${fieldName} is not an array`);
     }
     return value.map((item) => readObject(item, `${fieldName} item`));
 }
 function readObject(value, fieldName) {
     const object = optionalRecord(value);
     if (!object) {
-        throw providerError("provider_error", `17TRACK response field ${fieldName} is not an object`, 502);
+        throw providerResponseError(`17TRACK response field ${fieldName} is not an object`);
     }
     return object;
 }
 function readNumber(value, fieldName) {
     const number = optionalNumber(value);
     if (number === undefined) {
-        throw providerError("provider_error", `17TRACK response field ${fieldName} is not a number`, 502);
+        throw providerResponseError(`17TRACK response field ${fieldName} is not a number`);
     }
     return number;
 }