@wtyczki/mcp-security

Security utilities for Cloudflare MCP servers providing output sanitization, PII redaction, and response validation.

Features

• Output Sanitization: Remove HTML tags, control characters, and dangerous encoding patterns
• PII Redaction: Detect and redact sensitive information (emails, phones, credit cards, SSNs, etc.)
• Polish Market Support: PESEL, Polish ID cards, Polish passports, Polish phone numbers
• Response Validation: Validate output format, size, and content against schema
• TypeScript Support: Full type definitions and strict type checking
• Configurable: Customize which PII types to redact and redaction placeholders
• Logging Ready: Get detailed statistics on what was sanitized/redacted

Installation

npm install @wtyczki/mcp-security
# or
yarn add @wtyczki/mcp-security
# or
pnpm add @wtyczki/mcp-security

Quick Start

Basic Usage

import { sanitizeOutput, redactPII } from '@wtyczki/mcp-security';

// Sanitize HTML and dangerous content
const sanitized = sanitizeOutput('<script>alert("xss")</script>Hello World', {
  removeHtml: true,
  maxLength: 1000,
});

// Redact PII
const { redacted, detectedPII } = redactPII(
  'Contact me at [email protected] or call 555-123-4567',
  {
    redactEmails: true,
    redactPhones: true,
  }
);

console.log(redacted); // 'Contact me at [REDACTED] or call [REDACTED]'
console.log(detectedPII); // ['email', 'phone']

Combined Approach

import { secureOutput } from '@wtyczki/mcp-security';

const { sanitized, redacted, detectedPII } = secureOutput(
  rawResult,
  {
    sanitize: { removeHtml: true, maxLength: 5000 },
    redact: { redactEmails: true, redactPhones: true, redactCreditCards: true },
  }
);

In MCP Tools

import { sanitizeOutput, redactPII } from '@wtyczki/mcp-security';

this.server.tool(
  'query_database',
  'Query sensitive data',
  schema,
  async (params) => {
    // Get data from database
    const data = await db.query(params);

    // Sanitize and redact before returning
    const sanitized = sanitizeOutput(JSON.stringify(data));
    const { redacted, detectedPII } = redactPII(sanitized, {
      redactEmails: true,
      redactPhones: true,
      redactCreditCards: true,
    });

    // Log if PII was found
    if (detectedPII.length > 0) {
      console.warn(`[Security] Detected and redacted PII: ${detectedPII.join(', ')}`);
    }

    return {
      content: [{ type: 'text', text: redacted }],
    };
  }
);

Polish Market PII (v1.1.0+)

import { redactPII } from '@wtyczki/mcp-security';

// Redact Polish PII
const { redacted, detectedPII } = redactPII(
  'Jan Kowalski, PESEL: 44051401359, Dowód: ABC123456, Tel: +48 123 456 789',
  {
    redactPESEL: true,
    redactPolishIdCard: true,
    redactPolishPhones: true,
  }
);

console.log(redacted);
// 'Jan Kowalski, PESEL: [REDACTED] (PESEL), Dowód: [REDACTED] (Polish ID), Tel: [REDACTED] (Polish Phone)'

console.log(detectedPII);
// ['pesel', 'polishIdCard', 'polishPhone']

Note on Email Redaction: In v1.1.0+, redactEmails defaults to false for Polish business use cases where email addresses are commonly shared. Enable explicitly if needed:

redactPII(text, { redactEmails: true })

API Reference

sanitizeOutput(text, options?)

Removes potentially dangerous content from text.

Options:

• removeHtml (boolean, default: true) - Remove HTML/XML tags
• maxLength (number) - Truncate output to max length
• allowedTags (string[]) - Allow specific HTML tags
• removeControlChars (boolean, default: true) - Remove control characters
• normalizeWhitespace (boolean, default: true) - Normalize whitespace
• removeEncodingPatterns (boolean, default: true) - Remove encoding tricks

Returns: Sanitized string

Example:

const output = sanitizeOutput(
  '<script>alert("xss")</script>Hello World',
  { removeHtml: true, maxLength: 100 }
);
// Result: 'Hello World'

redactPII(text, options?)

Detects and redacts personally identifiable information.

Options:

• redactEmails (boolean, default: false in v1.1.0+)
• redactPhones (boolean, default: true)
• redactCreditCards (boolean, default: true)
• redactSSN (boolean, default: true)
• redactBankAccounts (boolean, default: true)
• redactDriverLicense (boolean, default: true)
• redactPassport (boolean, default: true)
• redactIPAddresses (boolean, default: true)
• redactURLCredentials (boolean, default: true)
• Polish Market (v1.1.0+):
  • redactPESEL (boolean, default: true) - Polish National ID (11 digits)
  • redactPolishIdCard (boolean, default: true) - Polish ID card (3 letters + 6 digits)
  • redactPolishPassport (boolean, default: true) - Polish passport (2 letters + 7 digits)
  • redactPolishPhones (boolean, default: true) - Polish phone numbers (+48 prefix)
• placeholder (string, default: '[REDACTED]') - Custom redaction placeholder

Returns:

{
  redacted: string;           // Text with PII redacted
  detectedPII: string[];      // Types of PII found
  detectionDetails: {         // Details about each PII type
    emails: string[];
    phones: string[];
    creditCards: string[];
    ssns: string[];
    bankAccounts: string[];
    driverLicenses: string[];
    passports: string[];
    ipAddresses: string[];
    urlCredentials: string[];
    // Polish Market (v1.1.0+)
    peselNumbers: string[];
    polishIdCards: string[];
    polishPassports: string[];
    polishPhones: string[];
  };
}

Examples:

US/International PII:

const result = redactPII(
  'Email: [email protected], SSN: 123-45-6789',
  {
    redactEmails: true,
    redactSSN: true,
    placeholder: '***'
  }
);

console.log(result.redacted); // 'Email: ***, SSN: *** (SSN)'
console.log(result.detectedPII); // ['email', 'ssn']

Polish PII:

const result = redactPII(
  'PESEL: 44051401359, Dowód osobisty: ABC123456, Paszport: FG1234567',
  {
    redactPESEL: true,
    redactPolishIdCard: true,
    redactPolishPassport: true
  }
);

console.log(result.redacted);
// 'PESEL: [REDACTED] (PESEL), Dowód osobisty: [REDACTED] (Polish ID), Paszport: [REDACTED] (Polish Passport)'

console.log(result.detectedPII);
// ['pesel', 'polishIdCard', 'polishPassport']

console.log(result.detectionDetails);
// { peselNumbers: ['[REDACTED]'], polishIdCards: ['[REDACTED]'], polishPassports: ['[REDACTED]'], ... }

validateOutput(output, options?)

Validates output format, size, and content.

Options:

• expectedType (string - 'string' | 'object' | 'array' | 'any')
• maxSizeBytes (number) - Maximum size in bytes
• maxLength (number) - Maximum length
• warnOnErrorDetails (boolean, default: true)
• warnOnDatabaseData (boolean, default: true)
• warnOnCodeSnippets (boolean, default: false)
• allowedKeys (string[]) - For object validation

Returns:

{
  valid: boolean;
  errors: string[];
  warnings: string[];
  metadata: {
    type: string;
    size: number;
    length?: number;
    keys?: string[];
  };
}

Example:

const result = validateOutput(toolOutput, {
  expectedType: 'object',
  maxSizeBytes: 10000,
  allowedKeys: ['result', 'status']
});

if (!result.valid) {
  console.error('Validation failed:', result.errors);
}

if (result.warnings.length > 0) {
  console.warn('Validation warnings:', result.warnings);
}

hasPII(text)

Quick check if text contains any PII.

Returns: boolean

if (hasPII(output)) {
  console.warn('Output contains PII!');
}

getPIISummary(text)

Get a summary of detected PII.

Returns:

{
  hasPII: boolean;
  piiTypes: string[];
  count: number;
  summary: string;
}

const summary = getPIISummary(output);
console.log(summary.summary); // 'Found 2 PII items (email, phone)'

Polish Market PII Patterns (v1.1.0+)

Supported Polish PII Types

| PII Type | Format | Example | Detection Pattern | |----------|--------|---------|-------------------| | PESEL | 11 digits (YYMMDDNNNCS) | 44051401359 | 11-digit sequence | | Polish ID Card | 3 letters + 6 digits | ABC123456 | Pattern: [A-Z]{3}\d{6} | | Polish Passport | 2 letters + 7 digits | FG1234567 | Pattern: [A-Z]{2}\d{7} | | Polish Phone | +48 or 0048 prefix + 9 digits | +48 123 456 789 | With country code |

Why NIP and REGON Are Not Included

NIP (Tax Identification Number) and REGON (Business Registry Number) are publicly searchable in Poland through government databases:

• NIP: Available via sprawdz-nip.pl
• REGON: Available via stat.gov.pl

Since these are public business identifiers (not personal data under GDPR), they are intentionally not redacted by this library. If your use case requires redacting business identifiers, implement custom patterns.

Email Redaction Default Changed

In v1.1.0+, redactEmails defaults to false (changed from true in v1.0.0) because:

• Email addresses are commonly shared in Polish business contexts
• GDPR compliance focuses on sensitive personal data (PESEL, ID numbers)
• Reduces false positives in business communications

To enable email redaction explicitly:

redactPII(text, { redactEmails: true })

Pattern Matching Order

PII patterns are checked in priority order to avoid conflicts:

1. Most specific patterns first: Credit cards (16 digits), PESEL (11 digits), SSN (9 digits)
2. Moderately specific: Polish ID (3L+6D), Polish passport (2L+7D)
3. General patterns last: Phone numbers (10 digits), bank accounts (10-12 digits)

This prevents general patterns from matching more specific ones (e.g., 10-digit phone pattern matching PESEL).

Testing with Polish Data

import { redactPII, hasPII, getPIISummary } from '@wtyczki/mcp-security';

// Test comprehensive Polish PII detection
const testData = `
  Użytkownik: Jan Kowalski
  PESEL: 44051401359
  Dowód osobisty: ABC123456
  Paszport: FG1234567
  Telefon: +48 123 456 789
  Email: [email protected]
`;

const result = redactPII(testData, {
  redactPESEL: true,
  redactPolishIdCard: true,
  redactPolishPassport: true,
  redactPolishPhones: true,
  redactEmails: false  // Email not redacted by default
});

console.log(result.detectedPII);
// ['pesel', 'polishIdCard', 'polishPassport', 'polishPhone']

const summary = getPIISummary(testData);
console.log(summary.summary);
// 'Found 4 PII items (pesel, polishIdCard, polishPassport, polishPhone)'

Security Considerations

What This Does

• ✅ Removes HTML tags and script content
• ✅ Detects and redacts common PII patterns
• ✅ Validates output format and size
• ✅ Warns about suspicious content patterns
• ✅ Prevents information leakage in error messages

What This Doesn't Do

• ❌ Encrypt data (use TLS for transport security)
• ❌ Validate business logic
• ❌ Protect against injection at database layer (that's your responsibility)
• ❌ Provide authentication/authorization
• ❌ Detect all possible PII (patterns are pattern-based, not exhaustive)

Best Practices

1. Always sanitize before returning to LLM

   const sanitized = sanitizeOutput(data);
   const { redacted } = redactPII(sanitized);
   return { content: [{ type: 'text', text: redacted }] };

2. Log PII detection for security audits

   if (detectedPII.length > 0) {
     console.warn(`[Security] Redacted: ${detectedPII.join(', ')}`);
   }

3. Combine with AI Gateway DLP

   • Use @wtyczki/mcp-security for output-layer sanitization
   • Use Cloudflare AI Gateway DLP for input-layer detection

4. Test with realistic data

   • Include PII in test cases
   • Verify redaction works as expected

Testing

Run tests with:

npm test
npm run test:coverage  # With coverage report

Performance

• Sanitization: Sub-millisecond for typical outputs (<10KB)
• PII Redaction: 1-5ms for typical outputs (regex-based pattern matching)
• Validation: <1ms for schema validation

All functions run synchronously in-process, no external calls.

TypeScript Support

Full TypeScript support with strict type checking:

import {
  sanitizeOutput,
  redactPII,
  validateOutput,
  type SanitizationOptions,
  type PIIRedactionOptions,
  type ValidationOptions,
} from '@wtyczki/mcp-security';

Version Management

Version History

• 1.0.0 - Initial release with sanitization, PII redaction (US/international), and validation
• 1.1.0 - Polish market support (PESEL, Polish ID/passport, Polish phones) + email default changed to false
  • ✅ New: redactPESEL, redactPolishIdCard, redactPolishPassport, redactPolishPhones
  • ⚠️ Breaking behavior: redactEmails default changed from true → false (enable explicitly if needed)
  • 🐛 Fixed: Pattern matching order (specific patterns checked before general patterns)
  • 📊 Test coverage: 99%+ with comprehensive Polish PII test suite
• 2.0.0 - Future: Breaking API changes (major version bump)

Migration Guide: 1.0.0 → 1.1.0

Email redaction default changed:

// v1.0.0 behavior (emails redacted by default)
redactPII(text)  // ❌ No longer redacts emails

// v1.1.0+ behavior (emails preserved by default)
redactPII(text, { redactEmails: true })  // ✅ Enable explicitly

New Polish options (all default to true):

redactPII(text, {
  redactPESEL: true,           // Polish National ID
  redactPolishIdCard: true,    // Polish ID card
  redactPolishPassport: true,  // Polish passport
  redactPolishPhones: true,    // Polish phone numbers
})

Updating

npm install @wtyczki/mcp-security@latest
# or specific version
npm install @wtyczki/[email protected]

Contributing

Issues and PRs welcome. Please include tests for new PII patterns.

License

MIT