@zackbart/connecta 0.28.0 → 0.29.0

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

@@ -0,0 +1,144 @@
+import type { ConnectorContext } from "../types.js";
+/** The methods a hand-written provider surface actually uses. */
+type GuardedMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+export interface GuardedRequest {
+    method: GuardedMethod;
+    /**
+     * Provider-relative path beginning with one `/`, resolved against the base
+     * URL's own path. Never an absolute URL, and never carrying `?` or `#` —
+     * query parameters go in `query`, where they are encoded rather than parsed.
+     */
+    path: string;
+    /**
+     * Search parameters; `undefined` values are dropped, others stringified. An
+     * array repeats its key once per element, in order — the spelling of the key
+     * itself (`ids` or `ids[]`) is the provider's convention, not the helper's.
+     */
+    query?: Record<string, string | number | boolean | readonly (string | number | boolean)[] | undefined>;
+    /**
+     * Per-request headers. `undefined` values are dropped, and a header that
+     * collides with an authentication header is refused rather than allowed to
+     * shadow it.
+     */
+    headers?: Record<string, string | undefined>;
+    /** JSON request body. Serialized here, with the `Content-Type` to match. */
+    body?: unknown;
+    /**
+     * A pre-framed body — `FormData`, text, bytes. Mutually exclusive with
+     * `body`, and no `Content-Type` is supplied: multipart needs `fetch` to pick
+     * the boundary, and anything else knows its own type.
+     */
+    rawBody?: BodyInit;
+    /**
+     * The mapper reads only a bounded prefix of a successful body, with
+     * `response.prefix()`, so a declared length past the ceiling is not refused
+     * up front: the ceiling still bounds what is read, never what is sent.
+     */
+    prefixOnly?: boolean;
+}
+/**
+ * One downstream response, read under the connector's byte ceiling.
+ *
+ * The accessors are the whole read surface — there is no escape to the
+ * underlying `Response`, because an unbounded `.text()` on it is exactly the
+ * mistake this type exists to remove. `status`, `ok`, and `headers` are the
+ * raw facts a provider mapper needs to make its own classification.
+ */
+interface GuardedResponse {
+    readonly status: number;
+    readonly ok: boolean;
+    readonly headers: Headers;
+    /** The body as bytes. */
+    bytes(): Promise<Uint8Array>;
+    /** The body decoded as UTF-8. */
+    text(): Promise<string>;
+    /** The body parsed as JSON; `undefined` for an empty body, throws on junk. */
+    json(): Promise<unknown>;
+    /** Parse JSON while distinguishing malformed content from transport failure. */
+    jsonResult(): Promise<{
+        value: unknown;
+    } | {
+        parseError: unknown;
+    }>;
+    /**
+     * At most `maxBytes` of the body (never past the ceiling), then the rest of
+     * the stream cancelled unread. Exactly: it retains at most `maxBytes` bytes,
+     * and consumes from the transport at most `maxBytes` plus one chunk — the
+     * chunk that crosses the bound, whose overflow is how it learns there was
+     * more (`truncated`). Chunks are whatever size the runtime delivers (64 KiB
+     * is common), so that one chunk is the whole of the overrun. Exclusive with
+     * the other readers: a body is read once.
+     */
+    prefix(maxBytes: number): Promise<{
+        bytes: Uint8Array;
+        truncated: boolean;
+    }>;
+}
+/** 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
+ * own typed failure. This is where status codes acquire meaning, and it is
+ * always the provider's code.
+ */
+type GuardedResponseMapper<T> = (response: GuardedResponse, ctx: ConnectorContext) => T | Promise<T>;
+export interface GuardedFetchOptions {
+    /**
+     * Provider name as it appears in normalized failure prose — "Cloudflare",
+     * "Notion". Used for messages only; it is never parsed.
+     */
+    provider: string;
+    /**
+     * Absolute base URL. Its origin and path prefix are the confinement: every
+     * request resolves beneath it or is refused.
+     */
+    baseUrl: string;
+    /**
+     * Headers proving the caller's identity, resolved once per request. Throwing
+     * a typed `auth_required` from here is the documented way to report a
+     * missing credential — the helper has no opinion about what a credential is.
+     */
+    authenticate: (ctx: ConnectorContext) => Record<string, string> | Promise<Record<string, string>>;
+    /**
+     * What actually sends a request, after confinement, framing, and
+     * authentication. Defaults to the global `fetch`. A connector that declares
+     * `oauth` supplies {@link oauthBearer}'s, so the calling owner's grant — not
+     * a header this helper assembled — authenticates the request. A rejection
+     * that is already a `ConnectorCallError` passes through unchanged; any other
+     * is normalized to `unavailable`, exactly as a global `fetch` failure is.
+     */
+    fetch?: GuardedFetcher;
+    /** Constant headers sent with every request — `Accept`, an API version. */
+    headers?: Record<string, string>;
+    /**
+     * Ceiling on the response body, in bytes. Required, because a default here
+     * would be the helper guessing on a provider's behalf: what counts as an
+     * absurd response is a fact about the API, not about HTTP.
+     */
+    maxResponseBytes: number;
+}
+/** Sends one already-guarded request on behalf of one call's context. */
+type GuardedFetcher = (url: string, init: RequestInit, ctx: ConnectorContext) => Promise<Response>;
+/**
+ * The transport half of a guarded connector that authenticates through its
+ * own `api()` OAuth grant: no header of the helper's making, and every request
+ * sent through `ctx.oauth.fetch`, which adds the calling owner's bearer token,
+ * refuses any origin outside the grant's `apiOrigins`, and spends one
+ * coordinated refresh and one replay on a 401 before answering
+ * `auth_required`. Spread it into the options:
+ * `guardedFetch({ provider, baseUrl, maxResponseBytes, ...oauthBearer(provider) })`.
+ *
+ * Confinement still happens here first, so a request reaches the grant only
+ * once it is provably beneath `baseUrl`; the grant's origin check is the second
+ * fence, not the only one.
+ */
+export declare function oauthBearer(provider: string): Pick<GuardedFetchOptions, "authenticate" | "fetch">;
+/** Send one guarded request and map its response with provider knowledge. */
+export type GuardedTransport = <T>(request: GuardedRequest, ctx: ConnectorContext, map: GuardedResponseMapper<T>) => Promise<T>;
+/**
+ * Build the transport a connector sends every request through. `maxResponseBytes`
+ * is required rather than defaulted: what counts as an absurd response is a fact
+ * about the API, not about HTTP.
+ */
+export declare function guardedFetch(options: GuardedFetchOptions): GuardedTransport;
+export {};

package/dist/connectors/guarded-fetch.js

@@ -13,6 +13,7 @@
  * public surface. Web APIs only.
  */
 import { ConnectorCallError, unavailableCallError } from "../errors.js";
+import { sentSecretsFor } from "../sent-secrets.js";
 /** Parse delta-seconds or an HTTP-date into a non-negative wait window. */
 export function retryAfterMs(headers) {
     const raw = headers.get("retry-after");
@@ -29,12 +30,36 @@ export function retryAfterMs(headers) {
     const date = Date.parse(raw);
     return Number.isFinite(date) ? Math.max(0, date - Date.now()) : undefined;
 }
+/**
+ * The transport half of a guarded connector that authenticates through its
+ * own `api()` OAuth grant: no header of the helper's making, and every request
+ * sent through `ctx.oauth.fetch`, which adds the calling owner's bearer token,
+ * refuses any origin outside the grant's `apiOrigins`, and spends one
+ * coordinated refresh and one replay on a 401 before answering
+ * `auth_required`. Spread it into the options:
+ * `guardedFetch({ provider, baseUrl, maxResponseBytes, ...oauthBearer(provider) })`.
+ *
+ * Confinement still happens here first, so a request reaches the grant only
+ * once it is provably beneath `baseUrl`; the grant's origin check is the second
+ * fence, not the only one.
+ */
+export function oauthBearer(provider) {
+    const send = (url, init, ctx) => {
+        const grant = ctx.oauth;
+        if (!grant) {
+            // A wiring bug, not an outage: the transport was built for a grant the
+            // connector does not have, so no request can be authenticated.
+            throw new ConnectorCallError("connector_call_failed", `The ${provider} transport authenticates through the connector's OAuth grant, and this call's context carries none.`, { retryable: false });
+        }
+        return grant.fetch(url, init);
+    };
+    return { authenticate: () => ({}), fetch: send };
+}
 /** Statuses that instruct a client to re-send somewhere else. Never followed. */
 const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
 /** Statuses the HTTP spec defines as carrying no body at all. */
 const BODILESS_STATUSES = new Set([204, 205, 304]);
 const decoder = new TextDecoder();
-const encoder = new TextEncoder();
 /**
  * A base URL is deployment configuration, so a bad one is a structural mistake
  * and throws where it is written rather than on the first call that uses it.
@@ -47,9 +72,7 @@ function confinementBase(provider, baseUrl) {
     catch {
         throw new Error(`${provider} baseUrl must be an absolute URL: ${baseUrl}`);
     }
-    const loopback = base.hostname === "localhost" ||
-        base.hostname === "127.0.0.1" ||
-        base.hostname === "[::1]";
+    const loopback = base.hostname === "localhost" || base.hostname === "127.0.0.1" || base.hostname === "[::1]";
     if (base.protocol !== "https:" && !(base.protocol === "http:" && loopback)) {
         throw new Error(`${provider} baseUrl must be https (http is allowed only for a loopback proxy or test double): ${baseUrl}`);
     }
@@ -84,13 +107,18 @@ function confinedUrl(provider, base, basePath, request) {
     catch {
         throw new ConnectorCallError("invalid_args", `A ${provider} request path did not resolve to a valid URL.`);
     }
-    if (url.origin !== base.origin ||
-        !`${url.pathname}/`.startsWith(`${basePath}/`)) {
+    if (url.origin !== base.origin || !`${url.pathname}/`.startsWith(`${basePath}/`)) {
         throw new ConnectorCallError("invalid_args", `A ${provider} request path escaped the connector's base URL.`);
     }
     for (const [key, value] of Object.entries(request.query ?? {})) {
         if (value === undefined)
             continue;
+        if (Array.isArray(value)) {
+            url.searchParams.delete(key);
+            for (const item of value)
+                url.searchParams.append(key, String(item));
+            continue;
+        }
         url.searchParams.set(key, String(value));
     }
     return url;
@@ -101,9 +129,7 @@ function oversized(provider, limit, detail) {
 /** The response body as a `ReadableStream`, or null when there is none to read. */
 function readableBody(response) {
     const body = response.body;
-    return body && typeof body.getReader === "function"
-        ? body
-        : null;
+    return body && typeof body.getReader === "function" ? body : null;
 }
 /** Read a stream to the ceiling and stop there — never past it. */
 async function drain(provider, stream, limit) {
@@ -139,9 +165,9 @@ async function drain(provider, stream, limit) {
 /**
  * Every read is capped at `maxResponseBytes`: a streaming body is abandoned at
  * the ceiling rather than buffered past it, and where a runtime gives no body
- * stream the text is measured in UTF-8 bytes before it is accepted, with JSON
- * parsed from that same bounded text. Such a runtime still buffers internally,
- * but cannot return an oversized body as a successful result.
+ * stream the buffered bytes are measured before they are accepted, with text
+ * and JSON decoded from them. Such a runtime still buffers internally, but
+ * cannot return an oversized body as a successful result.
  *
  * A mapper must re-throw `ConnectorCallError` and swallow only what it
  * recognizes: a bare `catch` around `response.json()` eats this refusal along
@@ -159,9 +185,22 @@ function boundedResponse(provider, response, limit) {
             text: async () => "",
             json: emptyJson,
             jsonResult: () => jsonResult(emptyJson),
+            prefix: async () => ({ bytes: new Uint8Array(), truncated: false }),
         };
     }
     const stream = readableBody(response);
+    const prefix = async (maxBytes) => {
+        const keep = Math.min(Math.max(0, Math.trunc(maxBytes)), limit);
+        if (stream)
+            return await readPrefix(stream, keep);
+        // A runtime with no body stream buffers the body regardless; the
+        // ceiling still bounds what is accepted.
+        const buffer = new Uint8Array(await response.arrayBuffer());
+        if (buffer.byteLength > limit && keep === limit) {
+            throw oversized(provider, limit, `${buffer.byteLength} bytes`);
+        }
+        return { bytes: buffer.slice(0, keep), truncated: buffer.byteLength > keep };
+    };
     let read;
     const bytes = () => {
         read ??= stream
@@ -176,14 +215,9 @@ function boundedResponse(provider, response, limit) {
     };
     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;
-            });
+        // Bytes, then UTF-8, never `response.text()`: workerd quotes a text
+        // read's non-text Content-Type in its own log (INV-6).
+        readText ??= bytes().then((body) => decoder.decode(body));
         return readText;
     };
     const json = async () => {
@@ -198,8 +232,51 @@ function boundedResponse(provider, response, limit) {
         text,
         json,
         jsonResult: () => jsonResult(json),
+        prefix,
     };
 }
+/**
+ * Read until a chunk crosses `keep` — at most one chunk past it — keep the
+ * first `keep` bytes, and cancel the stream: the source stops producing
+ * instead of being drained to the ceiling for bytes nobody will look at.
+ * A BYOB reader could stop at `keep + 1` exactly, but not every runtime's
+ * fetch body offers one, and one chunk is a bounded overrun.
+ */
+async function readPrefix(stream, keep) {
+    const reader = stream.getReader();
+    const chunks = [];
+    let total = 0;
+    let truncated = false;
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            if (!value)
+                continue;
+            if (total + value.byteLength > keep) {
+                chunks.push(value.subarray(0, keep - total));
+                total = keep;
+                truncated = true;
+                break;
+            }
+            chunks.push(value);
+            total += value.byteLength;
+        }
+        if (truncated)
+            await reader.cancel().catch(() => { });
+    }
+    finally {
+        reader.releaseLock();
+    }
+    const bytes = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return { bytes, truncated };
+}
 async function jsonResult(read) {
     try {
         return { value: await read() };
@@ -224,7 +301,8 @@ export function guardedFetch(options) {
     // "" for a root base, so joining never doubles the separator.
     const basePath = base.pathname.replace(/\/+$/, "");
     const constantHeaders = { ...options.headers };
-    return async function send(request, ctx, map) {
+    const send = options.fetch ?? ((url, init) => fetch(url, init));
+    return async function guarded(request, ctx, map) {
         if (request.body !== undefined && request.rawBody !== undefined) {
             throw new Error(`A ${provider} request cannot carry both a JSON body and a raw body.`);
         }
@@ -246,10 +324,11 @@ export function guardedFetch(options) {
                 throw new ConnectorCallError("invalid_args", `A ${provider} request may not set the ${shadow} header; authentication is connector-owned.`);
             }
             headers[name] = value;
+            sentSecretsFor(ctx).header(value);
         }
         let response;
         try {
-            response = await fetch(url.toString(), {
+            const init = {
                 method: request.method,
                 headers,
                 ...(request.body !== undefined
@@ -262,19 +341,23 @@ export function guardedFetch(options) {
                 // never one. Refused below rather than followed.
                 redirect: "manual",
                 ...(ctx.signal ? { signal: ctx.signal } : {}),
-            });
+            };
+            sentSecretsFor(ctx).request(url, init);
+            response = await send(url.toString(), init, ctx);
         }
         catch (cause) {
             if (cause instanceof ConnectorCallError)
                 throw cause;
-            throw unavailableCallError(cause, url.href, `Could not reach the ${provider} API.`);
+            throw unavailableCallError(cause, url.href, `Could not reach the ${provider} API.`, ctx.signal);
         }
         if (REDIRECT_STATUSES.has(response.status)) {
             await response.body?.cancel().catch(() => { });
             throw new ConnectorCallError("connector_call_failed", `${provider} answered HTTP ${response.status} with a redirect; this connector talks to exactly one origin and never forwards its credential to another.`, { retryable: false });
         }
         const declared = Number(response.headers.get("content-length"));
-        if (Number.isFinite(declared) && declared > limit) {
+        // A prefix read takes only what it was asked for, so a long body is not
+        // a reason to refuse it; the ceiling still bounds what is read.
+        if (Number.isFinite(declared) && declared > limit && !(request.prefixOnly && response.ok)) {
             await response.body?.cancel().catch(() => { });
             throw oversized(provider, limit, `a declared ${declared} bytes`);
         }

package/dist/connectors/negotiation-cache.js

@@ -0,0 +1,46 @@
+import { isSpecType } from "@modelcontextprotocol/client";
+import { failureRecord, logFailure } from "../operator-record.js";
+import { sentSecretsForRequest } from "../sent-secrets.js";
+import { assertDownstreamOutputSafe } from "../downstream-input-context.js";
+import { negotiationKeys, NEGOTIATION_TTL_SECONDS } from "../storage/keys.js";
+/** Verdicts carry data only. Clients, signals and secrets remain request-local. */
+export async function readNegotiation(ctx, digest) {
+    let prior;
+    try {
+        const raw = await ctx.storage.get(negotiationKeys.verdict(digest));
+        if (!raw)
+            return;
+        const value = JSON.parse(raw);
+        if (!Number.isFinite(value.expiresAt) || value.expiresAt <= Date.now())
+            return;
+        const candidate = value.prior;
+        if ((candidate?.kind === "legacy" && Object.keys(candidate).length === 1) ||
+            (candidate?.kind === "modern" && isSpecType.DiscoverResult(candidate.discover)))
+            prior = candidate;
+    }
+    catch (error) {
+        logFailure(ctx.logger, "negotiation cache read failed", failureRecord({}, error));
+    }
+    // Privacy refusals are not cache misses and must not enter cache diagnostics.
+    if (prior)
+        assertDownstreamOutputSafe(ctx.requestScope ?? ctx, prior);
+    return prior;
+}
+export async function storeNegotiation(ctx, digest, prior) {
+    if (ctx.signal?.aborted)
+        return;
+    assertDownstreamOutputSafe(ctx.requestScope ?? ctx, prior);
+    // DiscoverResult instructions, metadata and capability keys can echo auth.
+    const clean = sentSecretsForRequest(ctx.requestScope ?? ctx).redact(prior);
+    if (clean.kind === "modern" && !isSpecType.DiscoverResult(clean.discover))
+        return;
+    try {
+        await ctx.storage.set(negotiationKeys.verdict(digest), JSON.stringify({
+            prior: clean,
+            expiresAt: Date.now() + NEGOTIATION_TTL_SECONDS * 1000,
+        }), { ttlSeconds: NEGOTIATION_TTL_SECONDS });
+    }
+    catch (error) {
+        logFailure(ctx.logger, "negotiation cache write failed", failureRecord({}, error));
+    }
+}

package/dist/connectors/option-shapes.js

@@ -0,0 +1,27 @@
+// Closed option shapes shared by the built-in connector factories: `api()`,
+// `remoteMcp()`, and every maintained provider. Each factory walks its options
+// against its shape with `assertKnownOptions` before reading a value, so a
+// misspelled `maxResultByte` or `requireHTTPs` throws at construction with its
+// path instead of silently doing nothing (INV-11). Values stay the factory's
+// to validate; handlers, schemas, and loggers pass through as `opaque()`.
+import { array, keys, optionsOf, strings, variants } from "../config-schema.js";
+export { CALL_ADMISSION, PROVIDER_COMMON } from "../provider.js";
+export const CREDENTIAL = optionsOf()({
+    ...keys("label", "description", "placeholder"),
+    fields: array(optionsOf()(keys("name", "label", "description", "placeholder", "inputType"))),
+});
+/** The structured form; a string guide has no keys to check. */
+export const USAGE_GUIDE = optionsOf()(keys("content", "summary", "required"));
+/** `remoteMcp()`'s `auth`, closed per `type`. */
+export const REMOTE_MCP_AUTH = variants("type", {
+    request: optionsOf()({ ...keys("type", "token"), headers: strings() }).shape,
+    headers: optionsOf()({ ...keys("type"), headers: strings() }).shape,
+    credential: optionsOf()({
+        ...keys("type", "header", "scheme"),
+        credential: CREDENTIAL,
+    }).shape,
+    oauth: optionsOf()({
+        ...keys("type", "clientMetadataUrl", "scope"),
+        client: optionsOf()(keys("issuer", "clientId", "clientSecret", "tokenEndpointAuthMethod")),
+    }).shape,
+});

package/dist/connectors/remote-mcp.d.ts

@@ -1,6 +1,7 @@
+import { type RemoteOAuthClient } from "../auth/downstream-client-metadata.js";
 import type { FetchLike, Transport } from "@modelcontextprotocol/client";
 import { ConnectorCallError } from "../errors.js";
-import type { Connector, ConnectorCallAdmissionPolicy, ConnectorContext, ConnectorCredentialConfig, ConnectorUsageGuide, Logger } from "../types.js";
+import type { Connector, ConnectorCallAdmissionPolicy, ConnectorContext, ConnectorCredentialConfig, ConnectorUsageGuide, Logger, ToolClassification } from "../types.js";
 /**
  * A static downstream credential supplied through the connection in the
  * operator UI rather than baked into deployment source.
@@ -34,12 +35,20 @@ interface RemoteMcpCredentialAuth {
     scheme?: string | null;
 }
 export type RemoteMcpAuth = {
+    type: "request";
+    /** Resolve a Bearer token inside this request. Never persisted or described. */
+    token: (ctx: ConnectorContext) => Promise<string>;
+    /** Static protocol/catalog headers, never Authorization. */
+    headers?: Record<string, string>;
+} | {
     type: "headers";
     headers: Record<string, string>;
 } | RemoteMcpCredentialAuth | {
     type: "oauth";
     /** Public HTTPS client metadata document, for servers supporting URL-based client IDs. */
     clientMetadataUrl?: string;
+    /** Pre-registered client, bound to its configured issuer; excludes clientMetadataUrl. */
+    client?: RemoteOAuthClient;
     /** Space-separated default scopes when the resource server does not advertise them. */
     scope?: string;
 };
@@ -67,10 +76,10 @@ export interface RemoteMcpOptions {
     authScope?: "shared" | "personal";
     /**
      * Max inline result size (bytes) for this connector's tools before
-     * call_tool truncates and stashes the full text for get_result
+     * call_tool truncates and stashes the full text for connecta.result
      * paging. Overrides the deployment's `calls.maxResultBytes`; omit to inherit
-     * it. Must be a whole number of bytes >= 1; anything else warns at startup
-     * and is ignored.
+     * it. Must be a whole number of bytes >= 1; anything else refuses to
+     * construct.
      */
     maxResultBytes?: number;
     /** Optional per-runtime downstream call-admission policy. */
@@ -81,7 +90,24 @@ export interface RemoteMcpOptions {
      * discovery metadata. See `Connector.usageGuide`.
      */
     usageGuide?: string | ConnectorUsageGuide;
+    /** Opt in to downstream Skills listing and resource reads. Defaults to false. */
+    skills?: boolean;
     auth?: RemoteMcpAuth;
+    /**
+     * Reviewed read/write verdicts for this downstream's tools, by exact name.
+     * Validated at construction. A listed read fills downstream silence but
+     * never overrules an explicit write annotation; a listed write or
+     * destructive tool stays a write whatever the downstream claims; an unlisted
+     * tool is read-only only when it says so explicitly; a listed tool whose
+     * `schemaDigest` no longer matches, or cannot be checked, is served as a
+     * write. Setting it also reports
+     * catalog drift against the list: unclassified, unserved, contradicted, and
+     * schema-changed tools, as counts. The connector carries it as
+     * `classification`, and its `listTools` returns the downstream's listing
+     * unclassified: the registry classifies every read. Omit it to keep the
+     * downstream's own annotations, which still fail closed.
+     */
+    classify?: ToolClassification | undefined;
     /**
      * Downstream MCP version-negotiation mode. Defaults to `"auto"`, which
      * probes with `server/discover` and falls back to the legacy lifecycle when