@artemiskit/sdk 0.3.1 → 0.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +229 -0
- package/README.md +44 -1
- package/dist/artemiskit.d.ts +149 -0
- package/dist/artemiskit.d.ts.map +1 -0
- package/dist/builders/index.d.ts +352 -0
- package/dist/builders/index.d.ts.map +1 -0
- package/dist/builders/index.js +354 -0
- package/dist/contracts/index.d.ts +253 -0
- package/dist/contracts/index.d.ts.map +1 -0
- package/dist/contracts/index.js +53 -0
- package/dist/guardian/action-validator.d.ts +92 -0
- package/dist/guardian/action-validator.d.ts.map +1 -0
- package/dist/guardian/circuit-breaker.d.ts +211 -0
- package/dist/guardian/circuit-breaker.d.ts.map +1 -0
- package/dist/guardian/guardian.d.ts +213 -0
- package/dist/guardian/guardian.d.ts.map +1 -0
- package/dist/guardian/guardrails.d.ts +107 -0
- package/dist/guardian/guardrails.d.ts.map +1 -0
- package/dist/guardian/index.d.ts +35 -0
- package/dist/guardian/index.d.ts.map +1 -0
- package/dist/guardian/intent-classifier.d.ts +81 -0
- package/dist/guardian/intent-classifier.d.ts.map +1 -0
- package/dist/guardian/interceptor.d.ts +141 -0
- package/dist/guardian/interceptor.d.ts.map +1 -0
- package/dist/guardian/policy.d.ts +52 -0
- package/dist/guardian/policy.d.ts.map +1 -0
- package/dist/guardian/semantic-validator.d.ts +61 -0
- package/dist/guardian/semantic-validator.d.ts.map +1 -0
- package/dist/guardian/types.d.ts +653 -0
- package/dist/guardian/types.d.ts.map +1 -0
- package/dist/index.d.ts +23 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +44918 -28644
- package/dist/matchers/core.d.ts +81 -0
- package/dist/matchers/core.d.ts.map +1 -0
- package/dist/matchers/index.d.ts +6 -0
- package/dist/matchers/index.d.ts.map +1 -0
- package/dist/matchers/index.js +13 -59
- package/dist/matchers/jest.d.ts +46 -0
- package/dist/matchers/jest.d.ts.map +1 -0
- package/dist/matchers/jest.js +0 -46
- package/dist/matchers/vitest.d.ts +24 -0
- package/dist/matchers/vitest.d.ts.map +1 -0
- package/dist/matchers/vitest.js +0 -46
- package/dist/types-only.d.ts +31 -0
- package/dist/types-only.d.ts.map +1 -0
- package/dist/types-only.js +1 -0
- package/dist/types.d.ts +379 -0
- package/dist/types.d.ts.map +1 -0
- package/dist/utils/index.d.ts +112 -0
- package/dist/utils/index.d.ts.map +1 -0
- package/dist/utils/index.js +58 -0
- package/package.json +19 -4
- package/src/__tests__/builders.test.ts +450 -0
- package/src/__tests__/circuit-breaker.test.ts +704 -0
- package/src/__tests__/compare.test.ts +469 -0
- package/src/__tests__/contracts.test.ts +354 -0
- package/src/__tests__/guardian-modes.test.ts +215 -0
- package/src/__tests__/guardrails.test.ts +404 -0
- package/src/__tests__/semantic-validator.test.ts +421 -0
- package/src/__tests__/utils.test.ts +324 -0
- package/src/__tests__/validate.test.ts +310 -0
- package/src/artemiskit.ts +479 -5
- package/src/builders/index.ts +700 -0
- package/src/contracts/index.ts +357 -0
- package/src/guardian/circuit-breaker.ts +74 -28
- package/src/guardian/guardian.ts +307 -20
- package/src/guardian/guardrails.ts +143 -1
- package/src/guardian/index.ts +35 -1
- package/src/guardian/interceptor.ts +87 -11
- package/src/guardian/semantic-validator.ts +399 -0
- package/src/guardian/types.ts +413 -2
- package/src/index.ts +258 -14
- package/src/types-only.ts +276 -0
- package/src/types.ts +186 -0
- package/src/utils/index.ts +225 -0
- package/tsconfig.json +2 -1
- package/adapters/openai/dist/index.js +0 -5625
|
@@ -0,0 +1,213 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Guardian - Main runtime protection class
|
|
3
|
+
*
|
|
4
|
+
* Provides a unified interface for all guardian features:
|
|
5
|
+
* - Interceptor for LLM client wrapping
|
|
6
|
+
* - Action validation for tool/function calls
|
|
7
|
+
* - Intent classification
|
|
8
|
+
* - Input/output guardrails
|
|
9
|
+
* - Policy-based configuration
|
|
10
|
+
* - Circuit breaker protection
|
|
11
|
+
* - Metrics collection
|
|
12
|
+
*/
|
|
13
|
+
import type { ModelClient } from '@artemiskit/core';
|
|
14
|
+
import { RateLimiter } from './circuit-breaker';
|
|
15
|
+
import { type GuardrailsConfig } from './guardrails';
|
|
16
|
+
import { GuardianBlockedError, GuardianInterceptor, type GuardrailFn } from './interceptor';
|
|
17
|
+
import type { ActionDefinition, ContentValidationConfig, GuardianEventHandler, GuardianMetrics, GuardianMode, GuardianModeCanonical, GuardianPolicy, MultiTurnConfig, Violation } from './types';
|
|
18
|
+
/**
|
|
19
|
+
* Normalize Guardian mode to canonical form with deprecation warning
|
|
20
|
+
* @param mode - The mode to normalize
|
|
21
|
+
* @returns The canonical mode
|
|
22
|
+
*/
|
|
23
|
+
export declare function normalizeGuardianMode(mode: GuardianMode): GuardianModeCanonical;
|
|
24
|
+
/**
|
|
25
|
+
* Guardian configuration options
|
|
26
|
+
*/
|
|
27
|
+
export interface GuardianConfig {
|
|
28
|
+
/**
|
|
29
|
+
* Operating mode
|
|
30
|
+
*
|
|
31
|
+
* Canonical modes (recommended):
|
|
32
|
+
* - 'observe': Log only, never block (for monitoring)
|
|
33
|
+
* - 'selective': Block high-confidence threats (threshold-based)
|
|
34
|
+
* - 'strict': Block all detected violations (maximum protection)
|
|
35
|
+
*
|
|
36
|
+
* Legacy modes (deprecated):
|
|
37
|
+
* - 'testing' → 'observe'
|
|
38
|
+
* - 'guardian' → 'strict'
|
|
39
|
+
* - 'hybrid' → 'selective'
|
|
40
|
+
*/
|
|
41
|
+
mode?: GuardianMode;
|
|
42
|
+
/** Policy file path or policy object */
|
|
43
|
+
policy?: string | GuardianPolicy;
|
|
44
|
+
/** LLM client for semantic validation and intent classification */
|
|
45
|
+
llmClient?: ModelClient;
|
|
46
|
+
/** Enable input validation */
|
|
47
|
+
validateInput?: boolean;
|
|
48
|
+
/** Enable output validation */
|
|
49
|
+
validateOutput?: boolean;
|
|
50
|
+
/** Block on validation failure */
|
|
51
|
+
blockOnFailure?: boolean;
|
|
52
|
+
/**
|
|
53
|
+
* Content validation strategy configuration
|
|
54
|
+
*
|
|
55
|
+
* @default { strategy: 'semantic', semanticThreshold: 0.9 }
|
|
56
|
+
*/
|
|
57
|
+
contentValidation?: ContentValidationConfig;
|
|
58
|
+
/** Custom guardrails configuration (pattern-based) */
|
|
59
|
+
guardrails?: GuardrailsConfig;
|
|
60
|
+
/**
|
|
61
|
+
* Multi-turn detection configuration
|
|
62
|
+
*
|
|
63
|
+
* Enable to detect attacks that span multiple messages:
|
|
64
|
+
* - Trust-building before sensitive requests
|
|
65
|
+
* - Escalating risk patterns
|
|
66
|
+
* - Context manipulation claims
|
|
67
|
+
* - Split payload attacks
|
|
68
|
+
*/
|
|
69
|
+
multiTurn?: MultiTurnConfig;
|
|
70
|
+
/** Custom action definitions */
|
|
71
|
+
allowedActions?: ActionDefinition[];
|
|
72
|
+
/** Event handler */
|
|
73
|
+
onEvent?: GuardianEventHandler;
|
|
74
|
+
/** Enable metrics collection */
|
|
75
|
+
collectMetrics?: boolean;
|
|
76
|
+
/** Enable logging */
|
|
77
|
+
enableLogging?: boolean;
|
|
78
|
+
}
|
|
79
|
+
/**
|
|
80
|
+
* Guardian class - main runtime protection API
|
|
81
|
+
*/
|
|
82
|
+
export declare class Guardian {
|
|
83
|
+
private config;
|
|
84
|
+
private policy;
|
|
85
|
+
private circuitBreaker;
|
|
86
|
+
private rateLimiter?;
|
|
87
|
+
private metricsCollector;
|
|
88
|
+
private actionValidator;
|
|
89
|
+
private intentClassifier;
|
|
90
|
+
private semanticValidator?;
|
|
91
|
+
private inputGuardrails;
|
|
92
|
+
private outputGuardrails;
|
|
93
|
+
private eventHandlers;
|
|
94
|
+
/** The normalized (canonical) mode after processing legacy modes */
|
|
95
|
+
private normalizedMode;
|
|
96
|
+
constructor(config?: GuardianConfig);
|
|
97
|
+
/**
|
|
98
|
+
* Wrap a model client with guardian protection
|
|
99
|
+
*
|
|
100
|
+
* Note: Checks circuit breaker on each LLM request via the shouldAllow callback.
|
|
101
|
+
* When the circuit is open due to detected attack patterns, all LLM requests are blocked.
|
|
102
|
+
*/
|
|
103
|
+
protect(client: ModelClient): GuardianInterceptor;
|
|
104
|
+
/**
|
|
105
|
+
* Validate a tool/function call
|
|
106
|
+
*/
|
|
107
|
+
validateAction(toolName: string, args: Record<string, unknown>, agentId?: string): Promise<{
|
|
108
|
+
valid: boolean;
|
|
109
|
+
violations: Violation[];
|
|
110
|
+
sanitizedArguments?: Record<string, unknown>;
|
|
111
|
+
requiresApproval?: boolean;
|
|
112
|
+
}>;
|
|
113
|
+
/**
|
|
114
|
+
* Classify intent of a message
|
|
115
|
+
*/
|
|
116
|
+
classifyIntent(text: string): Promise<import("./types").IntentClassification[]>;
|
|
117
|
+
/**
|
|
118
|
+
* Validate input content
|
|
119
|
+
*/
|
|
120
|
+
validateInput(content: string): Promise<{
|
|
121
|
+
valid: boolean;
|
|
122
|
+
violations: Violation[];
|
|
123
|
+
transformedContent?: string;
|
|
124
|
+
}>;
|
|
125
|
+
/**
|
|
126
|
+
* Validate output content
|
|
127
|
+
*/
|
|
128
|
+
validateOutput(content: string): Promise<{
|
|
129
|
+
valid: boolean;
|
|
130
|
+
violations: Violation[];
|
|
131
|
+
transformedContent?: string;
|
|
132
|
+
}>;
|
|
133
|
+
/**
|
|
134
|
+
* Get current metrics
|
|
135
|
+
*/
|
|
136
|
+
getMetrics(): GuardianMetrics;
|
|
137
|
+
/**
|
|
138
|
+
* Get circuit breaker state
|
|
139
|
+
*/
|
|
140
|
+
getCircuitBreakerState(): {
|
|
141
|
+
state: string;
|
|
142
|
+
violationCount: number;
|
|
143
|
+
timeUntilReset: number;
|
|
144
|
+
};
|
|
145
|
+
/**
|
|
146
|
+
* Get rate limit status
|
|
147
|
+
*/
|
|
148
|
+
getRateLimitStatus(): ReturnType<RateLimiter['getStatus']> | undefined;
|
|
149
|
+
/**
|
|
150
|
+
* Get the current policy
|
|
151
|
+
*/
|
|
152
|
+
getPolicy(): GuardianPolicy;
|
|
153
|
+
/**
|
|
154
|
+
* Get the normalized (canonical) operating mode
|
|
155
|
+
*
|
|
156
|
+
* This returns the canonical mode even if a legacy mode was configured.
|
|
157
|
+
*/
|
|
158
|
+
getMode(): GuardianModeCanonical;
|
|
159
|
+
/**
|
|
160
|
+
* Check if Guardian should block based on mode and violation severity
|
|
161
|
+
*
|
|
162
|
+
* - observe: Never blocks
|
|
163
|
+
* - selective: Blocks high-confidence/high-severity only
|
|
164
|
+
* - strict: Blocks all violations
|
|
165
|
+
*/
|
|
166
|
+
shouldBlock(violation: Violation): boolean;
|
|
167
|
+
/**
|
|
168
|
+
* Get the content validation configuration
|
|
169
|
+
*/
|
|
170
|
+
getContentValidationConfig(): ContentValidationConfig;
|
|
171
|
+
/**
|
|
172
|
+
* Update policy at runtime
|
|
173
|
+
*/
|
|
174
|
+
updatePolicy(policy: GuardianPolicy): void;
|
|
175
|
+
/**
|
|
176
|
+
* Register an allowed action
|
|
177
|
+
*/
|
|
178
|
+
registerAction(action: ActionDefinition): void;
|
|
179
|
+
/**
|
|
180
|
+
* Add a custom guardrail
|
|
181
|
+
*/
|
|
182
|
+
addInputGuardrail(guardrail: GuardrailFn): void;
|
|
183
|
+
/**
|
|
184
|
+
* Add a custom output guardrail
|
|
185
|
+
*/
|
|
186
|
+
addOutputGuardrail(guardrail: GuardrailFn): void;
|
|
187
|
+
/**
|
|
188
|
+
* Register an event handler
|
|
189
|
+
*/
|
|
190
|
+
onEvent(handler: GuardianEventHandler): void;
|
|
191
|
+
/**
|
|
192
|
+
* Remove an event handler
|
|
193
|
+
*/
|
|
194
|
+
offEvent(handler: GuardianEventHandler): void;
|
|
195
|
+
/**
|
|
196
|
+
* Reset all metrics and state
|
|
197
|
+
*/
|
|
198
|
+
reset(): void;
|
|
199
|
+
/**
|
|
200
|
+
* Load or create policy
|
|
201
|
+
*/
|
|
202
|
+
private loadOrCreatePolicy;
|
|
203
|
+
/**
|
|
204
|
+
* Emit an event to all handlers
|
|
205
|
+
*/
|
|
206
|
+
private emit;
|
|
207
|
+
}
|
|
208
|
+
/**
|
|
209
|
+
* Create a guardian instance
|
|
210
|
+
*/
|
|
211
|
+
export declare function createGuardian(config?: GuardianConfig): Guardian;
|
|
212
|
+
export { GuardianBlockedError };
|
|
213
|
+
//# sourceMappingURL=guardian.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"guardian.d.ts","sourceRoot":"","sources":["../../src/guardian/guardian.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Guardrails Module
|
|
3
|
+
*
|
|
4
|
+
* Provides input/output validation including:
|
|
5
|
+
* - Injection detection (prompt injection, jailbreaks)
|
|
6
|
+
* - PII detection and redaction
|
|
7
|
+
* - Content filtering
|
|
8
|
+
* - Custom validation rules
|
|
9
|
+
*/
|
|
10
|
+
import type { ContentCategory, ContentFilterResult, GuardrailResult, InjectionDetection, PIIDetection, PIIType, PatternCategory, PatternConfig, ViolationSeverity } from './types';
|
|
11
|
+
/**
|
|
12
|
+
* Options for custom pattern matching
|
|
13
|
+
*/
|
|
14
|
+
export interface CustomPatternOptions {
|
|
15
|
+
/** Case-insensitive matching (default: true) */
|
|
16
|
+
caseInsensitive?: boolean;
|
|
17
|
+
/** Pattern category for categorization */
|
|
18
|
+
category?: PatternCategory;
|
|
19
|
+
/** Severity level for matches */
|
|
20
|
+
severity?: ViolationSeverity;
|
|
21
|
+
}
|
|
22
|
+
/**
|
|
23
|
+
* Match a pattern against content with options
|
|
24
|
+
*/
|
|
25
|
+
export declare function matchPattern(content: string, pattern: string | RegExp, options?: CustomPatternOptions): {
|
|
26
|
+
matched: boolean;
|
|
27
|
+
match?: RegExpMatchArray;
|
|
28
|
+
};
|
|
29
|
+
/**
|
|
30
|
+
* Create a custom pattern guardrail
|
|
31
|
+
*/
|
|
32
|
+
export declare function createCustomPatternGuardrail(patterns: Array<string | RegExp>, options?: CustomPatternOptions): (content: string, context?: Record<string, unknown>) => Promise<GuardrailResult>;
|
|
33
|
+
/**
|
|
34
|
+
* Detect injection attempts in text
|
|
35
|
+
*/
|
|
36
|
+
export declare function detectInjection(text: string): InjectionDetection;
|
|
37
|
+
/**
|
|
38
|
+
* Create an injection detection guardrail
|
|
39
|
+
*/
|
|
40
|
+
export declare function createInjectionGuardrail(): (content: string, context?: Record<string, unknown>) => Promise<GuardrailResult>;
|
|
41
|
+
/**
|
|
42
|
+
* Detect PII in text
|
|
43
|
+
*/
|
|
44
|
+
export declare function detectPII(text: string): PIIDetection;
|
|
45
|
+
/**
|
|
46
|
+
* Create a PII detection guardrail
|
|
47
|
+
*/
|
|
48
|
+
export declare function createPIIGuardrail(options?: {
|
|
49
|
+
redact?: boolean;
|
|
50
|
+
block?: boolean;
|
|
51
|
+
allowedTypes?: PIIType[];
|
|
52
|
+
}): (content: string, context?: Record<string, unknown>) => Promise<GuardrailResult>;
|
|
53
|
+
/**
|
|
54
|
+
* Filter content for harmful categories
|
|
55
|
+
*/
|
|
56
|
+
export declare function filterContent(text: string): ContentFilterResult;
|
|
57
|
+
/**
|
|
58
|
+
* Create a content filter guardrail
|
|
59
|
+
*/
|
|
60
|
+
export declare function createContentFilterGuardrail(options?: {
|
|
61
|
+
blockedCategories?: ContentCategory[];
|
|
62
|
+
warnCategories?: ContentCategory[];
|
|
63
|
+
}): (content: string, context?: Record<string, unknown>) => Promise<GuardrailResult>;
|
|
64
|
+
/**
|
|
65
|
+
* Guardrail configuration options
|
|
66
|
+
*/
|
|
67
|
+
export interface GuardrailsConfig {
|
|
68
|
+
/** Enable injection detection */
|
|
69
|
+
injectionDetection?: boolean;
|
|
70
|
+
/** Enable PII detection */
|
|
71
|
+
piiDetection?: boolean;
|
|
72
|
+
/** PII detection options */
|
|
73
|
+
piiOptions?: {
|
|
74
|
+
redact?: boolean;
|
|
75
|
+
block?: boolean;
|
|
76
|
+
allowedTypes?: PIIType[];
|
|
77
|
+
};
|
|
78
|
+
/** Enable content filtering */
|
|
79
|
+
contentFilter?: boolean;
|
|
80
|
+
/** Content filter options */
|
|
81
|
+
contentFilterOptions?: {
|
|
82
|
+
blockedCategories?: ContentCategory[];
|
|
83
|
+
warnCategories?: ContentCategory[];
|
|
84
|
+
};
|
|
85
|
+
/**
|
|
86
|
+
* Pattern matching configuration
|
|
87
|
+
* Controls how custom patterns are matched
|
|
88
|
+
*/
|
|
89
|
+
patternConfig?: PatternConfig;
|
|
90
|
+
/**
|
|
91
|
+
* Custom patterns to add to injection detection
|
|
92
|
+
* These are checked in addition to built-in patterns
|
|
93
|
+
*/
|
|
94
|
+
customPatterns?: Array<string | RegExp>;
|
|
95
|
+
/**
|
|
96
|
+
* Pattern categories to enable (default: all)
|
|
97
|
+
* Use this to selectively enable pattern categories
|
|
98
|
+
*/
|
|
99
|
+
enabledPatternCategories?: PatternCategory[];
|
|
100
|
+
/** Custom guardrails */
|
|
101
|
+
custom?: Array<(content: string, context?: Record<string, unknown>) => Promise<GuardrailResult>>;
|
|
102
|
+
}
|
|
103
|
+
/**
|
|
104
|
+
* Create a composite guardrail from configuration
|
|
105
|
+
*/
|
|
106
|
+
export declare function createGuardrails(config?: GuardrailsConfig): Array<(content: string, context?: Record<string, unknown>) => Promise<GuardrailResult>>;
|
|
107
|
+
//# sourceMappingURL=guardrails.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"guardrails.d.ts","sourceRoot":"","sources":["../../src/guardian/guardrails.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Guardian Module - Runtime protection for AI/LLM applications
|
|
3
|
+
*
|
|
4
|
+
* Provides comprehensive guardrails to prevent AI agents from performing
|
|
5
|
+
* harmful or unauthorized actions.
|
|
6
|
+
*
|
|
7
|
+
* @example
|
|
8
|
+
* ```typescript
|
|
9
|
+
* import { Guardian, createGuardian } from '@artemiskit/sdk/guardian';
|
|
10
|
+
*
|
|
11
|
+
* const guardian = createGuardian({
|
|
12
|
+
* mode: 'guardian',
|
|
13
|
+
* blockOnFailure: true,
|
|
14
|
+
* });
|
|
15
|
+
*
|
|
16
|
+
* // Wrap your LLM client
|
|
17
|
+
* const protectedClient = guardian.protect(myLLMClient);
|
|
18
|
+
*
|
|
19
|
+
* // Validate tool calls
|
|
20
|
+
* const result = await guardian.validateAction('delete_file', { path: '/etc/passwd' });
|
|
21
|
+
* if (!result.valid) {
|
|
22
|
+
* console.log('Blocked:', result.violations);
|
|
23
|
+
* }
|
|
24
|
+
* ```
|
|
25
|
+
*/
|
|
26
|
+
export { Guardian, createGuardian, normalizeGuardianMode, type GuardianConfig } from './guardian';
|
|
27
|
+
export { SemanticValidator, createSemanticValidator } from './semantic-validator';
|
|
28
|
+
export { GuardianInterceptor, GuardianBlockedError, createInterceptor, type InterceptorConfig, type InterceptorStats, type GuardrailFn, } from './interceptor';
|
|
29
|
+
export { ActionValidator, createDefaultActionValidator, type ActionValidatorConfig, type ActionValidationResult, } from './action-validator';
|
|
30
|
+
export { IntentClassifier, createIntentClassifier, type IntentClassifierConfig, type IntentCategory, } from './intent-classifier';
|
|
31
|
+
export { detectInjection, createInjectionGuardrail, detectPII, createPIIGuardrail, filterContent, createContentFilterGuardrail, createGuardrails, matchPattern, createCustomPatternGuardrail, type GuardrailsConfig, type CustomPatternOptions, } from './guardrails';
|
|
32
|
+
export { loadPolicy, parsePolicy, validatePolicy, createDefaultPolicy, mergePolicies, getRulesByType, isRuleEnabled, generatePolicyTemplate, PolicyLoadError, PolicyValidationError, } from './policy';
|
|
33
|
+
export { CircuitBreaker, MetricsCollector, RateLimiter, type CircuitBreakerEvent, type CircuitBreakerEventHandler, type RateLimiterConfig, } from './circuit-breaker';
|
|
34
|
+
export type { GuardianMode, ViolationSeverity, ViolationAction, GuardrailType, Violation, GuardrailResult, PolicyRule, PolicyCondition, GuardianPolicy, CircuitBreakerConfig, RateLimitConfig, CostLimitConfig, ActionDefinition, ActionParameter, ParameterValidation, IntentClassification, PIIDetection, PIIType, PIILocation, InjectionDetection, InjectionType, ContentFilterResult, ContentFlag, ContentCategory, HallucinationCheckResult, Citation, UnsupportedClaim, GuardianMetrics, CircuitBreakerState, CostTracking, GuardianEventType, GuardianEvent, GuardianEventHandler, InterceptedRequest, InterceptedResponse, InterceptedToolCall, InterceptedAgentStep, FrameworkType, FrameworkIntegrationConfig, GuardianModeCanonical, GuardianModeLegacy, GuardianModeAll, ContentValidationConfig, PatternConfig, ValidationCategory, PatternCategory, SemanticValidationResult, SessionStorageType, SessionStorageConfig, SessionMessage, SessionMetrics, ConversationSession, TrustBuildingHeuristicConfig, EscalationHeuristicConfig, ContextManipulationHeuristicConfig, SplitPayloadHeuristicConfig, MultiTurnHeuristics, MultiTurnSemanticConfig, MultiTurnConfig, HeuristicResult, HeuristicResults, MultiTurnValidationResult, ValidateMessageOptions, } from './types';
|
|
35
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/guardian/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAGH,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,qBAAqB,EAAE,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC;AAGlG,OAAO,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAGlF,OAAO,EACL,mBAAmB,EACnB,oBAAoB,EACpB,iBAAiB,EACjB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,WAAW,GACjB,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,eAAe,EACf,4BAA4B,EAC5B,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,GAC5B,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EACL,gBAAgB,EAChB,sBAAsB,EACtB,KAAK,sBAAsB,EAC3B,KAAK,cAAc,GACpB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EACL,eAAe,EACf,wBAAwB,EACxB,SAAS,EACT,kBAAkB,EAClB,aAAa,EACb,4BAA4B,EAC5B,gBAAgB,EAEhB,YAAY,EACZ,4BAA4B,EAC5B,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,GAC1B,MAAM,cAAc,CAAC;AAGtB,OAAO,EACL,UAAU,EACV,WAAW,EACX,cAAc,EACd,mBAAmB,EACnB,aAAa,EACb,cAAc,EACd,aAAa,EACb,sBAAsB,EACtB,eAAe,EACf,qBAAqB,GACtB,MAAM,UAAU,CAAC;AAGlB,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,WAAW,EACX,KAAK,mBAAmB,EACxB,KAAK,0BAA0B,EAC/B,KAAK,iBAAiB,GACvB,MAAM,mBAAmB,CAAC;AAG3B,YAAY,EAEV,YAAY,EACZ,iBAAiB,EACjB,eAAe,EACf,aAAa,EACb,SAAS,EACT,eAAe,EAEf,UAAU,EACV,eAAe,EACf,cAAc,EACd,oBAAoB,EACpB,eAAe,EACf,eAAe,EAEf,gBAAgB,EAChB,eAAe,EACf,mBAAmB,EAEnB,oBAAoB,EAEpB,YAAY,EACZ,OAAO,EACP,WAAW,EACX,kBAAkB,EAClB,aAAa,EACb,mBAAmB,EACnB,WAAW,EACX,eAAe,EACf,wBAAwB,EACxB,QAAQ,EACR,gBAAgB,EAEhB,eAAe,EACf,mBAAmB,EACnB,YAAY,EAEZ,iBAAiB,EACjB,aAAa,EACb,oBAAoB,EAEpB,kBAAkB,EAClB,mBAAmB,EACnB,mBAAmB,EACnB,oBAAoB,EAEpB,aAAa,EACb,0BAA0B,EAE1B,qBAAqB,EACrB,kBAAkB,EAClB,eAAe,EAEf,uBAAuB,EACvB,aAAa,EACb,kBAAkB,EAClB,eAAe,EACf,wBAAwB,EAExB,kBAAkB,EAClB,oBAAoB,EACpB,cAAc,EACd,cAAc,EACd,mBAAmB,EACnB,4BAA4B,EAC5B,yBAAyB,EACzB,kCAAkC,EAClC,2BAA2B,EAC3B,mBAAmB,EACnB,uBAAuB,EACvB,eAAe,EACf,eAAe,EACf,gBAAgB,EAChB,yBAAyB,EACzB,sBAAsB,GACvB,MAAM,SAAS,CAAC"}
|
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Intent Classifier
|
|
3
|
+
*
|
|
4
|
+
* Analyzes AI/agent intent to determine what it's trying to accomplish,
|
|
5
|
+
* not just the literal action. Uses pattern matching and optionally LLM-based
|
|
6
|
+
* classification to detect potentially risky intents.
|
|
7
|
+
*/
|
|
8
|
+
import type { ModelClient } from '@artemiskit/core';
|
|
9
|
+
import type { GuardrailResult, IntentClassification, ViolationSeverity } from './types';
|
|
10
|
+
/**
|
|
11
|
+
* Intent category definition
|
|
12
|
+
*/
|
|
13
|
+
export interface IntentCategory {
|
|
14
|
+
name: string;
|
|
15
|
+
description: string;
|
|
16
|
+
riskLevel: ViolationSeverity;
|
|
17
|
+
patterns?: RegExp[];
|
|
18
|
+
keywords?: string[];
|
|
19
|
+
examples?: string[];
|
|
20
|
+
action?: 'allow' | 'warn' | 'block';
|
|
21
|
+
}
|
|
22
|
+
/**
|
|
23
|
+
* Intent classifier configuration
|
|
24
|
+
*/
|
|
25
|
+
export interface IntentClassifierConfig {
|
|
26
|
+
/** Pre-defined intent categories */
|
|
27
|
+
categories?: IntentCategory[];
|
|
28
|
+
/** Use LLM for classification */
|
|
29
|
+
useLLM?: boolean;
|
|
30
|
+
/** LLM client for classification */
|
|
31
|
+
llmClient?: ModelClient;
|
|
32
|
+
/** Minimum confidence threshold */
|
|
33
|
+
confidenceThreshold?: number;
|
|
34
|
+
/** Block unknown intents */
|
|
35
|
+
blockUnknown?: boolean;
|
|
36
|
+
/** Block high-risk intents */
|
|
37
|
+
blockHighRisk?: boolean;
|
|
38
|
+
}
|
|
39
|
+
/**
|
|
40
|
+
* Intent Classifier
|
|
41
|
+
*
|
|
42
|
+
* Analyzes text to determine the underlying intent and assess risk.
|
|
43
|
+
*/
|
|
44
|
+
export declare class IntentClassifier {
|
|
45
|
+
private config;
|
|
46
|
+
private categories;
|
|
47
|
+
constructor(config?: IntentClassifierConfig);
|
|
48
|
+
/**
|
|
49
|
+
* Classify the intent of a given text
|
|
50
|
+
*/
|
|
51
|
+
classify(text: string): Promise<IntentClassification[]>;
|
|
52
|
+
/**
|
|
53
|
+
* Create a guardrail function from this classifier
|
|
54
|
+
*/
|
|
55
|
+
asGuardrail(): (content: string, context?: Record<string, unknown>) => Promise<GuardrailResult>;
|
|
56
|
+
/**
|
|
57
|
+
* Validate content and return guardrail result
|
|
58
|
+
*/
|
|
59
|
+
validate(text: string): Promise<GuardrailResult>;
|
|
60
|
+
/**
|
|
61
|
+
* Add a custom intent category
|
|
62
|
+
*/
|
|
63
|
+
addCategory(category: IntentCategory): void;
|
|
64
|
+
/**
|
|
65
|
+
* Remove an intent category
|
|
66
|
+
*/
|
|
67
|
+
removeCategory(name: string): void;
|
|
68
|
+
/**
|
|
69
|
+
* Get all categories
|
|
70
|
+
*/
|
|
71
|
+
getCategories(): IntentCategory[];
|
|
72
|
+
/**
|
|
73
|
+
* Classify using LLM (for more nuanced understanding)
|
|
74
|
+
*/
|
|
75
|
+
private classifyWithLLM;
|
|
76
|
+
}
|
|
77
|
+
/**
|
|
78
|
+
* Create a default intent classifier
|
|
79
|
+
*/
|
|
80
|
+
export declare function createIntentClassifier(config?: IntentClassifierConfig): IntentClassifier;
|
|
81
|
+
//# sourceMappingURL=intent-classifier.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"intent-classifier.d.ts","sourceRoot":"","sources":["../../src/guardian/intent-classifier.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD,OAAO,KAAK,EAAE,eAAe,EAAE,oBAAoB,EAAa,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAEnG;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,iBAAiB,CAAC;IAC7B,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,MAAM,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC;CACrC;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,oCAAoC;IACpC,UAAU,CAAC,EAAE,cAAc,EAAE,CAAC;IAC9B,iCAAiC;IACjC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,oCAAoC;IACpC,SAAS,CAAC,EAAE,WAAW,CAAC;IACxB,mCAAmC;IACnC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,4BAA4B;IAC5B,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,8BAA8B;IAC9B,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AA0ID;;;;GAIG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,MAAM,CAAyB;IACvC,OAAO,CAAC,UAAU,CAAmB;gBAEzB,MAAM,GAAE,sBAA2B;IAU/C;;OAEG;IACG,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,EAAE,CAAC;IAuD7D;;OAEG;IACH,WAAW,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,eAAe,CAAC;IAO/F;;OAEG;IACG,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IAyCtD;;OAEG;IACH,WAAW,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI;IAI3C;;OAEG;IACH,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAIlC;;OAEG;IACH,aAAa,IAAI,cAAc,EAAE;IAIjC;;OAEG;YACW,eAAe;CAoC9B;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,GAAE,sBAA2B,GAAG,gBAAgB,CAE5F"}
|
|
@@ -0,0 +1,141 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Guardian Interceptor
|
|
3
|
+
*
|
|
4
|
+
* Wraps LLM clients to intercept and validate all inputs/outputs.
|
|
5
|
+
* Acts as middleware between the agent and the LLM.
|
|
6
|
+
*/
|
|
7
|
+
import type { GenerateOptions, GenerateResult, ModelClient } from '@artemiskit/core';
|
|
8
|
+
import type { GuardianEventHandler, GuardrailResult, InterceptedRequest, Violation } from './types';
|
|
9
|
+
/**
|
|
10
|
+
* Guardrail function signature
|
|
11
|
+
*/
|
|
12
|
+
export type GuardrailFn = (content: string, context?: Record<string, unknown>) => Promise<GuardrailResult>;
|
|
13
|
+
/**
|
|
14
|
+
* Interceptor configuration
|
|
15
|
+
*/
|
|
16
|
+
export interface InterceptorConfig {
|
|
17
|
+
/** Enable input validation */
|
|
18
|
+
validateInput?: boolean;
|
|
19
|
+
/** Enable output validation */
|
|
20
|
+
validateOutput?: boolean;
|
|
21
|
+
/** Input guardrails to run */
|
|
22
|
+
inputGuardrails?: GuardrailFn[];
|
|
23
|
+
/** Output guardrails to run */
|
|
24
|
+
outputGuardrails?: GuardrailFn[];
|
|
25
|
+
/** Whether to block on validation failure (flat boolean, see shouldBlockViolation for finer control) */
|
|
26
|
+
blockOnFailure?: boolean;
|
|
27
|
+
/**
|
|
28
|
+
* Callback to determine if a specific violation should cause blocking.
|
|
29
|
+
* Use this for mode-aware blocking (e.g., selective mode blocks only high-severity).
|
|
30
|
+
* If provided, this callback is used instead of flat blockOnFailure for per-violation decisions.
|
|
31
|
+
* The callback receives a violation and should return true if it should block.
|
|
32
|
+
*/
|
|
33
|
+
shouldBlockViolation?: (violation: Violation) => boolean;
|
|
34
|
+
/** Event handlers */
|
|
35
|
+
onEvent?: GuardianEventHandler;
|
|
36
|
+
/** Log violations */
|
|
37
|
+
logViolations?: boolean;
|
|
38
|
+
/**
|
|
39
|
+
* Callback to check if requests should be allowed (e.g., circuit breaker check).
|
|
40
|
+
* Called before each LLM request. Return false to block the request.
|
|
41
|
+
*/
|
|
42
|
+
shouldAllow?: () => {
|
|
43
|
+
allowed: boolean;
|
|
44
|
+
reason?: string;
|
|
45
|
+
};
|
|
46
|
+
}
|
|
47
|
+
/**
|
|
48
|
+
* Interceptor statistics
|
|
49
|
+
*/
|
|
50
|
+
export interface InterceptorStats {
|
|
51
|
+
totalRequests: number;
|
|
52
|
+
blockedRequests: number;
|
|
53
|
+
totalViolations: number;
|
|
54
|
+
averageLatencyMs: number;
|
|
55
|
+
inputViolations: number;
|
|
56
|
+
outputViolations: number;
|
|
57
|
+
}
|
|
58
|
+
/**
|
|
59
|
+
* Guardian Interceptor wraps a ModelClient to add validation
|
|
60
|
+
*/
|
|
61
|
+
export declare class GuardianInterceptor implements ModelClient {
|
|
62
|
+
readonly provider: string;
|
|
63
|
+
private client;
|
|
64
|
+
private config;
|
|
65
|
+
private stats;
|
|
66
|
+
private requestHistory;
|
|
67
|
+
constructor(client: ModelClient, config?: InterceptorConfig);
|
|
68
|
+
/**
|
|
69
|
+
* Generate with guardrail validation
|
|
70
|
+
*/
|
|
71
|
+
generate(options: GenerateOptions): Promise<GenerateResult>;
|
|
72
|
+
/**
|
|
73
|
+
* Get model capabilities (pass-through)
|
|
74
|
+
*/
|
|
75
|
+
capabilities(): Promise<import("@artemiskit/core").ModelCapabilities>;
|
|
76
|
+
/**
|
|
77
|
+
* Stream generation with guardrail validation
|
|
78
|
+
*
|
|
79
|
+
* IMPORTANT: Streaming is currently not supported by GuardianInterceptor.
|
|
80
|
+
* This method throws an error to prevent bypassing Guardian protections.
|
|
81
|
+
*
|
|
82
|
+
* Streaming validation is complex because:
|
|
83
|
+
* 1. Input validation must complete before streaming starts
|
|
84
|
+
* 2. Output validation requires the complete response
|
|
85
|
+
* 3. Circuit breaker must be checked per-request
|
|
86
|
+
*
|
|
87
|
+
* For protected LLM access, use the non-streaming `generate()` method.
|
|
88
|
+
* If you need streaming, use the underlying client directly (unprotected).
|
|
89
|
+
*
|
|
90
|
+
* @throws {Error} Always throws - streaming not supported in Guardian
|
|
91
|
+
*/
|
|
92
|
+
stream?(_options: GenerateOptions, _onChunk: (chunk: string) => void): AsyncIterable<string>;
|
|
93
|
+
/**
|
|
94
|
+
* Embed text (pass-through)
|
|
95
|
+
*/
|
|
96
|
+
embed?(text: string, model?: string): Promise<number[]>;
|
|
97
|
+
/**
|
|
98
|
+
* Close the client
|
|
99
|
+
*/
|
|
100
|
+
close?(): Promise<void>;
|
|
101
|
+
/**
|
|
102
|
+
* Get interceptor statistics
|
|
103
|
+
*/
|
|
104
|
+
getStats(): InterceptorStats;
|
|
105
|
+
/**
|
|
106
|
+
* Reset statistics
|
|
107
|
+
*/
|
|
108
|
+
resetStats(): void;
|
|
109
|
+
/**
|
|
110
|
+
* Get request history
|
|
111
|
+
*/
|
|
112
|
+
getRequestHistory(): InterceptedRequest[];
|
|
113
|
+
/**
|
|
114
|
+
* Clear request history
|
|
115
|
+
*/
|
|
116
|
+
clearHistory(): void;
|
|
117
|
+
/**
|
|
118
|
+
* Run guardrails and aggregate results
|
|
119
|
+
*/
|
|
120
|
+
private runGuardrails;
|
|
121
|
+
/**
|
|
122
|
+
* Extract text from prompt (string or messages array)
|
|
123
|
+
*/
|
|
124
|
+
private extractPromptText;
|
|
125
|
+
/**
|
|
126
|
+
* Emit an event to the handler
|
|
127
|
+
*/
|
|
128
|
+
private emitEvent;
|
|
129
|
+
}
|
|
130
|
+
/**
|
|
131
|
+
* Error thrown when a request is blocked by guardrails
|
|
132
|
+
*/
|
|
133
|
+
export declare class GuardianBlockedError extends Error {
|
|
134
|
+
readonly violations: Violation[];
|
|
135
|
+
constructor(message: string, violations: Violation[]);
|
|
136
|
+
}
|
|
137
|
+
/**
|
|
138
|
+
* Create an interceptor wrapping a model client
|
|
139
|
+
*/
|
|
140
|
+
export declare function createInterceptor(client: ModelClient, config?: InterceptorConfig): GuardianInterceptor;
|
|
141
|
+
//# sourceMappingURL=interceptor.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"interceptor.d.ts","sourceRoot":"","sources":["../../src/guardian/interceptor.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAErF,OAAO,KAAK,EAEV,oBAAoB,EACpB,eAAe,EACf,kBAAkB,EAElB,SAAS,EACV,MAAM,SAAS,CAAC;AAEjB;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,CACxB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC9B,OAAO,CAAC,eAAe,CAAC,CAAC;AAE9B;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,8BAA8B;IAC9B,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,+BAA+B;IAC/B,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,8BAA8B;IAC9B,eAAe,CAAC,EAAE,WAAW,EAAE,CAAC;IAChC,+BAA+B;IAC/B,gBAAgB,CAAC,EAAE,WAAW,EAAE,CAAC;IACjC,wGAAwG;IACxG,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;;;OAKG;IACH,oBAAoB,CAAC,EAAE,CAAC,SAAS,EAAE,SAAS,KAAK,OAAO,CAAC;IACzD,qBAAqB;IACrB,OAAO,CAAC,EAAE,oBAAoB,CAAC;IAC/B,qBAAqB;IACrB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC3D;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,gBAAgB,EAAE,MAAM,CAAC;IACzB,eAAe,EAAE,MAAM,CAAC;IACxB,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED;;GAEG;AACH,qBAAa,mBAAoB,YAAW,WAAW;IACrD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,MAAM,CAAoB;IAClC,OAAO,CAAC,KAAK,CAAmB;IAChC,OAAO,CAAC,cAAc,CAAkC;gBAE5C,MAAM,EAAE,WAAW,EAAE,MAAM,GAAE,iBAAsB;IAqB/D;;OAEG;IACG,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC;IAgLjE;;OAEG;IACG,YAAY;IAIlB;;;;;;;;;;;;;;;OAeG;IACH,MAAM,CAAC,CAAC,QAAQ,EAAE,eAAe,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,GAAG,aAAa,CAAC,MAAM,CAAC;IAY5F;;OAEG;IACG,KAAK,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAO7D;;OAEG;IACG,KAAK,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC;IAM7B;;OAEG;IACH,QAAQ,IAAI,gBAAgB;IAI5B;;OAEG;IACH,UAAU,IAAI,IAAI;IAWlB;;OAEG;IACH,iBAAiB,IAAI,kBAAkB,EAAE;IAIzC;;OAEG;IACH,YAAY,IAAI,IAAI;IAIpB;;OAEG;YACW,aAAa;IA8B3B;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAOzB;;OAEG;IACH,OAAO,CAAC,SAAS;CAkBlB;AAED;;GAEG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,QAAQ,CAAC,UAAU,EAAE,SAAS,EAAE,CAAC;gBAErB,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,EAAE;CAKrD;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,WAAW,EACnB,MAAM,GAAE,iBAAsB,GAC7B,mBAAmB,CAErB"}
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Policy Loader
|
|
3
|
+
*
|
|
4
|
+
* Loads and validates guardian policies from YAML files.
|
|
5
|
+
* Policies define the guardrails, rules, and configurations for the guardian.
|
|
6
|
+
*/
|
|
7
|
+
import type { GuardianPolicy, GuardrailType, PolicyRule } from './types';
|
|
8
|
+
/**
|
|
9
|
+
* Load a guardian policy from a YAML file
|
|
10
|
+
*/
|
|
11
|
+
export declare function loadPolicy(filePath: string): GuardianPolicy;
|
|
12
|
+
/**
|
|
13
|
+
* Parse a guardian policy from YAML string
|
|
14
|
+
*/
|
|
15
|
+
export declare function parsePolicy(yamlContent: string): GuardianPolicy;
|
|
16
|
+
/**
|
|
17
|
+
* Validate a guardian policy object
|
|
18
|
+
*/
|
|
19
|
+
export declare function validatePolicy(policy: unknown): GuardianPolicy;
|
|
20
|
+
/**
|
|
21
|
+
* Create a default guardian policy
|
|
22
|
+
*/
|
|
23
|
+
export declare function createDefaultPolicy(): GuardianPolicy;
|
|
24
|
+
/**
|
|
25
|
+
* Merge two policies (second overrides first)
|
|
26
|
+
*/
|
|
27
|
+
export declare function mergePolicies(base: GuardianPolicy, override: Partial<GuardianPolicy>): GuardianPolicy;
|
|
28
|
+
/**
|
|
29
|
+
* Get rules by type from a policy
|
|
30
|
+
*/
|
|
31
|
+
export declare function getRulesByType(policy: GuardianPolicy, type: GuardrailType): PolicyRule[];
|
|
32
|
+
/**
|
|
33
|
+
* Check if a rule is enabled in the policy
|
|
34
|
+
*/
|
|
35
|
+
export declare function isRuleEnabled(policy: GuardianPolicy, ruleId: string): boolean;
|
|
36
|
+
/**
|
|
37
|
+
* Error thrown when policy loading fails
|
|
38
|
+
*/
|
|
39
|
+
export declare class PolicyLoadError extends Error {
|
|
40
|
+
constructor(message: string);
|
|
41
|
+
}
|
|
42
|
+
/**
|
|
43
|
+
* Error thrown when policy validation fails
|
|
44
|
+
*/
|
|
45
|
+
export declare class PolicyValidationError extends Error {
|
|
46
|
+
constructor(message: string);
|
|
47
|
+
}
|
|
48
|
+
/**
|
|
49
|
+
* Generate a YAML policy template
|
|
50
|
+
*/
|
|
51
|
+
export declare function generatePolicyTemplate(): string;
|
|
52
|
+
//# sourceMappingURL=policy.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../../src/guardian/policy.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,KAAK,EAIV,cAAc,EACd,aAAa,EACb,UAAU,EAIX,MAAM,SAAS,CAAC;AA8FjB;;GAEG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,cAAc,CAgB3D;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,cAAc,CAiB/D;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,OAAO,GAAG,cAAc,CAS9D;AAED;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,cAAc,CA2FpD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,cAAc,EACpB,QAAQ,EAAE,OAAO,CAAC,cAAc,CAAC,GAChC,cAAc,CAkBhB;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,cAAc,EAAE,IAAI,EAAE,aAAa,GAAG,UAAU,EAAE,CAExF;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAG7E;AAMD;;GAEG;AACH,qBAAa,eAAgB,SAAQ,KAAK;gBAC5B,OAAO,EAAE,MAAM;CAI5B;AAED;;GAEG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;gBAClC,OAAO,EAAE,MAAM;CAI5B;AAMD;;GAEG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,CAyG/C"}
|