@graphorin/observability 0.5.0

package/dist/redaction/errors.js

@@ -0,0 +1,42 @@
+//#region src/redaction/errors.ts
+/**
+* Thrown by the validator when `failOnUnredactedSensitive: true` and
+* a value would otherwise be dropped or masked. The error never
+* carries the secret value itself; only the sanitized
+* {@link RedactionViolation} metadata.
+*
+* @stable
+*/
+var RedactionValidationError = class extends Error {
+	/** @stable */
+	kind = "redaction-validation-failed";
+	/** @stable */
+	violation;
+	constructor(message, violation) {
+		super(message);
+		this.name = "RedactionValidationError";
+		this.violation = violation;
+	}
+};
+/**
+* Thrown at startup when an exporter is registered without going
+* through `withValidation(...)`. Enforces ADR-035: every exporter
+* must validate before forwarding.
+*
+* @stable
+*/
+var UnvalidatedExporterError = class extends Error {
+	/** @stable */
+	kind = "unvalidated-exporter";
+	/** Exporter identifier (typically `exporter.constructor.name`). */
+	exporterId;
+	constructor(exporterId) {
+		super(`Exporter "${exporterId}" was registered without withValidation(). All exporters must be wrapped — see RedactionValidator policy. Wrap with \`withValidation(exporter, opts)\` or set \`validation: 'off'\` (NOT recommended) on the tracer to opt out explicitly (logs a startup WARN).`);
+		this.name = "UnvalidatedExporterError";
+		this.exporterId = exporterId;
+	}
+};
+
+//#endregion
+export { RedactionValidationError, UnvalidatedExporterError };
+//# sourceMappingURL=errors.js.map

package/dist/redaction/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","names":[],"sources":["../../src/redaction/errors.ts"],"sourcesContent":["/**\n * Errors thrown by the redaction layer.\n *\n * @packageDocumentation\n */\n\nimport type { RedactionViolation } from './types.js';\n\n/**\n * Thrown by the validator when `failOnUnredactedSensitive: true` and\n * a value would otherwise be dropped or masked. The error never\n * carries the secret value itself; only the sanitized\n * {@link RedactionViolation} metadata.\n *\n * @stable\n */\nexport class RedactionValidationError extends Error {\n  /** @stable */\n  readonly kind = 'redaction-validation-failed' as const;\n  /** @stable */\n  readonly violation: RedactionViolation;\n\n  constructor(message: string, violation: RedactionViolation) {\n    super(message);\n    this.name = 'RedactionValidationError';\n    this.violation = violation;\n  }\n}\n\n/**\n * Thrown at startup when an exporter is registered without going\n * through `withValidation(...)`. Enforces ADR-035: every exporter\n * must validate before forwarding.\n *\n * @stable\n */\nexport class UnvalidatedExporterError extends Error {\n  /** @stable */\n  readonly kind = 'unvalidated-exporter' as const;\n  /** Exporter identifier (typically `exporter.constructor.name`). */\n  readonly exporterId: string;\n\n  constructor(exporterId: string) {\n    super(\n      `Exporter \"${exporterId}\" was registered without withValidation(). All ` +\n        'exporters must be wrapped — see RedactionValidator policy. Wrap with ' +\n        \"`withValidation(exporter, opts)` or set `validation: 'off'` (NOT recommended) \" +\n        'on the tracer to opt out explicitly (logs a startup WARN).',\n    );\n    this.name = 'UnvalidatedExporterError';\n    this.exporterId = exporterId;\n  }\n}\n"],"mappings":";;;;;;;;;AAgBA,IAAa,2BAAb,cAA8C,MAAM;;CAElD,AAAS,OAAO;;CAEhB,AAAS;CAET,YAAY,SAAiB,WAA+B;AAC1D,QAAM,QAAQ;AACd,OAAK,OAAO;AACZ,OAAK,YAAY;;;;;;;;;;AAWrB,IAAa,2BAAb,cAA8C,MAAM;;CAElD,AAAS,OAAO;;CAEhB,AAAS;CAET,YAAY,YAAoB;AAC9B,QACE,aAAa,WAAW,kQAIzB;AACD,OAAK,OAAO;AACZ,OAAK,aAAa"}

package/dist/redaction/imperative-patterns.d.ts

@@ -0,0 +1,108 @@
+//#region src/redaction/imperative-patterns.d.ts
+/**
+ * Imperative-pattern catalogue for inbound prompt-injection defence.
+ *
+ * Sibling to {@link BUILT_IN_PATTERNS} (PII / secrets) — the two
+ * catalogues are disjoint by construction. The imperative catalogue
+ * is consumed by the inbound sanitization layer in `@graphorin/tools`
+ * to scan tool / MCP results before they reach the agent's message
+ * store; the PII / secrets catalogue is consumed by the outbound
+ * exporter validators to scan span attributes before they reach an
+ * exporter.
+ *
+ * The patterns target the canonical English "ignore previous
+ * instructions" / "system override" injection family — the concrete
+ * surface that an untrusted-skill or MCP server result might use to
+ * smuggle imperative content into the next provider call. The
+ * catalogue is intentionally conservative: every entry has a fixed-
+ * substring prefilter so the per-byte scan budget stays sub-millisecond
+ * on typical 16 KB tool results.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Stable name of an imperative pattern. The catalogue is curated;
+ * user-supplied patterns can use any identifier they want and will be
+ * passed through the sanitization layer alongside the built-ins.
+ *
+ * @stable
+ */
+type ImperativePatternName = 'ignore-previous-instructions' | 'forget-instructions' | 'override-instructions' | 'system-prompt-leak' | 'role-reassignment' | 'developer-mode' | 'jailbreak-marker' | 'tool-call-injection' | 'role-tag-injection';
+/**
+ * One entry in the imperative-pattern catalogue. The shape mirrors
+ * {@link BUILT_IN_PATTERNS} so consumers can share scan / replace
+ * machinery, but the fields are typed as imperative-only so the two
+ * catalogues do not accidentally merge.
+ *
+ * @stable
+ */
+interface ImperativePattern {
+  readonly name: ImperativePatternName | (string & {});
+  readonly description: string;
+  /**
+   * Cheap substring prefilter applied before the regex; if the body
+   * does not contain any of the prefilter substrings the regex is
+   * skipped entirely. The prefilter is case-insensitive.
+   */
+  readonly prefilter: ReadonlyArray<string>;
+  /**
+   * Full regex applied when the prefilter matches. Always carries the
+   * `g` and `i` flags; the catalogue construction validates this.
+   */
+  readonly regex: RegExp;
+  /** Replacement string applied by the `'detect-and-strip*'` policies. */
+  readonly mask: string;
+}
+/**
+ * The default-on imperative-pattern catalogue. Stable across patches;
+ * additions during the pre-1.0 window are minor-bumps because new
+ * patterns may produce additional `tool.inbound.sanitization.hit{...}`
+ * counter increments on existing deployments.
+ *
+ * @stable
+ */
+declare const BUILT_IN_IMPERATIVE_PATTERNS: readonly ImperativePattern[];
+/**
+ * Combined Aho-Corasick-style prefilter set across every pattern.
+ * Lower-cased substrings; consumers test the body once with the
+ * combined filter before iterating regexes.
+ *
+ * @stable
+ */
+declare const IMPERATIVE_PREFILTER_SUBSTRINGS: ReadonlyArray<string>;
+/**
+ * Compiled scan helper. Returns the list of pattern names that fired
+ * AND the number of bytes the strip would remove if applied. Bounded
+ * by the budget hint — when exceeded, returns `null` to let the caller
+ * apply the best-effort `'detect-failed'` annotation.
+ *
+ * @stable
+ */
+interface ScanResult {
+  readonly hits: ReadonlyArray<{
+    readonly pattern: string;
+    readonly matchCount: number;
+  }>;
+  readonly bytesMatched: number;
+  readonly scanDurationUs: number;
+}
+/**
+ * Run the imperative-pattern scan against `body`. Patterns are
+ * iterated in catalogue order; the prefilter shortcut returns early
+ * for bodies that do not contain any imperative-family substring.
+ *
+ * @stable
+ */
+declare function scanImperativePatterns(body: string, patterns?: ReadonlyArray<ImperativePattern>, budgetMs?: number): ScanResult | null;
+/**
+ * Apply `pattern.mask` to every match of every pattern in `body`. Used
+ * by the `'detect-and-strip*'` policies. The mask is calibrated to NOT
+ * match any imperative pattern itself, so post-strip bodies do not
+ * trigger another scan hit on round trips.
+ *
+ * @stable
+ */
+declare function stripImperativePatterns(body: string, patterns?: ReadonlyArray<ImperativePattern>): string;
+//#endregion
+export { BUILT_IN_IMPERATIVE_PATTERNS, IMPERATIVE_PREFILTER_SUBSTRINGS, ImperativePattern, ImperativePatternName, ScanResult, scanImperativePatterns, stripImperativePatterns };
+//# sourceMappingURL=imperative-patterns.d.ts.map

package/dist/redaction/imperative-patterns.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"imperative-patterns.d.ts","names":[],"sources":["../../src/redaction/imperative-patterns.ts"],"sourcesContent":[],"mappings":";;AA6BA;AAmBA;;;;;AAuGA;AASA;AAYA;AAaA;;;;;AA4DA;;;;;;;;;;;;;KAxNY,qBAAA;;;;;;;;;UAmBK,iBAAA;iBACA;;;;;;;sBAOK;;;;;kBAKJ;;;;;;;;;;;;cA0FL,uCAAuC;;;;;;;;cASvC,iCAAiC;;;;;;;;;UAY7B,UAAA;iBACA;;;;;;;;;;;;;;iBAYD,sBAAA,0BAEJ,cAAc,wCAEvB;;;;;;;;;iBAwDa,uBAAA,0BAEJ,cAAc"}

package/dist/redaction/imperative-patterns.js

@@ -0,0 +1,187 @@
+//#region src/redaction/imperative-patterns.ts
+const PATTERNS = [
+	{
+		name: "ignore-previous-instructions",
+		description: "The canonical \"ignore previous instructions\" injection — the most common form of prompt injection seen across MCP results.",
+		prefilter: [
+			"ignore",
+			"disregard",
+			"forget"
+		],
+		regex: /\b(?:ignore|disregard|forget)\s+(?:all\s+)?(?:the\s+)?(?:previous|prior|above|earlier|preceding|original)\s+(?:instructions?|prompts?|messages?|directives?|rules?)\b/gi,
+		mask: "[REDACTED:imperative-pattern]"
+	},
+	{
+		name: "forget-instructions",
+		description: "Imperative \"forget what I told you\" / memory-wipe family.",
+		prefilter: [
+			"forget",
+			"erase",
+			"clear"
+		],
+		regex: /\b(?:forget|erase|clear|wipe)\s+(?:everything|all)\s+(?:above|before|previous|i\s+(?:told|said))\b/gi,
+		mask: "[REDACTED:imperative-pattern]"
+	},
+	{
+		name: "override-instructions",
+		description: "\"Override the system prompt\" / \"new instructions\" injection family.",
+		prefilter: [
+			"override",
+			"new instructions",
+			"updated instructions",
+			"replace"
+		],
+		regex: /\b(?:override|replace)\s+(?:the\s+)?(?:system\s+)?(?:prompt|instructions?|directives?)\b|\bnew\s+(?:instructions?|prompts?|directives?)\s*(?::|follow|are)\b|\bupdated\s+(?:instructions?|prompts?|directives?)\b/gi,
+		mask: "[REDACTED:imperative-pattern]"
+	},
+	{
+		name: "system-prompt-leak",
+		description: "Requests asking the model to reveal its system prompt / hidden instructions / configuration.",
+		prefilter: [
+			"system prompt",
+			"system message",
+			"reveal",
+			"print",
+			"show"
+		],
+		regex: /\b(?:reveal|print|show|output|repeat|expose|disclose)\s+(?:your|the)\s+(?:system\s+(?:prompt|message|instructions?)|hidden\s+instructions?|initial\s+(?:prompt|instructions?)|configuration)\b/gi,
+		mask: "[REDACTED:imperative-pattern]"
+	},
+	{
+		name: "role-reassignment",
+		description: "\"You are now ...\" / role-reassignment imperative family.",
+		prefilter: [
+			"you are now",
+			"you are no longer",
+			"pretend",
+			"act as"
+		],
+		regex: /\byou\s+are\s+(?:now|no\s+longer)\s+(?:a\b|an\b|the\b)|\bpretend\s+(?:to\s+be|you\s+are)\b|\bact\s+as\s+(?:a|an|the|if\s+you)\b/gi,
+		mask: "[REDACTED:imperative-pattern]"
+	},
+	{
+		name: "developer-mode",
+		description: "Requests to enter \"developer mode\" / \"DAN\" / unrestricted modes — a long-running jailbreak family.",
+		prefilter: [
+			"developer mode",
+			"admin mode",
+			"unrestricted"
+		],
+		regex: /\b(?:enter|enable|activate)\s+(?:developer|admin|debug|unrestricted|god|root)\s+mode\b/gi,
+		mask: "[REDACTED:imperative-pattern]"
+	},
+	{
+		name: "jailbreak-marker",
+		description: "Direct \"jailbreak\" markers in tool result content.",
+		prefilter: ["jailbreak", "jailbroken"],
+		regex: /\bjailbroken?\s+(?:mode|response|model|assistant)\b/gi,
+		mask: "[REDACTED:imperative-pattern]"
+	},
+	{
+		name: "tool-call-injection",
+		description: "Tool-call markers that try to coerce the model into invoking a tool from the result content.",
+		prefilter: [
+			"<tool_use",
+			"<function_call",
+			"<invoke"
+		],
+		regex: /<(?:tool_use|function_call|invoke|tool_call)\b[^>]*>/gi,
+		mask: "[REDACTED:imperative-pattern]"
+	},
+	{
+		name: "role-tag-injection",
+		description: "Chat-role tags injected into tool results to spoof a system / assistant message in the conversation.",
+		prefilter: [
+			"<|im_start|",
+			"<|system|",
+			"<|assistant|",
+			"<|user|"
+		],
+		regex: /<\|(?:im_start|system|assistant|user|im_end)\|>/gi,
+		mask: "[REDACTED:imperative-pattern]"
+	}
+];
+/**
+* The default-on imperative-pattern catalogue. Stable across patches;
+* additions during the pre-1.0 window are minor-bumps because new
+* patterns may produce additional `tool.inbound.sanitization.hit{...}`
+* counter increments on existing deployments.
+*
+* @stable
+*/
+const BUILT_IN_IMPERATIVE_PATTERNS = PATTERNS;
+/**
+* Combined Aho-Corasick-style prefilter set across every pattern.
+* Lower-cased substrings; consumers test the body once with the
+* combined filter before iterating regexes.
+*
+* @stable
+*/
+const IMPERATIVE_PREFILTER_SUBSTRINGS = Object.freeze([...new Set(BUILT_IN_IMPERATIVE_PATTERNS.flatMap((p) => p.prefilter.map((s) => s.toLowerCase())))]);
+/**
+* Run the imperative-pattern scan against `body`. Patterns are
+* iterated in catalogue order; the prefilter shortcut returns early
+* for bodies that do not contain any imperative-family substring.
+*
+* @stable
+*/
+function scanImperativePatterns(body, patterns = BUILT_IN_IMPERATIVE_PATTERNS, budgetMs = 5) {
+	const start = performance.now();
+	if (body.length === 0) return {
+		hits: [],
+		bytesMatched: 0,
+		scanDurationUs: 0
+	};
+	const lower = body.toLowerCase();
+	let prefilterHit = false;
+	for (const sub of IMPERATIVE_PREFILTER_SUBSTRINGS) if (lower.includes(sub)) {
+		prefilterHit = true;
+		break;
+	}
+	if (!prefilterHit) return {
+		hits: [],
+		bytesMatched: 0,
+		scanDurationUs: Math.round((performance.now() - start) * 1e3)
+	};
+	const hits = [];
+	let bytesMatched = 0;
+	for (const pattern of patterns) {
+		if (performance.now() - start > budgetMs) return null;
+		if (!pattern.prefilter.some((sub) => lower.includes(sub.toLowerCase()))) continue;
+		let matchCount = 0;
+		pattern.regex.lastIndex = 0;
+		let match = pattern.regex.exec(body);
+		while (match !== null) {
+			matchCount++;
+			bytesMatched += match[0].length;
+			if (pattern.regex.lastIndex === match.index) pattern.regex.lastIndex = match.index + 1;
+			match = pattern.regex.exec(body);
+		}
+		if (matchCount > 0) hits.push({
+			pattern: pattern.name,
+			matchCount
+		});
+	}
+	return {
+		hits,
+		bytesMatched,
+		scanDurationUs: Math.round((performance.now() - start) * 1e3)
+	};
+}
+/**
+* Apply `pattern.mask` to every match of every pattern in `body`. Used
+* by the `'detect-and-strip*'` policies. The mask is calibrated to NOT
+* match any imperative pattern itself, so post-strip bodies do not
+* trigger another scan hit on round trips.
+*
+* @stable
+*/
+function stripImperativePatterns(body, patterns = BUILT_IN_IMPERATIVE_PATTERNS) {
+	let out = body;
+	for (const pattern of patterns) out = out.replace(pattern.regex, pattern.mask);
+	return out;
+}
+
+//#endregion
+export { BUILT_IN_IMPERATIVE_PATTERNS, IMPERATIVE_PREFILTER_SUBSTRINGS, scanImperativePatterns, stripImperativePatterns };
+//# sourceMappingURL=imperative-patterns.js.map

package/dist/redaction/imperative-patterns.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"imperative-patterns.js","names":["PATTERNS: readonly ImperativePattern[]","BUILT_IN_IMPERATIVE_PATTERNS: readonly ImperativePattern[]","IMPERATIVE_PREFILTER_SUBSTRINGS: ReadonlyArray<string>","hits: { pattern: string; matchCount: number }[]","match: RegExpExecArray | null"],"sources":["../../src/redaction/imperative-patterns.ts"],"sourcesContent":["/**\n * Imperative-pattern catalogue for inbound prompt-injection defence.\n *\n * Sibling to {@link BUILT_IN_PATTERNS} (PII / secrets) — the two\n * catalogues are disjoint by construction. The imperative catalogue\n * is consumed by the inbound sanitization layer in `@graphorin/tools`\n * to scan tool / MCP results before they reach the agent's message\n * store; the PII / secrets catalogue is consumed by the outbound\n * exporter validators to scan span attributes before they reach an\n * exporter.\n *\n * The patterns target the canonical English \"ignore previous\n * instructions\" / \"system override\" injection family — the concrete\n * surface that an untrusted-skill or MCP server result might use to\n * smuggle imperative content into the next provider call. The\n * catalogue is intentionally conservative: every entry has a fixed-\n * substring prefilter so the per-byte scan budget stays sub-millisecond\n * on typical 16 KB tool results.\n *\n * @packageDocumentation\n */\n\n/**\n * Stable name of an imperative pattern. The catalogue is curated;\n * user-supplied patterns can use any identifier they want and will be\n * passed through the sanitization layer alongside the built-ins.\n *\n * @stable\n */\nexport type ImperativePatternName =\n  | 'ignore-previous-instructions'\n  | 'forget-instructions'\n  | 'override-instructions'\n  | 'system-prompt-leak'\n  | 'role-reassignment'\n  | 'developer-mode'\n  | 'jailbreak-marker'\n  | 'tool-call-injection'\n  | 'role-tag-injection';\n\n/**\n * One entry in the imperative-pattern catalogue. The shape mirrors\n * {@link BUILT_IN_PATTERNS} so consumers can share scan / replace\n * machinery, but the fields are typed as imperative-only so the two\n * catalogues do not accidentally merge.\n *\n * @stable\n */\nexport interface ImperativePattern {\n  readonly name: ImperativePatternName | (string & {});\n  readonly description: string;\n  /**\n   * Cheap substring prefilter applied before the regex; if the body\n   * does not contain any of the prefilter substrings the regex is\n   * skipped entirely. The prefilter is case-insensitive.\n   */\n  readonly prefilter: ReadonlyArray<string>;\n  /**\n   * Full regex applied when the prefilter matches. Always carries the\n   * `g` and `i` flags; the catalogue construction validates this.\n   */\n  readonly regex: RegExp;\n  /** Replacement string applied by the `'detect-and-strip*'` policies. */\n  readonly mask: string;\n}\n\nconst PATTERNS: readonly ImperativePattern[] = [\n  {\n    name: 'ignore-previous-instructions',\n    description:\n      'The canonical \"ignore previous instructions\" injection — the most common form of prompt injection seen across MCP results.',\n    prefilter: ['ignore', 'disregard', 'forget'],\n    regex:\n      /\\b(?:ignore|disregard|forget)\\s+(?:all\\s+)?(?:the\\s+)?(?:previous|prior|above|earlier|preceding|original)\\s+(?:instructions?|prompts?|messages?|directives?|rules?)\\b/gi,\n    mask: '[REDACTED:imperative-pattern]',\n  },\n  {\n    name: 'forget-instructions',\n    description: 'Imperative \"forget what I told you\" / memory-wipe family.',\n    prefilter: ['forget', 'erase', 'clear'],\n    regex:\n      /\\b(?:forget|erase|clear|wipe)\\s+(?:everything|all)\\s+(?:above|before|previous|i\\s+(?:told|said))\\b/gi,\n    mask: '[REDACTED:imperative-pattern]',\n  },\n  {\n    name: 'override-instructions',\n    description: '\"Override the system prompt\" / \"new instructions\" injection family.',\n    prefilter: ['override', 'new instructions', 'updated instructions', 'replace'],\n    regex:\n      /\\b(?:override|replace)\\s+(?:the\\s+)?(?:system\\s+)?(?:prompt|instructions?|directives?)\\b|\\bnew\\s+(?:instructions?|prompts?|directives?)\\s*(?::|follow|are)\\b|\\bupdated\\s+(?:instructions?|prompts?|directives?)\\b/gi,\n    mask: '[REDACTED:imperative-pattern]',\n  },\n  {\n    name: 'system-prompt-leak',\n    description:\n      'Requests asking the model to reveal its system prompt / hidden instructions / configuration.',\n    prefilter: ['system prompt', 'system message', 'reveal', 'print', 'show'],\n    regex:\n      /\\b(?:reveal|print|show|output|repeat|expose|disclose)\\s+(?:your|the)\\s+(?:system\\s+(?:prompt|message|instructions?)|hidden\\s+instructions?|initial\\s+(?:prompt|instructions?)|configuration)\\b/gi,\n    mask: '[REDACTED:imperative-pattern]',\n  },\n  {\n    name: 'role-reassignment',\n    description: '\"You are now ...\" / role-reassignment imperative family.',\n    prefilter: ['you are now', 'you are no longer', 'pretend', 'act as'],\n    regex:\n      /\\byou\\s+are\\s+(?:now|no\\s+longer)\\s+(?:a\\b|an\\b|the\\b)|\\bpretend\\s+(?:to\\s+be|you\\s+are)\\b|\\bact\\s+as\\s+(?:a|an|the|if\\s+you)\\b/gi,\n    mask: '[REDACTED:imperative-pattern]',\n  },\n  {\n    name: 'developer-mode',\n    description:\n      'Requests to enter \"developer mode\" / \"DAN\" / unrestricted modes — a long-running jailbreak family.',\n    prefilter: ['developer mode', 'admin mode', 'unrestricted'],\n    regex:\n      /\\b(?:enter|enable|activate)\\s+(?:developer|admin|debug|unrestricted|god|root)\\s+mode\\b/gi,\n    mask: '[REDACTED:imperative-pattern]',\n  },\n  {\n    name: 'jailbreak-marker',\n    description: 'Direct \"jailbreak\" markers in tool result content.',\n    prefilter: ['jailbreak', 'jailbroken'],\n    regex: /\\bjailbroken?\\s+(?:mode|response|model|assistant)\\b/gi,\n    mask: '[REDACTED:imperative-pattern]',\n  },\n  {\n    name: 'tool-call-injection',\n    description:\n      'Tool-call markers that try to coerce the model into invoking a tool from the result content.',\n    prefilter: ['<tool_use', '<function_call', '<invoke'],\n    regex: /<(?:tool_use|function_call|invoke|tool_call)\\b[^>]*>/gi,\n    mask: '[REDACTED:imperative-pattern]',\n  },\n  {\n    name: 'role-tag-injection',\n    description:\n      'Chat-role tags injected into tool results to spoof a system / assistant message in the conversation.',\n    prefilter: ['<|im_start|', '<|system|', '<|assistant|', '<|user|'],\n    regex: /<\\|(?:im_start|system|assistant|user|im_end)\\|>/gi,\n    mask: '[REDACTED:imperative-pattern]',\n  },\n];\n\n/**\n * The default-on imperative-pattern catalogue. Stable across patches;\n * additions during the pre-1.0 window are minor-bumps because new\n * patterns may produce additional `tool.inbound.sanitization.hit{...}`\n * counter increments on existing deployments.\n *\n * @stable\n */\nexport const BUILT_IN_IMPERATIVE_PATTERNS: readonly ImperativePattern[] = PATTERNS;\n\n/**\n * Combined Aho-Corasick-style prefilter set across every pattern.\n * Lower-cased substrings; consumers test the body once with the\n * combined filter before iterating regexes.\n *\n * @stable\n */\nexport const IMPERATIVE_PREFILTER_SUBSTRINGS: ReadonlyArray<string> = Object.freeze([\n  ...new Set(BUILT_IN_IMPERATIVE_PATTERNS.flatMap((p) => p.prefilter.map((s) => s.toLowerCase()))),\n]);\n\n/**\n * Compiled scan helper. Returns the list of pattern names that fired\n * AND the number of bytes the strip would remove if applied. Bounded\n * by the budget hint — when exceeded, returns `null` to let the caller\n * apply the best-effort `'detect-failed'` annotation.\n *\n * @stable\n */\nexport interface ScanResult {\n  readonly hits: ReadonlyArray<{ readonly pattern: string; readonly matchCount: number }>;\n  readonly bytesMatched: number;\n  readonly scanDurationUs: number;\n}\n\n/**\n * Run the imperative-pattern scan against `body`. Patterns are\n * iterated in catalogue order; the prefilter shortcut returns early\n * for bodies that do not contain any imperative-family substring.\n *\n * @stable\n */\nexport function scanImperativePatterns(\n  body: string,\n  patterns: ReadonlyArray<ImperativePattern> = BUILT_IN_IMPERATIVE_PATTERNS,\n  budgetMs = 5,\n): ScanResult | null {\n  const start = performance.now();\n  if (body.length === 0) {\n    return { hits: [], bytesMatched: 0, scanDurationUs: 0 };\n  }\n  const lower = body.toLowerCase();\n  let prefilterHit = false;\n  for (const sub of IMPERATIVE_PREFILTER_SUBSTRINGS) {\n    if (lower.includes(sub)) {\n      prefilterHit = true;\n      break;\n    }\n  }\n  if (!prefilterHit) {\n    return {\n      hits: [],\n      bytesMatched: 0,\n      scanDurationUs: Math.round((performance.now() - start) * 1000),\n    };\n  }\n  const hits: { pattern: string; matchCount: number }[] = [];\n  let bytesMatched = 0;\n  for (const pattern of patterns) {\n    if (performance.now() - start > budgetMs) return null;\n    const localPrefilterMatch = pattern.prefilter.some((sub) => lower.includes(sub.toLowerCase()));\n    if (!localPrefilterMatch) continue;\n    let matchCount = 0;\n    pattern.regex.lastIndex = 0;\n    let match: RegExpExecArray | null = pattern.regex.exec(body);\n    while (match !== null) {\n      matchCount++;\n      bytesMatched += match[0].length;\n      if (pattern.regex.lastIndex === match.index) {\n        pattern.regex.lastIndex = match.index + 1;\n      }\n      match = pattern.regex.exec(body);\n    }\n    if (matchCount > 0) {\n      hits.push({ pattern: pattern.name as string, matchCount });\n    }\n  }\n  return {\n    hits,\n    bytesMatched,\n    scanDurationUs: Math.round((performance.now() - start) * 1000),\n  };\n}\n\n/**\n * Apply `pattern.mask` to every match of every pattern in `body`. Used\n * by the `'detect-and-strip*'` policies. The mask is calibrated to NOT\n * match any imperative pattern itself, so post-strip bodies do not\n * trigger another scan hit on round trips.\n *\n * @stable\n */\nexport function stripImperativePatterns(\n  body: string,\n  patterns: ReadonlyArray<ImperativePattern> = BUILT_IN_IMPERATIVE_PATTERNS,\n): string {\n  let out = body;\n  for (const pattern of patterns) {\n    out = out.replace(pattern.regex, pattern.mask);\n  }\n  return out;\n}\n"],"mappings":";AAkEA,MAAMA,WAAyC;CAC7C;EACE,MAAM;EACN,aACE;EACF,WAAW;GAAC;GAAU;GAAa;GAAS;EAC5C,OACE;EACF,MAAM;EACP;CACD;EACE,MAAM;EACN,aAAa;EACb,WAAW;GAAC;GAAU;GAAS;GAAQ;EACvC,OACE;EACF,MAAM;EACP;CACD;EACE,MAAM;EACN,aAAa;EACb,WAAW;GAAC;GAAY;GAAoB;GAAwB;GAAU;EAC9E,OACE;EACF,MAAM;EACP;CACD;EACE,MAAM;EACN,aACE;EACF,WAAW;GAAC;GAAiB;GAAkB;GAAU;GAAS;GAAO;EACzE,OACE;EACF,MAAM;EACP;CACD;EACE,MAAM;EACN,aAAa;EACb,WAAW;GAAC;GAAe;GAAqB;GAAW;GAAS;EACpE,OACE;EACF,MAAM;EACP;CACD;EACE,MAAM;EACN,aACE;EACF,WAAW;GAAC;GAAkB;GAAc;GAAe;EAC3D,OACE;EACF,MAAM;EACP;CACD;EACE,MAAM;EACN,aAAa;EACb,WAAW,CAAC,aAAa,aAAa;EACtC,OAAO;EACP,MAAM;EACP;CACD;EACE,MAAM;EACN,aACE;EACF,WAAW;GAAC;GAAa;GAAkB;GAAU;EACrD,OAAO;EACP,MAAM;EACP;CACD;EACE,MAAM;EACN,aACE;EACF,WAAW;GAAC;GAAe;GAAa;GAAgB;GAAU;EAClE,OAAO;EACP,MAAM;EACP;CACF;;;;;;;;;AAUD,MAAaC,+BAA6D;;;;;;;;AAS1E,MAAaC,kCAAyD,OAAO,OAAO,CAClF,GAAG,IAAI,IAAI,6BAA6B,SAAS,MAAM,EAAE,UAAU,KAAK,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,CACjG,CAAC;;;;;;;;AAuBF,SAAgB,uBACd,MACA,WAA6C,8BAC7C,WAAW,GACQ;CACnB,MAAM,QAAQ,YAAY,KAAK;AAC/B,KAAI,KAAK,WAAW,EAClB,QAAO;EAAE,MAAM,EAAE;EAAE,cAAc;EAAG,gBAAgB;EAAG;CAEzD,MAAM,QAAQ,KAAK,aAAa;CAChC,IAAI,eAAe;AACnB,MAAK,MAAM,OAAO,gCAChB,KAAI,MAAM,SAAS,IAAI,EAAE;AACvB,iBAAe;AACf;;AAGJ,KAAI,CAAC,aACH,QAAO;EACL,MAAM,EAAE;EACR,cAAc;EACd,gBAAgB,KAAK,OAAO,YAAY,KAAK,GAAG,SAAS,IAAK;EAC/D;CAEH,MAAMC,OAAkD,EAAE;CAC1D,IAAI,eAAe;AACnB,MAAK,MAAM,WAAW,UAAU;AAC9B,MAAI,YAAY,KAAK,GAAG,QAAQ,SAAU,QAAO;AAEjD,MAAI,CADwB,QAAQ,UAAU,MAAM,QAAQ,MAAM,SAAS,IAAI,aAAa,CAAC,CAAC,CACpE;EAC1B,IAAI,aAAa;AACjB,UAAQ,MAAM,YAAY;EAC1B,IAAIC,QAAgC,QAAQ,MAAM,KAAK,KAAK;AAC5D,SAAO,UAAU,MAAM;AACrB;AACA,mBAAgB,MAAM,GAAG;AACzB,OAAI,QAAQ,MAAM,cAAc,MAAM,MACpC,SAAQ,MAAM,YAAY,MAAM,QAAQ;AAE1C,WAAQ,QAAQ,MAAM,KAAK,KAAK;;AAElC,MAAI,aAAa,EACf,MAAK,KAAK;GAAE,SAAS,QAAQ;GAAgB;GAAY,CAAC;;AAG9D,QAAO;EACL;EACA;EACA,gBAAgB,KAAK,OAAO,YAAY,KAAK,GAAG,SAAS,IAAK;EAC/D;;;;;;;;;;AAWH,SAAgB,wBACd,MACA,WAA6C,8BACrC;CACR,IAAI,MAAM;AACV,MAAK,MAAM,WAAW,SACpB,OAAM,IAAI,QAAQ,QAAQ,OAAO,QAAQ,KAAK;AAEhD,QAAO"}

package/dist/redaction/index.d.ts

@@ -0,0 +1,7 @@
+import { ALL_BUILT_IN_PATTERNS, BUILT_IN_PATTERNS, BuiltInPatternName, OPT_IN_PATTERNS, PatternCategory, RedactionPattern } from "./patterns.js";
+import { RedactionCounters, RedactionInput, RedactionOutput, RedactionValidator, RedactionValidatorInstance, RedactionValidatorOptions, RedactionViolation, RedactionViolationCallback } from "./types.js";
+import { DEFAULT_VALIDATION_CONFIG, ValidationConfig } from "./config.js";
+import { RedactionValidationError, UnvalidatedExporterError } from "./errors.js";
+import { BUILT_IN_IMPERATIVE_PATTERNS, IMPERATIVE_PREFILTER_SUBSTRINGS, ImperativePattern, ImperativePatternName, ScanResult, scanImperativePatterns, stripImperativePatterns } from "./imperative-patterns.js";
+import { compareSensitivityTiers, createRedactionValidator } from "./validator.js";
+export { ALL_BUILT_IN_PATTERNS, BUILT_IN_IMPERATIVE_PATTERNS, BUILT_IN_PATTERNS, type BuiltInPatternName, DEFAULT_VALIDATION_CONFIG, IMPERATIVE_PREFILTER_SUBSTRINGS, type ImperativePattern, type ImperativePatternName, type ScanResult as ImperativeScanResult, OPT_IN_PATTERNS, type PatternCategory, type RedactionCounters, type RedactionInput, type RedactionOutput, type RedactionPattern, RedactionValidationError, type RedactionValidator, type RedactionValidatorInstance, type RedactionValidatorOptions, type RedactionViolation, type RedactionViolationCallback, UnvalidatedExporterError, type ValidationConfig, compareSensitivityTiers, createRedactionValidator, scanImperativePatterns, stripImperativePatterns };

package/dist/redaction/index.js

@@ -0,0 +1,7 @@
+import { RedactionValidationError, UnvalidatedExporterError } from "./errors.js";
+import { ALL_BUILT_IN_PATTERNS, BUILT_IN_PATTERNS, OPT_IN_PATTERNS } from "./patterns.js";
+import { compareSensitivityTiers, createRedactionValidator } from "./validator.js";
+import { DEFAULT_VALIDATION_CONFIG } from "./config.js";
+import { BUILT_IN_IMPERATIVE_PATTERNS, IMPERATIVE_PREFILTER_SUBSTRINGS, scanImperativePatterns, stripImperativePatterns } from "./imperative-patterns.js";
+
+export { ALL_BUILT_IN_PATTERNS, BUILT_IN_IMPERATIVE_PATTERNS, BUILT_IN_PATTERNS, DEFAULT_VALIDATION_CONFIG, IMPERATIVE_PREFILTER_SUBSTRINGS, OPT_IN_PATTERNS, RedactionValidationError, UnvalidatedExporterError, compareSensitivityTiers, createRedactionValidator, scanImperativePatterns, stripImperativePatterns };

package/dist/redaction/patterns.d.ts

@@ -0,0 +1,85 @@
+//#region src/redaction/patterns.d.ts
+/**
+ * Built-in PII / secret detection patterns. The catalogue is intentionally
+ * conservative — every pattern has both positive and negative test
+ * fixtures and is documented so operators understand exactly what is
+ * matched.
+ *
+ * The catalogue is split into two groups:
+ *
+ * - **secret** — credentials, API tokens, JWTs, private keys. Matches
+ *   are always dropped + counted, regardless of the configured tier
+ *   floor.
+ * - **pii** — email / phone / IBAN / credit card / SSN / IP address.
+ *   Subject to the configured tier floor + per-pattern enable / disable
+ *   knobs.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Stable pattern identifier. The catalogue is curated; user-supplied
+ * patterns can use any identifier they want and will be passed through
+ * the validator in addition to the built-ins.
+ *
+ * @stable
+ */
+type BuiltInPatternName = 'graphorin-token' | 'openai-key' | 'anthropic-key' | 'aws-access-key' | 'gcp-service-account' | 'github-pat' | 'jwt' | 'bearer-header' | 'basic-auth' | 'private-key-pem' | 'email' | 'creditcard' | 'us-ssn' | 'phone-e164' | 'iban' | 'ipv4' | 'ipv6';
+/**
+ * Pattern category — `secret` matches always force a drop; `pii`
+ * matches respect the configured `enabledPatterns` allow-list.
+ *
+ * @stable
+ */
+type PatternCategory = 'secret' | 'pii';
+/**
+ * One entry in the redaction catalogue.
+ *
+ * @stable
+ */
+interface RedactionPattern {
+  readonly name: string;
+  readonly category: PatternCategory;
+  readonly description: string;
+  readonly regex: RegExp;
+  /** Replacement string used when `mode === 'mask'`. */
+  readonly mask?: string;
+  /**
+   * Optional per-match predicate (RP-21). When present, a regex hit is only
+   * treated as a real match — and masked — when this returns `true` for the
+   * matched substring. Used by the `creditcard` pattern to require a valid
+   * Luhn checksum so look-alike digit runs (epoch-ms timestamps, order ids)
+   * are not corrupted.
+   */
+  readonly verify?: (match: string) => boolean;
+  /**
+   * Optional opt-in flag. When `true` the pattern is **not** active by
+   * default; operators must add it to `enabledPatterns` explicitly. Used
+   * by the IPv4 / IPv6 patterns because raw IPs frequently appear in
+   * non-PII log lines (host headers, debug traces, …).
+   */
+  readonly optIn?: boolean;
+}
+/**
+ * The 14 default-on built-in patterns (the IPv4 and IPv6 detectors are
+ * opt-in and live in {@link OPT_IN_PATTERNS}).
+ *
+ * @stable
+ */
+declare const BUILT_IN_PATTERNS: readonly RedactionPattern[];
+/**
+ * Patterns that are recognised by the validator but are NOT enabled by
+ * default. Use them via `patterns: [...BUILT_IN_PATTERNS, ...OPT_IN_PATTERNS]`.
+ *
+ * @stable
+ */
+declare const OPT_IN_PATTERNS: readonly RedactionPattern[];
+/**
+ * Full registry — for tooling that wants to introspect every pattern
+ * the framework knows about (e.g. CLI `graphorin redaction list`).
+ *
+ * @stable
+ */
+declare const ALL_BUILT_IN_PATTERNS: readonly RedactionPattern[];
+//#endregion
+export { ALL_BUILT_IN_PATTERNS, BUILT_IN_PATTERNS, BuiltInPatternName, OPT_IN_PATTERNS, PatternCategory, RedactionPattern };
+//# sourceMappingURL=patterns.d.ts.map

package/dist/redaction/patterns.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"patterns.d.ts","names":[],"sources":["../../src/redaction/patterns.ts"],"sourcesContent":[],"mappings":";;AAyBA;AAyBA;AAOA;AA+JA;AAUA;AAUA;;;;;;;;;;;;;;;;;;KAnNY,kBAAA;;;;;;;KAyBA,eAAA;;;;;;UAOK,gBAAA;;qBAEI;;kBAEH;;;;;;;;;;;;;;;;;;;;;;;;;cA2JL,4BAA4B;;;;;;;cAU5B,0BAA0B;;;;;;;cAU1B,gCAAgC"}

package/dist/redaction/patterns.js

@@ -0,0 +1,172 @@
+//#region src/redaction/patterns.ts
+const PATTERNS = [
+	{
+		name: "graphorin-token",
+		category: "secret",
+		description: "Graphorin server token (`kru_<env>_v1_<entropy>_<crc32>`).",
+		regex: /kru_(?:dev|test|prod)_v1_[A-Za-z0-9]{20,80}_[A-Za-z0-9]{6}/g,
+		mask: "[REDACTED graphorin-token]"
+	},
+	{
+		name: "openai-key",
+		category: "secret",
+		description: "OpenAI API key (`sk-...`).",
+		regex: /\bsk-[A-Za-z0-9_-]{20,}\b/g,
+		mask: "[REDACTED openai-key]"
+	},
+	{
+		name: "anthropic-key",
+		category: "secret",
+		description: "Anthropic API key (`sk-ant-...`).",
+		regex: /\bsk-ant-[A-Za-z0-9_-]{20,}\b/g,
+		mask: "[REDACTED anthropic-key]"
+	},
+	{
+		name: "aws-access-key",
+		category: "secret",
+		description: "AWS access-key id (`AKIA...`).",
+		regex: /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/g,
+		mask: "[REDACTED aws-access-key]"
+	},
+	{
+		name: "gcp-service-account",
+		category: "secret",
+		description: "GCP service-account email (`...@...iam.gserviceaccount.com`). Opt-in; the `email` pattern already redacts the address shape; this entry exists for operators wanting the explicit `gcp-service-account` counter label.",
+		regex: /[A-Za-z0-9._-]+@[A-Za-z0-9-]+\.iam\.gserviceaccount\.com\b/g,
+		mask: "[REDACTED gcp-service-account]",
+		optIn: true
+	},
+	{
+		name: "github-pat",
+		category: "secret",
+		description: "GitHub personal-access token / OAuth token / app token.",
+		regex: /\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{36,255}\b/g,
+		mask: "[REDACTED github-pat]"
+	},
+	{
+		name: "jwt",
+		category: "secret",
+		description: "JSON Web Token (`eyJ...`).",
+		regex: /\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/g,
+		mask: "[REDACTED jwt]"
+	},
+	{
+		name: "bearer-header",
+		category: "secret",
+		description: "`Authorization: Bearer ...` header values.",
+		regex: /\bBearer\s+[A-Za-z0-9._-]{16,}\b/gi,
+		mask: "Bearer [REDACTED]"
+	},
+	{
+		name: "basic-auth",
+		category: "secret",
+		description: "`Authorization: Basic ...` header values.",
+		regex: /\bBasic\s+[A-Za-z0-9+/=]{16,}\b/gi,
+		mask: "Basic [REDACTED]"
+	},
+	{
+		name: "private-key-pem",
+		category: "secret",
+		description: "PEM private-key block (`-----BEGIN ... PRIVATE KEY-----`).",
+		regex: /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]+?-----END [A-Z ]*PRIVATE KEY-----/g,
+		mask: "[REDACTED private-key-pem]"
+	},
+	{
+		name: "email",
+		category: "pii",
+		description: "RFC-5322-ish email address.",
+		regex: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g,
+		mask: "[REDACTED email]"
+	},
+	{
+		name: "creditcard",
+		category: "pii",
+		description: "Credit card number (13–19 digits, optional spaces / dashes; Luhn-checked).",
+		regex: /\b(?:\d[\s-]*?){13,19}\b/g,
+		mask: "[REDACTED creditcard]",
+		verify: isLuhnValid
+	},
+	{
+		name: "us-ssn",
+		category: "pii",
+		description: "US Social Security Number (`123-45-6789`).",
+		regex: /\b\d{3}-\d{2}-\d{4}\b/g,
+		mask: "[REDACTED us-ssn]"
+	},
+	{
+		name: "phone-e164",
+		category: "pii",
+		description: "E.164 phone number (`+11234567890`).",
+		regex: /\+\d{7,15}\b/g,
+		mask: "[REDACTED phone-e164]"
+	},
+	{
+		name: "iban",
+		category: "pii",
+		description: "IBAN (2-letter country + 2 check digits + up to 30 alphanumerics).",
+		regex: /\b[A-Z]{2}\d{2}[A-Z0-9]{11,30}\b/g,
+		mask: "[REDACTED iban]"
+	},
+	{
+		name: "ipv4",
+		category: "pii",
+		description: "IPv4 dotted-quad address. Opt-in (often appears legitimately in logs).",
+		regex: /\b(?:\d{1,3}\.){3}\d{1,3}\b/g,
+		mask: "[REDACTED ipv4]",
+		optIn: true
+	},
+	{
+		name: "ipv6",
+		category: "pii",
+		description: "IPv6 address (full / compressed). Opt-in.",
+		regex: /\b(?:[0-9a-fA-F]{1,4}:){2,7}[0-9a-fA-F]{1,4}\b/g,
+		mask: "[REDACTED ipv6]",
+		optIn: true
+	}
+];
+/**
+* The 14 default-on built-in patterns (the IPv4 and IPv6 detectors are
+* opt-in and live in {@link OPT_IN_PATTERNS}).
+*
+* @stable
+*/
+const BUILT_IN_PATTERNS = PATTERNS.filter((p) => p.optIn !== true);
+/**
+* Patterns that are recognised by the validator but are NOT enabled by
+* default. Use them via `patterns: [...BUILT_IN_PATTERNS, ...OPT_IN_PATTERNS]`.
+*
+* @stable
+*/
+const OPT_IN_PATTERNS = PATTERNS.filter((p) => p.optIn === true);
+/**
+* Full registry — for tooling that wants to introspect every pattern
+* the framework knows about (e.g. CLI `graphorin redaction list`).
+*
+* @stable
+*/
+const ALL_BUILT_IN_PATTERNS = PATTERNS;
+/**
+* Luhn (mod-10) checksum validator used by the `creditcard` pattern (RP-21).
+* Strips spaces / dashes, bounds the length to 13–19 digits, and verifies the
+* checksum so a digit run that merely *looks* like a PAN is not redacted.
+*/
+function isLuhnValid(value) {
+	const digits = value.replace(/\D/g, "");
+	if (digits.length < 13 || digits.length > 19) return false;
+	let sum = 0;
+	let double = false;
+	for (let i = digits.length - 1; i >= 0; i -= 1) {
+		let d = digits.charCodeAt(i) - 48;
+		if (double) {
+			d *= 2;
+			if (d > 9) d -= 9;
+		}
+		sum += d;
+		double = !double;
+	}
+	return sum % 10 === 0;
+}
+
+//#endregion
+export { ALL_BUILT_IN_PATTERNS, BUILT_IN_PATTERNS, OPT_IN_PATTERNS };
+//# sourceMappingURL=patterns.js.map