@corbits/mcp 0.3.1 → 0.4.0

package/dist/interchange/client/projection.js

@@ -0,0 +1,92 @@
+import { createElicitationRuntime } from "../../extensions/elicitation.js";
+import { validateInputRequests, } from "../../protocol/index.js";
+import { type } from "arktype";
+import { mcpContinue, mcpGetTask, mcpUpdateTask, mcpCancelTask, } from "../../client.js";
+const TextBlocks = type({ type: "'text'", text: "string" }).array();
+export function shapeMcpContent(content) {
+    if (typeof content === "string")
+        return content;
+    const blocks = TextBlocks(content);
+    if (!(blocks instanceof type.errors))
+        return blocks.map((block) => block.text).join("\n");
+    return JSON.stringify(content) ?? "";
+}
+/** One lifecycle and rich-result projection for live and stored catalogs. */
+export async function projectToolResult(context, initial, client, host = {}) {
+    let result = initial;
+    // Bound interactive loops independently of individual HTTP request timeouts.
+    for (let round = 0; round < 32; round++) {
+        context.signal.throwIfAborted();
+        if (result.resultType === "input_required") {
+            if (host.requestInput === undefined && host.elicitation === undefined)
+                return unavailable("unsupported", result);
+            if (result.method !== "tools/call")
+                throw new Error("MCP tool continuation changed method");
+            let responses;
+            if (host.requestInput !== undefined)
+                responses = await host.requestInput(context, result);
+            else {
+                const requests = result.inputRequests;
+                assertInputRequests(requests);
+                responses = await createElicitationRuntime(host.elicitation ?? {}).respond(requests, context.signal);
+            }
+            context.signal.throwIfAborted();
+            if (responses === undefined)
+                return unavailable("declined", result);
+            const next = await mcpContinue(context.url, result, responses, {
+                ...client,
+                signal: context.signal,
+            });
+            if (next.resultType === "input_required" ||
+                next.resultType === "task" ||
+                "content" in next) {
+                result = next;
+                continue;
+            }
+            throw new Error("MCP tool continuation returned a non-tool result");
+        }
+        if (result.resultType === "task") {
+            if (host.adoptTask === undefined)
+                return unavailable("unsupported", result);
+            const taskId = result.taskId;
+            // Do not retain the original invocation signal for the task's lifetime.
+            const { signal: _signal, ...taskClient } = client;
+            const adopted = await host.adoptTask(context, result, {
+                get: () => mcpGetTask(context.url, taskId, taskClient),
+                update: (responses) => mcpUpdateTask(context.url, taskId, responses, taskClient),
+                cancel: () => mcpCancelTask(context.url, taskId, taskClient),
+            });
+            if (adopted.correlationId.trim().length === 0)
+                throw new Error("MCP task host returned an empty correlation ID");
+            return {
+                callId: context.callId,
+                content: "Remote MCP task adopted by the host; awaiting its outcome.",
+                detail: { mcp: result, outcome: "pending" },
+                pendingMarker: {
+                    status: "pending",
+                    correlationId: adopted.correlationId,
+                },
+            };
+        }
+        await host.presentResult?.(context, result);
+        return {
+            callId: context.callId,
+            isError: result.isError === true,
+            content: shapeMcpContent(result.content),
+            detail: { mcp: result },
+        };
+    }
+    throw new Error("MCP continuation exceeded 32 input rounds");
+    function unavailable(outcome, pending) {
+        return {
+            callId: context.callId,
+            isError: true,
+            content: `MCP ${pending.resultType}: host handling ${outcome}.`,
+            detail: { mcp: pending, outcome },
+        };
+    }
+}
+/** Narrow using the sole shared wire validator, not a second schema. */
+function assertInputRequests(value) {
+    validateInputRequests(value);
+}

package/dist/interchange/client/skills.d.ts

@@ -0,0 +1,16 @@
+import { type McpClientOptions } from "../../client.js";
+import { type McpSkillOrigin, type McpSkillHostPolicy } from "../../extensions/skills/index.js";
+/** Host-bound skill consumption. Supply a mediated client, never a raw token.
+ * Verification alone does not admit model context or authorize execution. */
+export declare function createMcpSkillConsumer(options: {
+    origin: McpSkillOrigin;
+    url: string;
+    client: McpClientOptions;
+    host?: McpSkillHostPolicy;
+}): {
+    /** Refetching a changed entry invalidates its previous approval. */
+    get: (uri: string) => Promise<import("../../extensions/skills/contracts.js").HeldSkill>;
+    verify: (held: import("../../extensions/skills/contracts.js").HeldSkill, uri?: string) => Promise<import("../../extensions/skills/contracts.js").VerifiedSkillBytes>;
+    activate: (held: import("../../extensions/skills/contracts.js").HeldSkill) => Promise<import("../../extensions/skills/contracts.js").SkillLease>;
+    clear: () => void;
+};

package/dist/interchange/client/skills.js

@@ -0,0 +1,87 @@
+import { type } from "arktype";
+import { mcpGetSkill, mcpConnect, mcpReadResource, } from "../../client.js";
+import { validateSkill, MCP_EXT_SKILLS } from "../../protocol/index.js";
+import { createSkillLoader, } from "../../extensions/skills/index.js";
+/** This host adapter accepts only one matching text/blob resource. The shared
+ * client validates the wire; this narrower shape is the byte-decoder boundary. */
+const TextResource = type({ uri: "string", text: "string" });
+const BlobResource = type({ uri: "string", blob: "string" });
+/** Host-bound skill consumption. Supply a mediated client, never a raw token.
+ * Verification alone does not admit model context or authorize execution. */
+export function createMcpSkillConsumer(options) {
+    const origin = Object.freeze(structuredClone(options.origin));
+    const client = {
+        ...options.client,
+        extensions: [
+            ...new Set([...(options.client.extensions ?? []), MCP_EXT_SKILLS]),
+        ],
+    };
+    let ready;
+    function connect() {
+        ready ??= (async () => ({
+            ...client,
+            session: client.session ?? (await mcpConnect(options.url, client)),
+        }))().catch((cause) => {
+            ready = undefined;
+            throw cause;
+        });
+        return ready;
+    }
+    const loader = createSkillLoader({
+        async get(_origin, uri) {
+            const result = await mcpGetSkill(options.url, uri, await connect());
+            return validateSkill(result.skill);
+        },
+        async read(_origin, uri, maxBytes) {
+            const result = await mcpReadResource(options.url, uri, {
+                ...(await connect()),
+                maxDecodedBytes: maxBytes,
+            });
+            if (result.resultType !== "complete")
+                throw new Error("Skill resource requires unsupported host interaction");
+            if (result.contents.length !== 1)
+                throw new Error("Skill resource must contain exactly one matching item");
+            const item = result.contents[0];
+            const text = TextResource(item);
+            const blob = BlobResource(item);
+            let bytes;
+            if (!(text instanceof type.errors) &&
+                blob instanceof type.errors &&
+                text.uri === uri) {
+                if (Buffer.byteLength(text.text, "utf8") > maxBytes)
+                    throw new Error("Skill resource exceeds manifest size");
+                bytes = new TextEncoder().encode(text.text);
+            }
+            else if (!(blob instanceof type.errors) &&
+                text instanceof type.errors &&
+                blob.uri === uri) {
+                // Avoid a repeated-group regex: engines can exhaust their matching
+                // budget on valid multi-megabyte blobs. Scan alphabet and padding separately.
+                const padding = blob.blob.indexOf("=");
+                if (blob.blob.length % 4 !== 0 ||
+                    /[^A-Za-z0-9+/=]/u.test(blob.blob) ||
+                    (padding !== -1 &&
+                        (padding < blob.blob.length - 2 ||
+                            !/^={1,2}$/u.test(blob.blob.slice(padding)))))
+                    throw new Error("Invalid skill resource base64");
+                const decodedLength = (blob.blob.length / 4) * 3 -
+                    (blob.blob.endsWith("==") ? 2 : blob.blob.endsWith("=") ? 1 : 0);
+                if (decodedLength > maxBytes)
+                    throw new Error("Skill resource exceeds manifest size");
+                bytes = Uint8Array.from(atob(blob.blob), (character) => character.charCodeAt(0));
+            }
+            else
+                throw new Error("Skill resource must contain matching text or blob bytes");
+            if (bytes.byteLength > maxBytes)
+                throw new Error("Skill resource exceeds manifest size");
+            return bytes;
+        },
+    }, options.host);
+    return {
+        /** Refetching a changed entry invalidates its previous approval. */
+        get: (uri) => loader.get(origin, uri),
+        verify: loader.verify,
+        activate: loader.activate,
+        clear: loader.clear,
+    };
+}

package/dist/interchange/client.d.ts

@@ -0,0 +1,8 @@
+/** Remote MCP consumption through actual Interchange tool and host contracts. */
+export { mcpTools, type McpServerConfig, type McpToolsEnv, type McpToolsOptions, } from "../tool.js";
+export { mcpServers, SIDECAR_BUNDLE_ID, shapeMcpContent, type McpBoundServer, type McpServersConfig, type McpServersEnv, } from "../sidecar-bundle.js";
+export type { McpHostContext, McpHostServices, McpTaskControls, } from "./client/contracts.js";
+export { createCatalogGuard, type McpCatalogSnapshot, } from "./client/catalog.js";
+export { createMcpSkillConsumer } from "./client/skills.js";
+export { createSkillLoader, parseSkillFrontmatter, SKILL_LIMITS, } from "../extensions/skills/index.js";
+export type * from "../extensions/skills/contracts.js";

package/dist/interchange/client.js

@@ -0,0 +1,6 @@
+/** Remote MCP consumption through actual Interchange tool and host contracts. */
+export { mcpTools, } from "../tool.js";
+export { mcpServers, SIDECAR_BUNDLE_ID, shapeMcpContent, } from "../sidecar-bundle.js";
+export { createCatalogGuard, } from "./client/catalog.js";
+export { createMcpSkillConsumer } from "./client/skills.js";
+export { createSkillLoader, parseSkillFrontmatter, SKILL_LIMITS, } from "../extensions/skills/index.js";

package/dist/interchange/server/contracts.d.ts

@@ -0,0 +1,65 @@
+import type { Agent, ToolBundle } from "@intx/agent";
+import type { ToolResult } from "@intx/types/runtime";
+import type { McpIdentity, McpAuthPolicy } from "../../auth/contracts.js";
+import type { McpOperationOutcome, McpRequestContext } from "../../server/contracts.js";
+import type { McpToolBinding } from "../../server/tools.js";
+type BaseExposure = {
+    definition: McpToolBinding["definition"];
+    tenantId: string;
+    resource: string;
+    action: string;
+    /** Host approval/grant floor. Mandatory even for a bare ToolBundle dispatcher. */
+    approve: (args: Record<string, unknown>, context: McpRequestContext) => Promise<boolean>;
+    /** Host must bind continuations to identity, operation, arguments and one-time state. */
+    continue?: (params: Record<string, unknown>, context: McpRequestContext) => Promise<McpOperationOutcome>;
+};
+export type InterchangeToolExposure = BaseExposure & {
+    kind: "tool";
+    bundle: Pick<ToolBundle, "definitions" | "run">;
+    toolName: string;
+    /** Explicit mapping for pending markers and full-fidelity detail; no implicit approval. */
+    projectResult?: (result: ToolResult, context: McpRequestContext) => Promise<McpOperationOutcome>;
+};
+export type InterchangeAgentExposure = BaseExposure & {
+    kind: "agent";
+    agent: Pick<Agent, "send">;
+    message: (args: Record<string, unknown>) => string;
+    suspended: (result: Extract<Awaited<ReturnType<Agent["send"]>>, {
+        type: "suspended";
+    }>, context: McpRequestContext) => Promise<McpOperationOutcome>;
+};
+/** Host-authenticated app pipeline; the adapter never forwards MCP bearer headers. */
+export type InterchangeDispatch = (request: Request, identity: McpIdentity) => Promise<Response>;
+export type InterchangeHttpExposure = BaseExposure & {
+    kind: "operation";
+    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+    /** Fully bound path. No model-controlled tenant, host, path or authorization headers. */
+    path: string;
+    origin: string;
+    dispatch: InterchangeDispatch;
+    /** Authored projection, not automatic exposure of OpenAPI or an entire hub. */
+    body?: (args: Record<string, unknown>) => Record<string, unknown>;
+};
+export type WorkflowTrigger = {
+    runId: string;
+    address: string;
+    messageId: string;
+};
+export type InterchangeWorkflowExposure = BaseExposure & {
+    kind: "workflow";
+    deploymentId: string;
+    origin: string;
+    dispatch: InterchangeDispatch;
+    message: (args: Record<string, unknown>) => string;
+    /** Must durably persist dispatch intent; ambiguous dispatch is never automatically replayed. */
+    prepare: (args: Record<string, unknown>, context: McpRequestContext) => Promise<string>;
+    recordTrigger: (intentId: string, trigger: WorkflowTrigger, context: McpRequestContext) => Promise<void>;
+    /** Select only this message's result, or durably create a task bound to its correlation. */
+    selectResult: (trigger: WorkflowTrigger, context: McpRequestContext) => Promise<McpOperationOutcome>;
+};
+export type InterchangeExposure = InterchangeToolExposure | InterchangeAgentExposure | InterchangeHttpExposure | InterchangeWorkflowExposure;
+export type InterchangeServerOptions = {
+    auth: McpAuthPolicy;
+    exposures: readonly InterchangeExposure[];
+};
+export {};

package/dist/interchange/server/contracts.js

@@ -0,0 +1 @@
+export {};

package/dist/interchange/server.d.ts

@@ -0,0 +1,5 @@
+import type { McpProviders } from "../server/contracts.js";
+import type { InterchangeServerOptions } from "./server/contracts.js";
+export type * from "./server/contracts.js";
+/** Explicit allowlist only: no hub scanning, factory enumeration, or grant widening. */
+export declare function createInterchangeProviders(options: InterchangeServerOptions): McpProviders;

package/dist/interchange/server.js

@@ -0,0 +1,172 @@
+import { type } from "arktype";
+import { McpError, validateInstance } from "../protocol/index.js";
+import { createToolProviders } from "../server/tools.js";
+const Trigger = type({
+    runId: "string > 0",
+    address: "string > 0",
+    messageId: "string > 0",
+});
+const textResult = (text) => ({
+    content: [{ type: "text", text }],
+});
+const jsonResult = (value) => ({
+    content: [{ type: "text", text: JSON.stringify(value) }],
+    ...(value !== null && typeof value === "object" && !Array.isArray(value)
+        ? { structuredContent: value }
+        : {}),
+});
+function boundUrl(origin, path) {
+    const base = new URL(origin);
+    if (!/^https?:$/.test(base.protocol) ||
+        base.username ||
+        base.password ||
+        base.pathname !== "/" ||
+        base.search ||
+        base.hash)
+        throw new Error("Expected a fixed HTTP origin");
+    if (!path.startsWith("/") || path.startsWith("//") || /[\\?#{}]/u.test(path))
+        throw new Error("Expected a fully bound operation path");
+    for (const segment of path.split("/")) {
+        const decoded = decodeURIComponent(segment);
+        if (decoded === "." ||
+            decoded === ".." ||
+            /[/\\%]/u.test(decoded) ||
+            [...decoded].some((character) => character.charCodeAt(0) <= 32))
+            throw new Error("Unsafe operation path");
+    }
+    const url = new URL(path, base);
+    if (url.origin !== base.origin)
+        throw new Error("Operation origin mismatch");
+    return url;
+}
+async function responseJson(response) {
+    if (!response.ok)
+        throw new McpError("Interchange operation failed", 502, -32603);
+    if (response.status === 204)
+        return {};
+    const body = await response.text();
+    if (response.status === 202 && body.length === 0) {
+        const location = response.headers.get("location");
+        // Acceptance is not completion/cancellation; keep the polling hint without following it.
+        return {
+            status: 202,
+            accepted: true,
+            ...(location === null ? {} : { location }),
+        };
+    }
+    if (response.headers.get("content-type")?.split(";")[0]?.trim() !==
+        "application/json")
+        throw new McpError("Unsupported Interchange response content type", 502, -32603);
+    return JSON.parse(body);
+}
+/** Explicit allowlist only: no hub scanning, factory enumeration, or grant widening. */
+export function createInterchangeProviders(options) {
+    const bindings = options.exposures.map((exposure) => {
+        if (!exposure.tenantId || typeof exposure.approve !== "function")
+            throw new Error("Tenant binding and approval service required");
+        if (exposure.kind === "operation") {
+            boundUrl(exposure.origin, exposure.path);
+            if (exposure.method === "GET" && exposure.body)
+                throw new Error("GET request bodies are unsupported");
+        }
+        if (exposure.kind === "workflow")
+            boundUrl(exposure.origin, workflowPath(exposure));
+        if (exposure.kind === "tool") {
+            const selected = exposure.bundle.definitions.filter((definition) => definition.name === exposure.toolName);
+            if (selected.length !== 1)
+                throw new Error("Tool selection must identify one installed definition");
+        }
+        return {
+            definition: exposure.definition,
+            resource: exposure.resource,
+            action: exposure.action,
+            visible: (context) => context.identity?.tenantId === exposure.tenantId,
+            async execute(args, context, params) {
+                if (!context.identity ||
+                    context.identity.tenantId !== exposure.tenantId)
+                    throw new McpError("Identity is not authorized for this binding", 403, -32602);
+                if (!(await exposure.approve(args, context)))
+                    throw new McpError("Invocation approval required", 403, -32602);
+                context.signal.throwIfAborted();
+                if (params.inputResponses !== undefined ||
+                    params.requestState !== undefined) {
+                    if (!exposure.continue)
+                        throw new McpError("Continuation unavailable", 400, -32602);
+                    return exposure.continue(params, context);
+                }
+                switch (exposure.kind) {
+                    case "tool": {
+                        const selected = exposure.bundle.definitions.find((definition) => definition.name === exposure.toolName);
+                        if (!selected)
+                            throw new Error("Selected tool is no longer available");
+                        validateInstance(selected.inputSchema, args);
+                        const result = await exposure.bundle.run({
+                            id: String(context.requestId),
+                            name: exposure.toolName,
+                            arguments: args,
+                        }, context.signal);
+                        if (exposure.projectResult)
+                            return exposure.projectResult(result, context);
+                        if (result.pendingMarker)
+                            throw new McpError("Pending tool requires a lifecycle projection", 500, -32603);
+                        // detail is deliberately host-only in Interchange; never leak it implicitly.
+                        return {
+                            ...(typeof result.content === "string"
+                                ? textResult(result.content)
+                                : jsonResult(result.content)),
+                            ...(result.isError === undefined
+                                ? {}
+                                : { isError: result.isError }),
+                        };
+                    }
+                    case "agent": {
+                        // Agent.send aborts the waiter, not the shared reactor. Never close a shared agent.
+                        const result = await exposure.agent.send(exposure.message(args), {
+                            signal: context.signal,
+                        });
+                        return result.type === "reply"
+                            ? textResult(result.reply)
+                            : exposure.suspended(result, context);
+                    }
+                    case "operation": {
+                        const body = exposure.body?.(args);
+                        const response = await exposure.dispatch(new Request(boundUrl(exposure.origin, exposure.path).href, {
+                            method: exposure.method,
+                            signal: context.signal,
+                            redirect: "error",
+                            ...(body === undefined
+                                ? {}
+                                : {
+                                    headers: { "Content-Type": "application/json" },
+                                    body: JSON.stringify(body),
+                                }),
+                        }), context.identity);
+                        return jsonResult(await responseJson(response));
+                    }
+                    case "workflow": {
+                        const intentId = await exposure.prepare(args, context);
+                        if (!intentId)
+                            throw new Error("Durable dispatch intent required");
+                        context.signal.throwIfAborted();
+                        const response = await exposure.dispatch(new Request(boundUrl(exposure.origin, workflowPath(exposure)).href, {
+                            method: "POST",
+                            signal: context.signal,
+                            redirect: "error",
+                            headers: { "Content-Type": "application/json" },
+                            body: JSON.stringify({ content: exposure.message(args) }),
+                        }), context.identity);
+                        const trigger = Trigger(await responseJson(response));
+                        if (trigger instanceof type.errors)
+                            throw new Error("Invalid workflow trigger response");
+                        await exposure.recordTrigger(intentId, trigger, context);
+                        return exposure.selectResult(trigger, context);
+                    }
+                }
+            },
+        };
+    });
+    return createToolProviders(bindings, options.auth);
+}
+function workflowPath(exposure) {
+    return `/api/tenants/${encodeURIComponent(exposure.tenantId)}/workflows/${encodeURIComponent(exposure.deploymentId)}/mail`;
+}

package/dist/naming.d.ts

@@ -22,3 +22,5 @@ export declare function toolDescription(tool: McpTool, server: string): string;
  * `destructiveHint: true` -- that flag wins no matter what is listed.
  */
 export declare function isAskExempt(qualified: string, tool: McpTool, allowWithoutAsk: readonly string[]): boolean;
+/** App-only tools never enter model definitions or the model dispatcher. */
+export declare function isModelVisible(tool: McpTool): boolean;

package/dist/naming.js

@@ -1,6 +1,8 @@
 // Naming and the ask floor, shared by the author-time `mcpTools` factory and
 // the deployed `mcpServers` sidecar bundle so both project a server's catalog
 // onto identical tool names and identical approval marks.
+import { validateUiToolMeta } from "./protocol/ui.js";
+import { isToolVisibleToModel } from "./extensions/apps.js";
 import { parseMcpEndpoint } from "./url.js";
 /** `<server>.<tool>`, the grantable unit: `tool:<server>.*` covers a server. */
 export function qualifiedName(server, tool) {
@@ -57,3 +59,8 @@ export function isAskExempt(qualified, tool, allowWithoutAsk) {
         return false;
     return allowWithoutAsk.includes(qualified);
 }
+/** App-only tools never enter model definitions or the model dispatcher. */
+export function isModelVisible(tool) {
+    const ui = tool._meta?.ui;
+    return isToolVisibleToModel(ui === undefined ? undefined : validateUiToolMeta(ui));
+}

package/dist/oauth-discovery.d.ts

@@ -1,4 +1,4 @@
-import type { FetchLike } from "@intx/harness";
+import type { FetchLike } from "./auth/http.js";
 import { type OAuthClientConfig } from "@corbits/oauth-core";
 export type McpAuthorizationServer = {
     issuer: string;
@@ -9,16 +9,26 @@ export type McpAuthorizationServer = {
     scopesSupported?: readonly string[];
     tokenEndpointAuthMethodsSupported?: readonly string[];
     codeChallengeMethodsSupported?: readonly string[];
+    /** Present only when the server sent `client_id_metadata_document_supported`. */
+    clientIdMetadataDocumentSupported?: boolean;
+    /** Present only when the server sent `authorization_response_iss_parameter_supported`. */
+    authorizationResponseIssParameterSupported?: boolean;
 };
 export type McpLoginEntry = {
     resourceUrl: string;
     authorizationServer: McpAuthorizationServer;
     resourceScopesSupported?: readonly string[];
+    /** Scope required by the actual MCP challenge, ahead of PRM defaults. */
+    challengeScope?: string;
 };
 export type DiscoverMcpLoginEntryOptions = {
     resourceUrl: string;
     fetchImpl?: FetchLike;
     timeoutMs?: number;
+    /** Challenge retained from the actual MCP 401/403 response. */
+    wwwAuthenticate?: string;
+    /** Pre-PRM compatibility only; modern MCP requires protected-resource metadata. */
+    allowLegacyAuthorizationServerFallback?: boolean;
 };
 export type RegisterMcpClientOptions = {
     registrationEndpoint: string;
@@ -26,6 +36,13 @@ export type RegisterMcpClientOptions = {
     clientName: string;
     grantTypesSupported?: readonly string[];
     scope?: string;
+    /**
+     * OIDC defaults an omitted `application_type` to `"web"`, which rejects
+     * loopback redirect URIs. Loopback and other public clients use `"native"`.
+     */
+    applicationType?: "native" | "web";
+    /** Recorded on the result so the caller can key the credential by issuer. */
+    issuer?: string;
     fetchImpl?: FetchLike;
     timeoutMs?: number;
 };
@@ -33,6 +50,38 @@ export type McpClientRegistration = {
     clientId: string;
     grantTypes: string[];
     scope?: string;
+    /** Set when `registerMcpClient` was given an issuer to persist with the credential. */
+    issuer?: string;
+};
+export type McpClientIdMetadataDocument = {
+    client_id: string;
+    client_name: string;
+    redirect_uris: string[];
+    grant_types: string[];
+    response_types: ["code"];
+    token_endpoint_auth_method: "none";
+};
+export type McpClientRegistrationPlan = {
+    mechanism: "pre-registered";
+    clientId: string;
+} | {
+    mechanism: "client-id-metadata";
+    clientId: string;
+} | {
+    mechanism: "dynamic";
+    registrationEndpoint: string;
+};
+export type StoredMcpClient = {
+    kind: "cimd" | "dynamic" | "pre-registered";
+    clientId: string;
+    /** Required for `dynamic` and `pre-registered`. CIMD credentials are portable. */
+    issuer?: string;
+};
+export type AuthorizationIssuerOptions = {
+    recordedIssuer: string;
+    /** Absent when the authorization response omitted `iss`. An empty string is present. */
+    iss?: string;
+    authorizationResponseIssParameterSupported?: boolean;
 };
 export type McpClientConfigOptions = {
     clientId: string;
@@ -59,6 +108,63 @@ export declare function discoverMcpLoginEntry(opts: DiscoverMcpLoginEntryOptions
  * rejects the request.
  */
 export declare function registerMcpClient(opts: RegisterMcpClientOptions): Promise<McpClientRegistration>;
+/**
+ * Build a Client ID Metadata Document whose `client_id` is the document URL.
+ * The caller hosts the returned JSON at that exact URL.
+ */
+export declare function mcpClientIdMetadataDocument(opts: {
+    metadataUrl: string;
+    clientName: string;
+    redirectUris: readonly string[];
+    grantTypes?: readonly string[];
+}): McpClientIdMetadataDocument;
+/**
+ * Registration priority: pre-registered client id, then a Client ID Metadata
+ * Document when the authorization server advertises support and a metadata
+ * URL is available, then RFC 7591. Anything else is an error.
+ */
+export declare function preferredMcpClientRegistration(opts: {
+    authorizationServer: Pick<McpAuthorizationServer, "clientIdMetadataDocumentSupported" | "registrationEndpoint">;
+    preRegisteredClientId?: string;
+    clientMetadataUrl?: string;
+}): McpClientRegistrationPlan;
+/**
+ * CIMD client ids are portable across issuers. Dynamic and pre-registered
+ * credentials are keyed by issuer and must be registered again when it changes.
+ * Issuers are compared exactly, including trailing slashes.
+ */
+export declare function resolveStoredMcpClient(issuer: string, stored: StoredMcpClient): {
+    clientId: string;
+};
+/**
+ * RFC 9207 via the MCP authorization spec. A present `iss` (including an
+ * empty string) must equal the recorded issuer with no normalization. When
+ * the server advertises `authorization_response_iss_parameter_supported`, a
+ * missing `iss` is rejected. Otherwise a missing `iss` is allowed.
+ */
+export declare function assertAuthorizationIssuer(opts: AuthorizationIssuerOptions): void;
+/** Validate callback provenance without acting on code or terminal error fields.
+ * Callers may consume a one-use login only after this and their state check pass. */
+export declare function assertAuthorizationCallbackIssuer(params: URLSearchParams | Record<string, string | undefined | null>, opts: Omit<AuthorizationIssuerOptions, "iss">): void;
+/**
+ * Mix-up defense for metadata that names an authorization or token endpoint
+ * on a different origin than the issuer. RFC 9207 allows a missing `iss` when
+ * the server does not advertise `authorization_response_iss_parameter_supported`,
+ * but that would send the code and PKCE verifier to whichever token endpoint
+ * the metadata named. Cross-origin endpoints require a present `iss` equal to
+ * the recorded issuer. Same-origin issuers keep the ordinary missing-`iss` rule.
+ */
+export declare function assertCrossOriginAuthorizationIssuer(params: URLSearchParams | Record<string, string | undefined | null>, server: Pick<McpAuthorizationServer, "issuer" | "authorizationEndpoint" | "tokenEndpoint">): void;
+/**
+ * Read an authorization callback. `iss` is checked before `error` or `code`
+ * is acted on, and this function does not redeem the code.
+ */
+export declare function readAuthorizationCallback(params: URLSearchParams | Record<string, string | undefined | null>, opts: {
+    recordedIssuer: string;
+    authorizationResponseIssParameterSupported?: boolean;
+}): {
+    code: string;
+};
 export declare function selectMcpScopes(opts: SelectMcpScopesOptions): string[];
 /**
  * Build the OAuth client config for a discovered entry plus a registered