@l4yercak3/cli 1.1.12 → 1.2.0

package/docs/mcp_server/ontologySchemas.ts

@@ -0,0 +1,185 @@
+/**
+ * ONTOLOGY SCHEMAS
+ *
+ * Universal object storage system for ALL data types.
+ * This replaces separate tables with a unified object model.
+ *
+ * Core Concepts:
+ * - objects: Universal storage for any entity (translations, events, contacts, etc.)
+ * - objectLinks: Relationships between objects (like graph edges)
+ * - objectActions: Audit trail of actions performed on objects
+ */
+
+import { defineTable } from "convex/server";
+import { v } from "convex/values";
+
+/**
+ * OBJECTS TABLE
+ * Universal storage for all entity types
+ *
+ * Examples:
+ * - type="translation", subtype="system", name="desktop.welcome"
+ * - type="event", subtype="podcast", name="Episode 42"
+ * - type="invoice", subtype="client", name="INV-2024-001"
+ * - type="contact", subtype="customer", name="John Doe"
+ * - type="transaction", subtype="ticket_purchase", name="Product - Customer"
+ *
+ * TRANSACTION OBJECT STRUCTURE:
+ * Transactions (type="transaction") store purchase data in customProperties.
+ *
+ * NEW STRUCTURE (v2 - Multi-line Item Transactions):
+ * One transaction per checkout with multiple line items:
+ * {
+ *   checkoutSessionId: Id<"objects">,
+ *   lineItems: [
+ *     {
+ *       productId: Id<"objects">,
+ *       productName: string,
+ *       productDescription?: string,
+ *       quantity: number,
+ *       unitPriceInCents: number,        // Net price per unit
+ *       totalPriceInCents: number,       // Net total for this line (unitPrice * quantity)
+ *       taxRatePercent: number,
+ *       taxAmountInCents: number,
+ *       ticketId?: Id<"objects">,        // If this is a ticket product
+ *       eventId?: Id<"objects">,
+ *       eventName?: string,
+ *     },
+ *     // ... more line items
+ *   ],
+ *   subtotalInCents: number,             // Sum of all line item totals (net)
+ *   taxAmountInCents: number,            // Sum of all line item taxes
+ *   totalInCents: number,                // Grand total (subtotal + tax)
+ *   currency: string,
+ *   customerName: string,
+ *   customerEmail: string,
+ *   payerType: "individual" | "organization",
+ *   paymentMethod: string,
+ *   paymentStatus: string,
+ *   invoicingStatus: "pending" | "on_draft_invoice" | "invoiced",
+ *   // ... other customer/payer fields
+ * }
+ *
+ * LEGACY STRUCTURE (v1 - Single Product Per Transaction):
+ * DEPRECATED: Old approach created one transaction per product.
+ * Kept for backward compatibility with existing data.
+ * {
+ *   productId: Id<"objects">,
+ *   productName: string,
+ *   quantity: number,
+ *   amountInCents: number,               // Total for this ONE product
+ *   currency: string,
+ *   taxRatePercent: number,
+ *   // ... single product fields
+ * }
+ */
+export const objects = defineTable({
+  // Multi-tenancy
+  organizationId: v.id("organizations"),
+
+  // Object Identity
+  type: v.string(),              // "translation", "event", "invoice", "contact", etc.
+  subtype: v.optional(v.string()), // "system", "app", "content", etc.
+
+  // Universal Properties (ALL objects have these)
+  name: v.string(),              // Human-readable identifier
+  description: v.optional(v.string()),
+  status: v.string(),            // Object-specific statuses
+
+  // Translation-Specific Fields (only used when type="translation")
+  locale: v.optional(v.string()),     // "en", "de", "pl"
+  value: v.optional(v.string()),      // Translation text
+
+  // Gravel Road - Per-Org/Per-Type Customizations
+  // This allows each organization to add their own fields without schema changes
+  customProperties: v.optional(v.record(v.string(), v.any())),
+
+  // Metadata
+  // createdBy can be either platform user (staff) or frontend_user (customer)
+  // - Platform user (Id<"users">): When staff creates records administratively
+  // - Frontend user (Id<"objects">): When customers create records (guest registration, checkout)
+  createdBy: v.optional(v.union(v.id("users"), v.id("objects"))),
+  createdAt: v.number(),
+  updatedAt: v.number(),
+})
+  // Core indexes for fast queries
+  .index("by_org", ["organizationId"])
+  .index("by_org_type", ["organizationId", "type"])
+  .index("by_org_type_subtype", ["organizationId", "type", "subtype"])
+  .index("by_type", ["type"])
+  .index("by_type_subtype", ["type", "subtype"])
+  .index("by_status", ["status"])
+
+  // Translation-specific indexes
+  .index("by_org_type_locale", ["organizationId", "type", "locale"])
+  .index("by_org_type_locale_name", ["organizationId", "type", "locale", "name"])
+  .index("by_type_locale", ["type", "locale"])
+
+  // Search indexes
+  .searchIndex("search_by_name", { searchField: "name" })
+  .searchIndex("search_by_value", { searchField: "value" });
+
+/**
+ * OBJECT LINKS TABLE
+ * Relationships between objects (graph edges)
+ *
+ * Examples:
+ * - fromObjectId=translation1, toObjectId=event1, linkType="translates"
+ * - fromObjectId=user1, toObjectId=org1, linkType="member_of"
+ * - fromObjectId=org1, toObjectId=address1, linkType="has_address"
+ * - fromObjectId=contact1, toObjectId=event1, linkType="registers_for"
+ */
+export const objectLinks = defineTable({
+  organizationId: v.id("organizations"),
+
+  // Link Endpoints
+  fromObjectId: v.id("objects"),
+  toObjectId: v.id("objects"),
+
+  // Link Type (the "verb" in the relationship)
+  linkType: v.string(), // "translates", "member_of", "has_address", "registers_for", etc.
+
+  // Link-Specific Data
+  // Store additional metadata about the relationship
+  properties: v.optional(v.record(v.string(), v.any())),
+
+  // Metadata
+  // createdBy can be platform user or frontend_user (same as objects table)
+  createdBy: v.optional(v.union(v.id("users"), v.id("objects"))),
+  createdAt: v.number(),
+})
+  .index("by_from_object", ["fromObjectId"])
+  .index("by_to_object", ["toObjectId"])
+  .index("by_org_link_type", ["organizationId", "linkType"])
+  .index("by_from_link_type", ["fromObjectId", "linkType"])
+  .index("by_to_link_type", ["toObjectId", "linkType"]);
+
+/**
+ * OBJECT ACTIONS TABLE
+ * Audit trail of actions performed on objects
+ *
+ * Examples:
+ * - objectId=translation1, actionType="approve", performedBy=user1
+ * - objectId=event1, actionType="publish", performedBy=user2
+ * - objectId=invoice1, actionType="send", performedBy=user3
+ */
+export const objectActions = defineTable({
+  organizationId: v.id("organizations"),
+  objectId: v.id("objects"),
+
+  // Action Identity
+  actionType: v.string(), // "approve", "translate", "publish", "view", "edit", etc.
+
+  // Action Data
+  // Store details about what changed
+  actionData: v.optional(v.record(v.string(), v.any())),
+
+  // Who & When
+  // performedBy can be platform user or frontend_user (same as objects table)
+  performedBy: v.optional(v.union(v.id("users"), v.id("objects"))),
+  performedAt: v.number(),
+})
+  .index("by_object", ["objectId"])
+  .index("by_org_action_type", ["organizationId", "actionType"])
+  .index("by_performer", ["performedBy"])
+  .index("by_performed_at", ["performedAt"]);

package/docs/mcp_server/schema.ts

@@ -0,0 +1,250 @@
+/**
+ * ORGANIZED SCHEMA STRUCTURE
+ *
+ * This schema is composed from modular definitions in the schemas/ directory.
+ * See schemas/README.md for documentation on adding new apps.
+ *
+ * Structure:
+ * 1. Core platform (users, organizations, memberships)
+ * 2. App Store (apps registry, installations, purchases)
+ * 3. Individual Apps (l4yercak3pod, etc. - each is self-contained)
+ * 4. Utilities (audit logs)
+ */
+
+import { defineSchema } from "convex/server";
+
+// Import modular schema definitions
+import {
+  users,
+  organizations,
+  organizationMembers,
+  userPasswords,
+  sessions,
+  frontendSessions,
+  passkeys,
+  passkeysChallenges,
+  apiKeys,
+  roles,
+  permissions,
+  rolePermissions,
+  userPreferences,
+  organizationMedia,
+  oauthConnections,
+  oauthStates,
+  cliSessions,
+  cliLoginStates,
+  oauthSignupStates,
+  webhookSubscriptions
+} from "./schemas/coreSchemas";
+// NOTE: apiKeyDomains table removed - now using unified domain configurations in objects table
+import { apps, appInstallations, snapshots, snapshotLoads, purchases, appAvailabilities } from "./schemas/appStoreSchemas";
+// import { app_podcasting } from "./schemas/appDataSchemas"; // Not yet used
+import { auditLogs, workflowExecutionLogs } from "./schemas/utilitySchemas";
+
+// ✅ NEW ONTOLOGY SCHEMAS
+import { objects, objectLinks, objectActions } from "./schemas/ontologySchemas";
+
+// 🤖 AI INTEGRATION SCHEMAS
+import {
+  aiConversations,
+  aiMessages,
+  aiToolExecutions,
+  organizationAiSettings,
+  aiAgentTasks,
+  aiAgentMemory,
+  aiModels,
+  aiWorkItems
+} from "./schemas/aiSchemas";
+
+// 💳 AI BILLING SCHEMAS v3.1 (VAT-inclusive pricing, EUR only)
+import {
+  aiUsage,
+  aiSubscriptions,
+  aiTokenBalance,
+  aiTokenPurchases,
+  aiBudgetAlerts,
+  aiBillingEvents
+} from "./schemas/aiBillingSchemas";
+
+// 👤 USER QUOTA SCHEMAS (Phase 1: Foundation for per-user limits)
+import { userAIQuotas } from "./schemas/userQuotaSchemas";
+
+// 💾 STORAGE TRACKING SCHEMAS (Organization + per-user storage)
+import { organizationStorage, userStorageQuotas } from "./schemas/storageSchemas";
+
+// 📧 CONTACT SYNC & BULK EMAIL SCHEMAS (AI-powered external contact integration)
+import { contactSyncs, emailCampaigns } from "./schemas/contactSyncSchemas";
+
+// 🔐 OAUTH 2.0 SCHEMAS (OAuth authentication for third-party integrations)
+import {
+  oauthApplications,
+  oauthAuthorizationCodes,
+  oauthRefreshTokens,
+  oauthRevokedTokens,
+  oauthTokenUsage
+} from "./schemas/oauthSchemas";
+
+// 🚦 RATE LIMITING SCHEMAS (Token bucket rate limiting for API abuse prevention)
+import { rateLimitSchemas } from "./schemas/rateLimitSchemas";
+
+// 🛡️ SECURITY SCHEMAS (Anomaly detection and security event monitoring)
+import { securitySchemas } from "./schemas/securitySchemas";
+
+// 📊 GROWTH TRACKING SCHEMAS (Launch metrics and KPI tracking)
+import {
+  dailyGrowthMetrics,
+  signupEvents,
+  weeklyScorecard,
+  salesNotifications,
+  celebrationMilestones
+} from "./schemas/growthTrackingSchemas";
+
+// 📧 EMAIL QUEUE SCHEMA (Email delivery tracking)
+import { emailQueue } from "./schemas/emailQueueSchemas";
+
+// 🎁 BENEFITS PLATFORM SCHEMAS (Benefits & Commissions tracking)
+import {
+  benefitClaims,
+  commissionPayouts,
+  memberWallets,
+  platformFees
+} from "./schemas/benefitsSchemas";
+
+/**
+ * MAIN SCHEMA EXPORT
+ *
+ * All tables are defined in their respective schema modules.
+ * This file simply composes them together.
+ */
+export default defineSchema({
+  // 👥 CORE: Platform foundation
+  users,
+  organizations,
+  organizationMembers,
+  userPasswords,
+  sessions,
+  frontendSessions, // Customer user sessions (separate from platform staff)
+  passkeys,
+  passkeysChallenges,
+  apiKeys,
+  // Domain configurations (including API access, email, branding) stored in objects table
+  userPreferences,
+  organizationMedia,
+  oauthConnections,
+  oauthStates,
+  cliSessions,
+  cliLoginStates,
+  oauthSignupStates,
+  webhookSubscriptions,
+
+  // 🔐 RBAC: Role-Based Access Control
+  roles,
+  permissions,
+  rolePermissions,
+
+  // 🏪 APP STORE: Marketplace functionality
+  apps,
+  appInstallations,
+  appAvailabilities,
+  snapshots,
+  snapshotLoads,
+  purchases,
+
+  // 📱 APPS: Individual app data tables
+  // Each app is self-contained with its own table
+  // All apps follow the appSchemaBase pattern (see schemas/appSchemaBase.ts)
+  // NAMING: Always prefix with "app_"
+  // app_podcasting,  // Podcasting App
+  // Add more apps here as they're created:
+  // app_analytics,
+  // app_subscribers,
+  // app_calendar,
+
+  // 🛠️ UTILITIES: Supporting functionality
+  auditLogs,
+  workflowExecutionLogs,
+
+  // 🥷 ONTOLOGY: Universal object system
+  objects,        // Universal storage for all entity types
+  objectLinks,    // Relationships between objects
+  objectActions,  // Audit trail of actions
+
+  // 🤖 AI INTEGRATION: General AI Assistant + Email AI Specialist
+  aiConversations,        // Chat history for general AI assistant
+  aiMessages,             // Individual messages in conversations
+  aiToolExecutions,       // Audit trail of tool executions
+  // NOTE: Tool drafts use objects table with status="draft" + AI metadata in customProperties
+  organizationAiSettings, // AI configuration per organization (LLM + embeddings)
+  aiModels,               // AI model discovery cache (auto-refreshed daily)
+  aiWorkItems,            // Work items for human-in-the-loop approval workflow
+  aiAgentTasks,          // Email AI tasks with approval workflow
+  aiAgentMemory,         // Email templates and preferences with vector search
+
+  // 💳 AI BILLING v3.1: Three-tier system (€49 or €2,500-€12,000/mo, VAT incl.)
+  aiUsage,               // Track AI API usage for billing and monitoring (with privacy audit)
+  aiSubscriptions,       // Stripe subscriptions for AI features (tier-based + sub-tiers)
+  aiTokenBalance,        // Purchased token balance (Standard/Privacy-Enhanced only)
+  aiTokenPurchases,      // Token pack purchase history (with VAT breakdown)
+  aiBudgetAlerts,        // Budget alert history and acknowledgments
+  aiBillingEvents,       // Audit log for billing operations
+
+  // 👤 USER QUOTAS: Per-user limits foundation (Phase 1: tracking only, Phase 4: enforcement)
+  userAIQuotas,          // Per-user monthly AI token limits
+
+  // 💾 STORAGE TRACKING: Organization + per-user storage metrics
+  organizationStorage,   // Aggregated storage per organization
+  userStorageQuotas,     // Per-user storage limits (Phase 1: tracking only)
+
+  // 📧 CONTACT SYNC & BULK EMAIL: AI-powered external contact integration
+  contactSyncs,          // Audit trail for contact synchronization (Microsoft/Google → CRM)
+  emailCampaigns,        // Bulk email campaigns to CRM contacts/organizations
+
+  // 🔐 OAUTH 2.0: Third-party authentication and authorization
+  oauthApplications,         // OAuth apps registered by organizations (Zapier, Make, etc.)
+  oauthAuthorizationCodes,   // Temporary authorization codes (10 min lifetime)
+  oauthRefreshTokens,        // Long-lived refresh tokens (30 days)
+  oauthRevokedTokens,        // Revocation list for access tokens
+  oauthTokenUsage,           // Token usage analytics (optional, for monitoring)
+
+  // 🚦 RATE LIMITING: Token bucket rate limiting for API abuse prevention
+  ...rateLimitSchemas,       // rateLimitBuckets, rateLimitViolations
+
+  // 🛡️ SECURITY: Anomaly detection and security event monitoring
+  ...securitySchemas,        // securityEvents, usageMetadata, failedAuthAttempts
+
+  // 📊 GROWTH TRACKING: Launch metrics and KPI tracking
+  dailyGrowthMetrics,        // Daily metrics (automated + manual)
+  signupEvents,              // Signup event tracking
+  weeklyScorecard,           // Weekly scorecard snapshots
+  salesNotifications,        // Sales team notifications
+  celebrationMilestones,     // Milestone achievements
+
+  // 📧 EMAIL QUEUE: Email delivery tracking
+  emailQueue,                // Outbound email queue
+
+  // 🎁 BENEFITS PLATFORM: Benefits & Commissions tracking
+  benefitClaims,             // Benefit claim workflow tracking
+  commissionPayouts,         // Commission payout workflow tracking
+  memberWallets,             // Crypto wallet links for members
+  platformFees,              // Platform fee tracking for billing
+
+  // ❌ OLD TRANSLATIONS - Replaced by ontology
+  // systemTranslations,
+  // appTranslations,
+  // contentTranslations,
+  // translationNamespaces,
+  // translationKeys,
+  // supportedLocales,
+});
+
+/**
+ * ADDING A NEW APP?
+ * 
+ * 1. Define your table in schemas/appDataSchemas.ts
+ * 2. Import it above: import { yourapp } from "./schemas/appDataSchemas";
+ * 3. Add it to the schema export under "APPS" section
+ * 4. Register it in convex/apps.ts DEFAULT_APPS
+ * 5. Create convex/yourapp.ts for queries/mutations
+ * 
+ * See schemas/README.md for complete guide
+ */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@l4yercak3/cli",
-  "version": "1.1.12",
+  "version": "1.2.0",
   "description": "Icing on the L4yercak3 - The sweet finishing touch for your Layer Cake integration",
   "main": "src/index.js",
   "bin": {
@@ -37,11 +37,14 @@
     "cli",
     "backend",
     "platform",
-    "integration"
+    "integration",
+    "mcp",
+    "claude-code"
   ],
   "author": "",
   "license": "MIT",
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
     "chalk": "^4.1.2",
     "commander": "^14.0.2",
     "figlet": "^1.7.0",

package/src/commands/login.js

@@ -197,12 +197,6 @@ async function handleLogin() {
     configManager.saveSession(session);
 
     // Validate session with backend
-    // Add delay to allow Convex to propagate the session (debugging timing issues)
-    if (process.env.L4YERCAK3_DEBUG) {
-      console.log('[DEBUG] Waiting 2s for session propagation...');
-    }
-    await new Promise(resolve => setTimeout(resolve, 2000));
-
     try {
       const userInfo = await backendClient.validateSession();
       if (userInfo) {

package/src/commands/mcp-server.js

@@ -0,0 +1,32 @@
+/**
+ * MCP Server Command
+ *
+ * Starts the L4YERCAK3 MCP server for Claude Code integration.
+ * The server exposes L4YERCAK3 capabilities as MCP tools.
+ *
+ * Usage:
+ *   l4yercak3 mcp-server
+ *
+ * To add to Claude Code:
+ *   claude mcp add l4yercak3 -- npx l4yercak3 mcp-server
+ *
+ * @module commands/mcp-server
+ */
+
+const { startServer } = require('../mcp/server');
+
+module.exports = {
+  command: 'mcp-server',
+  description: 'Start the MCP server for Claude Code integration',
+  handler: async () => {
+    // Note: All output goes to stderr because stdout is used for MCP protocol
+    // console.error is used intentionally here
+
+    try {
+      await startServer();
+    } catch (error) {
+      console.error(`[L4YERCAK3 MCP] Failed to start server: ${error.message}`);
+      process.exit(1);
+    }
+  },
+};

package/src/commands/spread.js

@@ -230,8 +230,61 @@ async function handleSpread() {
         console.log(chalk.gray('     • Delete an existing key at https://app.l4yercak3.com?openWindow=integrations&panel=api-keys'));
         console.log(chalk.gray('     • Upgrade your plan at https://app.l4yercak3.com?openWindow=store\n'));
         process.exit(0);
+      } else if (existingKeys && existingKeys.keys && existingKeys.keys.length > 0) {
+        // Has existing keys - offer to reuse or generate new
+        const activeKeys = existingKeys.keys.filter(k => k.status === 'active');
+
+        if (activeKeys.length > 0) {
+          console.log(chalk.gray(`  Found ${activeKeys.length} active API key(s)\n`));
+
+          const keyChoices = activeKeys.map(key => ({
+            name: `${key.name} (${key.keyPreview})`,
+            value: key.id,
+          }));
+          keyChoices.push({ name: '➕ Generate a new API key', value: '__generate__' });
+
+          const { keyChoice } = await inquirer.prompt([
+            {
+              type: 'list',
+              name: 'keyChoice',
+              message: 'Which API key would you like to use?',
+              choices: keyChoices,
+            },
+          ]);
+
+          if (keyChoice === '__generate__') {
+            apiKey = await generateNewApiKey(organizationId);
+          } else {
+            // User selected existing key - we only have the preview, not the full key
+            // They need to use the key they have stored or get it from dashboard
+            const selectedKey = activeKeys.find(k => k.id === keyChoice);
+            console.log(chalk.yellow(`\n  ⚠️  For security, we can't retrieve the full API key.`));
+            console.log(chalk.gray(`  You selected: ${selectedKey.name} (${selectedKey.keyPreview})`));
+            console.log(chalk.gray(`  If you have this key stored, enter it below.`));
+            console.log(chalk.gray(`  Otherwise, generate a new key or find it at:`));
+            console.log(chalk.gray(`  https://app.l4yercak3.com?openWindow=integrations&panel=api-keys\n`));
+
+            const { existingKey } = await inquirer.prompt([
+              {
+                type: 'input',
+                name: 'existingKey',
+                message: 'Enter your API key (or press Enter to generate new):',
+              },
+            ]);
+
+            if (existingKey.trim()) {
+              apiKey = existingKey.trim();
+              console.log(chalk.green(`  ✅ Using existing API key\n`));
+            } else {
+              apiKey = await generateNewApiKey(organizationId);
+            }
+          }
+        } else {
+          // Only revoked keys exist - generate new
+          apiKey = await generateNewApiKey(organizationId);
+        }
       } else {
-        // Generate new key (either no keys exist or can create more)
+        // No existing keys - generate one
         apiKey = await generateNewApiKey(organizationId);
       }
     } catch (error) {

package/src/mcp/auth.js

@@ -0,0 +1,127 @@
+/**
+ * MCP Server Authentication Layer
+ *
+ * Reads CLI session from ~/.l4yercak3/config.json and validates with backend.
+ * Provides auth context for tool execution.
+ *
+ * @module mcp/auth
+ */
+
+const configManager = require('../config/config-manager');
+const backendClient = require('../api/backend-client');
+
+/**
+ * @typedef {Object} AuthContext
+ * @property {string} userId - The authenticated user's ID
+ * @property {string} organizationId - Current organization ID
+ * @property {string} organizationName - Current organization name
+ * @property {string} sessionToken - The CLI session token
+ * @property {string[]} permissions - User's permissions in the organization
+ */
+
+/**
+ * Get authentication context from CLI session
+ * Returns null if not authenticated or session expired
+ *
+ * @returns {Promise<AuthContext|null>}
+ */
+async function getAuthContext() {
+  // Check if session exists locally
+  if (!configManager.isLoggedIn()) {
+    return null;
+  }
+
+  const session = configManager.getSession();
+  if (!session || !session.token) {
+    return null;
+  }
+
+  // Check if session is expired locally
+  if (session.expiresAt && session.expiresAt < Date.now()) {
+    return null;
+  }
+
+  try {
+    // Validate session with backend
+    const validation = await backendClient.validateSession();
+
+    if (!validation || !validation.valid) {
+      return null;
+    }
+
+    // Build auth context
+    return {
+      userId: validation.userId || session.userId,
+      organizationId: validation.organizationId || session.organizationId,
+      organizationName: validation.organizationName || session.organizationName || 'Unknown',
+      sessionToken: session.token,
+      email: validation.email || session.email,
+      permissions: validation.permissions || [],
+    };
+  } catch (error) {
+    // Log error to stderr (stdout is for MCP protocol)
+    console.error('[L4YERCAK3 MCP] Auth validation error:', error.message);
+    return null;
+  }
+}
+
+/**
+ * Require authentication for a tool
+ * Throws if not authenticated
+ *
+ * @param {AuthContext|null} authContext
+ * @returns {AuthContext}
+ * @throws {Error} If not authenticated
+ */
+function requireAuth(authContext) {
+  if (!authContext) {
+    throw new Error(
+      'Not authenticated with L4YERCAK3. Please run "l4yercak3 login" first.'
+    );
+  }
+  return authContext;
+}
+
+/**
+ * Check if user has a specific permission
+ *
+ * @param {AuthContext} authContext
+ * @param {string} permission
+ * @returns {boolean}
+ */
+function hasPermission(authContext, permission) {
+  if (!authContext || !authContext.permissions) {
+    return false;
+  }
+
+  // Check for wildcard permission
+  if (authContext.permissions.includes('*')) {
+    return true;
+  }
+
+  return authContext.permissions.includes(permission);
+}
+
+/**
+ * Require a specific permission
+ *
+ * @param {AuthContext} authContext
+ * @param {string} permission
+ * @throws {Error} If permission not granted
+ */
+function requirePermission(authContext, permission) {
+  requireAuth(authContext);
+
+  if (!hasPermission(authContext, permission)) {
+    throw new Error(
+      `Permission denied: ${permission} required. Contact your organization admin.`
+    );
+  }
+}
+
+module.exports = {
+  getAuthContext,
+  requireAuth,
+  hasPermission,
+  requirePermission,
+};