@graphorin/observability 0.6.0 → 0.7.0

package/src/redaction/config.ts

@@ -0,0 +1,50 @@
+/**
+ * Configuration shape consumed by `observability.validation.*`.
+ *
+ * The shape mirrors the canonical settings so consumer configuration
+ * files can use a single typed structure.
+ *
+ * @packageDocumentation
+ */
+
+import type { Sensitivity } from '@graphorin/core';
+
+import type { RedactionPattern } from './patterns.js';
+
+/**
+ * @stable
+ */
+export interface ValidationConfig {
+  /** Lowest tier that may pass through the validator. */
+  readonly minTier?: Sensitivity;
+  /**
+   * When `true`, the validator throws on dropped values instead of
+   * silently dropping + counting. Use in tests; production should
+   * keep the default.
+   *
+   * @default false
+   */
+  readonly failOnUnredactedSensitive?: boolean;
+  /**
+   * Custom pattern catalogue. Defaults to the 14 default-on built-in
+   * patterns.
+   */
+  readonly patterns?: ReadonlyArray<RedactionPattern>;
+  /** Per-name allow-list. */
+  readonly enabledPatterns?: ReadonlyArray<string>;
+  /** Per-name deny-list. */
+  readonly disabledPatterns?: ReadonlyArray<string>;
+}
+
+/**
+ * Default validation configuration. Mirrors the runtime defaults used
+ * by `createTracer({ ... })` when `validation` is omitted.
+ *
+ * @stable
+ */
+export const DEFAULT_VALIDATION_CONFIG: Required<
+  Pick<ValidationConfig, 'minTier' | 'failOnUnredactedSensitive'>
+> = Object.freeze({
+  minTier: 'public' as const,
+  failOnUnredactedSensitive: false,
+});

package/src/redaction/errors.ts

@@ -0,0 +1,53 @@
+/**
+ * Errors thrown by the redaction layer.
+ *
+ * @packageDocumentation
+ */
+
+import type { RedactionViolation } from './types.js';
+
+/**
+ * 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
+ */
+export class RedactionValidationError extends Error {
+  /** @stable */
+  readonly kind = 'redaction-validation-failed' as const;
+  /** @stable */
+  readonly violation: RedactionViolation;
+
+  constructor(message: string, violation: RedactionViolation) {
+    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
+ */
+export class UnvalidatedExporterError extends Error {
+  /** @stable */
+  readonly kind = 'unvalidated-exporter' as const;
+  /** Exporter identifier (typically `exporter.constructor.name`). */
+  readonly exporterId: string;
+
+  constructor(exporterId: string) {
+    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;
+  }
+}

package/src/redaction/imperative-patterns.ts

@@ -0,0 +1,268 @@
+/**
+ * Imperative-pattern catalogue for inbound prompt-injection defence.
+ *
+ * Sibling to `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
+ */
+export type ImperativePatternName =
+  | 'ignore-previous-instructions'
+  | 'forget-instructions'
+  | 'override-instructions'
+  | 'system-prompt-leak'
+  | 'role-reassignment'
+  | 'developer-mode'
+  | 'jailbreak-marker'
+  | 'tool-call-injection'
+  | 'role-tag-injection'
+  | 'untrusted-content-delimiter-injection';
+
+/**
+ * One entry in the imperative-pattern catalogue. The shape mirrors
+ * `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
+ */
+export 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;
+}
+
+const PATTERNS: readonly ImperativePattern[] = [
+  {
+    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]',
+  },
+  {
+    name: 'untrusted-content-delimiter-injection',
+    description:
+      'Fabricated `<<<untrusted_content>>>` envelope delimiters inside untrusted content - an attempt to prematurely close, or spoof a nested opening of, the inbound trust envelope. The regex is scoped STRICTLY to the envelope markers (never bare `<<<` / `>>>` runs) so legitimate Python doctest / REPL `>>>` and shell heredoc fragments are untouched.',
+    // The word alone is the prefilter: any marker form the regex can
+    // match necessarily contains it, including whitespace-padded
+    // variants like `<<< untrusted_content` that a tighter
+    // `<<<untrusted_content` prefilter would miss.
+    prefilter: ['untrusted_content'],
+    regex: /<<<\s*\/?\s*untrusted_content/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
+ */
+export const BUILT_IN_IMPERATIVE_PATTERNS: readonly ImperativePattern[] = 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
+ */
+export const IMPERATIVE_PREFILTER_SUBSTRINGS: ReadonlyArray<string> = Object.freeze([
+  ...new Set(BUILT_IN_IMPERATIVE_PATTERNS.flatMap((p) => p.prefilter.map((s) => s.toLowerCase()))),
+]);
+
+/**
+ * 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
+ */
+export 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
+ */
+export function scanImperativePatterns(
+  body: string,
+  patterns: ReadonlyArray<ImperativePattern> = BUILT_IN_IMPERATIVE_PATTERNS,
+  budgetMs = 5,
+): ScanResult | null {
+  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) * 1000),
+    };
+  }
+  const hits: { pattern: string; matchCount: number }[] = [];
+  let bytesMatched = 0;
+  for (const pattern of patterns) {
+    if (performance.now() - start > budgetMs) return null;
+    const localPrefilterMatch = pattern.prefilter.some((sub) => lower.includes(sub.toLowerCase()));
+    if (!localPrefilterMatch) continue;
+    let matchCount = 0;
+    pattern.regex.lastIndex = 0;
+    let match: RegExpExecArray | null = 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 as string, matchCount });
+    }
+  }
+  return {
+    hits,
+    bytesMatched,
+    scanDurationUs: Math.round((performance.now() - start) * 1000),
+  };
+}
+
+/**
+ * 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
+ */
+export function stripImperativePatterns(
+  body: string,
+  patterns: ReadonlyArray<ImperativePattern> = BUILT_IN_IMPERATIVE_PATTERNS,
+): string {
+  let out = body;
+  for (const pattern of patterns) {
+    out = out.replace(pattern.regex, pattern.mask);
+  }
+  return out;
+}

package/src/redaction/index.ts

@@ -0,0 +1,42 @@
+/**
+ * Sensitivity-aware redaction surface for `@graphorin/observability`.
+ *
+ * The validator is the building block for the mandatory `withValidation()`
+ * wrapper applied to every exporter. It defaults to **default-deny
+ * non-public** - values declared above the tier floor are dropped + counted
+ * - and runs every value through the catalogue of built-in PII / secret
+ * patterns.
+ *
+ * @packageDocumentation
+ */
+
+export { DEFAULT_VALIDATION_CONFIG, type ValidationConfig } from './config.js';
+export { RedactionValidationError, UnvalidatedExporterError } from './errors.js';
+export {
+  BUILT_IN_IMPERATIVE_PATTERNS,
+  IMPERATIVE_PREFILTER_SUBSTRINGS,
+  type ImperativePattern,
+  type ImperativePatternName,
+  type ScanResult as ImperativeScanResult,
+  scanImperativePatterns,
+  stripImperativePatterns,
+} from './imperative-patterns.js';
+export {
+  ALL_BUILT_IN_PATTERNS,
+  BUILT_IN_PATTERNS,
+  type BuiltInPatternName,
+  OPT_IN_PATTERNS,
+  type PatternCategory,
+  type RedactionPattern,
+} from './patterns.js';
+export type {
+  RedactionCounters,
+  RedactionInput,
+  RedactionOutput,
+  RedactionValidator,
+  RedactionValidatorInstance,
+  RedactionValidatorOptions,
+  RedactionViolation,
+  RedactionViolationCallback,
+} from './types.js';
+export { compareSensitivityTiers, createRedactionValidator } from './validator.js';

package/src/redaction/patterns.ts

@@ -0,0 +1,263 @@
+/**
+ * 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
+ */
+export 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
+ */
+export type PatternCategory = 'secret' | 'pii';
+
+/**
+ * One entry in the redaction catalogue.
+ *
+ * @stable
+ */
+export 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;
+}
+
+const PATTERNS: readonly RedactionPattern[] = [
+  {
+    name: 'graphorin-token',
+    category: 'secret',
+    // Matches the DEFAULT token prefix from @graphorin/security
+    // (DEFAULT_TOKEN_PREFIX = 'gph'); deployments that configure a
+    // custom prefix must register their own pattern. The env label is
+    // matched loosely because `acceptEnvironments` is operator-extensible.
+    description: 'Graphorin server token (`gph_<env>_v1_<entropy>_<crc32>`; default prefix).',
+    regex: /gph_[a-z0-9]{2,12}_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]',
+    // RP-21: require a valid Luhn checksum so a 13-19 digit run that is not a
+    // real PAN (millisecond epoch timestamps, order numbers, …) is left alone.
+    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
+ */
+export const BUILT_IN_PATTERNS: readonly RedactionPattern[] = 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
+ */
+export const OPT_IN_PATTERNS: readonly RedactionPattern[] = 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
+ */
+export const ALL_BUILT_IN_PATTERNS: readonly RedactionPattern[] = 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: string): boolean {
+  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; // '0'
+    if (double) {
+      d *= 2;
+      if (d > 9) d -= 9;
+    }
+    sum += d;
+    double = !double;
+  }
+  return sum % 10 === 0;
+}