@directive-run/ai 1.18.0 → 1.19.1
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/dist/chunk-2C3R77ZW.cjs +16 -0
- package/dist/chunk-2C3R77ZW.cjs.map +1 -0
- package/dist/chunk-ARYO7BLK.js +16 -0
- package/dist/chunk-ARYO7BLK.js.map +1 -0
- package/dist/chunk-MPAX6C5V.cjs +4 -0
- package/dist/chunk-MPAX6C5V.cjs.map +1 -0
- package/dist/chunk-WERHNNUD.js +4 -0
- package/dist/chunk-WERHNNUD.js.map +1 -0
- package/dist/guardrails.cjs +1 -1
- package/dist/guardrails.d.cts +186 -2
- package/dist/guardrails.d.ts +186 -2
- package/dist/guardrails.js +1 -1
- package/dist/index.cjs +11 -11
- package/dist/index.d.cts +2 -2
- package/dist/index.d.ts +2 -2
- package/dist/index.js +11 -11
- package/dist/index.js.map +1 -1
- package/dist/multi-agent.d.cts +2 -2
- package/dist/multi-agent.d.ts +2 -2
- package/dist/{orchestrator-types-Dlfcvdxw.d.cts → orchestrator-types-C-sgbBQX.d.cts} +19 -17
- package/dist/{orchestrator-types-D5cFRt3s.d.ts → orchestrator-types-CX1PqpKR.d.ts} +19 -17
- package/dist/testing.cjs +1 -1
- package/dist/testing.d.cts +1 -1
- package/dist/testing.d.ts +1 -1
- package/dist/testing.js +1 -1
- package/package.json +2 -2
- package/dist/chunk-BFSRYCOS.js +0 -4
- package/dist/chunk-BFSRYCOS.js.map +0 -1
- package/dist/chunk-CAA6Q4YY.cjs +0 -4
- package/dist/chunk-CAA6Q4YY.cjs.map +0 -1
- package/dist/chunk-D72LIBH2.js +0 -16
- package/dist/chunk-D72LIBH2.js.map +0 -1
- package/dist/chunk-UZKM276C.cjs +0 -16
- package/dist/chunk-UZKM276C.cjs.map +0 -1
package/dist/guardrails.d.cts
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import { m as GuardrailFn, I as InputGuardrailData, O as OutputGuardrailData, aW as SchemaValidator, T as ToolCallGuardrailData } from './types-DJ09LjZX.cjs';
|
|
2
2
|
import { a as Embedding } from './semantic-cache-DM7ev7NQ.cjs';
|
|
3
3
|
export { B as BatchedEmbedder, C as CacheEntry, b as CacheLookupResult, c as CacheStats, E as EmbedderFn, S as SemanticCache, d as SemanticCacheConfig, e as SemanticCacheStorage, f as createBatchedEmbedder, g as createInMemoryStorage, h as createSemanticCache, i as createSemanticCacheGuardrail, j as createTestEmbedder } from './semantic-cache-DM7ev7NQ.cjs';
|
|
4
|
-
import '@directive-run/core';
|
|
4
|
+
import { Plugin } from '@directive-run/core';
|
|
5
5
|
|
|
6
6
|
/**
|
|
7
7
|
* Built-in guardrails for AI adapter — PII, moderation, rate limiting, tool allowlists, schema validation.
|
|
@@ -215,6 +215,190 @@ declare function createContentFilterGuardrail(options: {
|
|
|
215
215
|
caseSensitive?: boolean;
|
|
216
216
|
}): GuardrailFn<OutputGuardrailData>;
|
|
217
217
|
|
|
218
|
+
/**
|
|
219
|
+
* Fact-PII Guardrail — input guardrail at the fact-store boundary
|
|
220
|
+
*
|
|
221
|
+
* Closes the source → fact → agent prompt PII bypass surfaced by R5's
|
|
222
|
+
* red-team / privacy / AI-integration reviewers: `createPIIGuardrail`
|
|
223
|
+
* only inspects the `data.input` string at runStream entry, so PII that
|
|
224
|
+
* a source publishes into a fact (a Supabase realtime row carrying a
|
|
225
|
+
* customer email, a webhook payload with a SSN, an MCP server's
|
|
226
|
+
* resource notification with a card number) reaches the agent's
|
|
227
|
+
* prompt — via fact injection — without ever hitting the input
|
|
228
|
+
* guardrail chain.
|
|
229
|
+
*
|
|
230
|
+
* This plugin runs as a Directive plugin (`onFactSet` / `onFactsBatch`),
|
|
231
|
+
* scans every write to a pii-tagged fact against a sync regex matcher
|
|
232
|
+
* for the three highest-volume PII categories (SSN, credit card, email),
|
|
233
|
+
* and either **redacts** the value (the default — safe shipping posture)
|
|
234
|
+
* or **rejects** the write (throws so the source's publish handler can
|
|
235
|
+
* surface the violation). Operators wire it once at `createSystem`; no
|
|
236
|
+
* per-source / per-fact changes are required.
|
|
237
|
+
*
|
|
238
|
+
* The async PII detector from `pii-enhanced.ts` is unsuitable here:
|
|
239
|
+
* `onFactSet` is synchronous and a deferred detection would let the
|
|
240
|
+
* raw PII reach observers + breakpoints + audit-ledger before the
|
|
241
|
+
* redaction completed. Built-in matching is therefore inlined as
|
|
242
|
+
* synchronous regex. Consumers who need richer detection pass a
|
|
243
|
+
* synchronous `customDetector`.
|
|
244
|
+
*
|
|
245
|
+
* @example Defensive (redact PII writes into pii-tagged facts)
|
|
246
|
+
* ```ts
|
|
247
|
+
* import { createSystem, t } from '@directive-run/core';
|
|
248
|
+
* import { createFactPIIGuardrail } from '@directive-run/ai/guardrails';
|
|
249
|
+
*
|
|
250
|
+
* const customer = createModule('customer', {
|
|
251
|
+
* schema: {
|
|
252
|
+
* facts: {
|
|
253
|
+
* email: t.string().meta({ tags: ['pii'] }),
|
|
254
|
+
* ssn: t.string().meta({ tags: ['pii'] }),
|
|
255
|
+
* },
|
|
256
|
+
* },
|
|
257
|
+
* sources: {
|
|
258
|
+
* supabase: { attach: (publish) => subscribe(publish) },
|
|
259
|
+
* },
|
|
260
|
+
* });
|
|
261
|
+
*
|
|
262
|
+
* const system = createSystem({
|
|
263
|
+
* module: customer,
|
|
264
|
+
* plugins: [
|
|
265
|
+
* createFactPIIGuardrail({
|
|
266
|
+
* mode: 'redact',
|
|
267
|
+
* onBlocked: (key, detected) => {
|
|
268
|
+
* console.warn(`[fact-pii] redacted ${detected.length} match(es) in ${key}`);
|
|
269
|
+
* },
|
|
270
|
+
* }),
|
|
271
|
+
* ],
|
|
272
|
+
* });
|
|
273
|
+
* ```
|
|
274
|
+
*
|
|
275
|
+
* @example Monitor-only (alert on every PII match; don't mutate the fact)
|
|
276
|
+
* ```ts
|
|
277
|
+
* createFactPIIGuardrail({
|
|
278
|
+
* mode: 'alert',
|
|
279
|
+
* onBlocked: (key) => Sentry.captureException(new Error(`pii match: ${key}`)),
|
|
280
|
+
* });
|
|
281
|
+
* ```
|
|
282
|
+
*
|
|
283
|
+
* @example Allow specific keys (not just by tag)
|
|
284
|
+
* ```ts
|
|
285
|
+
* createFactPIIGuardrail({
|
|
286
|
+
* includeKeys: ['customer.email', 'customer.phone'],
|
|
287
|
+
* });
|
|
288
|
+
* ```
|
|
289
|
+
*/
|
|
290
|
+
|
|
291
|
+
/**
|
|
292
|
+
* Public match record for a single PII finding. Mirrors `DetectedPII` from
|
|
293
|
+
* `pii-enhanced.ts` so a downstream guardrail can normalize against either
|
|
294
|
+
* detection path.
|
|
295
|
+
*/
|
|
296
|
+
interface FactPIIMatch {
|
|
297
|
+
type: FactPIICategory;
|
|
298
|
+
value: string;
|
|
299
|
+
start: number;
|
|
300
|
+
end: number;
|
|
301
|
+
}
|
|
302
|
+
/** PII categories the built-in synchronous detector covers. */
|
|
303
|
+
type FactPIICategory = "ssn" | "credit_card" | "email";
|
|
304
|
+
/**
|
|
305
|
+
* Behavior when a pii-tagged fact's incoming value contains detected PII.
|
|
306
|
+
*
|
|
307
|
+
* - `"redact"` (default): the fact is rewritten with redacted text (e.g.
|
|
308
|
+
* `"[SSN]"`) via a follow-up store write. The system briefly observes
|
|
309
|
+
* the raw value during the same microtask the publish landed in, then
|
|
310
|
+
* the redacted value overwrites it before any reconcile / agent runs.
|
|
311
|
+
* Safe shipping posture for production: the LLM call always sees the
|
|
312
|
+
* redacted value.
|
|
313
|
+
* - `"alert"`: fire `onBlocked` but DO NOT mutate the fact. The raw value
|
|
314
|
+
* stays in the store. Use this for monitoring-only deployments where
|
|
315
|
+
* the source's transport is already trusted but a regression detector
|
|
316
|
+
* is needed (paging ops on every match).
|
|
317
|
+
*
|
|
318
|
+
* Note: Directive plugin hooks (`onFactSet`, `onFactsBatch`) are
|
|
319
|
+
* wrapped by the plugin manager's `safeCall` so a throw from inside the
|
|
320
|
+
* hook is swallowed. The guardrail therefore cannot reject the write
|
|
321
|
+
* itself — it can only observe + redact-via-followup-write or alert.
|
|
322
|
+
* For hard rejection at the publish boundary, a future RFC will add a
|
|
323
|
+
* pre-commit transform hook on the source primitive.
|
|
324
|
+
*/
|
|
325
|
+
type FactPIIGuardrailMode = "redact" | "alert";
|
|
326
|
+
interface FactPIIGuardrailOptions {
|
|
327
|
+
/** Default: `"redact"` */
|
|
328
|
+
mode?: FactPIIGuardrailMode;
|
|
329
|
+
/**
|
|
330
|
+
* Built-in categories to scan for. Default: all three (`ssn`,
|
|
331
|
+
* `credit_card`, `email`). Pass `[]` to opt out of the built-ins and
|
|
332
|
+
* rely entirely on `customDetector`.
|
|
333
|
+
*/
|
|
334
|
+
types?: readonly FactPIICategory[];
|
|
335
|
+
/**
|
|
336
|
+
* Specific fact keys to scan in addition to the auto-detected
|
|
337
|
+
* `pii`-tagged set. Useful when a consumer can't change the schema's
|
|
338
|
+
* meta but knows the key should be screened.
|
|
339
|
+
*/
|
|
340
|
+
includeKeys?: readonly string[];
|
|
341
|
+
/**
|
|
342
|
+
* Exclude these fact keys even if they're pii-tagged. Escape hatch for
|
|
343
|
+
* a key that's already pre-sanitized upstream of the manager.
|
|
344
|
+
*/
|
|
345
|
+
excludeKeys?: readonly string[];
|
|
346
|
+
/**
|
|
347
|
+
* Called whenever the guardrail detects PII and acts on it. Receives the
|
|
348
|
+
* fact key, the detected matches, and the action that was taken. Fires
|
|
349
|
+
* AFTER redact + before any throw in `reject` mode. Use this to alert
|
|
350
|
+
* SREs without coupling the guardrail to a specific logging backend.
|
|
351
|
+
*/
|
|
352
|
+
onBlocked?: (key: string, detected: readonly FactPIIMatch[], action: FactPIIGuardrailMode) => void;
|
|
353
|
+
/**
|
|
354
|
+
* Custom synchronous detector that runs alongside the built-in regex
|
|
355
|
+
* scanner. The union of detections is acted on. Useful when the
|
|
356
|
+
* consumer ships a domain-specific PII detector (e.g. internal
|
|
357
|
+
* account-number format). MUST be synchronous — `onFactSet` cannot
|
|
358
|
+
* await deferred work.
|
|
359
|
+
*/
|
|
360
|
+
customDetector?: (text: string) => readonly FactPIIMatch[];
|
|
361
|
+
/**
|
|
362
|
+
* Maximum nesting depth to walk when scanning a structured fact
|
|
363
|
+
* value. Default `1` — the scanner inspects top-level strings, then
|
|
364
|
+
* descends one level into the object/array. Arrays and plain objects
|
|
365
|
+
* count as one depth level each. Maps and Sets are still NOT walked
|
|
366
|
+
* by the built-in scanner; PII inside those structures must go
|
|
367
|
+
* through a `customDetector`.
|
|
368
|
+
*
|
|
369
|
+
* Per R13-C6 the walker recurses into arrays (Supabase realtime
|
|
370
|
+
* payloads ship as `payload.new = [{...}]`, MCP resource lists ship
|
|
371
|
+
* as arrays — those shapes silently bypassed the Tier 0 guard before).
|
|
372
|
+
*
|
|
373
|
+
* Consumers with deeply-nested PII shapes have two options:
|
|
374
|
+
* 1. Pass `walkDepth: 2` (or higher) — the scanner walks plain
|
|
375
|
+
* objects and arrays to that depth. Maps and Sets are still
|
|
376
|
+
* skipped.
|
|
377
|
+
* 2. Pass a `customDetector` that walks the consumer-specific shape
|
|
378
|
+
* and returns concrete matches — the right answer for
|
|
379
|
+
* domain-specific structures (Maps, Sets, getters, Symbol keys).
|
|
380
|
+
*
|
|
381
|
+
* Maximum is `5` to prevent pathological recursion on cyclic
|
|
382
|
+
* structures. Passing anything higher clamps to `5`.
|
|
383
|
+
*
|
|
384
|
+
* Property iteration uses `Object.entries`, which skips
|
|
385
|
+
* Symbol-keyed properties and non-enumerable string keys. If you
|
|
386
|
+
* store PII under a Symbol key (unusual), a `customDetector` is the
|
|
387
|
+
* right escape hatch.
|
|
388
|
+
*/
|
|
389
|
+
walkDepth?: number;
|
|
390
|
+
}
|
|
391
|
+
/**
|
|
392
|
+
* Create a Directive plugin that scans pii-tagged fact writes for PII and
|
|
393
|
+
* redacts or rejects them at the manager boundary.
|
|
394
|
+
*
|
|
395
|
+
* Wire it once at `createSystem({ plugins: [...] })`. The plugin caches
|
|
396
|
+
* the pii-tagged key set on `onInit` so per-write hooks are O(1) lookups.
|
|
397
|
+
*
|
|
398
|
+
* @returns a `Plugin` instance ready to add to `SystemConfig.plugins`.
|
|
399
|
+
*/
|
|
400
|
+
declare function createFactPIIGuardrail(options?: FactPIIGuardrailOptions): Plugin;
|
|
401
|
+
|
|
218
402
|
/**
|
|
219
403
|
* Enhanced PII Detection Guardrail
|
|
220
404
|
*
|
|
@@ -615,4 +799,4 @@ interface VPTreeIndexConfig {
|
|
|
615
799
|
*/
|
|
616
800
|
declare function createVPTreeIndex(vpConfig?: VPTreeIndexConfig): ANNIndex;
|
|
617
801
|
|
|
618
|
-
export { type ANNIndex, type ANNSearchResult, DEFAULT_INJECTION_PATTERNS, type DetectedPII, Embedding, type EnhancedPIIGuardrailOptions, type InjectionDetectionResult, type PIIDetectionResult, type PIIDetector, type PIIType, type PromptInjectionGuardrailOptions, type RateLimitGuardrail, type RedactionStyle, STRICT_INJECTION_PATTERNS, type VPTreeIndexConfig, createBruteForceIndex, createContentFilterGuardrail, createEnhancedPIIGuardrail, createLengthGuardrail, createModerationGuardrail, createOutputPIIGuardrail, createOutputSchemaGuardrail, createOutputTypeGuardrail, createPIIGuardrail, createPromptInjectionGuardrail, createRateLimitGuardrail, createToolGuardrail, createUntrustedContentGuardrail, createVPTreeIndex, detectAndRedactPII, detectPII, detectPromptInjection, markUntrustedContent, redactPII, sanitizeInjection };
|
|
802
|
+
export { type ANNIndex, type ANNSearchResult, DEFAULT_INJECTION_PATTERNS, type DetectedPII, Embedding, type EnhancedPIIGuardrailOptions, type FactPIICategory, type FactPIIGuardrailMode, type FactPIIGuardrailOptions, type FactPIIMatch, type InjectionDetectionResult, type PIIDetectionResult, type PIIDetector, type PIIType, type PromptInjectionGuardrailOptions, type RateLimitGuardrail, type RedactionStyle, STRICT_INJECTION_PATTERNS, type VPTreeIndexConfig, createBruteForceIndex, createContentFilterGuardrail, createEnhancedPIIGuardrail, createFactPIIGuardrail, createLengthGuardrail, createModerationGuardrail, createOutputPIIGuardrail, createOutputSchemaGuardrail, createOutputTypeGuardrail, createPIIGuardrail, createPromptInjectionGuardrail, createRateLimitGuardrail, createToolGuardrail, createUntrustedContentGuardrail, createVPTreeIndex, detectAndRedactPII, detectPII, detectPromptInjection, markUntrustedContent, redactPII, sanitizeInjection };
|
package/dist/guardrails.d.ts
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import { m as GuardrailFn, I as InputGuardrailData, O as OutputGuardrailData, aW as SchemaValidator, T as ToolCallGuardrailData } from './types-DJ09LjZX.js';
|
|
2
2
|
import { a as Embedding } from './semantic-cache-DM7ev7NQ.js';
|
|
3
3
|
export { B as BatchedEmbedder, C as CacheEntry, b as CacheLookupResult, c as CacheStats, E as EmbedderFn, S as SemanticCache, d as SemanticCacheConfig, e as SemanticCacheStorage, f as createBatchedEmbedder, g as createInMemoryStorage, h as createSemanticCache, i as createSemanticCacheGuardrail, j as createTestEmbedder } from './semantic-cache-DM7ev7NQ.js';
|
|
4
|
-
import '@directive-run/core';
|
|
4
|
+
import { Plugin } from '@directive-run/core';
|
|
5
5
|
|
|
6
6
|
/**
|
|
7
7
|
* Built-in guardrails for AI adapter — PII, moderation, rate limiting, tool allowlists, schema validation.
|
|
@@ -215,6 +215,190 @@ declare function createContentFilterGuardrail(options: {
|
|
|
215
215
|
caseSensitive?: boolean;
|
|
216
216
|
}): GuardrailFn<OutputGuardrailData>;
|
|
217
217
|
|
|
218
|
+
/**
|
|
219
|
+
* Fact-PII Guardrail — input guardrail at the fact-store boundary
|
|
220
|
+
*
|
|
221
|
+
* Closes the source → fact → agent prompt PII bypass surfaced by R5's
|
|
222
|
+
* red-team / privacy / AI-integration reviewers: `createPIIGuardrail`
|
|
223
|
+
* only inspects the `data.input` string at runStream entry, so PII that
|
|
224
|
+
* a source publishes into a fact (a Supabase realtime row carrying a
|
|
225
|
+
* customer email, a webhook payload with a SSN, an MCP server's
|
|
226
|
+
* resource notification with a card number) reaches the agent's
|
|
227
|
+
* prompt — via fact injection — without ever hitting the input
|
|
228
|
+
* guardrail chain.
|
|
229
|
+
*
|
|
230
|
+
* This plugin runs as a Directive plugin (`onFactSet` / `onFactsBatch`),
|
|
231
|
+
* scans every write to a pii-tagged fact against a sync regex matcher
|
|
232
|
+
* for the three highest-volume PII categories (SSN, credit card, email),
|
|
233
|
+
* and either **redacts** the value (the default — safe shipping posture)
|
|
234
|
+
* or **rejects** the write (throws so the source's publish handler can
|
|
235
|
+
* surface the violation). Operators wire it once at `createSystem`; no
|
|
236
|
+
* per-source / per-fact changes are required.
|
|
237
|
+
*
|
|
238
|
+
* The async PII detector from `pii-enhanced.ts` is unsuitable here:
|
|
239
|
+
* `onFactSet` is synchronous and a deferred detection would let the
|
|
240
|
+
* raw PII reach observers + breakpoints + audit-ledger before the
|
|
241
|
+
* redaction completed. Built-in matching is therefore inlined as
|
|
242
|
+
* synchronous regex. Consumers who need richer detection pass a
|
|
243
|
+
* synchronous `customDetector`.
|
|
244
|
+
*
|
|
245
|
+
* @example Defensive (redact PII writes into pii-tagged facts)
|
|
246
|
+
* ```ts
|
|
247
|
+
* import { createSystem, t } from '@directive-run/core';
|
|
248
|
+
* import { createFactPIIGuardrail } from '@directive-run/ai/guardrails';
|
|
249
|
+
*
|
|
250
|
+
* const customer = createModule('customer', {
|
|
251
|
+
* schema: {
|
|
252
|
+
* facts: {
|
|
253
|
+
* email: t.string().meta({ tags: ['pii'] }),
|
|
254
|
+
* ssn: t.string().meta({ tags: ['pii'] }),
|
|
255
|
+
* },
|
|
256
|
+
* },
|
|
257
|
+
* sources: {
|
|
258
|
+
* supabase: { attach: (publish) => subscribe(publish) },
|
|
259
|
+
* },
|
|
260
|
+
* });
|
|
261
|
+
*
|
|
262
|
+
* const system = createSystem({
|
|
263
|
+
* module: customer,
|
|
264
|
+
* plugins: [
|
|
265
|
+
* createFactPIIGuardrail({
|
|
266
|
+
* mode: 'redact',
|
|
267
|
+
* onBlocked: (key, detected) => {
|
|
268
|
+
* console.warn(`[fact-pii] redacted ${detected.length} match(es) in ${key}`);
|
|
269
|
+
* },
|
|
270
|
+
* }),
|
|
271
|
+
* ],
|
|
272
|
+
* });
|
|
273
|
+
* ```
|
|
274
|
+
*
|
|
275
|
+
* @example Monitor-only (alert on every PII match; don't mutate the fact)
|
|
276
|
+
* ```ts
|
|
277
|
+
* createFactPIIGuardrail({
|
|
278
|
+
* mode: 'alert',
|
|
279
|
+
* onBlocked: (key) => Sentry.captureException(new Error(`pii match: ${key}`)),
|
|
280
|
+
* });
|
|
281
|
+
* ```
|
|
282
|
+
*
|
|
283
|
+
* @example Allow specific keys (not just by tag)
|
|
284
|
+
* ```ts
|
|
285
|
+
* createFactPIIGuardrail({
|
|
286
|
+
* includeKeys: ['customer.email', 'customer.phone'],
|
|
287
|
+
* });
|
|
288
|
+
* ```
|
|
289
|
+
*/
|
|
290
|
+
|
|
291
|
+
/**
|
|
292
|
+
* Public match record for a single PII finding. Mirrors `DetectedPII` from
|
|
293
|
+
* `pii-enhanced.ts` so a downstream guardrail can normalize against either
|
|
294
|
+
* detection path.
|
|
295
|
+
*/
|
|
296
|
+
interface FactPIIMatch {
|
|
297
|
+
type: FactPIICategory;
|
|
298
|
+
value: string;
|
|
299
|
+
start: number;
|
|
300
|
+
end: number;
|
|
301
|
+
}
|
|
302
|
+
/** PII categories the built-in synchronous detector covers. */
|
|
303
|
+
type FactPIICategory = "ssn" | "credit_card" | "email";
|
|
304
|
+
/**
|
|
305
|
+
* Behavior when a pii-tagged fact's incoming value contains detected PII.
|
|
306
|
+
*
|
|
307
|
+
* - `"redact"` (default): the fact is rewritten with redacted text (e.g.
|
|
308
|
+
* `"[SSN]"`) via a follow-up store write. The system briefly observes
|
|
309
|
+
* the raw value during the same microtask the publish landed in, then
|
|
310
|
+
* the redacted value overwrites it before any reconcile / agent runs.
|
|
311
|
+
* Safe shipping posture for production: the LLM call always sees the
|
|
312
|
+
* redacted value.
|
|
313
|
+
* - `"alert"`: fire `onBlocked` but DO NOT mutate the fact. The raw value
|
|
314
|
+
* stays in the store. Use this for monitoring-only deployments where
|
|
315
|
+
* the source's transport is already trusted but a regression detector
|
|
316
|
+
* is needed (paging ops on every match).
|
|
317
|
+
*
|
|
318
|
+
* Note: Directive plugin hooks (`onFactSet`, `onFactsBatch`) are
|
|
319
|
+
* wrapped by the plugin manager's `safeCall` so a throw from inside the
|
|
320
|
+
* hook is swallowed. The guardrail therefore cannot reject the write
|
|
321
|
+
* itself — it can only observe + redact-via-followup-write or alert.
|
|
322
|
+
* For hard rejection at the publish boundary, a future RFC will add a
|
|
323
|
+
* pre-commit transform hook on the source primitive.
|
|
324
|
+
*/
|
|
325
|
+
type FactPIIGuardrailMode = "redact" | "alert";
|
|
326
|
+
interface FactPIIGuardrailOptions {
|
|
327
|
+
/** Default: `"redact"` */
|
|
328
|
+
mode?: FactPIIGuardrailMode;
|
|
329
|
+
/**
|
|
330
|
+
* Built-in categories to scan for. Default: all three (`ssn`,
|
|
331
|
+
* `credit_card`, `email`). Pass `[]` to opt out of the built-ins and
|
|
332
|
+
* rely entirely on `customDetector`.
|
|
333
|
+
*/
|
|
334
|
+
types?: readonly FactPIICategory[];
|
|
335
|
+
/**
|
|
336
|
+
* Specific fact keys to scan in addition to the auto-detected
|
|
337
|
+
* `pii`-tagged set. Useful when a consumer can't change the schema's
|
|
338
|
+
* meta but knows the key should be screened.
|
|
339
|
+
*/
|
|
340
|
+
includeKeys?: readonly string[];
|
|
341
|
+
/**
|
|
342
|
+
* Exclude these fact keys even if they're pii-tagged. Escape hatch for
|
|
343
|
+
* a key that's already pre-sanitized upstream of the manager.
|
|
344
|
+
*/
|
|
345
|
+
excludeKeys?: readonly string[];
|
|
346
|
+
/**
|
|
347
|
+
* Called whenever the guardrail detects PII and acts on it. Receives the
|
|
348
|
+
* fact key, the detected matches, and the action that was taken. Fires
|
|
349
|
+
* AFTER redact + before any throw in `reject` mode. Use this to alert
|
|
350
|
+
* SREs without coupling the guardrail to a specific logging backend.
|
|
351
|
+
*/
|
|
352
|
+
onBlocked?: (key: string, detected: readonly FactPIIMatch[], action: FactPIIGuardrailMode) => void;
|
|
353
|
+
/**
|
|
354
|
+
* Custom synchronous detector that runs alongside the built-in regex
|
|
355
|
+
* scanner. The union of detections is acted on. Useful when the
|
|
356
|
+
* consumer ships a domain-specific PII detector (e.g. internal
|
|
357
|
+
* account-number format). MUST be synchronous — `onFactSet` cannot
|
|
358
|
+
* await deferred work.
|
|
359
|
+
*/
|
|
360
|
+
customDetector?: (text: string) => readonly FactPIIMatch[];
|
|
361
|
+
/**
|
|
362
|
+
* Maximum nesting depth to walk when scanning a structured fact
|
|
363
|
+
* value. Default `1` — the scanner inspects top-level strings, then
|
|
364
|
+
* descends one level into the object/array. Arrays and plain objects
|
|
365
|
+
* count as one depth level each. Maps and Sets are still NOT walked
|
|
366
|
+
* by the built-in scanner; PII inside those structures must go
|
|
367
|
+
* through a `customDetector`.
|
|
368
|
+
*
|
|
369
|
+
* Per R13-C6 the walker recurses into arrays (Supabase realtime
|
|
370
|
+
* payloads ship as `payload.new = [{...}]`, MCP resource lists ship
|
|
371
|
+
* as arrays — those shapes silently bypassed the Tier 0 guard before).
|
|
372
|
+
*
|
|
373
|
+
* Consumers with deeply-nested PII shapes have two options:
|
|
374
|
+
* 1. Pass `walkDepth: 2` (or higher) — the scanner walks plain
|
|
375
|
+
* objects and arrays to that depth. Maps and Sets are still
|
|
376
|
+
* skipped.
|
|
377
|
+
* 2. Pass a `customDetector` that walks the consumer-specific shape
|
|
378
|
+
* and returns concrete matches — the right answer for
|
|
379
|
+
* domain-specific structures (Maps, Sets, getters, Symbol keys).
|
|
380
|
+
*
|
|
381
|
+
* Maximum is `5` to prevent pathological recursion on cyclic
|
|
382
|
+
* structures. Passing anything higher clamps to `5`.
|
|
383
|
+
*
|
|
384
|
+
* Property iteration uses `Object.entries`, which skips
|
|
385
|
+
* Symbol-keyed properties and non-enumerable string keys. If you
|
|
386
|
+
* store PII under a Symbol key (unusual), a `customDetector` is the
|
|
387
|
+
* right escape hatch.
|
|
388
|
+
*/
|
|
389
|
+
walkDepth?: number;
|
|
390
|
+
}
|
|
391
|
+
/**
|
|
392
|
+
* Create a Directive plugin that scans pii-tagged fact writes for PII and
|
|
393
|
+
* redacts or rejects them at the manager boundary.
|
|
394
|
+
*
|
|
395
|
+
* Wire it once at `createSystem({ plugins: [...] })`. The plugin caches
|
|
396
|
+
* the pii-tagged key set on `onInit` so per-write hooks are O(1) lookups.
|
|
397
|
+
*
|
|
398
|
+
* @returns a `Plugin` instance ready to add to `SystemConfig.plugins`.
|
|
399
|
+
*/
|
|
400
|
+
declare function createFactPIIGuardrail(options?: FactPIIGuardrailOptions): Plugin;
|
|
401
|
+
|
|
218
402
|
/**
|
|
219
403
|
* Enhanced PII Detection Guardrail
|
|
220
404
|
*
|
|
@@ -615,4 +799,4 @@ interface VPTreeIndexConfig {
|
|
|
615
799
|
*/
|
|
616
800
|
declare function createVPTreeIndex(vpConfig?: VPTreeIndexConfig): ANNIndex;
|
|
617
801
|
|
|
618
|
-
export { type ANNIndex, type ANNSearchResult, DEFAULT_INJECTION_PATTERNS, type DetectedPII, Embedding, type EnhancedPIIGuardrailOptions, type InjectionDetectionResult, type PIIDetectionResult, type PIIDetector, type PIIType, type PromptInjectionGuardrailOptions, type RateLimitGuardrail, type RedactionStyle, STRICT_INJECTION_PATTERNS, type VPTreeIndexConfig, createBruteForceIndex, createContentFilterGuardrail, createEnhancedPIIGuardrail, createLengthGuardrail, createModerationGuardrail, createOutputPIIGuardrail, createOutputSchemaGuardrail, createOutputTypeGuardrail, createPIIGuardrail, createPromptInjectionGuardrail, createRateLimitGuardrail, createToolGuardrail, createUntrustedContentGuardrail, createVPTreeIndex, detectAndRedactPII, detectPII, detectPromptInjection, markUntrustedContent, redactPII, sanitizeInjection };
|
|
802
|
+
export { type ANNIndex, type ANNSearchResult, DEFAULT_INJECTION_PATTERNS, type DetectedPII, Embedding, type EnhancedPIIGuardrailOptions, type FactPIICategory, type FactPIIGuardrailMode, type FactPIIGuardrailOptions, type FactPIIMatch, type InjectionDetectionResult, type PIIDetectionResult, type PIIDetector, type PIIType, type PromptInjectionGuardrailOptions, type RateLimitGuardrail, type RedactionStyle, STRICT_INJECTION_PATTERNS, type VPTreeIndexConfig, createBruteForceIndex, createContentFilterGuardrail, createEnhancedPIIGuardrail, createFactPIIGuardrail, createLengthGuardrail, createModerationGuardrail, createOutputPIIGuardrail, createOutputSchemaGuardrail, createOutputTypeGuardrail, createPIIGuardrail, createPromptInjectionGuardrail, createRateLimitGuardrail, createToolGuardrail, createUntrustedContentGuardrail, createVPTreeIndex, detectAndRedactPII, detectPII, detectPromptInjection, markUntrustedContent, redactPII, sanitizeInjection };
|
package/dist/guardrails.js
CHANGED
|
@@ -1,2 +1,2 @@
|
|
|
1
|
-
export{
|
|
1
|
+
export{o as DEFAULT_INJECTION_PATTERNS,p as STRICT_INJECTION_PATTERNS,A as createBatchedEmbedder,B as createBruteForceIndex,h as createContentFilterGuardrail,k as createEnhancedPIIGuardrail,i as createFactPIIGuardrail,w as createInMemoryStorage,g as createLengthGuardrail,b as createModerationGuardrail,l as createOutputPIIGuardrail,e as createOutputSchemaGuardrail,f as createOutputTypeGuardrail,a as createPIIGuardrail,s as createPromptInjectionGuardrail,c as createRateLimitGuardrail,x as createSemanticCache,y as createSemanticCacheGuardrail,z as createTestEmbedder,d as createToolGuardrail,u as createUntrustedContentGuardrail,C as createVPTreeIndex,n as detectAndRedactPII,m as detectPII,q as detectPromptInjection,t as markUntrustedContent,j as redactPII,r as sanitizeInjection}from'./chunk-WERHNNUD.js';import'./chunk-UR5BMWEN.js';//# sourceMappingURL=guardrails.js.map
|
|
2
2
|
//# sourceMappingURL=guardrails.js.map
|