@agentmailbox/mcp-auth 1.0.5 → 1.1.1

package/README.md

@@ -57,13 +57,87 @@ Replace:
 | Variable | Required | Description |
 |----------|----------|-------------|
 | `MCP_OAUTH_CLIENT_ID` | Yes | Your OAuth2 client ID |
-| `MCP_OAUTH_CLIENT_SECRET` | Yes | Your OAuth2 client secret |
+| `MCP_OAUTH_CLIENT_SECRET` | Conditional | Your OAuth2 client secret (or use file-based secret) |
+| `MCP_OAUTH_CLIENT_SECRET_FILE` | Conditional | Path to file containing client secret (more secure) |
+| `MCP_DISABLE_CERT_PINNING` | No | Set to `"true"` to disable certificate pinning (for corporate proxies) |
+| `MCP_DEBUG` | No | Set to `"true"` to enable debug logging (never logs secrets) |
+
+**Note:** Either `MCP_OAUTH_CLIENT_SECRET` or `MCP_OAUTH_CLIENT_SECRET_FILE` must be provided.
+
+### Using File-Based Secrets (Recommended for Production)
+
+For enhanced security, store your client secret in a file instead of an environment variable:
+
+```bash
+# Create a secret file with restricted permissions (avoids shell history)
+read -rs SECRET && printf '%s' "$SECRET" > ~/.agentmail-secret && unset SECRET
+chmod 600 ~/.agentmail-secret
+```
+
+Then configure:
+```json
+{
+  "env": {
+    "MCP_OAUTH_CLIENT_ID": "your-client-id",
+    "MCP_OAUTH_CLIENT_SECRET_FILE": "/Users/you/.agentmail-secret"
+  }
+}
+```
+
+## Security Features
+
+This package implements several security measures:
+
+| Feature | Description |
+|---------|-------------|
+| **HTTPS Enforcement** | All endpoints must use HTTPS (localhost allowed for development) |
+| **Certificate Pinning** | SPKI pinning for AgentMailbox domains (Amazon Root CAs) |
+| **Environment Isolation** | Child processes receive minimal environment variables |
+| **File-Based Secrets** | Option to read secrets from files instead of environment variables |
+| **Response Size Limits** | Prevents memory exhaustion from malicious responses (100KB max) |
+| **Token Validation** | Validates JWT token format before use |
+| **Error Sanitization** | Removes sensitive data from error messages |
+| **Pinned Dependencies** | Uses pinned version of mcp-remote |
+| **Exponential Backoff** | Automatic retries with jitter to prevent thundering herd |
+| **Security Headers** | Advisory checks for HSTS and X-Content-Type-Options (logs warnings in debug mode) |
+
+### Certificate Pinning
+
+Certificate pinning is enabled by default for AgentMailbox domains (`auth.agentmailbox.to`, `mcp.agentmailbox.to`). This helps mitigate many MITM scenarios by validating that certificates are signed by expected root CAs.
+
+If you're behind a corporate proxy that performs TLS inspection, you may need to disable pinning:
+
+```json
+{
+  "env": {
+    "MCP_DISABLE_CERT_PINNING": "true"
+  }
+}
+```
+
+**Warning:** Only disable certificate pinning if you understand the security implications.
+
+## Troubleshooting
+
+Enable debug logging to diagnose connection issues:
+
+```json
+{
+  "env": {
+    "MCP_DEBUG": "true"
+  }
+}
+```
+
+Debug logs are written to stderr and include timestamps. **Sensitive data (tokens, secrets) is never logged.**
 
 ## How It Works
 
-1. Fetches an OAuth2 access token using the Client Credentials flow
-2. Passes the token to `mcp-remote` via environment variable
-3. Forwards all MCP communication to the AgentMailbox server
+1. Reads client credentials from environment variables or secret file
+2. Fetches an OAuth2 access token using the Client Credentials flow (with automatic retries)
+3. Validates the token response (size limits, JWT format, security headers)
+4. Passes the token to `mcp-remote` via environment variable
+5. Forwards all MCP communication to the AgentMailbox server
 
 ## Requirements
 

package/index.js

@@ -5,6 +5,17 @@
  * OAuth2 Client Credentials wrapper for MCP servers.
  * Handles M2M (machine-to-machine) authentication for AgentMailbox MCP endpoints.
  *
+ * Security features:
+ * - HTTPS enforcement for all endpoints (localhost allowed for development)
+ * - Certificate pinning for AgentMailbox domains (optional, enabled by default)
+ * - Environment isolation for child processes
+ * - Support for secret file to avoid environment variable exposure
+ * - Response size limits and token format validation
+ * - Sanitized error messages to prevent information leakage
+ * - Exponential backoff for retries (prevents accidental DoS)
+ * - Security headers validation
+ * - Optional debug logging for troubleshooting
+ *
  * Usage with npx in claude_desktop_config.json:
  * {
  *   "mcpServers": {
@@ -19,7 +30,7 @@
  *       ],
  *       "env": {
  *         "MCP_OAUTH_CLIENT_ID": "your-client-id",
- *         "MCP_OAUTH_CLIENT_SECRET": "your-client-secret"
+ *         "MCP_OAUTH_CLIENT_SECRET": "your-client-secret"  // pragma: allowlist secret
  *       }
  *     }
  *   }
@@ -27,15 +38,123 @@
  */
 
 import { spawn } from 'child_process';
+import { readFileSync } from 'fs';
+import { request } from 'https';
+import { request as httpRequest } from 'http';
+import { createHash } from 'crypto';
+import { checkServerIdentity as tlsCheckServerIdentity } from 'tls';
+
+// Security constants
+const TOKEN_TIMEOUT_MS = 30000; // 30 seconds
+const MAX_TOKEN_RESPONSE_SIZE = 100000; // 100KB max response
+const MCP_REMOTE_VERSION = '0.1.12'; // Pinned version for security
+
+// Retry configuration with exponential backoff
+const MAX_RETRIES = 3;
+const INITIAL_RETRY_DELAY_MS = 1000; // 1 second
+const MAX_RETRY_DELAY_MS = 10000; // 10 seconds
+
+// Valid localhost hostnames (including IPv6)
+const LOCALHOST_HOSTS = new Set(['localhost', '127.0.0.1', '::1', '[::1]']);
+
+// Known AgentMailbox domains that should have certificate pinning
+const PINNED_DOMAINS = new Set([
+  'auth.agentmailbox.to',
+  'mcp.agentmailbox.to',
+  'api.agentmailbox.to',
+]);
 
-// Default timeout for token requests (30 seconds)
-const TOKEN_TIMEOUT_MS = 30000;
+// Expected security headers for token endpoint
+const EXPECTED_SECURITY_HEADERS = {
+  'strict-transport-security': true, // HSTS should be present
+  'x-content-type-options': 'nosniff',
+};
+
+// SPKI (Subject Public Key Info) hashes for certificate pinning
+// These are SHA-256 hashes of the public keys in the certificate chain
+// Using Amazon Root CA and intermediate CAs that sign AgentMailbox certs
+// To update: openssl s_client -connect auth.agentmailbox.to:443 | openssl x509 -pubkey -noout | openssl pkey -pubin -outform der | openssl dgst -sha256 -binary | base64
+// Public key hashes for certificate pinning (these are PUBLIC, not secrets)
+// pragma: allowlist nextline secret
+const PINNED_PUBLIC_KEYS = new Set([
+  // Amazon Root CA 1 - pragma: allowlist secret
+  '++MBgDH5WGvL9Bcn5Be30cRcL0f5O+NyoXuWtQdX1aI=',  // pragma: allowlist secret
+  // Amazon Root CA 2
+  'f0KW/FtqTjs108NpYj42SrGvOB2PpxIVM8nWxjPqJGE=',  // pragma: allowlist secret
+  // Amazon Root CA 3
+  'NqvDJlas/GRcYbcWE8S/IceG7Qz2ddXE5XX9x8JMA+k=',  // pragma: allowlist secret
+  // Amazon Root CA 4
+  '9+ze1cZgR9KO1kZrVDxA4HQ6voHRCSVNz4RdTCx4U8U=',  // pragma: allowlist secret
+  // Starfield Services Root CA (Amazon's root)
+  'KwccWaCgrnaw6tsrrSO61FgLacNgG2MMLq8GE6+oP5I=',  // pragma: allowlist secret
+]);
 
 const [mcpUrl, tokenEndpoint, scope] = process.argv.slice(2);
 const clientId = process.env.MCP_OAUTH_CLIENT_ID;
-const clientSecret = process.env.MCP_OAUTH_CLIENT_SECRET;
 
-if (!mcpUrl || !tokenEndpoint || !clientId || !clientSecret) {
+// Configuration flags
+const DISABLE_CERT_PINNING = process.env.MCP_DISABLE_CERT_PINNING === 'true';
+const DEBUG_MODE = process.env.MCP_DEBUG === 'true';
+
+/**
+ * Debug logger - only logs when MCP_DEBUG=true
+ * Never logs sensitive data like secrets or tokens
+ */
+function debugLog(message, data = null) {
+  if (!DEBUG_MODE) return;
+
+  const timestamp = new Date().toISOString();
+  const prefix = `[mcp-auth ${timestamp}]`;
+
+  if (data) {
+    // Sanitize any potentially sensitive data
+    const safeData = JSON.stringify(data, (key, value) => {
+      const sensitiveKeys = ['secret', 'token', 'password', 'authorization', 'bearer'];
+      if (sensitiveKeys.some(k => key.toLowerCase().includes(k))) {
+        return '[REDACTED]';
+      }
+      return value;
+    });
+    console.error(`${prefix} ${message}:`, safeData);
+  } else {
+    console.error(`${prefix} ${message}`);
+  }
+}
+
+/**
+ * Get client secret from environment variable or file.
+ * File-based secrets are more secure as they're not visible in process listings.
+ */
+function getClientSecret() {
+  // Prefer file-based secret if specified
+  const secretFile = process.env.MCP_OAUTH_CLIENT_SECRET_FILE;
+  if (secretFile) {
+    debugLog('Reading secret from file', { path: secretFile });
+    try {
+      const secret = readFileSync(secretFile, 'utf-8').trim();
+      if (!secret) {
+        console.error('Error: Secret file is empty');
+        process.exit(1);
+      }
+      debugLog('Secret loaded from file successfully');
+      return secret;
+    } catch (err) {
+      console.error(`Error: Failed to read secret file: ${err.code === 'ENOENT' ? 'File not found' : 'Read error'}`);
+      process.exit(1);
+    }
+  }
+
+  // Fall back to environment variable
+  const secret = process.env.MCP_OAUTH_CLIENT_SECRET;
+  if (!secret) {
+    console.error('Error: MCP_OAUTH_CLIENT_SECRET or MCP_OAUTH_CLIENT_SECRET_FILE must be set');
+    process.exit(1);
+  }
+  debugLog('Using secret from environment variable');
+  return secret;
+}
+
+if (!mcpUrl || !tokenEndpoint || !clientId) {
   console.error('Usage: npx @agentmailbox/mcp-auth <mcp-url> <token-endpoint> [scope]');
   console.error('');
   console.error('Arguments:');
@@ -43,38 +162,324 @@ if (!mcpUrl || !tokenEndpoint || !clientId || !clientSecret) {
   console.error('  token-endpoint The OAuth2 token endpoint (e.g., https://auth.agentmailbox.to/oauth2/token)');
   console.error('  scope          Optional OAuth2 scope (default: mcp-api/email.full)');
   console.error('');
-  console.error('Environment variables required:');
-  console.error('  MCP_OAUTH_CLIENT_ID     Your OAuth2 client ID');
-  console.error('  MCP_OAUTH_CLIENT_SECRET Your OAuth2 client secret');
+  console.error('Environment variables:');
+  console.error('  MCP_OAUTH_CLIENT_ID          Your OAuth2 client ID (required)');
+  console.error('  MCP_OAUTH_CLIENT_SECRET      Your OAuth2 client secret');
+  console.error('  MCP_OAUTH_CLIENT_SECRET_FILE Path to file containing client secret (more secure)');
+  console.error('  MCP_DISABLE_CERT_PINNING     Set to "true" to disable certificate pinning (for corporate proxies)');
+  console.error('  MCP_DEBUG                    Set to "true" to enable debug logging (never logs secrets)');
+  process.exit(1);
+}
+
+debugLog('Starting mcp-auth', {
+  mcpUrl,
+  tokenEndpoint,
+  scope: scope || 'mcp-api/email.full',
+  certPinning: !DISABLE_CERT_PINNING,
+});
+
+// Get secret after argument validation
+const clientSecret = getClientSecret();
+
+/**
+ * Validate that a URL uses HTTPS (or localhost for development).
+ * Prevents sending credentials over insecure connections.
+ */
+function isSecureEndpoint(url) {
+  try {
+    const parsed = new URL(url);
+
+    // HTTPS is always allowed
+    if (parsed.protocol === 'https:') {
+      return true;
+    }
+
+    // HTTP only allowed for true localhost (not localhost.attacker.com)
+    if (parsed.protocol === 'http:') {
+      return LOCALHOST_HOSTS.has(parsed.hostname.toLowerCase());
+    }
+
+    return false;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Validate URL format to prevent injection attacks.
+ */
+function isValidUrl(url) {
+  try {
+    const parsed = new URL(url);
+    // Only allow http/https protocols
+    return ['http:', 'https:'].includes(parsed.protocol);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check if a domain should have certificate pinning.
+ */
+function shouldPinCertificate(hostname) {
+  if (DISABLE_CERT_PINNING) return false;
+  return PINNED_DOMAINS.has(hostname.toLowerCase());
+}
+
+/**
+ * Verify certificate against pinned public keys.
+ * Uses SPKI (Subject Public Key Info) pinning which survives cert renewals.
+ */
+function verifyCertificatePin(cert, hostname) {
+  if (!shouldPinCertificate(hostname)) {
+    debugLog('Certificate pinning skipped', { hostname, reason: DISABLE_CERT_PINNING ? 'disabled' : 'not in pinned domains' });
+    return; // No pinning required for this domain
+  }
+
+  debugLog('Verifying certificate pin', { hostname });
+
+  // Get the certificate chain, tracking seen certs to prevent any cycle
+  const certChain = [];
+  const seenCerts = new Set();
+  let currentCert = cert;
+  while (currentCert) {
+    // Break if we've seen this certificate before (any cycle, not just back to root)
+    if (seenCerts.has(currentCert)) break;
+    seenCerts.add(currentCert);
+    certChain.push(currentCert);
+    const issuer = currentCert.issuerCertificate;
+    // Break if no issuer or self-signed (issuer points to itself)
+    if (!issuer || issuer === currentCert) break;
+    currentCert = issuer;
+  }
+
+  // Check if any certificate in the chain matches our pinned keys
+  for (const c of certChain) {
+    if (c.pubkey) {
+      const spkiHash = createHash('sha256').update(c.pubkey).digest('base64');
+      if (PINNED_PUBLIC_KEYS.has(spkiHash)) {
+        debugLog('Certificate pin verified successfully');
+        return; // Valid pin found
+      }
+    }
+  }
+
+  throw new Error(`Certificate pinning failed for ${hostname}. None of the certificates in the chain match pinned public keys.`);
+}
+
+/**
+ * Verify expected security headers are present in the response.
+ */
+function verifySecurityHeaders(headers, hostname) {
+  // Only verify for AgentMailbox domains
+  if (!PINNED_DOMAINS.has(hostname.toLowerCase())) {
+    return;
+  }
+
+  const warnings = [];
+
+  for (const [header, expectedValue] of Object.entries(EXPECTED_SECURITY_HEADERS)) {
+    const actualValue = headers[header];
+
+    if (expectedValue === true) {
+      // Just check presence
+      if (!actualValue) {
+        warnings.push(`Missing security header: ${header}`);
+      }
+    } else if (actualValue !== expectedValue) {
+      warnings.push(`Unexpected ${header} value: expected "${expectedValue}", got "${actualValue || 'missing'}"`);
+    }
+  }
+
+  if (warnings.length > 0) {
+    debugLog('Security header warnings', { warnings });
+    // Don't fail, just log warnings in debug mode
+  } else {
+    debugLog('Security headers verified');
+  }
+}
+
+if (!isValidUrl(tokenEndpoint)) {
+  console.error('Error: Invalid token-endpoint URL format');
+  process.exit(1);
+}
+
+if (!isValidUrl(mcpUrl)) {
+  console.error('Error: Invalid mcp-url URL format');
+  process.exit(1);
+}
+
+if (!isSecureEndpoint(tokenEndpoint)) {
+  console.error('Error: token-endpoint must use HTTPS (localhost allowed for development)');
+  process.exit(1);
+}
+
+if (!isSecureEndpoint(mcpUrl)) {
+  console.error('Error: mcp-url must use HTTPS (localhost allowed for development)');
   process.exit(1);
 }
 
 /**
- * Build a minimal environment for the child process.
- * Only passes through essential variables to avoid leaking secrets.
+ * Build a minimal allow-list environment for the child process.
+ * Only includes necessary system variables, avoiding exposure of ambient secrets.
  */
 function buildChildEnv(env) {
   const allowList = [
-    // Essential for process execution
+    // Essential system paths
     'PATH', 'HOME', 'USERPROFILE',
     // Temp directories
     'TMP', 'TEMP', 'TMPDIR',
-    // Windows-specific
-    'SystemRoot', 'ComSpec', 'WINDIR', 'PATHEXT',
-    // Proxy settings (important for corporate environments)
+    // Windows system variables
+    'SystemRoot', 'ComSpec', 'WINDIR', 'PATHEXT', 'APPDATA', 'LOCALAPPDATA',
+    // Proxy configuration
     'HTTP_PROXY', 'HTTPS_PROXY', 'NO_PROXY',
     'http_proxy', 'https_proxy', 'no_proxy',
     // Node.js configuration
     'NODE_EXTRA_CA_CERTS', 'NODE_OPTIONS',
-    // MCP-specific
+    // npm/npx configuration (for custom registries and cache in enterprise environments)
+    'NPM_CONFIG_REGISTRY', 'npm_config_registry',
+    'NPM_CONFIG_USERCONFIG', 'npm_config_userconfig',
+    'NPM_CONFIG_CACHE', 'npm_config_cache',
+    'NPM_CONFIG_PREFIX', 'npm_config_prefix',
+    // mcp-remote configuration directory
     'MCP_REMOTE_CONFIG_DIR',
   ];
-
   return Object.fromEntries(
     allowList.flatMap((key) => (env[key] ? [[key, env[key]]] : []))
   );
 }
 
+/**
+ * Validate that a string looks like a JWT token.
+ * JWTs have three base64url-encoded parts separated by dots.
+ */
+function isValidJwtFormat(token) {
+  if (typeof token !== 'string') return false;
+  const parts = token.split('.');
+  if (parts.length !== 3) return false;
+
+  // Check each part is valid base64url (alphanumeric, -, _)
+  const base64urlRegex = /^[A-Za-z0-9_-]+$/;
+  return parts.every(part => part.length > 0 && base64urlRegex.test(part));
+}
+
+/**
+ * Sanitize error messages to prevent information leakage.
+ * Defensively handles non-string inputs to avoid secondary failures.
+ */
+function sanitizeErrorMessage(message) {
+  // Safely coerce input to string
+  const safeMessage = typeof message === 'string' ? message : String(message ?? '');
+  // Remove potential sensitive data patterns
+  return safeMessage
+    .substring(0, 200) // Limit length
+    .replace(/Bearer\s+[A-Za-z0-9._-]+/gi, 'Bearer [REDACTED]')
+    .replace(/client_secret[^&]*/gi, 'client_secret=[REDACTED]')
+    .replace(/access_token[^&]*/gi, 'access_token=[REDACTED]');
+}
+
+/**
+ * Sleep for a given number of milliseconds.
+ */
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+/**
+ * Calculate exponential backoff delay with jitter.
+ */
+function calculateBackoffDelay(attempt) {
+  const exponentialDelay = INITIAL_RETRY_DELAY_MS * Math.pow(2, attempt);
+  const cappedDelay = Math.min(exponentialDelay, MAX_RETRY_DELAY_MS);
+  // Add jitter (0-25% of delay) to prevent thundering herd
+  const jitter = cappedDelay * Math.random() * 0.25;
+  return Math.floor(cappedDelay + jitter);
+}
+
+/**
+ * Make HTTPS request with certificate pinning support.
+ */
+function makeRequest(urlString, options, body) {
+  return new Promise((resolve, reject) => {
+    const url = new URL(urlString);
+    const isHttps = url.protocol === 'https:';
+    const requestFn = isHttps ? request : httpRequest;
+
+    const reqOptions = {
+      hostname: url.hostname,
+      port: url.port || (isHttps ? 443 : 80),
+      path: url.pathname + url.search,
+      method: options.method || 'GET',
+      headers: options.headers || {},
+      timeout: options.timeout || TOKEN_TIMEOUT_MS,
+    };
+
+    // Add certificate pinning during TLS handshake (before credentials are sent)
+    if (isHttps) {
+      reqOptions.checkServerIdentity = (host, cert) => {
+        // First, perform standard hostname verification
+        const hostnameError = tlsCheckServerIdentity(host, cert);
+        if (hostnameError) return hostnameError;
+        // Then verify certificate pinning
+        try {
+          verifyCertificatePin(cert, host);
+          return undefined; // Success
+        } catch (e) {
+          return e instanceof Error ? e : new Error('Certificate pinning failed');
+        }
+      };
+    }
+
+    debugLog('Making request', { hostname: url.hostname, method: reqOptions.method, path: reqOptions.path });
+
+    const req = requestFn(reqOptions, (res) => {
+      // Verify security headers
+      verifySecurityHeaders(res.headers, url.hostname);
+
+      let data = '';
+      let receivedLength = 0;
+
+      res.on('data', (chunk) => {
+        receivedLength += chunk.length;
+        if (receivedLength > MAX_TOKEN_RESPONSE_SIZE) {
+          req.destroy();
+          reject(new Error('Token response exceeded maximum allowed size'));
+          return;
+        }
+        data += chunk;
+      });
+
+      res.on('end', () => {
+        debugLog('Request completed', { status: res.statusCode, dataLength: data.length });
+        resolve({
+          status: res.statusCode,
+          headers: res.headers,
+          data,
+        });
+      });
+    });
+
+    req.on('error', (err) => {
+      debugLog('Request error', { error: err.message });
+      reject(new Error('Failed to connect to token endpoint'));
+    });
+
+    req.on('timeout', () => {
+      req.destroy();
+      debugLog('Request timeout');
+      reject(new Error(`Token request timed out after ${TOKEN_TIMEOUT_MS}ms`));
+    });
+
+    if (body) {
+      req.write(body);
+    }
+    req.end();
+  });
+}
+
+/**
+ * Get access token with exponential backoff retry logic.
+ */
 async function getAccessToken() {
   const params = new URLSearchParams({
     grant_type: 'client_credentials',
@@ -83,38 +488,73 @@ async function getAccessToken() {
     scope: scope || 'mcp-api/email.full',
   });
 
-  // Use AbortController for timeout
-  const controller = new AbortController();
-  const timeoutId = setTimeout(() => controller.abort(), TOKEN_TIMEOUT_MS);
+  let lastError;
 
-  let response;
-  try {
-    response = await fetch(tokenEndpoint, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
-      body: params.toString(),
-      signal: controller.signal,
-    });
-  } catch (err) {
-    clearTimeout(timeoutId);
-    if (err.name === 'AbortError') {
-      throw new Error(`Token request timed out after ${TOKEN_TIMEOUT_MS}ms`);
+  for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+    if (attempt > 0) {
+      const delay = calculateBackoffDelay(attempt - 1);
+      debugLog(`Retry attempt ${attempt}/${MAX_RETRIES}`, { delayMs: delay });
+      await sleep(delay);
     }
-    throw err;
-  } finally {
-    clearTimeout(timeoutId);
-  }
 
-  if (!response.ok) {
-    const error = await response.text();
-    throw new Error(`Token request failed: ${response.status} ${error}`);
-  }
+    try {
+      const response = await makeRequest(tokenEndpoint, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/x-www-form-urlencoded',
+          'Content-Length': Buffer.byteLength(params.toString()),
+        },
+        timeout: TOKEN_TIMEOUT_MS,
+      }, params.toString());
+
+      // Don't retry on client errors (4xx) - these won't succeed on retry
+      if (response.status >= 400 && response.status < 500) {
+        debugLog('Client error, not retrying', { status: response.status });
+        throw new Error(`Token request failed with status ${response.status}`);
+      }
+
+      // Retry on server errors (5xx) or network issues
+      if (response.status !== 200) {
+        throw new Error(`Token request failed with status ${response.status}`);
+      }
+
+      let data;
+      try {
+        data = JSON.parse(response.data);
+      } catch {
+        throw new Error('Invalid JSON response from token endpoint');
+      }
+
+      if (!data || typeof data.access_token !== 'string' || data.access_token.trim() === '') {
+        throw new Error('Missing access_token in response');
+      }
+
+      const token = data.access_token.trim();
 
-  const data = await response.json();
-  if (!data || typeof data.access_token !== 'string' || data.access_token.trim() === '') {
-    throw new Error('Missing or invalid access_token in token response');
+      // Validate token format (should be JWT)
+      if (!isValidJwtFormat(token)) {
+        throw new Error('Invalid token format received');
+      }
+
+      debugLog('Access token obtained successfully');
+      return token;
+
+    } catch (err) {
+      lastError = err;
+      debugLog('Token request failed', { attempt, error: err.message });
+
+      // Don't retry on certain errors
+      if (err.message.includes('Certificate pinning failed') ||
+          err.message.includes('Invalid token format') ||
+          err.message.includes('Missing access_token') ||
+          err.message.includes('status 4')) {
+        throw err;
+      }
+    }
   }
-  return data.access_token;
+
+  // All retries exhausted
+  throw lastError || new Error('Failed to obtain access token after retries');
 }
 
 async function main() {
@@ -124,25 +564,33 @@ async function main() {
     // Build minimal environment with only necessary variables
     const childEnv = buildChildEnv(process.env);
 
-    // Launch mcp-remote with Authorization header via --header flag
-    // Note: Token appears briefly in process args, but this is acceptable for MCP client usage
+    // Add token to child environment for mcp-remote to use
+    // This avoids exposing the token in process arguments
+    childEnv.MCP_HEADER_Authorization = `Bearer ${token}`;
+
+    debugLog('Launching mcp-remote', { version: MCP_REMOTE_VERSION, mcpUrl });
+
+    // Launch mcp-remote with pinned version
+    // Token is passed via environment variable, not command line args
     const child = spawn('npx', [
       '-y',
-      'mcp-remote',
+      `mcp-remote@${MCP_REMOTE_VERSION}`,
       mcpUrl,
       '--header',
-      `Authorization:Bearer ${token}`,
+      'Authorization:${MCP_HEADER_Authorization}',
     ], {
       stdio: 'inherit',
       env: childEnv,
     });
 
     child.on('error', (err) => {
-      console.error('Failed to start mcp-remote:', err);
+      const rawMessage = err instanceof Error ? err.message : err;
+      console.error('Failed to start mcp-remote:', sanitizeErrorMessage(rawMessage));
       process.exit(1);
     });
 
     child.on('exit', (code, signal) => {
+      debugLog('mcp-remote exited', { code, signal });
       if (code !== null) {
         process.exit(code);
       } else if (signal !== null) {
@@ -155,6 +603,7 @@ async function main() {
 
     // Forward signals to child process for graceful shutdown
     const forwardSignal = (sig) => {
+      debugLog('Forwarding signal to child', { signal: sig });
       if (child.pid) {
         child.kill(sig);
       }
@@ -162,7 +611,8 @@ async function main() {
     process.on('SIGINT', () => forwardSignal('SIGINT'));
     process.on('SIGTERM', () => forwardSignal('SIGTERM'));
   } catch (err) {
-    console.error('Error:', err.message);
+    const rawMessage = err instanceof Error ? err.message : err;
+    console.error('Error:', sanitizeErrorMessage(rawMessage));
     process.exit(1);
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentmailbox/mcp-auth",
-  "version": "1.0.5",
+  "version": "1.1.1",
   "description": "OAuth2 Client Credentials wrapper for MCP servers - enables M2M authentication with AgentMailbox",
   "type": "module",
   "bin": {