@heroku/js-blanket 0.0.0

package/README.md

@@ -0,0 +1,218 @@
+# Heroku JS Blanket
+
+A framework-agnostic sensitive data scrubbing library for logging, exception
+handling, and monitoring services for NodeJS and JavaScript projects. If you
+need to remove PII from structured data, JS Blanket has you covered.
+
+This project provides a core scrubbing engine with preset field lists for common
+PII patterns, making it easy to integrate with any logging or error monitoring
+service.
+
+## Features
+
+- **Deep Object Traversal**: Handles nested objects, arrays, and circular
+  references safely
+- **Multiple Scrubbing Modes**: Field-based, path-based, and pattern-based
+  scrubbing
+- **Immutable Operations**: Never modifies input data - always returns new
+  objects
+- **Preset Field Lists**: Battle-tested PII patterns (HEROKU_FIELDS,
+  GDPR_FIELDS, PCI_FIELDS)
+
+## Quick Start
+
+### Installation
+
+```bash
+# npm
+npm install @heroku/js-blanket
+
+# pnpm
+pnpm add @heroku/js-blanket
+
+# yarn
+yarn add @heroku/js-blanket
+```
+
+### Usage Examples
+
+Framework-specific examples
+[here](https://github.com/heroku/js-blanket/tree/main/docs/examples).
+
+## Core Scrubber API
+
+The `Scrubber` class provides flexible PII scrubbing with three modes:
+
+### Field-Based Scrubbing
+
+Scrubs values based on field names (exact match or regex):
+
+```typescript
+import { Scrubber } from '@heroku/js-blanket';
+
+const scrubber = new Scrubber({
+  fields: ['password', 'apiToken', /.*_token$/i],
+  replacement: '[REDACTED]',
+});
+
+const data = {
+  user: 'john',
+  password: 'secret123',
+  oauth_token: 'abc-def-ghi',
+};
+
+const result = scrubber.scrub(data);
+// Result: { user: 'john', password: '[REDACTED]', oauth_token: '[REDACTED]' }
+```
+
+### Path-Based Scrubbing
+
+Scrubs values at specific paths using dot notation:
+
+```typescript
+const scrubber = new Scrubber({
+  paths: ['user.email', 'user.profile.ssn'],
+});
+
+const data = {
+  user: {
+    name: 'John',
+    email: 'john@example.com',
+    profile: { ssn: '123-45-6789' },
+  },
+};
+
+const result = scrubber.scrub(data);
+// Result: { user: { name: 'John', email: '[SCRUBBED]', profile: { ssn: '[SCRUBBED]' } } }
+```
+
+### Pattern-Based Scrubbing
+
+Scrubs content matching regex patterns:
+
+```typescript
+const scrubber = new Scrubber({
+  patterns: [
+    /\b[\w._%+-]+@[\w.-]+\.[a-zA-Z]{2,}\b/g, // Email addresses
+    /\b\d{3}-\d{2}-\d{4}\b/g, // SSN patterns
+    /\b\d{13,19}\b/g, // Credit card numbers
+  ],
+});
+
+const data = {
+  message: 'Contact john@example.com or call 123-45-6789',
+};
+
+const result = scrubber.scrub(data);
+// Result: { message: 'Contact [SCRUBBED] or call [SCRUBBED]' }
+```
+
+## Preset Field Lists
+
+Use battle-tested preset field lists for common PII patterns:
+
+```typescript
+import { HEROKU_FIELDS, GDPR_FIELDS, PCI_FIELDS } from '@heroku/js-blanket';
+
+// Heroku-specific sensitive fields
+const scrubber = new Scrubber({
+  fields: HEROKU_FIELDS, // heroku_oauth_token, sudo_oauth_token, www-sso-session, etc.
+});
+
+// GDPR compliance fields
+const gdprScrubber = new Scrubber({
+  fields: GDPR_FIELDS, // email, ip_address, phone_number, ssn, date_of_birth, etc.
+});
+
+// PCI compliance fields
+const pciScrubber = new Scrubber({
+  fields: PCI_FIELDS, // credit_card, cvv, card_number, expiration_date, etc.
+});
+
+// Combine multiple presets
+const scrubber = new Scrubber({
+  fields: [...HEROKU_FIELDS, ...GDPR_FIELDS, ...PCI_FIELDS],
+});
+```
+
+## Code Quality and Testing
+
+This project uses pnpm for package management and includes comprehensive code
+quality tools to maintain high standards.
+
+### Available Scripts
+
+A list of useful scripts when developing against the codebase:
+
+```bash
+# All code quality checks and tests
+pnpm check
+
+# Run the full test suite with coverage reporting
+pnpm test
+
+# Check code quality with ESLint
+pnpm lint
+
+# Automatically fix linting issues and format code with Prettier
+pnpm format
+
+# Run TypeScript type checking
+pnpm type-check
+
+# Run the continuous integration checks (linting, type checking, and tests)
+pnpm ci
+```
+
+## Development Workflow
+
+For the best development experience:
+
+1. **Before starting work**: Ensure dependencies are installed with
+   `pnpm install`.
+2. **During development**: Run `pnpm type-check` periodically to catch type
+   errors early.
+3. **Before committing**: Run `pnpm check` to ensure all quality standards are
+   met.
+4. **Fix issues quickly**: Use `pnpm format` to auto-fix formatting and linting
+   issues.
+
+### Testing Requirements
+
+Tests are located in `src/**/*.test.ts` and run against the compiled JavaScript
+in `dist/`. The test suite includes:
+
+- Unit tests for all public APIs
+- Type safety validation tests
+- Coverage reporting with c8 (HTML and text-summary)
+
+Tests automatically run in silent mode (`LOG_LEVEL=silent`) to keep output
+clean.
+
+### Build Outputs
+
+The library produces dual builds for maximum compatibility:
+
+- **CommonJS** (`dist/cjs/`): Use for Node.js and older bundlers
+- **ES Modules** (`dist/esm/`): Use for modern bundlers and tree-shaking support
+
+Both outputs include TypeScript declaration files (`.d.ts`) for type
+information.
+
+## License
+
+Apache-2.0. See `LICENSE` for details.
+
+## Contributing
+
+We welcome issues and PRs. Please follow conventional commits, keep changes
+under 200 lines per commit, and ensure tests and type checks pass. See
+`CONTRIBUTING.md` for details.
+
+## Documentation
+
+For more detailed examples and use cases:
+
+- [Logging Integration Examples](docs/examples/logging-integration.md)
+- [Migration Guides](docs/MIGRATION.md)
+- [Project Status](docs/PROJECT-STATUS.md)

package/SECURITY.md

@@ -0,0 +1,8 @@
+## Security
+
+Please report any security issue to
+[security@salesforce.com](mailto:security@salesforce.com) as soon as it is
+discovered. This library limits its runtime dependencies in order to reduce the
+total cost of ownership as much as can be, but all consumers should remain
+vigilant and have their security stakeholders review all third-party products
+(3PP) like this one and their dependencies.