@heroku/js-blanket 0.0.0

package/src/core/types.test.ts

@@ -0,0 +1,516 @@
+/**
+ * Type Safety Tests for Core Scrubber
+ *
+ * These tests validate that TypeScript types are preserved correctly through scrubbing operations.
+ * They use compile-time type assertions to ensure type safety without runtime overhead.
+ *
+ * Run with: pnpm test (type-checked during pretest)
+ */
+
+import { expect } from 'chai';
+import { Scrubber } from './scrubber.js';
+import type { ScrubConfig, ScrubResult } from './types.js';
+
+/**
+ * Compile-time type assertion helper
+ * If T is not assignable to Expected, TypeScript will error at compile time
+ */
+type AssertType<T, Expected> = T extends Expected
+  ? Expected extends T
+    ? true
+    : never
+  : never;
+
+describe('Type Safety', () => {
+  describe('Generic Type Preservation', () => {
+    it('preserves simple object types', () => {
+      interface User {
+        name: string;
+        email: string;
+        password: string;
+      }
+
+      const scrubber = new Scrubber({ fields: ['password'] });
+      const user: User = {
+        name: 'John',
+        email: 'john@example.com',
+        password: 'secret',
+      };
+
+      const result = scrubber.scrub(user);
+
+      // Compile-time assertion: result.data should be User type
+      const typeCheck: AssertType<typeof result.data, User> = true;
+      expect(typeCheck).to.be.true;
+
+      // Runtime validation
+      expect(result.data).to.have.property('name');
+      expect(result.data).to.have.property('email');
+      expect(result.data).to.have.property('password');
+    });
+
+    it('preserves nested object types', () => {
+      interface Address {
+        street: string;
+        city: string;
+        zip: string;
+      }
+
+      interface UserProfile {
+        user: {
+          name: string;
+          email: string;
+        };
+        address: Address;
+        metadata: {
+          lastLogin: string;
+          loginCount: number;
+        };
+      }
+
+      const scrubber = new Scrubber({ fields: ['email'] });
+      const profile: UserProfile = {
+        user: { name: 'John', email: 'john@example.com' },
+        address: { street: '123 Main St', city: 'Springfield', zip: '12345' },
+        metadata: { lastLogin: '2024-01-01', loginCount: 42 },
+      };
+
+      const _result = scrubber.scrub(profile);
+
+      // Compile-time assertion
+      const typeCheck: AssertType<typeof _result.data, UserProfile> = true;
+      expect(typeCheck).to.be.true;
+    });
+
+    it('preserves array types', () => {
+      interface Item {
+        id: number;
+        name: string;
+        secret: string;
+      }
+
+      const scrubber = new Scrubber({ fields: ['secret'] });
+      const items: Item[] = [
+        { id: 1, name: 'Item 1', secret: 'secret1' },
+        { id: 2, name: 'Item 2', secret: 'secret2' },
+      ];
+
+      const result = scrubber.scrub(items);
+
+      // Compile-time assertion
+      const typeCheck: AssertType<typeof result.data, Item[]> = true;
+      expect(typeCheck).to.be.true;
+
+      // Runtime validation
+      expect(result.data).to.be.an('array');
+      expect(result.data).to.have.lengthOf(2);
+    });
+
+    it('preserves union types', () => {
+      type ComplexUnion =
+        | { type: 'user'; name: string; email: string }
+        | { type: 'admin'; name: string; permissions: string[] };
+
+      const scrubber = new Scrubber({ fields: ['email'] });
+      const data: ComplexUnion = {
+        type: 'user',
+        name: 'John',
+        email: 'john@example.com',
+      };
+
+      const _result = scrubber.scrub(data);
+
+      // Compile-time assertion
+      const typeCheck: AssertType<typeof _result.data, ComplexUnion> = true;
+      expect(typeCheck).to.be.true;
+    });
+
+    it('preserves readonly types', () => {
+      interface ReadonlyUser {
+        readonly id: number;
+        readonly name: string;
+        password: string;
+      }
+
+      const scrubber = new Scrubber({ fields: ['password'] });
+      const user: ReadonlyUser = {
+        id: 1,
+        name: 'John',
+        password: 'secret',
+      };
+
+      const result = scrubber.scrub(user);
+
+      // Compile-time assertion
+      const typeCheck: AssertType<typeof result.data, ReadonlyUser> = true;
+      expect(typeCheck).to.be.true;
+
+      // Immutability: original should not be modified
+      expect(user.password).to.equal('secret');
+      expect(result.data.password).to.equal('[SCRUBBED]');
+    });
+
+    it('preserves optional property types', () => {
+      interface PartialUser {
+        name: string;
+        email?: string;
+        phone?: string;
+        password: string;
+      }
+
+      const scrubber = new Scrubber({ fields: ['password'] });
+      const user: PartialUser = {
+        name: 'John',
+        email: 'john@example.com',
+        // phone is omitted
+        password: 'secret',
+      };
+
+      const _result = scrubber.scrub(user);
+
+      // Compile-time assertion
+      const typeCheck: AssertType<typeof _result.data, PartialUser> = true;
+      expect(typeCheck).to.be.true;
+    });
+  });
+
+  describe('ScrubResult Type', () => {
+    it('has correct result structure', () => {
+      const scrubber = new Scrubber({ fields: ['password'] });
+      const data = { user: 'john', password: 'secret' };
+      const result = scrubber.scrub(data);
+
+      // Type assertion: result should be ScrubResult
+      const typeCheck: AssertType<
+        typeof result,
+        ScrubResult<typeof data>
+      > = true;
+      expect(typeCheck).to.be.true;
+
+      // Runtime validation
+      expect(result).to.have.property('data');
+      expect(result).to.have.property('scrubbed');
+      expect(result).to.have.property('scrubbedPaths');
+      expect(result.scrubbed).to.be.a('boolean');
+      expect(result.scrubbedPaths).to.be.an('array');
+    });
+
+    it('preserves input type in result.data', () => {
+      interface Input {
+        a: string;
+        b: number;
+        c: boolean;
+      }
+
+      const scrubber = new Scrubber({ fields: ['a'] });
+      const input: Input = { a: 'test', b: 42, c: true };
+      const _result: ScrubResult<Input> = scrubber.scrub(input);
+
+      // Compile-time assertion
+      const typeCheck: AssertType<typeof _result.data, Input> = true;
+      expect(typeCheck).to.be.true;
+    });
+  });
+
+  describe('ScrubConfig Type', () => {
+    it('accepts valid configurations', () => {
+      const config1: ScrubConfig = {
+        fields: ['password', 'apiToken'],
+      };
+
+      const config2: ScrubConfig = {
+        fields: ['password', /api[-_]?key/i],
+        paths: ['user.email'],
+        patterns: [/\d{3}-\d{2}-\d{4}/g],
+        replacement: '[REDACTED]',
+      };
+
+      const config3: ScrubConfig = {
+        fields: [],
+        paths: [],
+        patterns: [],
+        recursive: false,
+      };
+
+      // All should be valid ScrubConfig types
+      expect(config1).to.be.an('object');
+      expect(config2).to.be.an('object');
+      expect(config3).to.be.an('object');
+    });
+
+    it('allows partial configurations', () => {
+      const partial1: ScrubConfig = {};
+      const partial2: ScrubConfig = { fields: ['password'] };
+      const partial3: ScrubConfig = { replacement: '[X]' };
+
+      expect(partial1).to.be.an('object');
+      expect(partial2).to.be.an('object');
+      expect(partial3).to.be.an('object');
+    });
+  });
+
+  describe('Complex Type Scenarios', () => {
+    it('handles deeply nested generic types', () => {
+      interface DeepNested<T> {
+        level1: {
+          level2: {
+            level3: {
+              level4: {
+                value: T;
+                secret: string;
+              };
+            };
+          };
+        };
+      }
+
+      const scrubber = new Scrubber({ fields: ['secret'] });
+      const data: DeepNested<number> = {
+        level1: {
+          level2: {
+            level3: {
+              level4: {
+                value: 42,
+                secret: 'hidden',
+              },
+            },
+          },
+        },
+      };
+
+      const _result = scrubber.scrub(data);
+
+      // Compile-time assertion
+      const typeCheck: AssertType<
+        typeof _result.data,
+        DeepNested<number>
+      > = true;
+      expect(typeCheck).to.be.true;
+    });
+
+    it('handles arrays of complex types', () => {
+      interface Event {
+        id: string;
+        timestamp: Date;
+        user: {
+          id: string;
+          email: string;
+        };
+        metadata: Record<string, unknown>;
+      }
+
+      const scrubber = new Scrubber({ fields: ['email'] });
+      const events: Event[] = [
+        {
+          id: '1',
+          timestamp: new Date(),
+          user: { id: 'u1', email: 'user1@example.com' },
+          metadata: { key: 'value' },
+        },
+        {
+          id: '2',
+          timestamp: new Date(),
+          user: { id: 'u2', email: 'user2@example.com' },
+          metadata: { key: 'value' },
+        },
+      ];
+
+      const _result = scrubber.scrub(events);
+
+      // Compile-time assertion
+      const typeCheck: AssertType<typeof _result.data, Event[]> = true;
+      expect(typeCheck).to.be.true;
+    });
+
+    it('handles Record types', () => {
+      type UserMap = Record<string, { name: string; password: string }>;
+
+      const scrubber = new Scrubber({ fields: ['password'] });
+      const users: UserMap = {
+        user1: { name: 'John', password: 'secret1' },
+        user2: { name: 'Jane', password: 'secret2' },
+      };
+
+      const _result = scrubber.scrub(users);
+
+      // Compile-time assertion
+      const typeCheck: AssertType<typeof _result.data, UserMap> = true;
+      expect(typeCheck).to.be.true;
+    });
+
+    it('handles mixed primitive and object types', () => {
+      interface MixedData {
+        string: string;
+        number: number;
+        boolean: boolean;
+        null: null;
+        undefined: undefined;
+        date: Date;
+        regex: RegExp;
+        object: { key: string };
+        array: number[];
+      }
+
+      const scrubber = new Scrubber({ fields: ['key'] });
+      const data: MixedData = {
+        string: 'text',
+        number: 42,
+        boolean: true,
+        null: null,
+        undefined: undefined,
+        date: new Date(),
+        regex: /test/,
+        object: { key: 'value' },
+        array: [1, 2, 3],
+      };
+
+      const _result = scrubber.scrub(data);
+
+      // Compile-time assertion
+      const typeCheck: AssertType<typeof _result.data, MixedData> = true;
+      expect(typeCheck).to.be.true;
+    });
+
+    it('handles tuple types', () => {
+      type UserTuple = [string, number, boolean, { password: string }];
+
+      const scrubber = new Scrubber({ fields: ['password'] });
+      const tuple: UserTuple = ['John', 30, true, { password: 'secret' }];
+
+      const result = scrubber.scrub(tuple);
+
+      // Note: TypeScript treats tuples as arrays at runtime, so the type is preserved
+      // but the specific tuple structure is maintained
+      expect(result.data).to.be.an('array');
+      expect(result.data).to.have.lengthOf(4);
+    });
+
+    it('preserves type safety with unknown types', () => {
+      const scrubber = new Scrubber({ fields: ['password'] });
+      const data: unknown = { user: 'john', password: 'secret' };
+
+      const _result = scrubber.scrub(data);
+
+      // Compile-time assertion: unknown in, unknown out
+      const typeCheck: AssertType<typeof _result.data, unknown> = true;
+      expect(typeCheck).to.be.true;
+    });
+  });
+
+  describe('Type Inference', () => {
+    it('infers types from literal objects', () => {
+      const scrubber = new Scrubber({ fields: ['password'] });
+
+      // Type should be inferred from the literal
+      const result = scrubber.scrub({
+        name: 'John',
+        email: 'john@example.com',
+        password: 'secret',
+      });
+
+      // TypeScript infers the exact shape
+      expect(result.data).to.have.property('name');
+      expect(result.data).to.have.property('email');
+      expect(result.data).to.have.property('password');
+    });
+
+    it('works with const assertions', () => {
+      const scrubber = new Scrubber({ fields: ['password'] });
+
+      const data = {
+        name: 'John',
+        role: 'admin',
+        password: 'secret',
+      } as const;
+
+      // Type should preserve readonly properties from const assertion
+      const result = scrubber.scrub(data);
+
+      expect(result.data.name).to.equal('John');
+      expect(result.data.role).to.equal('admin');
+    });
+  });
+
+  describe('Edge Case Types', () => {
+    it('handles empty objects', () => {
+      const scrubber = new Scrubber({ fields: ['password'] });
+      const empty = {};
+
+      const result = scrubber.scrub(empty);
+
+      const typeCheck: AssertType<typeof result.data, typeof empty> = true;
+      expect(typeCheck).to.be.true;
+      expect(result.data).to.deep.equal({});
+    });
+
+    it('handles primitives directly', () => {
+      const scrubber = new Scrubber({ fields: ['password'] });
+
+      const string = 'test';
+      const number = 42;
+      const boolean = true;
+      const nullVal = null;
+
+      expect(scrubber.scrub(string).data).to.equal(string);
+      expect(scrubber.scrub(number).data).to.equal(number);
+      expect(scrubber.scrub(boolean).data).to.equal(boolean);
+      expect(scrubber.scrub(nullVal).data).to.equal(nullVal);
+    });
+
+    it('handles circular references with type preservation', () => {
+      interface Circular {
+        name: string;
+        password: string;
+        self?: Circular;
+      }
+
+      const scrubber = new Scrubber({ fields: ['password'] });
+      const obj: Circular = {
+        name: 'test',
+        password: 'secret',
+      };
+      obj.self = obj; // Circular reference
+
+      const result = scrubber.scrub(obj);
+
+      // Type is preserved even with circular reference
+      const typeCheck: AssertType<typeof result.data, Circular> = true;
+      expect(typeCheck).to.be.true;
+      expect(result.data.name).to.equal('test');
+    });
+  });
+
+  describe('Strict TypeScript Compliance', () => {
+    it('respects noUncheckedIndexedAccess', () => {
+      const scrubber = new Scrubber({ fields: ['password'] });
+      const data: Record<string, string> = {
+        user: 'john',
+        password: 'secret',
+      };
+
+      const result = scrubber.scrub(data);
+
+      // With noUncheckedIndexedAccess, indexed access returns string | undefined
+      const value = result.data['nonexistent'];
+      expect(value).to.be.undefined;
+    });
+
+    it('respects strictNullChecks', () => {
+      interface NullableData {
+        value: string | null;
+        optional?: string;
+      }
+
+      const scrubber = new Scrubber({ fields: ['value'] });
+      const data: NullableData = {
+        value: null,
+      };
+
+      const _result = scrubber.scrub(data);
+
+      // Compile-time assertion
+      const typeCheck: AssertType<typeof _result.data, NullableData> = true;
+      expect(typeCheck).to.be.true;
+    });
+  });
+});

package/src/core/types.ts

@@ -0,0 +1,176 @@
+/**
+ * Configuration for the Scrubber
+ *
+ * Defines how the scrubber should identify and replace sensitive data.
+ * Supports three complementary scrubbing strategies:
+ *
+ * 1. **Field-based scrubbing** (`fields`): Matches field names at any depth in the object tree
+ * 2. **Path-based scrubbing** (`paths`): Matches specific dot-notation paths
+ * 3. **Pattern-based scrubbing** (`patterns`): Matches regex patterns in string content
+ *
+ * All three strategies can be used together for comprehensive data scrubbing.
+ *
+ * @example Field-based configuration
+ * ```typescript
+ * const config: ScrubConfig = {
+ *   fields: ['password', 'apiToken', /api[-_]?key/i], // Strings and regex patterns
+ *   replacement: '[REDACTED]'
+ * };
+ * ```
+ *
+ * @example Path-based configuration
+ * ```typescript
+ * const config: ScrubConfig = {
+ *   paths: [
+ *     'user.email',
+ *     'request.headers.authorization',
+ *     'items[0].password'  // Array index notation
+ *   ]
+ * };
+ * ```
+ *
+ * @example Pattern-based configuration
+ * ```typescript
+ * const config: ScrubConfig = {
+ *   patterns: [
+ *     /\b\d{3}-\d{2}-\d{4}\b/g,           // SSN
+ *     /\d{4}-\d{4}-\d{4}-\d{4}/g,        // Credit card
+ *     /[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}/g  // Email
+ *   ]
+ * };
+ * ```
+ */
+export interface ScrubConfig {
+  /**
+   * Field-based scrubbing: matches field names at any depth
+   *
+   * Supports both exact string matches and regular expressions for flexible matching.
+   * String matches are case-insensitive and use substring matching.
+   *
+   * @example
+   * ```typescript
+   * fields: [
+   *   'password',           // Matches 'password', 'Password', 'old_password', etc.
+   *   'apiToken',           // Matches 'apiToken', 'api_token', etc.
+   *   /api[-_]?key/i,       // Regex: matches 'api_key', 'api-key', 'apikey' (case insensitive)
+   *   /^secret$/            // Exact match: only 'secret', not 'my_secret'
+   * ]
+   * ```
+   */
+  fields?: (string | RegExp)[];
+
+  /**
+   * Path-based scrubbing: matches specific dot-notation paths
+   *
+   * Use dot notation to target specific fields in nested objects.
+   * Supports array index notation (e.g., `items[0].password`).
+   *
+   * @example
+   * ```typescript
+   * paths: [
+   *   'user.email',                        // Scrubs obj.user.email
+   *   'request.headers.authorization',     // Nested path
+   *   'items[0].secret',                   // Array index notation
+   *   'users[0]'                           // Scrubs entire array element
+   * ]
+   * ```
+   */
+  paths?: string[];
+
+  /**
+   * Pattern-based scrubbing: regex patterns for content scrubbing
+   *
+   * Scans string values and replaces content matching the patterns.
+   * Use the global flag (`/pattern/g`) to replace all matches in a string.
+   *
+   * **Note**: Patterns are applied to string values only, not to field names or paths.
+   *
+   * @example
+   * ```typescript
+   * patterns: [
+   *   /\b\d{3}-\d{2}-\d{4}\b/g,      // Social Security Number
+   *   /\d{4}-\d{4}-\d{4}-\d{4}/g,    // Credit Card
+   *   /Bearer\s+[A-Za-z0-9._-]+/g    // Bearer tokens
+   * ]
+   * ```
+   */
+  patterns?: RegExp[];
+
+  /**
+   * Replacement string for scrubbed values
+   *
+   * @default '[SCRUBBED]'
+   *
+   * @example
+   * ```typescript
+   * replacement: '[REDACTED]'     // Custom replacement text
+   * replacement: '***'            // Simple masking
+   * replacement: ''               // Empty string (removes content)
+   * ```
+   */
+  replacement?: string;
+
+  /**
+   * Whether to recursively scrub nested objects
+   *
+   * When `true`, the scrubber traverses the entire object tree.
+   * When `false`, only top-level fields are scrubbed.
+   *
+   * @default true
+   *
+   * @example
+   * ```typescript
+   * recursive: false  // Only scrub top-level fields
+   * ```
+   */
+  recursive?: boolean;
+}
+
+/**
+ * Result of a scrub operation
+ *
+ * Contains the scrubbed data along with metadata about what was scrubbed.
+ *
+ * @template T - The type of the scrubbed data (same as input type)
+ *
+ * @example
+ * ```typescript
+ * const scrubber = new Scrubber({ fields: ['password'] });
+ * const result = scrubber.scrub({ user: 'john', password: 'secret' });
+ *
+ * console.log(result.data);           // { user: 'john', password: '[SCRUBBED]' }
+ * console.log(result.scrubbed);       // true
+ * console.log(result.scrubbedPaths);  // ['password']
+ * ```
+ */
+export interface ScrubResult<T> {
+  /**
+   * The scrubbed data with sensitive values replaced
+   *
+   * This is a deep clone of the input with scrubbed values replaced.
+   * The original input is never mutated.
+   */
+  data: T;
+
+  /**
+   * Whether any scrubbing occurred
+   *
+   * `true` if at least one value was scrubbed, `false` if no sensitive data was found.
+   *
+   * Useful for logging or metrics to track scrubbing activity.
+   */
+  scrubbed: boolean;
+
+  /**
+   * Array of paths that were scrubbed
+   *
+   * Contains dot-notation paths for all fields that were scrubbed.
+   * Useful for debugging, auditing, or understanding what data was redacted.
+   *
+   * @example
+   * ```typescript
+   * ['password', 'user.email', 'request.headers.authorization']
+   * ```
+   */
+  scrubbedPaths: string[];
+}