@jagilber-org/index-server 1.19.1

package/dist/services/usageBuckets.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Usage Buckets Service - Phase 2 Temporal Windowing Implementation
+ *
+ * Provides time-windowed usage tracking with bucket rotation and persistence.
+ * Maintains usage-buckets.json sidecar file for temporal analytics.
+ */
+/**
+ * Time bucket configuration
+ */
+export interface BucketConfig {
+    /** Bucket size in minutes (default: 60 = 1 hour) */
+    bucketSizeMinutes: number;
+    /** Number of buckets to maintain (default: 24 = 24 hours) */
+    bucketCount: number;
+    /** Maximum entries per bucket (default: 1000) */
+    maxEntriesPerBucket: number;
+}
+/**
+ * Usage entry within a time bucket
+ */
+export interface UsageEntry {
+    timestamp: string;
+    operation: string;
+    instructionId?: string;
+    clientInfo?: string;
+    durationMs?: number;
+    success: boolean;
+    errorCode?: string;
+}
+/**
+ * Time bucket containing usage entries
+ */
+export interface UsageBucket {
+    /** Bucket start time (ISO 8601 UTC) */
+    startTime: string;
+    /** Bucket end time (ISO 8601 UTC) */
+    endTime: string;
+    /** Usage entries in this bucket */
+    entries: UsageEntry[];
+    /** Entry count for quick access */
+    entryCount: number;
+    /** Bucket creation timestamp */
+    createdAt: string;
+    /** Last update timestamp */
+    lastUpdated: string;
+}
+/**
+ * Usage buckets container with metadata
+ */
+export interface UsageBucketsContainer {
+    /** Configuration used */
+    config: BucketConfig;
+    /** Current bucket index (0 to bucketCount-1) */
+    currentBucketIndex: number;
+    /** Ring of time buckets */
+    buckets: UsageBucket[];
+    /** Container creation timestamp */
+    createdAt: string;
+    /** Last rotation timestamp */
+    lastRotation: string;
+    /** Total entries across all buckets */
+    totalEntries: number;
+    /** Metrics summary */
+    metrics: {
+        rotationCount: number;
+        totalOperations: number;
+        successRate: number;
+        avgDurationMs: number;
+    };
+    /** Integrity hash (sha256) over critical fields */
+    containerHash?: string;
+}
+/**
+ * Usage Buckets Service
+ */
+export declare class UsageBucketsService {
+    private container;
+    private bucketsFilePath;
+    private config;
+    private timeProvider;
+    constructor(instructionsDir: string, config?: Partial<BucketConfig>, opts?: {
+        timeProvider?: () => Date;
+    });
+    /**
+     * Initialize or load existing buckets container
+     */
+    initialize(): Promise<void>;
+    /**
+     * Record a usage entry
+     */
+    recordUsage(entry: Omit<UsageEntry, 'timestamp'>): Promise<void>;
+    /**
+     * Get current usage statistics
+     */
+    getStats(): {
+        currentBucket: UsageBucket;
+        totalEntries: number;
+        metrics: UsageBucketsContainer['metrics'];
+        bucketCount: number;
+    };
+    /**
+     * Get usage entries for a time range
+     */
+    getEntriesInRange(startTime: string, endTime: string): UsageEntry[];
+    /**
+     * Force a bucket rotation (for testing)
+     */
+    forceRotation(): Promise<void>;
+    /**
+     * Get the current bucket
+     */
+    private getCurrentBucket;
+    /**
+     * Check if bucket rotation is needed and perform it
+     */
+    private maybeRotate;
+    /**
+     * Rotate buckets and create new current bucket
+     */
+    private rotateBuckets;
+    /**
+     * Create a new container
+     */
+    private createContainer;
+    /**
+     * Load container from disk
+     */
+    private loadContainer;
+    /**
+     * Save container to disk
+     */
+    private saveContainer;
+    /**
+     * Get bucket start time aligned to bucket boundaries
+     */
+    private getBucketStartTime;
+    /**
+     * Update container metrics
+     */
+    private updateMetrics;
+    /**
+     * Compute integrity hash for container (excluding containerHash field itself)
+     */
+    private computeHash;
+    /**
+     * Verify integrity hash of a loaded container
+     */
+    private verifyHash;
+    /**
+     * Exposed only for testing: return internal container snapshot
+     */
+    _debugGetContainer(): UsageBucketsContainer | null;
+}
+/**
+ * Get or create the global usage buckets service instance
+ */
+export declare function getUsageBucketsService(instructionsDir?: string, config?: Partial<BucketConfig>): UsageBucketsService;
+/**
+ * Record usage for the global instance
+ */
+export declare function recordUsage(entry: Omit<UsageEntry, 'timestamp'>): Promise<void>;

package/dist/services/usageBuckets.js

@@ -0,0 +1,364 @@
+"use strict";
+/**
+ * Usage Buckets Service - Phase 2 Temporal Windowing Implementation
+ *
+ * Provides time-windowed usage tracking with bucket rotation and persistence.
+ * Maintains usage-buckets.json sidecar file for temporal analytics.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UsageBucketsService = void 0;
+exports.getUsageBucketsService = getUsageBucketsService;
+exports.recordUsage = recordUsage;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const crypto_1 = __importDefault(require("crypto"));
+const logger_1 = require("./logger");
+/**
+ * Default bucket configuration
+ */
+const DEFAULT_CONFIG = {
+    bucketSizeMinutes: 60, // 1 hour buckets
+    bucketCount: 24, // 24 hours of history
+    maxEntriesPerBucket: 1000
+};
+/**
+ * Usage Buckets Service
+ */
+class UsageBucketsService {
+    container = null;
+    bucketsFilePath;
+    config;
+    timeProvider;
+    constructor(instructionsDir, config = {}, opts = {}) {
+        this.bucketsFilePath = path_1.default.join(instructionsDir, 'usage-buckets.json');
+        this.config = { ...DEFAULT_CONFIG, ...config };
+        this.timeProvider = opts.timeProvider ?? (() => new Date());
+    }
+    /**
+     * Initialize or load existing buckets container
+     */
+    async initialize() {
+        try {
+            if (fs_1.default.existsSync(this.bucketsFilePath)) {
+                await this.loadContainer();
+                (0, logger_1.logInfo)(`[usageBuckets] Loaded existing container from ${this.bucketsFilePath}`);
+            }
+            else {
+                await this.createContainer();
+                (0, logger_1.logInfo)(`[usageBuckets] Created new container at ${this.bucketsFilePath}`);
+            }
+            // Check if rotation is needed
+            await this.maybeRotate();
+        }
+        catch (error) {
+            (0, logger_1.logError)(`[usageBuckets] Failed to initialize`, error);
+            // Fallback: create new container
+            await this.createContainer();
+        }
+    }
+    /**
+     * Record a usage entry
+     */
+    async recordUsage(entry) {
+        if (!this.container) {
+            await this.initialize();
+        }
+        const usageEntry = {
+            ...entry,
+            timestamp: this.timeProvider().toISOString()
+        };
+        // Add to current bucket
+        const currentBucket = this.getCurrentBucket();
+        currentBucket.entries.push(usageEntry);
+        currentBucket.entryCount++;
+        currentBucket.lastUpdated = usageEntry.timestamp;
+        // Update container metrics
+        this.updateMetrics(usageEntry);
+        // Check for rotation and persistence
+        await this.maybeRotate();
+        // Persist immediately for reliability
+        await this.saveContainer();
+    }
+    /**
+     * Get current usage statistics
+     */
+    getStats() {
+        if (!this.container) {
+            throw new Error('UsageBuckets not initialized');
+        }
+        return {
+            currentBucket: this.getCurrentBucket(),
+            totalEntries: this.container.totalEntries,
+            metrics: this.container.metrics,
+            bucketCount: this.container.buckets.length
+        };
+    }
+    /**
+     * Get usage entries for a time range
+     */
+    getEntriesInRange(startTime, endTime) {
+        if (!this.container) {
+            return [];
+        }
+        const start = new Date(startTime);
+        const end = new Date(endTime);
+        const entries = [];
+        for (const bucket of this.container.buckets) {
+            const bucketStart = new Date(bucket.startTime);
+            const bucketEnd = new Date(bucket.endTime);
+            // Check if bucket overlaps with requested range
+            if (bucketEnd >= start && bucketStart <= end) {
+                // Filter entries within the exact time range
+                const filteredEntries = bucket.entries.filter(entry => {
+                    const entryTime = new Date(entry.timestamp);
+                    return entryTime >= start && entryTime <= end;
+                });
+                entries.push(...filteredEntries);
+            }
+        }
+        return entries.sort((a, b) => a.timestamp.localeCompare(b.timestamp));
+    }
+    /**
+     * Force a bucket rotation (for testing)
+     */
+    async forceRotation() {
+        if (!this.container) {
+            await this.initialize();
+        }
+        await this.rotateBuckets();
+        await this.saveContainer();
+        (0, logger_1.logInfo)('[usageBuckets] Forced bucket rotation');
+    }
+    /**
+     * Get the current bucket
+     */
+    getCurrentBucket() {
+        if (!this.container) {
+            throw new Error('Container not initialized');
+        }
+        return this.container.buckets[this.container.currentBucketIndex];
+    }
+    /**
+     * Check if bucket rotation is needed and perform it
+     */
+    async maybeRotate() {
+        if (!this.container)
+            return;
+        const currentBucket = this.getCurrentBucket();
+        const now = this.timeProvider();
+        const bucketEnd = new Date(currentBucket.endTime);
+        if (now >= bucketEnd) {
+            await this.rotateBuckets();
+            (0, logger_1.logInfo)(`[usageBuckets] Rotated buckets at ${now.toISOString()}`);
+        }
+    }
+    /**
+     * Rotate buckets and create new current bucket
+     */
+    async rotateBuckets() {
+        if (!this.container)
+            return;
+        const now = this.timeProvider();
+        const bucketStartTime = this.getBucketStartTime(now);
+        const bucketEndTime = new Date(bucketStartTime.getTime() + this.config.bucketSizeMinutes * 60 * 1000);
+        // Move to next bucket index (circular)
+        this.container.currentBucketIndex = (this.container.currentBucketIndex + 1) % this.config.bucketCount;
+        // Replace the bucket at current index
+        const newBucket = {
+            startTime: bucketStartTime.toISOString(),
+            endTime: bucketEndTime.toISOString(),
+            entries: [],
+            entryCount: 0,
+            createdAt: now.toISOString(),
+            lastUpdated: now.toISOString()
+        };
+        // Update total entries count (subtract old bucket entries)
+        const oldBucket = this.container.buckets[this.container.currentBucketIndex];
+        this.container.totalEntries -= oldBucket.entryCount;
+        // Replace bucket
+        this.container.buckets[this.container.currentBucketIndex] = newBucket;
+        // Update container metadata
+        this.container.lastRotation = now.toISOString();
+        this.container.metrics.rotationCount++;
+    }
+    /**
+     * Create a new container
+     */
+    async createContainer() {
+        const now = this.timeProvider();
+        const buckets = [];
+        // Create initial buckets
+        for (let i = 0; i < this.config.bucketCount; i++) {
+            const bucketStart = new Date(now.getTime() - (this.config.bucketCount - 1 - i) * this.config.bucketSizeMinutes * 60 * 1000);
+            const bucketStartTime = this.getBucketStartTime(bucketStart);
+            const bucketEndTime = new Date(bucketStartTime.getTime() + this.config.bucketSizeMinutes * 60 * 1000);
+            buckets.push({
+                startTime: bucketStartTime.toISOString(),
+                endTime: bucketEndTime.toISOString(),
+                entries: [],
+                entryCount: 0,
+                createdAt: now.toISOString(),
+                lastUpdated: now.toISOString()
+            });
+        }
+        this.container = {
+            config: { ...this.config },
+            currentBucketIndex: this.config.bucketCount - 1, // Latest bucket
+            buckets,
+            createdAt: now.toISOString(),
+            lastRotation: now.toISOString(),
+            totalEntries: 0,
+            metrics: {
+                rotationCount: 0,
+                totalOperations: 0,
+                successRate: 1.0,
+                avgDurationMs: 0
+            }
+        };
+        await this.saveContainer();
+    }
+    /**
+     * Load container from disk
+     */
+    async loadContainer() {
+        const attemptLoad = (file) => {
+            try {
+                const raw = fs_1.default.readFileSync(file, 'utf8');
+                const parsed = JSON.parse(raw);
+                if (!parsed || !parsed.buckets || !Array.isArray(parsed.buckets)) {
+                    throw new Error('Invalid format');
+                }
+                return parsed;
+            }
+            catch (e) {
+                (0, logger_1.logError)(`[usageBuckets] Failed to load ${file}`, e);
+                return null;
+            }
+        };
+        const primary = attemptLoad(this.bucketsFilePath);
+        const backupPath = this.bucketsFilePath + '.bak';
+        let container = primary;
+        if (!container || !this.verifyHash(container)) {
+            (0, logger_1.logError)('[usageBuckets] Primary container missing or hash mismatch, attempting backup');
+            const backup = fs_1.default.existsSync(backupPath) ? attemptLoad(backupPath) : null;
+            if (backup && this.verifyHash(backup)) {
+                container = backup;
+            }
+            else {
+                (0, logger_1.logError)('[usageBuckets] Backup container invalid or hash mismatch; rebuilding new container');
+                await this.createContainer();
+                return;
+            }
+        }
+        // Update config if changed
+        container.config = { ...container.config, ...this.config };
+        this.container = container;
+    }
+    /**
+     * Save container to disk
+     */
+    async saveContainer() {
+        if (!this.container)
+            return;
+        // Ensure directory exists
+        const dir = path_1.default.dirname(this.bucketsFilePath);
+        if (!fs_1.default.existsSync(dir)) {
+            fs_1.default.mkdirSync(dir, { recursive: true });
+        }
+        // Write atomically
+        // Update hash prior to save
+        this.container.containerHash = this.computeHash(this.container);
+        const serialized = JSON.stringify(this.container, null, 2);
+        const tempFile = this.bucketsFilePath + '.tmp';
+        fs_1.default.writeFileSync(tempFile, serialized);
+        fs_1.default.renameSync(tempFile, this.bucketsFilePath);
+        // Maintain backup copy for recovery
+        try {
+            fs_1.default.writeFileSync(this.bucketsFilePath + '.bak', serialized);
+        }
+        catch (e) {
+            (0, logger_1.logError)(`[usageBuckets] Failed to write backup`, e);
+        }
+    }
+    /**
+     * Get bucket start time aligned to bucket boundaries
+     */
+    getBucketStartTime(date) {
+        const minutes = date.getMinutes();
+        const alignedMinutes = Math.floor(minutes / this.config.bucketSizeMinutes) * this.config.bucketSizeMinutes;
+        const aligned = new Date(date);
+        aligned.setMinutes(alignedMinutes, 0, 0); // Clear seconds and milliseconds
+        return aligned;
+    }
+    /**
+     * Update container metrics
+     */
+    updateMetrics(entry) {
+        if (!this.container)
+            return;
+        this.container.totalEntries++;
+        this.container.metrics.totalOperations++;
+        // Update success rate
+        const totalOps = this.container.metrics.totalOperations;
+        const currentSuccessCount = Math.round(this.container.metrics.successRate * (totalOps - 1));
+        const newSuccessCount = currentSuccessCount + (entry.success ? 1 : 0);
+        this.container.metrics.successRate = newSuccessCount / totalOps;
+        // Update average duration
+        if (entry.durationMs !== undefined) {
+            const currentAvg = this.container.metrics.avgDurationMs;
+            const currentCount = totalOps - 1;
+            this.container.metrics.avgDurationMs = (currentAvg * currentCount + entry.durationMs) / totalOps;
+        }
+    }
+    /**
+     * Compute integrity hash for container (excluding containerHash field itself)
+     */
+    computeHash(container) {
+        const { containerHash: _unusedHash, ...rest } = container; // exclude hash field
+        void _unusedHash; // satisfy linter for intentional discard
+        const hash = crypto_1.default.createHash('sha256');
+        hash.update(JSON.stringify(rest));
+        return hash.digest('hex');
+    }
+    /**
+     * Verify integrity hash of a loaded container
+     */
+    verifyHash(container) {
+        if (!container.containerHash)
+            return false;
+        const expected = this.computeHash(container);
+        return expected === container.containerHash;
+    }
+    /**
+     * Exposed only for testing: return internal container snapshot
+     */
+    /* @internal */
+    _debugGetContainer() {
+        return this.container ? JSON.parse(JSON.stringify(this.container)) : null;
+    }
+}
+exports.UsageBucketsService = UsageBucketsService;
+// Singleton instance for server use
+let usageBucketsInstance = null;
+/**
+ * Get or create the global usage buckets service instance
+ */
+function getUsageBucketsService(instructionsDir, config = {}) {
+    if (!usageBucketsInstance && instructionsDir) {
+        usageBucketsInstance = new UsageBucketsService(instructionsDir, config);
+    }
+    if (!usageBucketsInstance) {
+        throw new Error('Usage buckets service not initialized - call with instructionsDir first');
+    }
+    return usageBucketsInstance;
+}
+/**
+ * Record usage for the global instance
+ */
+async function recordUsage(entry) {
+    const service = getUsageBucketsService();
+    await service.recordUsage(entry);
+}

package/dist/services/validationService.d.ts

@@ -0,0 +1,38 @@
+import { ErrorObject } from 'ajv';
+interface ValidationCounters {
+    zodSuccess: number;
+    zodFailure: number;
+    ajvSuccess: number;
+    ajvFailure: number;
+    mode: string;
+}
+declare global {
+    var __MCP_VALIDATION_METRICS__: ValidationCounters | undefined;
+}
+/**
+ * Validate request parameters against the registered JSON Schema (or Zod schema) for `method`.
+ * Returns `{ ok: true }` when no schema is registered (fail-open) or when validation passes.
+ * @param method - JSON-RPC method name whose schema should be used for validation
+ * @param params - Parameter value received from the caller (may be `undefined`)
+ * @returns `{ ok: true }` on success, or `{ ok: false; errors: ErrorObject[] }` on failure
+ */
+export declare function validateParams(method: string, params: unknown): {
+    ok: true;
+} | {
+    ok: false;
+    errors: ErrorObject[];
+};
+/** Evict all cached validators, forcing re-compilation on the next call to {@link validateParams}. */
+export declare function clearValidationCache(): void;
+/**
+ * Return a snapshot of the validation counters for use in metrics reporting.
+ * @returns Copy of the current Zod vs. Ajv success/failure counters and active mode
+ */
+export declare function getValidationMetrics(): {
+    zodSuccess: number;
+    zodFailure: number;
+    ajvSuccess: number;
+    ajvFailure: number;
+    mode: string;
+};
+export {};

package/dist/services/validationService.js

@@ -0,0 +1,125 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateParams = validateParams;
+exports.clearValidationCache = clearValidationCache;
+exports.getValidationMetrics = getValidationMetrics;
+const ajv_1 = __importDefault(require("ajv"));
+const ajv_formats_1 = __importDefault(require("ajv-formats"));
+const json_schema_draft_07_json_1 = __importDefault(require("ajv/dist/refs/json-schema-draft-07.json"));
+const runtimeConfig_1 = require("../config/runtimeConfig");
+const toolRegistry_zod_1 = require("./toolRegistry.zod");
+const zod_1 = require("zod");
+const ajv = new ajv_1.default({ allErrors: true, strict: false });
+(0, ajv_formats_1.default)(ajv);
+try {
+    if (!ajv.getSchema('https://json-schema.org/draft-07/schema'))
+        ajv.addMetaSchema(json_schema_draft_07_json_1.default, 'https://json-schema.org/draft-07/schema');
+}
+catch (e) {
+    // ignore meta-schema registration errors (non-fatal)
+}
+const cache = new Map();
+// Validation mode feature flag is centrally defined via runtime config.
+// Modes: 'ajv' => force Ajv only, 'zod' (default) => prefer Zod with Ajv fallback, 'auto' reserved for future heuristics.
+function resolveValidationMode() {
+    const mode = (0, runtimeConfig_1.getRuntimeConfig)().validation.mode;
+    return mode && mode.trim().length ? mode : 'zod';
+}
+const validationCounters = { zodSuccess: 0, zodFailure: 0, ajvSuccess: 0, ajvFailure: 0, mode: resolveValidationMode() };
+function resolveValidationSettings() {
+    const mode = resolveValidationMode();
+    validationCounters.mode = mode;
+    return { mode, forceAjv: mode === 'ajv' };
+}
+globalThis.__MCP_VALIDATION_METRICS__ = validationCounters;
+function buildValidator(method) {
+    try {
+        const reg = (0, toolRegistry_zod_1.getZodEnhancedRegistry)().find(t => t.name === method);
+        if (!reg)
+            return null;
+        const compiled = ajv.compile(reg.inputSchema);
+        const { forceAjv } = resolveValidationSettings();
+        if (reg.zodSchema && !forceAjv) {
+            const z = reg.zodSchema;
+            const v = {
+                validate: (d) => {
+                    try {
+                        z.parse(d ?? {});
+                        return true;
+                    }
+                    catch (e) {
+                        if (e instanceof zod_1.ZodError) {
+                            // Map Zod issues into Ajv-like errors for uniform consumption
+                            compiled.errors = e.issues.map(issue => ({
+                                instancePath: issue.path.length ? '/' + issue.path.join('/') : '',
+                                keyword: issue.code,
+                                message: issue.message,
+                                params: { issue },
+                                schemaPath: '#'
+                            }));
+                            validationCounters.zodFailure++;
+                            return false;
+                        }
+                        validationCounters.zodFailure++;
+                        return false;
+                    }
+                },
+                errors: null,
+                zod: z,
+                ajvFn: compiled
+            };
+            return v;
+        }
+        return { validate: (d) => compiled(d), errors: null };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Validate request parameters against the registered JSON Schema (or Zod schema) for `method`.
+ * Returns `{ ok: true }` when no schema is registered (fail-open) or when validation passes.
+ * @param method - JSON-RPC method name whose schema should be used for validation
+ * @param params - Parameter value received from the caller (may be `undefined`)
+ * @returns `{ ok: true }` on success, or `{ ok: false; errors: ErrorObject[] }` on failure
+ */
+function validateParams(method, params) {
+    let entry = cache.get(method);
+    if (entry === undefined) {
+        entry = buildValidator(method);
+        cache.set(method, entry);
+    }
+    if (!entry)
+        return { ok: true }; // no schema => accept
+    const { forceAjv } = resolveValidationSettings();
+    const ok = entry.validate(params === undefined ? {} : params);
+    const hasZod = entry.zod !== undefined && !forceAjv;
+    if (ok) {
+        if (hasZod) {
+            validationCounters.zodSuccess++;
+        }
+        else {
+            validationCounters.ajvSuccess++;
+        }
+        return { ok: true };
+    }
+    if (hasZod) {
+        validationCounters.zodFailure++;
+    }
+    else {
+        validationCounters.ajvFailure++;
+    }
+    const v = entry.validate;
+    const errors = (v && typeof v === 'object' && 'errors' in v) ? v.errors || [] : [];
+    return { ok: false, errors };
+}
+/** Evict all cached validators, forcing re-compilation on the next call to {@link validateParams}. */
+function clearValidationCache() { cache.clear(); }
+/**
+ * Return a snapshot of the validation counters for use in metrics reporting.
+ * @returns Copy of the current Zod vs. Ajv success/failure counters and active mode
+ */
+function getValidationMetrics() { return { ...validationCounters }; }