@zackbart/connecta 0.24.1 → 0.24.3

package/dist/connector-access.js

@@ -0,0 +1,79 @@
+export const POOL_NAME_RE = /^[a-z0-9_-]+$/;
+const CONNECTOR_ID_RE = /^[a-z0-9_-]+$/;
+// MCP does not restrict tool names, and remote servers ship spaced and
+// non-ASCII ones. Only control characters are refused, so a grant for a
+// legitimately named tool cannot 403 the whole identity at request time.
+const TOOL_ADDRESS_RE = /^[a-z0-9_-]+\..{1,256}$/su;
+const hasControlCharacter = (value) => [...value].some((ch) => {
+    const code = ch.codePointAt(0);
+    return code < 0x20 || code === 0x7f;
+});
+/**
+ * Normalize a grant list. A bare connector id grants every tool on that
+ * connector; a `connector.tool` address grants one tool. Grants are additive,
+ * so a bare id beside addresses for the same connector means the whole
+ * connector. Anything else — an unknown shape, an empty tool name, a
+ * non-string — throws, and the caller decides whether that is a construction
+ * failure or a 403: a grant that cannot be parsed must never fail open.
+ */
+export function parseConnectorAccess(value) {
+    if (value === "all")
+        return { connectorIds: "all" };
+    if (!Array.isArray(value))
+        throw new Error("invalid connector permission");
+    const whole = new Set();
+    const partial = new Map();
+    for (const entry of value) {
+        if (typeof entry !== "string")
+            throw new Error("invalid connector permission");
+        if (CONNECTOR_ID_RE.test(entry)) {
+            whole.add(entry);
+            continue;
+        }
+        if (!TOOL_ADDRESS_RE.test(entry) || hasControlCharacter(entry))
+            throw new Error("invalid connector permission");
+        const dot = entry.indexOf(".");
+        const connectorId = entry.slice(0, dot);
+        const tools = partial.get(connectorId) ?? new Set();
+        tools.add(entry.slice(dot + 1));
+        partial.set(connectorId, tools);
+    }
+    for (const id of whole)
+        partial.delete(id);
+    const connectorIds = [...new Set([...whole, ...partial.keys()])];
+    return partial.size > 0
+        ? { connectorIds, toolAccess: partial }
+        : { connectorIds };
+}
+/**
+ * The view a pool endpoint serves: the pool's grants, never wider than the
+ * identity's own. A connector or tool outside either side is gone; a
+ * connector whose tool intersection is empty is gone too, so the pool can
+ * only narrow what the identity resolver already allowed.
+ */
+export function intersectAccess(ceiling, pool) {
+    if (pool.connectorIds === "all")
+        return ceiling;
+    const allowedIds = ceiling.connectorIds === "all"
+        ? null
+        : new Set(ceiling.connectorIds);
+    const connectorIds = [];
+    const toolAccess = new Map();
+    for (const id of pool.connectorIds) {
+        if (allowedIds && !allowedIds.has(id))
+            continue;
+        const fromPool = pool.toolAccess?.get(id);
+        const fromCeiling = ceiling.toolAccess?.get(id);
+        if (fromPool && fromCeiling) {
+            const both = new Set([...fromPool].filter((name) => fromCeiling.has(name)));
+            if (both.size === 0)
+                continue;
+            toolAccess.set(id, both);
+        }
+        else if (fromPool ?? fromCeiling) {
+            toolAccess.set(id, (fromPool ?? fromCeiling));
+        }
+        connectorIds.push(id);
+    }
+    return toolAccess.size > 0 ? { connectorIds, toolAccess } : { connectorIds };
+}

package/dist/connectors/api.js

@@ -1,3 +1,4 @@
+import { ConnectorCallError, networkErrorCode, unavailableCallError, } from "../errors.js";
 import { compileValidator, validateToolInput } from "../validate.js";
 export function defined(value) {
     return Object.fromEntries(Object.entries(value).filter(([, item]) => item !== undefined));
@@ -74,7 +75,16 @@ export function api(id, opts) {
             // its first await never sits handler-less for the thenable-adoption
             // microtask — workerd and vitest both report that gap as an unhandled
             // rejection even though the caller catches the failure.
-            return await tool.handler(input, ctx);
+            try {
+                return await tool.handler(input, ctx);
+            }
+            catch (error) {
+                // A handler owns its destinations. ctx.baseUrl is Connecta's inbound
+                // URL, so it must never masquerade as the failed downstream host.
+                if (error instanceof ConnectorCallError || !networkErrorCode(error))
+                    throw error;
+                throw unavailableCallError(error);
+            }
         },
     };
 }

package/dist/connectors/guarded-fetch.d.ts

@@ -51,7 +51,7 @@ interface GuardedResponse {
         parseError: unknown;
     }>;
 }
-/** Parse a decimal `Retry-After` header in seconds into milliseconds. */
+/** Parse delta-seconds or an HTTP-date into a non-negative wait window. */
 export declare function retryAfterMs(headers: Headers): number | undefined;
 /**
  * Turn one response into the provider's own result, or throw the provider's

package/dist/connectors/guarded-fetch.js

@@ -1,14 +1,20 @@
 /** See documentation/connectors.md#the-guarded-fetch-transport. Web APIs only. */
-import { ConnectorCallError } from "../errors.js";
-/** Parse a decimal `Retry-After` header in seconds into milliseconds. */
+import { ConnectorCallError, unavailableCallError } from "../errors.js";
+/** Parse delta-seconds or an HTTP-date into a non-negative wait window. */
 export function retryAfterMs(headers) {
     const raw = headers.get("retry-after");
     if (!raw)
         return undefined;
     const seconds = Number(raw.trim());
-    if (!Number.isFinite(seconds) || seconds < 0)
+    if (Number.isFinite(seconds)) {
+        return seconds < 0 ? undefined : Math.trunc(seconds * 1000);
+    }
+    // Require the HTTP-date shape, so Date.parse cannot reinterpret "-1" as
+    // a calendar date on runtimes that accept loose date strings.
+    if (!/^[A-Za-z]{3}, \d{2} [A-Za-z]{3} \d{4} \d{2}:\d{2}:\d{2} GMT$/.test(raw.trim()))
         return undefined;
-    return Math.trunc(seconds * 1000);
+    const date = Date.parse(raw);
+    return Number.isFinite(date) ? Math.max(0, date - Date.now()) : undefined;
 }
 /** Statuses that instruct a client to re-send somewhere else. Never followed. */
 const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
@@ -144,13 +150,20 @@ function boundedResponse(provider, response, limit) {
             });
         return read;
     };
+    let readText;
+    const text = () => {
+        readText ??= stream
+            ? bytes().then((body) => decoder.decode(body))
+            : response.text().then((body) => {
+                const size = encoder.encode(body).length;
+                if (size > limit)
+                    throw oversized(provider, limit, `${size} bytes`);
+                return body;
+            });
+        return readText;
+    };
     const json = async () => {
-        // No stream means no bytes to count: a stand-in that answers `json()`
-        // directly is taken at its word, which is the one accessor on the one
-        // path where the ceiling cannot be applied.
-        if (!stream)
-            return await response.json();
-        const body = decoder.decode(await bytes());
+        const body = await text();
         return body.trim() === "" ? undefined : JSON.parse(body);
     };
     return {
@@ -158,15 +171,7 @@ function boundedResponse(provider, response, limit) {
         ok: response.ok,
         headers: response.headers,
         bytes,
-        async text() {
-            if (stream)
-                return decoder.decode(await bytes());
-            const body = await response.text();
-            const size = encoder.encode(body).length;
-            if (size > limit)
-                throw oversized(provider, limit, `${size} bytes`);
-            return body;
-        },
+        text,
         json,
         jsonResult: () => jsonResult(json),
     };
@@ -230,7 +235,9 @@ export function guardedFetch(options) {
             });
         }
         catch (cause) {
-            throw new ConnectorCallError("unavailable", `Could not reach the ${provider} API: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+            if (cause instanceof ConnectorCallError)
+                throw cause;
+            throw unavailableCallError(cause, url.href, `Could not reach the ${provider} API.`);
         }
         if (REDIRECT_STATUSES.has(response.status)) {
             await response.body?.cancel().catch(() => { });

package/dist/connectors/remote-mcp.js

@@ -1,7 +1,7 @@
-import { Client, isInputRequiredResult, specTypeSchemas, StreamableHTTPClientTransport, UnauthorizedError, } from "@modelcontextprotocol/client";
+import { Client, ProtocolError, SdkHttpError, isInputRequiredResult, specTypeSchemas, StreamableHTTPClientTransport, UnauthorizedError, } from "@modelcontextprotocol/client";
 import { KvOAuthProvider, OAuthRefreshCoordinator, } from "../auth/downstream-oauth.js";
 import { MAX_CATALOG_TOOLS } from "../catalog-limits.js";
-import { ConnectorCallError, msg } from "../errors.js";
+import { boundedEchoText, ConnectorCallError, msg, unavailableCallError, } from "../errors.js";
 import { CONNECTA_VERSION } from "../version.js";
 /**
  * Apply a maintained provider's slot copy and header framing to credential
@@ -157,6 +157,28 @@ async function terminateSession(transport, logger, connectorId) {
         });
     });
 }
+/** Classify protocol/status facts; provider prose never decides retryability. */
+function downstreamCallError(error) {
+    if (error instanceof ProtocolError && error.code === -32602) {
+        return new ConnectorCallError("invalid_args", boundedEchoText(error.message));
+    }
+    if (error instanceof SdkHttpError && error.status >= 400 && error.status < 500) {
+        let message = error.message;
+        if (typeof error.data.text === "string") {
+            try {
+                const body = JSON.parse(error.data.text);
+                const detail = body?.message ?? body?.error?.message ?? body?.error_description;
+                if (typeof detail === "string")
+                    message = detail;
+            }
+            catch {
+                // Non-JSON refusals still retain a bounded diagnostic.
+            }
+        }
+        return new ConnectorCallError(error.status === 429 ? "rate_limited" : error.status === 408 ? "timeout" : "connector_call_failed", boundedEchoText(message));
+    }
+    return error;
+}
 const encoder = new TextEncoder();
 /** Base64 of a UTF-8 string, Web-API only so the core still runs on workerd. */
 function base64Utf8(value) {
@@ -266,10 +288,18 @@ export function redirectSafeFetch(connectorId, policy = "none", baseFetch = fetc
         const seen = new Set([current.href]);
         let hops = 0;
         while (true) {
-            const response = await baseFetch(current, {
-                ...init,
-                redirect: "manual",
-            });
+            let response;
+            try {
+                response = await baseFetch(current, {
+                    ...init,
+                    redirect: "manual",
+                });
+            }
+            catch (cause) {
+                if (cause instanceof ConnectorCallError)
+                    throw cause;
+                throw unavailableCallError(cause, current.href);
+            }
             if (!REDIRECT_STATUSES.has(response.status))
                 return response;
             const location = response.headers.get("location");
@@ -549,19 +579,38 @@ export function remoteMcp(id, opts) {
         state.credentialDigest = null;
         // `closed` is deliberately not cleared — see ConnectionState.
     };
-    const closeHalf = async (state) => {
+    // The context has no deferred-work hook. Detached exits start this bounded
+    // best-effort tail immediately; closeScope awaits its own tail so the core
+    // can pass it to the runtime's deferred channel.
+    const closingSessions = new WeakMap();
+    const closeConnection = (client, transport, logger) => {
+        const previous = transport && closingSessions.get(transport);
+        if (previous)
+            return previous;
+        const closing = (async () => {
+            try {
+                if (transport)
+                    await terminateSession(transport, logger, id);
+                if (client)
+                    await client.close();
+                else
+                    await transport?.close();
+            }
+            catch {
+                // Local close cannot replace the operation's result.
+            }
+        })();
+        // A connect can acquire a session after an early close. Deduplicate only
+        // once that session exists, so its late abandonment still sends DELETE.
+        if (transport?.sessionId)
+            closingSessions.set(transport, closing);
+        return closing;
+    };
+    const closeHalf = (state, ctx) => {
         const client = state.client;
         const transport = state.transport;
         reset(state);
-        try {
-            if (client)
-                await client.close();
-            else
-                await transport?.close();
-        }
-        catch {
-            // The discarded state remains authoritative if local close fails.
-        }
+        void closeConnection(client, transport, ctx.logger);
     };
     const ensureConnected = async (ctx, state) => {
         // A 401 after connect is a verdict for the whole request scope, not merely
@@ -581,7 +630,7 @@ export function remoteMcp(id, opts) {
             if (provider.isOperatorDisconnectedGeneration(oauthGeneration)) {
                 const connecting = state.connecting;
                 void connecting?.catch(() => { });
-                await closeHalf(state);
+                closeHalf(state, ctx);
                 throw operatorDisconnectedError();
             }
         }
@@ -592,7 +641,7 @@ export function remoteMcp(id, opts) {
             if (state.closed)
                 throw scopeEndedError();
             if (oauthGeneration !== state.connectedGeneration) {
-                reset(state);
+                closeHalf(state, ctx);
             }
         }
         // The static-credential counterpart of the epoch read above, and
@@ -618,7 +667,7 @@ export function remoteMcp(id, opts) {
                     throw scopeEndedError();
                 const connecting = state.connecting;
                 void connecting?.catch(() => { });
-                await closeHalf(state);
+                closeHalf(state, ctx);
             }
         }
         if (state.closed)
@@ -629,13 +678,8 @@ export function remoteMcp(id, opts) {
             let attempt;
             attempt = (async () => {
                 const ownsAttempt = () => state.connecting === attempt && !state.closed;
-                const abandon = async (owner) => {
-                    try {
-                        await owner.close();
-                    }
-                    catch {
-                        // The attempt is detached either way.
-                    }
+                const abandon = (client, transport) => {
+                    void closeConnection(client, transport, ctx.logger);
                     throw scopeEndedError();
                 };
                 // Let the assignment immediately below this async IIFE publish
@@ -666,7 +710,7 @@ export function remoteMcp(id, opts) {
                 });
                 const t = buildTransport(ctx, provider, credentialFramed);
                 if (!ownsAttempt())
-                    await abandon(t);
+                    abandon(null, t);
                 state.transport = t;
                 try {
                     await c.connect(t);
@@ -675,7 +719,7 @@ export function remoteMcp(id, opts) {
                     // that race anyway, close the resulting client rather than
                     // resurrecting a session in the detached state object.
                     if (!ownsAttempt())
-                        await abandon(c);
+                        abandon(c, t);
                     // A force re-auth that landed WHILE we were connecting wiped the
                     // credentials this client just bound to. Discard it rather than
                     // cache a stale-isolate connection.
@@ -685,24 +729,22 @@ export function remoteMcp(id, opts) {
                         // connect succeeded but before this client is cached. Discard the
                         // client on that side of the await too.
                         if (!ownsAttempt())
-                            await abandon(c);
+                            abandon(c, t);
                         if (generation !== genAtStart) {
-                            try {
-                                await c.close();
-                            }
-                            catch {
-                                // discarding either way
-                            }
+                            void closeConnection(c, t, ctx.logger);
                             throw new UnauthorizedError("Connector was re-authorized during connect; reconnect required.");
                         }
                     }
                     if (!ownsAttempt())
-                        await abandon(c);
+                        abandon(c, t);
                     state.client = c;
                     state.connectedGeneration = genAtStart;
                     state.authRequired = false;
                 }
                 catch (err) {
+                    void closeConnection(c, t, ctx.logger);
+                    if (ownsAttempt())
+                        state.transport = null;
                     // Only a real 401/UnauthorizedError means auth is the problem — a
                     // network error on an oauth connector must surface as "error", not
                     // "auth_required".
@@ -748,7 +790,7 @@ export function remoteMcp(id, opts) {
             // client/transport exists. Reset is unconditional because KV may already
             // be fenced behind a newer epoch after a cleanup error.
             void connecting?.catch(() => { });
-            await closeHalf(state);
+            closeHalf(state, ctx);
         }
     };
     const connector = {
@@ -976,7 +1018,7 @@ export function remoteMcp(id, opts) {
                         state.authRequired = true;
                     throw authRequiredError(err);
                 }
-                throw err;
+                throw downstreamCallError(err);
             }
         },
         async closeScope(ctx) {
@@ -993,20 +1035,7 @@ export function remoteMcp(id, opts) {
             const client = state.client;
             const transport = state.transport;
             reset(state);
-            // Ask the downstream to drop its session first — closing only aborts our
-            // side, and the DELETE that frees the server's rides on the very
-            // AbortSignal the close is about to trip.
-            if (transport)
-                await terminateSession(transport, ctx.logger, id);
-            // Client.close() owns its connected transport. During an unfinished or
-            // failed connect there is no cached client yet, so close the transport
-            // directly to abort/release that half-open session.
-            if (client) {
-                await client.close();
-            }
-            else {
-                await transport?.close();
-            }
+            await closeConnection(client, transport, ctx.logger);
         },
         async status(ctx) {
             const state = stateFor(ctx);
@@ -1054,7 +1083,9 @@ export function remoteMcp(id, opts) {
             }
             await provider.clearPending();
             // Reset so the next use reconnects with the freshly stored tokens.
-            reset(state);
+            if (!state.transport)
+                state.transport = t;
+            closeHalf(state, ctx);
         },
     };
     if (opts.auth?.type === "oauth") {

package/dist/errors.d.ts

@@ -39,6 +39,17 @@ export declare function boundedEchoText(value: string, maxBytes?: number): strin
 export declare function echoedCallArgs(args: unknown): {
     args?: unknown;
 };
+/** Optional transport diagnostics; never a URL path or raw runtime message. */
+interface UnavailableDetails {
+    /** HTTP(S) origin only, at most 253 UTF-8 bytes. */
+    host?: string;
+    /** Validated network errno or `timeout`, at most 32 bytes. */
+    code?: string;
+}
+/** Runtime fields only: provider prose cannot supply an errno or a deadline. */
+export declare function networkErrorCode(error: unknown): string | undefined;
+/** Use at a fetch boundary where the destination and transport failure are known. */
+export declare function unavailableCallError(cause: unknown, host?: string, message?: string): ConnectorCallError;
 /** Agent-visible recovery class attached only to `auth_required` failures. */
 export type AuthRecoveryMode = "oauth" | "operator_config" | "unavailable";
 /**
@@ -67,15 +78,20 @@ export declare class ConnectorCallError extends Error {
     readonly retryAfterMs: number | undefined;
     /** Bounded schema findings for `invalid_args`; never submitted values. */
     readonly validation: ArgumentValidationDetails | undefined;
+    /** Sanitized transport diagnostics for `unavailable` only. */
+    readonly details: UnavailableDetails | undefined;
     constructor(code: ConnectorCallErrorCode, message: string, opts?: {
         retryable?: boolean;
         retryAfterMs?: number;
         cause?: unknown;
         validation?: ArgumentValidationDetails;
+        details?: UnavailableDetails;
     });
 }
 /** The `error` object surfaced in value-mode call results and rejected promises. */
 export interface CallErrorDetails {
+    /** Sanitized transport diagnostics, absent when the runtime supplies none. */
+    details?: UnavailableDetails;
     code: string;
     message: string;
     retryable: boolean;
@@ -151,3 +167,4 @@ export declare function framingError(code: string, message: string): CallErrorDe
  */
 export declare function classifyCallError(err: unknown, fallbackCode?: string): CallErrorDetails;
 export declare function msg(err: unknown): string;
+export {};

package/dist/errors.js

@@ -102,6 +102,58 @@ function boundedValidation(details) {
         ...(truncated ? { truncated: true } : {}),
     };
 }
+const NETWORK_ERROR_CODES = new Set([
+    "ECONNREFUSED", "ENOTFOUND", "ECONNRESET", "ETIMEDOUT", "EAI_AGAIN",
+    "EAI_FAIL", "EHOSTUNREACH", "ENETUNREACH", "ENETDOWN", "EHOSTDOWN",
+    "ECONNABORTED", "EPIPE", "EACCES", "EPERM",
+    "UND_ERR_CONNECT_TIMEOUT", "UND_ERR_HEADERS_TIMEOUT", "UND_ERR_BODY_TIMEOUT",
+    "UND_ERR_SOCKET", "timeout",
+]);
+function networkCode(value) {
+    return typeof value === "string" && value.length <= 32 && NETWORK_ERROR_CODES.has(value)
+        ? value
+        : undefined;
+}
+function sanitizedUnavailableDetails(details) {
+    if (!details)
+        return undefined;
+    let host;
+    if (typeof details.host === "string") {
+        try {
+            const url = new URL(details.host);
+            if ((url.protocol === "https:" || url.protocol === "http:") &&
+                echoEncoder.encode(url.origin).length <= 253)
+                host = url.origin;
+        }
+        catch {
+            // An invalid or oversized origin is absent, never a clipped destination.
+        }
+    }
+    const code = networkCode(details.code);
+    return host || code ? { ...(host ? { host } : {}), ...(code ? { code } : {}) } : undefined;
+}
+/** Runtime fields only: provider prose cannot supply an errno or a deadline. */
+export function networkErrorCode(error) {
+    if (!error || typeof error !== "object")
+        return undefined;
+    if (error instanceof Error &&
+        (error.name === "AbortError" || error.name === "TimeoutError")) {
+        return "timeout";
+    }
+    const runtime = error;
+    const cause = runtime.cause;
+    return networkCode(runtime.code) ?? (cause && typeof cause === "object"
+        ? networkCode(cause.code)
+        : undefined);
+}
+/** Use at a fetch boundary where the destination and transport failure are known. */
+export function unavailableCallError(cause, host, message = "Could not reach the downstream service.") {
+    const code = networkErrorCode(cause);
+    return new ConnectorCallError("unavailable", message, {
+        cause,
+        details: { ...(host ? { host } : {}), ...(code ? { code } : {}) },
+    });
+}
 const RETRYABLE_BY_CODE = {
     timeout: true,
     rate_limited: true,
@@ -146,12 +198,16 @@ export class ConnectorCallError extends Error {
     retryAfterMs;
     /** Bounded schema findings for `invalid_args`; never submitted values. */
     validation;
+    /** Sanitized transport diagnostics for `unavailable` only. */
+    details;
     constructor(code, message, opts = {}) {
         super(message, opts.cause !== undefined ? { cause: opts.cause } : undefined);
         this.name = "ConnectorCallError";
         this.code = code;
         this.retryable = opts.retryable ?? RETRYABLE_BY_CODE[code];
         this.retryAfterMs = normalizeRetryAfterMs(opts.retryAfterMs);
+        this.details =
+            code === "unavailable" ? sanitizedUnavailableDetails(opts.details) : undefined;
         this.validation =
             code === "invalid_args" ? boundedValidation(opts.validation) : undefined;
     }
@@ -164,6 +220,7 @@ export class ConnectorCallError extends Error {
  * trusts the flag would cheerfully retry a refusal forever.
  */
 const NEVER_RETRYABLE_FRAMING = new Set([
+    "result_processing_failed",
     "unknown_address",
     "unknown_tool",
     "ambiguous_tool_alias",
@@ -203,6 +260,7 @@ export function classifyCallError(err, fallbackCode = "connector_call_failed") {
                 ? { retryAfterMs: err.retryAfterMs }
                 : {}),
             ...(err.validation ? { validation: err.validation } : {}),
+            ...(err.details ? { details: err.details } : {}),
         };
     }
     // An aborted fetch rejects with a DOMException named "AbortError" whose