@mnemopay/sdk 0.9.3 → 1.0.0

package/dist/anomaly.d.ts

@@ -0,0 +1,242 @@
+/**
+ * Streaming Anomaly Detection — Real-Time Agent Behavior Monitoring
+ *
+ * Two complementary systems:
+ *
+ * 1. EWMA (Exponentially Weighted Moving Average) Detector
+ *    - Tracks running mean and variance of any metric stream
+ *    - Alerts when value exceeds k standard deviations from moving average
+ *    - Formula: mu_t = alpha * x_t + (1 - alpha) * mu_{t-1}
+ *    - O(1) per update, no windowing needed, no buffer overflow
+ *
+ * 2. Behavioral Fingerprint Monitor
+ *    - Tracks multi-dimensional behavioral profile of each agent
+ *    - Detects sudden behavioral shifts (hijacked agent, credential theft)
+ *    - Uses Mahalanobis distance for multivariate anomaly scoring
+ *    - Gartner 2026: behavioral fingerprinting reduces impersonation 70%
+ *
+ * 3. Canary Transaction System
+ *    - Plants honeypot transactions that should never be accessed
+ *    - If an agent touches a canary, it's compromised
+ *    - Inspired by Snare (GitHub) canary credential framework
+ *
+ * References:
+ *   - Roberts, S.W. (1959). "Control Chart Tests Based on EWMA"
+ *   - Lucas & Saccucci (1990). "EWMA Control Chart Properties"
+ *   - Mahalanobis (1936). "On the Generalized Distance in Statistics"
+ *   - MnemoPay Master Strategy, Part 2.1 — EWMA + behavioral fingerprinting
+ */
+export interface EWMAState {
+    /** Running mean */
+    mean: number;
+    /** Running variance */
+    variance: number;
+    /** Running standard deviation */
+    stdDev: number;
+    /** Number of observations */
+    count: number;
+    /** Last observed value */
+    lastValue: number;
+    /** Whether the detector has enough data to be reliable */
+    warmedUp: boolean;
+}
+export interface EWMAAlert {
+    /** Whether this observation is anomalous */
+    anomaly: boolean;
+    /** Current value */
+    value: number;
+    /** Current mean */
+    mean: number;
+    /** Current std dev */
+    stdDev: number;
+    /** Z-score: how many std devs from mean */
+    zScore: number;
+    /** Alert severity */
+    severity: "none" | "warning" | "critical";
+    /** Timestamp */
+    timestamp: number;
+}
+export interface BehaviorFingerprint {
+    /** Agent ID */
+    agentId: string;
+    /** Per-feature EWMA trackers */
+    features: Record<string, EWMAState>;
+    /** Number of observations used to build fingerprint */
+    observations: number;
+    /** Whether the fingerprint is established (>= warmupPeriod observations) */
+    established: boolean;
+    /** Last observation timestamp */
+    lastObserved: number;
+}
+export interface HijackDetection {
+    /** Whether hijack is suspected */
+    suspected: boolean;
+    /** Overall anomaly score (0-1, higher = more anomalous) */
+    anomalyScore: number;
+    /** Number of features that are anomalous */
+    anomalousFeatures: number;
+    /** Total features tracked */
+    totalFeatures: number;
+    /** Per-feature anomaly details */
+    details: Record<string, {
+        zScore: number;
+        anomalous: boolean;
+    }>;
+    /** Severity assessment */
+    severity: "none" | "low" | "medium" | "high" | "critical";
+    /** Recommendation */
+    recommendation: string;
+}
+export interface CanaryTransaction {
+    /** Canary ID */
+    id: string;
+    /** Fake amount (should never be accessed) */
+    amount: number;
+    /** Canary type */
+    type: "transaction" | "memory" | "credential";
+    /** When the canary was planted */
+    plantedAt: number;
+    /** Whether the canary has been triggered */
+    triggered: boolean;
+    /** When triggered (if applicable) */
+    triggeredAt?: number;
+    /** What agent triggered it */
+    triggeredBy?: string;
+}
+export interface CanaryAlert {
+    /** The triggered canary */
+    canary: CanaryTransaction;
+    /** Agent that triggered it */
+    agentId: string;
+    /** Severity: always critical (canary trigger = compromise) */
+    severity: "critical";
+    /** Message */
+    message: string;
+    /** Timestamp */
+    timestamp: number;
+}
+export interface AnomalyConfig {
+    /** EWMA smoothing factor (0-1). Higher = more reactive. Default 0.15 */
+    alpha: number;
+    /** Z-score threshold for warning. Default 2.5 */
+    warningThreshold: number;
+    /** Z-score threshold for critical. Default 3.5 */
+    criticalThreshold: number;
+    /** Minimum observations before alerting. Default 10 */
+    warmupPeriod: number;
+    /** Features to track for behavioral fingerprinting */
+    trackedFeatures: string[];
+    /** Fraction of anomalous features to flag hijack. Default 0.4 */
+    hijackFeatureThreshold: number;
+    /** Max canaries per agent. Default 5 */
+    maxCanaries: number;
+}
+export declare const DEFAULT_ANOMALY_CONFIG: AnomalyConfig;
+export declare class EWMADetector {
+    private mean;
+    private variance;
+    private count;
+    private lastValue;
+    private readonly alpha;
+    private readonly warningK;
+    private readonly criticalK;
+    private readonly warmup;
+    constructor(alpha?: number, warningK?: number, criticalK?: number, warmup?: number);
+    /**
+     * Update the detector with a new observation.
+     * Returns anomaly assessment.
+     *
+     * EWMA formulas:
+     *   mu_t = alpha * x_t + (1 - alpha) * mu_{t-1}
+     *   sigma_t^2 = alpha * (x_t - mu_t)^2 + (1 - alpha) * sigma_{t-1}^2
+     *   Alert when: |x_t - mu_t| > k * sigma_t
+     */
+    update(value: number): EWMAAlert;
+    private _makeAlert;
+    /** Get current state */
+    getState(): EWMAState;
+    /** Reset the detector */
+    reset(): void;
+    /** Serialize for persistence */
+    serialize(): {
+        mean: number;
+        variance: number;
+        count: number;
+        lastValue: number;
+    };
+    /** Restore from serialized state */
+    restore(state: {
+        mean: number;
+        variance: number;
+        count: number;
+        lastValue: number;
+    }): void;
+}
+export declare class BehaviorMonitor {
+    private fingerprints;
+    private observationCounts;
+    private lastObserved;
+    readonly config: AnomalyConfig;
+    /** Max agents to track before evicting oldest inactive. Prevents unbounded memory growth. */
+    static readonly MAX_AGENTS = 10000;
+    constructor(config?: Partial<AnomalyConfig>);
+    /**
+     * Observe agent behavior. Updates the behavioral fingerprint.
+     * Returns hijack detection result.
+     */
+    observe(agentId: string, features: Record<string, number>): HijackDetection;
+    /**
+     * Get the behavioral fingerprint for an agent.
+     */
+    getFingerprint(agentId: string): BehaviorFingerprint | null;
+    /**
+     * Remove an agent's fingerprint (on agent deletion).
+     */
+    removeAgent(agentId: string): boolean;
+    /** Number of agents being monitored */
+    get agentCount(): number;
+    /** Serialize for persistence */
+    serialize(): Record<string, {
+        features: Record<string, ReturnType<EWMADetector["serialize"]>>;
+        count: number;
+        lastObserved: number;
+    }>;
+    /** Deserialize with validation */
+    static deserialize(data: Record<string, any>, config?: Partial<AnomalyConfig>): BehaviorMonitor;
+}
+export declare class CanarySystem {
+    private canaries;
+    private alerts;
+    private readonly maxCanaries;
+    static readonly MAX_ALERTS = 100;
+    constructor(maxCanaries?: number);
+    /**
+     * Plant a canary transaction.
+     * Returns the canary ID. Store this — never expose to the agent.
+     */
+    plant(type?: CanaryTransaction["type"]): CanaryTransaction;
+    /**
+     * Check if an ID matches a canary. If yes, the agent is compromised.
+     * This should be called on every transaction/memory access.
+     */
+    check(id: string, agentId: string): CanaryAlert | null;
+    /** Check if any ID in a list matches a canary */
+    checkBatch(ids: string[], agentId: string): CanaryAlert[];
+    /** Get all alerts */
+    getAlerts(): CanaryAlert[];
+    /** Get all active (untriggered) canaries */
+    getActiveCanaries(): CanaryTransaction[];
+    /** Check if a specific canary ID exists (for internal use only) */
+    isCanary(id: string): boolean;
+    /** Serialize for persistence */
+    serialize(): {
+        canaries: CanaryTransaction[];
+        alerts: CanaryAlert[];
+    };
+    /** Deserialize with validation */
+    static deserialize(data: {
+        canaries?: CanaryTransaction[];
+        alerts?: CanaryAlert[];
+    }, maxCanaries?: number): CanarySystem;
+}
+//# sourceMappingURL=anomaly.d.ts.map

package/dist/anomaly.d.ts.map

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