@holokai/sdk 0.1.0

package/dist/plugin/guard.d.ts

@@ -0,0 +1,307 @@
+import { IPlugin } from "./base";
+/**
+ * Types of guards
+ */
+export declare enum GuardType {
+    CONTENT_FILTER = "content_filter",
+    RATE_LIMITER = "rate_limiter",
+    TOKEN_LIMITER = "token_limiter",
+    PII_DETECTOR = "pii_detector",
+    PROMPT_INJECTION = "prompt_injection",
+    CUSTOM = "custom"
+}
+/**
+ * Guard rule condition for matching requests/responses
+ */
+export interface GuardCondition {
+    /**
+     * Field to check (e.g., 'content', 'headers.authorization', 'model')
+     */
+    field: string;
+    /**
+     * Operator for comparison
+     */
+    operator: 'equals' | 'contains' | 'regex' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'not_in';
+    /**
+     * Value(s) to compare against
+     */
+    value: string | number | boolean | string[] | number[];
+    /**
+     * Case sensitivity for string comparisons
+     */
+    caseSensitive?: boolean;
+    /**
+     * Negate the condition
+     */
+    negate?: boolean;
+}
+/**
+ * Guard rule definition
+ */
+export interface GuardRule {
+    id: string;
+    name: string;
+    description?: string;
+    enabled: boolean;
+    severity: 'low' | 'medium' | 'high' | 'critical';
+    action: 'allow' | 'block' | 'redact' | 'warn';
+    /**
+     * Conditions that must be met for this rule to apply
+     * If multiple conditions, all must match (AND logic)
+     */
+    conditions?: GuardCondition[];
+    /**
+     * Logical operator for multiple conditions
+     */
+    conditionOperator?: 'AND' | 'OR';
+}
+/**
+ * Details about a guard rule violation
+ */
+export interface GuardViolation {
+    /**
+     * ID of the rule that was violated
+     */
+    rule: string;
+    /**
+     * Severity of the violation
+     */
+    severity: 'low' | 'medium' | 'high' | 'critical';
+    /**
+     * Human-readable message about the violation
+     */
+    message: string;
+    /**
+     * Field/location where violation occurred
+     */
+    field?: string;
+    /**
+     * The value that caused the violation (for debugging)
+     */
+    offendingValue?: string | number | boolean;
+    /**
+     * Suggested remediation action
+     */
+    remediation?: string;
+}
+/**
+ * Guard processing metadata
+ */
+export interface GuardMetadata {
+    /**
+     * Time taken to process in milliseconds
+     */
+    processingTimeMs?: number;
+    /**
+     * Number of rules evaluated
+     */
+    rulesEvaluated?: number;
+    /**
+     * Guard plugin that performed the validation
+     */
+    guardPlugin?: string;
+    /**
+     * Additional plugin-specific metadata
+     */
+    [key: string]: string | number | boolean | undefined;
+}
+/**
+ * Result of guard validation
+ */
+export interface GuardResult {
+    passed: boolean;
+    violations?: GuardViolation[];
+    /**
+     * Content that was redacted/sanitized (if action was 'redact')
+     * Contains the sanitized version of the original content
+     */
+    redactedContent?: string | object;
+    /**
+     * Processing metadata
+     */
+    metadata?: GuardMetadata;
+    errors?: string[];
+}
+/**
+ * Rate limiting configuration
+ */
+export interface RateLimiting {
+    /**
+     * Max requests per time window
+     */
+    maxRequests: number;
+    /**
+     * Time window in seconds
+     */
+    windowSeconds: number;
+    /**
+     * Rate limit per user or global
+     */
+    scope: 'user' | 'global' | 'ip';
+}
+/**
+ * Custom pattern for PII detection
+ */
+export interface CustomPattern {
+    name: string;
+    pattern: string;
+    flags?: string;
+}
+/**
+ * PII detection settings
+ */
+export interface PIIDetection {
+    /**
+     * Types of PII to detect
+     */
+    detectTypes: Array<'email' | 'phone' | 'ssn' | 'credit_card' | 'ip_address' | 'custom'>;
+    /**
+     * Custom regex patterns for PII detection
+     */
+    customPatterns?: CustomPattern[];
+    /**
+     * Action when PII is detected
+     */
+    action: 'block' | 'redact' | 'warn';
+}
+/**
+ * Content filtering settings
+ */
+export interface ContentFiltering {
+    /**
+     * Blocked keywords/phrases
+     */
+    blockedTerms?: string[];
+    /**
+     * Allowed domains for URLs
+     */
+    allowedDomains?: string[];
+    /**
+     * Maximum content length
+     */
+    maxContentLength?: number;
+}
+/**
+ * Configuration for guard plugins
+ */
+export interface GuardConfig {
+    enabled: boolean;
+    rules: GuardRule[];
+    mode: 'blocking' | 'monitoring';
+    /**
+     * Rate limiting configuration (if applicable)
+     */
+    rateLimiting?: RateLimiting;
+    /**
+     * PII detection settings (if applicable)
+     */
+    piiDetection?: PIIDetection;
+    /**
+     * Content filtering settings (if applicable)
+     */
+    contentFiltering?: ContentFiltering;
+}
+/**
+ * Guard plugin interface for request/response validation and security.
+ * @template TRequest The type of requests validated by this guard.
+ * @template TResponse The type of responses validated by this guard.
+ *
+ * @example
+ * ```typescript
+ * class ContentFilterPlugin
+ *   extends BasePlugin
+ *   implements IGuardPlugin<unknown, unknown>
+ * {
+ *   async validateRequest(request: unknown): Promise<GuardResult> {
+ *     const violations = await this.checkContent(request);
+ *     return {
+ *       passed: violations.length === 0,
+ *       violations
+ *     };
+ *   }
+ *
+ *   async validateResponse(response: unknown): Promise<GuardResult> {
+ *     return { passed: true };
+ *   }
+ *
+ *   getGuardType(): GuardType {
+ *     return GuardType.CONTENT_FILTER;
+ *   }
+ *
+ *   getRules(): GuardRule[] {
+ *     return this.currentRules;
+ *   }
+ *
+ *   async configure(config: Partial<GuardConfig>): Promise<void> {
+ *     Object.assign(this.config, config);
+ *   }
+ * }
+ * ```
+ */
+export interface IGuardPlugin<TRequest = unknown, TResponse = unknown> extends IPlugin {
+    /**
+     * Validate an incoming request.
+     * @param request The request to validate (typed per guard).
+     * @returns Validation result with pass/fail and violations.
+     */
+    validateRequest(request: TRequest): Promise<GuardResult>;
+    /**
+     * Validate an outgoing response.
+     * @param response The response to validate (typed per guard).
+     * @returns Validation result with pass/fail and violations.
+     */
+    validateResponse(response: TResponse): Promise<GuardResult>;
+    /**
+     * Get the type of guard.
+     * @returns The guard type.
+     */
+    getGuardType(): GuardType;
+    /**
+     * Get configured rules.
+     * @returns Array of guard rules.
+     */
+    getRules(): GuardRule[];
+    /**
+     * Configure the guard. Implementations may merge with existing config.
+     * @param config Guard configuration (partial updates allowed).
+     */
+    configure(config: Partial<GuardConfig>): Promise<void>;
+}
+export declare const GuardResultSchema: {
+    $schema: string;
+    type: string;
+    properties: {
+        passed: {
+            type: string;
+        };
+        errors: {
+            type: string;
+            items: {
+                type: string;
+            };
+        };
+    };
+    required: string[];
+    if: {
+        properties: {
+            passed: {
+                const: boolean;
+            };
+        };
+    };
+    then: {
+        required: string[];
+        properties: {
+            errors: {
+                minItems: number;
+            };
+        };
+    };
+    else: {
+        properties: {
+            errors: boolean;
+        };
+    };
+    additionalProperties: boolean;
+};
+//# sourceMappingURL=guard.d.ts.map

package/dist/plugin/guard.d.ts.map

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

package/dist/plugin/guard.js

@@ -0,0 +1,46 @@
+/**
+ * Types of guards
+ */
+export var GuardType;
+(function (GuardType) {
+    GuardType["CONTENT_FILTER"] = "content_filter";
+    GuardType["RATE_LIMITER"] = "rate_limiter";
+    GuardType["TOKEN_LIMITER"] = "token_limiter";
+    GuardType["PII_DETECTOR"] = "pii_detector";
+    GuardType["PROMPT_INJECTION"] = "prompt_injection";
+    GuardType["CUSTOM"] = "custom";
+})(GuardType || (GuardType = {}));
+export const GuardResultSchema = {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "type": "object",
+    "properties": {
+        "passed": {
+            "type": "boolean"
+        },
+        "errors": {
+            "type": "array",
+            "items": {
+                "type": "string"
+            }
+        }
+    },
+    "required": ["passed"],
+    "if": {
+        "properties": { "passed": { "const": false } }
+    },
+    "then": {
+        "required": ["errors"],
+        "properties": {
+            "errors": {
+                "minItems": 1
+            }
+        }
+    },
+    "else": {
+        "properties": {
+            "errors": false
+        }
+    },
+    "additionalProperties": false
+};
+//# sourceMappingURL=guard.js.map

package/dist/plugin/guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guard.js","sourceRoot":"","sources":["../../src/plugin/guard.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,CAAN,IAAY,SAOX;AAPD,WAAY,SAAS;IACjB,8CAAiC,CAAA;IACjC,0CAA6B,CAAA;IAC7B,4CAA+B,CAAA;IAC/B,0CAA6B,CAAA;IAC7B,kDAAqC,CAAA;IACrC,8BAAiB,CAAA;AACrB,CAAC,EAPW,SAAS,KAAT,SAAS,QAOpB;AA2SD,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC7B,SAAS,EAAE,8CAA8C;IACzD,MAAM,EAAE,QAAQ;IAChB,YAAY,EAAE;QACV,QAAQ,EAAE;YACN,MAAM,EAAE,SAAS;SACpB;QACD,QAAQ,EAAE;YACN,MAAM,EAAE,OAAO;YACf,OAAO,EAAE;gBACL,MAAM,EAAE,QAAQ;aACnB;SACJ;KACJ;IACD,UAAU,EAAE,CAAC,QAAQ,CAAC;IACtB,IAAI,EAAE;QACF,YAAY,EAAE,EAAC,QAAQ,EAAE,EAAC,OAAO,EAAE,KAAK,EAAC,EAAC;KAC7C;IACD,MAAM,EAAE;QACJ,UAAU,EAAE,CAAC,QAAQ,CAAC;QACtB,YAAY,EAAE;YACV,QAAQ,EAAE;gBACN,UAAU,EAAE,CAAC;aAChB;SACJ;KACJ;IACD,MAAM,EAAE;QACJ,YAAY,EAAE;YACV,QAAQ,EAAE,KAAK;SAClB;KACJ;IACD,sBAAsB,EAAE,KAAK;CAChC,CAAC"}

package/dist/plugin/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Plugin SDK version for compatibility checking
+ */
+export declare const PLUGIN_SDK_VERSION = "0.1.0";
+export * from './base';
+export * from './context';
+export * from './provider';
+export * from './errors';
+export * from './evaluator';
+export * from './guard';
+export * from './manifest';
+export * from './provider';
+export * from './registry';
+//# sourceMappingURL=index.d.ts.map

package/dist/plugin/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/plugin/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,eAAO,MAAM,kBAAkB,UAAU,CAAC;AAE1C,cAAc,QAAQ,CAAC;AACvB,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,SAAS,CAAC;AACxB,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC"}

package/dist/plugin/index.js

@@ -0,0 +1,14 @@
+/**
+ * Plugin SDK version for compatibility checking
+ */
+export const PLUGIN_SDK_VERSION = '0.1.0';
+export * from './base';
+export * from './context';
+export * from './provider';
+export * from './errors';
+export * from './evaluator';
+export * from './guard';
+export * from './manifest';
+export * from './provider';
+export * from './registry';
+//# sourceMappingURL=index.js.map

package/dist/plugin/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/plugin/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,OAAO,CAAC;AAE1C,cAAc,QAAQ,CAAC;AACvB,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,SAAS,CAAC;AACxB,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC"}