shroud-privacy 2.2.11 → 2.2.13

package/dist/profiler-analysis.js

@@ -1,230 +0,0 @@
-/**
- * Statistical analysis utilities for behavioural profiling.
- *
- * Welford's online algorithm for incremental mean/stddev,
- * Z-score computation, and multi-feature anomaly scoring.
- * All synchronous, zero dependencies.
- */
-import { AnomalyType, } from "./profiler-types.js";
-// ===================================================================
-// Welford's Online Algorithm
-// ===================================================================
-/** Create a fresh running stats accumulator. */
-export function emptyStats() {
-    return { mean: 0, m2: 0, n: 0, min: Infinity, max: -Infinity };
-}
-/**
- * Update running stats with a new observation.
- * Uses Welford's algorithm for numerically stable incremental mean/variance.
- */
-export function updateStats(stats, x) {
-    const n = stats.n + 1;
-    const delta = x - stats.mean;
-    const mean = stats.mean + delta / n;
-    const delta2 = x - mean;
-    const m2 = stats.m2 + delta * delta2;
-    return {
-        mean,
-        m2,
-        n,
-        min: Math.min(stats.min, x),
-        max: Math.max(stats.max, x),
-    };
-}
-/** Compute standard deviation from running stats. */
-export function stddev(stats) {
-    if (stats.n < 2)
-        return 0;
-    return Math.sqrt(stats.m2 / stats.n);
-}
-// ===================================================================
-// Z-Score and Anomaly Detection
-// ===================================================================
-/** Compute Z-score. Returns 0 if stddev is 0 and value equals mean. */
-export function zScore(observed, mean, sd) {
-    if (sd === 0)
-        return observed === mean ? 0 : Infinity;
-    return (observed - mean) / sd;
-}
-/** Features extracted from a FeatureVector that we track in the baseline. */
-const NUMERIC_FEATURES = [
-    {
-        name: "entityDensityPer1k",
-        extract: (fv) => fv.entityDensityPer1k,
-        anomalyType: AnomalyType.ENTITY_DENSITY_SPIKE,
-    },
-    {
-        name: "entityCategoryEntropy",
-        extract: (fv) => fv.entityCategoryEntropy,
-        anomalyType: AnomalyType.ENTITY_CATEGORY_SHIFT,
-    },
-    {
-        name: "toolCallCount",
-        extract: (fv) => fv.toolCallCount,
-        anomalyType: AnomalyType.TOOL_OUTSIDE_PROFILE,
-    },
-    {
-        name: "directiveVerbCount",
-        extract: (fv) => fv.directiveVerbCount,
-        anomalyType: AnomalyType.ENTITY_CATEGORY_SHIFT,
-    },
-    {
-        name: "commandToQuestionRatio",
-        extract: (fv) => isFinite(fv.commandToQuestionRatio) ? fv.commandToQuestionRatio : 10,
-        anomalyType: AnomalyType.ENTITY_CATEGORY_SHIFT,
-    },
-    {
-        name: "responseLength",
-        extract: (fv) => fv.responseLength,
-        anomalyType: AnomalyType.EXFILTRATION_PATTERN,
-    },
-    {
-        name: "entityEchoRate",
-        extract: (fv) => fv.entityEchoRate,
-        anomalyType: AnomalyType.EXFILTRATION_PATTERN,
-    },
-    {
-        name: "lexicalOverlapWithPrevious",
-        extract: (fv) => fv.lexicalOverlapWithPrevious,
-        anomalyType: AnomalyType.TOPIC_DISCONTINUITY,
-    },
-    {
-        name: "newVocabularyRate",
-        extract: (fv) => fv.newVocabularyRate,
-        anomalyType: AnomalyType.TOPIC_DISCONTINUITY,
-    },
-    {
-        name: "tokenEstimate",
-        extract: (fv) => fv.tokenEstimate,
-        anomalyType: AnomalyType.ENTITY_DENSITY_SPIKE,
-    },
-    {
-        name: "nonLatinRatio",
-        extract: (fv) => fv.nonLatinRatio,
-        anomalyType: AnomalyType.TOPIC_DISCONTINUITY,
-    },
-    {
-        name: "imagePayloadCount",
-        extract: (fv) => fv.imagePayloadCount,
-        anomalyType: AnomalyType.ENTITY_CATEGORY_SHIFT,
-    },
-    {
-        name: "imagePayloadBytes",
-        extract: (fv) => fv.imagePayloadBytes,
-        anomalyType: AnomalyType.ENTITY_CATEGORY_SHIFT,
-    },
-    {
-        name: "inputTokens",
-        extract: (fv) => fv.inputTokens,
-        anomalyType: AnomalyType.ENTITY_DENSITY_SPIKE,
-    },
-    {
-        name: "outputTokens",
-        extract: (fv) => fv.outputTokens,
-        anomalyType: AnomalyType.EXFILTRATION_PATTERN,
-    },
-    {
-        name: "cacheHitRatio",
-        extract: (fv) => fv.cacheHitRatio,
-        anomalyType: AnomalyType.TOPIC_DISCONTINUITY,
-    },
-    {
-        name: "cacheWriteTokens",
-        extract: (fv) => fv.cacheWriteTokens,
-        anomalyType: AnomalyType.ENTITY_CATEGORY_SHIFT,
-    },
-];
-/**
- * Detect anomalies by comparing a feature vector against the baseline.
- *
- * @param features - Current turn's feature vector
- * @param baseline - Accumulated baseline feature statistics
- * @param sigma - Z-score threshold (default 3.0)
- * @param knownTools - Set of tool names seen in baseline sessions
- * @param knownCategories - Set of entity categories seen in baseline sessions
- */
-export function detectAnomalies(features, baseline, sigma, knownTools, knownCategories) {
-    const alerts = [];
-    const ts = features.timestamp;
-    const turn = features.turnIndex;
-    // Z-score based anomalies for numeric features
-    for (const feat of NUMERIC_FEATURES) {
-        const stats = baseline[feat.name];
-        if (!stats || stats.n < 2)
-            continue; // Not enough data
-        const observed = feat.extract(features);
-        const sd = stddev(stats);
-        const z = zScore(observed, stats.mean, sd);
-        if (Math.abs(z) > sigma) {
-            const severity = Math.abs(z) > sigma * 1.5 ? "critical" : "warning";
-            alerts.push({
-                type: feat.anomalyType,
-                severity,
-                feature: feat.name,
-                observedValue: observed,
-                baselineMean: stats.mean,
-                baselineStddev: sd,
-                zScore: z,
-                turnIndex: turn,
-                timestamp: ts,
-                description: `${feat.name}: z=${z.toFixed(2)} (observed=${observed.toFixed(2)}, baseline=${stats.mean.toFixed(2)}±${sd.toFixed(2)})`,
-            });
-        }
-    }
-    // Tool outside profile — tool name never seen in baseline
-    if (knownTools.size > 0) {
-        for (const tool of features.toolNames) {
-            if (!knownTools.has(tool)) {
-                alerts.push({
-                    type: AnomalyType.TOOL_OUTSIDE_PROFILE,
-                    severity: "warning",
-                    feature: "toolName",
-                    observedValue: 1,
-                    baselineMean: 0,
-                    baselineStddev: 0,
-                    zScore: Infinity,
-                    turnIndex: turn,
-                    timestamp: ts,
-                    description: `Tool "${tool}" not in baseline tool set`,
-                });
-            }
-        }
-    }
-    // Credential emergence — credential-like categories appearing for first time
-    const credentialCategories = new Set(["api_key", "jwt", "network_credential", "certificate"]);
-    for (const [cat, count] of Object.entries(features.entityCategoryCounts)) {
-        if (credentialCategories.has(cat) && count > 0 && !knownCategories.has(cat)) {
-            alerts.push({
-                type: AnomalyType.CREDENTIAL_EMERGENCE,
-                severity: "critical",
-                feature: `category:${cat}`,
-                observedValue: count,
-                baselineMean: 0,
-                baselineStddev: 0,
-                zScore: Infinity,
-                turnIndex: turn,
-                timestamp: ts,
-                description: `Credential category "${cat}" appeared (count=${count}) with no baseline history`,
-            });
-        }
-    }
-    return alerts;
-}
-/**
- * Update the baseline with feature values from a completed turn.
- */
-export function updateBaseline(baseline, features) {
-    const updated = { ...baseline };
-    for (const feat of NUMERIC_FEATURES) {
-        const value = feat.extract(features);
-        if (!updated[feat.name]) {
-            updated[feat.name] = emptyStats();
-        }
-        updated[feat.name] = updateStats(updated[feat.name], value);
-    }
-    return updated;
-}
-/** Get the list of tracked numeric feature names. */
-export function getTrackedFeatureNames() {
-    return NUMERIC_FEATURES.map((f) => f.name);
-}

package/dist/profiler-store.d.ts

@@ -1,33 +0,0 @@
-/**
- * File-based persistence for behavioural profiling baselines.
- *
- * Stores per-agent-build baselines as JSON files.
- * Uses Welford's online algorithm — only running statistics are persisted,
- * not raw data. Zero runtime dependencies.
- */
-import { AgentBaseline, SessionProfile } from "./profiler-types.js";
-/**
- * File-based store for agent behavioural baselines.
- */
-export declare class BaselineStore {
-    private readonly _profileDir;
-    constructor(profileDir: string);
-    /** Load a baseline for the given agent build ID. Returns null if not found. */
-    load(agentBuildId: string): AgentBaseline | null;
-    /** Save a baseline to disk. */
-    save(agentBuildId: string, baseline: AgentBaseline): void;
-    /**
-     * Update the baseline with a completed session's feature data.
-     * Uses Welford's algorithm for incremental statistics.
-     */
-    updateFromSession(agentBuildId: string, session: SessionProfile): void;
-    /** Check if a baseline exists for the given build ID. */
-    exists(agentBuildId: string): boolean;
-    private _filePath;
-    private _computeMaturity;
-}
-/**
- * Compute agent build ID from system prompt, plugin list, and model.
- * Excludes dynamic files (MEMORY.md) to avoid constant invalidation.
- */
-export declare function computeAgentBuildId(systemPrompt: string, pluginList: string[], modelId: string): string;

package/dist/profiler-store.js

@@ -1,118 +0,0 @@
-/**
- * File-based persistence for behavioural profiling baselines.
- *
- * Stores per-agent-build baselines as JSON files.
- * Uses Welford's online algorithm — only running statistics are persisted,
- * not raw data. Zero runtime dependencies.
- */
-import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
-import { join } from "node:path";
-import { createHash } from "node:crypto";
-import { updateBaseline } from "./profiler-analysis.js";
-/**
- * File-based store for agent behavioural baselines.
- */
-export class BaselineStore {
-    _profileDir;
-    constructor(profileDir) {
-        // Expand ~ to actual home directory (Node.js doesn't do this automatically)
-        this._profileDir = profileDir.startsWith("~")
-            ? join(process.env.HOME || "/tmp", profileDir.slice(1))
-            : profileDir;
-    }
-    /** Load a baseline for the given agent build ID. Returns null if not found. */
-    load(agentBuildId) {
-        const filePath = this._filePath(agentBuildId);
-        if (!existsSync(filePath))
-            return null;
-        try {
-            const raw = readFileSync(filePath, "utf-8");
-            return JSON.parse(raw);
-        }
-        catch {
-            // Corrupt file — start fresh
-            return null;
-        }
-    }
-    /** Save a baseline to disk. */
-    save(agentBuildId, baseline) {
-        try {
-            mkdirSync(this._profileDir, { recursive: true });
-            const filePath = this._filePath(agentBuildId);
-            writeFileSync(filePath, JSON.stringify(baseline, null, 2), "utf-8");
-        }
-        catch {
-            // Best-effort — don't crash the plugin if profile dir is unwritable
-        }
-    }
-    /**
-     * Update the baseline with a completed session's feature data.
-     * Uses Welford's algorithm for incremental statistics.
-     */
-    updateFromSession(agentBuildId, session) {
-        let baseline = this.load(agentBuildId);
-        if (!baseline) {
-            baseline = {
-                agentBuildId,
-                sessionCount: 0,
-                maturity: "learning",
-                features: {},
-                toolProfile: [],
-                categoryProfile: [],
-                lastUpdated: Date.now(),
-            };
-        }
-        // Update running stats for each turn's features
-        for (const turn of session.turns) {
-            baseline.features = updateBaseline(baseline.features, turn);
-        }
-        // Update tool and category profiles
-        const toolSet = new Set(baseline.toolProfile);
-        const catSet = new Set(baseline.categoryProfile);
-        for (const turn of session.turns) {
-            for (const tool of turn.toolNames)
-                toolSet.add(tool);
-            for (const cat of Object.keys(turn.entityCategoryCounts)) {
-                if (turn.entityCategoryCounts[cat] > 0)
-                    catSet.add(cat);
-            }
-        }
-        baseline.toolProfile = [...toolSet];
-        baseline.categoryProfile = [...catSet];
-        baseline.sessionCount += 1;
-        baseline.maturity = this._computeMaturity(baseline.sessionCount);
-        baseline.lastUpdated = Date.now();
-        this.save(agentBuildId, baseline);
-    }
-    /** Check if a baseline exists for the given build ID. */
-    exists(agentBuildId) {
-        return existsSync(this._filePath(agentBuildId));
-    }
-    _filePath(agentBuildId) {
-        // Sanitize build ID for filesystem safety
-        const safe = agentBuildId.replace(/[^a-zA-Z0-9_-]/g, "");
-        return join(this._profileDir, `${safe}.json`);
-    }
-    _computeMaturity(sessionCount) {
-        if (sessionCount >= 50)
-            return "mature";
-        if (sessionCount >= 5)
-            return "reliable";
-        return "learning";
-    }
-}
-/**
- * Compute agent build ID from system prompt, plugin list, and model.
- * Excludes dynamic files (MEMORY.md) to avoid constant invalidation.
- */
-export function computeAgentBuildId(systemPrompt, pluginList, modelId) {
-    const components = [
-        systemPrompt,
-        pluginList.sort().join(","),
-        modelId,
-    ];
-    return createHash("sha256")
-        .update(components.join("\n"))
-        .digest("hex")
-        .slice(0, 16);
-}

package/dist/profiler-types.d.ts

@@ -1,128 +0,0 @@
-/**
- * Types for the behavioural profiling system (Track 3).
- *
- * Per-turn feature extraction, per-session aggregation,
- * cross-session baseline accumulation, and anomaly detection.
- */
-/** Per-turn feature vector — all computable sync, zero-dep. */
-export interface FeatureVector {
-    /** Entity category → count for this turn. */
-    entityCategoryCounts: Record<string, number>;
-    /** Entities per 1,000 tokens. */
-    entityDensityPer1k: number;
-    /** Shannon entropy of entity category distribution. */
-    entityCategoryEntropy: number;
-    /** Number of tool calls this turn. */
-    toolCallCount: number;
-    /** Ordered list of tool names called this turn. */
-    toolNames: string[];
-    /** Count of imperative/directive verbs in the prompt. */
-    directiveVerbCount: number;
-    /** Count of questions (sentences ending in ?). */
-    questionCount: number;
-    /** Ratio of directives to questions (Infinity if questionCount=0). */
-    commandToQuestionRatio: number;
-    /** Response text length in characters. */
-    responseLength: number;
-    /** Fraction of request entities that appear in the response. */
-    entityEchoRate: number;
-    /** Jaccard similarity of word bigrams between this and previous turn (0-1). */
-    lexicalOverlapWithPrevious: number;
-    /** Fraction of words not seen in any previous turn this session. */
-    newVocabularyRate: number;
-    /** Turn index (0-based). */
-    turnIndex: number;
-    /** Timestamp (ms since epoch). */
-    timestamp: number;
-    /** Estimated token count (chars / 4). */
-    tokenEstimate: number;
-    /** Detected script/language of the input (e.g. "latin", "cjk", "cyrillic", "arabic"). */
-    detectedScript: string;
-    /** Fraction of non-Latin characters in the input (0-1). */
-    nonLatinRatio: number;
-    /** Number of image payloads in this turn's API request. */
-    imagePayloadCount: number;
-    /** Total size of image payloads in bytes (base64 decoded). */
-    imagePayloadBytes: number;
-    /** Input tokens sent to the LLM. */
-    inputTokens: number;
-    /** Output tokens generated by the LLM. */
-    outputTokens: number;
-    /** Tokens read from cache (high = stable context, drop = new content injected). */
-    cacheReadTokens: number;
-    /** Tokens written to cache (spike = large new context entering). */
-    cacheWriteTokens: number;
-    /** Cache hit ratio: cacheRead / inputTokens (0-1). */
-    cacheHitRatio: number;
-}
-/** Aggregate statistics for a session. */
-export interface SessionAggregates {
-    /** Top 3 entity categories by frequency. */
-    dominantCategories: string[];
-    /** SHA256 of sorted unique tool names. */
-    toolSequenceFingerprint: string;
-    /** Mean entity density across turns. */
-    averageEntityDensity: number;
-    /** Mean directive verb count across turns. */
-    averageDirectiveVerbCount: number;
-    /** Mean response length across turns. */
-    averageResponseLength: number;
-    /** Mean lexical overlap across turns. */
-    averageLexicalOverlap: number;
-    /** Total turn count. */
-    turnCount: number;
-}
-/** A session's full profile. */
-export interface SessionProfile {
-    sessionId: string;
-    agentBuildId: string;
-    startedAt: number;
-    turns: FeatureVector[];
-    aggregates: SessionAggregates;
-}
-/** Running statistics for a single feature (Welford's algorithm). */
-export interface RunningStats {
-    mean: number;
-    m2: number;
-    n: number;
-    min: number;
-    max: number;
-}
-/** Baseline for a feature set derived from multiple sessions. */
-export interface BaselineFeatureStats {
-    [featureName: string]: RunningStats;
-}
-/** Baseline maturity level. */
-export type BaselineMaturity = "learning" | "reliable" | "mature";
-/** Agent baseline — cross-session profile keyed by build ID. */
-export interface AgentBaseline {
-    agentBuildId: string;
-    sessionCount: number;
-    maturity: BaselineMaturity;
-    features: BaselineFeatureStats;
-    toolProfile: string[];
-    categoryProfile: string[];
-    lastUpdated: number;
-}
-/** Named anomaly types modelled on IDS alert categories. */
-export declare enum AnomalyType {
-    ENTITY_CATEGORY_SHIFT = "entity_category_shift",
-    ENTITY_DENSITY_SPIKE = "entity_density_spike",
-    TOOL_OUTSIDE_PROFILE = "tool_outside_profile",
-    TOPIC_DISCONTINUITY = "topic_discontinuity",
-    CREDENTIAL_EMERGENCE = "credential_emergence",
-    EXFILTRATION_PATTERN = "exfiltration_pattern"
-}
-/** An anomaly alert emitted when profiler detects deviation. */
-export interface AnomalyAlert {
-    type: AnomalyType;
-    severity: "info" | "warning" | "critical";
-    feature: string;
-    observedValue: number;
-    baselineMean: number;
-    baselineStddev: number;
-    zScore: number;
-    turnIndex: number;
-    timestamp: number;
-    description: string;
-}

package/dist/profiler-types.js

@@ -1,16 +0,0 @@
-/**
- * Types for the behavioural profiling system (Track 3).
- *
- * Per-turn feature extraction, per-session aggregation,
- * cross-session baseline accumulation, and anomaly detection.
- */
-/** Named anomaly types modelled on IDS alert categories. */
-export var AnomalyType;
-(function (AnomalyType) {
-    AnomalyType["ENTITY_CATEGORY_SHIFT"] = "entity_category_shift";
-    AnomalyType["ENTITY_DENSITY_SPIKE"] = "entity_density_spike";
-    AnomalyType["TOOL_OUTSIDE_PROFILE"] = "tool_outside_profile";
-    AnomalyType["TOPIC_DISCONTINUITY"] = "topic_discontinuity";
-    AnomalyType["CREDENTIAL_EMERGENCE"] = "credential_emergence";
-    AnomalyType["EXFILTRATION_PATTERN"] = "exfiltration_pattern";
-})(AnomalyType || (AnomalyType = {}));

package/dist/profiler.d.ts

@@ -1,81 +0,0 @@
-/**
- * Behavioural profiler for LLM agent sessions (Track 3).
- *
- * Extracts per-turn feature vectors from request/response text,
- * maintains session aggregates, and detects anomalies against
- * cross-session baselines. All feature extraction is synchronous
- * and zero-dependency.
- */
-import { AnomalyAlert, FeatureVector, SessionProfile } from "./profiler-types.js";
-import { BaselineStore } from "./profiler-store.js";
-/** Configuration for the profiler. */
-export interface ProfilerConfig {
-    mode: "learning" | "active" | "strict";
-    sigma: number;
-    minBaseline: number;
-    profileDir: string;
-}
-/** Tool call info passed from hooks layer. */
-export interface ToolCallInfo {
-    name: string;
-    arguments?: Record<string, unknown>;
-}
-/**
- * Behavioural profiler. One instance per session.
- */
-export declare class BehaviouralProfiler {
-    private _config;
-    private _store;
-    private _sessionId;
-    private _agentBuildId;
-    private _turns;
-    private _alerts;
-    private _previousTurnBigrams;
-    private _allSessionWords;
-    private _startedAt;
-    private _pendingRequest;
-    constructor(config: ProfilerConfig, store: BaselineStore);
-    /** Set the agent build ID (from system prompt hash). */
-    setAgentBuildId(buildId: string): void;
-    /**
-     * Extract features from the outbound request text.
-     * Called after obfuscation, before sending to LLM.
-     */
-    extractRequestFeatures(text: string, entityCategoryCounts: Record<string, number>, toolCalls?: ToolCallInfo[], imagePayloads?: {
-        count: number;
-        totalBytes: number;
-    }): void;
-    /**
-     * Complete the feature vector with response-side features.
-     * Called after deobfuscation of the LLM response.
-     */
-    extractResponseFeatures(responseText: string, requestEntities: string[], cacheUsage?: {
-        inputTokens: number;
-        outputTokens: number;
-        cacheReadTokens: number;
-        cacheWriteTokens: number;
-    }): FeatureVector | null;
-    /**
-     * Analyze a completed turn against the baseline.
-     * Returns anomaly alerts (empty if in learning mode or insufficient baseline).
-     */
-    analyzeTurn(features: FeatureVector): AnomalyAlert[];
-    /**
-     * Finalize the session: compute aggregates, update baseline store.
-     */
-    finalizeSession(): SessionProfile;
-    /** Get all anomaly alerts from this session. */
-    getAlerts(): readonly AnomalyAlert[];
-    /** Get LLM cache usage summary for the current session. */
-    getCacheStats(): {
-        totalInput: number;
-        totalOutput: number;
-        totalCacheRead: number;
-        totalCacheWrite: number;
-        hitRatio: number;
-        turns: number;
-    };
-    /** Get current session profile (without finalizing). */
-    getSessionProfile(): SessionProfile;
-    private _computeAggregates;
-}