@jini-ai/mcp 0.3.4 → 0.4.1

package/dist/federation/testing/adapter.memory.js

@@ -0,0 +1,189 @@
+/**
+ * @file The in-memory doubles for both federation seams — rule-of-two's partner to
+ * `adapter.stdio.ts`, and this codebase's usual `repo.memory.ts`/`repo.sqlite.ts` split applied to
+ * an outbound protocol boundary instead of a database.
+ *
+ * One double per seam (see `ports.ts`), and they test different things:
+ *
+ * - {@link InMemoryMcpSession} fakes `McpSessionPort`, i.e. "an MCP server exists and behaves". It
+ * is what `registrations.ts`'s tests use, so the trust tier and the registration wiring are
+ * exercised with no protocol in the picture at all.
+ *
+ * - {@link ScriptedMcpStdioChannel} fakes `McpStdioChannel`, i.e. raw newline-delimited JSON-RPC.
+ * It is what `adapter.stdio.ts`'s OWN tests use, so the real client's handshake ordering,
+ * pagination, id correlation, timeout and close behaviour are exercised against something that
+ * can also misbehave on purpose — reply out of order, reply late, reply twice, never reply,
+ * send an unsolicited request, or die mid-flight.
+ *
+ * - {@link ScriptedMcpHttpExchange} does the same for `McpHttpExchange`, the hosted transport's
+ * seam, so `adapter.http.ts` is under test on the same terms.
+ *
+ * Those inner-seam doubles are the ones that make the "no live third-party server in this sandbox"
+ * constraint survivable: the protocol code under test is the real production code, and only the
+ * pipe beneath it is fake. A double at the outer seam alone would have proved only that the double
+ * works.
+ *
+ * Architectural role:
+ * Test doubles. Ships in `src/` beside the port they implement, exactly as every feature's
+ * `repo.memory.ts` does, so they are importable from `__tests__/` without a second tsconfig.
+ * See docs/decisions/DR-003-trusted-federation-composition.md.
+ */
+/**
+ * A scripted `McpSessionPort`: a fixed tool list plus a per-tool call handler.
+ *
+ * `callTool` records every call, so a test can assert not just the returned value but that the
+ * REMOTE NAME was sent — the property that proves namespacing is applied on the way in and stripped
+ * on the way out, which is the single most load-bearing behaviour in the registration layer.
+ */
+export class InMemoryMcpSession {
+    calls = [];
+    closed = false;
+    tools;
+    handler;
+    listToolsBehaviour;
+    constructor({ tools }, options = {}) {
+        this.tools = [...tools];
+        this.handler = options.onCall ?? (({ name, args }) => ({ content: [{ type: "text", text: `called ${name} with ${JSON.stringify(args)}` }] }));
+        this.listToolsBehaviour = options.onListTools;
+    }
+    async listTools() {
+        if (this.listToolsBehaviour)
+            return this.listToolsBehaviour();
+        return [...this.tools];
+    }
+    async callTool(request, _options = {}) {
+        this.calls.push({ name: request.name, arguments: request.arguments });
+        return this.handler({ name: request.name, args: request.arguments });
+    }
+    async close(_required) {
+        this.closed = true;
+    }
+}
+/**
+ * A fake {@link McpStdioChannel} that plays the SERVER side of MCP, under the test's control.
+ *
+ * `respond` is a plain function of the received message, so a test scripts a server by writing one:
+ * return a response object to reply, or `undefined` to stay silent (the case that exercises the
+ * client's timeout path). Everything the client sends is captured in {@link sent}, which is how
+ * handshake ordering is asserted — that `initialize` comes first and that
+ * `notifications/initialized` follows it with no `id`.
+ */
+export class ScriptedMcpStdioChannel {
+    /** Every message the client wrote, parsed, in order. */
+    sent = [];
+    closedReason = null;
+    messageListeners = [];
+    closeListeners = [];
+    respond;
+    messages;
+    constructor(options) {
+        this.respond = options.respond;
+        this.messages = options.messages;
+    }
+    send({ message }) {
+        if (this.closedReason !== null)
+            throw new Error("scripted channel is closed");
+        const parsed = JSON.parse(message);
+        this.sent.push(parsed);
+        const reply = this.respond({ message: parsed });
+        // Delivered on a later microtask, as a real pipe would: a client that only works when its reply
+        // arrives synchronously inside its own `send` is a client that does not work.
+        if (reply !== undefined)
+            queueMicrotask(() => this.deliver({ message: reply }));
+    }
+    onMessage({ listener }) {
+        this.messageListeners.push(listener);
+    }
+    onClose({ listener }) {
+        this.closeListeners.push(listener);
+    }
+    close(_required) {
+        this.fail({ reason: this.messages.closedByHost });
+    }
+    /** Pushes a message to the client out of band — for late replies, unsolicited server requests,
+     * and notifications. */
+    deliver({ message }) {
+        const line = typeof message === "string" ? message : JSON.stringify(message);
+        for (const listener of this.messageListeners)
+            listener({ message: line });
+    }
+    /** Simulates the far end dying. */
+    fail({ reason }) {
+        if (this.closedReason !== null)
+            return;
+        this.closedReason = reason;
+        for (const listener of this.closeListeners)
+            listener({ reason: reason });
+    }
+    /** The last id the client used for `method`, for building a matching reply. */
+    idFor({ method }) {
+        for (let i = this.sent.length - 1; i >= 0; i -= 1) {
+            if (this.sent[i]?.method === method)
+                return this.sent[i]?.id;
+        }
+        return undefined;
+    }
+}
+/**
+ * A fake {@link McpHttpExchange} that plays the SERVER side of MCP's Streamable HTTP transport.
+ *
+ * The hosted counterpart to {@link ScriptedMcpStdioChannel}, and it exists for the same reason: so
+ * `adapter.http.ts`'s REAL handshake ordering, session-id propagation, SSE framing, pagination,
+ * status mapping and timeout behaviour are exercised against something that can misbehave on
+ * purpose — answer 401, answer with an unparseable body, issue a header-injecting session id,
+ * paginate forever, or never answer at all — rather than against a stub of the client itself.
+ *
+ * `respond` is a plain function of the received request, so a test scripts a server by writing one.
+ * Returning `undefined` means "never answer", which is how the timeout path is reached: the
+ * returned promise stays pending until the client's own `AbortSignal` fires.
+ */
+export class ScriptedMcpHttpExchange {
+    /** Every request the client made, in order. */
+    sent = [];
+    respond;
+    constructor(options) {
+        this.respond = options.respond;
+    }
+    async send(request, options = {}) {
+        const captured = {
+            url: request.url,
+            method: request.method,
+            headers: { ...request.headers },
+            message: options.body === undefined ? undefined : JSON.parse(options.body),
+        };
+        this.sent.push(captured);
+        const reply = this.respond({ request: captured });
+        if (reply === undefined)
+            return this.neverAnswer(options.signal);
+        return {
+            status: reply.status ?? 200,
+            contentType: reply.contentType ?? "application/json",
+            ...(reply.sessionId === undefined ? {} : { sessionId: reply.sessionId }),
+            ...(reply.wwwAuthenticate === undefined ? {} : { wwwAuthenticate: reply.wwwAuthenticate }),
+            text: typeof reply.body === "string" ? reply.body : JSON.stringify(reply.body ?? {}),
+        };
+    }
+    /** A server that accepts the request and then goes quiet. Settles only when the client aborts,
+     *  which is exactly what a real stalled connection does. */
+    neverAnswer(signal) {
+        return new Promise((_resolve, reject) => {
+            if (!signal)
+                return;
+            if (signal.aborted) {
+                reject(new Error("aborted"));
+                return;
+            }
+            signal.addEventListener("abort", () => reject(new Error("aborted")), { once: true });
+        });
+    }
+    /** The last request whose JSON-RPC `method` matches, for asserting on what was sent. */
+    lastRequestFor({ method }) {
+        for (let i = this.sent.length - 1; i >= 0; i -= 1) {
+            const candidate = this.sent[i];
+            if (candidate?.message?.method === method)
+                return candidate;
+        }
+        return undefined;
+    }
+}
+//# sourceMappingURL=adapter.memory.js.map

package/dist/federation/testing/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./adapter.memory.js";
+export * from "./tool-approvals.memory.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/federation/testing/index.js

@@ -0,0 +1,3 @@
+export * from "./adapter.memory.js";
+export * from "./tool-approvals.memory.js";
+//# sourceMappingURL=index.js.map

package/dist/federation/testing/tool-approvals.memory.d.ts

@@ -0,0 +1,27 @@
+import type { ExternalMcpToolApprovalRepoPort, ExternalMcpToolApprovalRecord, ConversationToolApprovalStore } from "../tool-approvals.js";
+/** In-memory {@link ExternalMcpToolApprovalRepoPort}, for DB-less compositions and tests. */
+export declare class InMemoryExternalMcpToolApprovalRepo implements ExternalMcpToolApprovalRepoPort {
+    private readonly rows;
+    constructor(_required: Record<string, never>);
+    find(input: {
+        serverId: string;
+        toolName: string;
+    }, optional?: {
+        scope?: string;
+    }): Promise<ExternalMcpToolApprovalRecord | null>;
+    upsert(record: Omit<ExternalMcpToolApprovalRecord, "scope">, optional?: {
+        scope?: string;
+    }): Promise<void>;
+    listByScope(_required: Record<string, never>, { scope }?: {
+        scope?: string;
+    }): Promise<ExternalMcpToolApprovalRecord[]>;
+    delete(input: {
+        serverId: string;
+        toolName: string;
+    }, optional?: {
+        scope?: string;
+    }): Promise<boolean>;
+}
+/** In-memory {@link ConversationToolApprovalStore}, for DB-less compositions and tests. */
+export declare function createInMemoryConversationToolApprovalStore(_required: Record<string, never>): ConversationToolApprovalStore;
+//# sourceMappingURL=tool-approvals.memory.d.ts.map

package/dist/federation/testing/tool-approvals.memory.js

@@ -0,0 +1,38 @@
+function approvalKey(input, optional) {
+    return JSON.stringify([optional.scope, input.serverId, input.toolName]);
+}
+/** In-memory {@link ExternalMcpToolApprovalRepoPort}, for DB-less compositions and tests. */
+export class InMemoryExternalMcpToolApprovalRepo {
+    rows = new Map();
+    constructor(_required) { }
+    async find(input, optional = {}) {
+        return this.rows.get(approvalKey(input, optional)) ?? null;
+    }
+    async upsert(record, optional = {}) {
+        const scopedRecord = { ...record, ...optional };
+        // Scope belongs to the options bag, even if a caller passes a record with extra fields.
+        if (optional.scope === undefined)
+            delete scopedRecord.scope;
+        this.rows.set(approvalKey(record, optional), scopedRecord);
+    }
+    async listByScope(_required, { scope } = {}) {
+        return [...this.rows.values()].filter((row) => row.scope === scope);
+    }
+    async delete(input, optional = {}) {
+        return this.rows.delete(approvalKey(input, optional));
+    }
+}
+/** In-memory {@link ConversationToolApprovalStore}, for DB-less compositions and tests. */
+export function createInMemoryConversationToolApprovalStore(_required) {
+    const rows = new Map();
+    const keyOf = (key) => JSON.stringify([key.conversationId, key.principalId, key.connectionId, key.toolName]);
+    return {
+        async has(key) {
+            return rows.get(keyOf(key)) === key.fingerprint;
+        },
+        async grant({ key }) {
+            rows.set(keyOf(key), key.fingerprint);
+        },
+    };
+}
+//# sourceMappingURL=tool-approvals.memory.js.map

package/dist/federation/tool-approvals.d.ts

@@ -0,0 +1,97 @@
+import type { FederatedConnectionOrigin, RemoteToolDescriptor } from "./ports.js";
+/**
+ * Shared remembered approvals for external servers, agent plugins and integrations; no plugin
+ * configuration is read here. Chat grants belong to a conversation AND a person, so another
+ * person's conversation id cannot reuse them. Always grants belong beside a connection in the
+ * host store, for its operator to list and revoke. A fingerprint pins both scopes to exactly the
+ * admitted tool; changes to server identity, hints, description or schema ask again.
+ * Destructive calls always require a fresh one-call answer and never use either remembered scope.
+ *
+ * How long a person's answer on the card should count. `once` is the plain "Allow".
+ */
+export type FederatedApprovalScope = "once" | "chat" | "always";
+/** Everything that identifies a tool for a remembered approval — change any of it and it asks again. */
+export interface FederatedToolIdentity {
+    readonly connectionId: string;
+    readonly remoteName: string;
+    /** The hints recorded when the tool was admitted (`AdmittedFederatedTool.declaredAnnotations`). */
+    readonly declaredAnnotations: RemoteToolDescriptor["annotations"] | undefined;
+    /**
+     * Where the connection came from. A roster connection's `admissionRevision` already changes when
+     * its url/command/args/transport/auth mode/credential or the row itself changes
+     * (`externalMcpAdmissionRevision`), which is what "the server changed" means here.
+     */
+    readonly origin: FederatedConnectionOrigin | undefined;
+    /** The description the model reads, as admitted (`AdmittedFederatedTool.description`). */
+    readonly description: string;
+    /** The input schema, as admitted. */
+    readonly inputSchema: Readonly<Record<string, unknown>>;
+}
+/**
+ * The fingerprint a remembered approval is saved under and later matched against: the connection,
+ * the server it reaches (its origin and admission revision), the remote tool name, its declared
+ * hints, the description the model reads and its input schema — so any drift in what the tool says
+ * about itself voids the approval. Object keys are sorted first, so key order alone never counts as
+ * drift. Hashed, because an admission revision is itself derived from values that can carry
+ * credentials and this string is stored and compared, never shown.
+ *
+ * The host supplies the persisted domain. Changing it invalidates remembered grants.
+ * The v2 revision (2026-09-27, "hint drift") added description and input schema: v1 grants
+ * no longer matched, asked once and were saved again. A host must keep its chosen bytes stable.
+ *
+ * @complexity O(h + s) in the size of the hints and the schema.
+ */
+export declare function federatedToolApprovalFingerprint({ identity, fingerprintDomain }: {
+    identity: FederatedToolIdentity;
+    fingerprintDomain: string;
+}): string;
+/** One saved "Always allow". */
+export interface ExternalMcpToolApprovalRecord {
+    readonly scope?: string;
+    readonly serverId: string;
+    readonly toolName: string;
+    readonly fingerprint: string;
+    readonly grantedByPrincipalId: string;
+    readonly grantedAt: string;
+}
+/** The "Always allow" store (`external_mcp_tool_approvals`). */
+export interface ExternalMcpToolApprovalRepoPort {
+    find(input: {
+        serverId: string;
+        toolName: string;
+    }, optional?: {
+        scope?: string;
+    }): Promise<ExternalMcpToolApprovalRecord | null>;
+    /** Inserts, or replaces the fingerprint/grant of, the one row for scope + connection + tool. */
+    upsert(record: Omit<ExternalMcpToolApprovalRecord, "scope">, optional?: {
+        scope?: string;
+    }): Promise<void>;
+    listByScope(input: Record<string, never>, optional?: {
+        scope?: string;
+    }): Promise<ExternalMcpToolApprovalRecord[]>;
+    /** @returns Whether a row was removed. */
+    delete(input: {
+        serverId: string;
+        toolName: string;
+    }, optional?: {
+        scope?: string;
+    }): Promise<boolean>;
+}
+/** One saved "Allow for this chat". */
+export interface ConversationToolApprovalKey {
+    readonly conversationId: string;
+    readonly principalId: string;
+    readonly connectionId: string;
+    readonly toolName: string;
+    readonly fingerprint: string;
+}
+/** The "Allow for this chat" store, kept with the conversation (`chat.db`). */
+export interface ConversationToolApprovalStore {
+    /** True only for this conversation AND this person AND this exact fingerprint. */
+    has(key: ConversationToolApprovalKey): Promise<boolean>;
+    grant(input: {
+        key: ConversationToolApprovalKey;
+        grantedAt: string;
+    }): Promise<void>;
+}
+//# sourceMappingURL=tool-approvals.d.ts.map

package/dist/federation/tool-approvals.js

@@ -0,0 +1,42 @@
+import { createHash } from "node:crypto";
+/** Stable JSON: object keys sorted at every depth, so the same hints always hash the same. */
+function canonicalJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(",")}]`;
+    if (value !== null && typeof value === "object") {
+        const entries = Object.entries(value)
+            .filter(([, child]) => child !== undefined)
+            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+        return `{${entries.map(([key, child]) => `${JSON.stringify(key)}:${canonicalJson(child)}`).join(",")}}`;
+    }
+    return JSON.stringify(value) ?? "null";
+}
+/**
+ * The fingerprint a remembered approval is saved under and later matched against: the connection,
+ * the server it reaches (its origin and admission revision), the remote tool name, its declared
+ * hints, the description the model reads and its input schema — so any drift in what the tool says
+ * about itself voids the approval. Object keys are sorted first, so key order alone never counts as
+ * drift. Hashed, because an admission revision is itself derived from values that can carry
+ * credentials and this string is stored and compared, never shown.
+ *
+ * The host supplies the persisted domain. Changing it invalidates remembered grants.
+ * The v2 revision (2026-09-27, "hint drift") added description and input schema: v1 grants
+ * no longer matched, asked once and were saved again. A host must keep its chosen bytes stable.
+ *
+ * @complexity O(h + s) in the size of the hints and the schema.
+ */
+export function federatedToolApprovalFingerprint({ identity, fingerprintDomain }) {
+    const origin = identity.origin === undefined ? null : identity.origin.kind === "roster" ? ["roster", identity.origin.admissionRevision] : ["preset"];
+    return createHash("sha256")
+        .update(canonicalJson([
+        fingerprintDomain,
+        identity.connectionId,
+        origin,
+        identity.remoteName,
+        identity.declaredAnnotations ?? null,
+        identity.description,
+        identity.inputSchema,
+    ]))
+        .digest("hex");
+}
+//# sourceMappingURL=tool-approvals.js.map