@zackbart/connecta 0.27.0 → 0.28.1

package/dist/auth/static-oauth.js

@@ -0,0 +1,504 @@
+import { auth, OAuthError, UnauthorizedError } from "@modelcontextprotocol/client";
+import { redirectSafeFetch } from "../connectors/remote-mcp.js";
+import { ConnectorCallError, msg } from "../errors.js";
+import { oauthPartitionFor, retainOAuthPartition, retainingOAuthPartition, } from "../oauth-partition.js";
+import { oauthSealerFor } from "../oauth-sealing.js";
+import { assertOAuthScope, authorizingContext, KvOAuthProvider, LEGACY_GENERATION, refreshCoordinatorsByPartition, } from "./downstream-oauth.js";
+import { trackOAuthStartReset } from "./oauth-start-reset.js";
+/**
+ * Downstream OAuth for a hand-written `api()` connector: the authorization
+ * code grant against endpoints and a pre-registered client the deployment
+ * declares, rather than ones a server advertises.
+ *
+ * Everything that makes the `remoteMcp()` grant safe is reused, not copied.
+ * `StaticOAuthProvider` is a `KvOAuthProvider` — the same epochs, sealing,
+ * owner partitions, generation fence, reset lineage, and refresh-failure
+ * verdicts — whose discovery state and client are constants, and the SDK's
+ * own `auth()` drives it through the same `OAuthRefreshCoordinator`. What a
+ * static configuration subtracts is the network learning: no RFC 9728 or 8414
+ * discovery and no dynamic registration, so no URL here was taught to
+ * connecta by a downstream.
+ */
+/** Parameters the grant itself owns; a deployment may not restate them. */
+const RESERVED_AUTHORIZATION_PARAMS = new Set([
+    "response_type",
+    "client_id",
+    "redirect_uri",
+    "state",
+    "scope",
+    "code_challenge",
+    "code_challenge_method",
+    "resource",
+]);
+/** Token-request headers the grant owns: client authentication and framing. */
+const RESERVED_TOKEN_HEADERS = new Set([
+    "authorization",
+    "content-type",
+    "content-length",
+    "cookie",
+    "host",
+]);
+/** An RFC 9110 field-name token. */
+const HEADER_NAME = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+const CLIENT_AUTHENTICATION = new Set([
+    "client_secret_basic",
+    "client_secret_post",
+    "none",
+]);
+function isLoopback(hostname) {
+    return (hostname === "localhost" ||
+        hostname === "127.0.0.1" ||
+        hostname === "[::1]");
+}
+/** An absolute HTTPS URL (or HTTP on loopback), without credentials or fragment. */
+function configuredUrl(id, option, value) {
+    let url;
+    try {
+        url = new URL(String(value));
+    }
+    catch {
+        // Reported below without echoing the value.
+    }
+    if (!url ||
+        !(url.protocol === "https:" || (url.protocol === "http:" && isLoopback(url.hostname))) ||
+        url.username ||
+        url.password ||
+        url.hash) {
+        throw new Error(`[connecta] connector "${id}" oauth.${option} must be an absolute https URL ` +
+            "(http only on loopback), without credentials or a fragment.");
+    }
+    return url;
+}
+/** Structural mistakes throw here, where they are written. */
+function settingsFor(id, config) {
+    if (!config || typeof config !== "object") {
+        throw new Error(`[connecta] connector "${id}" oauth must be an object.`);
+    }
+    const authorizationEndpoint = configuredUrl(id, "authorizationEndpoint", config.authorizationEndpoint);
+    const tokenEndpoint = configuredUrl(id, "tokenEndpoint", config.tokenEndpoint);
+    if (tokenEndpoint.search) {
+        throw new Error(`[connecta] connector "${id}" oauth.tokenEndpoint must not carry a query.`);
+    }
+    if (typeof config.clientId !== "string" || config.clientId.trim() === "") {
+        throw new Error(`[connecta] connector "${id}" oauth.clientId must be a non-empty string.`);
+    }
+    if (config.clientSecret !== undefined &&
+        (typeof config.clientSecret !== "string" || config.clientSecret === "")) {
+        // Usually an unset environment variable read as "". Never echo it.
+        throw new Error(`[connecta] connector "${id}" oauth.clientSecret must be a non-empty string when set.`);
+    }
+    const clientAuthentication = config.tokenEndpointAuthMethod ??
+        (config.clientSecret !== undefined ? "client_secret_basic" : "none");
+    if (!CLIENT_AUTHENTICATION.has(clientAuthentication)) {
+        throw new Error(`[connecta] connector "${id}" oauth.tokenEndpointAuthMethod must be ` +
+            '"client_secret_basic", "client_secret_post", or "none".');
+    }
+    if (clientAuthentication === "none" && config.clientSecret !== undefined) {
+        throw new Error(`[connecta] connector "${id}" oauth declares a clientSecret with ` +
+            'tokenEndpointAuthMethod "none"; a public client sends no secret.');
+    }
+    if (clientAuthentication !== "none" && config.clientSecret === undefined) {
+        throw new Error(`[connecta] connector "${id}" oauth.tokenEndpointAuthMethod ` +
+            `"${clientAuthentication}" needs a clientSecret.`);
+    }
+    assertOAuthScope(id, config.scope);
+    const authorizationParams = [];
+    for (const [name, value] of Object.entries(config.authorizationParams ?? {})) {
+        if (RESERVED_AUTHORIZATION_PARAMS.has(name)) {
+            throw new Error(`[connecta] connector "${id}" oauth.authorizationParams may not set ` +
+                `"${name}"; the authorization request owns it.`);
+        }
+        if (typeof value !== "string") {
+            throw new Error(`[connecta] connector "${id}" oauth.authorizationParams.${name} must be a string.`);
+        }
+        authorizationParams.push([name, value]);
+    }
+    const tokenRequestHeaders = [];
+    for (const [name, value] of Object.entries(config.tokenRequestHeaders ?? {})) {
+        if (!HEADER_NAME.test(name)) {
+            throw new Error(`[connecta] connector "${id}" oauth.tokenRequestHeaders has an invalid header name.`);
+        }
+        if (RESERVED_TOKEN_HEADERS.has(name.toLowerCase())) {
+            throw new Error(`[connecta] connector "${id}" oauth.tokenRequestHeaders may not set ` +
+                `"${name}"; the token request owns it.`);
+        }
+        if (typeof value !== "string" || value.includes("\r") || value.includes("\n") || value.includes("\0")) {
+            throw new Error(`[connecta] connector "${id}" oauth.tokenRequestHeaders.${name} must be a single-line string.`);
+        }
+        tokenRequestHeaders.push([name, value]);
+    }
+    const origins = Array.isArray(config.apiOrigins) ? config.apiOrigins : [];
+    if (origins.length === 0) {
+        throw new Error(`[connecta] connector "${id}" oauth.apiOrigins must name at least one ` +
+            "origin; ctx.oauth.fetch sends the access token nowhere else.");
+    }
+    const apiOrigins = new Set();
+    for (const origin of origins) {
+        const url = configuredUrl(id, "apiOrigins", origin);
+        if (url.origin !== origin) {
+            throw new Error(`[connecta] connector "${id}" oauth.apiOrigins entries must be exact ` +
+                'origins, like "https://api.example.com", with no path or trailing slash.');
+        }
+        apiOrigins.add(url.origin);
+    }
+    return {
+        authorizationEndpoint,
+        tokenEndpoint,
+        clientId: config.clientId,
+        ...(config.clientSecret !== undefined ? { clientSecret: config.clientSecret } : {}),
+        clientAuthentication,
+        ...(config.scope !== undefined ? { scope: config.scope } : {}),
+        pkce: config.pkce ?? true,
+        authorizationParams,
+        tokenRequestHeaders,
+        apiOrigins,
+        serverUrl: new URL(origins[0]),
+        identity: tokenEndpoint.href,
+    };
+}
+/**
+ * A `KvOAuthProvider` whose discovery and client are constants. Storage,
+ * sealing, epochs, refresh coordination, and the authorization hooks are the
+ * base class's, unchanged; only what discovery and registration would have
+ * written is answered from configuration and never written.
+ */
+class StaticOAuthProvider extends KvOAuthProvider {
+    settings;
+    /** Set only for the code exchange of a PKCE-less flow. */
+    exchangeCode;
+    constructor(connectorId, ctx, coordinator, settings) {
+        super(connectorId, ctx.storage, `${ctx.baseUrl}/oauth/callback/${connectorId}`, coordinator, ctx.allowAuthorization === true, oauthSealerFor(ctx), ctx.signal, 
+        // No client binding: the client is configuration, so there is no
+        // registration for a restart to carry forward or discard.
+        undefined, (reset) => trackOAuthStartReset(ctx.requestScope ?? ctx, reset), undefined, settings.scope);
+        this.settings = settings;
+    }
+    /**
+     * The pre-registered client, answered from configuration. Its secret is
+     * never written to storage, sealed or otherwise: it is deployment config,
+     * not grant state, and an operator disconnect cannot delete it.
+     */
+    async clientInformation() {
+        const { settings } = this;
+        return {
+            client_id: settings.clientId,
+            ...(settings.clientSecret !== undefined
+                ? { client_secret: settings.clientSecret }
+                : {}),
+            redirect_uris: [this.redirectUrl],
+            token_endpoint_auth_method: settings.clientAuthentication,
+            issuer: settings.identity,
+        };
+    }
+    async saveClientInformation() {
+        // Nothing to save: the SDK only saves a client it registered or stamped.
+    }
+    /**
+     * Discovery as a constant. Supplying both halves keeps the SDK from
+     * fetching either: no protected-resource probe of the API origin, and no
+     * metadata request to an authorization server that may not publish any.
+     * The metadata names no `issuer`, so the SDK binds grants to the configured
+     * token endpoint and does not demand an RFC 9207 `iss` it cannot know.
+     */
+    async discoveryState() {
+        const { settings } = this;
+        const metadata = {
+            authorization_endpoint: settings.authorizationEndpoint.href,
+            token_endpoint: settings.tokenEndpoint.href,
+            response_types_supported: ["code"],
+            grant_types_supported: ["authorization_code", "refresh_token"],
+            code_challenge_methods_supported: ["S256"],
+            token_endpoint_auth_methods_supported: [settings.clientAuthentication],
+        };
+        return {
+            authorizationServerUrl: settings.identity,
+            authorizationServerMetadata: metadata,
+            resourceMetadata: { resource: settings.serverUrl.origin },
+        };
+    }
+    async saveDiscoveryState() {
+        // Configuration is the discovery; there is nothing to remember.
+    }
+    /** No RFC 8707 `resource` parameter: a plain REST API names no resource. */
+    async validateResourceURL() {
+        return undefined;
+    }
+    /**
+     * The code exchange without `code_verifier`, for a flow whose authorization
+     * request carried no challenge. Undefined everywhere else, which hands the
+     * SDK back its own request.
+     */
+    prepareTokenRequest() {
+        if (this.settings.pkce || this.exchangeCode === undefined)
+            return undefined;
+        return new URLSearchParams({
+            grant_type: "authorization_code",
+            code: this.exchangeCode,
+            redirect_uri: this.redirectUrl,
+        });
+    }
+    /** @internal Remember the code a PKCE-less exchange sends. */
+    exchanging(code) {
+        this.exchangeCode = code;
+    }
+    async redirectToAuthorization(authorizationUrl) {
+        for (const [name, value] of this.settings.authorizationParams) {
+            authorizationUrl.searchParams.set(name, value);
+        }
+        if (!this.settings.pkce) {
+            authorizationUrl.searchParams.delete("code_challenge");
+            authorizationUrl.searchParams.delete("code_challenge_method");
+        }
+        await super.redirectToAuthorization(authorizationUrl);
+    }
+}
+const AUTH_REQUIRED_MESSAGE = "Authorization required — open the URL to connect.";
+/** The grant behind one `api()` connector's `oauth`, as the hooks it exposes. */
+export function staticOAuth(id, config) {
+    const settings = settingsFor(id, config);
+    const issuerContext = { issuer: settings.identity };
+    const coordinatorFor = refreshCoordinatorsByPartition();
+    // Keyed by request scope, so nothing here outlives the request that set it.
+    const callbackProviders = new WeakMap();
+    const rejectedScopes = new WeakSet();
+    const scopeOf = (ctx) => ctx.requestScope ?? ctx;
+    const providerFor = (ctx) => new StaticOAuthProvider(id, ctx, coordinatorFor(ctx), settings);
+    /**
+     * The global `fetch`, read per request, with the configured token-request
+     * headers laid over the SDK's own. With discovery and registration answered
+     * from configuration the token endpoint is the only URL the SDK fetches here;
+     * the check keeps the headers on it even if that ever changes.
+     */
+    const tokenEndpointFetch = (input, init = {}) => {
+        const url = new URL(input);
+        if (settings.tokenRequestHeaders.length === 0 ||
+            `${url.origin}${url.pathname}` !== settings.identity) {
+            return fetch(input, init);
+        }
+        const headers = new Headers(init.headers);
+        for (const [name, value] of settings.tokenRequestHeaders)
+            headers.set(name, value);
+        return fetch(input, { ...init, headers });
+    };
+    /**
+     * The SDK's `auth()` over this provider. The token endpoint is fetched
+     * through the refresh coordinator — rotation, coalescing, and dead-versus-
+     * outage verdicts — above a fetch that refuses every redirect, as the
+     * `remoteMcp()` default does.
+     */
+    const runAuth = (provider, ctx, exchange) => auth(provider, {
+        serverUrl: settings.serverUrl,
+        ...exchange,
+        fetchFn: coordinatorFor(ctx).coordinatedFetch(provider, redirectSafeFetch(id, "none", tokenEndpointFetch), ctx.signal),
+    });
+    const authRequiredError = (cause) => new ConnectorCallError("auth_required", `Connector "${id}" requires authorization — call authorize_connector({ connector: "${id}" }) and open the returned URL.`, cause !== undefined ? { cause } : undefined);
+    const disconnectedMessage = `Connector "${id}" was disconnected by an operator — explicitly start authorization to reconnect it.`;
+    /**
+     * One request through the owner's grant. A 401 earns exactly one recovery:
+     * a token another request has already rotated in, or else one coordinated
+     * refresh. A second 401 is `auth_required`, latched for the request scope
+     * so a program's later calls do not each spend a refresh on it.
+     */
+    const authorizedFetch = async (ctx, input, init = {}) => {
+        const url = new URL(input);
+        if (!settings.apiOrigins.has(url.origin)) {
+            throw new ConnectorCallError("connector_call_failed", `Connector "${id}" sends its OAuth access token only to its declared ` +
+                `apiOrigins, and ${url.origin} is not one of them.`, { retryable: false });
+        }
+        if (init.body instanceof ReadableStream) {
+            throw new TypeError(`Connector "${id}": ctx.oauth.fetch may replay a request once after a ` +
+                "refresh, so it cannot send a stream body. Buffer the body first.");
+        }
+        const headers = new Headers(init.headers);
+        if (headers.has("authorization")) {
+            throw new ConnectorCallError("connector_call_failed", `Connector "${id}": a request through ctx.oauth.fetch may not set ` +
+                "Authorization; the connector's grant owns it.", { retryable: false });
+        }
+        const signal = init.signal && ctx.signal
+            ? AbortSignal.any([init.signal, ctx.signal])
+            : (init.signal ?? ctx.signal);
+        const send = (accessToken) => {
+            const sent = new Headers(headers);
+            sent.set("Authorization", `Bearer ${accessToken}`);
+            // The token rides to a declared origin and no further: a redirect is
+            // handed back to the handler unfollowed rather than re-sent anywhere.
+            return fetch(url, {
+                ...init,
+                headers: sent,
+                redirect: "manual",
+                ...(signal ? { signal } : {}),
+            });
+        };
+        if (rejectedScopes.has(scopeOf(ctx)))
+            throw authRequiredError();
+        const release = retainOAuthPartition(oauthPartitionFor(ctx));
+        try {
+            if (signal?.aborted)
+                throw signal.reason;
+            const provider = providerFor(ctx);
+            const generation = await provider.generation();
+            if (provider.isOperatorDisconnectedGeneration(generation)) {
+                throw new ConnectorCallError("auth_required", disconnectedMessage);
+            }
+            // A refresh this call triggers writes into the epoch it started under,
+            // so a reset landing meanwhile leaves its rotation unreadable.
+            provider.captureGeneration(generation);
+            const tokens = await provider.tokens(issuerContext);
+            if (!tokens)
+                throw authRequiredError();
+            const first = await send(tokens.access_token);
+            if (first.status !== 401)
+                return first;
+            void first.body?.cancel().catch(() => { });
+            let accessToken;
+            const current = await provider.tokens(issuerContext);
+            if (current && current.access_token !== tokens.access_token) {
+                accessToken = current.access_token;
+            }
+            else {
+                if ((await runAuth(provider, ctx)) !== "AUTHORIZED")
+                    throw authRequiredError();
+                const refreshed = await provider.tokens(issuerContext);
+                if (!refreshed)
+                    throw authRequiredError();
+                accessToken = refreshed.access_token;
+            }
+            const second = await send(accessToken);
+            if (second.status !== 401)
+                return second;
+            void second.body?.cancel().catch(() => { });
+            rejectedScopes.add(scopeOf(ctx));
+            throw authRequiredError();
+        }
+        catch (error) {
+            if (error instanceof UnauthorizedError) {
+                rejectedScopes.add(scopeOf(ctx));
+                throw authRequiredError(error);
+            }
+            // The coordinator's answer while another request is still committing
+            // a rotation it redeemed. The SDK rethrows it untouched; it is a
+            // moment, not a verdict on the grant.
+            if (error instanceof OAuthError && error.code === "temporarily_unavailable") {
+                throw new ConnectorCallError("unavailable", `Connector "${id}" could not refresh its OAuth grant while another ` +
+                    "request was saving one. The grant is kept; retry.", { cause: error });
+            }
+            throw error;
+        }
+        finally {
+            release();
+        }
+    };
+    const status = async (ctx) => {
+        if (rejectedScopes.has(scopeOf(ctx))) {
+            return {
+                state: "auth_required",
+                message: "Authorization required — the downstream rejected this connector's OAuth grant.",
+            };
+        }
+        // A status read never starts authorization: this provider cannot, and
+        // nothing here calls the SDK. A stored grant is healthy until a call
+        // says otherwise — the downstream is asked nothing.
+        const provider = providerFor(ctx);
+        if (await provider.operatorDisconnected()) {
+            return { state: "auth_required", message: disconnectedMessage };
+        }
+        return (await provider.tokens())
+            ? { state: "ok" }
+            : { state: "auth_required", message: AUTH_REQUIRED_MESSAGE };
+    };
+    const startAuth = async (original, opts) => {
+        const ctx = authorizingContext(original);
+        const provider = providerFor(ctx);
+        if (ctx.signal?.aborted)
+            throw ctx.signal.reason;
+        const disconnected = opts?.force ? false : await provider.operatorDisconnected();
+        if (ctx.signal?.aborted)
+            throw ctx.signal.reason;
+        if (opts?.force || disconnected) {
+            await provider.resetAuthorization();
+            rejectedScopes.delete(scopeOf(original));
+        }
+        else {
+            // Hand back a recent consent URL rather than overwrite the verifier
+            // the operator may be mid-consent on.
+            const pending = await provider.reusablePendingAuthorizationUrl();
+            if (pending) {
+                return {
+                    state: "auth_required",
+                    authorizationUrl: pending,
+                    authorizationReused: true,
+                    message: AUTH_REQUIRED_MESSAGE,
+                };
+            }
+        }
+        if (ctx.signal?.aborted)
+            throw ctx.signal.reason;
+        try {
+            let generation = await provider.generation();
+            // Born modern. The legacy generation exists so a `remoteMcp()` grant
+            // from before epochs survives an upgrade; this connector has no such
+            // past, and a flow started there writes an untimed pending URL that a
+            // second Connect could not hand back.
+            if (generation === LEGACY_GENERATION)
+                generation = await provider.bumpGeneration();
+            provider.captureGeneration(generation);
+            // An issuer-bound read: a grant from a since-repointed token endpoint
+            // is fenced here, before it could be reported healthy.
+            if (await provider.tokens(issuerContext)) {
+                return { state: "ok", message: "Already authorized — connection is healthy." };
+            }
+            if ((await runAuth(provider, ctx)) === "AUTHORIZED") {
+                return { state: "ok", message: "Already authorized — connection is healthy." };
+            }
+            const authorizationUrl = await provider.pendingAuthorizationUrl();
+            return {
+                state: "auth_required",
+                ...(authorizationUrl !== undefined ? { authorizationUrl } : {}),
+                message: AUTH_REQUIRED_MESSAGE,
+            };
+        }
+        catch (error) {
+            if (error instanceof UnauthorizedError) {
+                return { state: "auth_required", message: AUTH_REQUIRED_MESSAGE };
+            }
+            return { state: "error", message: msg(error) };
+        }
+    };
+    const disconnectAuth = async (ctx) => {
+        rejectedScopes.delete(scopeOf(ctx));
+        await providerFor(ctx).resetAuthorization(true);
+    };
+    const verifyState = async (state, ctx) => {
+        // The provider that verified the state captured its flow's epoch, and the
+        // exchange must write under exactly that one.
+        const provider = providerFor(ctx);
+        callbackProviders.set(scopeOf(ctx), provider);
+        return provider.verifyState(state);
+    };
+    const finishAuth = async (code, ctx, callbackParams) => {
+        const provider = callbackProviders.get(scopeOf(ctx)) ?? providerFor(ctx);
+        callbackProviders.delete(scopeOf(ctx));
+        const authorizationCode = callbackParams?.get("code") ?? code;
+        const iss = callbackParams?.get("iss") ?? undefined;
+        provider.exchanging(authorizationCode);
+        const result = await runAuth(provider, ctx, {
+            authorizationCode,
+            ...(iss !== undefined ? { iss } : {}),
+        });
+        if (result !== "AUTHORIZED") {
+            throw new UnauthorizedError("Failed to authorize");
+        }
+        await provider.clearPending();
+        rejectedScopes.delete(scopeOf(ctx));
+    };
+    return {
+        status: retainingOAuthPartition(status, 0),
+        startAuth: retainingOAuthPartition(startAuth, 0),
+        disconnectAuth: retainingOAuthPartition(disconnectAuth, 0),
+        verifyState: retainingOAuthPartition(verifyState, 1),
+        finishAuth: retainingOAuthPartition(finishAuth, 1),
+        access: (ctx) => ({
+            fetch: (input, init) => authorizedFetch(ctx, input, init),
+        }),
+    };
+}

package/dist/catalog-service.js

@@ -538,7 +538,7 @@ export class CatalogService {
                     ...(match.tool.annotations
                         ? { annotations: match.tool.annotations }
                         : {}),
-                    // Config lets a program call this write without pausing (#566).
+                    // Config lets a program call this write without asking (#566).
                     // A marker, not a class: the tool stays approval-required.
                     ...(isApprovalExempt(this.approval, match.connector, match.tool.name, match.tool)
                         ? { approval: "exempt" }

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

@@ -0,0 +1,168 @@
+import type { Connector, ConnectorCallAdmissionPolicy, ConnectorCredentialConfig, ConnectorCredentialValues, ConnectorContext, ConnectorStatus, ConnectorUsageGuide, CredentialTestResult, JsonSchema, ToolAnnotations } from "../types.js";
+export declare function defined<T extends object>(value: T): {
+    [K in keyof T]?: Exclude<T[K], undefined>;
+};
+export interface ApiTool {
+    name: string;
+    /**
+     * Required, non-empty. Discovery has nothing else to go on: a nameless
+     * capability costs the agent a guess, and a guess costs a wrong call.
+     */
+    description: string;
+    /**
+     * A plain JSON Schema object describing the tool input. Optional, but what
+     * you supply must be a schema the validator can compile — `api()` refuses to
+     * construct otherwise.
+     */
+    inputSchema?: JsonSchema;
+    /** A plain JSON Schema object describing the tool's structured output. */
+    outputSchema?: JsonSchema;
+    /**
+     * Standard MCP-style behavior hints, with an explicit `readOnlyHint`
+     * required: `true` declares a read and admits the tool to call_tool and
+     * execute_code, `false` declares work that must cross
+     * `call_destructive_tool` where a host can ask a human. Connecta never
+     * infers the classification from a name, a description, a schema, or the
+     * other annotations.
+     */
+    annotations: ToolAnnotations & {
+        readOnlyHint: boolean;
+    };
+    handler: (args: any, ctx: ApiHandlerContext) => Promise<unknown> | unknown;
+}
+/** How a pre-registered client authenticates at the token endpoint. */
+export type ApiOAuthClientAuthentication = "client_secret_basic" | "client_secret_post" | "none";
+/**
+ * Downstream OAuth 2.0 authorization code grant for a hand-written API whose
+ * provider issues clients by hand and publishes no discovery metadata. Every
+ * endpoint is declared here; nothing is learned from the network.
+ */
+export interface ApiOAuthConfig {
+    /** Where the operator's browser is sent for consent. Absolute https URL. */
+    authorizationEndpoint: string;
+    /** Where codes are exchanged and refresh tokens redeemed. Absolute https URL. */
+    tokenEndpoint: string;
+    /** The client id the provider issued for this deployment. */
+    clientId: string;
+    /**
+     * The client secret, from deployment configuration (an environment variable
+     * or Worker secret), never a literal in source. Omit for a public client.
+     * It is never written to storage.
+     */
+    clientSecret?: string;
+    /**
+     * Token-endpoint client authentication. Defaults to `client_secret_basic`
+     * with a secret and `none` without one.
+     */
+    tokenEndpointAuthMethod?: ApiOAuthClientAuthentication;
+    /** Space-separated scopes requested at consent. */
+    scope?: string;
+    /** PKCE with S256 (default true). Disable only for a server that rejects it. */
+    pkce?: boolean;
+    /**
+     * Extra authorization-request parameters, such as a provider's
+     * `access_type`. The grant's own parameters cannot be overridden.
+     */
+    authorizationParams?: Record<string, string>;
+    /**
+     * Headers added to every token-endpoint request — the code exchange and
+     * each refresh — for a provider whose token endpoint demands its own
+     * framing, such as Church Community Builder's
+     * `Accept: application/vnd.ccbchurch.v2+json`. They replace the grant's
+     * defaults of the same name; `Authorization`, `Content-Type`,
+     * `Content-Length`, `Cookie`, and `Host` stay the grant's.
+     */
+    tokenRequestHeaders?: Record<string, string>;
+    /**
+     * The exact origins `ctx.oauth.fetch` sends the access token to, such as
+     * `"https://api.ccbchurch.com"`. A request anywhere else is refused before
+     * it is sent, so an untrusted URL in a response cannot carry the token off.
+     */
+    apiOrigins: readonly string[];
+}
+/** A handler's use of its connector's OAuth grant, never the grant itself. */
+export interface ApiOAuthAccess {
+    /**
+     * `fetch` with the calling owner's access token as `Authorization: Bearer`.
+     * Only to `apiOrigins`; redirects are returned unfollowed. A 401 earns one
+     * coordinated refresh and one replay; a second 401, a refused refresh, or
+     * no grant at all throws `auth_required`, and an authorization-server
+     * outage throws a retryable `unavailable`.
+     */
+    fetch(input: string | URL, init?: RequestInit): Promise<Response>;
+}
+/** The context an `api()` handler receives. */
+export interface ApiHandlerContext extends ConnectorContext {
+    /** Present exactly when the connector declares `oauth`. */
+    oauth?: ApiOAuthAccess;
+}
+export interface ApiOptions {
+    /** Human-readable display name; the connector id remains the address prefix. */
+    title?: string;
+    description?: string;
+    /** Downstream auth ownership. Defaults to one shared deployment grant. */
+    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
+     * 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.
+     */
+    maxResultBytes?: number;
+    /** Optional per-runtime downstream call-admission policy. */
+    callAdmission?: ConnectorCallAdmissionPolicy;
+    /**
+     * Optional agent-facing usage guide served by `skills` as
+     * `connector:<id>`. A string is markdown; the structured form adds bounded
+     * discovery metadata. See `Connector.usageGuide`.
+     */
+    usageGuide?: string | ConnectorUsageGuide;
+    /** Optional operator-managed credential exposed through ctx.credential and the connection in the operator UI. */
+    credential?: ConnectorCredentialConfig;
+    /**
+     * Optional downstream OAuth, exposed to handlers as `ctx.oauth` and managed
+     * like a `remoteMcp()` grant: Connect in the operator UI, or
+     * `authorize_connector`. Exclusive with `credential` — one connector, one
+     * way to authenticate, so `auth_required` has one recovery.
+     */
+    oauth?: ApiOAuthConfig;
+    /** Optional validation behind the connection's Test action in the operator UI. */
+    testCredential?: (value: string, ctx: ConnectorContext) => Promise<CredentialTestResult>;
+    /** Optional validation for named multi-field credentials. */
+    testCredentials?: (values: ConnectorCredentialValues, ctx: ConnectorContext) => Promise<CredentialTestResult>;
+    /**
+     * Validate call arguments against each tool's `inputSchema` before invoking
+     * the handler (default true). Mismatches fail with a non-retryable
+     * `invalid_args` ConnectorCallError instead of reaching the handler. Set
+     * false to restore the pre-validation pass-through for deployments relying
+     * on loose coercion.
+     */
+    validateArgs?: boolean;
+    tools: ApiTool[];
+}
+/**
+ * The OAuth half of an `api()` connector: the hooks the callback route,
+ * operator UI, and `authorize_connector` key on, and the handler accessor.
+ * Supplied by `api()` from `src/auth/static-oauth.ts`; defined here so this
+ * module never imports the grant machinery.
+ */
+export interface ApiOAuthHooks {
+    status(ctx: ConnectorContext): Promise<ConnectorStatus>;
+    startAuth(ctx: ConnectorContext, opts?: {
+        force?: boolean;
+    }): Promise<ConnectorStatus>;
+    disconnectAuth(ctx: ConnectorContext): Promise<void>;
+    verifyState(state: string | null, ctx: ConnectorContext): Promise<boolean>;
+    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.
+ */
+export declare function apiConnector(id: string, opts: ApiOptions, oauth?: ApiOAuthHooks): Connector;