@adcp/sdk 5.23.0

package/dist/lib/auth/oauth/file-storage.js

@@ -0,0 +1,112 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createFileOAuthStorage = createFileOAuthStorage;
+/**
+ * File-backed {@link OAuthConfigStorage} implementation.
+ *
+ * Persists refreshed OAuth tokens back to a JSON file so that subsequent
+ * `callTool` invocations use the latest access + refresh tokens without
+ * triggering a redundant refresh (or worse, a re-login).
+ *
+ * On-disk format is the shape used by the `adcp` CLI's agents.json — agents
+ * keyed by alias, each with `{ url, protocol, auth_token?, oauth_tokens?, oauth_client? }`.
+ * Library consumers who want a different shape can implement
+ * {@link OAuthConfigStorage} directly.
+ */
+const fs_1 = require("fs");
+const path_1 = __importDefault(require("path"));
+const crypto_1 = require("crypto");
+/**
+ * Create a file-backed `OAuthConfigStorage`.
+ *
+ * Reads are cheap: a single JSON.parse per call. Writes are atomic via
+ * `write-then-rename` so a crash mid-save cannot produce a half-written file.
+ *
+ * Does NOT touch fields outside the OAuth envelope (`auth_token`, custom
+ * fields) when saving — the MCP provider only mutates `oauth_tokens`,
+ * `oauth_client`, and `oauth_code_verifier`, and we preserve everything else.
+ *
+ * @example
+ * ```ts
+ * const storage = createFileOAuthStorage({ configPath: '/home/user/.adcp/config.json' });
+ * const provider = createNonInteractiveOAuthProvider(agent, { storage });
+ * ```
+ */
+function createFileOAuthStorage(options) {
+    const configPath = options.configPath;
+    const agentKeyOverride = options.agentKey;
+    const autoCreateDir = options.autoCreateDir ?? true;
+    const fileMode = options.fileMode ?? 0o600;
+    async function readConfig() {
+        try {
+            const raw = await fs_1.promises.readFile(configPath, 'utf-8');
+            const parsed = JSON.parse(raw);
+            if (!parsed.agents || typeof parsed.agents !== 'object')
+                parsed.agents = {};
+            return parsed;
+        }
+        catch (err) {
+            if (isNotFound(err))
+                return { agents: {} };
+            throw err;
+        }
+    }
+    async function writeConfig(config) {
+        if (autoCreateDir) {
+            await fs_1.promises.mkdir(path_1.default.dirname(configPath), { recursive: true, mode: 0o700 });
+        }
+        // Atomic write: stage next to the target, then rename. Same filesystem →
+        // rename is atomic on POSIX and on NTFS (MoveFileEx under the hood).
+        // Random suffix guards against two concurrent saves in the same process
+        // racing on the same temp path.
+        const tempPath = `${configPath}.${process.pid}.${(0, crypto_1.randomBytes)(4).toString('hex')}.tmp`;
+        const serialized = JSON.stringify(config, null, 2);
+        await fs_1.promises.writeFile(tempPath, serialized, { mode: fileMode });
+        await fs_1.promises.rename(tempPath, configPath);
+    }
+    return {
+        async loadAgent(agentId) {
+            const key = agentKeyOverride ?? agentId;
+            const config = await readConfig();
+            const stored = config.agents[key];
+            if (!stored)
+                return undefined;
+            return {
+                id: agentId,
+                name: agentId,
+                agent_uri: stored.url,
+                protocol: stored.protocol ?? 'mcp',
+                auth_token: stored.auth_token,
+                oauth_tokens: stored.oauth_tokens,
+                oauth_client: stored.oauth_client,
+                oauth_client_credentials: stored.oauth_client_credentials,
+                oauth_code_verifier: stored.oauth_code_verifier,
+            };
+        },
+        async saveAgent(agent) {
+            const key = agentKeyOverride ?? agent.id;
+            const config = await readConfig();
+            const existing = config.agents[key] ?? { url: agent.agent_uri };
+            config.agents[key] = {
+                ...existing,
+                url: agent.agent_uri,
+                protocol: agent.protocol,
+                ...(agent.auth_token !== undefined ? { auth_token: agent.auth_token } : {}),
+                ...(agent.oauth_tokens !== undefined ? { oauth_tokens: agent.oauth_tokens } : {}),
+                ...(agent.oauth_client !== undefined ? { oauth_client: agent.oauth_client } : {}),
+                ...(agent.oauth_client_credentials !== undefined
+                    ? { oauth_client_credentials: agent.oauth_client_credentials }
+                    : {}),
+                ...(agent.oauth_code_verifier !== undefined ? { oauth_code_verifier: agent.oauth_code_verifier } : {}),
+            };
+            await writeConfig(config);
+        },
+    };
+}
+function isNotFound(err) {
+    return Boolean(err && typeof err === 'object' && err.code === 'ENOENT');
+}
+//# sourceMappingURL=file-storage.js.map

package/dist/lib/auth/oauth/file-storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-storage.js","sourceRoot":"","sources":["../../../../src/lib/auth/oauth/file-storage.ts"],"names":[],"mappings":"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"}

package/dist/lib/auth/oauth/index.d.ts

@@ -0,0 +1,133 @@
+/**
+ * OAuth module for MCP authentication
+ *
+ * OAuth tokens are stored directly in AgentConfig, same as static auth tokens.
+ *
+ * @example
+ * ```typescript
+ * import { MCPOAuthProvider, CLIFlowHandler } from '@adcp/sdk';
+ *
+ * // Agent config - tokens will be stored here
+ * const agent: AgentConfig = {
+ *   id: 'my-agent',
+ *   name: 'My Agent',
+ *   agent_uri: 'https://agent.example.com/mcp',
+ *   protocol: 'mcp',
+ *   // After OAuth flow completes:
+ *   // oauth_tokens: { access_token: '...', refresh_token: '...' }
+ * };
+ *
+ * // Create provider with CLI flow handler
+ * const provider = new MCPOAuthProvider({
+ *   agent,
+ *   flowHandler: new CLIFlowHandler(),
+ *   storage: myConfigStorage  // Optional: persists tokens to file/db
+ * });
+ *
+ * // Use with MCP transport
+ * const transport = new StreamableHTTPClientTransport(url, {
+ *   authProvider: provider
+ * });
+ * ```
+ */
+export type { OAuthFlowHandler, OAuthProviderConfig, OAuthConfigStorage, OAuthClientInformation, OAuthClientInformationFull, OAuthClientMetadata, OAuthTokens, AgentConfig, AgentOAuthTokens, AgentOAuthClient, } from './types';
+export { DEFAULT_CLIENT_METADATA, OAuthError, OAuthCancelledError, OAuthTimeoutError, toMCPTokens, fromMCPTokens, toMCPClientInfo, fromMCPClientInfo, } from './types';
+export { CLIFlowHandler, type CLIFlowHandlerConfig } from './CLIFlowHandler';
+export { NonInteractiveFlowHandler, type NonInteractiveFlowHandlerConfig } from './NonInteractiveFlowHandler';
+export { MCPOAuthProvider } from './MCPOAuthProvider';
+import { MCPOAuthProvider } from './MCPOAuthProvider';
+import type { OAuthClientMetadata, OAuthConfigStorage, AgentConfig } from './types';
+/**
+ * Create an OAuth provider for CLI usage
+ *
+ * @param agent Agent configuration (tokens stored here)
+ * @param options Optional configuration
+ * @returns Configured OAuth provider
+ *
+ * @example
+ * ```typescript
+ * const agent: AgentConfig = {
+ *   id: 'my-agent',
+ *   name: 'My Agent',
+ *   agent_uri: 'https://agent.example.com/mcp',
+ *   protocol: 'mcp'
+ * };
+ *
+ * const provider = createCLIOAuthProvider(agent);
+ *
+ * const transport = new StreamableHTTPClientTransport(url, {
+ *   authProvider: provider
+ * });
+ *
+ * try {
+ *   await client.connect(transport);
+ * } catch (error) {
+ *   if (error instanceof UnauthorizedError) {
+ *     const code = await provider.waitForCallback();
+ *     await transport.finishAuth(code);
+ *     await client.connect(transport);
+ *   }
+ * }
+ *
+ * // After successful auth, agent.oauth_tokens is populated
+ * console.log(agent.oauth_tokens);
+ * ```
+ */
+export declare function createCLIOAuthProvider(agent: AgentConfig, options?: {
+    /** Callback port (default: 8766) */
+    callbackPort?: number;
+    /** Auth timeout in ms (default: 300000 = 5 min) */
+    timeout?: number;
+    /** Custom client metadata overrides */
+    clientMetadata?: Partial<OAuthClientMetadata>;
+    /** Suppress console output */
+    quiet?: boolean;
+    /** Storage for persisting agent config */
+    storage?: OAuthConfigStorage;
+}): MCPOAuthProvider;
+/**
+ * Create an OAuth provider that uses and auto-refreshes saved tokens but
+ * refuses to start a new interactive browser flow. Use this for storyboard
+ * runs, scheduled jobs, and other non-interactive contexts where you've
+ * already saved tokens via `createCLIOAuthProvider`.
+ *
+ * If refresh fails (e.g., the refresh_token is revoked or expired), the
+ * MCP SDK will throw `UnauthorizedError` at call time — the caller should
+ * treat that as a signal to run `adcp --save-auth <alias> --oauth` and retry.
+ */
+export declare function createNonInteractiveOAuthProvider(agent: AgentConfig, options?: {
+    /** Hint shown in error messages if an interactive flow is attempted. */
+    agentHint?: string;
+    /** Custom client metadata overrides (inherited from saved registration in practice). */
+    clientMetadata?: Partial<OAuthClientMetadata>;
+    /** Storage for persisting refreshed tokens back to disk. */
+    storage?: OAuthConfigStorage;
+}): MCPOAuthProvider;
+/**
+ * Check if an error indicates OAuth is required
+ */
+export declare function isOAuthRequired(error: unknown): boolean;
+/**
+ * Check if an agent has valid OAuth tokens
+ */
+export declare function hasValidOAuthTokens(agent: AgentConfig): boolean;
+/**
+ * Clear OAuth tokens from an agent config
+ */
+export declare function clearOAuthTokens(agent: AgentConfig): void;
+/**
+ * Get the effective auth token for an agent
+ * Returns OAuth access_token if available, otherwise static auth_token
+ */
+export declare function getEffectiveAuthToken(agent: AgentConfig): string | undefined;
+export { discoverOAuthMetadata, supportsOAuth, supportsDynamicRegistration, type OAuthMetadata, type DiscoveryOptions, } from './discovery';
+export { parseWWWAuthenticate, decodeAccessTokenClaims, validateTokenAudience, type WWWAuthenticateChallenge, type DecodedJWTHeader, type DecodedJWTClaims, type DecodedAccessToken, type TokenAudienceResult, } from './diagnostics';
+export { runAuthDiagnosis, AUTH_DIAGNOSIS_SCHEMA_VERSION, type DiagnoseOptions, type HttpCapture, type DiagnosisStep, type Hypothesis, type HypothesisVerdict, type AuthDiagnosisReport, } from './diagnose';
+export { NeedsAuthorizationError, discoverAuthorizationRequirements, type AuthorizationRequirements, type DiscoverAuthorizationOptions, } from './authorization-required';
+export { createFileOAuthStorage, type FileOAuthStorageOptions } from './file-storage';
+export { exchangeClientCredentials, ensureClientCredentialsTokens, ClientCredentialsExchangeError, type ExchangeClientCredentialsOptions, type EnsureClientCredentialsOptions, } from './ClientCredentialsFlow';
+export { resolveSecret, isEnvSecretReference, toEnvSecretReference, extractEnvSecretName, MissingEnvSecretError, } from './secret-resolver';
+export type { AgentOAuthClientCredentials } from '../../types/adcp';
+export { bindAgentStorage, getAgentStorage, unbindAgentStorage } from './storage-registry';
+export { InvalidTokenError, InsufficientScopeError } from '@modelcontextprotocol/sdk/server/auth/errors.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/auth/oauth/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/lib/auth/oauth/index.ts"],"names":[],"mappings":"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"}

package/dist/lib/auth/oauth/index.js

@@ -0,0 +1,246 @@
+"use strict";
+/**
+ * OAuth module for MCP authentication
+ *
+ * OAuth tokens are stored directly in AgentConfig, same as static auth tokens.
+ *
+ * @example
+ * ```typescript
+ * import { MCPOAuthProvider, CLIFlowHandler } from '@adcp/sdk';
+ *
+ * // Agent config - tokens will be stored here
+ * const agent: AgentConfig = {
+ *   id: 'my-agent',
+ *   name: 'My Agent',
+ *   agent_uri: 'https://agent.example.com/mcp',
+ *   protocol: 'mcp',
+ *   // After OAuth flow completes:
+ *   // oauth_tokens: { access_token: '...', refresh_token: '...' }
+ * };
+ *
+ * // Create provider with CLI flow handler
+ * const provider = new MCPOAuthProvider({
+ *   agent,
+ *   flowHandler: new CLIFlowHandler(),
+ *   storage: myConfigStorage  // Optional: persists tokens to file/db
+ * });
+ *
+ * // Use with MCP transport
+ * const transport = new StreamableHTTPClientTransport(url, {
+ *   authProvider: provider
+ * });
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InsufficientScopeError = exports.InvalidTokenError = exports.unbindAgentStorage = exports.getAgentStorage = exports.bindAgentStorage = exports.MissingEnvSecretError = exports.extractEnvSecretName = exports.toEnvSecretReference = exports.isEnvSecretReference = exports.resolveSecret = exports.ClientCredentialsExchangeError = exports.ensureClientCredentialsTokens = exports.exchangeClientCredentials = exports.createFileOAuthStorage = exports.discoverAuthorizationRequirements = exports.NeedsAuthorizationError = exports.AUTH_DIAGNOSIS_SCHEMA_VERSION = exports.runAuthDiagnosis = exports.validateTokenAudience = exports.decodeAccessTokenClaims = exports.parseWWWAuthenticate = exports.supportsDynamicRegistration = exports.supportsOAuth = exports.discoverOAuthMetadata = exports.MCPOAuthProvider = exports.NonInteractiveFlowHandler = exports.CLIFlowHandler = exports.fromMCPClientInfo = exports.toMCPClientInfo = exports.fromMCPTokens = exports.toMCPTokens = exports.OAuthTimeoutError = exports.OAuthCancelledError = exports.OAuthError = exports.DEFAULT_CLIENT_METADATA = void 0;
+exports.createCLIOAuthProvider = createCLIOAuthProvider;
+exports.createNonInteractiveOAuthProvider = createNonInteractiveOAuthProvider;
+exports.isOAuthRequired = isOAuthRequired;
+exports.hasValidOAuthTokens = hasValidOAuthTokens;
+exports.clearOAuthTokens = clearOAuthTokens;
+exports.getEffectiveAuthToken = getEffectiveAuthToken;
+var types_1 = require("./types");
+Object.defineProperty(exports, "DEFAULT_CLIENT_METADATA", { enumerable: true, get: function () { return types_1.DEFAULT_CLIENT_METADATA; } });
+Object.defineProperty(exports, "OAuthError", { enumerable: true, get: function () { return types_1.OAuthError; } });
+Object.defineProperty(exports, "OAuthCancelledError", { enumerable: true, get: function () { return types_1.OAuthCancelledError; } });
+Object.defineProperty(exports, "OAuthTimeoutError", { enumerable: true, get: function () { return types_1.OAuthTimeoutError; } });
+Object.defineProperty(exports, "toMCPTokens", { enumerable: true, get: function () { return types_1.toMCPTokens; } });
+Object.defineProperty(exports, "fromMCPTokens", { enumerable: true, get: function () { return types_1.fromMCPTokens; } });
+Object.defineProperty(exports, "toMCPClientInfo", { enumerable: true, get: function () { return types_1.toMCPClientInfo; } });
+Object.defineProperty(exports, "fromMCPClientInfo", { enumerable: true, get: function () { return types_1.fromMCPClientInfo; } });
+// Flow handlers
+var CLIFlowHandler_1 = require("./CLIFlowHandler");
+Object.defineProperty(exports, "CLIFlowHandler", { enumerable: true, get: function () { return CLIFlowHandler_1.CLIFlowHandler; } });
+var NonInteractiveFlowHandler_1 = require("./NonInteractiveFlowHandler");
+Object.defineProperty(exports, "NonInteractiveFlowHandler", { enumerable: true, get: function () { return NonInteractiveFlowHandler_1.NonInteractiveFlowHandler; } });
+// Main provider
+var MCPOAuthProvider_1 = require("./MCPOAuthProvider");
+Object.defineProperty(exports, "MCPOAuthProvider", { enumerable: true, get: function () { return MCPOAuthProvider_1.MCPOAuthProvider; } });
+// ========================================
+// Convenience factory functions
+// ========================================
+const MCPOAuthProvider_2 = require("./MCPOAuthProvider");
+const CLIFlowHandler_2 = require("./CLIFlowHandler");
+const types_2 = require("./types");
+/**
+ * Create an OAuth provider for CLI usage
+ *
+ * @param agent Agent configuration (tokens stored here)
+ * @param options Optional configuration
+ * @returns Configured OAuth provider
+ *
+ * @example
+ * ```typescript
+ * const agent: AgentConfig = {
+ *   id: 'my-agent',
+ *   name: 'My Agent',
+ *   agent_uri: 'https://agent.example.com/mcp',
+ *   protocol: 'mcp'
+ * };
+ *
+ * const provider = createCLIOAuthProvider(agent);
+ *
+ * const transport = new StreamableHTTPClientTransport(url, {
+ *   authProvider: provider
+ * });
+ *
+ * try {
+ *   await client.connect(transport);
+ * } catch (error) {
+ *   if (error instanceof UnauthorizedError) {
+ *     const code = await provider.waitForCallback();
+ *     await transport.finishAuth(code);
+ *     await client.connect(transport);
+ *   }
+ * }
+ *
+ * // After successful auth, agent.oauth_tokens is populated
+ * console.log(agent.oauth_tokens);
+ * ```
+ */
+function createCLIOAuthProvider(agent, options) {
+    const flowConfig = {
+        callbackPort: options?.callbackPort,
+        timeout: options?.timeout,
+        quiet: options?.quiet,
+    };
+    const flowHandler = new CLIFlowHandler_2.CLIFlowHandler(flowConfig);
+    // Build complete client metadata
+    const clientMetadata = {
+        ...types_2.DEFAULT_CLIENT_METADATA,
+        redirect_uris: [flowHandler.getRedirectUrl().toString()],
+        ...options?.clientMetadata,
+    };
+    return new MCPOAuthProvider_2.MCPOAuthProvider({
+        agent,
+        flowHandler,
+        storage: options?.storage,
+        clientMetadata,
+    });
+}
+/**
+ * Create an OAuth provider that uses and auto-refreshes saved tokens but
+ * refuses to start a new interactive browser flow. Use this for storyboard
+ * runs, scheduled jobs, and other non-interactive contexts where you've
+ * already saved tokens via `createCLIOAuthProvider`.
+ *
+ * If refresh fails (e.g., the refresh_token is revoked or expired), the
+ * MCP SDK will throw `UnauthorizedError` at call time — the caller should
+ * treat that as a signal to run `adcp --save-auth <alias> --oauth` and retry.
+ */
+function createNonInteractiveOAuthProvider(agent, options) {
+    const { NonInteractiveFlowHandler } = require('./NonInteractiveFlowHandler');
+    const flowHandler = new NonInteractiveFlowHandler({ agentHint: options?.agentHint });
+    const clientMetadata = {
+        ...types_2.DEFAULT_CLIENT_METADATA,
+        redirect_uris: [flowHandler.getRedirectUrl().toString()],
+        ...options?.clientMetadata,
+    };
+    return new MCPOAuthProvider_2.MCPOAuthProvider({
+        agent,
+        flowHandler,
+        storage: options?.storage,
+        clientMetadata,
+    });
+}
+/**
+ * Check if an error indicates OAuth is required
+ */
+function isOAuthRequired(error) {
+    if (error instanceof Error) {
+        if (error.name === 'UnauthorizedError')
+            return true;
+        const msg = error.message.toLowerCase();
+        if (msg.includes('unauthorized') || msg.includes('authentication required') || msg.includes('oauth')) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Check if an agent has valid OAuth tokens
+ */
+function hasValidOAuthTokens(agent) {
+    const tokens = agent.oauth_tokens;
+    if (!tokens?.access_token)
+        return false;
+    if (tokens.expires_at) {
+        const expiresAt = new Date(tokens.expires_at);
+        // Expired if within 5 minutes of expiration
+        if (expiresAt.getTime() - Date.now() < 5 * 60 * 1000) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Clear OAuth tokens from an agent config
+ */
+function clearOAuthTokens(agent) {
+    delete agent.oauth_tokens;
+    delete agent.oauth_client;
+    delete agent.oauth_code_verifier;
+}
+/**
+ * Get the effective auth token for an agent
+ * Returns OAuth access_token if available, otherwise static auth_token
+ */
+function getEffectiveAuthToken(agent) {
+    // Prefer OAuth if available and valid
+    if (hasValidOAuthTokens(agent)) {
+        return agent.oauth_tokens.access_token;
+    }
+    // Fall back to static token
+    return agent.auth_token;
+}
+// OAuth discovery
+var discovery_1 = require("./discovery");
+Object.defineProperty(exports, "discoverOAuthMetadata", { enumerable: true, get: function () { return discovery_1.discoverOAuthMetadata; } });
+Object.defineProperty(exports, "supportsOAuth", { enumerable: true, get: function () { return discovery_1.supportsOAuth; } });
+Object.defineProperty(exports, "supportsDynamicRegistration", { enumerable: true, get: function () { return discovery_1.supportsDynamicRegistration; } });
+// Diagnostics utilities — for `adcp diagnose-auth` and consumer introspection
+var diagnostics_1 = require("./diagnostics");
+Object.defineProperty(exports, "parseWWWAuthenticate", { enumerable: true, get: function () { return diagnostics_1.parseWWWAuthenticate; } });
+Object.defineProperty(exports, "decodeAccessTokenClaims", { enumerable: true, get: function () { return diagnostics_1.decodeAccessTokenClaims; } });
+Object.defineProperty(exports, "validateTokenAudience", { enumerable: true, get: function () { return diagnostics_1.validateTokenAudience; } });
+// End-to-end OAuth handshake diagnosis (powers `adcp diagnose-auth`)
+var diagnose_1 = require("./diagnose");
+Object.defineProperty(exports, "runAuthDiagnosis", { enumerable: true, get: function () { return diagnose_1.runAuthDiagnosis; } });
+Object.defineProperty(exports, "AUTH_DIAGNOSIS_SCHEMA_VERSION", { enumerable: true, get: function () { return diagnose_1.AUTH_DIAGNOSIS_SCHEMA_VERSION; } });
+// Zero-config authorization discovery + actionable error type.
+// Raised automatically by `ProtocolClient.callTool` when an MCP agent returns
+// a 401 Bearer challenge and the caller has no saved tokens.
+var authorization_required_1 = require("./authorization-required");
+Object.defineProperty(exports, "NeedsAuthorizationError", { enumerable: true, get: function () { return authorization_required_1.NeedsAuthorizationError; } });
+Object.defineProperty(exports, "discoverAuthorizationRequirements", { enumerable: true, get: function () { return authorization_required_1.discoverAuthorizationRequirements; } });
+// File-backed `OAuthConfigStorage` implementation (agents.json format).
+var file_storage_1 = require("./file-storage");
+Object.defineProperty(exports, "createFileOAuthStorage", { enumerable: true, get: function () { return file_storage_1.createFileOAuthStorage; } });
+// OAuth 2.0 client credentials grant (RFC 6749 §4.4) for machine-to-machine
+// token exchange. Used by the CLI for automated compliance runs where there
+// is no user to walk through an authorization-code flow.
+var ClientCredentialsFlow_1 = require("./ClientCredentialsFlow");
+Object.defineProperty(exports, "exchangeClientCredentials", { enumerable: true, get: function () { return ClientCredentialsFlow_1.exchangeClientCredentials; } });
+Object.defineProperty(exports, "ensureClientCredentialsTokens", { enumerable: true, get: function () { return ClientCredentialsFlow_1.ensureClientCredentialsTokens; } });
+Object.defineProperty(exports, "ClientCredentialsExchangeError", { enumerable: true, get: function () { return ClientCredentialsFlow_1.ClientCredentialsExchangeError; } });
+// `$ENV:VAR` indirection for client credentials so secrets can live in env
+// vars (CI) rather than on disk in the agent config.
+var secret_resolver_1 = require("./secret-resolver");
+Object.defineProperty(exports, "resolveSecret", { enumerable: true, get: function () { return secret_resolver_1.resolveSecret; } });
+Object.defineProperty(exports, "isEnvSecretReference", { enumerable: true, get: function () { return secret_resolver_1.isEnvSecretReference; } });
+Object.defineProperty(exports, "toEnvSecretReference", { enumerable: true, get: function () { return secret_resolver_1.toEnvSecretReference; } });
+Object.defineProperty(exports, "extractEnvSecretName", { enumerable: true, get: function () { return secret_resolver_1.extractEnvSecretName; } });
+Object.defineProperty(exports, "MissingEnvSecretError", { enumerable: true, get: function () { return secret_resolver_1.MissingEnvSecretError; } });
+// Per-agent storage binding — the bridge that lets `callTool` pick up the
+// caller's chosen `OAuthConfigStorage` without a signature change.
+var storage_registry_1 = require("./storage-registry");
+Object.defineProperty(exports, "bindAgentStorage", { enumerable: true, get: function () { return storage_registry_1.bindAgentStorage; } });
+Object.defineProperty(exports, "getAgentStorage", { enumerable: true, get: function () { return storage_registry_1.getAgentStorage; } });
+Object.defineProperty(exports, "unbindAgentStorage", { enumerable: true, get: function () { return storage_registry_1.unbindAgentStorage; } });
+// Re-exported MCP SDK OAuth error types so consumers can discriminate 401 causes
+// without string-matching on error messages. These originate from the MCP server
+// auth module but are the canonical OAuth error classes for client-side handling too.
+var errors_js_1 = require("@modelcontextprotocol/sdk/server/auth/errors.js");
+Object.defineProperty(exports, "InvalidTokenError", { enumerable: true, get: function () { return errors_js_1.InvalidTokenError; } });
+Object.defineProperty(exports, "InsufficientScopeError", { enumerable: true, get: function () { return errors_js_1.InsufficientScopeError; } });
+//# sourceMappingURL=index.js.map

package/dist/lib/auth/oauth/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/lib/auth/oauth/index.ts"],"names":[],"mappings":"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"}

package/dist/lib/auth/oauth/secret-resolver.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Secret resolution for OAuth client credentials.
+ *
+ * Values stored in `AgentOAuthClientCredentials.client_id` /
+ * `client_secret` may be either literal strings or env-var references in
+ * the form `$ENV:VAR_NAME`. Literal secrets end up on disk in
+ * `~/.adcp/config.json` (chmod 600); env-var references stay in the config
+ * but the secret itself is pulled from the environment at token-exchange
+ * time — the CI path where secrets come from the pipeline and should never
+ * hit the filesystem.
+ *
+ * There is no auto-detection: a value without the `$ENV:` prefix is treated
+ * as a literal. The CLI's `--client-secret-env VAR` flag writes the
+ * reference form.
+ */
+/**
+ * Raised when a `$ENV:VAR` reference cannot be resolved. The
+ * {@link reason} discriminator separates "variable not set at all" from
+ * "set to empty string" — the latter is a common CI footgun (`.env` with
+ * `CLIENT_SECRET=`) that deserves a different nudge to the user.
+ */
+export declare class MissingEnvSecretError extends Error {
+    readonly envVar: string;
+    readonly reason: 'unset' | 'empty';
+    readonly code = "missing_env_secret";
+    constructor(envVar: string, reason?: 'unset' | 'empty');
+}
+/**
+ * Resolve a credential value that may be a `$ENV:VAR` reference.
+ *
+ * - Literal strings pass through unchanged.
+ * - `$ENV:VAR` reads `process.env.VAR` and returns it. Throws
+ *   {@link MissingEnvSecretError} with `reason: 'unset'` if the variable
+ *   is not set, and `reason: 'empty'` if it is set to the empty string.
+ *   We treat empty as missing to catch `.env` typos — a compliance run
+ *   should loudly fail rather than silently POST an empty secret.
+ *
+ * Whitespace around the variable name (`$ENV: FOO`) is tolerated — a common
+ * copy/paste mistake that we don't want to punish at runtime.
+ */
+export declare function resolveSecret(value: string): string;
+/** True if `value` is a `$ENV:VAR` reference (not a literal secret). */
+export declare function isEnvSecretReference(value: string): boolean;
+/** Build a `$ENV:VAR` reference string from an env-var name. */
+export declare function toEnvSecretReference(envVar: string): string;
+/**
+ * Extract the env-var name from a `$ENV:VAR` reference, or `null` if the
+ * value is a literal secret. Safe to display: the env-var name is not
+ * itself sensitive (it's a well-known identifier the user chose), and this
+ * helper exists so callers printing the source of a credential can avoid
+ * handling the raw `client_secret` field value at all.
+ */
+export declare function extractEnvSecretName(value: string): string | null;
+//# sourceMappingURL=secret-resolver.d.ts.map

package/dist/lib/auth/oauth/secret-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secret-resolver.d.ts","sourceRoot":"","sources":["../../../../src/lib/auth/oauth/secret-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH;;;;;GAKG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;aAG5B,MAAM,EAAE,MAAM;aACd,MAAM,EAAE,OAAO,GAAG,OAAO;IAH3C,QAAQ,CAAC,IAAI,wBAAwB;gBAEnB,MAAM,EAAE,MAAM,EACd,MAAM,GAAE,OAAO,GAAG,OAAiB;CAStD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAgBnD;AAED,wEAAwE;AACxE,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAE3D;AAED,gEAAgE;AAChE,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAIjE"}