@retrivora-ai/rag-engine 2.3.0 → 2.3.2

package/src/core/DatabaseStorage.ts

@@ -291,8 +291,11 @@ export class DatabaseStorage {
     }
   }
 
-  async getHistory(sessionId: string): Promise<HistoryMessage[]> {
+  async getHistory(sessionId: string, projectIds?: string[]): Promise<HistoryMessage[]> {
     this.checkHistoryEnabled();
+    if (projectIds && projectIds.length > 0 && !this.sessionInScope(sessionId, projectIds)) {
+      return [];
+    }
     if (this.provider === 'postgresql' || this.provider === 'pgvector') {
       const pool = await this.getPGPool();
       const res = await pool.query(
@@ -328,8 +331,11 @@ export class DatabaseStorage {
     }
   }
 
-  async clearHistory(sessionId: string): Promise<void> {
+  async clearHistory(sessionId: string, projectIds?: string[]): Promise<void> {
     this.checkHistoryEnabled();
+    if (projectIds && projectIds.length > 0 && !this.sessionInScope(sessionId, projectIds)) {
+      return;
+    }
     if (this.provider === 'postgresql' || this.provider === 'pgvector') {
       const pool = await this.getPGPool();
       await pool.query(`DELETE FROM ${this.historyTableName} WHERE session_id = $1`, [sessionId]);
@@ -350,21 +356,37 @@ export class DatabaseStorage {
     }
   }
 
-  async listSessions(): Promise<string[]> {
+  /**
+   * Return true when `sessionId` falls into the allowed `projectIds` scope.
+   * When `projectIds` is empty / undefined we allow the call (legacy behavior
+   * for non-multi-tenant consumers). Session ids typically begin with the
+   * project id they were created for, so we prefix-match as well as contains-match
+   * to catch sharded / suffix-style ids used by some integrations.
+   */
+  private sessionInScope(sessionId: string, projectIds?: string[]): boolean {
+    if (!projectIds || projectIds.length === 0) return true;
+    return projectIds.some(
+      (pid) => pid && (sessionId === pid || sessionId.startsWith(pid) || sessionId.includes(pid))
+    );
+  }
+
+  async listSessions(projectIds?: string[]): Promise<string[]> {
     this.checkHistoryEnabled();
+    let raw: string[] = [];
     if (this.provider === 'postgresql' || this.provider === 'pgvector') {
       const pool = await this.getPGPool();
       const res = await pool.query(`SELECT DISTINCT session_id FROM ${this.historyTableName}`);
-      return res.rows.map((r: any) => r.session_id);
+      raw = res.rows.map((r: any) => r.session_id);
     } else if (this.provider === 'mongodb') {
       await this.getMongoClient();
       const db = this.getMongoDb();
-      return db.collection(this.historyTableName).distinct('session_id');
+      raw = await db.collection(this.historyTableName).distinct('session_id');
     } else {
       const history = this.readLocalFile(this.historyFile);
-      const sessions = new Set<string>(history.map((h) => h.session_id));
-      return Array.from(sessions);
+      raw = Array.from(new Set<string>(history.map((h) => h.session_id)));
     }
+    if (!projectIds || projectIds.length === 0) return raw;
+    return raw.filter((sid) => this.sessionInScope(sid, projectIds));
   }
 
   // ─── Feedback Operations ──────────────────────────────────────────────────
@@ -422,8 +444,9 @@ export class DatabaseStorage {
     }
   }
 
-  async getFeedback(messageId: string): Promise<FeedbackItem | null> {
+  async getFeedback(messageId: string, projectIds?: string[]): Promise<FeedbackItem | null> {
     this.checkFeedbackEnabled();
+    let item: FeedbackItem | null = null;
     if (this.provider === 'postgresql' || this.provider === 'pgvector') {
       const pool = await this.getPGPool();
       const res = await pool.query(
@@ -432,29 +455,35 @@ export class DatabaseStorage {
          WHERE message_id = $1`,
         [messageId]
       );
-      return res.rows[0] || null;
+      item = res.rows[0] || null;
     } else if (this.provider === 'mongodb') {
       await this.getMongoClient();
       const db = this.getMongoDb();
       const col = db.collection(this.feedbackTableName);
-      const item = await col.findOne({ message_id: messageId });
-      if (!item) return null;
-      return {
-        id: item.id,
-        messageId: item.message_id,
-        sessionId: item.session_id,
-        rating: item.rating,
-        comment: item.comment,
-        createdAt: item.created_at,
-      };
+      const raw = await col.findOne({ message_id: messageId });
+      if (raw) {
+        item = {
+          id: raw.id,
+          messageId: raw.message_id,
+          sessionId: raw.session_id,
+          rating: raw.rating,
+          comment: raw.comment,
+          createdAt: raw.created_at,
+        };
+      }
     } else {
       const list = this.readLocalFile(this.feedbackFile);
-      return list.find((f) => f.message_id === messageId) || null;
+      item = list.find((f) => f.message_id === messageId) || null;
+    }
+    if (item && projectIds && projectIds.length > 0) {
+      return this.sessionInScope(item.sessionId, projectIds) ? item : null;
     }
+    return item;
   }
 
-  async listFeedback(): Promise<FeedbackItem[]> {
+  async listFeedback(projectIds?: string[]): Promise<FeedbackItem[]> {
     this.checkFeedbackEnabled();
+    let raw: FeedbackItem[] = [];
     if (this.provider === 'postgresql' || this.provider === 'pgvector') {
       const pool = await this.getPGPool();
       const res = await pool.query(
@@ -462,13 +491,13 @@ export class DatabaseStorage {
          FROM ${this.feedbackTableName} 
          ORDER BY created_at DESC`
       );
-      return res.rows;
+      raw = res.rows;
     } else if (this.provider === 'mongodb') {
       await this.getMongoClient();
       const db = this.getMongoDb();
       const col = db.collection(this.feedbackTableName);
       const items = await col.find({}).sort({ created_at: -1 }).toArray();
-      return items.map((item: any) => ({
+      raw = items.map((item: any) => ({
         id: item.id,
         messageId: item.message_id,
         sessionId: item.session_id,
@@ -478,8 +507,10 @@ export class DatabaseStorage {
       }));
     } else {
       const list = this.readLocalFile(this.feedbackFile);
-      return [...list].sort((a, b) => new Date(b.created_at).getTime() - new Date(a.created_at).getTime());
+      raw = [...list].sort((a, b) => new Date(b.created_at).getTime() - new Date(a.created_at).getTime());
     }
+    if (!projectIds || projectIds.length === 0) return raw;
+    return raw.filter((f) => this.sessionInScope(f.sessionId, projectIds));
   }
 
   async disconnect() {

package/src/core/FreeTierLimitsGuard.ts

@@ -0,0 +1,281 @@
+/**
+ * FreeTierLimitsGuard — Enforces strict operational quotas for Free Tier workspaces.
+ * Retrivora Free Tier (Hobby) policy enforcement & Request Units accounting.
+ *
+ * Inline copy for the published SDK package (@retrivora-ai/rag-engine). The
+ * canonical source lives in `services/billing/FreeTierLimitsGuard.ts` and is
+ * kept in sync for the monorepo via copy on changes; bundling it here ensures
+ * published dist builds don't depend on `@services/*` path aliases that only
+ * resolve inside the Turborepo workspace.
+ */
+
+export interface WorkspaceUsageStats {
+  documentCount: number;
+  totalStorageBytes: number;
+  totalEmbeddingsCount: number;
+  dailyQueriesCount: number;
+  totalRequestUnitsUsed?: number;
+  dailyRequestUnitsUsed?: number;
+  trialStartedAt?: string;
+  concurrentRequests?: number;
+}
+
+export const FREE_TIER_QUOTAS = {
+  MAX_DOCUMENTS: 25,
+  MAX_FILE_SIZE_BYTES: 20 * 1024 * 1024,
+  MAX_STORAGE_BYTES: 250 * 1024 * 1024,
+  MAX_TRIAL_REQUEST_UNITS: 500,
+  MAX_DAILY_REQUEST_UNITS: 50,
+  TRIAL_DURATION_DAYS: 14,
+  GRACE_PERIOD_DAYS: 2,
+  MAX_RPM: 10,
+  MAX_RPH: 100,
+  MAX_RPD: 500,
+  MAX_CONCURRENT_REQUESTS: 2,
+  MAX_INPUT_TOKENS: 20000,
+  MAX_OUTPUT_TOKENS: 4000,
+  UPGRADE_REMINDER_DAYS: [7, 12, 14] as const,
+  MAX_USERS: 1,
+  MAX_NAMESPACES: 1,
+  MAX_PROJECTS: 1,
+} as const;
+
+export interface TrialTimestamps {
+  trial_started_at: string;
+  trial_expires_at: string;
+  grace_period_expires_at: string;
+}
+
+export interface TrialStatusResult {
+  status: 'active' | 'grace_period' | 'expired';
+  daysElapsed: number;
+  daysRemaining: number;
+  isGracePeriod: boolean;
+  isExpired: boolean;
+  upgradeReminderDue?: number;
+  usageReminderDue?: '80%' | '90%' | '100%';
+  reason?: string;
+}
+
+export interface RequestCheckParams {
+  operationType?: string;
+  inputTokens?: number;
+  outputTokens?: number;
+  dailyUnitsUsed?: number;
+  totalUnitsUsed?: number;
+  trialStartedAt?: string | Date;
+  concurrentRequests?: number;
+  chunkCount?: number;
+  nowServerTime?: Date;
+}
+
+export class FreeTierLimitsGuard {
+  static calculateTrialTimestamps(startedAt?: Date | string): TrialTimestamps {
+    const startDate = startedAt ? new Date(startedAt) : new Date();
+    const trialStartedAtMs = startDate.getTime();
+
+    const trialExpiresAtMs = trialStartedAtMs + FREE_TIER_QUOTAS.TRIAL_DURATION_DAYS * 24 * 60 * 60 * 1000;
+    const gracePeriodExpiresAtMs =
+      trialStartedAtMs + (FREE_TIER_QUOTAS.TRIAL_DURATION_DAYS + FREE_TIER_QUOTAS.GRACE_PERIOD_DAYS) * 24 * 60 * 60 * 1000;
+
+    return {
+      trial_started_at: new Date(trialStartedAtMs).toISOString(),
+      trial_expires_at: new Date(trialExpiresAtMs).toISOString(),
+      grace_period_expires_at: new Date(gracePeriodExpiresAtMs).toISOString(),
+    };
+  }
+
+  static calculateRequestUnits(operationType: string, options?: { chunkCount?: number }): number {
+    const op = operationType.toLowerCase().trim();
+
+    if (
+      op.includes('suggestion') ||
+      op.includes('template') ||
+      op.includes('history') ||
+      op.includes('model') ||
+      op.includes('health') ||
+      op.includes('auth') ||
+      op.includes('license') ||
+      op.includes('usage') ||
+      op.includes('feedback') ||
+      op.includes('analytic')
+    ) {
+      return 0;
+    }
+
+    if (op.includes('image')) {
+      return 10;
+    }
+
+    if (op.includes('embedding')) {
+      const chunks = options?.chunkCount ?? 1;
+      return Math.max(1, Math.ceil(chunks / 1000));
+    }
+
+    return 1;
+  }
+
+  static checkTrialStatus(
+    startedAt?: Date | string,
+    totalUnitsUsed = 0,
+    nowServerTime = new Date()
+  ): TrialStatusResult {
+    const timestamps = this.calculateTrialTimestamps(startedAt);
+    const startMs = new Date(timestamps.trial_started_at).getTime();
+    const expireMs = new Date(timestamps.trial_expires_at).getTime();
+    const graceExpireMs = new Date(timestamps.grace_period_expires_at).getTime();
+    const nowMs = nowServerTime.getTime();
+
+    const daysElapsed = Math.floor(Math.max(0, nowMs - startMs) / (1000 * 60 * 60 * 24));
+    const daysRemaining = Math.max(0, Math.ceil((expireMs - nowMs) / (1000 * 60 * 60 * 24)));
+
+    const isConsumedUnits = totalUnitsUsed >= FREE_TIER_QUOTAS.MAX_TRIAL_REQUEST_UNITS;
+    const isExpiredTime = nowMs > expireMs;
+    const isPastGraceTime = nowMs > graceExpireMs;
+
+    let status: 'active' | 'grace_period' | 'expired' = 'active';
+    let reason: string | undefined;
+
+    if (isPastGraceTime || (isConsumedUnits && isExpiredTime)) {
+      status = 'expired';
+      reason = 'Trial period and grace period have expired. Upgrade your plan.';
+    } else if (isExpiredTime || isConsumedUnits) {
+      status = 'grace_period';
+      reason = isConsumedUnits
+        ? 'Total trial request quota (500 units) consumed. Grace period active (dashboard access only).'
+        : '14-day trial period expired. 2-day grace period active (dashboard access only).';
+    }
+
+    let upgradeReminderDue: number | undefined;
+    if (FREE_TIER_QUOTAS.UPGRADE_REMINDER_DAYS.includes(daysElapsed as any)) {
+      upgradeReminderDue = daysElapsed;
+    }
+
+    let usageReminderDue: '80%' | '90%' | '100%' | undefined;
+    const usagePercent = (totalUnitsUsed / FREE_TIER_QUOTAS.MAX_TRIAL_REQUEST_UNITS) * 100;
+    if (usagePercent >= 100) {
+      usageReminderDue = '100%';
+    } else if (usagePercent >= 90) {
+      usageReminderDue = '90%';
+    } else if (usagePercent >= 80) {
+      usageReminderDue = '80%';
+    }
+
+    return {
+      status,
+      daysElapsed,
+      daysRemaining,
+      isGracePeriod: status === 'grace_period',
+      isExpired: status === 'expired',
+      upgradeReminderDue,
+      usageReminderDue,
+      reason,
+    };
+  }
+
+  static checkIngestionAllowed(
+    stats: Partial<WorkspaceUsageStats>,
+    incomingSizeBytes = 0
+  ): { allowed: boolean; reason?: string } {
+    const docs = stats.documentCount ?? 0;
+    const storage = stats.totalStorageBytes ?? 0;
+
+    if (incomingSizeBytes > FREE_TIER_QUOTAS.MAX_FILE_SIZE_BYTES) {
+      const mbSize = (incomingSizeBytes / (1024 * 1024)).toFixed(1);
+      return {
+        allowed: false,
+        reason: `[FreeTierIngestor] File size (${mbSize}MB) exceeds maximum allowed size of 20MB under Free Tier rules.`,
+      };
+    }
+
+    if (docs >= FREE_TIER_QUOTAS.MAX_DOCUMENTS) {
+      return {
+        allowed: false,
+        reason: `Document limit reached (${docs}/${FREE_TIER_QUOTAS.MAX_DOCUMENTS}). Upgrade to Pro to ingest more documents.`,
+      };
+    }
+
+    if (storage + incomingSizeBytes > FREE_TIER_QUOTAS.MAX_STORAGE_BYTES) {
+      const mbUsed = (storage / (1024 * 1024)).toFixed(1);
+      return {
+        allowed: false,
+        reason: `Storage quota exceeded (${mbUsed}MB / 250MB). Upgrade for unlimited storage.`,
+      };
+    }
+
+    return { allowed: true };
+  }
+
+  static checkRequestAllowed(params: RequestCheckParams): { allowed: boolean; reason?: string; costUnits?: number } {
+    const op = params.operationType ?? 'chat';
+    const costUnits = this.calculateRequestUnits(op, { chunkCount: params.chunkCount });
+
+    if (costUnits === 0) {
+      return { allowed: true, costUnits: 0 };
+    }
+
+    if (params.inputTokens && params.inputTokens > FREE_TIER_QUOTAS.MAX_INPUT_TOKENS) {
+      return {
+        allowed: false,
+        reason: 'Token limit exceeded. Upgrade your plan.',
+        costUnits,
+      };
+    }
+    if (params.outputTokens && params.outputTokens > FREE_TIER_QUOTAS.MAX_OUTPUT_TOKENS) {
+      return {
+        allowed: false,
+        reason: 'Token limit exceeded. Upgrade your plan.',
+        costUnits,
+      };
+    }
+
+    if (params.concurrentRequests && params.concurrentRequests > FREE_TIER_QUOTAS.MAX_CONCURRENT_REQUESTS) {
+      return {
+        allowed: false,
+        reason: `Concurrent limit exceeded (max ${FREE_TIER_QUOTAS.MAX_CONCURRENT_REQUESTS} active requests). Please wait for active streams to finish.`,
+        costUnits,
+      };
+    }
+
+    const totalUnits = params.totalUnitsUsed ?? 0;
+    const trialStatus = this.checkTrialStatus(params.trialStartedAt, totalUnits, params.nowServerTime);
+
+    if (trialStatus.status === 'expired' || trialStatus.status === 'grace_period') {
+      return {
+        allowed: false,
+        reason: trialStatus.reason || 'Trial limit reached. Upgrade your plan.',
+        costUnits,
+      };
+    }
+
+    if (totalUnits + costUnits > FREE_TIER_QUOTAS.MAX_TRIAL_REQUEST_UNITS) {
+      return {
+        allowed: false,
+        reason: `Total trial request unit limit reached (${totalUnits}/${FREE_TIER_QUOTAS.MAX_TRIAL_REQUEST_UNITS}). Upgrade your plan.`,
+        costUnits,
+      };
+    }
+
+    const dailyUnits = params.dailyUnitsUsed ?? 0;
+    if (dailyUnits + costUnits > FREE_TIER_QUOTAS.MAX_DAILY_REQUEST_UNITS) {
+      return {
+        allowed: false,
+        reason: `Daily request quota limit reached (${dailyUnits}/${FREE_TIER_QUOTAS.MAX_DAILY_REQUEST_UNITS} units/day). Quota resets tomorrow.`,
+        costUnits,
+      };
+    }
+
+    return { allowed: true, costUnits };
+  }
+
+  static checkQueryAllowed(dailyQueriesCount = 0): { allowed: boolean; reason?: string } {
+    if (dailyQueriesCount >= FREE_TIER_QUOTAS.MAX_DAILY_REQUEST_UNITS) {
+      return {
+        allowed: false,
+        reason: `Daily query limit reached (${FREE_TIER_QUOTAS.MAX_DAILY_REQUEST_UNITS}/day). Quota resets tomorrow.`,
+      };
+    }
+
+    return { allowed: true };
+  }
+}

package/src/core/LangChainAgent.ts

@@ -14,7 +14,6 @@ import { RagConfig } from "../config/RagConfig";
  * - Invocation uses `{ messages: [...] }` instead of `{ input, chat_history }`.
  */
 export class LangChainAgent {
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
   private agent?: any;
 
   constructor(private pipeline: Pipeline, private config: RagConfig) {}
@@ -75,7 +74,6 @@ export class LangChainAgent {
       }
 
       this.agent = createAgent({
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
         model: chatModel as any,
         tools: [searchTool],
         systemPrompt: finalSystemPrompt,

package/src/core/LicenseValidator.ts

@@ -2,31 +2,79 @@ import { SDK_VERSION } from '../version';
 import { SDKVersionUnsupportedError, LicenseValidationError } from '../exceptions';
 import { LicenseVerifier } from './LicenseVerifier';
 
+/**
+ * Input contract for `LicenseValidator.validate()`.
+ *
+ * At least one source must yield a license key: `licenseKey` field, an
+ * `x-license-key` entry in `headers`, or the process environment variables
+ * (NEXT_PUBLIC_RETRIVORA_LICENSE_KEY / RETRIVORA_LICENSE_KEY).
+ */
 export interface LicenseValidationRequest {
+  /** Explicit `rtv_`-prefixed license key passed as a prop (highest priority). */
   licenseKey: string;
+  /** Project ID the caller is running under, checked for license binding match. */
   projectId?: string;
+  /** SDK version reported for minimum-supported-version enforcement (defaults to SDK_VERSION). */
   sdkVersion?: string;
+  /** SDK package identifier sent to server for observability. */
   sdk?: string;
+  /** browser | node — reported for observability only. */
   platform?: string;
+  /** Override base URL of the Retrivora API endpoint. Defaults to env or '/api/retrivora'. */
   retrivoraApiBase?: string;
+  /** Custom headers that may contain `x-license-key` or `Authorization: Bearer`. */
   headers?: Record<string, string>;
 }
 
+/**
+ * Response contract returned from `LicenseValidator.validate()`.
+ *
+ * Status enumerations are ordered — anything other than ACTIVE means the
+ * widget/chat must be disabled and must not pass server-side handler checks.
+ */
 export interface LicenseValidationResponse {
+  /** True only when `licenseStatus` is ACTIVE and SDK version is supported. */
   valid: boolean;
+  /** Lifecycle state of the license record. TERMINATED/SUSPENDED/EXPIRED/REVOKED must block chat. */
   licenseStatus: 'ACTIVE' | 'SUSPENDED' | 'TERMINATED' | 'EXPIRED' | 'REVOKED';
+  /** Minimum SDK version that the server will accept (semver-compare). */
   minimumSupportedVersion: string;
+  /** Latest generally-available SDK version (for upgrade prompts). */
   latestVersion: string;
+  /** True when the SDK version is older than minimumSupportedVersion — UI must force upgrade. */
   forceUpgrade: boolean;
+  /** RFC3339 expiration timestamp or null for perpetual licenses. */
   expiresAt: string | null;
+  /** Human-readable status/reason string, suitable for tooltips/toasts. */
   message: string;
 }
 
+/** Internal cache entry shape for successful validations only (failures are never cached). */
 interface CachedSuccessValidation {
   response: LicenseValidationResponse;
   timestamp: number;
 }
 
+/**
+ * Client-side orchestrator for license validation.
+ *
+ * Flow:
+ *   1. Resolve the license key (prop → header → env)
+ *   2. Return any fresh (< 5 min old) successful cached result
+ *   3. POST to `{retrivoraApiBase}/v1/license/validate` for server-side DB-backed status
+ *   4. On network or HTTP error, fall back to zero-latency local RSA signature
+ *      verification via `LicenseVerifier.verify()`.
+ *
+ * Caching policy:
+ *   - ONLY successful (valid + ACTIVE + !forceUpgrade) responses are cached
+ *   - Any failed validation immediately purges the cache entry
+ *   - TTL is 5 minutes for success cache to allow TERMINATED/REVOKED status
+ *     changes on the server to propagate quickly.
+ *
+ * Thread safety: Singleton pattern via `getInstance()`. Used by ChatWidget,
+ * useRagChat hook, and the server-side `createLicenseHandler` indirectly through
+ * its own `LicenseVerifier.verify()` path.
+ */
 export class LicenseValidator {
   private static instance: LicenseValidator;
   private cache: Map<string, CachedSuccessValidation> = new Map();
@@ -34,6 +82,7 @@ export class LicenseValidator {
 
   private constructor() {}
 
+  /** @returns Singleton instance of the validator (shared cache across all consumers). */
   public static getInstance(): LicenseValidator {
     if (!LicenseValidator.instance) {
       LicenseValidator.instance = new LicenseValidator();
@@ -42,7 +91,12 @@ export class LicenseValidator {
   }
 
   /**
-   * Invalidate local validation cache for a license key
+   * Purge entries from the local success cache.
+   *
+   * @param licenseKey - Optional. If provided, only that key's cache entry is
+   *                     removed. If omitted the entire cache is cleared.
+   *                     Callers use this after any 401/403 to ensure the next
+   *                     validate() call re-validates against the server.
    */
   public purgeCache(licenseKey?: string): void {
     if (licenseKey) {
@@ -53,7 +107,17 @@ export class LicenseValidator {
   }
 
   /**
-   * Validate license status and SDK version against Retrivora License Service
+   * Primary validation entry-point for UI / hook consumers.
+   *
+   * Resolves the license key, consults the local success cache, performs a
+   * server POST for authoritative status, and falls back to local RSA
+   * signature verification if the server can't be reached.
+   *
+   * @throws LicenseValidationError - When no key is provided OR both the
+   *         server call AND the local-RSA fallback report an invalid/expired key.
+   * @throws SDKVersionUnsupportedError - When server reports forceUpgrade=true.
+   * @returns A `LicenseValidationResponse` that the UI can use to enable or
+   *          lock the chat widget.
    */
   public async validate(request: LicenseValidationRequest): Promise<LicenseValidationResponse> {
     const {

package/src/core/LicenseVerifier.ts

@@ -1,15 +1,43 @@
 import * as crypto from 'crypto';
 import { ConfigurationException } from '../exceptions';
 
+/**
+ * Decoded payload of a Retrivora license JWT.
+ *
+ * Retrivora licenses are signed with RS256 using a key held exclusively by
+ * Retrivora SaaS. They carry the project binding, the expiration time, and
+ * the customer tier, which the SDK uses to enforce per-tier feature limits
+ * (vector DB provider whitelist).
+ */
 export interface LicensePayload {
+  /** Project ID this license is bound to — used to prevent cross-tenant reuse. */
   projectId: string;
-  expiresAt: number; // UNIX timestamp in seconds
+  /** UNIX timestamp in seconds after which the license must be considered expired. */
+  expiresAt: number;
+  /** Customer tier (hobby | pro | enterprise). */
   tier: string;
+  /** Optional: License lifecycle status propagated by the server validator (ACTIVE/TERMINATED/etc). */
+  licenseStatus?: string;
 }
 
 /**
- * LicenseVerifier — handles cryptographic validation of signed JWT license keys.
- * Enables zero-latency local license validation without external network calls.
+ * Zero-latency cryptographic license verifier.
+ *
+ * Responsibilities:
+ *   1. Parse the `rtv_`-prefixed JWT (base64url header.payload.signature)
+ *   2. Verify the RS256 signature against Retrivora's embedded PUBLIC_KEY
+ *   3. Match the license's projectId to the currently configured projectId
+ *   4. Enforce expiration (current UNIX seconds > expiresAt)
+ *   5. Enforce per-tier vector DB provider whitelist in production
+ *
+ * Fail-open policy: In non-production environments a missing license key
+ * produces a console-warning and a synthetic 24h "hobby" payload so that
+ * local development continues to work without signing up.  In production
+ * any missing/invalid key throws `ConfigurationException`.
+ *
+ * Caching: Cryptographic verification is CPU-expensive — successful results
+ * are cached for 60 seconds keyed by (licenseKey, projectId, provider,
+ * publicKeyOverride).  Cache hits still re-verify expiresAt.
  */
 export class LicenseVerifier {
   // A simple in-memory cache to save CPU overhead of cryptographic signature checks.

package/src/core/VectorPlugin.ts

@@ -7,6 +7,7 @@ import { IngestDocument, ChatResponse } from '../types';
 import { ChatMessage } from '../types';
 import { LicenseVerifier } from './LicenseVerifier';
 import { wrapError, RetrivoraErrorCode } from '../exceptions';
+import { FreeTierLimitsGuard } from './FreeTierLimitsGuard';
 
 /**
  * VectorPlugin — main orchestrator class.
@@ -78,6 +79,13 @@ export class VectorPlugin {
     );
   }
 
+  private estimateInputTokens(message: string, history: ChatMessage[] = []): number {
+    const allContent =
+      message.length +
+      history.reduce((acc, m) => acc + ((m as any)?.content?.length || (m as any)?.text?.length || 0), 0);
+    return Math.ceil(allContent / 4);
+  }
+
   /**
    * Run a chat query.
    */
@@ -88,6 +96,14 @@ export class VectorPlugin {
       throw wrapError(err, 'CONFIGURATION_ERROR');
     }
     try {
+      const inputTokens = this.estimateInputTokens(message, history);
+      const tokenCheck = (FreeTierLimitsGuard as any).checkRequestAllowed({
+        operationType: 'chat',
+        inputTokens,
+      });
+      if (!tokenCheck.allowed && tokenCheck.reason?.toLowerCase().includes('token')) {
+        throw wrapError(new Error(tokenCheck.reason), 'RATE_LIMITED');
+      }
       return await this.pipeline.ask(message, history, namespace);
     } catch (err) {
       const msg = String(err);
@@ -95,6 +111,9 @@ export class VectorPlugin {
       if (msg.includes('Embed') || msg.includes('embed')) {
         defaultCode = 'EMBEDDING_FAILED';
       }
+      if (msg.toLowerCase().includes('token limit')) {
+        defaultCode = 'RATE_LIMITED';
+      }
       throw wrapError(err, defaultCode);
     }
   }
@@ -109,6 +128,14 @@ export class VectorPlugin {
       throw wrapError(err, 'CONFIGURATION_ERROR');
     }
     try {
+      const inputTokens = this.estimateInputTokens(message, history);
+      const tokenCheck = (FreeTierLimitsGuard as any).checkRequestAllowed({
+        operationType: 'chat_stream',
+        inputTokens,
+      });
+      if (!tokenCheck.allowed && tokenCheck.reason?.toLowerCase().includes('token')) {
+        throw wrapError(new Error(tokenCheck.reason), 'RATE_LIMITED');
+      }
       const stream = this.pipeline.askStream(message, history, namespace);
       for await (const chunk of stream) {
         yield chunk;
@@ -119,6 +146,9 @@ export class VectorPlugin {
       if (msg.includes('Embed') || msg.includes('embed')) {
         defaultCode = 'EMBEDDING_FAILED';
       }
+      if (msg.toLowerCase().includes('token limit')) {
+        defaultCode = 'RATE_LIMITED';
+      }
       throw wrapError(err, defaultCode);
     }
   }