caplets 0.8.0 → 0.9.0

package/README.md

@@ -28,7 +28,7 @@ the agent chooses that server and asks to search, list, inspect, or call them.
 
 ## What It Does
 
-- Reads downstream MCP server definitions, native OpenAPI endpoint definitions, native GraphQL endpoint definitions, and explicit HTTP API action definitions from `~/.caplets/config.json`.
+- Reads downstream MCP server definitions, native OpenAPI endpoint definitions, native GraphQL endpoint definitions, and explicit HTTP API action definitions from the user config file.
 - Registers one generated MCP tool for each enabled MCP server, OpenAPI endpoint, GraphQL endpoint, or HTTP API.
 - Uses the configured server ID as the generated tool name.
 - Uses the configured `name` and `description` as the capability card shown to agents.
@@ -59,7 +59,7 @@ pnpm build
 
 ## Configure
 
-Create a starter `~/.caplets/config.json`:
+Create a starter user config at `${XDG_CONFIG_HOME:-~/.config}/caplets/config.json` on Unix-like platforms or `%APPDATA%\caplets\config.json` on Windows:
 
 ```sh
 caplets init
@@ -143,7 +143,7 @@ you want Caplets to expose:
 }
 ```
 
-The default config path can be overridden with `CAPLETS_CONFIG`:
+The default config path is `${XDG_CONFIG_HOME:-~/.config}/caplets/config.json` on Unix-like platforms and `%APPDATA%\caplets\config.json` on Windows. It can be overridden with `CAPLETS_CONFIG`:
 
 ```sh
 CAPLETS_CONFIG=/path/to/config.json caplets init
@@ -279,11 +279,13 @@ caplets install spiritledsoftware/caplets github linear
 ```
 
 `caplets install` accepts a GitHub `owner/repo` shorthand, a Git URL, or a local repository path.
-It installs into your user Caplets root, which is `~/.caplets` by default or the parent directory
-of `CAPLETS_CONFIG` when that environment variable is set. Existing Caplets are not overwritten
-unless `--force` is passed.
+It installs into your user Caplets root, which is `${XDG_CONFIG_HOME:-~/.config}/caplets` on Unix-like platforms,
+`%APPDATA%\caplets` on Windows, or the parent directory of `CAPLETS_CONFIG` when that environment variable is set.
+Existing Caplets are not overwritten unless `--force` is passed.
 
-Caplets always loads user Caplet files from `~/.caplets`. Project `./.caplets/config.json`
+On Unix-like platforms, relative `XDG_CONFIG_HOME` and `XDG_STATE_HOME` values are ignored.
+
+Caplets always loads user Caplet files from the user Caplets root. Project `./.caplets/config.json`
 is still loaded as project config, but project Markdown Caplet files are executable
 configuration and are ignored unless explicitly trusted:
 
@@ -511,10 +513,11 @@ For headless terminals:
 caplets auth login <server> --no-open
 ```
 
-OAuth/OIDC tokens are stored under `~/.caplets/auth/<server>.json` with owner-only file
-permissions where the platform supports them. Caplets supports well-known OAuth/OIDC
-discovery and dynamic client registration when advertised. When a token expires, run
-`caplets auth login <server>` again.
+OAuth/OIDC tokens are stored under `${XDG_STATE_HOME:-~/.local/state}/caplets/auth/<server>.json`
+on Unix-like platforms and `%LOCALAPPDATA%\caplets\auth\<server>.json` on Windows.
+Token files use owner-only file permissions where the platform supports them. Caplets supports
+well-known OAuth/OIDC discovery and dynamic client registration when advertised. When a token expires,
+run `caplets auth login <server>` again.
 
 To inspect or remove stored OAuth credentials:
 

package/dist/index.js

@@ -2,7 +2,7 @@
 import { createRequire } from "node:module";
 import minproc, { stdin, stdout, default as process$1 } from "node:process";
 import { execFileSync } from "node:child_process";
-import minpath, { basename, dirname, extname, isAbsolute, join, parse, relative, resolve, sep } from "node:path";
+import minpath, { basename, dirname, extname, isAbsolute, join, parse, posix, relative, resolve, win32 } from "node:path";
 import { accessSync, chmodSync, constants, cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, statSync, watch, writeFileSync } from "node:fs";
 import { createInterface } from "node:readline/promises";
 import { createServer } from "node:http";
@@ -9619,7 +9619,7 @@ const { program, createCommand, createArgument, createOption, CommanderError, In
 })))(), 1)).default;
 //#endregion
 //#region package.json
-var version = "0.8.0";
+var version = "0.9.0";
 //#endregion
 //#region node_modules/.pnpm/pkce-challenge@5.0.1/node_modules/pkce-challenge/dist/index.node.js
 let crypto;
@@ -10658,6 +10658,41 @@ async function registerClient(authorizationServerUrl, { metadata, clientMetadata
 	return OAuthClientInformationFullSchema.parse(await response.json());
 }
 //#endregion
+//#region src/config/paths.ts
+function defaultConfigBaseDir(env = process.env, home = homedir(), platform = process.platform) {
+	if (platform === "win32") return env.APPDATA && win32.isAbsolute(env.APPDATA) ? env.APPDATA : win32.join(home, "AppData", "Roaming");
+	return env.XDG_CONFIG_HOME && posix.isAbsolute(env.XDG_CONFIG_HOME) ? env.XDG_CONFIG_HOME : posix.join(home, ".config");
+}
+function defaultStateBaseDir(env = process.env, home = homedir(), platform = process.platform) {
+	if (platform === "win32") return env.LOCALAPPDATA && win32.isAbsolute(env.LOCALAPPDATA) ? env.LOCALAPPDATA : win32.join(home, "AppData", "Local");
+	return env.XDG_STATE_HOME && posix.isAbsolute(env.XDG_STATE_HOME) ? env.XDG_STATE_HOME : posix.join(home, ".local", "state");
+}
+function defaultConfigPath(env = process.env, home = homedir(), platform = process.platform) {
+	return (platform === "win32" ? win32.join : posix.join)(defaultConfigBaseDir(env, home, platform), "caplets", "config.json");
+}
+function defaultAuthDir(env = process.env, home = homedir(), platform = process.platform) {
+	return (platform === "win32" ? win32.join : posix.join)(defaultStateBaseDir(env, home, platform), "caplets", "auth");
+}
+const DEFAULT_CONFIG_PATH = defaultConfigPath();
+const DEFAULT_AUTH_DIR = defaultAuthDir();
+const PROJECT_CONFIG_FILE = join(".caplets", "config.json");
+const TRUST_PROJECT_CAPLETS_ENV = "CAPLETS_TRUST_PROJECT_CAPLETS";
+function resolveConfigPath(path) {
+	return path ?? DEFAULT_CONFIG_PATH;
+}
+function resolveProjectConfigPath(cwd = process.cwd()) {
+	return join(cwd, PROJECT_CONFIG_FILE);
+}
+function resolveCapletsRoot(configPath = resolveConfigPath()) {
+	return dirname(configPath);
+}
+function resolveProjectCapletsRoot(cwd = process.cwd()) {
+	return join(cwd, ".caplets");
+}
+function isTrustedEnvEnabled(value) {
+	return value === "1" || value?.toLowerCase() === "true" || value?.toLowerCase() === "yes";
+}
+//#endregion
 //#region src/errors.ts
 var CapletsError = class extends Error {
 	code;
@@ -10708,11 +10743,12 @@ function errorResult(error, fallback) {
 }
 //#endregion
 //#region src/auth/store.ts
-function authStorePath(server, authDir = join(homedir(), ".caplets", "auth")) {
+function authStorePath(server, authDir = DEFAULT_AUTH_DIR) {
 	if (!server || server.includes("/") || server.includes("\\") || server.includes("..")) throw new CapletsError("REQUEST_INVALID", `Invalid auth store server name ${server}`);
 	const authRoot = resolve(authDir);
 	const candidate = resolve(authRoot, `${server}.json`);
-	if (candidate !== authRoot && candidate.startsWith(`${authRoot}${sep}`)) return candidate;
+	const relativePath = relative(authRoot, candidate);
+	if (relativePath && !relativePath.startsWith("..") && !isAbsolute(relativePath)) return candidate;
 	throw new CapletsError("REQUEST_INVALID", `Invalid auth store server name ${server}`);
 }
 function readTokenBundle(server, authDir) {
@@ -10780,11 +10816,13 @@ var FileOAuthProvider = class {
 	verifier = base64url(randomBytes(32));
 	stateValue = base64url(randomBytes(24));
 	clientInfo;
+	clientMetadataUrl;
 	constructor(server, redirectUrl, onRedirect, authDir) {
 		this.server = server;
 		this.redirectUrl = redirectUrl;
 		this.onRedirect = onRedirect;
 		this.authDir = authDir;
+		if ((this.server.auth?.type === "oauth2" || this.server.auth?.type === "oidc") && this.server.auth.clientMetadataUrl) this.clientMetadataUrl = this.server.auth.clientMetadataUrl;
 	}
 	get clientMetadata() {
 		return {
@@ -10884,10 +10922,19 @@ async function runOAuthFlow(server, options = {}) {
 			authorizationCode: completion.code,
 			...scope ? { scope } : {}
 		});
+	} catch (error) {
+		throw normalizeMcpOAuthError(server, error);
 	} finally {
 		await callback.close();
 	}
 }
+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,
+		nextAction: "configure_bearer_auth_or_host_oauth_app"
+	});
+	return error;
+}
 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;
@@ -11057,6 +11104,11 @@ async function resolveGenericClient(target, authConfig, metadata, redirectUri, a
 		...authConfig.clientSecret ? { clientSecret: authConfig.clientSecret } : {},
 		dynamic: false
 	};
+	if (authConfig.clientMetadataUrl) return {
+		clientId: authConfig.clientMetadataUrl,
+		...authConfig.clientSecret ? { clientSecret: authConfig.clientSecret } : {},
+		dynamic: false
+	};
 	if (!metadata.registration_endpoint) throw new CapletsError("AUTH_FAILED", "OAuth clientId is required without dynamic registration", { server: target.server });
 	const response = await fetchJson(metadata.registration_endpoint, target.requestTimeoutMs, {
 		method: "POST",
@@ -11125,8 +11177,9 @@ function assertAllowedAuthUrl(value, label, allowLoopbackHttp = false) {
 	throw new CapletsError("AUTH_FAILED", `${label} must use https except loopback development URLs`);
 }
 function assertTokenBundleMatchesTarget(bundle, target, authConfig) {
+	const configuredClientId = authConfig.clientId ?? authConfig.clientMetadataUrl;
 	const expectedOrigin = protectedResourceOrigin(target, authConfig);
-	if (bundle.authType !== authConfig.type || expectedOrigin && bundle.protectedResourceOrigin !== expectedOrigin || authConfig.clientId && bundle.clientId !== authConfig.clientId || authConfig.issuer && bundle.issuer !== authConfig.issuer) throw new CapletsError("AUTH_REQUIRED", `OAuth credentials for ${target.server} do not match the configured backend`, {
+	if (bundle.authType !== authConfig.type || expectedOrigin && bundle.protectedResourceOrigin !== expectedOrigin || configuredClientId && bundle.clientId !== configuredClientId || authConfig.issuer && bundle.issuer !== authConfig.issuer) throw new CapletsError("AUTH_REQUIRED", `OAuth credentials for ${target.server} do not match the configured backend`, {
 		server: target.server,
 		backend: target.backend,
 		authType: authConfig.type,
@@ -18762,6 +18815,7 @@ const capletRemoteAuthSchema = discriminatedUnion("type", [
 		resourceMetadataUrl: string().min(1).optional(),
 		authorizationServerMetadataUrl: string().min(1).optional(),
 		openidConfigurationUrl: string().min(1).optional(),
+		clientMetadataUrl: string().min(1).optional(),
 		clientId: string().min(1).optional(),
 		clientSecret: string().min(1).optional(),
 		scopes: array(string().min(1)).optional(),
@@ -18775,6 +18829,7 @@ const capletRemoteAuthSchema = discriminatedUnion("type", [
 		resourceMetadataUrl: string().min(1).optional(),
 		authorizationServerMetadataUrl: string().min(1).optional(),
 		openidConfigurationUrl: string().min(1).optional(),
+		clientMetadataUrl: string().min(1).optional(),
 		clientId: string().min(1).optional(),
 		clientSecret: string().min(1).optional(),
 		scopes: array(string().min(1)).optional(),
@@ -18799,6 +18854,7 @@ const capletEndpointAuthSchema = discriminatedUnion("type", [
 		resourceMetadataUrl: string().min(1).optional(),
 		authorizationServerMetadataUrl: string().min(1).optional(),
 		openidConfigurationUrl: string().min(1).optional(),
+		clientMetadataUrl: string().min(1).optional(),
 		clientId: string().min(1).optional(),
 		clientSecret: string().min(1).optional(),
 		scopes: array(string().min(1)).optional(),
@@ -18812,6 +18868,7 @@ const capletEndpointAuthSchema = discriminatedUnion("type", [
 		resourceMetadataUrl: string().min(1).optional(),
 		authorizationServerMetadataUrl: string().min(1).optional(),
 		openidConfigurationUrl: string().min(1).optional(),
+		clientMetadataUrl: string().min(1).optional(),
 		clientId: string().min(1).optional(),
 		clientSecret: string().min(1).optional(),
 		scopes: array(string().min(1)).optional(),
@@ -18855,10 +18912,11 @@ const capletMcpServerSchema = object$1({
 		path: ["url"],
 		message: "remote url must use https except loopback development urls"
 	});
-	if (server.auth?.type === "oauth2") for (const field of [
+	if (server.auth?.type === "oauth2" || server.auth?.type === "oidc") for (const field of [
 		"authorizationUrl",
 		"tokenUrl",
 		"issuer",
+		"clientMetadataUrl",
 		"redirectUri"
 	]) {
 		const value = server.auth[field];
@@ -19161,27 +19219,6 @@ function hasEnvReference$1(value) {
 	return /\$\{[A-Za-z_][A-Za-z0-9_]*\}|\$env:[A-Za-z_][A-Za-z0-9_]*/.test(value);
 }
 //#endregion
-//#region src/config/paths.ts
-const DEFAULT_CONFIG_PATH = join(homedir(), ".caplets", "config.json");
-const DEFAULT_AUTH_DIR = join(homedir(), ".caplets", "auth");
-const PROJECT_CONFIG_FILE = join(".caplets", "config.json");
-const TRUST_PROJECT_CAPLETS_ENV = "CAPLETS_TRUST_PROJECT_CAPLETS";
-function resolveConfigPath(path) {
-	return path ?? DEFAULT_CONFIG_PATH;
-}
-function resolveProjectConfigPath(cwd = process.cwd()) {
-	return join(cwd, PROJECT_CONFIG_FILE);
-}
-function resolveCapletsRoot(configPath = resolveConfigPath()) {
-	return dirname(configPath);
-}
-function resolveProjectCapletsRoot(cwd = process.cwd()) {
-	return join(cwd, ".caplets");
-}
-function isTrustedEnvEnabled(value) {
-	return value === "1" || value?.toLowerCase() === "true" || value?.toLowerCase() === "yes";
-}
-//#endregion
 //#region src/config.ts
 const NON_INTERPOLATED_SERVER_FIELDS = new Set([
 	"name",
@@ -19207,6 +19244,7 @@ const remoteAuthSchema = discriminatedUnion("type", [
 		resourceMetadataUrl: string().url().optional(),
 		authorizationServerMetadataUrl: string().url().optional(),
 		openidConfigurationUrl: string().url().optional(),
+		clientMetadataUrl: string().url().optional(),
 		clientId: string().min(1).optional(),
 		clientSecret: string().min(1).optional(),
 		scopes: array(string().min(1)).optional(),
@@ -19220,6 +19258,7 @@ const remoteAuthSchema = discriminatedUnion("type", [
 		resourceMetadataUrl: string().url().optional(),
 		authorizationServerMetadataUrl: string().url().optional(),
 		openidConfigurationUrl: string().url().optional(),
+		clientMetadataUrl: string().url().optional(),
 		clientId: string().min(1).optional(),
 		clientSecret: string().min(1).optional(),
 		scopes: array(string().min(1)).optional(),
@@ -19234,6 +19273,7 @@ const oauthLikeAuthSchema = union([object$1({
 	resourceMetadataUrl: string().url().optional(),
 	authorizationServerMetadataUrl: string().url().optional(),
 	openidConfigurationUrl: string().url().optional(),
+	clientMetadataUrl: string().url().optional(),
 	clientId: string().min(1).optional(),
 	clientSecret: string().min(1).optional(),
 	scopes: array(string().min(1)).optional(),
@@ -19246,6 +19286,7 @@ const oauthLikeAuthSchema = union([object$1({
 	resourceMetadataUrl: string().url().optional(),
 	authorizationServerMetadataUrl: string().url().optional(),
 	openidConfigurationUrl: string().url().optional(),
+	clientMetadataUrl: string().url().optional(),
 	clientId: string().min(1).optional(),
 	clientSecret: string().min(1).optional(),
 	scopes: array(string().min(1)).optional(),
@@ -19896,12 +19937,14 @@ function formatCapletList(rows) {
 }
 function resolveCliConfigPaths(envConfigPath, authDir) {
 	const configPath = resolveConfigPath(envConfigPath);
+	const effectiveAuthDir = authDir ?? DEFAULT_AUTH_DIR;
 	return {
 		userConfig: configPath,
 		projectConfig: resolveProjectConfigPath(),
 		userRoot: resolveCapletsRoot(configPath),
+		stateRoot: dirname(effectiveAuthDir),
 		projectRoot: resolveProjectCapletsRoot(),
-		authDir: authDir ?? DEFAULT_AUTH_DIR,
+		authDir: effectiveAuthDir,
 		envConfig: envConfigPath ?? null,
 		projectCapletsTrusted: isTrustedProjectCapletsEnabled()
 	};
@@ -19911,6 +19954,7 @@ function formatConfigPaths(paths) {
 		`userConfig: ${paths.userConfig}`,
 		`projectConfig: ${paths.projectConfig}`,
 		`userRoot: ${paths.userRoot}`,
+		`stateRoot: ${paths.stateRoot}`,
 		`projectRoot: ${paths.projectRoot}`,
 		`authDir: ${paths.authDir}`,
 		`envConfig: ${paths.envConfig ?? "unset"}`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "caplets",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Progressive disclosure gateway for MCP servers.",
   "keywords": [
     "caplets",

package/schemas/caplet.schema.json

@@ -149,6 +149,10 @@
                   "type": "string",
                   "minLength": 1
                 },
+                "clientMetadataUrl": {
+                  "type": "string",
+                  "minLength": 1
+                },
                 "clientId": {
                   "type": "string",
                   "minLength": 1
@@ -203,6 +207,10 @@
                   "type": "string",
                   "minLength": 1
                 },
+                "clientMetadataUrl": {
+                  "type": "string",
+                  "minLength": 1
+                },
                 "clientId": {
                   "type": "string",
                   "minLength": 1
@@ -353,6 +361,10 @@
                   "type": "string",
                   "minLength": 1
                 },
+                "clientMetadataUrl": {
+                  "type": "string",
+                  "minLength": 1
+                },
                 "clientId": {
                   "type": "string",
                   "minLength": 1
@@ -407,6 +419,10 @@
                   "type": "string",
                   "minLength": 1
                 },
+                "clientMetadataUrl": {
+                  "type": "string",
+                  "minLength": 1
+                },
                 "clientId": {
                   "type": "string",
                   "minLength": 1
@@ -591,6 +607,10 @@
                   "type": "string",
                   "minLength": 1
                 },
+                "clientMetadataUrl": {
+                  "type": "string",
+                  "minLength": 1
+                },
                 "clientId": {
                   "type": "string",
                   "minLength": 1
@@ -645,6 +665,10 @@
                   "type": "string",
                   "minLength": 1
                 },
+                "clientMetadataUrl": {
+                  "type": "string",
+                  "minLength": 1
+                },
                 "clientId": {
                   "type": "string",
                   "minLength": 1
@@ -788,6 +812,10 @@
                   "type": "string",
                   "minLength": 1
                 },
+                "clientMetadataUrl": {
+                  "type": "string",
+                  "minLength": 1
+                },
                 "clientId": {
                   "type": "string",
                   "minLength": 1
@@ -842,6 +870,10 @@
                   "type": "string",
                   "minLength": 1
                 },
+                "clientMetadataUrl": {
+                  "type": "string",
+                  "minLength": 1
+                },
                 "clientId": {
                   "type": "string",
                   "minLength": 1

package/schemas/caplets-config.schema.json

@@ -168,6 +168,10 @@
                     "type": "string",
                     "format": "uri"
                   },
+                  "clientMetadataUrl": {
+                    "type": "string",
+                    "format": "uri"
+                  },
                   "clientId": {
                     "type": "string",
                     "minLength": 1
@@ -222,6 +226,10 @@
                     "type": "string",
                     "format": "uri"
                   },
+                  "clientMetadataUrl": {
+                    "type": "string",
+                    "format": "uri"
+                  },
                   "clientId": {
                     "type": "string",
                     "minLength": 1
@@ -403,6 +411,10 @@
                     "type": "string",
                     "format": "uri"
                   },
+                  "clientMetadataUrl": {
+                    "type": "string",
+                    "format": "uri"
+                  },
                   "clientId": {
                     "type": "string",
                     "minLength": 1
@@ -457,6 +469,10 @@
                     "type": "string",
                     "format": "uri"
                   },
+                  "clientMetadataUrl": {
+                    "type": "string",
+                    "format": "uri"
+                  },
                   "clientId": {
                     "type": "string",
                     "minLength": 1
@@ -670,6 +686,10 @@
                     "type": "string",
                     "format": "uri"
                   },
+                  "clientMetadataUrl": {
+                    "type": "string",
+                    "format": "uri"
+                  },
                   "clientId": {
                     "type": "string",
                     "minLength": 1
@@ -724,6 +744,10 @@
                     "type": "string",
                     "format": "uri"
                   },
+                  "clientMetadataUrl": {
+                    "type": "string",
+                    "format": "uri"
+                  },
                   "clientId": {
                     "type": "string",
                     "minLength": 1
@@ -896,6 +920,10 @@
                     "type": "string",
                     "format": "uri"
                   },
+                  "clientMetadataUrl": {
+                    "type": "string",
+                    "format": "uri"
+                  },
                   "clientId": {
                     "type": "string",
                     "minLength": 1
@@ -950,6 +978,10 @@
                     "type": "string",
                     "format": "uri"
                   },
+                  "clientMetadataUrl": {
+                    "type": "string",
+                    "format": "uri"
+                  },
                   "clientId": {
                     "type": "string",
                     "minLength": 1