@happyvertical/smrt-app-cli 0.40.48 → 0.40.50

package/AGENTS.md

@@ -13,6 +13,8 @@ Application CLI support for SMRT-based apps.
 - Keep commands app-agnostic; pass app identity through `CliConfigContext`.
 - Treat transient auth polling failures as recoverable until the server-issued expiration window closes.
 - Do not persist tokens, server URLs, or app slugs outside the configured local CLI config path.
+- Bind persisted bearer tokens to the exact issuer emitted by the device flow
+  and to the server selected during login. Never reuse them after either changes.
 - Keep command output stream-injectable so tests can assert behavior without writing to the real terminal.
 
 ## Gotchas

package/README.md

@@ -90,6 +90,13 @@ surface is typically mounted with
 - Device-code login distinguishes pending approval, expiry, transient network
   failure, and hard rejection.
 - Tokens and server configuration stay in the app-specific local config path.
+- Device-flow responses identify their issuer. Tokens are keyed by that exact
+  issuer and are not reused when the configured server changes.
+
+For standards-based remote MCP OAuth registration, use
+`registerMcpClient()` (Client ID Metadata Document first, executable RFC 7591
+DCR fallback with `application_type`) and follow the
+[remote MCP authorization guide](../../docs/content/architecture/remote-mcp-authorization.md).
 
 ## Public API
 
@@ -101,6 +108,8 @@ surface is typically mounted with
 | `invokeCommand()` | Invoke one generated resource command |
 | `buildFlagParser()` | Convert supported JSON Schema to flags |
 | `loadCliConfig()` / `saveCliConfig()` | Read and write namespaced CLI config |
+| `resolveMcpClientRegistration()` | Inspect the selected Client ID Metadata or DCR path |
+| `registerMcpClient()` | Use Client ID Metadata or execute the DCR fallback |
 
 ## Development
 

package/dist/bin/smrt-mcp-bridge.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { l as runMcpStdioBridge } from "../config-DB4AMYT0.js";
+import { l as runMcpStdioBridge } from "../config-DvxwoFks.js";
 //#region src/bin/smrt-mcp-bridge.ts
 /**
 * `smrt-mcp-bridge` — generic stdio MCP bridge.

package/dist/bridge-D0LJc3mN.js

@@ -0,0 +1,2 @@
+import { l as runMcpStdioBridge } from "./config-DvxwoFks.js";
+export { runMcpStdioBridge };

package/dist/{config-DB4AMYT0.js → config-DvxwoFks.js}

@@ -129,23 +129,41 @@ async function getServerUrl(context, config) {
 	const resolved = config ?? await loadCliConfig(context);
 	return (process.env[`${context.envPrefix}_SERVER_URL`] ?? resolved.serverUrl ?? context.defaultServerUrl ?? DEFAULT_LOCAL_SERVER).replace(/\/+$/u, "");
 }
-/** Resolve the stored bearer token (env var wins over config). */
-async function getStoredToken(context, config) {
+/** Resolve a bearer token only when it is bound to the exact target server. */
+async function getStoredToken(context, config, serverUrl) {
 	const resolved = config ?? await loadCliConfig(context);
-	return process.env[`${context.envPrefix}_TOKEN`] ?? resolved.token;
+	const targetServer = (serverUrl ?? await getServerUrl(context, resolved)).replace(/\/+$/u, "");
+	const environmentToken = process.env[`${context.envPrefix}_TOKEN`];
+	const environmentServer = process.env[`${context.envPrefix}_SERVER_URL`]?.replace(/\/+$/u, "");
+	if (environmentToken) return environmentServer === targetServer ? environmentToken : void 0;
+	const configuredServer = resolved.serverUrl?.replace(/\/+$/u, "");
+	if (!configuredServer || configuredServer !== targetServer) return void 0;
+	if (resolved.credentialIssuer) return resolved.tokensByIssuer?.[resolved.credentialIssuer];
+	return resolved.token;
 }
 /** Remove the token from the config file (e.g. on logout). */
 async function clearStoredToken(context) {
 	const config = await loadCliConfig(context);
+	if (config.credentialIssuer && config.tokensByIssuer) {
+		delete config.tokensByIssuer[config.credentialIssuer];
+		if (Object.keys(config.tokensByIssuer).length === 0) delete config.tokensByIssuer;
+	}
+	delete config.credentialIssuer;
 	delete config.token;
 	await saveCliConfig(context, config);
 }
-/** Persist a login: writes both serverUrl and token to the config file. */
-async function saveAuth(context, serverUrl, token) {
+/** Persist a login with the bearer token keyed by its exact issuer. */
+async function saveAuth(context, serverUrl, token, issuer = serverUrl) {
+	const config = await loadCliConfig(context);
+	const normalizedServerUrl = serverUrl.replace(/\/+$/u, "");
+	if (!issuer.trim()) throw new Error("Credential issuer must not be empty.");
+	const exactIssuer = issuer;
 	await saveCliConfig(context, {
-		...await loadCliConfig(context),
-		serverUrl: serverUrl.replace(/\/+$/u, ""),
-		token
+		...config,
+		credentialIssuer: exactIssuer,
+		serverUrl: normalizedServerUrl,
+		token: void 0,
+		tokensByIssuer: { [exactIssuer]: token }
 	});
 }
 var DEFAULT_MAX_RESPONSE_BYTES = 10 * 1024 * 1024;
@@ -157,7 +175,7 @@ var DEFAULT_MAX_RESPONSE_BYTES = 10 * 1024 * 1024;
 async function requestJson(context, path, init = {}, options = {}) {
 	const config = options.loadedConfig ?? await loadCliConfig(context);
 	const serverUrl = (options.serverUrl ?? await getServerUrl(context, config)).replace(/\/+$/u, "");
-	const token = await getStoredToken(context, config);
+	const token = await getStoredToken(context, config, serverUrl);
 	const headers = new Headers(init.headers);
 	if (options.requireAuth && options.auth !== false && !token) throw new Error(`Not authenticated. Run \`${context.envPrefix.toLowerCase()} auth login\` first.`);
 	if (!headers.has("content-type") && init.body) headers.set("content-type", "application/json");

package/dist/index.d.ts

@@ -68,8 +68,13 @@ export declare function clearStoredToken(context: CliConfigContext): Promise<voi
 
 /** Shape stored on disk in the app's CLI config file. */
 export declare interface CliConfig {
+    /** Issuer selected for the currently configured server. */
+    credentialIssuer?: string;
     serverUrl?: string;
+    /** Legacy single-token field. Read only when its stored server still matches. */
     token?: string;
+    /** Bearer credentials keyed by their exact issuer identifier. */
+    tokensByIssuer?: Record<string, string>;
 }
 
 /**
@@ -166,6 +171,9 @@ export declare interface CreateAppCliOptions {
     extraCommands?: AppCliCommand[];
 }
 
+/** Build and validate the document hosted at an HTTPS URL used as client_id. */
+export declare function createMcpClientIdMetadataDocument(options: McpClientRegistrationOptions): McpClientIdMetadataDocument;
+
 /**
  * Wire up the stdio server. Use `runMcpStdioBridge` for a one-call entry
  * point in `bin/` scripts; this lower-level form is exposed for tests.
@@ -212,8 +220,8 @@ export declare function findResourceBySlug(response: ResourceListResponse, slug:
 /** Resolve the server URL: env var → config file → `defaultServerUrl`. */
 export declare function getServerUrl(context: CliConfigContext, config?: CliConfig): Promise<string>;
 
-/** Resolve the stored bearer token (env var wins over config). */
-export declare function getStoredToken(context: CliConfigContext, config?: CliConfig): Promise<string | undefined>;
+/** Resolve a bearer token only when it is bound to the exact target server. */
+export declare function getStoredToken(context: CliConfigContext, config?: CliConfig, serverUrl?: string): Promise<string | undefined>;
 
 /**
  * Build the URL the CLI should hit for this command, plus the fetch init
@@ -236,6 +244,41 @@ declare interface InvokeOptions {
 /** Read the CLI config file. Missing file → empty config. */
 export declare function loadCliConfig(context: CliConfigContext): Promise<CliConfig>;
 
+export declare interface McpClientIdMetadataDocument {
+    application_type: OAuthApplicationType;
+    client_id: string;
+    client_name: string;
+    grant_types: ['authorization_code'];
+    redirect_uris: string[];
+    response_types: ['code'];
+    token_endpoint_auth_method: 'none';
+}
+
+export declare type McpClientRegistration = {
+    clientId: string;
+    kind: 'client_id_metadata_document';
+    metadataDocument: McpClientIdMetadataDocument;
+} | {
+    endpoint: string;
+    kind: 'dynamic_client_registration';
+    request: Omit<McpClientIdMetadataDocument, 'client_id'>;
+};
+
+export declare interface McpClientRegistrationOptions {
+    applicationType: OAuthApplicationType;
+    /** HTTPS metadata-document URL. Required only when CIMD is advertised. */
+    clientId?: string;
+    clientName: string;
+    redirectUris: string[];
+}
+
+export declare interface McpRegisteredClient {
+    clientId: string;
+    kind: McpClientRegistration['kind'];
+    metadataDocument?: McpClientIdMetadataDocument;
+    registrationResponse?: Record<string, unknown>;
+}
+
 /**
  * Configuration for the bridge.
  *
@@ -258,6 +301,14 @@ export declare interface McpStdioBridgeOptions extends CliConfigContext {
     fetch?: typeof fetch;
 }
 
+/** MCP OAuth client-registration helpers for remote HTTP deployments. */
+export declare type OAuthApplicationType = 'native' | 'web';
+
+export declare interface OAuthAuthorizationServerMetadata {
+    client_id_metadata_document_supported?: boolean;
+    registration_endpoint?: string;
+}
+
 declare interface OutputOptions {
     stdout?: NodeJS.WriteStream | Writable;
     stderr?: NodeJS.WriteStream | Writable;
@@ -281,6 +332,14 @@ declare interface ParserOptions {
     positionalOnly?: boolean;
 }
 
+/**
+ * Complete client registration against discovered authorization-server
+ * metadata. A Client ID Metadata Document needs no registration request: the
+ * authorization server retrieves it from the HTTPS client_id. The legacy DCR
+ * fallback is executed as an RFC 7591 JSON POST.
+ */
+export declare function registerMcpClient(authorizationServer: OAuthAuthorizationServerMetadata, options: McpClientRegistrationOptions, fetchImpl?: typeof fetch): Promise<McpRegisteredClient>;
+
 /**
  * Render the response. Returns the desired exit code.
  */
@@ -331,6 +390,12 @@ export declare interface RequestJsonOptions {
     loadedConfig?: CliConfig;
 }
 
+/**
+ * Select registration in MCP priority order: Client ID Metadata Documents
+ * first, then RFC 7591 DCR as a compatibility fallback.
+ */
+export declare function resolveMcpClientRegistration(authorizationServer: OAuthAuthorizationServerMetadata, options: McpClientRegistrationOptions): McpClientRegistration;
+
 export declare type ResourceListResponse = ResourceListResponseBody;
 
 declare interface ResourceListResponseBody {
@@ -348,8 +413,8 @@ declare interface ResourceListResponseBody {
  */
 export declare function runMcpStdioBridge(options: McpStdioBridgeOptions): Promise<void>;
 
-/** Persist a login: writes both serverUrl and token to the config file. */
-export declare function saveAuth(context: CliConfigContext, serverUrl: string, token: string): Promise<void>;
+/** Persist a login with the bearer token keyed by its exact issuer. */
+export declare function saveAuth(context: CliConfigContext, serverUrl: string, token: string, issuer?: string): Promise<void>;
 
 /**
  * Write the CLI config to disk with 0600 permissions (the token is a bearer

package/dist/index.js

@@ -1,4 +1,4 @@
-import { a as requestJson, c as createMcpStdioBridge, i as loadCliConfig, l as runMcpStdioBridge, n as getServerUrl, o as saveAuth, r as getStoredToken, s as saveCliConfig, t as clearStoredToken } from "./config-DB4AMYT0.js";
+import { a as requestJson, c as createMcpStdioBridge, i as loadCliConfig, l as runMcpStdioBridge, n as getServerUrl, o as saveAuth, r as getStoredToken, s as saveCliConfig, t as clearStoredToken } from "./config-DvxwoFks.js";
 import { spawn, spawnSync } from "node:child_process";
 //#region src/discovery.ts
 /**
@@ -91,6 +91,79 @@ function splitPath(s) {
 	return s.split("/").filter((p) => p.length > 0);
 }
 //#endregion
+//#region src/mcp-oauth.ts
+function createMcpRegistrationRequest(options) {
+	if (!options.clientName.trim()) throw new Error("MCP client_name must not be empty.");
+	if (options.redirectUris.length === 0) throw new Error("MCP client metadata requires at least one redirect URI.");
+	for (const redirectUri of options.redirectUris) new URL(redirectUri);
+	return {
+		application_type: options.applicationType,
+		client_name: options.clientName,
+		grant_types: ["authorization_code"],
+		redirect_uris: [...options.redirectUris],
+		response_types: ["code"],
+		token_endpoint_auth_method: "none"
+	};
+}
+/** Build and validate the document hosted at an HTTPS URL used as client_id. */
+function createMcpClientIdMetadataDocument(options) {
+	if (!options.clientId) throw new Error("MCP client_id metadata URL is required for CIMD.");
+	const clientId = new URL(options.clientId);
+	if (clientId.protocol !== "https:" || clientId.pathname === "/") throw new Error("MCP client_id metadata URL must use HTTPS and include a path.");
+	if (clientId.search || clientId.hash) throw new Error("MCP client_id metadata URL must not include query or fragment.");
+	return {
+		...createMcpRegistrationRequest(options),
+		client_id: options.clientId
+	};
+}
+/**
+* Select registration in MCP priority order: Client ID Metadata Documents
+* first, then RFC 7591 DCR as a compatibility fallback.
+*/
+function resolveMcpClientRegistration(authorizationServer, options) {
+	if (authorizationServer.client_id_metadata_document_supported === true) {
+		const metadataDocument = createMcpClientIdMetadataDocument(options);
+		return {
+			clientId: metadataDocument.client_id,
+			kind: "client_id_metadata_document",
+			metadataDocument
+		};
+	}
+	if (authorizationServer.registration_endpoint) return {
+		endpoint: authorizationServer.registration_endpoint,
+		kind: "dynamic_client_registration",
+		request: createMcpRegistrationRequest(options)
+	};
+	throw new Error("Authorization server supports neither Client ID Metadata Documents nor dynamic client registration.");
+}
+/**
+* Complete client registration against discovered authorization-server
+* metadata. A Client ID Metadata Document needs no registration request: the
+* authorization server retrieves it from the HTTPS client_id. The legacy DCR
+* fallback is executed as an RFC 7591 JSON POST.
+*/
+async function registerMcpClient(authorizationServer, options, fetchImpl = fetch) {
+	const registration = resolveMcpClientRegistration(authorizationServer, options);
+	if (registration.kind === "client_id_metadata_document") return {
+		clientId: registration.clientId,
+		kind: registration.kind,
+		metadataDocument: registration.metadataDocument
+	};
+	const response = await fetchImpl(registration.endpoint, {
+		body: JSON.stringify(registration.request),
+		headers: { "content-type": "application/json" },
+		method: "POST"
+	});
+	if (!response.ok) throw new Error(`Dynamic client registration failed: HTTP ${response.status}`);
+	const body = await response.json();
+	if (typeof body !== "object" || body === null || typeof body.client_id !== "string" || !body.client_id) throw new Error("Dynamic client registration response omitted client_id.");
+	return {
+		clientId: body.client_id,
+		kind: registration.kind,
+		registrationResponse: body
+	};
+}
+//#endregion
 //#region src/output.ts
 var JSON_BUFFER_LIMIT = 10 * 1024 * 1024;
 /**
@@ -558,7 +631,7 @@ async function runAuthLogin(options, args) {
 				serverUrl: targetServer
 			});
 			if (token.status === "approved" && token.accessToken) {
-				await saveAuth(options.context, targetServer, token.accessToken);
+				await saveAuth(options.context, targetServer, token.accessToken, start.issuer ?? targetServer);
 				stdout.write(`Authenticated to ${targetServer}\n`);
 				return;
 			}
@@ -774,7 +847,7 @@ function createAppCli(options) {
 	return {
 		run: (argv) => runCli(context, options, extraByName, argv),
 		startMcpBridge: async (serverInfo) => {
-			const { runMcpStdioBridge } = await import("./bridge-sTKlA6Hz.js");
+			const { runMcpStdioBridge } = await import("./bridge-D0LJc3mN.js");
 			await runMcpStdioBridge({
 				...context,
 				serverInfo: {
@@ -927,4 +1000,4 @@ function similar(a, b) {
 	return true;
 }
 //#endregion
-export { buildFlagParser, buildUrl, classifySchema, clearStoredToken, createAppCli, createMcpStdioBridge, fetchResourceList, findCommand, findResourceBySlug, getServerUrl, getStoredToken, invokeCommand, loadCliConfig, renderResponse, requestJson, runMcpStdioBridge, saveAuth, saveCliConfig };
+export { buildFlagParser, buildUrl, classifySchema, clearStoredToken, createAppCli, createMcpClientIdMetadataDocument, createMcpStdioBridge, fetchResourceList, findCommand, findResourceBySlug, getServerUrl, getStoredToken, invokeCommand, loadCliConfig, registerMcpClient, renderResponse, requestJson, resolveMcpClientRegistration, runMcpStdioBridge, saveAuth, saveCliConfig };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@happyvertical/smrt-app-cli",
-  "version": "0.40.48",
+  "version": "0.40.50",
   "description": "Reusable CLI factory for SMRT apps — branded `<name> <resource> <command>` CLI + stdio MCP bridge with decorator-driven resource discovery",
   "type": "module",
   "main": "./dist/index.js",
@@ -21,7 +21,7 @@
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.25.2",
-    "@happyvertical/smrt-users": "0.40.48"
+    "@happyvertical/smrt-users": "0.40.50"
   },
   "devDependencies": {
     "@types/node": "24.13.2",
@@ -29,7 +29,7 @@
     "vite": "8.1.4",
     "vite-plugin-dts": "4.5.4",
     "vitest": "4.1.10",
-    "@happyvertical/smrt-core": "0.40.48"
+    "@happyvertical/smrt-core": "0.40.50"
   },
   "engines": {
     "node": ">=24.18.0"

package/dist/bridge-sTKlA6Hz.js

@@ -1,2 +0,0 @@
-import { l as runMcpStdioBridge } from "./config-DB4AMYT0.js";
-export { runMcpStdioBridge };