@jini-ai/mcp 0.3.4 → 0.4.1

package/dist/tools/ask-choice/schema.d.ts

@@ -0,0 +1,91 @@
+/** Model input schema. Callback correlation params are carried by the rendered form only. */
+export declare const ASK_CHOICE_INPUT_SCHEMA: {
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly required: readonly ["title"];
+    readonly anyOf: readonly [{
+        readonly required: readonly ["singleSelect"];
+    }, {
+        readonly required: readonly ["multiSelect"];
+    }];
+    readonly properties: {
+        readonly title: {
+            readonly type: "string";
+        };
+        readonly description: {
+            readonly type: "string";
+        };
+        readonly submitLabel: {
+            readonly type: "string";
+        };
+        readonly singleSelect: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly required: readonly ["label", "options"];
+            readonly properties: {
+                readonly label: {
+                    readonly type: "string";
+                };
+                readonly options: {
+                    readonly type: "array";
+                    readonly minItems: 1;
+                    readonly items: {
+                        readonly type: "object";
+                        readonly additionalProperties: false;
+                        readonly required: readonly ["value", "label"];
+                        readonly properties: {
+                            readonly value: {
+                                readonly type: "string";
+                            };
+                            readonly label: {
+                                readonly type: "string";
+                            };
+                        };
+                    };
+                };
+            };
+        };
+        readonly multiSelect: {
+            readonly properties: {
+                readonly hint: {
+                    readonly type: "string";
+                };
+                readonly label: {
+                    readonly type: "string";
+                };
+                readonly options: {
+                    readonly type: "array";
+                    readonly minItems: 1;
+                    readonly items: {
+                        readonly type: "object";
+                        readonly additionalProperties: false;
+                        readonly required: readonly ["value", "label"];
+                        readonly properties: {
+                            readonly value: {
+                                readonly type: "string";
+                            };
+                            readonly label: {
+                                readonly type: "string";
+                            };
+                        };
+                    };
+                };
+            };
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly required: readonly ["label", "options"];
+        };
+        readonly choice: {
+            readonly type: "string";
+            readonly description: "Set by the rendered form; never by the model.";
+        };
+        readonly selections: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+            readonly description: "Set by the rendered form; never by the model.";
+        };
+    };
+};
+//# sourceMappingURL=schema.d.ts.map

package/dist/tools/ask-choice/schema.js

@@ -0,0 +1,27 @@
+const optionSchema = {
+    type: 'object', additionalProperties: false, required: ['value', 'label'],
+    properties: { value: { type: 'string' }, label: { type: 'string' } },
+};
+const selectSchema = {
+    type: 'object', additionalProperties: false, required: ['label', 'options'],
+    properties: {
+        label: { type: 'string' },
+        options: { type: 'array', minItems: 1, items: optionSchema },
+    },
+};
+/** Model input schema. Callback correlation params are carried by the rendered form only. */
+export const ASK_CHOICE_INPUT_SCHEMA = {
+    type: 'object', additionalProperties: false, required: ['title'],
+    anyOf: [{ required: ['singleSelect'] }, { required: ['multiSelect'] }],
+    properties: {
+        title: { type: 'string' }, description: { type: 'string' }, submitLabel: { type: 'string' },
+        singleSelect: selectSchema,
+        multiSelect: {
+            ...selectSchema,
+            properties: { ...selectSchema.properties, hint: { type: 'string' } },
+        },
+        choice: { type: 'string', description: 'Set by the rendered form; never by the model.' },
+        selections: { type: 'array', items: { type: 'string' }, description: 'Set by the rendered form; never by the model.' },
+    },
+};
+//# sourceMappingURL=schema.js.map

package/dist/tools/ask-choice/types.d.ts

@@ -0,0 +1,106 @@
+/** Product-neutral question content; rendering and copy belong to the host. */
+export interface AskChoiceSelect {
+    readonly label: string;
+    readonly hint?: string;
+    readonly options: ReadonlyArray<{
+        value: string;
+        label: string;
+    }>;
+}
+export interface AskChoiceQuestion {
+    readonly title: string;
+    readonly description?: string;
+    readonly submitLabel?: string;
+    readonly singleSelect?: AskChoiceSelect;
+    readonly multiSelect?: AskChoiceSelect;
+}
+export interface AskChoiceMessages {
+    readonly pending: string;
+    readonly forgedAnswer: string;
+    readonly submitted: string;
+    readonly typed: string;
+    readonly noAnswer: string;
+    readonly cancelled: string;
+    readonly expired: string;
+    readonly abandoned: string;
+}
+export type AskChoiceMessage = {
+    status: 'received';
+    params: Record<string, unknown>;
+} | {
+    status: 'expired' | 'abandoned';
+};
+export interface AskChoiceEmission {
+    channel: 'mcp-ui';
+    payload: {
+        resource: unknown;
+    };
+}
+export type AskChoiceEmitter = (args: {
+    emission: AskChoiceEmission;
+}) => Promise<void>;
+/** The host owns correlation, principal binding, buffering, and expiry of live exchanges. */
+export interface AskChoiceExchange {
+    readonly id: string;
+    send(args: {
+        emission: AskChoiceEmission;
+    }): Promise<void>;
+    receive(args: Record<string, never>): Promise<AskChoiceMessage>;
+    close(args: Record<string, never>): void;
+}
+export interface AskChoiceExchangeStore {
+    open(args: {
+        toolId: string;
+        principalId: string;
+        emit: AskChoiceEmitter;
+    }): AskChoiceExchange;
+}
+/** Redeem consumes before checking binding, time, and offered options; rejection is fail-closed. */
+export interface AskChoicePendingStore {
+    mint(args: {
+        principalId: string;
+        question: AskChoiceQuestion;
+    }): string;
+    redeem(args: {
+        ticket: string | undefined;
+        principalId: string;
+        params: Record<string, unknown>;
+    }): boolean;
+}
+export interface AskChoiceCall {
+    principalId: string;
+    input: unknown;
+    signal: AbortSignal;
+    emitSurface?: AskChoiceEmitter;
+}
+/** Authorization is invoked before either displaying a question or redeeming its answer. */
+export interface AskChoicePolicy {
+    authorize(args: {
+        ctx: AskChoiceCall;
+        toolId: string;
+    }): void | Promise<void>;
+    inputError(args: {
+        message: string;
+    }): Error;
+    shapeError(args: {
+        message: string;
+        toolId: string;
+        inputSchema: Readonly<Record<string, unknown>>;
+    }): Error;
+}
+export interface AskChoiceForm {
+    toolName: string;
+    principalId: string;
+    question: AskChoiceQuestion;
+    baseParams: Record<string, unknown>;
+    cancelParams?: Record<string, unknown>;
+}
+/** The host supplies resource identity, labels, field presentation, app metadata, and result encoding. */
+export interface AskChoicePresentation {
+    render(args: Omit<AskChoiceForm, 'cancelParams'>, options?: Pick<AskChoiceForm, 'cancelParams'>): unknown;
+    buildResult(args: {
+        modelText: string;
+        ui: unknown;
+    }): Record<string, unknown>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/tools/ask-choice/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jini-ai/mcp",
-  "version": "0.3.4",
+  "version": "0.4.1",
   "description": "Model Context Protocol adapters: server config schema and IO, an MCP client, and agent-side MCP server installation.",
   "license": "Apache-2.0",
   "repository": {
@@ -11,7 +11,16 @@
   "jini": {
     "domain": "integration",
     "kind": "protocol-adapter",
-    "runtime": "node"
+    "runtime": "node",
+    "entries": {
+      ".": "node",
+      "./bin": "node",
+      "./tools/ask-choice": "universal",
+      "./federation": "node",
+      "./federation/approvals": "node",
+      "./federation/stdio": "node",
+      "./federation/testing": "universal"
+    }
   },
   "type": "module",
   "sideEffects": false,
@@ -23,7 +32,34 @@
       "import": "./dist/index.js",
       "default": "./dist/index.js"
     },
+    "./tools/ask-choice": {
+      "types": "./dist/tools/ask-choice/index.d.ts",
+      "import": "./dist/tools/ask-choice/index.js",
+      "default": "./dist/tools/ask-choice/index.js"
+    },
+    "./federation": {
+      "types": "./dist/federation/index.d.ts",
+      "import": "./dist/federation/index.js",
+      "default": "./dist/federation/index.js"
+    },
+    "./federation/approvals": {
+      "types": "./dist/federation/approvals/index.d.ts",
+      "import": "./dist/federation/approvals/index.js",
+      "default": "./dist/federation/approvals/index.js"
+    },
+    "./federation/stdio": {
+      "types": "./dist/federation/stdio/index.d.ts",
+      "import": "./dist/federation/stdio/index.js",
+      "default": "./dist/federation/stdio/index.js"
+    },
+    "./federation/testing": {
+      "types": "./dist/federation/testing/index.d.ts",
+      "import": "./dist/federation/testing/index.js",
+      "default": "./dist/federation/testing/index.js"
+    },
     "./bin": {
+      "types": "./dist/bin/serve.d.ts",
+      "import": "./dist/bin/serve.js",
       "default": "./dist/bin/serve.js"
     }
   },
@@ -32,6 +68,9 @@
   },
   "files": [
     "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
     "!dist/**/*.test.js",
     "!dist/**/*.test.d.ts",
     "!dist/**/*.test.js.map",
@@ -46,9 +85,8 @@
   "dependencies": {
     "@cfworker/json-schema": "^4.1.1",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "undici": "^7.25.0",
-    "@jini-ai/platform": "0.3.0",
-    "@jini-ai/cli": "0.3.1"
+    "@jini-ai/platform": "^0.5.1",
+    "@jini-ai/core": "^0.4.1"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json && chmod +x dist/bin/serve.js",

package/dist/core/oauth.d.ts

@@ -1,274 +0,0 @@
-/**
- * @module @jini-ai/mcp/core/oauth
- * Daemon-side OAuth 2.1 / PKCE client for remote (HTTP / SSE) MCP servers:
- * auth-server discovery, dynamic client registration, the authorize/token/refresh
- * exchanges, and the in-memory `PendingAuthCache`. Part of the MCP `core` kernel;
- * depends on no sibling subdirectory.
- */
-import { createValidatingLookup } from '@jini-ai/platform';
-/** RFC 9728 `oauth-protected-resource` document fields we use. */
-export interface ProtectedResourceMetadata {
-    resource?: string;
-    authorization_servers?: string[];
-    scopes_supported?: string[];
-}
-/** RFC 8414 / OIDC discovery document fields we use. */
-export interface AuthorizationServerMetadata {
-    issuer: string;
-    authorization_endpoint: string;
-    token_endpoint: string;
-    registration_endpoint?: string;
-    scopes_supported?: string[];
-    response_types_supported?: string[];
-    grant_types_supported?: string[];
-    code_challenge_methods_supported?: string[];
-    token_endpoint_auth_methods_supported?: string[];
-}
-/** Cached client registration for a given auth server + redirect URI. */
-export interface RegisteredClient {
-    authServerIssuer: string;
-    redirectUri: string;
-    clientId: string;
-    clientSecret?: string;
-    registeredAt: number;
-}
-/** RFC 6749 §5.1 token endpoint response (subset). */
-export interface OAuthTokenResponse {
-    access_token: string;
-    token_type?: string;
-    expires_in?: number;
-    refresh_token?: string;
-    scope?: string;
-}
-/** In-flight authorization request. Stashed in memory while the user
- * approves in their browser. */
-export interface PendingAuthState {
-    serverId: string;
-    authServerIssuer: string;
-    tokenEndpoint: string;
-    clientId: string;
-    clientSecret?: string;
-    redirectUri: string;
-    codeVerifier: string;
-    scope?: string;
-    resourceUrl?: string;
-    createdAt: number;
-}
-type DnsLookupCb = Parameters<typeof createValidatingLookup>[0];
-/**
- * Read a response body up to `maxBytes`, aborting `controller` (when given)
- * and throwing the moment the cap is exceeded rather than buffering an
- * unbounded body first. Falls back to a single `res.text()` call (tolerant
- * of a throw, matching the old `safeText`'s forgiving error-path behavior)
- * for response-like test doubles that don't expose a real `ReadableStream`
- * body.
- *
- * `controller` is real, intentional API surface — a caller that already has
- * an in-flight fetch's `AbortController` can pass it so an oversized
- * response stops being pulled from upstream the moment the cap is exceeded,
- * not merely rejected after the fact — but no real call site in this file
- * currently has one in scope to pass (each of the four call sites reads a
- * `Response` it received after its own `safeOAuthFetch` call already
- * returned, by which point that call's own `AbortController` is out of
- * scope). Exported (not just internal) so this real, functioning behavior
- * is directly unit-testable without inventing an unused call site just to
- * reach it — matching this repo's established "extract into a directly-
- * testable pure function" convention.
- */
-export declare function readCappedText(res: Response, maxBytes: number, controller?: AbortController): Promise<string>;
-/**
- * Generate a cryptographically random PKCE code verifier (RFC 7636 §4.1).
- * Produces a 64-byte base64url-encoded string, within the 43–128 character range.
- * @returns A fresh code verifier string for use in a single authorization request.
- */
-export declare function generateCodeVerifier(): string;
-/**
- * Derive the S256 PKCE code challenge from a code verifier (RFC 7636 §4.2).
- * Computes `BASE64URL(SHA256(ASCII(verifier)))`.
- * @param verifier The code verifier string produced by `generateCodeVerifier`.
- * @returns The base64url-encoded SHA-256 hash to pass as `code_challenge`.
- */
-export declare function deriveCodeChallenge(verifier: string): string;
-/**
- * Generate a cryptographically random OAuth `state` parameter.
- * Used as the CSRF token for the authorization request; must be unique per flow.
- * @returns A base64url-encoded 32-byte random string.
- */
-export declare function generateState(): string;
-/**
- * Try to fetch the protected-resource metadata for a given MCP URL.
- *
- * Per RFC 9728, the well-known is at the resource origin's
- * `/.well-known/oauth-protected-resource[<path>]`. We try both the
- * path-suffixed form and the bare `/.well-known/...` so servers that
- * only publish at the root still work.
- *
- * @param lookupImpl Injectable `dns.lookup` for the connection-time SSRF
- *   guard (tests only — see `safeOAuthFetch`).
- */
-export declare function discoverProtectedResource(resourceUrl: string, fetchImpl?: typeof fetch, lookupImpl?: DnsLookupCb): Promise<ProtectedResourceMetadata | null>;
-/**
- * Fetch the authorization-server metadata for an issuer URL. Tries both
- * the OAuth (RFC 8414) and OIDC layouts (`/.well-known/oauth-authorization-server`
- * and `/.well-known/openid-configuration`); some providers only publish one.
- *
- * Per RFC 8414 §3.3, a discovery document's `issuer` — when present — MUST
- * match the issuer used to construct the request; a mismatched document is
- * rejected rather than trusted (SEC-RB-001 / CR-005). Every endpoint the
- * document names (`authorization_endpoint`, `token_endpoint`,
- * `registration_endpoint`) is additionally required to be an absolute
- * `https:` URL sharing the queried issuer's own origin, so a compromised or
- * hostile document can't redirect DCR or token exchange at an unrelated
- * origin.
- *
- * @param lookupImpl Injectable `dns.lookup` for the connection-time SSRF
- *   guard (tests only — see `safeOAuthFetch`).
- */
-export declare function discoverAuthServer(issuer: string, fetchImpl?: typeof fetch, lookupImpl?: DnsLookupCb): Promise<AuthorizationServerMetadata | null>;
-/**
- * POST to the auth server's `registration_endpoint` per RFC 7591. Returns
- * a freshly issued client_id (and optional client_secret). Caller is
- * responsible for caching the result.
- * @param lookupImpl Injectable `dns.lookup` for the connection-time SSRF
- *   guard (tests only — see `safeOAuthFetch`).
- */
-export declare function registerClient(registrationEndpoint: string, redirectUri: string, fetchImpl?: typeof fetch, lookupImpl?: DnsLookupCb): Promise<{
-    clientId: string;
-    clientSecret?: string;
-}>;
-/**
- * Cached version of `registerClient`. Looks up `(authServerIssuer, redirectUri)`
- * in the cache file and re-uses the existing client; falls back to a fresh
- * DCR call when nothing is cached.
- * @param lookupImpl Injectable `dns.lookup` for the connection-time SSRF
- *   guard (tests only — see `safeOAuthFetch`).
- */
-export declare function getOrRegisterClient(dataDir: string, authServer: AuthorizationServerMetadata, redirectUri: string, fetchImpl?: typeof fetch, lookupImpl?: DnsLookupCb): Promise<RegisteredClient>;
-/** Inputs required to assemble the authorization redirect URL. */
-export interface AuthorizeUrlInput {
-    authServer: AuthorizationServerMetadata;
-    clientId: string;
-    redirectUri: string;
-    state: string;
-    codeChallenge: string;
-    scope?: string;
-    /** RFC 8707 resource indicator — narrows the issued token to the target MCP server. */
-    resource?: string;
-}
-/**
- * Assemble the authorization endpoint URL the user's browser must be directed to.
- * Sets PKCE parameters (`code_challenge`, `code_challenge_method=S256`), the `state`
- * CSRF token, and optionally the RFC 8707 `resource` indicator.
- * @param input All parameters needed to build the URL.
- * @returns The fully-qualified authorization URL as a string.
- */
-export declare function buildAuthorizeUrl(input: AuthorizeUrlInput): string;
-/** Inputs for the authorization-code → token exchange (RFC 6749 §4.1.3). */
-export interface ExchangeCodeInput {
-    tokenEndpoint: string;
-    clientId: string;
-    clientSecret?: string;
-    redirectUri: string;
-    code: string;
-    codeVerifier: string;
-    /** RFC 8707 resource indicator to include in the token request. */
-    resource?: string;
-}
-/**
- * Exchange an authorization code for access and refresh tokens (RFC 6749 §4.1.3).
- * Includes the PKCE `code_verifier` and, when supplied, the RFC 8707 `resource`
- * indicator. Throws when the token endpoint returns a non-2xx status.
- * @param input The code-exchange parameters.
- * @param fetchImpl Injectable fetch, defaults to the global `fetch`.
- * @param lookupImpl Injectable `dns.lookup` for the connection-time SSRF
- *   guard (tests only — see `safeOAuthFetch`).
- * @returns The token endpoint response containing at least an `access_token`.
- */
-export declare function exchangeCodeForToken(input: ExchangeCodeInput, fetchImpl?: typeof fetch, lookupImpl?: DnsLookupCb): Promise<OAuthTokenResponse>;
-/** Inputs for the refresh-token → new-access-token exchange (RFC 6749 §6). */
-export interface RefreshTokenInput {
-    tokenEndpoint: string;
-    clientId: string;
-    clientSecret?: string;
-    refreshToken: string;
-    scope?: string;
-    /** RFC 8707 resource indicator, included when the original token was resource-scoped. */
-    resource?: string;
-}
-/**
- * Exchange a refresh token for a new access token (RFC 6749 §6).
- * Preserves scope and resource binding from the original authorization.
- * Throws when the token endpoint returns a non-2xx status.
- * @param input The refresh parameters.
- * @param fetchImpl Injectable fetch, defaults to the global `fetch`.
- * @param lookupImpl Injectable `dns.lookup` for the connection-time SSRF
- *   guard (tests only — see `safeOAuthFetch`).
- * @returns A fresh `OAuthTokenResponse`; the server may issue a new refresh token.
- */
-export declare function refreshAccessToken(input: RefreshTokenInput, fetchImpl?: typeof fetch, lookupImpl?: DnsLookupCb): Promise<OAuthTokenResponse>;
-/**
- * The OAuth dance is split across two HTTP requests on our side:
- *   1. the "start" request                 — we mint state + verifier
- *   2. the "callback" request              — browser returns code + state
- * State has to survive between (1) and (2) on the daemon. We keep it in a
- * Map with a TTL sweeper; persistence isn't needed because the user has
- * to complete auth in the same daemon process anyway (state is single-use).
- */
-export declare class PendingAuthCache {
-    private readonly ttlMs;
-    private store;
-    private timer;
-    constructor(ttlMs?: number);
-    /**
-     * Store a pending auth state keyed by the OAuth `state` parameter.
-     * Starts the TTL sweeper if it is not already running.
-     * @param state The random `state` string from the authorization request.
-     * @param value The associated pending auth metadata to stash.
-     */
-    put(state: string, value: PendingAuthState): void;
-    /** One-shot consume — any successful callback removes the state so a
-     * replay can't reuse it. */
-    consume(state: string): PendingAuthState | null;
-    /** Return the number of pending auth states currently held in the cache. */
-    size(): number;
-    /** Stop the background sweeper. Used by tests; production lets the
-     * timer ride on the process lifetime. */
-    stop(): void;
-    private startSweeper;
-    private sweep;
-}
-/** Inputs for the full pre-redirect OAuth dance. */
-export interface BeginAuthInput {
-    /** The `McpServerConfig.id` of the server being authorized. */
-    serverId: string;
-    /** The MCP server endpoint URL (used for protected-resource discovery). */
-    serverUrl: string;
-    /** The OAuth redirect URI the daemon has registered. */
-    redirectUri: string;
-    /** The resolved data directory (for caching the client registration). */
-    dataDir: string;
-    scope?: string;
-    /** Injectable fetch implementation; defaults to the global `fetch`. */
-    fetchImpl?: typeof fetch;
-    /** Injectable `dns.lookup` for the connection-time SSRF guard (tests only). */
-    lookupImpl?: DnsLookupCb;
-}
-/** Result of `beginAuth`: everything needed to redirect the browser and later complete the flow. */
-export interface BeginAuthResult {
-    /** The fully-qualified authorization URL to redirect the user's browser to. */
-    authorizeUrl: string;
-    /** The random `state` string; must be passed to `PendingAuthCache.put` before redirecting. */
-    state: string;
-    /** The pending-auth metadata to store in `PendingAuthCache` keyed by `state`. */
-    pending: PendingAuthState;
-}
-/**
- * Run the entire pre-redirect half of the OAuth dance:
- *   discovery → DCR (cached) → PKCE → authorize URL.
- *
- * Returns everything the caller needs to (a) push the user's browser at the
- * correct authorize URL, and (b) finish the flow when the callback hits.
- */
-export declare function beginAuth(input: BeginAuthInput): Promise<BeginAuthResult>;
-export {};
-//# sourceMappingURL=oauth.d.ts.map