@vibecheckai/cli 3.7.0 → 3.8.0

package/bin/runners/lib/auth-shared.js

@@ -0,0 +1,977 @@
+/**
+ * Shared Auth Module Bridge (JavaScript)
+ * 
+ * Provides shared auth functionality for CLI commands.
+ * This bridges the TypeScript shared/auth module for JS consumers.
+ * 
+ * @module lib/auth-shared
+ */
+
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const crypto = require("crypto");
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// PATHS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+const VIBECHECK_DIR = ".vibecheck";
+const AUTH_FILE = "auth.json";
+const CACHE_FILE = "entitlements-cache.json";
+const AUDIT_FILE = "auth-audit.log";
+const ACTIVITY_FILE = ".auth-activity.json";
+const RATE_LIMIT_FILE = ".rate-limit.json";
+
+// Rate limit state in memory
+let rateLimitState = { retryAfter: null, timestamp: null };
+
+// Constants
+const MAX_RETRIES = 3;
+const BASE_RETRY_DELAY_MS = 1000;
+const FAILED_ATTEMPT_THRESHOLD = 5;
+const LOCKOUT_DURATION_MS = 15 * 60 * 1000; // 15 minutes
+const MAX_AUDIT_SIZE = 1024 * 1024; // 1MB
+
+/**
+ * Get vibecheck config directory.
+ * @returns {string}
+ */
+function getConfigDir() {
+  return path.join(os.homedir(), VIBECHECK_DIR);
+}
+
+/**
+ * Get auth file path.
+ * @returns {string}
+ */
+function getAuthPath() {
+  return path.join(getConfigDir(), AUTH_FILE);
+}
+
+/**
+ * Get cache file path.
+ * @returns {string}
+ */
+function getCachePath() {
+  return path.join(getConfigDir(), CACHE_FILE);
+}
+
+/**
+ * Get legacy config path (for migration).
+ * @returns {string}
+ */
+function getLegacyConfigPath() {
+  const home = os.homedir();
+  if (process.platform === "win32") {
+    return path.join(
+      process.env.APPDATA || path.join(home, "AppData", "Roaming"),
+      "vibecheck",
+      "config.json"
+    );
+  }
+  return path.join(home, ".config", "vibecheck", "config.json");
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// REDACTION
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Mask API key for secure display.
+ * @param {string} key
+ * @returns {string}
+ */
+function redactApiKey(key) {
+  if (!key || typeof key !== "string" || key.length < 8) {
+    return "****";
+  }
+
+  // New format: grl_ prefix
+  if (key.startsWith("grl_")) {
+    return `grl_${"*".repeat(8)}${key.slice(-4)}`;
+  }
+
+  // Legacy format: gr_<tier>_ prefix
+  const legacyMatch = key.match(/^(gr_[a-z]+_)/);
+  if (legacyMatch) {
+    return `${legacyMatch[1]}${"*".repeat(8)}${key.slice(-4)}`;
+  }
+
+  // Unknown format
+  if (key.length >= 12) {
+    return `${key.slice(0, 3)}****${key.slice(-4)}`;
+  }
+
+  return "****";
+}
+
+/**
+ * Redact API keys in output text.
+ * @param {string} text
+ * @returns {string}
+ */
+function redactOutput(text) {
+  if (!text || typeof text !== "string") return text;
+  
+  return text
+    .replace(/grl_[a-zA-Z0-9]{10,}/g, (m) => redactApiKey(m))
+    .replace(/gr_[a-z]+_[a-zA-Z0-9]{10,}/g, (m) => redactApiKey(m))
+    .replace(
+      /VIBECHECK_API_KEY\s*=\s*["']?([a-zA-Z0-9_-]{10,})["']?/gi,
+      (_, k) => `VIBECHECK_API_KEY=${redactApiKey(k)}`
+    );
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// VALIDATION
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Validate API key format.
+ * @param {string} key
+ * @returns {{ valid: boolean, error?: string, format?: string }}
+ */
+function validateKeyFormat(key) {
+  if (!key || typeof key !== "string") {
+    return { valid: false, error: "API key is required" };
+  }
+
+  const trimmed = key.trim();
+
+  if (trimmed.length < 20) {
+    return { valid: false, error: "API key is too short (minimum 20 characters)" };
+  }
+
+  // New format: grl_ prefix
+  if (trimmed.startsWith("grl_")) {
+    if (!/^grl_[a-zA-Z0-9]+$/.test(trimmed)) {
+      return { valid: false, error: "API key contains invalid characters", format: "grl" };
+    }
+    return { valid: true, format: "grl" };
+  }
+
+  // Legacy format: gr_<tier>_ prefix
+  if (trimmed.startsWith("gr_")) {
+    if (!/^gr_[a-z]+_[a-zA-Z0-9]+$/.test(trimmed)) {
+      return { valid: false, error: "Invalid legacy API key format", format: "legacy" };
+    }
+    return { valid: true, format: "legacy" };
+  }
+
+  // Also accept generic alphanumeric keys (backward compat)
+  if (/^[a-zA-Z0-9_-]+$/.test(trimmed) && trimmed.length >= 20) {
+    return { valid: true, format: "unknown" };
+  }
+
+  return { valid: false, error: 'API key must start with "grl_"' };
+}
+
+/**
+ * Quick format check.
+ * @param {string} key
+ * @returns {boolean}
+ */
+function isValidKeyFormat(key) {
+  return validateKeyFormat(key).valid;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// STORAGE
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Ensure config directory exists.
+ */
+function ensureConfigDir() {
+  const dir = getConfigDir();
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  }
+}
+
+/**
+ * Read credentials from new auth.json.
+ * @returns {object|null}
+ */
+function readCredentials() {
+  try {
+    const authPath = getAuthPath();
+    if (fs.existsSync(authPath)) {
+      return JSON.parse(fs.readFileSync(authPath, "utf8"));
+    }
+  } catch {
+    // Ignore
+  }
+  return null;
+}
+
+/**
+ * Write credentials to auth.json.
+ * @param {object} credentials
+ */
+function writeCredentials(credentials) {
+  ensureConfigDir();
+  const authPath = getAuthPath();
+  const data = { version: 2, ...credentials };
+  fs.writeFileSync(authPath, JSON.stringify(data, null, 2), { mode: 0o600 });
+}
+
+/**
+ * Delete credentials.
+ */
+function deleteCredentials() {
+  try {
+    const authPath = getAuthPath();
+    if (fs.existsSync(authPath)) {
+      fs.unlinkSync(authPath);
+    }
+  } catch {
+    // Ignore
+  }
+}
+
+/**
+ * Read entitlements cache.
+ * @returns {object|null}
+ */
+function readCache() {
+  try {
+    const cachePath = getCachePath();
+    if (fs.existsSync(cachePath)) {
+      return JSON.parse(fs.readFileSync(cachePath, "utf8"));
+    }
+  } catch {
+    // Ignore
+  }
+  return null;
+}
+
+/**
+ * Write entitlements cache.
+ * @param {object} cache
+ */
+function writeCache(cache) {
+  ensureConfigDir();
+  const cachePath = getCachePath();
+  fs.writeFileSync(cachePath, JSON.stringify(cache, null, 2), { mode: 0o600 });
+}
+
+/**
+ * Delete cache.
+ */
+function deleteCache() {
+  try {
+    const cachePath = getCachePath();
+    if (fs.existsSync(cachePath)) {
+      fs.unlinkSync(cachePath);
+    }
+  } catch {
+    // Ignore
+  }
+}
+
+/**
+ * Clear all auth data (logout).
+ */
+function clearAll() {
+  deleteCredentials();
+  deleteCache();
+  
+  // Clear activity tracker
+  try {
+    const activityPath = path.join(getConfigDir(), ACTIVITY_FILE);
+    if (fs.existsSync(activityPath)) {
+      fs.unlinkSync(activityPath);
+    }
+  } catch {
+    // Ignore
+  }
+  
+  // Clear rate limit
+  try {
+    const ratePath = path.join(getConfigDir(), RATE_LIMIT_FILE);
+    if (fs.existsSync(ratePath)) {
+      fs.unlinkSync(ratePath);
+    }
+  } catch {
+    // Ignore
+  }
+  
+  // Also clear legacy locations
+  try {
+    const legacyPath = getLegacyConfigPath();
+    if (fs.existsSync(legacyPath)) {
+      const config = JSON.parse(fs.readFileSync(legacyPath, "utf8"));
+      delete config.apiKey;
+      fs.writeFileSync(legacyPath, JSON.stringify(config, null, 2), { mode: 0o600 });
+    }
+  } catch {
+    // Ignore
+  }
+  
+  auditLog("LOGOUT", null, "cli");
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// AUDIT LOGGING
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Write audit log entry.
+ * @param {string} event
+ * @param {string|null} apiKey
+ * @param {string} source
+ * @param {object} [details]
+ */
+function auditLog(event, apiKey, source, details) {
+  try {
+    const configDir = getConfigDir();
+    const auditPath = path.join(configDir, AUDIT_FILE);
+    
+    ensureConfigDir();
+    
+    // Rotate log if too large
+    try {
+      const stats = fs.statSync(auditPath);
+      if (stats.size > MAX_AUDIT_SIZE) {
+        const backupPath = auditPath + ".1";
+        if (fs.existsSync(backupPath)) {
+          fs.unlinkSync(backupPath);
+        }
+        fs.renameSync(auditPath, backupPath);
+      }
+    } catch {
+      // File doesn't exist yet
+    }
+    
+    const entry = {
+      timestamp: new Date().toISOString(),
+      event,
+      keyMasked: apiKey ? redactApiKey(apiKey) : "****",
+      source,
+      details: details || undefined,
+    };
+    
+    fs.appendFileSync(auditPath, JSON.stringify(entry) + "\n", { mode: 0o600 });
+  } catch {
+    // Audit logging should never break auth flow
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// RATE LIMITING
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Check if currently rate limited.
+ * @returns {{ limited: boolean, retryAfter?: number }}
+ */
+function checkRateLimit() {
+  if (rateLimitState.retryAfter && rateLimitState.timestamp) {
+    const elapsed = Date.now() - rateLimitState.timestamp;
+    const remaining = (rateLimitState.retryAfter * 1000) - elapsed;
+    
+    if (remaining > 0) {
+      return { limited: true, retryAfter: Math.ceil(remaining / 1000) };
+    }
+  }
+  return { limited: false };
+}
+
+/**
+ * Record rate limit from response.
+ * @param {number} retryAfter
+ */
+function recordRateLimit(retryAfter) {
+  rateLimitState = { retryAfter, timestamp: Date.now() };
+  auditLog("RATE_LIMITED", null, "api", { retryAfter });
+}
+
+/**
+ * Clear rate limit state.
+ */
+function clearRateLimitState() {
+  rateLimitState = { retryAfter: null, timestamp: null };
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// ACTIVITY TRACKING (LOCKOUT PROTECTION)
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Track failed auth attempt.
+ * @returns {{ locked: boolean, lockoutRemaining?: number }}
+ */
+function trackFailedAttempt() {
+  try {
+    const activityPath = path.join(getConfigDir(), ACTIVITY_FILE);
+    
+    let activity = { failedAttempts: 0, lastAttempt: 0 };
+    
+    try {
+      activity = JSON.parse(fs.readFileSync(activityPath, "utf8"));
+    } catch {
+      // File doesn't exist
+    }
+    
+    // Check if currently locked out
+    if (activity.lockoutUntil && Date.now() < activity.lockoutUntil) {
+      return { 
+        locked: true, 
+        lockoutRemaining: Math.ceil((activity.lockoutUntil - Date.now()) / 1000) 
+      };
+    }
+    
+    // Reset if lock expired
+    if (activity.lockoutUntil && Date.now() >= activity.lockoutUntil) {
+      activity = { failedAttempts: 0, lastAttempt: 0 };
+    }
+    
+    // Track new attempt
+    activity.failedAttempts++;
+    activity.lastAttempt = Date.now();
+    
+    // Check if should lock out
+    if (activity.failedAttempts >= FAILED_ATTEMPT_THRESHOLD) {
+      activity.lockoutUntil = Date.now() + LOCKOUT_DURATION_MS;
+      auditLog("SUSPICIOUS_ACTIVITY", null, "local", { 
+        reason: "Too many failed attempts",
+        attempts: activity.failedAttempts,
+      });
+    }
+    
+    fs.writeFileSync(activityPath, JSON.stringify(activity), { mode: 0o600 });
+    
+    if (activity.lockoutUntil) {
+      return { locked: true, lockoutRemaining: Math.ceil(LOCKOUT_DURATION_MS / 1000) };
+    }
+    
+    return { locked: false };
+  } catch {
+    return { locked: false };
+  }
+}
+
+/**
+ * Reset activity tracker on successful auth.
+ */
+function resetActivityTracker() {
+  try {
+    const activityPath = path.join(getConfigDir(), ACTIVITY_FILE);
+    if (fs.existsSync(activityPath)) {
+      fs.unlinkSync(activityPath);
+    }
+  } catch {
+    // Non-critical
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// INPUT SANITIZATION
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Deeply sanitize user input.
+ * @param {*} input
+ * @returns {string}
+ */
+function sanitizeInput(input) {
+  if (input === null || input === undefined) return "";
+  
+  let str = String(input);
+  
+  // Remove null bytes
+  str = str.replace(/\0/g, "");
+  
+  // Remove control characters
+  str = str.replace(/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g, "");
+  
+  // Trim whitespace
+  str = str.trim();
+  
+  // Limit length
+  if (str.length > 256) {
+    str = str.slice(0, 256);
+  }
+  
+  return str;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// ENVIRONMENT DETECTION
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Detect execution environment.
+ * @returns {object}
+ */
+function detectEnvironment() {
+  const env = process.env;
+  
+  let isCI = env.CI === "true" || env.CI === "1";
+  let ciProvider;
+  
+  if (isCI) {
+    if (env.GITHUB_ACTIONS) ciProvider = "github";
+    else if (env.GITLAB_CI) ciProvider = "gitlab";
+    else if (env.CIRCLECI) ciProvider = "circleci";
+    else ciProvider = "unknown";
+  }
+  
+  return {
+    isCI,
+    ciProvider,
+    isProduction: env.NODE_ENV === "production",
+    isDevelopment: env.NODE_ENV === "development" || (!env.NODE_ENV && !isCI),
+    isInteractive: process.stdin.isTTY && !isCI,
+  };
+}
+
+/**
+ * Check if dev bypass is allowed.
+ * @returns {boolean}
+ */
+function isDevBypassAllowed() {
+  const env = detectEnvironment();
+  if (env.isProduction || env.isCI) return false;
+  return env.isDevelopment && process.env.VIBECHECK_DEV_PRO === "1";
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// RESOLUTION
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Hash API key for cache.
+ * @param {string} key
+ * @returns {string}
+ */
+function hashApiKey(key) {
+  return crypto.createHash("sha256").update(key).digest("hex").slice(0, 16);
+}
+
+/**
+ * Resolve API key from all sources.
+ * @param {string} [directKey] Key passed via --key flag
+ * @returns {{ key: string|null, source: string }}
+ */
+function resolveApiKey(directKey) {
+  // 1. Direct argument
+  if (directKey && isValidKeyFormat(directKey)) {
+    return { key: directKey.trim(), source: "args" };
+  }
+
+  // 2. Environment variable
+  const envKey = process.env.VIBECHECK_API_KEY;
+  if (envKey && isValidKeyFormat(envKey)) {
+    return { key: envKey.trim(), source: "env" };
+  }
+
+  // 3. New auth.json
+  const creds = readCredentials();
+  if (creds?.apiKey && isValidKeyFormat(creds.apiKey)) {
+    return { key: creds.apiKey, source: "file" };
+  }
+
+  // 4. Legacy config.json
+  try {
+    const legacyPath = getLegacyConfigPath();
+    if (fs.existsSync(legacyPath)) {
+      const config = JSON.parse(fs.readFileSync(legacyPath, "utf8"));
+      if (config.apiKey && isValidKeyFormat(config.apiKey)) {
+        return { key: config.apiKey, source: "legacy" };
+      }
+    }
+  } catch {
+    // Ignore
+  }
+
+  return { key: null, source: "none" };
+}
+
+/**
+ * Format source for display.
+ * @param {string} source
+ * @returns {string}
+ */
+function formatSource(source) {
+  switch (source) {
+    case "env": return "Environment Variable";
+    case "file": return "Config File";
+    case "args": return "Command Line";
+    case "legacy": return "Legacy Config";
+    case "none": return "Not Found";
+    default: return source;
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// CACHE HELPERS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+const CACHE_TTL_MS = 10 * 60 * 1000; // 10 minutes
+const STALE_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
+
+/**
+ * Check if cache is valid.
+ * @param {object} cache
+ * @param {string} keyHash
+ * @returns {boolean}
+ */
+function isCacheValid(cache, keyHash) {
+  if (!cache || cache.keyHash !== keyHash) return false;
+  return Date.now() - cache.timestamp < CACHE_TTL_MS;
+}
+
+/**
+ * Check if cache is stale but usable.
+ * @param {object} cache
+ * @param {string} keyHash
+ * @returns {boolean}
+ */
+function isCacheStale(cache, keyHash) {
+  if (!cache || cache.keyHash !== keyHash) return false;
+  const age = Date.now() - cache.timestamp;
+  return age >= CACHE_TTL_MS && age < STALE_TTL_MS;
+}
+
+/**
+ * Get cache age in seconds.
+ * @param {object} cache
+ * @returns {number}
+ */
+function getCacheAge(cache) {
+  if (!cache) return 0;
+  return Math.floor((Date.now() - cache.timestamp) / 1000);
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// AUTH CHECK
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Sleep helper.
+ * @param {number} ms
+ * @returns {Promise<void>}
+ */
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+/**
+ * Calculate retry delay with exponential backoff.
+ * @param {number} attempt
+ * @returns {number}
+ */
+function getRetryDelay(attempt) {
+  const exponentialDelay = BASE_RETRY_DELAY_MS * Math.pow(2, attempt);
+  const jitter = Math.random() * 500;
+  return Math.min(exponentialDelay + jitter, 30000);
+}
+
+/**
+ * Fetch with retry and rate limit handling.
+ * @param {string} apiKey
+ * @param {number} [attempt]
+ * @returns {Promise<object>}
+ */
+async function fetchWithRetry(apiKey, attempt = 0) {
+  const apiUrl = process.env.VIBECHECK_API_URL || "https://api.vibecheckai.dev";
+  
+  // Check rate limit
+  const rateCheck = checkRateLimit();
+  if (rateCheck.limited) {
+    return { ok: false, error: { code: "RATE_LIMITED", retryAfter: rateCheck.retryAfter } };
+  }
+  
+  try {
+    const response = await fetch(`${apiUrl}/v1/auth/whoami`, {
+      headers: { 
+        Authorization: `Bearer ${apiKey}`,
+        "X-Client-Version": "2.0.0",
+      },
+      signal: AbortSignal.timeout(10000),
+    });
+    
+    // Handle rate limiting
+    if (response.status === 429) {
+      const retryAfter = parseInt(response.headers.get("Retry-After") || "60", 10);
+      recordRateLimit(retryAfter);
+      return { ok: false, error: { code: "RATE_LIMITED", retryAfter } };
+    }
+    
+    // Auth errors - don't retry
+    if (response.status === 401) {
+      trackFailedAttempt();
+      auditLog("KEY_INVALID", apiKey, "api");
+      return { ok: false, error: { code: "INVALID_API_KEY" } };
+    }
+    
+    if (response.status === 403) {
+      auditLog("KEY_REVOKED", apiKey, "api");
+      return { ok: false, error: { code: "KEY_REVOKED" } };
+    }
+    
+    // Server errors - retry
+    if (response.status >= 500 && attempt < MAX_RETRIES) {
+      await sleep(getRetryDelay(attempt));
+      return fetchWithRetry(apiKey, attempt + 1);
+    }
+    
+    if (!response.ok) {
+      return { ok: false, error: { code: "API_ERROR", status: response.status } };
+    }
+    
+    clearRateLimitState();
+    resetActivityTracker();
+    
+    const data = await response.json();
+    auditLog("KEY_VALIDATED", apiKey, "api");
+    return { ok: true, data };
+  } catch (err) {
+    // Network error - retry
+    if (attempt < MAX_RETRIES) {
+      await sleep(getRetryDelay(attempt));
+      return fetchWithRetry(apiKey, attempt + 1);
+    }
+    return { ok: false, error: { code: "NETWORK_ERROR" } };
+  }
+}
+
+/**
+ * Comprehensive auth check (for --check flag).
+ * @param {string} [directKey]
+ * @returns {Promise<object>}
+ */
+async function checkAuth(directKey) {
+  // Check for lockout first
+  const lockout = trackFailedAttempt();
+  if (lockout.locked) {
+    // Reset the failed attempt we just added since we're checking lockout
+    resetActivityTracker();
+    return {
+      authenticated: false,
+      tier: "free",
+      source: "none",
+      keyMasked: "****",
+      networkOk: false,
+      cacheValid: false,
+      error: {
+        code: "LOCKED_OUT",
+        message: `Too many failed attempts. Try again in ${lockout.lockoutRemaining}s`,
+        recovery: `Wait ${Math.ceil(lockout.lockoutRemaining / 60)} minutes before retrying`,
+      },
+    };
+  }
+  resetActivityTracker(); // Reset the test attempt we just made
+
+  const resolved = resolveApiKey(directKey);
+
+  // No key found
+  if (!resolved.key) {
+    return {
+      authenticated: false,
+      tier: "free",
+      source: "none",
+      keyMasked: "****",
+      networkOk: false,
+      cacheValid: false,
+      error: {
+        code: "AUTH_REQUIRED",
+        message: "Not logged in",
+        recovery: 'Run "vibecheck login" or set VIBECHECK_API_KEY',
+      },
+    };
+  }
+
+  const keyHash = hashApiKey(resolved.key);
+  const cache = readCache();
+  const creds = readCredentials();
+
+  // Check cache status
+  const cacheValid = cache ? isCacheValid(cache, keyHash) : false;
+  const cacheAge = cache ? getCacheAge(cache) : undefined;
+
+  // Try to validate with API (with retry)
+  const result = await fetchWithRetry(resolved.key);
+  
+  let networkOk = result.ok;
+  let entitlements = result.data || null;
+  let error = null;
+
+  if (!result.ok) {
+    error = {
+      code: result.error?.code || "UNKNOWN",
+      message: getErrorMessage(result.error?.code),
+      recovery: getErrorRecovery(result.error?.code),
+    };
+    
+    // Use cache if available
+    if (cache && (isCacheValid(cache, keyHash) || isCacheStale(cache, keyHash))) {
+      entitlements = cache.data;
+    }
+  }
+
+  // Map plan to tier
+  const tier = entitlements?.plan === "free" || !entitlements?.plan ? "free" : "pro";
+
+  return {
+    authenticated: !!entitlements || !!creds?.apiKey,
+    tier: entitlements?.tier || tier,
+    source: resolved.source,
+    keyMasked: redactApiKey(resolved.key),
+    networkOk,
+    cacheValid,
+    cacheAge,
+    user: entitlements?.user || creds?.user,
+    entitlements,
+    error,
+  };
+}
+
+/**
+ * Get human-readable error message.
+ * @param {string} code
+ * @returns {string}
+ */
+function getErrorMessage(code) {
+  switch (code) {
+    case "RATE_LIMITED": return "Rate limit exceeded";
+    case "INVALID_API_KEY": return "Invalid API key";
+    case "KEY_REVOKED": return "API key has been revoked";
+    case "KEY_EXPIRED": return "API key has expired";
+    case "NETWORK_ERROR": return "Cannot connect to API";
+    case "LOCKED_OUT": return "Too many failed attempts";
+    default: return "Authentication error";
+  }
+}
+
+/**
+ * Get error recovery message.
+ * @param {string} code
+ * @returns {string}
+ */
+function getErrorRecovery(code) {
+  switch (code) {
+    case "RATE_LIMITED": return "Wait and try again";
+    case "INVALID_API_KEY": return "Check your API key format";
+    case "KEY_REVOKED": return "Generate a new key at vibecheckai.dev/settings/keys";
+    case "KEY_EXPIRED": return "Generate a new key at vibecheckai.dev/settings/keys";
+    case "NETWORK_ERROR": return "Check your network. Offline mode uses cached data.";
+    case "LOCKED_OUT": return "Wait before retrying";
+    default: return 'Run "vibecheck login" to re-authenticate';
+  }
+}
+
+/**
+ * Refresh entitlements (for --refresh flag).
+ * @param {string} [directKey]
+ * @returns {Promise<object|null>}
+ */
+async function refreshEntitlements(directKey) {
+  const resolved = resolveApiKey(directKey);
+
+  if (!resolved.key) {
+    return null;
+  }
+
+  const keyHash = hashApiKey(resolved.key);
+
+  try {
+    const apiUrl = process.env.VIBECHECK_API_URL || "https://api.vibecheckai.dev";
+    const response = await fetch(`${apiUrl}/v1/auth/whoami`, {
+      headers: { Authorization: `Bearer ${resolved.key}` },
+      signal: AbortSignal.timeout(10000),
+    });
+
+    if (!response.ok) {
+      return null;
+    }
+
+    const entitlements = await response.json();
+
+    // Update cache
+    writeCache({
+      keyHash,
+      timestamp: Date.now(),
+      data: entitlements,
+    });
+
+    // Update stored credentials
+    const creds = readCredentials() || { version: 2, keySource: "file" };
+    writeCredentials({
+      ...creds,
+      user: entitlements.user,
+      tier: entitlements.tier || (entitlements.plan === "free" ? "free" : "pro"),
+      lastValidated: new Date().toISOString(),
+    });
+
+    return entitlements;
+  } catch {
+    return null;
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// EXPORTS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+module.exports = {
+  // Paths
+  getConfigDir,
+  getAuthPath,
+  getCachePath,
+  getLegacyConfigPath,
+  
+  // Redaction
+  redactApiKey,
+  redactOutput,
+  
+  // Validation
+  validateKeyFormat,
+  isValidKeyFormat,
+  sanitizeInput,
+  
+  // Storage
+  ensureConfigDir,
+  readCredentials,
+  writeCredentials,
+  deleteCredentials,
+  readCache,
+  writeCache,
+  deleteCache,
+  clearAll,
+  
+  // Resolution
+  hashApiKey,
+  resolveApiKey,
+  formatSource,
+  
+  // Cache
+  isCacheValid,
+  isCacheStale,
+  getCacheAge,
+  CACHE_TTL_MS,
+  STALE_TTL_MS,
+  
+  // Rate limiting
+  checkRateLimit,
+  recordRateLimit,
+  clearRateLimitState,
+  
+  // Activity tracking
+  trackFailedAttempt,
+  resetActivityTracker,
+  
+  // Audit
+  auditLog,
+  
+  // Environment
+  detectEnvironment,
+  isDevBypassAllowed,
+  
+  // Auth
+  checkAuth,
+  refreshEntitlements,
+};