@artemiskit/sdk 0.3.0 → 0.3.3
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 +225 -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 +350 -0
- package/dist/builders/index.d.ts.map +1 -0
- package/dist/builders/index.js +398 -0
- package/dist/contracts/index.d.ts +253 -0
- package/dist/contracts/index.d.ts.map +1 -0
- package/dist/contracts/index.js +99 -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 +24847 -13653
- 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/jest.d.ts +46 -0
- package/dist/matchers/jest.d.ts.map +1 -0
- package/dist/matchers/vitest.d.ts +24 -0
- package/dist/matchers/vitest.d.ts.map +1 -0
- 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 +377 -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 +104 -0
- package/package.json +19 -4
- package/src/__tests__/builders.test.ts +445 -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 +307 -0
- package/src/artemiskit.ts +478 -5
- package/src/builders/index.ts +698 -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 +183 -0
- package/src/utils/index.ts +225 -0
- package/tsconfig.json +2 -1
package/src/guardian/guardian.ts
CHANGED
|
@@ -24,41 +24,122 @@ import {
|
|
|
24
24
|
type InterceptorConfig,
|
|
25
25
|
} from './interceptor';
|
|
26
26
|
import { createDefaultPolicy, loadPolicy, parsePolicy } from './policy';
|
|
27
|
+
import { type SemanticValidator, createSemanticValidator } from './semantic-validator';
|
|
27
28
|
import type {
|
|
28
29
|
ActionDefinition,
|
|
30
|
+
ContentValidationConfig,
|
|
29
31
|
GuardianEvent,
|
|
30
32
|
GuardianEventHandler,
|
|
31
33
|
GuardianMetrics,
|
|
32
34
|
GuardianMode,
|
|
35
|
+
GuardianModeCanonical,
|
|
36
|
+
GuardianModeLegacy,
|
|
33
37
|
GuardianPolicy,
|
|
34
38
|
InterceptedToolCall,
|
|
39
|
+
MultiTurnConfig,
|
|
35
40
|
Violation,
|
|
36
41
|
} from './types';
|
|
37
42
|
|
|
43
|
+
// =============================================================================
|
|
44
|
+
// Mode Normalization
|
|
45
|
+
// =============================================================================
|
|
46
|
+
|
|
47
|
+
/**
|
|
48
|
+
* Legacy to canonical mode mapping
|
|
49
|
+
*/
|
|
50
|
+
const LEGACY_MODE_MAP: Record<GuardianModeLegacy, GuardianModeCanonical> = {
|
|
51
|
+
testing: 'observe',
|
|
52
|
+
guardian: 'strict',
|
|
53
|
+
hybrid: 'selective',
|
|
54
|
+
};
|
|
55
|
+
|
|
56
|
+
/**
|
|
57
|
+
* Check if a mode is a legacy mode
|
|
58
|
+
*/
|
|
59
|
+
function isLegacyMode(mode: GuardianMode): mode is GuardianModeLegacy {
|
|
60
|
+
return mode in LEGACY_MODE_MAP;
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
/**
|
|
64
|
+
* Normalize Guardian mode to canonical form with deprecation warning
|
|
65
|
+
* @param mode - The mode to normalize
|
|
66
|
+
* @returns The canonical mode
|
|
67
|
+
*/
|
|
68
|
+
export function normalizeGuardianMode(mode: GuardianMode): GuardianModeCanonical {
|
|
69
|
+
if (isLegacyMode(mode)) {
|
|
70
|
+
const canonical = LEGACY_MODE_MAP[mode];
|
|
71
|
+
console.warn(
|
|
72
|
+
`[ArtemisKit Guardian] Mode '${mode}' is deprecated. Use '${canonical}' instead. Legacy modes will be removed in v1.0.0.`
|
|
73
|
+
);
|
|
74
|
+
return canonical;
|
|
75
|
+
}
|
|
76
|
+
return mode as GuardianModeCanonical;
|
|
77
|
+
}
|
|
78
|
+
|
|
38
79
|
/**
|
|
39
80
|
* Guardian configuration options
|
|
40
81
|
*/
|
|
41
82
|
export interface GuardianConfig {
|
|
42
|
-
/**
|
|
83
|
+
/**
|
|
84
|
+
* Operating mode
|
|
85
|
+
*
|
|
86
|
+
* Canonical modes (recommended):
|
|
87
|
+
* - 'observe': Log only, never block (for monitoring)
|
|
88
|
+
* - 'selective': Block high-confidence threats (threshold-based)
|
|
89
|
+
* - 'strict': Block all detected violations (maximum protection)
|
|
90
|
+
*
|
|
91
|
+
* Legacy modes (deprecated):
|
|
92
|
+
* - 'testing' → 'observe'
|
|
93
|
+
* - 'guardian' → 'strict'
|
|
94
|
+
* - 'hybrid' → 'selective'
|
|
95
|
+
*/
|
|
43
96
|
mode?: GuardianMode;
|
|
97
|
+
|
|
44
98
|
/** Policy file path or policy object */
|
|
45
99
|
policy?: string | GuardianPolicy;
|
|
46
|
-
|
|
100
|
+
|
|
101
|
+
/** LLM client for semantic validation and intent classification */
|
|
47
102
|
llmClient?: ModelClient;
|
|
103
|
+
|
|
48
104
|
/** Enable input validation */
|
|
49
105
|
validateInput?: boolean;
|
|
106
|
+
|
|
50
107
|
/** Enable output validation */
|
|
51
108
|
validateOutput?: boolean;
|
|
109
|
+
|
|
52
110
|
/** Block on validation failure */
|
|
53
111
|
blockOnFailure?: boolean;
|
|
54
|
-
|
|
112
|
+
|
|
113
|
+
/**
|
|
114
|
+
* Content validation strategy configuration
|
|
115
|
+
*
|
|
116
|
+
* @default { strategy: 'semantic', semanticThreshold: 0.9 }
|
|
117
|
+
*/
|
|
118
|
+
contentValidation?: ContentValidationConfig;
|
|
119
|
+
|
|
120
|
+
/** Custom guardrails configuration (pattern-based) */
|
|
55
121
|
guardrails?: GuardrailsConfig;
|
|
122
|
+
|
|
123
|
+
/**
|
|
124
|
+
* Multi-turn detection configuration
|
|
125
|
+
*
|
|
126
|
+
* Enable to detect attacks that span multiple messages:
|
|
127
|
+
* - Trust-building before sensitive requests
|
|
128
|
+
* - Escalating risk patterns
|
|
129
|
+
* - Context manipulation claims
|
|
130
|
+
* - Split payload attacks
|
|
131
|
+
*/
|
|
132
|
+
multiTurn?: MultiTurnConfig;
|
|
133
|
+
|
|
56
134
|
/** Custom action definitions */
|
|
57
135
|
allowedActions?: ActionDefinition[];
|
|
136
|
+
|
|
58
137
|
/** Event handler */
|
|
59
138
|
onEvent?: GuardianEventHandler;
|
|
139
|
+
|
|
60
140
|
/** Enable metrics collection */
|
|
61
141
|
collectMetrics?: boolean;
|
|
142
|
+
|
|
62
143
|
/** Enable logging */
|
|
63
144
|
enableLogging?: boolean;
|
|
64
145
|
}
|
|
@@ -74,19 +155,50 @@ export class Guardian {
|
|
|
74
155
|
private metricsCollector: MetricsCollector;
|
|
75
156
|
private actionValidator: ActionValidator;
|
|
76
157
|
private intentClassifier: IntentClassifier;
|
|
158
|
+
private semanticValidator?: SemanticValidator;
|
|
77
159
|
private inputGuardrails: GuardrailFn[];
|
|
78
160
|
private outputGuardrails: GuardrailFn[];
|
|
79
161
|
private eventHandlers: GuardianEventHandler[] = [];
|
|
80
162
|
|
|
163
|
+
/** The normalized (canonical) mode after processing legacy modes */
|
|
164
|
+
private normalizedMode: GuardianModeCanonical;
|
|
165
|
+
|
|
81
166
|
constructor(config: GuardianConfig = {}) {
|
|
167
|
+
// Normalize mode with deprecation warning for legacy modes
|
|
168
|
+
const inputMode = config.mode ?? 'strict';
|
|
169
|
+
this.normalizedMode = normalizeGuardianMode(inputMode);
|
|
170
|
+
|
|
171
|
+
// Default content validation with deep merge support
|
|
172
|
+
const defaultContentValidation: ContentValidationConfig = {
|
|
173
|
+
strategy: 'semantic',
|
|
174
|
+
semanticThreshold: 0.9,
|
|
175
|
+
categories: ['prompt_injection', 'jailbreak', 'pii_disclosure'],
|
|
176
|
+
patterns: { enabled: true, caseInsensitive: true },
|
|
177
|
+
};
|
|
178
|
+
|
|
179
|
+
// Deep merge contentValidation to preserve nested defaults
|
|
180
|
+
const mergedContentValidation: ContentValidationConfig = config.contentValidation
|
|
181
|
+
? {
|
|
182
|
+
...defaultContentValidation,
|
|
183
|
+
...config.contentValidation,
|
|
184
|
+
// Deep merge patterns if both exist
|
|
185
|
+
patterns: {
|
|
186
|
+
...defaultContentValidation.patterns,
|
|
187
|
+
...config.contentValidation.patterns,
|
|
188
|
+
},
|
|
189
|
+
}
|
|
190
|
+
: defaultContentValidation;
|
|
191
|
+
|
|
82
192
|
this.config = {
|
|
83
|
-
mode:
|
|
193
|
+
mode: inputMode, // Keep original for backwards compatibility
|
|
84
194
|
validateInput: true,
|
|
85
195
|
validateOutput: true,
|
|
86
196
|
blockOnFailure: true,
|
|
87
197
|
collectMetrics: true,
|
|
88
198
|
enableLogging: true,
|
|
89
199
|
...config,
|
|
200
|
+
// Apply deep-merged contentValidation after spreading config
|
|
201
|
+
contentValidation: mergedContentValidation,
|
|
90
202
|
};
|
|
91
203
|
|
|
92
204
|
// Load or create policy
|
|
@@ -130,6 +242,31 @@ export class Guardian {
|
|
|
130
242
|
// Add intent classifier as guardrail
|
|
131
243
|
this.inputGuardrails.push(this.intentClassifier.asGuardrail());
|
|
132
244
|
|
|
245
|
+
// Initialize semantic validator if strategy is 'semantic' or 'hybrid' and LLM client is provided
|
|
246
|
+
const validationStrategy = this.config.contentValidation?.strategy ?? 'semantic';
|
|
247
|
+
const requiresLlmClient = validationStrategy === 'semantic' || validationStrategy === 'hybrid';
|
|
248
|
+
const shouldUseSemanticValidation = requiresLlmClient && config.llmClient;
|
|
249
|
+
|
|
250
|
+
// Warn when semantic validation is configured but no LLM client is provided
|
|
251
|
+
if (requiresLlmClient && !config.llmClient) {
|
|
252
|
+
console.warn(
|
|
253
|
+
`[ArtemisKit Guardian] contentValidation.strategy is "${validationStrategy}" but no llmClient was provided. Semantic validation is disabled. Pass an llmClient to GuardianConfig to enable LLM-based content validation.`
|
|
254
|
+
);
|
|
255
|
+
}
|
|
256
|
+
|
|
257
|
+
if (shouldUseSemanticValidation && config.llmClient) {
|
|
258
|
+
this.semanticValidator = createSemanticValidator(
|
|
259
|
+
config.llmClient,
|
|
260
|
+
this.config.contentValidation
|
|
261
|
+
);
|
|
262
|
+
|
|
263
|
+
// Add semantic validator as input guardrail
|
|
264
|
+
this.inputGuardrails.push(this.semanticValidator.asGuardrail('input'));
|
|
265
|
+
|
|
266
|
+
// Add semantic validator as output guardrail
|
|
267
|
+
this.outputGuardrails.push(this.semanticValidator.asGuardrail('output'));
|
|
268
|
+
}
|
|
269
|
+
|
|
133
270
|
// Register event handler
|
|
134
271
|
if (config.onEvent) {
|
|
135
272
|
this.eventHandlers.push(config.onEvent);
|
|
@@ -155,38 +292,110 @@ export class Guardian {
|
|
|
155
292
|
|
|
156
293
|
/**
|
|
157
294
|
* Wrap a model client with guardian protection
|
|
295
|
+
*
|
|
296
|
+
* Note: Checks circuit breaker on each LLM request via the shouldAllow callback.
|
|
297
|
+
* When the circuit is open due to detected attack patterns, all LLM requests are blocked.
|
|
158
298
|
*/
|
|
159
299
|
protect(client: ModelClient): GuardianInterceptor {
|
|
300
|
+
// Check circuit breaker at creation time for immediate feedback
|
|
301
|
+
if (this.circuitBreaker.isOpen()) {
|
|
302
|
+
throw new GuardianBlockedError(
|
|
303
|
+
'Circuit breaker is open - too many violations detected. LLM requests are temporarily blocked.',
|
|
304
|
+
[]
|
|
305
|
+
);
|
|
306
|
+
}
|
|
307
|
+
|
|
308
|
+
// Derive blockOnFailure from normalizedMode to respect observe/selective/strict semantics
|
|
309
|
+
// In observe mode, never block (log only). In selective/strict, use config setting (default true).
|
|
310
|
+
const shouldBlockOnFailure =
|
|
311
|
+
this.normalizedMode !== 'observe' && (this.config.blockOnFailure ?? true);
|
|
312
|
+
|
|
313
|
+
// Track violations per request for metrics (keyed by requestId)
|
|
314
|
+
const pendingViolations = new Map<string, Violation[]>();
|
|
315
|
+
|
|
160
316
|
const interceptorConfig: InterceptorConfig = {
|
|
161
317
|
validateInput: this.config.validateInput,
|
|
162
318
|
validateOutput: this.config.validateOutput,
|
|
163
319
|
inputGuardrails: this.inputGuardrails,
|
|
164
320
|
outputGuardrails: this.outputGuardrails,
|
|
165
|
-
blockOnFailure:
|
|
321
|
+
blockOnFailure: shouldBlockOnFailure,
|
|
322
|
+
// Pass the Guardian's shouldBlock method for mode-aware per-violation decisions
|
|
323
|
+
// This ensures the interceptor respects observe/selective/strict semantics
|
|
324
|
+
shouldBlockViolation: (v) => this.shouldBlock(v),
|
|
166
325
|
logViolations: this.config.enableLogging,
|
|
326
|
+
// Per-request circuit breaker check
|
|
327
|
+
shouldAllow: () => {
|
|
328
|
+
if (this.circuitBreaker.isOpen()) {
|
|
329
|
+
return {
|
|
330
|
+
allowed: false,
|
|
331
|
+
reason: 'Circuit breaker is open - too many violations detected',
|
|
332
|
+
};
|
|
333
|
+
}
|
|
334
|
+
return { allowed: true };
|
|
335
|
+
},
|
|
167
336
|
onEvent: (event) => {
|
|
168
|
-
|
|
169
|
-
|
|
337
|
+
const requestId = event.data.requestId as string | undefined;
|
|
338
|
+
|
|
339
|
+
if (event.type === 'violation_detected') {
|
|
340
|
+
const violation = event.data.violation as Violation;
|
|
341
|
+
this.circuitBreaker.recordViolation(violation);
|
|
342
|
+
|
|
343
|
+
// Track violations for this request
|
|
344
|
+
if (requestId) {
|
|
345
|
+
const existing = pendingViolations.get(requestId) ?? [];
|
|
346
|
+
existing.push(violation);
|
|
347
|
+
pendingViolations.set(requestId, existing);
|
|
348
|
+
}
|
|
349
|
+
} else if (event.type === 'request_complete') {
|
|
170
350
|
const latencyMs = event.data.latencyMs as number;
|
|
351
|
+
// Retrieve any violations that were detected but not blocked (warn path)
|
|
352
|
+
const violations = requestId ? (pendingViolations.get(requestId) ?? []) : [];
|
|
353
|
+
const warned = violations.length > 0;
|
|
354
|
+
|
|
171
355
|
this.metricsCollector.recordRequest({
|
|
172
356
|
blocked: false,
|
|
173
|
-
warned
|
|
357
|
+
warned,
|
|
174
358
|
latencyMs,
|
|
175
|
-
violations
|
|
359
|
+
violations,
|
|
176
360
|
});
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
361
|
+
|
|
362
|
+
// Record success only if no violations occurred
|
|
363
|
+
if (violations.length === 0) {
|
|
364
|
+
this.circuitBreaker.recordSuccess();
|
|
365
|
+
}
|
|
366
|
+
|
|
367
|
+
// Clean up
|
|
368
|
+
if (requestId) {
|
|
369
|
+
pendingViolations.delete(requestId);
|
|
370
|
+
}
|
|
181
371
|
} else if (event.type === 'request_blocked') {
|
|
182
|
-
const
|
|
372
|
+
const blockingViolations = event.data.violations as Violation[];
|
|
183
373
|
const latencyMs = (event.data.latencyMs as number) ?? 0;
|
|
374
|
+
|
|
375
|
+
// Combine all violations: previously detected (e.g., input violations that didn't block)
|
|
376
|
+
// plus the current blocking violations (e.g., output violations)
|
|
377
|
+
// This ensures metrics accurately reflect ALL violations on a request, not just the
|
|
378
|
+
// ones from the blocking phase
|
|
379
|
+
const previousViolations = requestId ? (pendingViolations.get(requestId) ?? []) : [];
|
|
380
|
+
|
|
381
|
+
// Deduplicate by violation id to avoid double-counting violations already in pendingViolations
|
|
382
|
+
const allViolationIds = new Set(previousViolations.map((v) => v.id));
|
|
383
|
+
const newBlockingViolations = blockingViolations.filter(
|
|
384
|
+
(v) => !allViolationIds.has(v.id)
|
|
385
|
+
);
|
|
386
|
+
const allViolations = [...previousViolations, ...newBlockingViolations];
|
|
387
|
+
|
|
184
388
|
this.metricsCollector.recordRequest({
|
|
185
389
|
blocked: true,
|
|
186
390
|
warned: false,
|
|
187
391
|
latencyMs,
|
|
188
|
-
violations,
|
|
392
|
+
violations: allViolations,
|
|
189
393
|
});
|
|
394
|
+
|
|
395
|
+
// Clean up
|
|
396
|
+
if (requestId) {
|
|
397
|
+
pendingViolations.delete(requestId);
|
|
398
|
+
}
|
|
190
399
|
}
|
|
191
400
|
|
|
192
401
|
// Forward to guardian event handlers
|
|
@@ -217,7 +426,7 @@ export class Guardian {
|
|
|
217
426
|
violations: [
|
|
218
427
|
{
|
|
219
428
|
id: nanoid(),
|
|
220
|
-
type: '
|
|
429
|
+
type: 'circuit_breaker',
|
|
221
430
|
severity: 'high',
|
|
222
431
|
message: 'Circuit breaker is open - too many violations',
|
|
223
432
|
timestamp: new Date(),
|
|
@@ -304,13 +513,31 @@ export class Guardian {
|
|
|
304
513
|
}
|
|
305
514
|
}
|
|
306
515
|
|
|
307
|
-
// Record violations
|
|
516
|
+
// Record violations in circuit breaker
|
|
308
517
|
for (const violation of violations) {
|
|
309
518
|
this.circuitBreaker.recordViolation(violation);
|
|
310
519
|
}
|
|
311
520
|
|
|
521
|
+
// Apply mode-aware blocking logic
|
|
522
|
+
const shouldBlockAny = violations.some((v) => v.blocked && this.shouldBlock(v));
|
|
523
|
+
const blocked = violations.length > 0 && shouldBlockAny;
|
|
524
|
+
const warned = violations.length > 0 && !shouldBlockAny;
|
|
525
|
+
|
|
526
|
+
// Record metrics for standalone validateInput calls
|
|
527
|
+
this.metricsCollector.recordRequest({
|
|
528
|
+
blocked,
|
|
529
|
+
warned,
|
|
530
|
+
latencyMs: 0, // Latency tracking not available for standalone calls
|
|
531
|
+
violations,
|
|
532
|
+
});
|
|
533
|
+
|
|
534
|
+
// Record success only when no violations (violations already recorded in loop above)
|
|
535
|
+
if (violations.length === 0) {
|
|
536
|
+
this.circuitBreaker.recordSuccess();
|
|
537
|
+
}
|
|
538
|
+
|
|
312
539
|
return {
|
|
313
|
-
valid:
|
|
540
|
+
valid: !blocked,
|
|
314
541
|
violations,
|
|
315
542
|
transformedContent,
|
|
316
543
|
};
|
|
@@ -341,13 +568,31 @@ export class Guardian {
|
|
|
341
568
|
}
|
|
342
569
|
}
|
|
343
570
|
|
|
344
|
-
// Record violations
|
|
571
|
+
// Record violations in circuit breaker
|
|
345
572
|
for (const violation of violations) {
|
|
346
573
|
this.circuitBreaker.recordViolation(violation);
|
|
347
574
|
}
|
|
348
575
|
|
|
576
|
+
// Apply mode-aware blocking logic
|
|
577
|
+
const shouldBlockAny = violations.some((v) => v.blocked && this.shouldBlock(v));
|
|
578
|
+
const blocked = violations.length > 0 && shouldBlockAny;
|
|
579
|
+
const warned = violations.length > 0 && !shouldBlockAny;
|
|
580
|
+
|
|
581
|
+
// Record metrics for standalone validateOutput calls
|
|
582
|
+
this.metricsCollector.recordRequest({
|
|
583
|
+
blocked,
|
|
584
|
+
warned,
|
|
585
|
+
latencyMs: 0, // Latency tracking not available for standalone calls
|
|
586
|
+
violations,
|
|
587
|
+
});
|
|
588
|
+
|
|
589
|
+
// Record success only when no violations (violations already recorded in loop above)
|
|
590
|
+
if (violations.length === 0) {
|
|
591
|
+
this.circuitBreaker.recordSuccess();
|
|
592
|
+
}
|
|
593
|
+
|
|
349
594
|
return {
|
|
350
|
-
valid:
|
|
595
|
+
valid: !blocked,
|
|
351
596
|
violations,
|
|
352
597
|
transformedContent,
|
|
353
598
|
};
|
|
@@ -389,6 +634,48 @@ export class Guardian {
|
|
|
389
634
|
return this.policy;
|
|
390
635
|
}
|
|
391
636
|
|
|
637
|
+
/**
|
|
638
|
+
* Get the normalized (canonical) operating mode
|
|
639
|
+
*
|
|
640
|
+
* This returns the canonical mode even if a legacy mode was configured.
|
|
641
|
+
*/
|
|
642
|
+
getMode(): GuardianModeCanonical {
|
|
643
|
+
return this.normalizedMode;
|
|
644
|
+
}
|
|
645
|
+
|
|
646
|
+
/**
|
|
647
|
+
* Check if Guardian should block based on mode and violation severity
|
|
648
|
+
*
|
|
649
|
+
* - observe: Never blocks
|
|
650
|
+
* - selective: Blocks high-confidence/high-severity only
|
|
651
|
+
* - strict: Blocks all violations
|
|
652
|
+
*/
|
|
653
|
+
shouldBlock(violation: Violation): boolean {
|
|
654
|
+
switch (this.normalizedMode) {
|
|
655
|
+
case 'observe':
|
|
656
|
+
return false;
|
|
657
|
+
case 'selective':
|
|
658
|
+
// Block only critical or high severity violations
|
|
659
|
+
return violation.severity === 'critical' || violation.severity === 'high';
|
|
660
|
+
case 'strict':
|
|
661
|
+
return true;
|
|
662
|
+
default:
|
|
663
|
+
return true;
|
|
664
|
+
}
|
|
665
|
+
}
|
|
666
|
+
|
|
667
|
+
/**
|
|
668
|
+
* Get the content validation configuration
|
|
669
|
+
*/
|
|
670
|
+
getContentValidationConfig(): ContentValidationConfig {
|
|
671
|
+
return (
|
|
672
|
+
this.config.contentValidation ?? {
|
|
673
|
+
strategy: 'semantic',
|
|
674
|
+
semanticThreshold: 0.9,
|
|
675
|
+
}
|
|
676
|
+
);
|
|
677
|
+
}
|
|
678
|
+
|
|
392
679
|
/**
|
|
393
680
|
* Update policy at runtime
|
|
394
681
|
*/
|
|
@@ -19,10 +19,100 @@ import type {
|
|
|
19
19
|
PIIDetection,
|
|
20
20
|
PIILocation,
|
|
21
21
|
PIIType,
|
|
22
|
+
PatternCategory,
|
|
23
|
+
PatternConfig,
|
|
22
24
|
Violation,
|
|
23
25
|
ViolationSeverity,
|
|
24
26
|
} from './types';
|
|
25
27
|
|
|
28
|
+
// =============================================================================
|
|
29
|
+
// Pattern Matching Utilities
|
|
30
|
+
// =============================================================================
|
|
31
|
+
|
|
32
|
+
/**
|
|
33
|
+
* Options for custom pattern matching
|
|
34
|
+
*/
|
|
35
|
+
export interface CustomPatternOptions {
|
|
36
|
+
/** Case-insensitive matching (default: true) */
|
|
37
|
+
caseInsensitive?: boolean;
|
|
38
|
+
/** Pattern category for categorization */
|
|
39
|
+
category?: PatternCategory;
|
|
40
|
+
/** Severity level for matches */
|
|
41
|
+
severity?: ViolationSeverity;
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
/**
|
|
45
|
+
* Match a pattern against content with options
|
|
46
|
+
*/
|
|
47
|
+
export function matchPattern(
|
|
48
|
+
content: string,
|
|
49
|
+
pattern: string | RegExp,
|
|
50
|
+
options: CustomPatternOptions = {}
|
|
51
|
+
): { matched: boolean; match?: RegExpMatchArray } {
|
|
52
|
+
const { caseInsensitive = true } = options;
|
|
53
|
+
|
|
54
|
+
if (typeof pattern === 'string') {
|
|
55
|
+
// For string patterns, convert to regex with optional case insensitivity
|
|
56
|
+
const flags = caseInsensitive ? 'gi' : 'g';
|
|
57
|
+
const escapedPattern = pattern.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
|
|
58
|
+
const regex = new RegExp(escapedPattern, flags);
|
|
59
|
+
const match = content.match(regex);
|
|
60
|
+
return { matched: !!match, match: match ?? undefined };
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
// For RegExp patterns, apply if case insensitivity is requested and not already set
|
|
64
|
+
if (caseInsensitive && !pattern.flags.includes('i')) {
|
|
65
|
+
const newRegex = new RegExp(pattern.source, `${pattern.flags}i`);
|
|
66
|
+
const match = content.match(newRegex);
|
|
67
|
+
return { matched: !!match, match: match ?? undefined };
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
const match = content.match(pattern);
|
|
71
|
+
return { matched: !!match, match: match ?? undefined };
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
/**
|
|
75
|
+
* Create a custom pattern guardrail
|
|
76
|
+
*/
|
|
77
|
+
export function createCustomPatternGuardrail(
|
|
78
|
+
patterns: Array<string | RegExp>,
|
|
79
|
+
options: CustomPatternOptions = {}
|
|
80
|
+
): (content: string, context?: Record<string, unknown>) => Promise<GuardrailResult> {
|
|
81
|
+
const { caseInsensitive = true, category = 'injection', severity = 'high' } = options;
|
|
82
|
+
|
|
83
|
+
return async (content: string) => {
|
|
84
|
+
const violations: Violation[] = [];
|
|
85
|
+
|
|
86
|
+
for (const pattern of patterns) {
|
|
87
|
+
const result = matchPattern(content, pattern, { caseInsensitive });
|
|
88
|
+
|
|
89
|
+
if (result.matched && result.match) {
|
|
90
|
+
violations.push({
|
|
91
|
+
id: nanoid(),
|
|
92
|
+
type: 'injection_detection',
|
|
93
|
+
severity,
|
|
94
|
+
message: `Custom pattern match detected: ${category}`,
|
|
95
|
+
details: {
|
|
96
|
+
pattern: typeof pattern === 'string' ? pattern : pattern.source,
|
|
97
|
+
category,
|
|
98
|
+
matchedText: result.match[0],
|
|
99
|
+
},
|
|
100
|
+
timestamp: new Date(),
|
|
101
|
+
action: 'block',
|
|
102
|
+
blocked: true,
|
|
103
|
+
});
|
|
104
|
+
break; // One match is enough
|
|
105
|
+
}
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
if (violations.length > 0) {
|
|
109
|
+
return { passed: false, violations };
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
return { passed: true, violations: [] };
|
|
113
|
+
};
|
|
114
|
+
}
|
|
115
|
+
|
|
26
116
|
// =============================================================================
|
|
27
117
|
// Injection Detection
|
|
28
118
|
// =============================================================================
|
|
@@ -141,6 +231,7 @@ export function detectInjection(text: string): InjectionDetection {
|
|
|
141
231
|
return {
|
|
142
232
|
detected: true,
|
|
143
233
|
type,
|
|
234
|
+
severity, // Include actual severity from pattern definition
|
|
144
235
|
confidence: severity === 'critical' ? 0.95 : severity === 'high' ? 0.85 : 0.7,
|
|
145
236
|
pattern: pattern.source,
|
|
146
237
|
location:
|
|
@@ -175,7 +266,8 @@ export function createInjectionGuardrail(): (
|
|
|
175
266
|
{
|
|
176
267
|
id: nanoid(),
|
|
177
268
|
type: 'injection_detection',
|
|
178
|
-
severity
|
|
269
|
+
// Use detected severity from pattern definition, fallback to critical for safety
|
|
270
|
+
severity: detection.severity ?? 'critical',
|
|
179
271
|
message: `Detected ${detection.type?.replace(/_/g, ' ')} attempt`,
|
|
180
272
|
details: {
|
|
181
273
|
type: detection.type,
|
|
@@ -487,21 +579,44 @@ export function createContentFilterGuardrail(
|
|
|
487
579
|
export interface GuardrailsConfig {
|
|
488
580
|
/** Enable injection detection */
|
|
489
581
|
injectionDetection?: boolean;
|
|
582
|
+
|
|
490
583
|
/** Enable PII detection */
|
|
491
584
|
piiDetection?: boolean;
|
|
585
|
+
|
|
492
586
|
/** PII detection options */
|
|
493
587
|
piiOptions?: {
|
|
494
588
|
redact?: boolean;
|
|
495
589
|
block?: boolean;
|
|
496
590
|
allowedTypes?: PIIType[];
|
|
497
591
|
};
|
|
592
|
+
|
|
498
593
|
/** Enable content filtering */
|
|
499
594
|
contentFilter?: boolean;
|
|
595
|
+
|
|
500
596
|
/** Content filter options */
|
|
501
597
|
contentFilterOptions?: {
|
|
502
598
|
blockedCategories?: ContentCategory[];
|
|
503
599
|
warnCategories?: ContentCategory[];
|
|
504
600
|
};
|
|
601
|
+
|
|
602
|
+
/**
|
|
603
|
+
* Pattern matching configuration
|
|
604
|
+
* Controls how custom patterns are matched
|
|
605
|
+
*/
|
|
606
|
+
patternConfig?: PatternConfig;
|
|
607
|
+
|
|
608
|
+
/**
|
|
609
|
+
* Custom patterns to add to injection detection
|
|
610
|
+
* These are checked in addition to built-in patterns
|
|
611
|
+
*/
|
|
612
|
+
customPatterns?: Array<string | RegExp>;
|
|
613
|
+
|
|
614
|
+
/**
|
|
615
|
+
* Pattern categories to enable (default: all)
|
|
616
|
+
* Use this to selectively enable pattern categories
|
|
617
|
+
*/
|
|
618
|
+
enabledPatternCategories?: PatternCategory[];
|
|
619
|
+
|
|
505
620
|
/** Custom guardrails */
|
|
506
621
|
custom?: Array<(content: string, context?: Record<string, unknown>) => Promise<GuardrailResult>>;
|
|
507
622
|
}
|
|
@@ -516,18 +631,45 @@ export function createGuardrails(
|
|
|
516
631
|
(content: string, context?: Record<string, unknown>) => Promise<GuardrailResult>
|
|
517
632
|
> = [];
|
|
518
633
|
|
|
634
|
+
// Add injection detection if enabled
|
|
519
635
|
if (config.injectionDetection !== false) {
|
|
520
636
|
guardrails.push(createInjectionGuardrail());
|
|
521
637
|
}
|
|
522
638
|
|
|
639
|
+
// Add PII detection if enabled
|
|
523
640
|
if (config.piiDetection !== false) {
|
|
524
641
|
guardrails.push(createPIIGuardrail(config.piiOptions));
|
|
525
642
|
}
|
|
526
643
|
|
|
644
|
+
// Add content filtering if enabled
|
|
527
645
|
if (config.contentFilter !== false) {
|
|
528
646
|
guardrails.push(createContentFilterGuardrail(config.contentFilterOptions));
|
|
529
647
|
}
|
|
530
648
|
|
|
649
|
+
// Add custom patterns guardrail if patterns are provided
|
|
650
|
+
if (config.customPatterns && config.customPatterns.length > 0) {
|
|
651
|
+
// Determine category: single category uses that, no categories defaults to 'injection'
|
|
652
|
+
// Multiple categories are not supported - use createCustomPatternGuardrail directly
|
|
653
|
+
// for per-category pattern guardrails
|
|
654
|
+
const categories = config.patternConfig?.categories ?? [];
|
|
655
|
+
|
|
656
|
+
if (categories.length > 1) {
|
|
657
|
+
throw new Error(
|
|
658
|
+
`Cannot assign multiple categories (${categories.join(', ')}) to a flat pattern array. Custom patterns can only have a single category. To create patterns with different categories, use createCustomPatternGuardrail() multiple times with different options, or add them via the config.custom array.`
|
|
659
|
+
);
|
|
660
|
+
}
|
|
661
|
+
|
|
662
|
+
const category: PatternCategory = categories[0] ?? 'injection';
|
|
663
|
+
|
|
664
|
+
const patternOptions: CustomPatternOptions = {
|
|
665
|
+
caseInsensitive: config.patternConfig?.caseInsensitive ?? true,
|
|
666
|
+
category,
|
|
667
|
+
severity: 'high',
|
|
668
|
+
};
|
|
669
|
+
guardrails.push(createCustomPatternGuardrail(config.customPatterns, patternOptions));
|
|
670
|
+
}
|
|
671
|
+
|
|
672
|
+
// Add custom guardrails
|
|
531
673
|
if (config.custom) {
|
|
532
674
|
guardrails.push(...config.custom);
|
|
533
675
|
}
|