@od-oneapp/ai-platform 0.1.0

package/src/governance/entitlements/index.ts

@@ -0,0 +1,585 @@
+/**
+ * @fileoverview User Entitlements & Access Control.
+ * @module @od-oneapp/ai-platform/governance/entitlements
+ *
+ * Type-safe model access control and feature enablement by user tier.
+ *
+ * Features:
+ * - Tier-based access control (free, pro, enterprise)
+ * - Per-model access restrictions
+ * - Token quotas per day/hour/minute
+ * - Request rate limiting
+ * - Feature flag enablement by tier
+ * - Organization-scoped entitlements
+ */
+
+import { logInfo } from '@repo/shared/logs';
+
+/**
+ * User tier levels with increasing capabilities
+ */
+export type UserTier = 'free' | 'pro' | 'enterprise';
+
+/**
+ * User representation for entitlement checks
+ */
+export interface User {
+  /** Unique user identifier */
+  id: string;
+
+  /** User's tier level */
+  tier: UserTier;
+
+  /** Organization ID (for org-scoped quotas) */
+  organizationId?: string;
+
+  /** Additional user metadata */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Entitlements for a specific user tier
+ */
+export interface UserEntitlements {
+  /** User tier */
+  tier: UserTier;
+
+  /** List of allowed model IDs for this tier */
+  models: string[];
+
+  /** Maximum tokens allowed per day */
+  maxTokensPerDay: number;
+
+  /** Maximum tokens allowed per hour */
+  maxTokensPerHour: number;
+
+  /** Maximum requests allowed per minute */
+  maxRequestsPerMinute: number;
+
+  /** Maximum concurrent requests */
+  maxConcurrentRequests: number;
+
+  /** List of enabled features for this tier */
+  features: string[];
+
+  /** Custom rate limit bucket (for advanced configurations) */
+  rateLimitBucket?: {
+    capacity: number;
+    refillRate: number; // tokens per second
+  };
+}
+
+/**
+ * Configuration for entitlement checker
+ */
+export interface EntitlementConfig {
+  /** Entitlements by tier */
+  tiers: Record<UserTier, UserEntitlements>;
+
+  /** Enable audit logging */
+  enableLogging?: boolean;
+
+  /** Custom tier mapping function */
+  getTierForUser?: (user: User) => UserTier;
+}
+
+/**
+ * Result of an entitlement check
+ */
+export interface EntitlementCheckResult {
+  /** Whether the access is allowed */
+  allowed: boolean;
+
+  /** Reason if denied */
+  reason?: string;
+
+  /** Recommended tier upgrade if access denied */
+  suggestedTier?: UserTier;
+}
+
+/**
+ * Entitlement checker interface
+ */
+export interface EntitlementChecker {
+  /** Check if user has access to a specific model */
+  canAccessModel(user: User, modelId: string): EntitlementCheckResult;
+
+  /** Check if user has access to a feature */
+  canAccessFeature(user: User, feature: string): EntitlementCheckResult;
+
+  /** Get remaining token quota for a user */
+  getRemainingTokens(userId: string): Promise<number>;
+
+  /** Get remaining requests quota for a user */
+  getRemainingRequests(userId: string): Promise<number>;
+
+  /** Consume tokens for a request */
+  consumeTokens(userId: string, tokens: number): Promise<boolean>;
+
+  /** Consume a request quota */
+  consumeRequest(userId: string): Promise<boolean>;
+
+  /** Get user's current entitlements */
+  getUserEntitlements(user: User): UserEntitlements;
+
+  /** Reset quotas for a user */
+  resetQuotas(userId: string): Promise<void>;
+
+  /** Get quota usage stats */
+  getQuotaStats(userId: string): Promise<QuotaStats>;
+}
+
+/**
+ * Statistics about quota usage
+ */
+export interface QuotaStats {
+  /** Tokens consumed today */
+  tokensConsumedToday: number;
+
+  /** Tokens consumed this hour */
+  tokensConsumedThisHour: number;
+
+  /** Requests made this minute */
+  requestsThisMinute: number;
+
+  /** Total requests made today */
+  requestsToday: number;
+
+  /** Percentage of daily token quota used */
+  tokenUsagePercent: number;
+
+  /** Percentage of hourly token quota used */
+  tokenUsagePercentHour: number;
+
+  /** Percentage of per-minute request quota used */
+  requestUsagePercent: number;
+
+  /** When quotas reset */
+  resetsAt: Date;
+}
+
+/**
+ * Storage backend for quota tracking
+ */
+export interface QuotaStorage {
+  /** Get current token usage for a user in a specific period */
+  getTokenUsage(userId: string, period: 'day' | 'hour'): Promise<number>;
+
+  /** Get current request count for a user in a specific period */
+  getRequestCount(userId: string, period: 'minute' | 'hour' | 'day'): Promise<number>;
+
+  /** Add tokens to usage */
+  addTokenUsage(userId: string, tokens: number): Promise<void>;
+
+  /** Add request to count */
+  addRequest(userId: string): Promise<void>;
+
+  /** Reset usage for a user */
+  reset(userId: string): Promise<void>;
+
+  /** Clear expired records */
+  clearExpired(): Promise<void>;
+}
+
+/**
+ * Default entitlements by tier
+ */
+export const DEFAULT_ENTITLEMENTS: Record<UserTier, UserEntitlements> = {
+  free: {
+    tier: 'free',
+    models: ['gpt-4-mini', 'claude-3-haiku'],
+    maxTokensPerDay: 10000,
+    maxTokensPerHour: 1000,
+    maxRequestsPerMinute: 10,
+    maxConcurrentRequests: 1,
+    features: ['basic-chat', 'conversation-history', 'file-upload'],
+  },
+  pro: {
+    tier: 'pro',
+    models: ['gpt-4-mini', 'gpt-4-turbo', 'claude-3-haiku', 'claude-3-sonnet'],
+    maxTokensPerDay: 500000,
+    maxTokensPerHour: 100000,
+    maxRequestsPerMinute: 60,
+    maxConcurrentRequests: 5,
+    features: [
+      'basic-chat',
+      'conversation-history',
+      'code-execution',
+      'image-analysis',
+      'file-upload',
+    ],
+    rateLimitBucket: {
+      capacity: 100000,
+      refillRate: 100,
+    },
+  },
+  enterprise: {
+    tier: 'enterprise',
+    models: [
+      'gpt-4-mini',
+      'gpt-4-turbo',
+      'o1',
+      'claude-3-haiku',
+      'claude-3-sonnet',
+      'claude-3-opus',
+    ],
+    maxTokensPerDay: 100000000,
+    maxTokensPerHour: 10000000,
+    maxRequestsPerMinute: 1000,
+    maxConcurrentRequests: 100,
+    features: [
+      'basic-chat',
+      'conversation-history',
+      'code-execution',
+      'image-analysis',
+      'file-upload',
+      'api-access',
+      'custom-models',
+      'priority-support',
+      'audit-logs',
+      'sso',
+    ],
+    rateLimitBucket: {
+      capacity: 50000000,
+      refillRate: 10000,
+    },
+  },
+};
+
+/**
+ * Create an entitlement checker instance
+ *
+ * @param config - Entitlement configuration
+ * @param storage - Optional quota storage backend (defaults to in-memory)
+ * @returns EntitlementChecker instance
+ *
+ * @example
+ * ```typescript
+ * const checker = createEntitlementChecker({
+ *   tiers: DEFAULT_ENTITLEMENTS,
+ *   enableLogging: true
+ * });
+ *
+ * const user = { id: 'user-123', tier: 'pro' };
+ * const result = checker.canAccessModel(user, 'gpt-4-turbo');
+ * console.log(result.allowed); // true
+ * ```
+ */
+export function createEntitlementChecker(
+  config: EntitlementConfig,
+  storage?: QuotaStorage,
+): EntitlementChecker {
+  const logger = config.enableLogging ? logInfo : () => {};
+  const quotaStorage = storage || createInMemoryQuotaStorage();
+
+  return {
+    canAccessModel(user: User, modelId: string): EntitlementCheckResult {
+      const entitlements = this.getUserEntitlements(user);
+      const allowed = entitlements.models.includes(modelId);
+
+      if (!allowed) {
+        // Find a tier that has this model
+        let suggestedTier: UserTier | undefined;
+        const tierOrder: UserTier[] = ['free', 'pro', 'enterprise'];
+        const currentIndex = tierOrder.indexOf(user.tier);
+
+        for (let i = currentIndex + 1; i < tierOrder.length; i++) {
+          const tier = tierOrder[i];
+          if (!tier) continue;
+          const tierConfig = config.tiers[tier];
+          if (tierConfig?.models.includes(modelId)) {
+            suggestedTier = tier;
+            break;
+          }
+        }
+
+        logger(
+          `[Entitlements] Model access denied: user ${user.id} (${user.tier}) tried to access ${modelId}`,
+        );
+
+        return {
+          allowed: false,
+          reason: `Model '${modelId}' not available in ${user.tier} tier`,
+          suggestedTier,
+        };
+      }
+
+      logger(`[Entitlements] Model access granted: user ${user.id} can access ${modelId}`);
+      return { allowed: true };
+    },
+
+    canAccessFeature(user: User, feature: string): EntitlementCheckResult {
+      const entitlements = this.getUserEntitlements(user);
+      const allowed = entitlements.features.includes(feature);
+
+      if (!allowed) {
+        let suggestedTier: UserTier | undefined;
+        const tierOrder: UserTier[] = ['free', 'pro', 'enterprise'];
+        const currentIndex = tierOrder.indexOf(user.tier);
+
+        for (let i = currentIndex + 1; i < tierOrder.length; i++) {
+          const tier = tierOrder[i];
+          if (!tier) continue;
+          const tierConfig = config.tiers[tier];
+          if (tierConfig?.features.includes(feature)) {
+            suggestedTier = tier;
+            break;
+          }
+        }
+
+        logger(
+          `[Entitlements] Feature access denied: user ${user.id} (${user.tier}) tried to access ${feature}`,
+        );
+
+        return {
+          allowed: false,
+          reason: `Feature '${feature}' not available in ${user.tier} tier`,
+          suggestedTier,
+        };
+      }
+
+      logger(`[Entitlements] Feature access granted: user ${user.id} can access ${feature}`);
+      return { allowed: true };
+    },
+
+    async getRemainingTokens(userId: string): Promise<number> {
+      const user = { id: userId, tier: 'pro' as const }; // Default to pro for quota lookup
+      const entitlements = this.getUserEntitlements(user);
+
+      const consumed = await quotaStorage.getTokenUsage(userId, 'day');
+      const remaining = Math.max(0, entitlements.maxTokensPerDay - consumed);
+
+      logger(`[Entitlements] Remaining tokens for user ${userId}: ${remaining}`);
+      return remaining;
+    },
+
+    async getRemainingRequests(userId: string): Promise<number> {
+      const user = { id: userId, tier: 'pro' as const };
+      const entitlements = this.getUserEntitlements(user);
+
+      const consumed = await quotaStorage.getRequestCount(userId, 'minute');
+      const remaining = Math.max(0, entitlements.maxRequestsPerMinute - consumed);
+
+      logger(`[Entitlements] Remaining requests for user ${userId}: ${remaining}`);
+      return remaining;
+    },
+
+    async consumeTokens(userId: string, tokens: number): Promise<boolean> {
+      const remaining = await this.getRemainingTokens(userId);
+
+      if (tokens > remaining) {
+        logger(
+          `[Entitlements] Token quota exceeded for user ${userId}: needs ${tokens}, has ${remaining}`,
+        );
+        return false;
+      }
+
+      await quotaStorage.addTokenUsage(userId, tokens);
+      logger(`[Entitlements] Consumed ${tokens} tokens for user ${userId}`);
+      return true;
+    },
+
+    async consumeRequest(userId: string): Promise<boolean> {
+      const remaining = await this.getRemainingRequests(userId);
+
+      if (remaining <= 0) {
+        logger(`[Entitlements] Request quota exceeded for user ${userId}`);
+        return false;
+      }
+
+      await quotaStorage.addRequest(userId);
+      logger(`[Entitlements] Consumed 1 request for user ${userId}`);
+      return true;
+    },
+
+    getUserEntitlements(user: User): UserEntitlements {
+      const tier = config.getTierForUser?.(user) || user.tier;
+      return config.tiers[tier];
+    },
+
+    async resetQuotas(userId: string): Promise<void> {
+      await quotaStorage.reset(userId);
+      logger(`[Entitlements] Reset quotas for user ${userId}`);
+    },
+
+    async getQuotaStats(userId: string): Promise<QuotaStats> {
+      // For demo purposes, we assume pro tier
+      const user = { id: userId, tier: 'pro' as const };
+      const entitlements = this.getUserEntitlements(user);
+
+      const tokensConsumedToday = await quotaStorage.getTokenUsage(userId, 'day');
+      const tokensConsumedThisHour = await quotaStorage.getTokenUsage(userId, 'hour');
+      const requestsThisMinute = await quotaStorage.getRequestCount(userId, 'minute');
+      const requestsToday = await quotaStorage.getRequestCount(userId, 'day');
+
+      return {
+        tokensConsumedToday,
+        tokensConsumedThisHour,
+        requestsThisMinute,
+        requestsToday,
+        tokenUsagePercent: (tokensConsumedToday / entitlements.maxTokensPerDay) * 100,
+        tokenUsagePercentHour: (tokensConsumedThisHour / entitlements.maxTokensPerHour) * 100,
+        requestUsagePercent: (requestsThisMinute / entitlements.maxRequestsPerMinute) * 100,
+        resetsAt: getNextResetTime('day'),
+      };
+    },
+  };
+}
+
+/**
+ * Check if a user has access to a specific model
+ * Convenience function that creates a temporary checker
+ *
+ * @param user - User to check
+ * @param modelId - Model ID to check access for
+ * @returns Whether access is allowed
+ *
+ * @example
+ * ```typescript
+ * const user = { id: 'user-123', tier: 'free' };
+ * const canUse = checkModelAccess(user, 'gpt-4-turbo');
+ * ```
+ */
+export function checkModelAccess(user: User, modelId: string): boolean {
+  const checker = createEntitlementChecker({
+    tiers: DEFAULT_ENTITLEMENTS,
+  });
+
+  const result = checker.canAccessModel(user, modelId);
+  return result.allowed;
+}
+
+/**
+ * Check if a user has access to a specific feature
+ * Convenience function that creates a temporary checker
+ *
+ * @param user - User to check
+ * @param feature - Feature to check access for
+ * @returns Whether access is allowed
+ *
+ * @example
+ * ```typescript
+ * const user = { id: 'user-123', tier: 'pro' };
+ * const canUse = checkFeatureAccess(user, 'code-execution');
+ * ```
+ */
+export function checkFeatureAccess(user: User, feature: string): boolean {
+  const checker = createEntitlementChecker({
+    tiers: DEFAULT_ENTITLEMENTS,
+  });
+
+  const result = checker.canAccessFeature(user, feature);
+  return result.allowed;
+}
+
+/**
+ * Create in-memory quota storage backend
+ * Suitable for development and testing, not recommended for production
+ *
+ * @returns QuotaStorage instance
+ */
+function createInMemoryQuotaStorage(): QuotaStorage {
+  const tokenUsage = new Map<string, { day: number; hour: number; lastReset: Date }>();
+  const requestCount = new Map<
+    string,
+    { minute: number; hour: number; day: number; lastReset: Date }
+  >();
+
+  return {
+    async getTokenUsage(userId: string, period: 'day' | 'hour'): Promise<number> {
+      const usage = tokenUsage.get(userId);
+      if (!usage) return 0;
+
+      // Check if we need to reset
+      const now = new Date();
+      const hoursSinceReset = (now.getTime() - usage.lastReset.getTime()) / (1000 * 60 * 60);
+
+      if (period === 'day' && hoursSinceReset >= 24) {
+        return 0;
+      }
+      if (period === 'hour' && hoursSinceReset >= 1) {
+        return 0;
+      }
+
+      return period === 'day' ? usage.day : usage.hour;
+    },
+
+    async getRequestCount(userId: string, period: 'minute' | 'hour' | 'day'): Promise<number> {
+      const count = requestCount.get(userId);
+      if (!count) return 0;
+
+      const now = new Date();
+      const minutesSinceReset = (now.getTime() - count.lastReset.getTime()) / (1000 * 60);
+
+      if (period === 'day' && minutesSinceReset >= 1440) {
+        return 0;
+      }
+      if (period === 'hour' && minutesSinceReset >= 60) {
+        return 0;
+      }
+      if (period === 'minute' && minutesSinceReset >= 1) {
+        return 0;
+      }
+
+      return count[period];
+    },
+
+    async addTokenUsage(userId: string, tokens: number): Promise<void> {
+      const current = tokenUsage.get(userId) || {
+        day: 0,
+        hour: 0,
+        lastReset: new Date(),
+      };
+
+      current.day += tokens;
+      current.hour += tokens;
+      tokenUsage.set(userId, current);
+    },
+
+    async addRequest(userId: string): Promise<void> {
+      const current = requestCount.get(userId) || {
+        minute: 0,
+        hour: 0,
+        day: 0,
+        lastReset: new Date(),
+      };
+
+      current.minute += 1;
+      current.hour += 1;
+      current.day += 1;
+      requestCount.set(userId, current);
+    },
+
+    async reset(userId: string): Promise<void> {
+      tokenUsage.delete(userId);
+      requestCount.delete(userId);
+    },
+
+    async clearExpired(): Promise<void> {
+      // In-memory storage doesn't need cleanup
+    },
+  };
+}
+
+/**
+ * Get the next reset time for a quota period
+ */
+function getNextResetTime(period: 'day' | 'hour' | 'minute'): Date {
+  const now = new Date();
+
+  if (period === 'minute') {
+    return new Date(now.getTime() + 60 * 1000);
+  }
+
+  if (period === 'hour') {
+    return new Date(now.getTime() + 60 * 60 * 1000);
+  }
+
+  // Day - reset at midnight
+  const tomorrow = new Date(now);
+  tomorrow.setDate(tomorrow.getDate() + 1);
+  tomorrow.setHours(0, 0, 0, 0);
+  return tomorrow;
+}
+
+// Re-export types