@zackbart/connecta 0.28.1 → 0.30.0

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");
@@ -43,25 +44,22 @@ export function retryAfterMs(headers) {
  * fence, not the only one.
  */
 export function oauthBearer(provider) {
-    return {
-        authenticate: () => ({}),
-        fetch: (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);
-        },
+    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.
@@ -72,19 +70,17 @@ function confinementBase(provider, baseUrl) {
         base = new URL(baseUrl);
     }
     catch {
-        throw new Error(`${provider} baseUrl must be an absolute URL: ${baseUrl}`);
+        throw new Error(`${provider} baseUrl must be an absolute URL.`);
     }
-    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}`);
+        throw new Error(`${provider} baseUrl must be https (http is allowed only for a loopback proxy or test double).`);
     }
     if (base.username || base.password) {
         throw new Error(`${provider} baseUrl must not embed URL credentials; authentication belongs in headers.`);
     }
     if (base.search || base.hash) {
-        throw new Error(`${provider} baseUrl must not carry a query or fragment: ${baseUrl}`);
+        throw new Error(`${provider} baseUrl must not carry a query or fragment.`);
     }
     return base;
 }
@@ -111,8 +107,7 @@ 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 ?? {})) {
@@ -134,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) {
@@ -172,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
@@ -192,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
@@ -209,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 () => {
@@ -231,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() };
@@ -280,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 send(url.toString(), {
+            const init = {
                 method: request.method,
                 headers,
                 ...(request.body !== undefined
@@ -296,19 +341,23 @@ export function guardedFetch(options) {
                 // never one. Refused below rather than followed.
                 redirect: "manual",
                 ...(ctx.signal ? { signal: ctx.signal } : {}),
-            }, ctx);
+            };
+            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).redactCredentials(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