@vibecheckai/cli 3.5.0 → 3.5.2

package/mcp-server/tier-auth.js

@@ -1,14 +1,42 @@
 /**
  * MCP Server Tier Authentication
  * 
+ * ═══════════════════════════════════════════════════════════════════════════
+ * TIER MODEL - Aligned with CLI entitlements-v2.js
+ * ═══════════════════════════════════════════════════════════════════════════
+ * 
  * Simple 2-tier model:
  * - FREE ($0): Inspect & Observe
  * - PRO ($69/mo): Fix, Prove & Enforce
  * 
- * PRO includes:
- * - Authority System (verdicts, approvals)
- * - Agent Conductor (multi-agent coordination)
- * - Agent Firewall (enforce mode)
+ * ┌────────────────────────────────────────────────────────────────────────┐
+ * │ MCP Tool                        │ Tier │ CLI Equivalent               │
+ * ├────────────────────────────────────────────────────────────────────────┤
+ * │ vibecheck.scan                  │ FREE │ scan                         │
+ * │ vibecheck.scan (--autofix)      │ PRO  │ scan.autofix                 │
+ * │ vibecheck.ctx                   │ FREE │ ctx                          │
+ * │ vibecheck.verify                │ FREE │ verify                       │
+ * │ vibecheck.report                │ FREE │ report                       │
+ * │ vibecheck.status                │ FREE │ status                       │
+ * │ vibecheck.doctor                │ FREE │ doctor                       │
+ * │ vibecheck.firewall (observe)    │ FREE │ firewall.observe             │
+ * │ vibecheck.firewall (enforce)    │ PRO  │ firewall.enforce             │
+ * │ vibecheck.ship                  │ PRO  │ ship                         │
+ * │ vibecheck.fix                   │ PRO  │ fix                          │
+ * │ vibecheck.fix (--apply)         │ PRO  │ fix.apply                    │
+ * │ vibecheck.prove                 │ PRO  │ prove                        │
+ * │ vibecheck.gate                  │ PRO  │ gate                         │
+ * │ vibecheck.badge                 │ PRO  │ badge                        │
+ * │ vibecheck.reality               │ PRO  │ reality.full                 │
+ * │ vibecheck.ai_test               │ PRO  │ ai-test                      │
+ * │ vibecheck.share                 │ PRO  │ share                        │
+ * │ authority.list                  │ FREE │ (read-only authority)        │
+ * │ authority.classify              │ FREE │ (inventory analysis)         │
+ * │ authority.approve               │ PRO  │ (execute authority)          │
+ * │ vibecheck_conductor_status      │ FREE │ (status only)                │
+ * │ vibecheck_conductor_*           │ PRO  │ (full coordination)          │
+ * │ vibecheck_agent_firewall_*      │ PRO  │ (enforce mode)               │
+ * └────────────────────────────────────────────────────────────────────────┘
  */
 
 import fs from "fs/promises";
@@ -16,7 +44,17 @@ import path from "path";
 import os from "os";
 
 // ============================================================================
-// TIERS
+// ERROR CODES - Standard error envelope codes
+// ============================================================================
+export const ERROR_CODES = {
+  NOT_ENTITLED: 'NOT_ENTITLED',
+  INVALID_API_KEY: 'INVALID_API_KEY',
+  RATE_LIMITED: 'RATE_LIMITED',
+  OPTION_NOT_ENTITLED: 'OPTION_NOT_ENTITLED',
+};
+
+// ============================================================================
+// TIERS - Simple 2-tier model matching CLI
 // ============================================================================
 export const TIERS = {
   free: { name: 'FREE', price: 0 },
@@ -24,43 +62,68 @@ export const TIERS = {
 };
 
 // ============================================================================
-// MCP TOOLS - 15 Core + PRO Features
+// MCP TOOLS - Aligned with CLI entitlements-v2.js
 // ============================================================================
 
 /**
- * FREE TOOLS (7) - Inspect & Observe
+ * FREE TOOLS - Inspect & Observe
+ * Matches CLI FREE_FEATURES: scan, ctx, verify, report, status, doctor, etc.
  */
 export const FREE_TOOLS = [
-  // Core FREE tools
+  // Core analysis (CLI: scan, ctx, verify)
   'vibecheck.scan',
   'vibecheck.ctx',
   'vibecheck.verify',
+  
+  // Reports & setup (CLI: report, status, doctor)
   'vibecheck.report',
   'vibecheck.status',
   'vibecheck.doctor',
-  'vibecheck.firewall',           // Observe mode only
+  
+  // Firewall observe mode (CLI: firewall.observe)
+  'vibecheck.firewall',
+  
   // Authority (read-only)
   'authority.list',
   'authority.classify',
+  
   // Conductor (status only)
   'vibecheck_conductor_status',
+  
+  // Labs & experimental (CLI: labs, mdc)
+  'vibecheck.labs',
+  'vibecheck.mdc',
+  
+  // Allowlist management
+  'vibecheck.allowlist',
+  
+  // Context generation (basic - CLI: ctx)
+  'vibecheck.context',
+  
+  // Next action recommendation
+  'vibecheck.get_next_action',
 ];
 
 /**
- * PRO TOOLS (8 Core + Authority + Conductor + Firewall) - Fix, Prove & Enforce
+ * PRO TOOLS - Fix, Prove & Enforce
+ * Matches CLI PRO_FEATURES: ship, fix, prove, gate, badge, etc.
  */
 export const PRO_TOOLS = [
-  // Core PRO tools
+  // Core PRO (CLI: ship, fix, prove, gate, badge)
   'vibecheck.ship',
   'vibecheck.fix',
   'vibecheck.prove',
   'vibecheck.gate',
   'vibecheck.badge',
+  
+  // Runtime verification (CLI: reality.full, ai-test)
   'vibecheck.reality',
   'vibecheck.ai_test',
+  
+  // Sharing & PR (CLI: share, pr)
   'vibecheck.share',
   
-  // Authority System (full)
+  // Authority System (full - execute verdicts)
   'authority.approve',
   'authority.enforce',
   
@@ -71,31 +134,158 @@ export const PRO_TOOLS = [
   'vibecheck_conductor_propose',
   'vibecheck_conductor_terminate',
   
-  // Agent Firewall (enforce mode)
+  // Agent Firewall (enforce mode - CLI: firewall.enforce)
   'vibecheck_agent_firewall_intercept',
   'vibecheck.firewall.enforce',
+  
+  // Advanced features (CLI: checkpoint, polish, guard)
+  'vibecheck.checkpoint',
+  'vibecheck.polish',
+  'vibecheck.guard',
 ];
 
 export const ALL_TOOLS = [...FREE_TOOLS, ...PRO_TOOLS];
 
+/**
+ * OPTION-LEVEL GATES
+ * Some tools are FREE at base level but specific options require PRO
+ */
+export const OPTION_GATES = {
+  'vibecheck.scan': {
+    autofix: 'pro',      // scan --autofix requires PRO
+    fix: 'pro',          // scan --fix requires PRO
+  },
+  'vibecheck.fix': {
+    apply: 'pro',        // fix --apply requires PRO (plan is PRO too)
+    loop: 'pro',         // fix --loop requires PRO
+  },
+  'vibecheck.firewall': {
+    enforce: 'pro',      // firewall --enforce requires PRO
+    mode: { enforce: 'pro' },
+  },
+  'vibecheck.reality': {
+    full: 'pro',         // reality full mode requires PRO
+    auth: 'pro',         // auth boundary testing requires PRO
+  },
+};
+
 // ============================================================================
 // TIER CACHE
 // ============================================================================
 const tierCache = new Map();
 const CACHE_TTL = 5 * 60 * 1000; // 5 minutes
 
+/**
+ * Check if developer mode bypass is allowed.
+ * 
+ * SECURITY: VIBECHECK_DEV_PRO is ONLY allowed in non-production environments.
+ * This prevents environment variable injection from granting PRO access in production.
+ * 
+ * @returns {{ enabled: boolean, tier?: string }} Dev override status
+ */
+export function getDevModeOverride() {
+  // SECURITY: Never allow dev override in production
+  if (process.env.NODE_ENV === 'production') {
+    return { enabled: false };
+  }
+  // Also block in CI environments to prevent pipeline exploitation
+  if (process.env.CI === 'true' || process.env.CI === '1') {
+    return { enabled: false };
+  }
+  // Only in development with explicit flag
+  if (process.env.VIBECHECK_DEV_PRO === '1' && process.env.NODE_ENV === 'development') {
+    console.warn('[DEV] VIBECHECK_DEV_PRO override active - PRO features unlocked');
+    return { enabled: true, tier: 'pro' };
+  }
+  return { enabled: false };
+}
+
+/**
+ * Check if developer mode bypass is allowed (legacy function for backward compatibility)
+ * @returns {boolean} True only if in development AND VIBECHECK_DEV_PRO=1
+ */
+function isDevProBypassAllowed() {
+  return getDevModeOverride().enabled;
+}
+
 function hashKey(apiKey) {
   const crypto = require('crypto');
   return crypto.createHash('sha256').update(apiKey).digest('hex').slice(0, 16);
 }
 
+// ============================================================================
+// ERROR ENVELOPE - Standard format for tier errors
+// ============================================================================
+
+/**
+ * Create a standard ErrorEnvelope for tier-related errors
+ * @param {string} code - Error code (NOT_ENTITLED, INVALID_API_KEY, etc.)
+ * @param {string} message - Human-readable error message
+ * @param {object} extra - Additional properties
+ * @returns {object} ErrorEnvelope
+ */
+export function createTierErrorEnvelope(code, message, extra = {}) {
+  return {
+    code,
+    message,
+    userAction: extra.userAction || 'Open billing',
+    retryable: extra.retryable ?? false,
+    tier: extra.tier,
+    required: extra.required,
+    upgradeUrl: 'https://vibecheckai.dev/pricing',
+    ...extra,
+  };
+}
+
+/**
+ * Create NOT_ENTITLED error envelope
+ */
+export function notEntitledError(toolName, currentTier = 'free', requiredTier = 'pro') {
+  return createTierErrorEnvelope(ERROR_CODES.NOT_ENTITLED, `Requires ${requiredTier.toUpperCase()}`, {
+    tier: currentTier,
+    required: requiredTier,
+    tool: toolName,
+    userAction: 'Open billing',
+    retryable: false,
+    nextSteps: [
+      `Upgrade to ${requiredTier.toUpperCase()} ($69/mo) to unlock this feature`,
+      'Visit https://vibecheckai.dev/pricing',
+      'Run: vibecheck upgrade',
+    ],
+  });
+}
+
+/**
+ * Create OPTION_NOT_ENTITLED error envelope
+ */
+export function optionNotEntitledError(toolName, option, currentTier = 'free', requiredTier = 'pro') {
+  return createTierErrorEnvelope(ERROR_CODES.OPTION_NOT_ENTITLED, `Option --${option} requires ${requiredTier.toUpperCase()}`, {
+    tier: currentTier,
+    required: requiredTier,
+    tool: toolName,
+    option,
+    userAction: 'Open billing',
+    retryable: false,
+    nextSteps: [
+      `The --${option} flag requires ${requiredTier.toUpperCase()} subscription`,
+      `Base ${toolName} is available on FREE tier`,
+      'Visit https://vibecheckai.dev/pricing to upgrade',
+    ],
+  });
+}
+
 // ============================================================================
 // TIER VALIDATION
 // ============================================================================
 
 export async function getTierFromApiKey(apiKey) {
+  // Developer mode bypass (blocked in production)
+  if (isDevProBypassAllowed()) {
+    return 'pro';
+  }
+  
   if (!apiKey || typeof apiKey !== 'string' || apiKey.length < 10) {
-    return null;
+    return 'free'; // No API key = free tier (not null)
   }
   
   const keyHash = hashKey(apiKey);
@@ -109,28 +299,30 @@ export async function getTierFromApiKey(apiKey) {
   
   // Validate with API
   try {
-    const response = await fetch('https://api.vibecheckai.dev/whoami', {
+    const response = await fetch('https://api.vibecheckai.dev/v1/auth/whoami', {
       headers: { 'Authorization': `Bearer ${apiKey}` },
       signal: AbortSignal.timeout(10000),
     });
     
     if (!response.ok) {
-      return null;
+      // Invalid key - default to free
+      tierCache.set(keyHash, { tier: 'free', expiresAt: now + 60000 }); // Short cache for invalid
+      return 'free';
     }
     
     const data = await response.json();
-    const plan = data.plan?.toLowerCase() || 'free';
+    const plan = data.plan?.toLowerCase() || data.tier?.toLowerCase() || 'free';
     
-    // Any paid plan = pro
+    // Map any paid plan to 'pro' (STARTER, PRO, ENTERPRISE all = pro)
     const tier = (plan === 'free') ? 'free' : 'pro';
     
     tierCache.set(keyHash, { tier, expiresAt: now + CACHE_TTL });
     return tier;
     
   } catch {
-    // Network error - check stale cache
+    // Network error - check stale cache or default to free
     if (cached) return cached.tier;
-    return null;
+    return 'free';
   }
 }
 
@@ -139,10 +331,15 @@ export async function getTierFromApiKey(apiKey) {
 // ============================================================================
 
 export function isPro(tier) {
+  // Developer mode bypass (blocked in production)
+  if (isDevProBypassAllowed()) return true;
   return tier === 'pro';
 }
 
 export function canAccessTool(tier, toolName) {
+  // Developer mode bypass (blocked in production)
+  if (isDevProBypassAllowed()) return true;
+  
   // PRO gets everything
   if (tier === 'pro') return true;
   
@@ -150,59 +347,110 @@ export function canAccessTool(tier, toolName) {
   return FREE_TOOLS.includes(toolName);
 }
 
+/**
+ * Check option-level access
+ * @param {string} tier - User tier
+ * @param {string} toolName - Tool name
+ * @param {object} args - Tool arguments
+ * @returns {{ allowed: boolean, blockedOption?: string, required?: string }}
+ */
+export function checkOptionAccess(tier, toolName, args) {
+  // Developer mode (blocked in production) or PRO = full access
+  if (isDevProBypassAllowed() || tier === 'pro') {
+    return { allowed: true };
+  }
+  
+  const gates = OPTION_GATES[toolName];
+  if (!gates || !args) {
+    return { allowed: true };
+  }
+  
+  // Check each gated option
+  for (const [option, requiredTier] of Object.entries(gates)) {
+    // Handle nested object gates (e.g., mode: { enforce: 'pro' })
+    if (typeof requiredTier === 'object') {
+      const argValue = args[option];
+      if (argValue && requiredTier[argValue] === 'pro') {
+        return { allowed: false, blockedOption: `${option}=${argValue}`, required: 'pro' };
+      }
+    } else if (args[option] === true && requiredTier === 'pro') {
+      return { allowed: false, blockedOption: option, required: 'pro' };
+    }
+  }
+  
+  return { allowed: true };
+}
+
 /**
  * Get firewall mode based on tier
  * - FREE: observe (log only)
  * - PRO: enforce (block violations)
  */
 export function getFirewallMode(tier) {
+  if (isDevProBypassAllowed()) return 'enforce';
   return tier === 'pro' ? 'enforce' : 'observe';
 }
 
 /**
  * Check if user can use full conductor features
  */
-export function canUseCondcutor(tier) {
+export function canUseConductor(tier) {
+  if (isDevProBypassAllowed()) return true;
   return tier === 'pro';
 }
 
+// Legacy alias (typo fix)
+export const canUseCondcutor = canUseConductor;
+
 /**
  * Check if user can approve authorities
  */
 export function canApproveAuthority(tier) {
+  if (isDevProBypassAllowed()) return true;
   return tier === 'pro';
 }
 
-export async function getMcpToolAccess(toolName, apiKey) {
-  if (!apiKey) {
+/**
+ * Get MCP tool access with full ErrorEnvelope support
+ * 
+ * @param {string} toolName - Tool name
+ * @param {string} apiKey - API key (optional)
+ * @param {object} args - Tool arguments for option-level checks
+ * @returns {Promise<{hasAccess: boolean, tier: string, error?: object}>}
+ */
+export async function getMcpToolAccess(toolName, apiKey, args = {}) {
+  const tier = await getTierFromApiKey(apiKey);
+  
+  // Check tool-level access
+  const hasToolAccess = canAccessTool(tier, toolName);
+  
+  if (!hasToolAccess) {
     return {
-      hasAccess: FREE_TOOLS.includes(toolName),
-      tier: 'free',
-      reason: FREE_TOOLS.includes(toolName) 
-        ? 'Access granted (free tool)'
-        : 'This tool requires Pro. Set API key with `vibecheck login`.',
+      hasAccess: false,
+      tier,
+      firewallMode: getFirewallMode(tier),
+      error: notEntitledError(toolName, tier, 'pro'),
+      reason: `${toolName} requires Pro ($69/mo). Upgrade at https://vibecheckai.dev/pricing`,
     };
   }
   
-  const tier = await getTierFromApiKey(apiKey);
-  
-  if (!tier) {
+  // Check option-level access
+  const optionCheck = checkOptionAccess(tier, toolName, args);
+  if (!optionCheck.allowed) {
     return {
       hasAccess: false,
-      tier: null,
-      reason: 'Invalid API key.',
+      tier,
+      firewallMode: getFirewallMode(tier),
+      error: optionNotEntitledError(toolName, optionCheck.blockedOption, tier, optionCheck.required),
+      reason: `Option --${optionCheck.blockedOption} requires Pro`,
     };
   }
   
-  const hasAccess = canAccessTool(tier, toolName);
-  
   return {
-    hasAccess,
+    hasAccess: true,
     tier,
     firewallMode: getFirewallMode(tier),
-    reason: hasAccess
-      ? 'Access granted'
-      : `${toolName} requires Pro ($69/mo). Upgrade at https://vibecheckai.dev/pricing`,
+    reason: 'Access granted',
   };
 }
 
@@ -210,17 +458,27 @@ export async function getMcpToolAccess(toolName, apiKey) {
 // MIDDLEWARE
 // ============================================================================
 
+/**
+ * Middleware that wraps a tool handler with tier checking
+ * Returns proper ErrorEnvelope on failure
+ */
 export function withTierCheck(toolName, handler) {
   return async (args) => {
-    const access = await getMcpToolAccess(toolName, args?.apiKey);
+    const access = await getMcpToolAccess(toolName, args?.apiKey, args);
     
     if (!access.hasAccess) {
+      // Return proper ErrorEnvelope format
       return {
         content: [{
           type: "text",
-          text: `This tool requires Pro.\n\n${toolName} is a Pro feature.\n\nUpgrade to Pro ($69/mo) to unlock:\n- Authority System (verdicts & approvals)\n- Agent Conductor (multi-agent coordination)\n- Agent Firewall (enforce mode)\n\nhttps://vibecheckai.dev/pricing`
+          text: JSON.stringify({
+            ok: false,
+            error: access.error,
+          }, null, 2)
         }],
-        isError: true
+        isError: true,
+        // Also include error envelope at top level for structured access
+        _error: access.error,
       };
     }
     
@@ -230,6 +488,29 @@ export function withTierCheck(toolName, handler) {
   };
 }
 
+/**
+ * Create tier gate response for direct use in handlers
+ * Returns null if access granted, ErrorEnvelope if denied
+ */
+export async function checkTierGate(toolName, apiKey, args = {}) {
+  const access = await getMcpToolAccess(toolName, apiKey, args);
+  
+  if (!access.hasAccess) {
+    return {
+      content: [{
+        type: "text",
+        text: JSON.stringify({
+          ok: false,
+          error: access.error,
+        }, null, 2)
+      }],
+      isError: true,
+    };
+  }
+  
+  return null; // Access granted
+}
+
 // ============================================================================
 // USER INFO
 // ============================================================================
@@ -276,11 +557,63 @@ export async function getAvailableMcpTools(apiKey) {
   };
 }
 
-// Legacy exports for backward compatibility
-export async function getFeatureAccessStatus(featureName, apiKey) {
-  return getMcpToolAccess(featureName, apiKey);
+// ============================================================================
+// LEGACY EXPORTS - Backward compatibility
+// ============================================================================
+
+/**
+ * @deprecated Use getMcpToolAccess instead
+ */
+export async function getFeatureAccessStatus(featureName, apiKey, args = {}) {
+  const result = await getMcpToolAccess(featureName, apiKey, args);
+  // Add upgradeUrl for legacy consumers
+  return {
+    ...result,
+    upgradeUrl: 'https://vibecheckai.dev/pricing',
+  };
 }
 
+/**
+ * @deprecated Use withTierCheck instead
+ */
 export function withMcpToolCheck(toolName, handler) {
   return withTierCheck(toolName, handler);
 }
+
+// ============================================================================
+// TOOL TIER MAPPING - For documentation and testing
+// ============================================================================
+
+/**
+ * Get the tier requirements table for all MCP tools
+ * Used for documentation and test generation
+ */
+export function getToolTierTable() {
+  const table = [];
+  
+  for (const tool of FREE_TOOLS) {
+    table.push({ tool, tier: 'FREE', options: OPTION_GATES[tool] || null });
+  }
+  
+  for (const tool of PRO_TOOLS) {
+    table.push({ tool, tier: 'PRO', options: null });
+  }
+  
+  return table;
+}
+
+/**
+ * Print formatted tier table (for CLI/debugging)
+ */
+export function printTierTable() {
+  console.log('┌────────────────────────────────────┬──────┬─────────────────────────┐');
+  console.log('│ MCP Tool                           │ Tier │ Gated Options           │');
+  console.log('├────────────────────────────────────┼──────┼─────────────────────────┤');
+  
+  for (const { tool, tier, options } of getToolTierTable()) {
+    const optStr = options ? Object.keys(options).join(', ') : '-';
+    console.log(`│ ${tool.padEnd(34)} │ ${tier.padEnd(4)} │ ${optStr.padEnd(23)} │`);
+  }
+  
+  console.log('└────────────────────────────────────┴──────┴─────────────────────────┘');
+}