@caplets/core 0.16.0 → 0.17.0

package/dist/native/options.d.ts

@@ -1,16 +1,15 @@
-export type NativeCapletsMode = "auto" | "local" | "remote";
+import { type CapletsMode, type CapletsServerEnv, type CapletsServerInput } from "../server/options";
+export type NativeCapletsMode = CapletsMode;
 export type NativeRemoteCapletsOptions = {
-    url?: string;
-    user?: string;
-    password?: string;
     pollIntervalMs?: number;
     fetch?: typeof fetch;
 };
 export type NativeCapletsServiceResolutionInput = {
     mode?: NativeCapletsMode;
+    server?: CapletsServerInput;
     remote?: NativeRemoteCapletsOptions;
 };
-export type NativeCapletsEnv = Partial<Record<"CAPLETS_NATIVE_MODE" | "CAPLETS_REMOTE_URL" | "CAPLETS_REMOTE_USER" | "CAPLETS_REMOTE_PASSWORD", string>>;
+export type NativeCapletsEnv = CapletsServerEnv;
 export type NativeRemoteAuthOptions = {
     enabled: false;
     user: string;

package/dist/native.js

@@ -1,76 +1,33 @@
-import { K as ToolListChangedNotificationSchema, Tt as CapletsError, a as capabilityDescription, d as StreamableHTTPClientTransport, m as Client, n as generatedToolInputSchema, t as CapletsEngine } from "./engine-Brwid_mq.js";
+import { $ as ToolListChangedNotificationSchema, Nt as CapletsError, a as resolveCapletsServer, i as resolveCapletsMode, n as mcpUrlForBase, o as CapletsEngine, s as generatedToolInputSchema, u as capabilityDescription, v as StreamableHTTPClientTransport, x as Client } from "./options-CJEOqS87.js";
 import { generatedToolInputJsonSchema } from "./generated-tool-input-schema.js";
-import { Buffer } from "node:buffer";
 //#region src/native/options.ts
-const DEFAULT_REMOTE_USER = "caplets";
 const DEFAULT_POLL_INTERVAL_MS = 3e4;
 function resolveNativeCapletsServiceOptions(input = {}, env = process.env) {
-	const mode = parseMode(input.mode ?? env.CAPLETS_NATIVE_MODE ?? "auto");
-	if (mode === "local") return { mode: "local" };
-	const rawUrl = nonEmpty(input.remote?.url, "remote.url") ?? nonEmpty(env.CAPLETS_REMOTE_URL, "CAPLETS_REMOTE_URL");
-	if (mode === "remote" && rawUrl === void 0) throw new CapletsError("REQUEST_INVALID", "CAPLETS_NATIVE_MODE=remote requires CAPLETS_REMOTE_URL or remote.url.");
-	if (rawUrl === void 0) return { mode: "local" };
-	const url = parseRemoteUrl(rawUrl);
-	const userWasExplicit = input.remote?.user !== void 0 || hasEnv(env.CAPLETS_REMOTE_USER);
-	const user = nonEmpty(input.remote?.user, "remote.user") ?? nonEmpty(env.CAPLETS_REMOTE_USER, "CAPLETS_REMOTE_USER") ?? DEFAULT_REMOTE_USER;
-	const password = nonEmpty(input.remote?.password, "remote.password") ?? nonEmpty(env.CAPLETS_REMOTE_PASSWORD, "CAPLETS_REMOTE_PASSWORD");
-	if (userWasExplicit && password === void 0) throw new CapletsError("REQUEST_INVALID", "Remote Caplets Basic Auth requires a password; set CAPLETS_REMOTE_PASSWORD or remote.password.");
-	const auth = password === void 0 ? {
-		enabled: false,
-		user
-	} : {
-		enabled: true,
-		user,
-		password
-	};
-	const requestInit = auth.enabled ? { headers: { Authorization: basicAuthHeader(auth.user, auth.password) } } : {};
+	if (resolveCapletsMode({
+		...input.mode ? { mode: input.mode } : {},
+		...input.server?.url ? { serverUrl: input.server.url } : {}
+	}, env).mode === "local") return { mode: "local" };
+	const serverFetch = input.remote?.fetch ?? input.server?.fetch;
+	const server = resolveCapletsServer({
+		...input.server,
+		...serverFetch ? { fetch: serverFetch } : {}
+	}, env);
 	return {
 		mode: "remote",
 		remote: {
-			url,
-			auth,
+			url: mcpUrlForBase(server.baseUrl),
+			auth: server.auth,
 			pollIntervalMs: parsePollInterval(input.remote?.pollIntervalMs),
-			requestInit,
-			...input.remote?.fetch ? { fetch: input.remote.fetch } : {}
+			requestInit: server.requestInit,
+			...server.fetch ? { fetch: server.fetch } : {}
 		}
 	};
 }
-function parseMode(value) {
-	if (value === "auto" || value === "local" || value === "remote") return value;
-	throw new CapletsError("REQUEST_INVALID", `Expected CAPLETS_NATIVE_MODE to be auto, local, or remote, got ${value}`);
-}
-function parseRemoteUrl(value) {
-	let url;
-	try {
-		url = new URL(value);
-	} catch {
-		throw new CapletsError("REQUEST_INVALID", "Invalid remote Caplets URL.");
-	}
-	if (url.username !== "" || url.password !== "") throw new CapletsError("REQUEST_INVALID", "Remote Caplets URL must not include username or password; use CAPLETS_REMOTE_USER/CAPLETS_REMOTE_PASSWORD or remote.user/remote.password instead.");
-	if (url.protocol === "https:") return url;
-	if (url.protocol === "http:" && isLoopbackHost(url.hostname)) return url;
-	throw new CapletsError("REQUEST_INVALID", "Remote Caplets URL must use https except loopback development URLs.");
-}
-function isLoopbackHost(host) {
-	return host === "localhost" || host === "127.0.0.1" || host === "[::1]" || host === "::1";
-}
 function parsePollInterval(value) {
 	if (value === void 0) return DEFAULT_POLL_INTERVAL_MS;
 	if (!Number.isInteger(value) || value < 1e3) throw new CapletsError("REQUEST_INVALID", "remote.pollIntervalMs must be an integer >= 1000.");
 	return value;
 }
-function basicAuthHeader(user, password) {
-	return `Basic ${Buffer.from(`${user}:${password}`).toString("base64")}`;
-}
-function nonEmpty(value, label) {
-	if (value === void 0) return;
-	const trimmed = value.trim();
-	if (!trimmed) throw new CapletsError("REQUEST_INVALID", `${label} must not be empty`);
-	return trimmed;
-}
-function hasEnv(value) {
-	return value !== void 0 && value.trim() !== "";
-}
 //#endregion
 //#region src/native/tools.ts
 function nativeCapletToolName(capletId) {
@@ -281,7 +238,7 @@ function errorMessage(error) {
 	return error instanceof Error ? error.message : String(error);
 }
 function remoteAuthError() {
-	return new CapletsError("AUTH_FAILED", "Remote Caplets authentication failed; check CAPLETS_REMOTE_USER and CAPLETS_REMOTE_PASSWORD.");
+	return new CapletsError("AUTH_FAILED", "Remote Caplets authentication failed; check CAPLETS_SERVER_USER and CAPLETS_SERVER_PASSWORD.");
 }
 function isSessionFailure(error) {
 	const message = errorMessage(error).toLowerCase();

package/dist/{engine-Brwid_mq.js → options-CJEOqS87.js}

@@ -9,6 +9,7 @@ import { homedir } from "node:os";
 import { PassThrough } from "node:stream";
 import { createServer } from "node:http";
 import { createHash, randomBytes } from "node:crypto";
+import { Buffer as Buffer$1 } from "node:buffer";
 //#region \0rolldown/runtime.js
 var __create = Object.create;
 var __defProp = Object.defineProperty;
@@ -34,6 +35,25 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
 //#endregion
 //#region src/errors.ts
+const CAPLETS_ERROR_CODES = [
+	"CONFIG_NOT_FOUND",
+	"CONFIG_EXISTS",
+	"CONFIG_INVALID",
+	"REQUEST_INVALID",
+	"SERVER_NOT_FOUND",
+	"SERVER_UNAVAILABLE",
+	"SERVER_START_TIMEOUT",
+	"UNKNOWN_OPERATION",
+	"TOOL_NOT_FOUND",
+	"TOOL_CALL_TIMEOUT",
+	"AUTH_REQUIRED",
+	"AUTH_FAILED",
+	"AUTH_REFRESH_FAILED",
+	"DOWNSTREAM_PROTOCOL_ERROR",
+	"DOWNSTREAM_TOOL_ERROR",
+	"UNSUPPORTED_TRANSPORT",
+	"INTERNAL_ERROR"
+];
 var CapletsError = class extends Error {
 	code;
 	details;
@@ -31189,8 +31209,45 @@ var FileOAuthProvider = class {
 		headers.set("content-type", "application/x-www-form-urlencoded");
 	};
 };
-async function runOAuthFlow(server, options = {}) {
+async function startOAuthFlow(server, options) {
 	if (server.transport === "stdio" || !server.url || server.auth?.type !== "oauth2" && server.auth?.type !== "oidc") throw new CapletsError("REQUEST_INVALID", `${server.server} is not a configured OAuth remote server`);
+	let redirectUrl;
+	const provider = new FileOAuthProvider(server, options.redirectUri, (url) => {
+		redirectUrl = url;
+		options.print?.(`Open this URL to authorize ${server.server}:\n${url.toString()}`);
+	}, options.authDir);
+	const scope = scopesFor(server.auth);
+	try {
+		if (await auth(provider, {
+			serverUrl: server.url,
+			...scope ? { scope } : {}
+		}) === "AUTHORIZED") return {
+			authorizationUrl: "",
+			complete: async () => {}
+		};
+	} catch (error) {
+		throw normalizeMcpOAuthError(server, error);
+	}
+	if (!redirectUrl) throw new CapletsError("AUTH_FAILED", "OAuth authorization URL was not provided");
+	return {
+		authorizationUrl: redirectUrl.toString(),
+		complete: async (callbackUrl) => {
+			assertNoOAuthCallbackError(server, callbackUrl);
+			const completion = extractCompletion(callbackUrl);
+			if (completion.state !== provider.state()) throw new CapletsError("AUTH_FAILED", "OAuth callback state did not match");
+			try {
+				await auth(provider, {
+					serverUrl: server.url,
+					authorizationCode: completion.code,
+					...scope ? { scope } : {}
+				});
+			} catch (error) {
+				throw normalizeMcpOAuthError(server, error);
+			}
+		}
+	};
+}
+async function runOAuthFlow(server, options = {}) {
 	let callbackCode;
 	let callbackState;
 	const callback = await createLoopbackCallback((url) => {
@@ -31198,37 +31255,43 @@ async function runOAuthFlow(server, options = {}) {
 		callbackCode = url.searchParams.get("code") ?? void 0;
 		callbackState = url.searchParams.get("state") ?? void 0;
 	});
-	let redirectUrl;
-	const provider = new FileOAuthProvider(server, callback.redirectUri, (url) => {
-		redirectUrl = url;
-		options.print?.(`Open this URL to authorize ${server.server}:\n${url.toString()}`);
-	}, options.authDir);
 	try {
-		const scope = scopesFor(server.auth);
-		const first = await auth(provider, {
-			serverUrl: server.url,
-			...scope ? { scope } : {}
+		const started = await startOAuthFlow(server, {
+			redirectUri: callback.redirectUri,
+			...options.authDir ? { authDir: options.authDir } : {},
+			...options.print ? { print: options.print } : {}
 		});
-		if (first === "AUTHORIZED") return first;
-		if (!options.noOpen && redirectUrl) await (options.open ? options.open(redirectUrl.toString()) : openBrowser(redirectUrl.toString()));
+		if (!started.authorizationUrl) return "AUTHORIZED";
+		if (!options.noOpen) await (options.open ? options.open(started.authorizationUrl) : openBrowser(started.authorizationUrl));
 		const manualInput = options.manualInput ?? (options.noOpen ? await options.readManualInput?.() : void 0);
 		const completion = manualInput ? extractCompletion(manualInput) : await callback.waitForCode(() => callbackCode ? {
 			code: callbackCode,
 			...callbackState ? { state: callbackState } : {}
 		} : void 0);
-		const expectedState = provider.state();
-		if (completion.state !== expectedState) throw new CapletsError("AUTH_FAILED", "OAuth callback state did not match");
-		return await auth(provider, {
-			serverUrl: server.url,
-			authorizationCode: completion.code,
-			...scope ? { scope } : {}
-		});
+		await started.complete(completion.state ? `${callback.redirectUri}?code=${encodeURIComponent(completion.code)}&state=${encodeURIComponent(completion.state)}` : `${callback.redirectUri}?code=${encodeURIComponent(completion.code)}`);
+		return "AUTHORIZED";
 	} catch (error) {
 		throw normalizeMcpOAuthError(server, error);
 	} finally {
 		await callback.close();
 	}
 }
+function assertNoOAuthCallbackError(target, callbackUrl) {
+	let url;
+	try {
+		url = new URL(callbackUrl);
+	} catch {
+		return;
+	}
+	const error = url.searchParams.get("error");
+	if (!error) return;
+	const description = url.searchParams.get("error_description");
+	throw new CapletsError("AUTH_FAILED", description ? `OAuth provider returned an error: ${description}` : "OAuth provider returned an error", redactSecrets({
+		server: target.server,
+		error,
+		error_description: description ?? void 0
+	}));
+}
 function normalizeMcpOAuthError(server, error) {
 	if ((server.auth?.type === "oauth2" || server.auth?.type === "oidc") && !server.auth.clientId && !server.auth.clientMetadataUrl && error instanceof Error && error.message.includes("does not support dynamic client registration")) return new CapletsError("AUTH_FAILED", "OAuth is not available for this server without a host-specific OAuth app or PAT auth", {
 		server: server.server,
@@ -31236,6 +31299,75 @@ function normalizeMcpOAuthError(server, error) {
 	});
 	return error;
 }
+async function startGenericOAuthFlow(target, options) {
+	if (target.auth?.type !== "oauth2" && target.auth?.type !== "oidc") throw new CapletsError("REQUEST_INVALID", `${target.server} is not configured for OAuth`);
+	const authConfig = target.auth;
+	const redirectUri = authConfig.redirectUri ?? options.redirectUri;
+	const verifier = base64url(randomBytes(32));
+	const state = base64url(randomBytes(24));
+	const allowLoopbackHttp = isLoopbackDevelopmentTarget(target, authConfig);
+	const metadata = await discoverAuthorizationServer(target, authConfig, allowLoopbackHttp);
+	const authorizationEndpoint = authConfig.authorizationUrl ?? metadata.authorization_endpoint;
+	const tokenEndpoint = authConfig.tokenUrl ?? metadata.token_endpoint;
+	if (!authorizationEndpoint || !tokenEndpoint) throw new CapletsError("AUTH_FAILED", "OAuth metadata is missing endpoints", { server: target.server });
+	assertAllowedAuthUrl(authorizationEndpoint, "authorization endpoint", allowLoopbackHttp);
+	assertAllowedAuthUrl(tokenEndpoint, "token endpoint", allowLoopbackHttp);
+	const client = await resolveGenericClient(target, authConfig, metadata, redirectUri, allowLoopbackHttp);
+	const scope = scopesFor(authConfig);
+	const authorizationUrl = new URL(authorizationEndpoint);
+	authorizationUrl.searchParams.set("response_type", "code");
+	authorizationUrl.searchParams.set("client_id", client.clientId);
+	authorizationUrl.searchParams.set("redirect_uri", redirectUri);
+	authorizationUrl.searchParams.set("code_challenge", pkceChallenge(verifier));
+	authorizationUrl.searchParams.set("code_challenge_method", "S256");
+	authorizationUrl.searchParams.set("state", state);
+	if (scope) authorizationUrl.searchParams.set("scope", scope);
+	options.print?.(`Open this URL to authorize ${target.server}:\n${authorizationUrl.toString()}`);
+	return {
+		authorizationUrl: authorizationUrl.toString(),
+		complete: async (callbackUrl) => {
+			assertNoOAuthCallbackError(target, callbackUrl);
+			const completion = extractCompletion(callbackUrl);
+			if (completion.state !== state) throw new CapletsError("AUTH_FAILED", "OAuth callback state did not match");
+			const params = new URLSearchParams({
+				grant_type: "authorization_code",
+				code: completion.code,
+				redirect_uri: redirectUri,
+				client_id: client.clientId,
+				code_verifier: verifier
+			});
+			if (client.clientSecret) params.set("client_secret", client.clientSecret);
+			const tokenResponse = await fetchJson(tokenEndpoint, target.requestTimeoutMs, {
+				method: "POST",
+				headers: { "content-type": "application/x-www-form-urlencoded" },
+				body: params.toString()
+			}, allowLoopbackHttp);
+			const idToken = asString(tokenResponse.id_token);
+			const idClaims = parseJwtPayload(idToken);
+			validateOidcToken(authConfig, metadata, idToken, idClaims, client.clientId);
+			writeTokenBundle(stripUndefined({
+				server: target.server,
+				authType: authConfig.type,
+				accessToken: requireString(tokenResponse.access_token, "access_token"),
+				refreshToken: asString(tokenResponse.refresh_token),
+				tokenType: asString(tokenResponse.token_type),
+				expiresAt: typeof tokenResponse.expires_in === "number" ? new Date(Date.now() + tokenResponse.expires_in * 1e3).toISOString() : void 0,
+				scope: asString(tokenResponse.scope) ?? scope,
+				idToken,
+				issuer: asString(idClaims?.iss) ?? metadata.issuer ?? authConfig.issuer,
+				subject: asString(idClaims?.sub),
+				clientId: client.clientId,
+				clientSecret: client.clientSecret,
+				protectedResourceOrigin: protectedResourceOrigin(target, authConfig),
+				metadata: redactSecrets({
+					protectedResource: target.url ?? target.baseUrl ?? target.specUrl,
+					authorizationServer: metadata,
+					dynamicClient: client.dynamic ? { client_id: client.clientId } : void 0
+				})
+			}), options.authDir);
+		}
+	};
+}
 async function runGenericOAuthFlow(target, options = {}) {
 	if (target.auth?.type !== "oauth2" && target.auth?.type !== "oidc") throw new CapletsError("REQUEST_INVALID", `${target.server} is not configured for OAuth`);
 	const authConfig = target.auth;
@@ -58156,4 +58288,90 @@ function isDirectory(path) {
 	}
 }
 //#endregion
-export { getLiteralValue as $, ErrorCode as A, ListToolsRequestSchema as B, CompleteRequestSchema as C, string as Ct, DEFAULT_NEGOTIATED_PROTOCOL_VERSION as D, __commonJSMin as Dt, CreateTaskResultSchema as E, toSafeError as Et, LATEST_PROTOCOL_VERSION as F, SetLevelRequestSchema as G, McpError as H, ListPromptsRequestSchema as I, assertCompleteRequestResourceTemplate as J, ToolListChangedNotificationSchema as K, ListResourceTemplatesRequestSchema as L, InitializeRequestSchema as M, InitializedNotificationSchema as N, ElicitResultSchema as O, __require as Ot, JSONRPCMessageSchema as P, isJSONRPCResultResponse as Q, ListResourcesRequestSchema as R, CallToolResultSchema as S, object$1 as St, CreateMessageResultWithToolsSchema as T, CapletsError as Tt, ReadResourceRequestSchema as U, LoggingLevelSchema as V, SUPPORTED_PROTOCOL_VERSIONS as W, isJSONRPCErrorResponse as X, isInitializeRequest as Y, isJSONRPCRequest as Z, AjvJsonSchemaValidator as _, discoverCapletFiles as _t, capabilityDescription as a, normalizeObjectSchema as at, toJsonSchemaCompat as b, ZodOptional$1 as bt, deleteTokenBundle as c, safeParseAsync as ct, StreamableHTTPClientTransport as d, parseConfig as dt, getObjectShape as et, ReadBuffer as f, DEFAULT_AUTH_DIR as ft, assertToolsCallTaskCapability as g, resolveProjectConfigPath as gt, assertClientRequestTaskCapability as h, resolveProjectCapletsRoot as ht, ServerRegistry as i, isZ4Schema as it, GetPromptRequestSchema as j, EmptyResultSchema as k, __toESM as kt, isTokenBundleExpired as l, loadConfig as lt, Client as m, resolveConfigPath as mt, generatedToolInputSchema as n, getSchemaDescription as nt, runGenericOAuthFlow as o, objectFromShape as ot, serializeMessage as p, resolveCapletsRoot as pt, assertCompleteRequestPrompt as q, handleServerTool as r, isSchemaOptional as rt, runOAuthFlow as s, safeParse as st, CapletsEngine as t, getParseErrorMessage as tt, readTokenBundle as u, loadConfigWithSources as ut, Protocol as v, validateCapletFile as vt, CreateMessageResultSchema as w, url as wt, CallToolRequestSchema as x, literal as xt, mergeCapabilities as y, SERVER_ID_PATTERN as yt, ListRootsResultSchema as z };
+//#region src/server/options.ts
+const DEFAULT_SERVER_USER = "caplets";
+function resolveCapletsMode(input = {}, env = process.env) {
+	const mode = parseCapletsMode(input.mode ?? env.CAPLETS_MODE ?? "auto");
+	if (mode === "local") return { mode: "local" };
+	const rawUrl = nonEmpty(input.serverUrl, "serverUrl") ?? nonEmpty(env.CAPLETS_SERVER_URL, "CAPLETS_SERVER_URL");
+	if (mode === "remote") {
+		if (rawUrl === void 0) throw new CapletsError("REQUEST_INVALID", "CAPLETS_MODE=remote requires CAPLETS_SERVER_URL or serverUrl.");
+		return { mode: "remote" };
+	}
+	return rawUrl === void 0 ? { mode: "local" } : { mode: "remote" };
+}
+function resolveCapletsServer(input = {}, env = process.env) {
+	const rawUrl = nonEmpty(input.url, "url") ?? nonEmpty(env.CAPLETS_SERVER_URL, "CAPLETS_SERVER_URL");
+	if (rawUrl === void 0) throw new CapletsError("REQUEST_INVALID", "CAPLETS_SERVER_URL or url is required.");
+	const baseUrl = parseServerBaseUrl(rawUrl);
+	const userWasExplicit = input.user !== void 0 || hasEnv(env.CAPLETS_SERVER_USER);
+	const user = nonEmpty(input.user, "user") ?? nonEmpty(env.CAPLETS_SERVER_USER, "CAPLETS_SERVER_USER") ?? DEFAULT_SERVER_USER;
+	const password = nonEmpty(input.password, "password") ?? nonEmpty(env.CAPLETS_SERVER_PASSWORD, "CAPLETS_SERVER_PASSWORD");
+	if (userWasExplicit && password === void 0) throw new CapletsError("REQUEST_INVALID", "Caplets server Basic Auth requires a password; set CAPLETS_SERVER_PASSWORD or password.");
+	const auth = password === void 0 ? {
+		enabled: false,
+		user
+	} : {
+		enabled: true,
+		user,
+		password
+	};
+	const requestInit = auth.enabled ? { headers: { Authorization: basicAuthHeader(auth.user, auth.password) } } : {};
+	return {
+		baseUrl,
+		mcpUrl: mcpUrlForBase(baseUrl),
+		controlUrl: controlUrlForBase(baseUrl),
+		healthUrl: healthUrlForBase(baseUrl),
+		auth,
+		requestInit,
+		...input.fetch ? { fetch: input.fetch } : {}
+	};
+}
+function mcpUrlForBase(baseUrl) {
+	return appendBasePath(baseUrl, "mcp");
+}
+function controlUrlForBase(baseUrl) {
+	return appendBasePath(baseUrl, "control");
+}
+function healthUrlForBase(baseUrl) {
+	return appendBasePath(baseUrl, "healthz");
+}
+function appendBasePath(baseUrl, path) {
+	const url = new URL(baseUrl.href);
+	url.pathname = `${url.pathname === "/" ? "" : url.pathname}/${path}`;
+	return url;
+}
+function parseServerBaseUrl(value) {
+	let url;
+	try {
+		url = new URL(value);
+	} catch {
+		throw new CapletsError("REQUEST_INVALID", "Invalid Caplets server URL.");
+	}
+	if (url.username !== "" || url.password !== "" || url.search !== "" || url.hash !== "") throw new CapletsError("REQUEST_INVALID", "Caplets server URL must not include username, password, query string, or fragment.");
+	if (url.protocol !== "https:" && !(url.protocol === "http:" && isLoopbackHost(url.hostname))) throw new CapletsError("REQUEST_INVALID", "Caplets server URL must use https except loopback development URLs.");
+	url.pathname = url.pathname === "/" ? "/" : url.pathname.replace(/\/+$/u, "");
+	return url;
+}
+function isLoopbackHost(host) {
+	const normalized = host.toLocaleLowerCase();
+	return normalized === "localhost" || normalized === "127.0.0.1" || normalized === "::1" || normalized === "[::1]";
+}
+function parseCapletsMode(value) {
+	if (value === "auto" || value === "local" || value === "remote") return value;
+	throw new CapletsError("REQUEST_INVALID", `Expected CAPLETS_MODE to be auto, local, or remote, got ${value}`);
+}
+function basicAuthHeader(user, password) {
+	return `Basic ${Buffer$1.from(`${user}:${password}`).toString("base64")}`;
+}
+function nonEmpty(value, label) {
+	if (value === void 0) return;
+	const trimmed = value.trim();
+	if (!trimmed) throw new CapletsError("REQUEST_INVALID", `${label} must not be empty`);
+	return trimmed;
+}
+function hasEnv(value) {
+	return value !== void 0 && value.trim() !== "";
+}
+//#endregion
+export { ToolListChangedNotificationSchema as $, CompleteRequestSchema as A, string as At, InitializedNotificationSchema as B, assertToolsCallTaskCapability as C, resolveProjectConfigPath as Ct, toJsonSchemaCompat as D, ZodOptional$1 as Dt, mergeCapabilities as E, SERVER_ID_PATTERN as Et, ElicitResultSchema as F, toSafeError as Ft, ListResourcesRequestSchema as G, LATEST_PROTOCOL_VERSION as H, EmptyResultSchema as I, __commonJSMin as It, LoggingLevelSchema as J, ListRootsResultSchema as K, ErrorCode as L, __require as Lt, CreateMessageResultWithToolsSchema as M, CAPLETS_ERROR_CODES as Mt, CreateTaskResultSchema as N, CapletsError as Nt, CallToolRequestSchema as O, literal as Ot, DEFAULT_NEGOTIATED_PROTOCOL_VERSION as P, redactSecrets as Pt, SetLevelRequestSchema as Q, GetPromptRequestSchema as R, __toESM as Rt, assertClientRequestTaskCapability as S, resolveProjectCapletsRoot as St, Protocol as T, validateCapletFile as Tt, ListPromptsRequestSchema as U, JSONRPCMessageSchema as V, ListResourceTemplatesRequestSchema as W, ReadResourceRequestSchema as X, McpError as Y, SUPPORTED_PROTOCOL_VERSIONS as Z, readTokenBundle as _, loadConfigWithSources as _t, resolveCapletsServer as a, isJSONRPCResultResponse as at, serializeMessage as b, resolveCapletsRoot as bt, handleServerTool as c, getParseErrorMessage as ct, runGenericOAuthFlow as d, isZ4Schema as dt, assertCompleteRequestPrompt as et, runOAuthFlow as f, normalizeObjectSchema as ft, isTokenBundleExpired as g, loadConfig as gt, deleteTokenBundle as h, safeParseAsync as ht, resolveCapletsMode as i, isJSONRPCRequest as it, CreateMessageResultSchema as j, url as jt, CallToolResultSchema as k, object$1 as kt, ServerRegistry as l, getSchemaDescription as lt, startOAuthFlow as m, safeParse as mt, mcpUrlForBase as n, isInitializeRequest as nt, CapletsEngine as o, getLiteralValue as ot, startGenericOAuthFlow as p, objectFromShape as pt, ListToolsRequestSchema as q, parseServerBaseUrl as r, isJSONRPCErrorResponse as rt, generatedToolInputSchema as s, getObjectShape as st, controlUrlForBase as t, assertCompleteRequestResourceTemplate as tt, capabilityDescription as u, isSchemaOptional as ut, StreamableHTTPClientTransport as v, parseConfig as vt, AjvJsonSchemaValidator as w, discoverCapletFiles as wt, Client as x, resolveConfigPath as xt, ReadBuffer as y, DEFAULT_AUTH_DIR as yt, InitializeRequestSchema as z };

package/dist/remote-control/auth-flow.d.ts

@@ -0,0 +1,22 @@
+export type RemoteAuthFlow = {
+    id: string;
+    server: string;
+    authorizationUrl: string;
+    createdAt: number;
+    complete(callbackUrl: string): Promise<void>;
+};
+export type RemoteAuthFlowStoreOptions = {
+    ttlMs?: number;
+    now?: () => number;
+};
+export declare class RemoteAuthFlowStore {
+    private readonly options;
+    private readonly flows;
+    constructor(options?: RemoteAuthFlowStoreOptions);
+    create(flow: Omit<RemoteAuthFlow, "id" | "createdAt">, id?: string): RemoteAuthFlow;
+    get(id: string): RemoteAuthFlow | undefined;
+    delete(id: string): void;
+    private pruneExpired;
+    private isExpired;
+    private now;
+}

package/dist/remote-control/client.d.ts

@@ -0,0 +1,11 @@
+import type { RemoteCliCommand, RemoteCliRequest } from "./types";
+export type RemoteControlClientOptions = {
+    baseUrl: URL;
+    requestInit: RequestInit;
+    fetch?: typeof fetch;
+};
+export declare class RemoteControlClient {
+    #private;
+    constructor(options: RemoteControlClientOptions);
+    request(command: RemoteCliCommand, args: RemoteCliRequest["arguments"]): Promise<unknown>;
+}

package/dist/remote-control/dispatch.d.ts

@@ -0,0 +1,9 @@
+import { type CapletsEngineOptions } from "../engine";
+import type { RemoteAuthFlowStore } from "./auth-flow";
+import type { RemoteCliRequest, RemoteCliResponse } from "./types";
+export type RemoteControlDispatchContext = CapletsEngineOptions & {
+    projectCapletsRoot: string;
+    authFlowStore?: RemoteAuthFlowStore;
+    controlCallbackBaseUrl?: string;
+};
+export declare function dispatchRemoteCliRequest(request: RemoteCliRequest, context: RemoteControlDispatchContext): Promise<RemoteCliResponse>;

package/dist/remote-control/types.d.ts

@@ -0,0 +1,17 @@
+import type { CapletsErrorCode } from "../errors";
+export type RemoteCliCommand = "list" | "get_caplet" | "check_backend" | "list_tools" | "search_tools" | "get_tool" | "call_tool" | "init" | "add" | "install" | "auth_login_start" | "auth_login_complete" | "auth_logout" | "auth_list";
+export type RemoteCliRequest = {
+    command: RemoteCliCommand;
+    arguments: Record<string, unknown>;
+};
+export type RemoteCliResponse = {
+    ok: true;
+    result: unknown;
+} | {
+    ok: false;
+    error: {
+        code: CapletsErrorCode;
+        message: string;
+        nextAction?: string;
+    };
+};

package/dist/serve/http.d.ts

@@ -1,12 +1,23 @@
 import { Hono } from "hono";
 import { CapletsEngine, type CapletsEngineOptions } from "../engine";
+import { type RemoteControlDispatchContext } from "../remote-control/dispatch";
+import { RemoteAuthFlowStore } from "../remote-control/auth-flow";
 import type { HttpServeOptions } from "./options";
 type HttpServeIo = {
     writeErr?: (value: string) => void;
+    control?: Omit<RemoteControlDispatchContext, "writeErr">;
+    authFlowStore?: RemoteAuthFlowStore;
 };
 export type CapletsHttpApp = Hono & {
     closeCapletsSessions: () => Promise<void>;
 };
 export declare function createHttpServeApp(options: HttpServeOptions, engine: CapletsEngine, io?: HttpServeIo): CapletsHttpApp;
 export declare function serveHttp(options: HttpServeOptions, engineOptions?: CapletsEngineOptions, writeErr?: (value: string) => void): Promise<void>;
+export declare function routePath(base: string, path: string): string;
+export declare function servicePaths(base: string): {
+    base: string;
+    mcp: string;
+    control: string;
+    health: string;
+};
 export {};

package/dist/serve/options.d.ts

@@ -7,6 +7,7 @@ export type RawServeOptions = {
     user?: string;
     password?: string;
     allowUnauthenticatedHttp?: boolean;
+    trustProxy?: boolean;
 };
 export type StdioServeOptions = {
     transport: "stdio";
@@ -19,6 +20,7 @@ export type HttpServeOptions = {
     auth: HttpBasicAuthOptions;
     warnUnauthenticatedNetwork: boolean;
     loopback: boolean;
+    trustProxy: boolean;
 };
 export type HttpBasicAuthOptions = {
     enabled: false;
@@ -29,6 +31,6 @@ export type HttpBasicAuthOptions = {
     password: string;
 };
 export type ServeOptions = StdioServeOptions | HttpServeOptions;
-export type ServeEnv = Partial<Record<"CAPLETS_SERVER_USER" | "CAPLETS_SERVER_PASSWORD", string>>;
+export type ServeEnv = Partial<Record<"CAPLETS_SERVER_URL" | "CAPLETS_SERVER_USER" | "CAPLETS_SERVER_PASSWORD", string>>;
 export declare function resolveServeOptions(raw: RawServeOptions, env?: ServeEnv): ServeOptions;
 export declare function isLoopbackHost(host: string): boolean;

package/dist/server/options.d.ts

@@ -0,0 +1,41 @@
+export type CapletsMode = "auto" | "local" | "remote";
+export type CapletsServerEnv = Partial<Record<"CAPLETS_MODE" | "CAPLETS_SERVER_URL" | "CAPLETS_SERVER_USER" | "CAPLETS_SERVER_PASSWORD", string>>;
+export type CapletsModeInput = {
+    mode?: string;
+    serverUrl?: string;
+};
+export type CapletsServerInput = {
+    url?: string;
+    user?: string;
+    password?: string;
+    fetch?: typeof fetch;
+};
+export type CapletsServerAuth = {
+    enabled: false;
+    user: string;
+} | {
+    enabled: true;
+    user: string;
+    password: string;
+};
+export type ResolvedCapletsServer = {
+    baseUrl: URL;
+    mcpUrl: URL;
+    controlUrl: URL;
+    healthUrl: URL;
+    auth: CapletsServerAuth;
+    requestInit: RequestInit;
+    fetch?: typeof fetch;
+};
+export declare function resolveCapletsMode(input?: CapletsModeInput, env?: CapletsServerEnv): {
+    mode: "local";
+} | {
+    mode: "remote";
+};
+export declare function resolveCapletsServer(input?: CapletsServerInput, env?: CapletsServerEnv): ResolvedCapletsServer;
+export declare function mcpUrlForBase(baseUrl: URL): URL;
+export declare function controlUrlForBase(baseUrl: URL): URL;
+export declare function healthUrlForBase(baseUrl: URL): URL;
+export declare function appendBasePath(baseUrl: URL, path: string): URL;
+export declare function parseServerBaseUrl(value: string): URL;
+export declare function isLoopbackHost(host: string): boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caplets/core",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Core runtime library for Caplets progressive disclosure gateways.",
   "keywords": [
     "caplets",