guardrail-core 1.0.0

package/dist/fix-packs/types.js

@@ -0,0 +1,71 @@
+"use strict";
+/**
+ * Fix Packs Types
+ *
+ * First-class objects that group findings into actionable batches.
+ * Used by CLI, Autopilot, and Verified AutoFix.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FIX_STRATEGIES = exports.SEVERITY_ORDER = exports.SEVERITY_LEVELS = exports.FINDING_CATEGORIES = void 0;
+exports.compareSeverity = compareSeverity;
+exports.isHigherSeverity = isHigherSeverity;
+exports.getHighestSeverity = getHighestSeverity;
+exports.generatePackId = generatePackId;
+exports.sortPacksBySeverity = sortPacksBySeverity;
+// ============================================================================
+// FINDING CATEGORY ENUM
+// ============================================================================
+exports.FINDING_CATEGORIES = [
+    'secrets',
+    'routes',
+    'mocks',
+    'auth',
+    'placeholders',
+    'deps',
+    'types',
+    'tests',
+    'security',
+    'performance',
+];
+// ============================================================================
+// SEVERITY LEVELS
+// ============================================================================
+exports.SEVERITY_LEVELS = ['critical', 'high', 'medium', 'low', 'info'];
+exports.SEVERITY_ORDER = {
+    critical: 0,
+    high: 1,
+    medium: 2,
+    low: 3,
+    info: 4,
+};
+// ============================================================================
+// FIX STRATEGY
+// ============================================================================
+exports.FIX_STRATEGIES = [
+    'auto', // Fully automated fix
+    'guided', // AI-guided with human review
+    'manual', // Requires manual intervention
+    'ai-assisted', // AI generates suggestions
+];
+// ============================================================================
+// HELPER FUNCTIONS
+// ============================================================================
+function compareSeverity(a, b) {
+    return exports.SEVERITY_ORDER[a] - exports.SEVERITY_ORDER[b];
+}
+function isHigherSeverity(a, b) {
+    return compareSeverity(a, b) < 0;
+}
+function getHighestSeverity(severities) {
+    if (severities.length === 0)
+        return 'info';
+    return severities.reduce((highest, current) => isHigherSeverity(current, highest) ? current : highest);
+}
+function generatePackId(category, index, hash) {
+    const categoryPrefix = category.slice(0, 3).toUpperCase();
+    const hashSuffix = hash.slice(0, 6);
+    return `FP-${categoryPrefix}-${String(index).padStart(3, '0')}-${hashSuffix}`;
+}
+function sortPacksBySeverity(packs) {
+    return [...packs].sort((a, b) => compareSeverity(a.severity, b.severity));
+}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export * from "./cache/redis-cache";
+export * from "./entitlements";
+export * from "./env";
+export * from "./fix-packs";
+export * from "./metrics/prometheus";
+export * from "./rbac";
+export * from "./tier-config";
+export * from "./types";
+export * from "./utils";
+export * from "./visualization/dependency-graph";
+export * from "./autopilot";
+export * from "./verified-autofix";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,OAAO,CAAC;AACtB,cAAc,aAAa,CAAC;AAC5B,cAAc,sBAAsB,CAAC;AACrC,cAAc,QAAQ,CAAC;AACvB,cAAc,eAAe,CAAC;AAC9B,cAAc,SAAS,CAAC;AACxB,cAAc,SAAS,CAAC;AACxB,cAAc,kCAAkC,CAAC;AACjD,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC"}

package/dist/index.js

@@ -0,0 +1,28 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./cache/redis-cache"), exports);
+__exportStar(require("./entitlements"), exports);
+__exportStar(require("./env"), exports);
+__exportStar(require("./fix-packs"), exports);
+__exportStar(require("./metrics/prometheus"), exports);
+__exportStar(require("./rbac"), exports);
+__exportStar(require("./tier-config"), exports);
+__exportStar(require("./types"), exports);
+__exportStar(require("./utils"), exports);
+__exportStar(require("./visualization/dependency-graph"), exports);
+__exportStar(require("./autopilot"), exports);
+__exportStar(require("./verified-autofix"), exports);

package/dist/metrics/prometheus.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Prometheus Metrics
+ *
+ * Production-ready metrics collection for Guardrail AI
+ * Exposes metrics in Prometheus format for monitoring and alerting
+ */
+export interface MetricLabels {
+    [key: string]: string;
+}
+export interface MetricValue {
+    value: number;
+    labels: MetricLabels;
+    timestamp?: number;
+}
+export interface Metric {
+    name: string;
+    help: string;
+    type: "counter" | "gauge" | "histogram" | "summary";
+    values: MetricValue[];
+}
+declare class Counter {
+    readonly name: string;
+    readonly help: string;
+    readonly labelNames: string[];
+    private values;
+    constructor(name: string, help: string, labelNames?: string[]);
+    inc(labels?: MetricLabels, value?: number): void;
+    get(labels?: MetricLabels): number;
+    reset(): void;
+    collect(): MetricValue[];
+    private labelsToKey;
+    private keyToLabels;
+}
+declare class Gauge {
+    readonly name: string;
+    readonly help: string;
+    readonly labelNames: string[];
+    private values;
+    constructor(name: string, help: string, labelNames?: string[]);
+    set(labels: MetricLabels, value: number): void;
+    set(value: number): void;
+    inc(labels?: MetricLabels, value?: number): void;
+    dec(labels?: MetricLabels, value?: number): void;
+    get(labels?: MetricLabels): number;
+    collect(): MetricValue[];
+    private labelsToKey;
+    private keyToLabels;
+}
+declare class Histogram {
+    readonly name: string;
+    readonly help: string;
+    readonly labelNames: string[];
+    private buckets;
+    private values;
+    constructor(name: string, help: string, labelNames?: string[], buckets?: number[]);
+    observe(labels: MetricLabels, value: number): void;
+    observe(value: number): void;
+    startTimer(labels?: MetricLabels): () => number;
+    collect(): MetricValue[];
+    private labelsToKey;
+    private keyToLabels;
+}
+/**
+ * Guardrail Metrics Registry
+ */
+declare class MetricsRegistry {
+    readonly scansTotal: Counter;
+    readonly scanDuration: Histogram;
+    readonly injectionsDetected: Counter;
+    readonly injectionScanDuration: Histogram;
+    readonly vulnerabilitiesFound: Counter;
+    readonly vulnerablePackages: Gauge;
+    readonly secretsDetected: Counter;
+    readonly complianceScore: Gauge;
+    readonly complianceViolations: Counter;
+    readonly apiRequestsTotal: Counter;
+    readonly apiRequestDuration: Histogram;
+    readonly agentActionsTotal: Counter;
+    readonly agentActionsBlocked: Counter;
+    readonly cacheHits: Counter;
+    readonly cacheMisses: Counter;
+    readonly activeConnections: Gauge;
+    readonly memoryUsageBytes: Gauge;
+    /**
+     * Generate Prometheus-formatted output
+     */
+    generatePrometheusOutput(): string;
+    /**
+     * Update system metrics
+     */
+    updateSystemMetrics(): void;
+    /**
+     * Reset all metrics (for testing)
+     */
+    resetAll(): void;
+}
+export declare const metrics: MetricsRegistry;
+export { Counter, Gauge, Histogram };
+//# sourceMappingURL=prometheus.d.ts.map

package/dist/metrics/prometheus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prometheus.d.ts","sourceRoot":"","sources":["../../src/metrics/prometheus.ts"],"names":[],"mappings":"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"}

package/dist/metrics/prometheus.js

@@ -0,0 +1,306 @@
+"use strict";
+/**
+ * Prometheus Metrics
+ *
+ * Production-ready metrics collection for Guardrail AI
+ * Exposes metrics in Prometheus format for monitoring and alerting
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Histogram = exports.Gauge = exports.Counter = exports.metrics = void 0;
+class Counter {
+    name;
+    help;
+    labelNames;
+    values = new Map();
+    constructor(name, help, labelNames = []) {
+        this.name = name;
+        this.help = help;
+        this.labelNames = labelNames;
+    }
+    inc(labels = {}, value = 1) {
+        const key = this.labelsToKey(labels);
+        const current = this.values.get(key) || 0;
+        this.values.set(key, current + value);
+    }
+    get(labels = {}) {
+        const key = this.labelsToKey(labels);
+        return this.values.get(key) || 0;
+    }
+    reset() {
+        this.values.clear();
+    }
+    collect() {
+        const result = [];
+        for (const [key, value] of this.values) {
+            result.push({
+                value,
+                labels: this.keyToLabels(key),
+            });
+        }
+        return result;
+    }
+    labelsToKey(labels) {
+        return this.labelNames.map((name) => labels[name] || "").join("|");
+    }
+    keyToLabels(key) {
+        const values = key.split("|");
+        const labels = {};
+        this.labelNames.forEach((name, i) => {
+            if (values[i]) {
+                labels[name] = values[i];
+            }
+        });
+        return labels;
+    }
+}
+exports.Counter = Counter;
+class Gauge {
+    name;
+    help;
+    labelNames;
+    values = new Map();
+    constructor(name, help, labelNames = []) {
+        this.name = name;
+        this.help = help;
+        this.labelNames = labelNames;
+    }
+    set(labelsOrValue, value) {
+        if (typeof labelsOrValue === "number") {
+            this.values.set("", labelsOrValue);
+        }
+        else {
+            const key = this.labelsToKey(labelsOrValue);
+            this.values.set(key, value);
+        }
+    }
+    inc(labels = {}, value = 1) {
+        const key = this.labelsToKey(labels);
+        const current = this.values.get(key) || 0;
+        this.values.set(key, current + value);
+    }
+    dec(labels = {}, value = 1) {
+        const key = this.labelsToKey(labels);
+        const current = this.values.get(key) || 0;
+        this.values.set(key, current - value);
+    }
+    get(labels = {}) {
+        const key = this.labelsToKey(labels);
+        return this.values.get(key) || 0;
+    }
+    collect() {
+        const result = [];
+        for (const [key, value] of this.values) {
+            result.push({
+                value,
+                labels: this.keyToLabels(key),
+            });
+        }
+        return result;
+    }
+    labelsToKey(labels) {
+        return this.labelNames.map((name) => labels[name] || "").join("|");
+    }
+    keyToLabels(key) {
+        const values = key.split("|");
+        const labels = {};
+        this.labelNames.forEach((name, i) => {
+            if (values[i]) {
+                labels[name] = values[i];
+            }
+        });
+        return labels;
+    }
+}
+exports.Gauge = Gauge;
+class Histogram {
+    name;
+    help;
+    labelNames;
+    buckets;
+    values = new Map();
+    constructor(name, help, labelNames = [], buckets) {
+        this.name = name;
+        this.help = help;
+        this.labelNames = labelNames;
+        this.buckets = buckets || [
+            0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10,
+        ];
+    }
+    observe(labelsOrValue, value) {
+        let labels;
+        let observedValue;
+        if (typeof labelsOrValue === "number") {
+            labels = {};
+            observedValue = labelsOrValue;
+        }
+        else {
+            labels = labelsOrValue;
+            observedValue = value;
+        }
+        const key = this.labelsToKey(labels);
+        let data = this.values.get(key);
+        if (!data) {
+            data = {
+                sum: 0,
+                count: 0,
+                buckets: new Array(this.buckets.length).fill(0),
+            };
+            this.values.set(key, data);
+        }
+        data.sum += observedValue;
+        data.count++;
+        for (let i = 0; i < this.buckets.length; i++) {
+            const bucket = this.buckets[i];
+            if (bucket !== undefined && observedValue <= bucket) {
+                // @ts-ignore
+                data.buckets[i]++;
+            }
+        }
+    }
+    startTimer(labels = {}) {
+        const start = process.hrtime.bigint();
+        return () => {
+            const end = process.hrtime.bigint();
+            const durationMs = Number(end - start) / 1e6;
+            this.observe(labels, durationMs / 1000); // Convert to seconds
+            return durationMs;
+        };
+    }
+    collect() {
+        const result = [];
+        for (const [key, data] of this.values) {
+            const labels = this.keyToLabels(key);
+            // Add bucket values
+            for (let i = 0; i < this.buckets.length; i++) {
+                const bucketValue = data.buckets[i] ?? 0;
+                const bucketLimit = this.buckets[i] ?? 0;
+                result.push({
+                    value: bucketValue,
+                    labels: { ...labels, le: String(bucketLimit) },
+                });
+            }
+            // Add +Inf bucket
+            result.push({
+                value: data.count,
+                labels: { ...labels, le: "+Inf" },
+            });
+            // Add sum and count
+            result.push({
+                value: data.sum,
+                labels: { ...labels, quantile: "sum" },
+            });
+            result.push({
+                value: data.count,
+                labels: { ...labels, quantile: "count" },
+            });
+        }
+        return result;
+    }
+    labelsToKey(labels) {
+        return this.labelNames.map((name) => labels[name] || "").join("|");
+    }
+    keyToLabels(key) {
+        const values = key.split("|");
+        const labels = {};
+        this.labelNames.forEach((name, i) => {
+            if (values[i]) {
+                labels[name] = values[i];
+            }
+        });
+        return labels;
+    }
+}
+exports.Histogram = Histogram;
+/**
+ * Guardrail Metrics Registry
+ */
+class MetricsRegistry {
+    // Scan metrics
+    scansTotal = new Counter("Guardrail_scans_total", "Total number of security scans performed", ["scan_type", "status"]);
+    scanDuration = new Histogram("Guardrail_scan_duration_seconds", "Duration of security scans in seconds", ["scan_type"], [0.1, 0.5, 1, 2, 5, 10, 30, 60]);
+    // Injection detection metrics
+    injectionsDetected = new Counter("Guardrail_injections_detected_total", "Total number of prompt injection attempts detected", ["severity", "type"]);
+    injectionScanDuration = new Histogram("Guardrail_injection_scan_duration_seconds", "Duration of injection scans in seconds", ["content_type"]);
+    // Vulnerability metrics
+    vulnerabilitiesFound = new Counter("Guardrail_vulnerabilities_found_total", "Total number of vulnerabilities found", ["severity", "source"]);
+    vulnerablePackages = new Gauge("Guardrail_vulnerable_packages", "Current number of vulnerable packages", ["project_id"]);
+    // Secret detection metrics
+    secretsDetected = new Counter("Guardrail_secrets_detected_total", "Total number of secrets detected", ["secret_type", "severity"]);
+    // Compliance metrics
+    complianceScore = new Gauge("Guardrail_compliance_score", "Current compliance score (0-100)", ["framework", "project_id"]);
+    complianceViolations = new Counter("Guardrail_compliance_violations_total", "Total number of compliance violations", ["framework", "severity"]);
+    // API metrics
+    apiRequestsTotal = new Counter("Guardrail_api_requests_total", "Total number of API requests", ["method", "endpoint", "status_code"]);
+    apiRequestDuration = new Histogram("Guardrail_api_request_duration_seconds", "Duration of API requests in seconds", ["method", "endpoint"]);
+    // Agent metrics
+    agentActionsTotal = new Counter("Guardrail_agent_actions_total", "Total number of agent actions", ["agent_id", "action_type", "status"]);
+    agentActionsBlocked = new Counter("Guardrail_agent_actions_blocked_total", "Total number of agent actions blocked", ["agent_id", "reason"]);
+    // Cache metrics
+    cacheHits = new Counter("Guardrail_cache_hits_total", "Total number of cache hits", ["cache_type"]);
+    cacheMisses = new Counter("Guardrail_cache_misses_total", "Total number of cache misses", ["cache_type"]);
+    // System metrics
+    activeConnections = new Gauge("Guardrail_active_connections", "Number of active WebSocket connections", []);
+    memoryUsageBytes = new Gauge("Guardrail_memory_usage_bytes", "Current memory usage in bytes", ["type"]);
+    /**
+     * Generate Prometheus-formatted output
+     */
+    generatePrometheusOutput() {
+        const lines = [];
+        const metrics = [
+            { metric: this.scansTotal, type: "counter" },
+            { metric: this.scanDuration, type: "histogram" },
+            { metric: this.injectionsDetected, type: "counter" },
+            { metric: this.injectionScanDuration, type: "histogram" },
+            { metric: this.vulnerabilitiesFound, type: "counter" },
+            { metric: this.vulnerablePackages, type: "gauge" },
+            { metric: this.secretsDetected, type: "counter" },
+            { metric: this.complianceScore, type: "gauge" },
+            { metric: this.complianceViolations, type: "counter" },
+            { metric: this.apiRequestsTotal, type: "counter" },
+            { metric: this.apiRequestDuration, type: "histogram" },
+            { metric: this.agentActionsTotal, type: "counter" },
+            { metric: this.agentActionsBlocked, type: "counter" },
+            { metric: this.cacheHits, type: "counter" },
+            { metric: this.cacheMisses, type: "counter" },
+            { metric: this.activeConnections, type: "gauge" },
+            { metric: this.memoryUsageBytes, type: "gauge" },
+        ];
+        for (const { metric, type } of metrics) {
+            lines.push(`# HELP ${metric.name} ${metric.help}`);
+            lines.push(`# TYPE ${metric.name} ${type}`);
+            const values = metric.collect();
+            for (const { value, labels } of values) {
+                const labelStr = Object.entries(labels)
+                    .map(([k, v]) => `${k}="${v}"`)
+                    .join(",");
+                if (labelStr) {
+                    lines.push(`${metric.name}{${labelStr}} ${value}`);
+                }
+                else {
+                    lines.push(`${metric.name} ${value}`);
+                }
+            }
+            lines.push("");
+        }
+        return lines.join("\n");
+    }
+    /**
+     * Update system metrics
+     */
+    updateSystemMetrics() {
+        const memUsage = process.memoryUsage();
+        this.memoryUsageBytes.set({ type: "heap_used" }, memUsage.heapUsed);
+        this.memoryUsageBytes.set({ type: "heap_total" }, memUsage.heapTotal);
+        this.memoryUsageBytes.set({ type: "rss" }, memUsage.rss);
+        this.memoryUsageBytes.set({ type: "external" }, memUsage.external);
+    }
+    /**
+     * Reset all metrics (for testing)
+     */
+    resetAll() {
+        this.scansTotal.reset();
+        // Add reset for other metrics as needed
+    }
+}
+// Export singleton registry
+exports.metrics = new MetricsRegistry();

package/dist/quota-ledger.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Quota Ledger - Server-Authoritative Usage Tracking
+ *
+ * Implements idempotent usage recording with request IDs to prevent double-counting.
+ * All quota checks are validated server-side before allowing operations.
+ *
+ * SECURITY: CLI cannot bypass quota checks by modifying local files.
+ * The server is the single source of truth for usage data.
+ */
+export type UsageActionType = 'scan' | 'scan_truth' | 'reality' | 'agent' | 'fix' | 'gate';
+export interface UsageEntry {
+    id: string;
+    action: UsageActionType;
+    count: number;
+    timestamp: string;
+    synced: boolean;
+    projectId?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface QuotaLimits {
+    scans: number;
+    reality: number;
+    agent: number;
+}
+export interface UsageSummary {
+    tier: string;
+    period: {
+        start: string;
+        end: string;
+    };
+    usage: {
+        scans: number;
+        reality: number;
+        agent: number;
+        fix: number;
+        gate: number;
+    };
+    limits: QuotaLimits;
+    remaining: {
+        scans: number;
+        reality: number;
+        agent: number;
+    };
+}
+export interface QuotaCheckResult {
+    allowed: boolean;
+    current: number;
+    limit: number;
+    remaining: number;
+    reason?: string;
+    source: 'server' | 'cache' | 'offline';
+    requestId: string;
+}
+export interface RecordResult {
+    success: boolean;
+    requestId: string;
+    newUsage: number;
+    remaining: number;
+    source: 'server' | 'queued';
+    error?: string;
+}
+export declare class QuotaLedger {
+    private configDir;
+    private ledgerFile;
+    private cacheFile;
+    private apiUrl;
+    private apiKey;
+    constructor();
+    /**
+     * Generate unique request ID for idempotency
+     */
+    generateRequestId(): string;
+    /**
+     * Check if action is allowed based on quota
+     * Always validates with server when possible
+     */
+    checkQuota(action: UsageActionType): Promise<QuotaCheckResult>;
+    /**
+     * Record usage with idempotency guarantee
+     * Uses request ID to prevent double-counting on retries
+     */
+    recordUsage(action: UsageActionType, count?: number, requestId?: string): Promise<RecordResult>;
+    /**
+     * Get usage summary for current billing period
+     */
+    getUsageSummary(): Promise<UsageSummary | null>;
+    /**
+     * Sync pending offline usage to server
+     */
+    syncPendingUsage(): Promise<{
+        synced: number;
+        failed: number;
+        errors: string[];
+    }>;
+    /**
+     * Get count of pending offline usage
+     */
+    getPendingCount(): Promise<number>;
+    private ensureDir;
+    private saveLedgerEntry;
+    private updateLedgerEntry;
+    private getUnsyncedEntries;
+    private isDuplicateRequest;
+    private getExistingResult;
+    private cacheQuotaResult;
+    private getCachedQuota;
+    private getLocalSummary;
+}
+export declare const quotaLedger: QuotaLedger;
+export declare const checkQuota: (action: UsageActionType) => Promise<QuotaCheckResult>;
+export declare const recordUsage: (action: UsageActionType, count?: number, requestId?: string) => Promise<RecordResult>;
+export declare const getUsageSummary: () => Promise<UsageSummary | null>;
+export declare const syncPendingUsage: () => Promise<{
+    synced: number;
+    failed: number;
+    errors: string[];
+}>;
+export declare const getPendingCount: () => Promise<number>;
+//# sourceMappingURL=quota-ledger.d.ts.map

package/dist/quota-ledger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"quota-ledger.d.ts","sourceRoot":"","sources":["../src/quota-ledger.ts"],"names":[],"mappings":"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"}