@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.
Files changed (78) hide show
  1. package/CHANGELOG.md +229 -0
  2. package/README.md +44 -1
  3. package/dist/artemiskit.d.ts +149 -0
  4. package/dist/artemiskit.d.ts.map +1 -0
  5. package/dist/builders/index.d.ts +352 -0
  6. package/dist/builders/index.d.ts.map +1 -0
  7. package/dist/builders/index.js +354 -0
  8. package/dist/contracts/index.d.ts +253 -0
  9. package/dist/contracts/index.d.ts.map +1 -0
  10. package/dist/contracts/index.js +53 -0
  11. package/dist/guardian/action-validator.d.ts +92 -0
  12. package/dist/guardian/action-validator.d.ts.map +1 -0
  13. package/dist/guardian/circuit-breaker.d.ts +211 -0
  14. package/dist/guardian/circuit-breaker.d.ts.map +1 -0
  15. package/dist/guardian/guardian.d.ts +213 -0
  16. package/dist/guardian/guardian.d.ts.map +1 -0
  17. package/dist/guardian/guardrails.d.ts +107 -0
  18. package/dist/guardian/guardrails.d.ts.map +1 -0
  19. package/dist/guardian/index.d.ts +35 -0
  20. package/dist/guardian/index.d.ts.map +1 -0
  21. package/dist/guardian/intent-classifier.d.ts +81 -0
  22. package/dist/guardian/intent-classifier.d.ts.map +1 -0
  23. package/dist/guardian/interceptor.d.ts +141 -0
  24. package/dist/guardian/interceptor.d.ts.map +1 -0
  25. package/dist/guardian/policy.d.ts +52 -0
  26. package/dist/guardian/policy.d.ts.map +1 -0
  27. package/dist/guardian/semantic-validator.d.ts +61 -0
  28. package/dist/guardian/semantic-validator.d.ts.map +1 -0
  29. package/dist/guardian/types.d.ts +653 -0
  30. package/dist/guardian/types.d.ts.map +1 -0
  31. package/dist/index.d.ts +23 -0
  32. package/dist/index.d.ts.map +1 -0
  33. package/dist/index.js +44918 -28644
  34. package/dist/matchers/core.d.ts +81 -0
  35. package/dist/matchers/core.d.ts.map +1 -0
  36. package/dist/matchers/index.d.ts +6 -0
  37. package/dist/matchers/index.d.ts.map +1 -0
  38. package/dist/matchers/index.js +13 -59
  39. package/dist/matchers/jest.d.ts +46 -0
  40. package/dist/matchers/jest.d.ts.map +1 -0
  41. package/dist/matchers/jest.js +0 -46
  42. package/dist/matchers/vitest.d.ts +24 -0
  43. package/dist/matchers/vitest.d.ts.map +1 -0
  44. package/dist/matchers/vitest.js +0 -46
  45. package/dist/types-only.d.ts +31 -0
  46. package/dist/types-only.d.ts.map +1 -0
  47. package/dist/types-only.js +1 -0
  48. package/dist/types.d.ts +379 -0
  49. package/dist/types.d.ts.map +1 -0
  50. package/dist/utils/index.d.ts +112 -0
  51. package/dist/utils/index.d.ts.map +1 -0
  52. package/dist/utils/index.js +58 -0
  53. package/package.json +19 -4
  54. package/src/__tests__/builders.test.ts +450 -0
  55. package/src/__tests__/circuit-breaker.test.ts +704 -0
  56. package/src/__tests__/compare.test.ts +469 -0
  57. package/src/__tests__/contracts.test.ts +354 -0
  58. package/src/__tests__/guardian-modes.test.ts +215 -0
  59. package/src/__tests__/guardrails.test.ts +404 -0
  60. package/src/__tests__/semantic-validator.test.ts +421 -0
  61. package/src/__tests__/utils.test.ts +324 -0
  62. package/src/__tests__/validate.test.ts +310 -0
  63. package/src/artemiskit.ts +479 -5
  64. package/src/builders/index.ts +700 -0
  65. package/src/contracts/index.ts +357 -0
  66. package/src/guardian/circuit-breaker.ts +74 -28
  67. package/src/guardian/guardian.ts +307 -20
  68. package/src/guardian/guardrails.ts +143 -1
  69. package/src/guardian/index.ts +35 -1
  70. package/src/guardian/interceptor.ts +87 -11
  71. package/src/guardian/semantic-validator.ts +399 -0
  72. package/src/guardian/types.ts +413 -2
  73. package/src/index.ts +258 -14
  74. package/src/types-only.ts +276 -0
  75. package/src/types.ts +186 -0
  76. package/src/utils/index.ts +225 -0
  77. package/tsconfig.json +2 -1
  78. package/adapters/openai/dist/index.js +0 -5625
@@ -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
- /** Operating mode */
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
- /** LLM client for intent classification */
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
- /** Custom guardrails configuration */
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: 'guardian',
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: this.config.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
- // Record metrics
169
- if (event.type === 'request_complete') {
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: false,
357
+ warned,
174
358
  latencyMs,
175
- violations: [],
359
+ violations,
176
360
  });
177
- this.circuitBreaker.recordSuccess();
178
- } else if (event.type === 'violation_detected') {
179
- const violation = event.data.violation as Violation;
180
- this.circuitBreaker.recordViolation(violation);
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 violations = event.data.violations as Violation[];
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: 'rate_limit',
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: violations.length === 0 || !violations.some((v) => v.blocked),
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: violations.length === 0 || !violations.some((v) => v.blocked),
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: 'critical',
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
  }