@floatingsidewal/bulkhead-core 0.3.0

package/dist/index.d.mts

@@ -0,0 +1,265 @@
+import { G as GuardMode, E as EngineConfig, a as Guard, b as GuardResult, C as CascadeConfig, c as CascadeClassifier, d as GuardConfig, D as Detection, e as DetectionSource, f as Disposition, P as PiiPattern } from './index-BNiM_sPB.mjs';
+export { B as BertLayerConfig, g as Confidence, L as LlmLayerConfig, h as LlmProvider, S as SecretPattern, T as Tactic, i as TacticName, j as TacticResult } from './index-BNiM_sPB.mjs';
+
+/** Severity level for risk rating */
+type RiskLevel = "critical" | "high" | "medium" | "low" | "none";
+/** Per-guard policy configuration */
+interface GuardPolicyConfig {
+    enabled: boolean;
+    threshold: number;
+    mode: GuardMode;
+    /** For PiiGuard: which entity types to detect */
+    entityTypes?: string[];
+    /** For SecretGuard: which secret types to detect */
+    secretTypes?: string[];
+}
+/** Score thresholds that map aggregate scores to risk levels */
+interface RiskThresholds {
+    /** Score >= this is critical */
+    critical: number;
+    /** Score >= this is high */
+    high: number;
+    /** Score >= this is medium */
+    medium: number;
+    /** Score >= this is low; below is none */
+    low: number;
+}
+/** A complete policy definition */
+interface PolicyDefinition {
+    name: string;
+    description: string;
+    guards: {
+        pii?: Partial<GuardPolicyConfig>;
+        secret?: Partial<GuardPolicyConfig>;
+        injection?: Partial<GuardPolicyConfig>;
+        leakage?: Partial<GuardPolicyConfig>;
+    };
+    riskThresholds: RiskThresholds;
+    /** How to handle test/synthetic data detection */
+    testDataDetection?: "flag" | "strip" | "ignore";
+}
+/** Risk assessment returned alongside scan results */
+interface RiskAssessment {
+    /** Overall risk level */
+    level: RiskLevel;
+    /** Aggregate score 0-1 */
+    score: number;
+    /** Per-guard risk breakdown */
+    guards: Record<string, {
+        level: RiskLevel;
+        score: number;
+        detectionCount: number;
+    }>;
+    /** Classified issues grouped by category */
+    issues: ClassifiedIssue[];
+    /** Synthetic/eval data flags */
+    testDataFlags: TestDataFlag[];
+}
+/** A single classified issue derived from detections */
+interface ClassifiedIssue {
+    category: "pii" | "secret" | "injection" | "leakage" | "testdata";
+    entityType: string;
+    severity: RiskLevel;
+    count: number;
+    /** Whether this issue overlaps with detected test data */
+    isTestData: boolean;
+    /** Representative sample (first detection text, truncated) */
+    sample?: string;
+}
+/** A flagged piece of synthetic/test data */
+interface TestDataFlag {
+    /** JSON path if available (e.g., "issueContext.SubscriptionID") */
+    field?: string;
+    /** The flagged value */
+    value: string;
+    /** Why it was flagged */
+    reason: string;
+    start: number;
+    end: number;
+}
+
+/** Orchestrates multiple guards and aggregates results */
+declare class GuardrailsEngine {
+    private guards;
+    private config;
+    private cascade;
+    constructor(config?: Partial<EngineConfig>);
+    /** Register a guard with the engine */
+    addGuard(guard: Guard): this;
+    /** Register multiple guards */
+    addGuards(guards: Guard[]): this;
+    /** Get configuration for a specific guard */
+    private getGuardConfig;
+    /** Run all enabled guards against the input text */
+    analyze(text: string): Promise<GuardResult[]>;
+    /** Run all guards and return a single pass/fail with all detections */
+    scan(text: string): Promise<{
+        passed: boolean;
+        results: GuardResult[];
+        redactedText?: string;
+    }>;
+    /** Get list of registered guard names */
+    get guardNames(): string[];
+    /** Whether the cascade is ready (BERT model loaded if enabled) */
+    get cascadeReady(): boolean;
+    /** Initialize or update the cascade classifier */
+    initCascade(config?: Partial<CascadeConfig>): CascadeClassifier;
+    /** Run the full cascade (regex + BERT + optional LLM) */
+    deepScan(text: string): Promise<GuardResult[]>;
+    /** Run regex + BERT only (no LLM) */
+    modelScan(text: string): Promise<GuardResult[]>;
+    /** Update engine configuration */
+    updateConfig(config: Partial<EngineConfig>): void;
+    /** Run all guards and return risk assessment alongside results */
+    policyScan(text: string, policy: PolicyDefinition): Promise<{
+        passed: boolean;
+        risk: RiskAssessment;
+        results: GuardResult[];
+        redactedText?: string;
+    }>;
+    /** Clean up resources (terminate BERT worker, etc.) */
+    dispose(): Promise<void>;
+}
+
+/** Base class for guards that detect patterns in text */
+declare abstract class BaseGuard implements Guard {
+    abstract readonly name: string;
+    protected mergeConfig(config?: Partial<GuardConfig>): GuardConfig;
+    abstract analyze(text: string, config?: Partial<GuardConfig>): Promise<GuardResult>;
+    /** Build a GuardResult from detections */
+    protected buildResult(text: string, detections: Detection[], mode: GuardMode): GuardResult;
+    /** Extract surrounding context for a detection */
+    protected extractContext(text: string, start: number, end: number): string;
+    /** Create a detection with provenance fields pre-filled for regex source */
+    protected makeDetection(text: string, partial: Omit<Detection, "source" | "context" | "disposition">, source?: DetectionSource, disposition?: Disposition): Detection;
+    /** Replace detected text with [REDACTED-TYPE] markers */
+    protected applyRedactions(text: string, detections: Detection[]): string;
+}
+
+/**
+ * PII Guard — detects personally identifiable information using regex patterns.
+ * Pattern library ported from Microsoft Presidio. See ATTRIBUTION.md.
+ */
+
+interface PiiGuardOptions {
+    /** Specific entity types to detect. If empty, all are enabled. */
+    entityTypes?: string[];
+    /** Additional custom patterns */
+    customPatterns?: PiiPattern[];
+}
+declare class PiiGuard extends BaseGuard {
+    readonly name = "pii";
+    private patterns;
+    constructor(options?: PiiGuardOptions);
+    analyze(text: string, config?: Partial<GuardConfig>): Promise<GuardResult>;
+    private detectAll;
+    private deduplicateDetections;
+}
+
+/**
+ * Secret Guard — detects API keys, tokens, credentials, and connection strings.
+ * Pattern approach inspired by HAI-Guardrails. See ATTRIBUTION.md.
+ */
+
+interface SecretGuardOptions {
+    /** Specific secret types to detect. If empty/undefined, all are enabled. */
+    secretTypes?: string[];
+}
+declare class SecretGuard extends BaseGuard {
+    readonly name = "secret";
+    private patterns;
+    constructor(options?: SecretGuardOptions);
+    analyze(text: string, config?: Partial<GuardConfig>): Promise<GuardResult>;
+}
+
+/**
+ * Injection Guard — detects prompt injection attempts.
+ * Detection approach inspired by HAI-Guardrails. See ATTRIBUTION.md.
+ */
+
+declare class InjectionGuard extends BaseGuard {
+    readonly name = "injection";
+    analyze(text: string, config?: Partial<GuardConfig>): Promise<GuardResult>;
+    private heuristicScore;
+}
+
+/**
+ * Leakage Guard — detects system prompt extraction attempts.
+ * Detection approach inspired by HAI-Guardrails. See ATTRIBUTION.md.
+ */
+
+declare class LeakageGuard extends BaseGuard {
+    readonly name = "leakage";
+    analyze(text: string, config?: Partial<GuardConfig>): Promise<GuardResult>;
+}
+
+/**
+ * Test Data Guard — detects synthetic, eval, and placeholder data.
+ * This guard identifies data that was clearly fabricated for testing rather than
+ * real sensitive content. Detections are informational, not blocking.
+ */
+
+declare class TestDataGuard extends BaseGuard {
+    readonly name = "testdata";
+    analyze(text: string, config?: Partial<GuardConfig>): Promise<GuardResult>;
+    /** Build a result that always passes — test data is informational, not blocking */
+    private buildInformationalResult;
+    private deduplicateDetections;
+}
+
+/** All built-in policies indexed by name */
+declare const BUILTIN_POLICIES: Record<string, PolicyDefinition>;
+/** Retrieve a built-in policy by name */
+declare function getPolicy(name: string): PolicyDefinition;
+
+/**
+ * Compose policies by merging a base with overlays.
+ * "Stricter wins": lower thresholds, entity-type intersection, block over redact.
+ */
+declare function resolvePolicy(base: string | PolicyDefinition, ...overlays: (string | PolicyDefinition)[]): PolicyDefinition;
+/** Translate a resolved policy into guard constructor options and per-guard configs */
+declare function policyToEngineConfig(policy: PolicyDefinition): {
+    piiOptions: PiiGuardOptions;
+    secretOptions: SecretGuardOptions;
+    guardConfigs: Record<string, Partial<GuardConfig>>;
+};
+
+/**
+ * Compute a risk assessment from guard results and a policy definition.
+ * Pure function — no side effects, no engine mutation.
+ */
+declare function assessRisk(results: GuardResult[], policy: PolicyDefinition): RiskAssessment;
+
+interface BulkheadConfig {
+    enabled: boolean;
+    debounceMs: number;
+    guards: {
+        pii: {
+            enabled: boolean;
+        };
+        secret: {
+            enabled: boolean;
+        };
+        injection: {
+            enabled: boolean;
+        };
+        contentSafety: {
+            enabled: boolean;
+        };
+    };
+    cascade: {
+        escalationThreshold: number;
+        contextSentences: number;
+        modelEnabled: boolean;
+        modelId: string;
+    };
+    /** Named policy or custom PolicyDefinition. Overrides guard-level config. */
+    policy?: string | PolicyDefinition;
+    /** Additional policy overlays for composition */
+    policyOverlays?: (string | PolicyDefinition)[];
+}
+declare const DEFAULT_CONFIG: BulkheadConfig;
+/** Create a configured engine from a BulkheadConfig */
+declare function createEngine(config?: BulkheadConfig): GuardrailsEngine;
+
+export { BUILTIN_POLICIES, BaseGuard, type BulkheadConfig, CascadeConfig, type ClassifiedIssue, DEFAULT_CONFIG, Detection, DetectionSource, Disposition, EngineConfig, Guard, GuardConfig, GuardMode, type GuardPolicyConfig, GuardResult, GuardrailsEngine, InjectionGuard, LeakageGuard, PiiGuard, type PiiGuardOptions, PiiPattern, type PolicyDefinition, type RiskAssessment, type RiskLevel, type RiskThresholds, SecretGuard, type SecretGuardOptions, type TestDataFlag, TestDataGuard, assessRisk, createEngine, getPolicy, policyToEngineConfig, resolvePolicy };

package/dist/index.d.ts

@@ -0,0 +1,265 @@
+import { G as GuardMode, E as EngineConfig, a as Guard, b as GuardResult, C as CascadeConfig, c as CascadeClassifier, d as GuardConfig, D as Detection, e as DetectionSource, f as Disposition, P as PiiPattern } from './index-BNiM_sPB.js';
+export { B as BertLayerConfig, g as Confidence, L as LlmLayerConfig, h as LlmProvider, S as SecretPattern, T as Tactic, i as TacticName, j as TacticResult } from './index-BNiM_sPB.js';
+
+/** Severity level for risk rating */
+type RiskLevel = "critical" | "high" | "medium" | "low" | "none";
+/** Per-guard policy configuration */
+interface GuardPolicyConfig {
+    enabled: boolean;
+    threshold: number;
+    mode: GuardMode;
+    /** For PiiGuard: which entity types to detect */
+    entityTypes?: string[];
+    /** For SecretGuard: which secret types to detect */
+    secretTypes?: string[];
+}
+/** Score thresholds that map aggregate scores to risk levels */
+interface RiskThresholds {
+    /** Score >= this is critical */
+    critical: number;
+    /** Score >= this is high */
+    high: number;
+    /** Score >= this is medium */
+    medium: number;
+    /** Score >= this is low; below is none */
+    low: number;
+}
+/** A complete policy definition */
+interface PolicyDefinition {
+    name: string;
+    description: string;
+    guards: {
+        pii?: Partial<GuardPolicyConfig>;
+        secret?: Partial<GuardPolicyConfig>;
+        injection?: Partial<GuardPolicyConfig>;
+        leakage?: Partial<GuardPolicyConfig>;
+    };
+    riskThresholds: RiskThresholds;
+    /** How to handle test/synthetic data detection */
+    testDataDetection?: "flag" | "strip" | "ignore";
+}
+/** Risk assessment returned alongside scan results */
+interface RiskAssessment {
+    /** Overall risk level */
+    level: RiskLevel;
+    /** Aggregate score 0-1 */
+    score: number;
+    /** Per-guard risk breakdown */
+    guards: Record<string, {
+        level: RiskLevel;
+        score: number;
+        detectionCount: number;
+    }>;
+    /** Classified issues grouped by category */
+    issues: ClassifiedIssue[];
+    /** Synthetic/eval data flags */
+    testDataFlags: TestDataFlag[];
+}
+/** A single classified issue derived from detections */
+interface ClassifiedIssue {
+    category: "pii" | "secret" | "injection" | "leakage" | "testdata";
+    entityType: string;
+    severity: RiskLevel;
+    count: number;
+    /** Whether this issue overlaps with detected test data */
+    isTestData: boolean;
+    /** Representative sample (first detection text, truncated) */
+    sample?: string;
+}
+/** A flagged piece of synthetic/test data */
+interface TestDataFlag {
+    /** JSON path if available (e.g., "issueContext.SubscriptionID") */
+    field?: string;
+    /** The flagged value */
+    value: string;
+    /** Why it was flagged */
+    reason: string;
+    start: number;
+    end: number;
+}
+
+/** Orchestrates multiple guards and aggregates results */
+declare class GuardrailsEngine {
+    private guards;
+    private config;
+    private cascade;
+    constructor(config?: Partial<EngineConfig>);
+    /** Register a guard with the engine */
+    addGuard(guard: Guard): this;
+    /** Register multiple guards */
+    addGuards(guards: Guard[]): this;
+    /** Get configuration for a specific guard */
+    private getGuardConfig;
+    /** Run all enabled guards against the input text */
+    analyze(text: string): Promise<GuardResult[]>;
+    /** Run all guards and return a single pass/fail with all detections */
+    scan(text: string): Promise<{
+        passed: boolean;
+        results: GuardResult[];
+        redactedText?: string;
+    }>;
+    /** Get list of registered guard names */
+    get guardNames(): string[];
+    /** Whether the cascade is ready (BERT model loaded if enabled) */
+    get cascadeReady(): boolean;
+    /** Initialize or update the cascade classifier */
+    initCascade(config?: Partial<CascadeConfig>): CascadeClassifier;
+    /** Run the full cascade (regex + BERT + optional LLM) */
+    deepScan(text: string): Promise<GuardResult[]>;
+    /** Run regex + BERT only (no LLM) */
+    modelScan(text: string): Promise<GuardResult[]>;
+    /** Update engine configuration */
+    updateConfig(config: Partial<EngineConfig>): void;
+    /** Run all guards and return risk assessment alongside results */
+    policyScan(text: string, policy: PolicyDefinition): Promise<{
+        passed: boolean;
+        risk: RiskAssessment;
+        results: GuardResult[];
+        redactedText?: string;
+    }>;
+    /** Clean up resources (terminate BERT worker, etc.) */
+    dispose(): Promise<void>;
+}
+
+/** Base class for guards that detect patterns in text */
+declare abstract class BaseGuard implements Guard {
+    abstract readonly name: string;
+    protected mergeConfig(config?: Partial<GuardConfig>): GuardConfig;
+    abstract analyze(text: string, config?: Partial<GuardConfig>): Promise<GuardResult>;
+    /** Build a GuardResult from detections */
+    protected buildResult(text: string, detections: Detection[], mode: GuardMode): GuardResult;
+    /** Extract surrounding context for a detection */
+    protected extractContext(text: string, start: number, end: number): string;
+    /** Create a detection with provenance fields pre-filled for regex source */
+    protected makeDetection(text: string, partial: Omit<Detection, "source" | "context" | "disposition">, source?: DetectionSource, disposition?: Disposition): Detection;
+    /** Replace detected text with [REDACTED-TYPE] markers */
+    protected applyRedactions(text: string, detections: Detection[]): string;
+}
+
+/**
+ * PII Guard — detects personally identifiable information using regex patterns.
+ * Pattern library ported from Microsoft Presidio. See ATTRIBUTION.md.
+ */
+
+interface PiiGuardOptions {
+    /** Specific entity types to detect. If empty, all are enabled. */
+    entityTypes?: string[];
+    /** Additional custom patterns */
+    customPatterns?: PiiPattern[];
+}
+declare class PiiGuard extends BaseGuard {
+    readonly name = "pii";
+    private patterns;
+    constructor(options?: PiiGuardOptions);
+    analyze(text: string, config?: Partial<GuardConfig>): Promise<GuardResult>;
+    private detectAll;
+    private deduplicateDetections;
+}
+
+/**
+ * Secret Guard — detects API keys, tokens, credentials, and connection strings.
+ * Pattern approach inspired by HAI-Guardrails. See ATTRIBUTION.md.
+ */
+
+interface SecretGuardOptions {
+    /** Specific secret types to detect. If empty/undefined, all are enabled. */
+    secretTypes?: string[];
+}
+declare class SecretGuard extends BaseGuard {
+    readonly name = "secret";
+    private patterns;
+    constructor(options?: SecretGuardOptions);
+    analyze(text: string, config?: Partial<GuardConfig>): Promise<GuardResult>;
+}
+
+/**
+ * Injection Guard — detects prompt injection attempts.
+ * Detection approach inspired by HAI-Guardrails. See ATTRIBUTION.md.
+ */
+
+declare class InjectionGuard extends BaseGuard {
+    readonly name = "injection";
+    analyze(text: string, config?: Partial<GuardConfig>): Promise<GuardResult>;
+    private heuristicScore;
+}
+
+/**
+ * Leakage Guard — detects system prompt extraction attempts.
+ * Detection approach inspired by HAI-Guardrails. See ATTRIBUTION.md.
+ */
+
+declare class LeakageGuard extends BaseGuard {
+    readonly name = "leakage";
+    analyze(text: string, config?: Partial<GuardConfig>): Promise<GuardResult>;
+}
+
+/**
+ * Test Data Guard — detects synthetic, eval, and placeholder data.
+ * This guard identifies data that was clearly fabricated for testing rather than
+ * real sensitive content. Detections are informational, not blocking.
+ */
+
+declare class TestDataGuard extends BaseGuard {
+    readonly name = "testdata";
+    analyze(text: string, config?: Partial<GuardConfig>): Promise<GuardResult>;
+    /** Build a result that always passes — test data is informational, not blocking */
+    private buildInformationalResult;
+    private deduplicateDetections;
+}
+
+/** All built-in policies indexed by name */
+declare const BUILTIN_POLICIES: Record<string, PolicyDefinition>;
+/** Retrieve a built-in policy by name */
+declare function getPolicy(name: string): PolicyDefinition;
+
+/**
+ * Compose policies by merging a base with overlays.
+ * "Stricter wins": lower thresholds, entity-type intersection, block over redact.
+ */
+declare function resolvePolicy(base: string | PolicyDefinition, ...overlays: (string | PolicyDefinition)[]): PolicyDefinition;
+/** Translate a resolved policy into guard constructor options and per-guard configs */
+declare function policyToEngineConfig(policy: PolicyDefinition): {
+    piiOptions: PiiGuardOptions;
+    secretOptions: SecretGuardOptions;
+    guardConfigs: Record<string, Partial<GuardConfig>>;
+};
+
+/**
+ * Compute a risk assessment from guard results and a policy definition.
+ * Pure function — no side effects, no engine mutation.
+ */
+declare function assessRisk(results: GuardResult[], policy: PolicyDefinition): RiskAssessment;
+
+interface BulkheadConfig {
+    enabled: boolean;
+    debounceMs: number;
+    guards: {
+        pii: {
+            enabled: boolean;
+        };
+        secret: {
+            enabled: boolean;
+        };
+        injection: {
+            enabled: boolean;
+        };
+        contentSafety: {
+            enabled: boolean;
+        };
+    };
+    cascade: {
+        escalationThreshold: number;
+        contextSentences: number;
+        modelEnabled: boolean;
+        modelId: string;
+    };
+    /** Named policy or custom PolicyDefinition. Overrides guard-level config. */
+    policy?: string | PolicyDefinition;
+    /** Additional policy overlays for composition */
+    policyOverlays?: (string | PolicyDefinition)[];
+}
+declare const DEFAULT_CONFIG: BulkheadConfig;
+/** Create a configured engine from a BulkheadConfig */
+declare function createEngine(config?: BulkheadConfig): GuardrailsEngine;
+
+export { BUILTIN_POLICIES, BaseGuard, type BulkheadConfig, CascadeConfig, type ClassifiedIssue, DEFAULT_CONFIG, Detection, DetectionSource, Disposition, EngineConfig, Guard, GuardConfig, GuardMode, type GuardPolicyConfig, GuardResult, GuardrailsEngine, InjectionGuard, LeakageGuard, PiiGuard, type PiiGuardOptions, PiiPattern, type PolicyDefinition, type RiskAssessment, type RiskLevel, type RiskThresholds, SecretGuard, type SecretGuardOptions, type TestDataFlag, TestDataGuard, assessRisk, createEngine, getPolicy, policyToEngineConfig, resolvePolicy };