invisi-data

A lightweight, efficient utility for identifying and masking sensitive information in strings. Perfect for logging, debugging, and data sanitization without exposing sensitive data like API keys, tokens, passwords, and other credentials.

✨ Features

• 🎯 Smart Pattern Recognition: Uses predefined regex patterns to detect various types of sensitive data
• ⚡ High Performance: Optimized for handling large strings efficiently
• 🔧 Customizable: Support for custom masking patterns alongside predefined ones
• 🛡️ Type-Safe: Full TypeScript support with comprehensive type definitions
• 📦 Zero Dependencies: Lightweight with no external dependencies
• 🌐 Universal: Works in Node.js, browsers, and other JavaScript environments
• 🔗 Multiple Formats: Supports both ES modules and CommonJS

📦 Installation

npm install invisi-data

🚀 Quick Start

ES Modules (Recommended)

import { maskSensitiveData } from 'invisi-data';

const input = JSON.stringify({
    Authorization: "Bearer abc123token",
    "api-key": "sk_live_sensitive_key_123",
    password: "supersecret123"
});

const masked = maskSensitiveData(input);
console.log(masked);
// Output: {"Authorization": "Bearer ****", "api-key": "****", "password": "****"}

CommonJS

const { maskSensitiveData } = require('invisi-data');

const logData = '{"Authorization": "Bearer jwt_token_here", "user": {"password": "userpass"}}';
const sanitized = maskSensitiveData(logData);
console.log(sanitized);
// Output: {"Authorization": "Bearer ****", "user": {"password": "****"}}

📚 API Reference

maskSensitiveData(input, customPatterns?)

Masks sensitive data in the provided string using predefined and custom patterns.

Parameters

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | input | string | ✅ | The input string containing potential sensitive data | | customPatterns | MaskingPattern[] | ❌ | Optional array of custom masking patterns |

Returns

• Type: string
• Description: A new string with sensitive data replaced by ****

Throws

• InvalidInputError: When input is not a valid string or is empty/whitespace only

Type Definitions

type MaskingPattern = {
  name: string;        // Human-readable pattern name
  regex: RegExp;       // Regular expression to match sensitive data
  mask: string;        // Replacement string for matches
};

class InvalidInputError extends Error {
  name: 'InvalidInputError';
}

🔍 Supported Sensitive Data Patterns

The library automatically detects and masks the following types of sensitive information:

| Pattern Type | Example Match | Masked Result | |-------------|---------------|---------------| | Authorization Bearer | "Authorization": "Bearer abc123" | "Authorization": "Bearer ****" | | cURL Authorization | "Authorization Bearer abc123" | "Authorization Bearer ****" | | API Key | "api-key": "sk_live_123" | "api-key": "****" | | Access Token | "access_token": "token123" | "access-token": "****" | | Refresh Token | "refresh-token": "refresh123" | "refresh-token": "****" | | Client ID | "client_id": "client123" | "client-id": "****" | | ID Token | "id-token": "id123" | "id-token": "****" | | Client Secret | "client_secret": "secret123" | "client-secret": "****" | | Generic Token | "token": "abc123" | "token": "****" | | Password | "password": "mypassword" | "password": "****" | | Basic Auth | "Authorization": "Basic dXNlcjpwYXNz" | "Authorization": "Basic ****" |

Note: All patterns are case-insensitive and support both hyphen (-) and underscore (_) variations.

🎨 Advanced Usage

Custom Patterns

Create your own masking patterns for domain-specific sensitive data:

import { maskSensitiveData, createPattern } from 'invisi-data';

// Create custom patterns
const customPatterns = [
    createPattern(
        'Database Password',
        /"db_password"\s*:\s*"([^"]+)"/gi,
        '"db_password": "****"'
    ),
    createPattern(
        'SSH Private Key',
        /"ssh_key"\s*:\s*"([^"]+)"/gi,
        '"ssh_key": "****"'
    )
];

const config = JSON.stringify({
    database: {
        host: "localhost",
        db_password: "super_secret_db_pass"
    },
    deployment: {
        ssh_key: "-----BEGIN PRIVATE KEY-----\nMIIEvQ...",
        api_key: "prod_api_key_123"
    }
});

const masked = maskSensitiveData(config, customPatterns);
console.log(masked);

Real-World Scenarios

HTTP Request Logging

const httpLog = `POST /api/auth - Headers: {"Authorization": "Bearer eyJhbGci...", "Content-Type": "application/json"} - Body: {"username": "user", "password": "secret123"}`;

const sanitizedLog = maskSensitiveData(httpLog);
console.log(sanitizedLog);
// Output: POST /api/auth - Headers: {"Authorization": "Bearer ****", "Content-Type": "application/json"} - Body: {"username": "user", "password": "****"}

Configuration File Sanitization

const appConfig = {
    server: { port: 3000, host: "localhost" },
    auth: {
        "client-secret": "oauth_client_secret_xyz",
        "api-key": "prod_api_key_abc123"
    },
    database: {
        url: "postgres://localhost:5432/myapp",
        password: "db_password_456"
    }
};

const configString = JSON.stringify(appConfig);
const maskedConfig = maskSensitiveData(configString);
const parsedConfig = JSON.parse(maskedConfig);

console.log(parsedConfig);
// Sensitive values are now masked while preserving structure

Error Logging

function logError(error, context) {
    const errorInfo = {
        message: error.message,
        stack: error.stack,
        context: context  // May contain sensitive data
    };
    
    // Safely log without exposing sensitive information
    console.error(maskSensitiveData(JSON.stringify(errorInfo)));
}

⚡ Performance Characteristics

• Memory: Minimal memory footprint with pre-compiled regex patterns
• Speed: Optimized for large strings (tested with 1MB+ inputs)
• Scalability: Linear time complexity O(n) where n is input string length
• Efficiency: Single-pass string processing for all patterns

Benchmarks

• Small strings (< 1KB): ~0.1ms processing time
• Medium strings (1KB - 100KB): ~1-10ms processing time
• Large strings (100KB - 1MB): ~10-100ms processing time

🛠️ Development

Building the Project

npm run buildcjs    # Build CommonJS version

Running Tests

npm test           # Run all tests
npm run test:basic # Run basic functionality tests only
npm run test:extended # Run extended/edge case tests only

Project Structure

invisi-data/
├── index.js           # Main module (ES6)
├── patterns.js        # Pattern definitions
├── index.cjs          # CommonJS build output
├── types.d.ts         # TypeScript definitions
├── index_test.js      # Basic test suite
└── test/
    └── extended-tests.js # Extended test coverage

🤝 Contributing

We welcome contributions! Here's how you can help:

Ways to Contribute

• 🐛 Report Bugs: Open an issue with reproduction steps
• 💡 Suggest Features: Propose new patterns or functionality
• 📝 Improve Documentation: Help make our docs clearer
• 🧪 Add Tests: Increase test coverage for edge cases
• 💻 Submit Code: Fix bugs or implement new features

Development Setup

1. Fork and clone the repository
2. Run npm install to install dependencies
3. Make your changes
4. Run npm test to ensure all tests pass
5. Run npm run buildcjs to verify build works
6. Submit a pull request with a clear description

Adding New Patterns

When adding new sensitive data patterns:

1. Add the pattern to patterns.js
2. Update types.d.ts if needed
3. Add comprehensive tests in test/extended-tests.js
4. Update this README with pattern documentation

🔒 Security Considerations

• False Negatives: Some sensitive data might not match predefined patterns
• False Positives: Non-sensitive data might occasionally be masked
• Custom Patterns: Always test custom patterns thoroughly
• Data Validation: The library masks but doesn't validate data formats
• Encoding: Assumes UTF-8 string encoding

📝 Changelog

v1.2.0 (Current)

• ✨ Added modular pattern system with patterns.js
• 🛡️ Improved error handling with InvalidInputError class
• 🧪 Comprehensive test suite with 40+ test cases
• 📚 Enhanced documentation and examples
• ⚡ Performance optimizations for large strings
• 🔧 Better regex patterns supporting unicode and special characters

v1.1.2 (Previous)

• Basic masking functionality
• Limited test coverage
• Simple error handling

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Thanks to all contributors who help improve this library
• Inspired by the need for better sensitive data handling in logging systems
• Built with ❤️ for the JavaScript community

📞 Support

• 🐛 Issues: GitHub Issues
• 📖 Documentation: This README and inline code comments
• 💬 Discussions: GitHub Discussions

Made with ❤️ by kobenguyent

⭐ Star this repo if you find it helpful!