@zackbart/connecta 0.28.1 → 0.29.0

package/dist/connectors/api-connector.d.ts

@@ -93,6 +93,8 @@ export interface ApiOAuthAccess {
 }
 /** The context an `api()` handler receives. */
 export interface ApiHandlerContext extends ConnectorContext {
+    /** Fetch with final outgoing credential headers and query values registered. */
+    fetch: typeof fetch;
     /** Present exactly when the connector declares `oauth`. */
     oauth?: ApiOAuthAccess;
 }
@@ -104,10 +106,10 @@ export interface ApiOptions {
     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. */
@@ -141,6 +143,54 @@ export interface ApiOptions {
     validateArgs?: boolean;
     tools: ApiTool[];
 }
+/** The closed options api() accepts; see `assertKnownOptions`. */
+export declare const API_OPTIONS: import("../config-schema.js").Field<unknown, unknown, true> & {
+    readonly shape: {
+        callAdmission: import("../config-schema.js").Field<unknown, unknown, true> & {
+            readonly shape: {
+                rules: import("../config-schema.js").Field<unknown[], readonly unknown[] | undefined, true>;
+                maxPartitions: import("../config-schema.js").Field<unknown, unknown, true>;
+            };
+        };
+        usageGuide: import("../config-schema.js").Field<unknown, unknown, true> & {
+            readonly shape: {
+                readonly required: import("../config-schema.js").Field<unknown, unknown, true>;
+                readonly content: import("../config-schema.js").Field<unknown, unknown, true>;
+                readonly summary: import("../config-schema.js").Field<unknown, unknown, true>;
+            };
+        };
+        credential: import("../config-schema.js").Field<unknown, unknown, true> & {
+            readonly shape: {
+                fields: import("../config-schema.js").Field<unknown[], readonly unknown[] | undefined, true>;
+                label: import("../config-schema.js").Field<unknown, unknown, true>;
+                description: import("../config-schema.js").Field<unknown, unknown, true>;
+                placeholder: import("../config-schema.js").Field<unknown, unknown, true>;
+            };
+        };
+        oauth: import("../config-schema.js").Field<unknown, unknown, true> & {
+            readonly shape: {
+                authorizationParams: import("../config-schema.js").Field<Record<string, string>, Readonly<Record<string, string>> | undefined, true>;
+                tokenRequestHeaders: import("../config-schema.js").Field<Record<string, string>, Readonly<Record<string, string>> | undefined, true>;
+                scope: import("../config-schema.js").Field<unknown, unknown, true>;
+                authorizationEndpoint: import("../config-schema.js").Field<unknown, unknown, true>;
+                tokenEndpoint: import("../config-schema.js").Field<unknown, unknown, true>;
+                apiOrigins: import("../config-schema.js").Field<unknown, unknown, true>;
+                tokenEndpointAuthMethod: import("../config-schema.js").Field<unknown, unknown, true>;
+                pkce: import("../config-schema.js").Field<unknown, unknown, true>;
+                clientId: import("../config-schema.js").Field<unknown, unknown, true>;
+                clientSecret: import("../config-schema.js").Field<unknown, unknown, true>;
+            };
+        };
+        tools: import("../config-schema.js").Field<unknown[], readonly unknown[] | undefined, true>;
+        title: import("../config-schema.js").Field<unknown, unknown, true>;
+        description: import("../config-schema.js").Field<unknown, unknown, true>;
+        testCredential: import("../config-schema.js").Field<unknown, unknown, true>;
+        testCredentials: import("../config-schema.js").Field<unknown, unknown, true>;
+        authScope: import("../config-schema.js").Field<unknown, unknown, true>;
+        maxResultBytes: import("../config-schema.js").Field<unknown, unknown, true>;
+        validateArgs: import("../config-schema.js").Field<unknown, unknown, true>;
+    };
+};
 /**
  * The OAuth half of an `api()` connector: the hooks the callback route,
  * operator UI, and `authorize_connector` key on, and the handler accessor.
@@ -154,15 +204,17 @@ export interface ApiOAuthHooks {
     }): Promise<ConnectorStatus>;
     disconnectAuth(ctx: ConnectorContext): Promise<void>;
     verifyState(state: string | null, ctx: ConnectorContext): Promise<boolean>;
-    finishAuth(code: string, ctx: ConnectorContext, callbackParams?: URLSearchParams): Promise<void>;
+    verifyCallbackIssuer(issuer: string | null, ctx: ConnectorContext): Promise<boolean>;
+    consumeAuthError(ctx: ConnectorContext): Promise<void>;
+    /** Requires callbackParams with a nonempty state, including without PKCE. */
+    finishAuth(code: string, ctx: ConnectorContext, callbackParams: URLSearchParams): Promise<void>;
     /** The handler-facing accessor for one call's context. */
     access(ctx: ConnectorContext): ApiOAuthAccess;
 }
 /**
  * A static connector; every tool passes {@link checkToolContract} first.
  *
- * The builder behind `api()`, without the downstream OAuth machinery: a
- * module that only ever builds credential-free connectors (the artifacts
- * connector) imports this and pays nothing for a grant it cannot declare.
+ * The builder behind `api()`, without the downstream OAuth machinery: credential-free
+ * providers import this without paying for a grant they cannot declare.
  */
 export declare function apiConnector(id: string, opts: ApiOptions, oauth?: ApiOAuthHooks): Connector;

package/dist/connectors/api-connector.js

@@ -1,5 +1,12 @@
-import { ConnectorCallError, networkErrorCode, unavailableCallError, } from "../errors.js";
-import { compileValidator, validateToolInput } from "../validate.js";
+import { ConnectorCallError, networkErrorCode, unavailableCallError, WithheldTextError } from "../errors.js";
+import { attachFailureFacts, carryFailureFacts, errorLabel } from "../operator-record.js";
+import { compileValidator, validateCatalogToolInput } from "../validate.js";
+import { array, assertKnownOptions, instance, keys, optionsOf, strings } from "../config-schema.js";
+import { describedEndpoint, describedOrigin, describedTools } from "../described.js";
+import { CALL_ADMISSION, CREDENTIAL, USAGE_GUIDE } from "./option-shapes.js";
+import { assertStaticToolNames } from "../tool-name.js";
+import { registerInvocationAuth } from "../invocation-auth.js";
+import { redactCatalog, redactSentSecrets, sentSecretsFetch, trackCredentialReads } from "../sent-secrets.js";
 export function defined(value) {
     return Object.fromEntries(Object.entries(value).filter(([, item]) => item !== undefined));
 }
@@ -25,17 +32,65 @@ function checkToolContract(id, tool) {
             "call_destructive_tool. Connecta never infers the classification " +
             "from a tool name, description, schema, or other annotations.");
     }
+    if (typeof tool.handler !== "function") {
+        throw new Error(`api() tool "${address}" needs a handler function.`);
+    }
     if (tool.inputSchema)
         compileValidator(tool.inputSchema, { address });
 }
+/** The closed options api() accepts; see `assertKnownOptions`. */
+export const API_OPTIONS = optionsOf()({
+    ...keys("title", "description", "authScope", "maxResultBytes", "testCredential", "testCredentials", "validateArgs"),
+    callAdmission: CALL_ADMISSION,
+    usageGuide: USAGE_GUIDE,
+    credential: CREDENTIAL,
+    oauth: optionsOf()({
+        ...keys("authorizationEndpoint", "tokenEndpoint", "clientId", "clientSecret", "tokenEndpointAuthMethod", "scope", "pkce", "apiOrigins"),
+        authorizationParams: strings(),
+        tokenRequestHeaders: strings(),
+    }),
+    // A tool's annotations stay open: MCP lets a tool carry hints Connecta
+    // does not interpret, and its schemas are JSON Schema, not options. A tool
+    // carries its handler, so it is checked in place and kept, never copied.
+    tools: array(instance(optionsOf()(keys("name", "description", "inputSchema", "outputSchema", "annotations", "handler")))),
+});
+/**
+ * How an `api()` connector authenticates, as names and public endpoints. The
+ * client id and secret, extra parameter values, and token-request header
+ * values never leave the options.
+ */
+function describedApiAuth(opts) {
+    const oauth = opts.oauth;
+    if (!oauth)
+        return { mode: opts.credential ? "credential" : "none" };
+    const confidential = typeof oauth.clientSecret === "string" && oauth.clientSecret !== "";
+    const authorizationEndpoint = describedEndpoint(oauth.authorizationEndpoint);
+    const tokenEndpoint = describedEndpoint(oauth.tokenEndpoint);
+    const apiOrigins = Array.isArray(oauth.apiOrigins)
+        ? oauth.apiOrigins.flatMap((origin) => describedOrigin(origin) ?? [])
+        : [];
+    return {
+        mode: "oauth",
+        ...(authorizationEndpoint ? { authorizationEndpoint } : {}),
+        ...(tokenEndpoint ? { tokenEndpoint } : {}),
+        apiOrigins,
+        tokenEndpointAuthMethod: oauth.tokenEndpointAuthMethod ?? (confidential ? "client_secret_basic" : "none"),
+        confidentialClient: confidential,
+        pkce: oauth.pkce ?? true,
+        ...(oauth.scope !== undefined ? { scope: oauth.scope } : {}),
+        ...(oauth.authorizationParams ? { authorizationParamNames: Object.keys(oauth.authorizationParams) } : {}),
+        ...(oauth.tokenRequestHeaders ? { tokenRequestHeaderNames: Object.keys(oauth.tokenRequestHeaders) } : {}),
+    };
+}
 /**
  * A static connector; every tool passes {@link checkToolContract} first.
  *
- * The builder behind `api()`, without the downstream OAuth machinery: a
- * module that only ever builds credential-free connectors (the artifacts
- * connector) imports this and pays nothing for a grant it cannot declare.
+ * The builder behind `api()`, without the downstream OAuth machinery: credential-free
+ * providers import this without paying for a grant they cannot declare.
  */
 export function apiConnector(id, opts, oauth) {
+    opts = assertKnownOptions(opts, `api(${JSON.stringify(id)})`, API_OPTIONS);
+    assertStaticToolNames(opts.tools, `api(${JSON.stringify(id)}).tools`);
     if (opts.oauth !== undefined && oauth === undefined) {
         throw new Error(`api() connector "${id}" declares oauth but was built without its grant; construct it with api().`);
     }
@@ -58,10 +113,12 @@ export function apiConnector(id, opts, oauth) {
     }));
     const byName = new Map(opts.tools.map((t) => [t.name, t]));
     const validateArgs = opts.validateArgs ?? true;
-    return {
+    const auth = describedApiAuth(opts);
+    const connector = {
         id,
         ...defined({ title: opts.title }),
         kind: "api",
+        describe: () => ({ source: { kind: "api" }, auth, tools: describedTools(defs) }),
         ...defined({
             description: opts.description,
             authScope: opts.authScope,
@@ -78,28 +135,31 @@ export function apiConnector(id, opts, oauth) {
                 startAuth: oauth.startAuth,
                 disconnectAuth: oauth.disconnectAuth,
                 verifyState: oauth.verifyState,
+                verifyCallbackIssuer: oauth.verifyCallbackIssuer,
+                consumeAuthError: oauth.consumeAuthError,
                 finishAuth: oauth.finishAuth,
             }
             : {}),
         staticTools: defs,
-        async listTools() {
-            return defs;
+        async listTools(ctx) {
+            return redactCatalog(ctx, defs);
         },
         async callTool(name, args, ctx) {
+            trackCredentialReads(ctx);
             const tool = byName.get(name);
             if (!tool) {
                 throw new Error(`Unknown tool "${name}" on connector "${id}"`);
             }
             const input = args ?? {};
             if (validateArgs && tool.inputSchema) {
-                const invalid = validateToolInput(tool.inputSchema, input, {
+                const invalid = validateCatalogToolInput(tool.inputSchema, input, {
                     address: `${id}.${name}`,
                     logger: ctx.logger,
                     // Always: the schema compiled at construction, so anything that
                     // fails here is a schema that cannot be enforced, and a surface we
                     // wrote ourselves does not get to admit unvalidated input quietly.
                     failClosed: true,
-                });
+                }, { connector: id, tool });
                 if (invalid)
                     throw invalid;
             }
@@ -107,21 +167,48 @@ export function apiConnector(id, opts, oauth) {
             // 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.
-            // The accessor closes over the registry's own context, not this copy,
-            // so the grant it reaches is the one that context's owner holds.
-            const handlerCtx = oauth
-                ? { ...ctx, oauth: oauth.access(ctx) }
-                : ctx;
+            // Preserve the registry's context identity: private caller/provenance
+            // markers belong to it, as does the grant its accessor reaches.
+            const handlerCtx = Object.assign(ctx, {
+                fetch: sentSecretsFetch(ctx),
+                ...(oauth ? { oauth: oauth.access(ctx) } : {}),
+            });
             try {
-                return await tool.handler(input, handlerCtx);
+                return redactSentSecrets(ctx, await tool.handler(input, handlerCtx));
             }
             catch (error) {
+                // The request's own abort reason, by identity, is the caller's.
+                if (ctx.signal?.aborted === true && error === ctx.signal.reason)
+                    throw 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);
+                if (error instanceof ConnectorCallError)
+                    throw redactSentSecrets(ctx, error);
+                if (!networkErrorCode(error)) {
+                    // Anything else is a runtime's, parser's, or stream's account of
+                    // what the handler read (a JSON parser quotes the reply it choked
+                    // on; a body stream rejects with whatever the runtime says), so it
+                    // is told in connecta's words, classified as the original would
+                    // have been, and rebuilt without its cause or nested errors. A
+                    // handler that means the agent to read its words throws a
+                    // ConnectorCallError. No host is named: connecta does not know
+                    // which destination the handler read.
+                    const kind = errorLabel(error);
+                    throw attachFailureFacts(carryFailureFacts(error, new WithheldTextError(`Connector "${id}" tool "${name}" handler failed` +
+                        `${kind ? ` (${kind})` : ""}. Its text is withheld because it ` +
+                        "can quote what the downstream sent.", error)), { step: "handler" });
+                }
+                throw unavailableCallError(error, undefined, undefined, ctx.signal);
             }
         },
     };
+    if (oauth)
+        registerInvocationAuth(connector, async (ctx) => {
+            // The built-in static OAuth status only reads the stored grant. It never
+            // refreshes, invokes a handler, or sends a downstream request.
+            if ((await oauth.status(ctx)).state === "auth_required") {
+                throw new ConnectorCallError("downstream_oauth_required", `Connector "${id}" requires authorization. Call authorize_connector.`);
+            }
+        });
+    return connector;
 }

package/dist/connectors/api.js

@@ -1,11 +1,14 @@
 import { staticOAuth } from "../auth/static-oauth.js";
-import { apiConnector } from "./api-connector.js";
+import { assertKnownOptions } from "../config-schema.js";
+import { API_OPTIONS, apiConnector } from "./api-connector.js";
 /**
  * A hand-written connector: static tools, each with a handler. With `oauth`,
  * its handlers reach the API through the calling owner's downstream grant
  * (`ctx.oauth`), managed exactly like a `remoteMcp()` grant.
  */
 export function api(id, opts) {
+    // Read the options once, as plain data, before choosing a grant from them.
+    opts = assertKnownOptions(opts, `api(${JSON.stringify(id)})`, API_OPTIONS);
     if (opts.oauth !== undefined && opts.credential !== undefined) {
         throw new Error(`api() connector "${id}" declares both oauth and credential. Declare ` +
             "one: auth_required must name a single recovery. A provider offering " +

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 {};