@jini-ai/mcp 0.4.0 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # @jini-ai/mcp
 
+## 0.4.1 — 2026-10-06
+
+- The delegated tool gateways send input `{}` when the model omits it or sends `null`, so a no-input call no longer fails before a retry.
+- Internal `@jini-ai/*` runtime dependencies are caret ranges (`workspace:^`) instead of exact pins.
+
 ## 0.4.0 — 2026-10-02
 
 ### BREAKING

package/dist/server/tools/delegated-tool.js

@@ -149,7 +149,10 @@ function createDelegatedGateway(variant, { runId }, options) {
                 runId,
                 toolUseId: generateToolUseId({}),
                 toolId: toolId,
-                input: args.input,
+                // The schema tells the model to omit `input` for a tool that takes none, but most tool
+                // handlers refuse an absent input ("input must be an object"). Sending `{}` makes the
+                // schema's promise true instead of costing a red failed call and a retry.
+                input: args.input ?? {},
                 ...(variant.requireReadOnly === undefined ? {} : { requireReadOnly: variant.requireReadOnly }),
             };
             const data = await postDaemonJson({ baseUrl: ctx.baseUrl, route: '/api/delegated-tool-calls', body: body }, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jini-ai/mcp",
-  "version": "0.4.0",
+  "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": {
@@ -85,8 +85,8 @@
   "dependencies": {
     "@cfworker/json-schema": "^4.1.1",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@jini-ai/core": "0.4.0",
-    "@jini-ai/platform": "0.5.0"
+    "@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

package/dist/core/oauth.js

@@ -1,667 +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.
- */
-// Daemon-side OAuth 2.1 client for HTTP / SSE MCP servers.
-//
-// Replaces the per-agent `mcp-remote` subprocess that bound a transient
-// `localhost:<port>` listener — that pattern can never work for a cloud-
-// deployed daemon (the user's browser can't reach the listener) and it
-// also broke locally because the listener died with the agent turn.
-//
-// What this module owns:
-//   - Discovery of the auth server for a given MCP URL
-//     (RFC 9728 protected-resource → RFC 8414 authorization-server).
-//   - Dynamic Client Registration (RFC 7591) when the server supports it,
-//     cached per `(authServerUrl, redirectUri)` in `<dataDir>/mcp-oauth-clients.json`
-//     so we register once and reuse forever.
-//   - PKCE (RFC 7636) code-verifier / code-challenge generation.
-//   - Authorization-code → token exchange and refresh-token rotation.
-//   - In-memory state cache keyed by the `state` parameter, used to look
-//     up the originating server + verifier when the browser hits our
-//     callback endpoint.
-//
-// Token persistence lives in `tokens.ts`. This file is the protocol
-// layer; storage is somebody else's job.
-import { readFile } from 'node:fs/promises';
-import { createHash, randomBytes } from 'node:crypto';
-import path from 'node:path';
-import { Agent } from 'undici';
-import { assertSafePublicUrl, createValidatingLookup } from '@jini-ai/platform';
-import { writeSecretFileAtomic } from './secure-write.js';
-// ───────────────────────────────────────────────────────────────────────
-// Outbound-fetch safety (SEC-RB-001 / CR-005).
-// ───────────────────────────────────────────────────────────────────────
-//
-// Every network hop below — protected-resource discovery, authorization-
-// server discovery, dynamic client registration, and the token endpoint —
-// fetches a URL that is ultimately caller- or metadata-controlled (a
-// user-supplied MCP server URL, or an endpoint a remote server's own
-// discovery document names). A hostile or compromised server can point any
-// of these at an internal service, a cloud-metadata endpoint, or an
-// attacker-controlled host that redirects or replies with an oversized /
-// slow response. `safeOAuthFetch` is the single choke point all of that
-// traffic goes through:
-//   - HTTPS-only (no plaintext downgrade).
-//   - `@jini-ai/platform`'s `assertSafePublicUrl` rejects embedded credentials,
-//     localhost, and literal private/link-local IPs before any socket opens.
-//   - A `createValidatingLookup`-wrapped dispatcher re-validates the
-//     *actual* resolved address at connection time, closing the
-//     DNS-rebinding / TOCTOU gap a one-time pre-check would leave open —
-//     mirrors `packages/deploy/src/reachability.ts` and
-//     `packages/platform/src/asset-cache.ts`, the two existing SSRF-safe
-//     fetch call sites in this repo.
-//   - Redirects are refused (`redirect: 'error'` plus an explicit
-//     status/type check, so a test double that bypasses real fetch
-//     semantics is still caught) rather than followed.
-//   - Every response is read through a byte-capped reader and every
-//     request carries an `AbortSignal`-based timeout.
-const OAUTH_FETCH_TIMEOUT_MS = 10_000;
-const OAUTH_FETCH_MAX_BYTES = 1_000_000; // 1 MB — generous for OAuth metadata/token JSON
-function assertSafeOAuthUrl(raw) {
-    const url = assertSafePublicUrl(raw);
-    if (url.protocol !== 'https:') {
-        // OAuth authorization servers always serve discovery/DCR/token endpoints
-        // over TLS; a plaintext candidate is never legitimate and downgrading a
-        // request that may carry client secrets or tokens to http is its own risk.
-        throw new Error(`OAuth endpoint must use https: ${raw}`);
-    }
-    return url;
-}
-// A fresh Agent per call would needlessly discard connection pooling; the
-// common (no test override) case shares one lazily-created dispatcher. A
-// caller-supplied `lookupImpl` (tests only) always gets its own dispatcher
-// instead of touching the shared one — mirrors reachability.ts's own
-// `resolveDispatcher`.
-let defaultOAuthDispatcher = null;
-function resolveOAuthDispatcher(lookupImpl) {
-    if (lookupImpl) {
-        return new Agent({ connect: { lookup: createValidatingLookup(lookupImpl) } });
-    }
-    defaultOAuthDispatcher ??= new Agent({ connect: { lookup: createValidatingLookup() } });
-    return defaultOAuthDispatcher;
-}
-function isRedirectResponse(res) {
-    return (res.status >= 300 && res.status < 400) || res.type === 'opaqueredirect';
-}
-/**
- * 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 async function readCappedText(res, maxBytes, controller) {
-    const body = res.body;
-    if (!body || typeof body.getReader !== 'function') {
-        try {
-            return await res.text();
-        }
-        catch {
-            return '';
-        }
-    }
-    const reader = body.getReader();
-    const chunks = [];
-    let total = 0;
-    try {
-        for (;;) {
-            const { done, value } = await reader.read();
-            if (done)
-                break;
-            if (!value)
-                continue;
-            total += value.byteLength;
-            if (total > maxBytes) {
-                controller?.abort(); // stop pulling more bytes from upstream
-                throw new Error(`response body exceeds ${maxBytes} byte limit`);
-            }
-            chunks.push(value);
-        }
-    }
-    finally {
-        try {
-            await reader.cancel();
-        }
-        catch {
-            // reader already closed/errored — nothing to release
-        }
-    }
-    return Buffer.concat(chunks).toString('utf8');
-}
-/** Best-effort, size-capped extraction of an error response's body text for
- *  inclusion in a thrown error message. Never throws. */
-async function safeErrorText(res) {
-    try {
-        const text = await readCappedText(res, OAUTH_FETCH_MAX_BYTES);
-        return text.slice(0, 500);
-    }
-    catch {
-        return '';
-    }
-}
-/**
- * The single outbound-fetch choke point for this file. Validates the URL,
- * attaches the connection-time SSRF guard, refuses redirects, and enforces a
- * request timeout. Callers still own reading/bounding the response body via
- * `readCappedText`.
- */
-async function safeOAuthFetch(rawUrl, init, fetchImpl, lookupImpl) {
-    const url = assertSafeOAuthUrl(rawUrl);
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), OAUTH_FETCH_TIMEOUT_MS);
-    try {
-        const reqInit = {
-            method: init.method ?? 'GET',
-            headers: init.headers,
-            ...(init.body !== undefined ? { body: init.body } : {}),
-            redirect: 'error',
-            signal: controller.signal,
-        };
-        // `dispatcher` is an undici extension of RequestInit; attach it at
-        // runtime (see asset-cache.ts / reachability.ts for the same pattern) to
-        // avoid the undici-types (bundled with @types/node) vs undici@7
-        // Dispatcher version skew a typed field would trip over.
-        reqInit.dispatcher = resolveOAuthDispatcher(lookupImpl);
-        let res;
-        try {
-            res = await fetchImpl(url.toString(), reqInit);
-        }
-        catch (err) {
-            throw new Error(`request to ${url.origin} failed: ${err instanceof Error ? err.message : String(err)}`);
-        }
-        if (isRedirectResponse(res)) {
-            // Never follow a redirect: the destination has not been validated,
-            // and a hostile or rebound server could point it at an internal
-            // address. `redirect: 'error'` already makes a *real* fetch reject
-            // before returning a Response; this explicit check is defense in
-            // depth for response-like test doubles that don't implement real
-            // HTTP redirect semantics.
-            throw new Error(`refusing to follow a redirect response from ${url.origin}`);
-        }
-        return res;
-    }
-    finally {
-        clearTimeout(timer);
-    }
-}
-// ───────────────────────────────────────────────────────────────────────
-// PKCE + state helpers.
-// ───────────────────────────────────────────────────────────────────────
-const VERIFIER_LEN = 64; // RFC 7636 §4.1: 43–128 chars
-function base64url(buf) {
-    return buf
-        .toString('base64')
-        .replace(/\+/g, '-')
-        .replace(/\//g, '_')
-        .replace(/=+$/g, '');
-}
-/**
- * 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 function generateCodeVerifier() {
-    return base64url(randomBytes(VERIFIER_LEN));
-}
-/**
- * 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 function deriveCodeChallenge(verifier) {
-    return base64url(createHash('sha256').update(verifier).digest());
-}
-/**
- * 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 function generateState() {
-    return base64url(randomBytes(32));
-}
-// ───────────────────────────────────────────────────────────────────────
-// Discovery.
-// ───────────────────────────────────────────────────────────────────────
-/**
- * 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 async function discoverProtectedResource(resourceUrl, fetchImpl = fetch, lookupImpl) {
-    let parsed;
-    try {
-        parsed = new URL(resourceUrl);
-    }
-    catch {
-        return null;
-    }
-    const candidates = [
-        new URL(`/.well-known/oauth-protected-resource${parsed.pathname.replace(/\/+$/u, '')}`, `${parsed.protocol}//${parsed.host}`).toString(),
-        new URL('/.well-known/oauth-protected-resource', `${parsed.protocol}//${parsed.host}`).toString(),
-    ];
-    for (const url of candidates) {
-        const json = await fetchJson(url, fetchImpl, lookupImpl);
-        if (json)
-            return json;
-    }
-    return 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 async function discoverAuthServer(issuer, fetchImpl = fetch, lookupImpl) {
-    let parsedIssuer;
-    try {
-        parsedIssuer = new URL(issuer);
-    }
-    catch {
-        return null;
-    }
-    const trimmed = parsedIssuer.pathname.replace(/\/+$/u, '');
-    const base = `${parsedIssuer.protocol}//${parsedIssuer.host}`;
-    const candidates = [
-        `${base}/.well-known/oauth-authorization-server${trimmed}`,
-        `${base}/.well-known/openid-configuration${trimmed}`,
-        `${base}/.well-known/oauth-authorization-server`,
-        `${base}/.well-known/openid-configuration`,
-    ];
-    for (const url of candidates) {
-        const json = await fetchJson(url, fetchImpl, lookupImpl);
-        if (json && typeof json.authorization_endpoint === 'string' && typeof json.token_endpoint === 'string') {
-            if (typeof json.issuer === 'string' && json.issuer !== issuer)
-                continue; // RFC 8414 §3.3 issuer mismatch
-            if (!endpointsShareIssuerOrigin(parsedIssuer, json))
-                continue;
-            // Spread first so the explicit issuer wins (otherwise duplicate-key
-            // assignments under exactOptionalPropertyTypes complain).
-            return { ...json, issuer: json.issuer ?? issuer };
-        }
-    }
-    return null;
-}
-function endpointsShareIssuerOrigin(issuerUrl, meta) {
-    const endpoints = [meta.authorization_endpoint, meta.token_endpoint, meta.registration_endpoint].filter((v) => typeof v === 'string');
-    for (const endpoint of endpoints) {
-        let parsed;
-        try {
-            parsed = new URL(endpoint);
-        }
-        catch {
-            return false;
-        }
-        if (parsed.protocol !== 'https:' || parsed.origin !== issuerUrl.origin)
-            return false;
-    }
-    return true;
-}
-async function fetchJson(url, fetchImpl, lookupImpl) {
-    try {
-        const res = await safeOAuthFetch(url, { headers: { accept: 'application/json' } }, fetchImpl, lookupImpl);
-        if (!res.ok)
-            return null;
-        const text = await readCappedText(res, OAUTH_FETCH_MAX_BYTES);
-        return JSON.parse(text);
-    }
-    catch {
-        return null;
-    }
-}
-function clientsFile(dataDir) {
-    return path.join(dataDir, 'mcp-oauth-clients.json');
-}
-async function readClientCache(dataDir) {
-    try {
-        const raw = await readFile(clientsFile(dataDir), 'utf8');
-        const parsed = JSON.parse(raw);
-        if (!parsed || !Array.isArray(parsed.clients))
-            return { clients: [] };
-        return { clients: parsed.clients.filter(isRegisteredClient) };
-    }
-    catch (err) {
-        const e = err;
-        if (e.code === 'ENOENT')
-            return { clients: [] };
-        throw err;
-    }
-}
-function isRegisteredClient(v) {
-    if (!v || typeof v !== 'object')
-        return false;
-    const r = v;
-    return (typeof r.authServerIssuer === 'string' &&
-        typeof r.redirectUri === 'string' &&
-        typeof r.clientId === 'string');
-}
-/**
- * Persist the client cache to `<dataDir>/mcp-oauth-clients.json`. May
- * contain a confidential client's `clientSecret` (CR-006 / SEC-RB-002), so
- * the file is created with owner-only (0600) permissions from the very
- * first byte via `writeSecretFileAtomic` rather than a post-rename chmod —
- * see that module for why.
- */
-async function writeClientCache(dataDir, next) {
-    await writeSecretFileAtomic(clientsFile(dataDir), JSON.stringify(next, null, 2));
-}
-/**
- * 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 async function registerClient(registrationEndpoint, redirectUri, fetchImpl = fetch, lookupImpl) {
-    const body = {
-        redirect_uris: [redirectUri],
-        token_endpoint_auth_method: 'none',
-        grant_types: ['authorization_code', 'refresh_token'],
-        response_types: ['code'],
-        client_name: 'Jini',
-        application_type: 'web',
-    };
-    const res = await safeOAuthFetch(registrationEndpoint, {
-        method: 'POST',
-        headers: {
-            'content-type': 'application/json',
-            accept: 'application/json',
-        },
-        body: JSON.stringify(body),
-    }, fetchImpl, lookupImpl);
-    if (!res.ok) {
-        const txt = await safeErrorText(res);
-        throw new Error(`dynamic client registration failed: HTTP ${res.status} ${res.statusText} ${txt}`);
-    }
-    const json = JSON.parse(await readCappedText(res, OAUTH_FETCH_MAX_BYTES));
-    if (!json.client_id) {
-        throw new Error('dynamic client registration response missing client_id');
-    }
-    const out = { clientId: json.client_id };
-    if (json.client_secret)
-        out.clientSecret = json.client_secret;
-    return out;
-}
-/**
- * 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 async function getOrRegisterClient(dataDir, authServer, redirectUri, fetchImpl = fetch, lookupImpl) {
-    const cache = await readClientCache(dataDir);
-    const cached = cache.clients.find((c) => c.authServerIssuer === authServer.issuer && c.redirectUri === redirectUri);
-    if (cached)
-        return cached;
-    if (!authServer.registration_endpoint) {
-        throw new Error(`auth server ${authServer.issuer} does not advertise a registration_endpoint and no client is pre-registered`);
-    }
-    const reg = await registerClient(authServer.registration_endpoint, redirectUri, fetchImpl, lookupImpl);
-    const next = {
-        authServerIssuer: authServer.issuer,
-        redirectUri,
-        clientId: reg.clientId,
-        registeredAt: Date.now(),
-    };
-    if (reg.clientSecret)
-        next.clientSecret = reg.clientSecret;
-    cache.clients.push(next);
-    await writeClientCache(dataDir, cache);
-    return next;
-}
-/**
- * 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 function buildAuthorizeUrl(input) {
-    const u = new URL(input.authServer.authorization_endpoint);
-    u.searchParams.set('response_type', 'code');
-    u.searchParams.set('client_id', input.clientId);
-    u.searchParams.set('redirect_uri', input.redirectUri);
-    u.searchParams.set('state', input.state);
-    u.searchParams.set('code_challenge', input.codeChallenge);
-    u.searchParams.set('code_challenge_method', 'S256');
-    if (input.scope)
-        u.searchParams.set('scope', input.scope);
-    // RFC 8707 resource indicator — narrows the issued token to the MCP
-    // resource we actually care about. Most authoritative MCP servers
-    // require it; harmless when ignored.
-    if (input.resource)
-        u.searchParams.set('resource', input.resource);
-    return u.toString();
-}
-/**
- * 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 async function exchangeCodeForToken(input, fetchImpl = fetch, lookupImpl) {
-    const form = new URLSearchParams();
-    form.set('grant_type', 'authorization_code');
-    form.set('code', input.code);
-    form.set('redirect_uri', input.redirectUri);
-    form.set('client_id', input.clientId);
-    form.set('code_verifier', input.codeVerifier);
-    if (input.resource)
-        form.set('resource', input.resource);
-    return tokenRequest(input.tokenEndpoint, form, input.clientSecret, fetchImpl, lookupImpl);
-}
-/**
- * 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 async function refreshAccessToken(input, fetchImpl = fetch, lookupImpl) {
-    const form = new URLSearchParams();
-    form.set('grant_type', 'refresh_token');
-    form.set('refresh_token', input.refreshToken);
-    form.set('client_id', input.clientId);
-    if (input.scope)
-        form.set('scope', input.scope);
-    if (input.resource)
-        form.set('resource', input.resource);
-    return tokenRequest(input.tokenEndpoint, form, input.clientSecret, fetchImpl, lookupImpl);
-}
-async function tokenRequest(tokenEndpoint, form, clientSecret, fetchImpl, lookupImpl) {
-    const headers = {
-        'content-type': 'application/x-www-form-urlencoded',
-        accept: 'application/json',
-    };
-    if (clientSecret) {
-        // RFC 6749 §2.3.1 — confidential clients use HTTP Basic with the
-        // client_id we already put in the form. Public clients (PKCE-only)
-        // skip this branch.
-        const basic = Buffer.from(`${form.get('client_id')}:${clientSecret}`).toString('base64');
-        headers['authorization'] = `Basic ${basic}`;
-    }
-    const res = await safeOAuthFetch(tokenEndpoint, { method: 'POST', headers, body: form.toString() }, fetchImpl, lookupImpl);
-    if (!res.ok) {
-        const txt = await safeErrorText(res);
-        throw new Error(`token endpoint rejected request: HTTP ${res.status} ${res.statusText} ${txt}`);
-    }
-    const json = JSON.parse(await readCappedText(res, OAUTH_FETCH_MAX_BYTES));
-    if (!json.access_token) {
-        throw new Error('token endpoint response missing access_token');
-    }
-    return json;
-}
-// ───────────────────────────────────────────────────────────────────────
-// In-memory pending-state cache.
-// ───────────────────────────────────────────────────────────────────────
-/**
- * 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 class PendingAuthCache {
-    ttlMs;
-    store = new Map();
-    timer = null;
-    constructor(ttlMs = 10 * 60 * 1000) {
-        this.ttlMs = ttlMs;
-    }
-    /**
-     * 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, value) {
-        this.store.set(state, value);
-        this.startSweeper();
-    }
-    /** One-shot consume — any successful callback removes the state so a
-     * replay can't reuse it. */
-    consume(state) {
-        const v = this.store.get(state);
-        if (!v)
-            return null;
-        this.store.delete(state);
-        if (Date.now() - v.createdAt > this.ttlMs)
-            return null;
-        return v;
-    }
-    /** Return the number of pending auth states currently held in the cache. */
-    size() {
-        return this.store.size;
-    }
-    /** Stop the background sweeper. Used by tests; production lets the
-     * timer ride on the process lifetime. */
-    stop() {
-        if (this.timer) {
-            clearInterval(this.timer);
-            this.timer = null;
-        }
-    }
-    startSweeper() {
-        if (this.timer)
-            return;
-        this.timer = setInterval(() => this.sweep(), Math.min(this.ttlMs, 60_000));
-        // unref so the cache doesn't keep the event loop alive in tests
-        this.timer.unref();
-    }
-    sweep() {
-        const now = Date.now();
-        for (const [k, v] of this.store) {
-            if (now - v.createdAt > this.ttlMs)
-                this.store.delete(k);
-        }
-        if (this.store.size === 0 && this.timer) {
-            clearInterval(this.timer);
-            this.timer = null;
-        }
-    }
-}
-/**
- * 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 async function beginAuth(input) {
-    const fetchImpl = input.fetchImpl ?? fetch;
-    const lookupImpl = input.lookupImpl;
-    // Step 1: ask the MCP server who its auth server is. If the server
-    // doesn't publish protected-resource metadata, fall back to assuming
-    // the resource origin IS the auth server — most "stand-alone" MCP
-    // providers host both at the same host.
-    const prm = await discoverProtectedResource(input.serverUrl, fetchImpl, lookupImpl);
-    const issuerHint = prm?.authorization_servers?.[0];
-    const issuer = issuerHint ?? new URL(input.serverUrl).origin;
-    // Step 2: discovery on the auth server.
-    const authServer = await discoverAuthServer(issuer, fetchImpl, lookupImpl);
-    if (!authServer) {
-        throw new Error(`could not discover OAuth metadata for ${issuer}`);
-    }
-    // Step 3: ensure we have a registered client_id (DCR if missing).
-    const client = await getOrRegisterClient(input.dataDir, authServer, input.redirectUri, fetchImpl, lookupImpl);
-    // Step 4: PKCE + state.
-    const codeVerifier = generateCodeVerifier();
-    const codeChallenge = deriveCodeChallenge(codeVerifier);
-    const state = generateState();
-    const scope = input.scope ??
-        (Array.isArray(prm?.scopes_supported) && prm.scopes_supported.length > 0
-            ? prm.scopes_supported.join(' ')
-            : authServer.scopes_supported?.join(' '));
-    const resource = prm?.resource ?? input.serverUrl;
-    const authUrlInput = {
-        authServer,
-        clientId: client.clientId,
-        redirectUri: input.redirectUri,
-        state,
-        codeChallenge,
-        resource,
-    };
-    if (scope)
-        authUrlInput.scope = scope;
-    const authorizeUrl = buildAuthorizeUrl(authUrlInput);
-    const pending = {
-        serverId: input.serverId,
-        authServerIssuer: authServer.issuer,
-        tokenEndpoint: authServer.token_endpoint,
-        clientId: client.clientId,
-        redirectUri: input.redirectUri,
-        codeVerifier,
-        resourceUrl: resource,
-        createdAt: Date.now(),
-    };
-    if (client.clientSecret)
-        pending.clientSecret = client.clientSecret;
-    if (scope)
-        pending.scope = scope;
-    return { authorizeUrl, state, pending };
-}
-//# sourceMappingURL=oauth.js.map

package/dist/core/secure-write.d.ts

@@ -1,17 +0,0 @@
-export interface WriteSecretFileOptions {
-    /** Injectable for tests only; defaults to `process.platform`. */
-    platform?: NodeJS.Platform;
-}
-/**
- * Atomically write `contents` to `finalPath` via a same-directory temp file
- * created exclusively with mode 0600. On POSIX platforms, verifies no
- * group/other permission bit made it onto disk before renaming into place;
- * throws (after removing the temp file) if verification fails or the write
- * itself fails, so a caller never observes a partially-written or
- * insufficiently-restricted secret file.
- * @param finalPath Absolute path the secret file should end up at.
- * @param contents UTF-8 text to write.
- * @param options `platform` override for tests; defaults to `process.platform`.
- */
-export declare function writeSecretFileAtomic(finalPath: string, contents: string, options?: WriteSecretFileOptions): Promise<void>;
-//# sourceMappingURL=secure-write.d.ts.map

package/dist/core/secure-write.js

@@ -1,72 +0,0 @@
-/**
- * @module @jini-ai/mcp/core/secure-write
- * Shared atomic, owner-only-permission (0600) secret-file writer used by
- * every secret-bearing on-disk store in this package: the server config
- * store (env vars / `Authorization` headers), the OAuth dynamic-client-
- * registration cache (`clientSecret`), and the OAuth token store (bearer /
- * refresh tokens, confidential-client secrets). CR-006 / SEC-RB-002.
- *
- * The previous pattern in each of those stores wrote the temp file with
- * default permissions and either never restricted it (config, OAuth client
- * cache) or `chmod(0600)`'d it *after* the atomic rename and silently
- * continued when the chmod failed (tokens) — both leave a window where the
- * file exists world/group-readable, and the latter makes the "protection"
- * advisory rather than enforced. This writer instead:
- *
- *   1. Creates the temp file *exclusively* (`wx`) with mode 0600 supplied to
- *      the same `open()`/`writeFile()` call that creates it — POSIX applies
- *      the requested mode atomically at creation time, so there is no
- *      window where the file exists with a broader mode. This repo already
- *      relies on `writeFile`'s `mode` option alone for a secret file with no
- *      separate chmod step (see `packages/agent-runtime/src/prompt-file.ts`);
- *      this module follows that same precedent rather than inventing a new one.
- *   2. On POSIX platforms, verifies the on-disk mode actually landed as
- *      owner-only before renaming into place, and fails closed — removing
- *      the temp file and throwing — if it did not (e.g. an unusual umask or
- *      a filesystem that doesn't honor `mode`).
- *   3. Skips that verification on `win32`: Windows has no POSIX permission-
- *      bit model (`mode` there only toggles the read-only attribute), so
- *      there is nothing meaningful to enforce or fail closed on — matching
- *      this repo's only other cross-platform file-mode precedent, which
- *      also does not branch on Windows.
- *
- * Part of the MCP `core` kernel; not part of the package's public barrel —
- * imported directly by sibling `core/*.ts` files.
- */
-import { mkdir, rename, rm, stat, writeFile } from 'node:fs/promises';
-import { randomBytes } from 'node:crypto';
-import path from 'node:path';
-const SECRET_FILE_MODE = 0o600;
-/**
- * Atomically write `contents` to `finalPath` via a same-directory temp file
- * created exclusively with mode 0600. On POSIX platforms, verifies no
- * group/other permission bit made it onto disk before renaming into place;
- * throws (after removing the temp file) if verification fails or the write
- * itself fails, so a caller never observes a partially-written or
- * insufficiently-restricted secret file.
- * @param finalPath Absolute path the secret file should end up at.
- * @param contents UTF-8 text to write.
- * @param options `platform` override for tests; defaults to `process.platform`.
- */
-export async function writeSecretFileAtomic(finalPath, contents, options = {}) {
-    const platform = options.platform ?? process.platform;
-    await mkdir(path.dirname(finalPath), { recursive: true });
-    const tmp = `${finalPath}.${randomBytes(4).toString('hex')}.tmp`;
-    try {
-        await writeFile(tmp, contents, { encoding: 'utf8', mode: SECRET_FILE_MODE, flag: 'wx' });
-        if (platform !== 'win32') {
-            const info = await stat(tmp);
-            const bits = info.mode & 0o777;
-            if ((bits & 0o077) !== 0) {
-                throw new Error(`refusing to persist secret-bearing file with non-owner-only permissions ` +
-                    `(mode 0${bits.toString(8)}): ${finalPath}`);
-            }
-        }
-        await rename(tmp, finalPath);
-    }
-    catch (err) {
-        await rm(tmp, { force: true }).catch(() => undefined);
-        throw err;
-    }
-}
-//# sourceMappingURL=secure-write.js.map