@bernierllc/email-mitm-masking 1.3.0 → 1.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -14,6 +14,9 @@ const database_js_1 = require("./database.js");
14
14
  * Email masking and man-in-the-middle routing service
15
15
  */
16
16
  class EmailMaskingService {
17
+ config;
18
+ db;
19
+ cleanupInterval;
17
20
  constructor(config) {
18
21
  this.config = config;
19
22
  this.db = new pg_1.Pool({
@@ -0,0 +1,11 @@
1
+ export type EmailMitmMaskingErrorCode = 'EMAIL_MITM_MASKING_ERROR' | 'INVALID_INPUT' | 'OPERATION_FAILED';
2
+ export interface EmailMitmMaskingErrorOptions {
3
+ cause?: Error;
4
+ code?: EmailMitmMaskingErrorCode;
5
+ context?: Record<string, unknown>;
6
+ }
7
+ export declare class EmailMitmMaskingError extends Error {
8
+ readonly code: EmailMitmMaskingErrorCode;
9
+ readonly context?: Record<string, unknown>;
10
+ constructor(message: string, options?: EmailMitmMaskingErrorOptions);
11
+ }
package/dist/errors.js ADDED
@@ -0,0 +1,24 @@
1
+ "use strict";
2
+ /*
3
+ Copyright (c) 2025 Bernier LLC
4
+
5
+ This file is licensed to the client under a limited-use license.
6
+ The client may use and modify this code *only within the scope of the project it was delivered for*.
7
+ Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
8
+ */
9
+ Object.defineProperty(exports, "__esModule", { value: true });
10
+ exports.EmailMitmMaskingError = void 0;
11
+ class EmailMitmMaskingError extends Error {
12
+ code;
13
+ context;
14
+ constructor(message, options) {
15
+ super(message, options?.cause ? { cause: options.cause } : undefined);
16
+ this.name = 'EmailMitmMaskingError';
17
+ this.code = options?.code ?? 'EMAIL_MITM_MASKING_ERROR';
18
+ if (options?.context !== undefined) {
19
+ this.context = options.context;
20
+ }
21
+ Error.captureStackTrace?.(this, this.constructor);
22
+ }
23
+ }
24
+ exports.EmailMitmMaskingError = EmailMitmMaskingError;
package/dist/index.d.ts CHANGED
@@ -1,2 +1,3 @@
1
1
  export { EmailMaskingService } from './EmailMaskingService.js';
2
+ export { EmailMitmMaskingError, type EmailMitmMaskingErrorCode, type EmailMitmMaskingErrorOptions } from './errors.js';
2
3
  export type { EmailMaskingConfig, DatabaseConfig, ProxyAddress, MaskingRule, RoutingResult, RoutingAudit, MaskingResult, CreateProxyOptions, EmailContent } from './types.js';
package/dist/index.js CHANGED
@@ -7,6 +7,8 @@ The client may use and modify this code *only within the scope of the project it
7
7
  Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
8
8
  */
9
9
  Object.defineProperty(exports, "__esModule", { value: true });
10
- exports.EmailMaskingService = void 0;
10
+ exports.EmailMitmMaskingError = exports.EmailMaskingService = void 0;
11
11
  var EmailMaskingService_js_1 = require("./EmailMaskingService.js");
12
12
  Object.defineProperty(exports, "EmailMaskingService", { enumerable: true, get: function () { return EmailMaskingService_js_1.EmailMaskingService; } });
13
+ var errors_js_1 = require("./errors.js");
14
+ Object.defineProperty(exports, "EmailMitmMaskingError", { enumerable: true, get: function () { return errors_js_1.EmailMitmMaskingError; } });
package/package.json CHANGED
@@ -1,9 +1,13 @@
1
1
  {
2
2
  "name": "@bernierllc/email-mitm-masking",
3
- "version": "1.3.0",
3
+ "version": "1.5.0",
4
4
  "description": "Email masking and man-in-the-middle routing service for privacy-focused email communication",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",
7
+ "files": [
8
+ "dist/**/*",
9
+ "README.md"
10
+ ],
7
11
  "keywords": [
8
12
  "email",
9
13
  "masking",
package/.eslintrc.js DELETED
@@ -1,21 +0,0 @@
1
- module.exports = {
2
- parser: '@typescript-eslint/parser',
3
- parserOptions: {
4
- ecmaVersion: 2020,
5
- sourceType: 'module',
6
- project: './tsconfig.json',
7
- },
8
- extends: [
9
- 'eslint:recommended',
10
- 'plugin:@typescript-eslint/recommended',
11
- 'plugin:@typescript-eslint/recommended-requiring-type-checking',
12
- ],
13
- plugins: ['@typescript-eslint'],
14
- rules: {
15
- '@typescript-eslint/no-explicit-any': 'error',
16
- '@typescript-eslint/explicit-function-return-type': 'warn',
17
- '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
18
- '@typescript-eslint/no-floating-promises': 'error',
19
- },
20
- ignorePatterns: ['dist', 'node_modules', '*.js', '*.cjs'],
21
- };
package/CHANGELOG.md DELETED
@@ -1,157 +0,0 @@
1
- # Change Log
2
-
3
- All notable changes to this project will be documented in this file.
4
- See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
5
-
6
- # 1.3.0 (2026-05-20)
7
-
8
-
9
- ### Features
10
-
11
- * **contentful-types:** es2022, errors.ts with error.cause ([b74c636](https://github.com/bernierllc/tools/commit/b74c636e9c4675885c9386dcd413c5163a166ef8))
12
-
13
-
14
-
15
-
16
-
17
- ## [1.2.7](https://github.com/bernierllc/tools/compare/@bernierllc/email-mitm-masking@1.2.6...@bernierllc/email-mitm-masking@1.2.7) (2026-05-19)
18
-
19
- **Note:** Version bump only for package @bernierllc/email-mitm-masking
20
-
21
-
22
-
23
-
24
-
25
- ## [1.2.6](https://github.com/bernierllc/tools/compare/@bernierllc/email-mitm-masking@1.2.5...@bernierllc/email-mitm-masking@1.2.6) (2026-05-19)
26
-
27
- **Note:** Version bump only for package @bernierllc/email-mitm-masking
28
-
29
-
30
-
31
-
32
-
33
- ## [1.2.5](https://github.com/bernierllc/tools/compare/@bernierllc/email-mitm-masking@1.2.4...@bernierllc/email-mitm-masking@1.2.5) (2026-03-30)
34
-
35
- **Note:** Version bump only for package @bernierllc/email-mitm-masking
36
-
37
-
38
-
39
-
40
-
41
- ## [1.2.4](https://github.com/bernierllc/tools/compare/@bernierllc/email-mitm-masking@1.2.3...@bernierllc/email-mitm-masking@1.2.4) (2026-03-21)
42
-
43
- **Note:** Version bump only for package @bernierllc/email-mitm-masking
44
-
45
-
46
-
47
-
48
-
49
- ## [1.2.3](https://github.com/bernierllc/tools/compare/@bernierllc/email-mitm-masking@1.2.2...@bernierllc/email-mitm-masking@1.2.3) (2026-03-18)
50
-
51
- **Note:** Version bump only for package @bernierllc/email-mitm-masking
52
-
53
-
54
-
55
-
56
-
57
- ## [1.2.2](https://github.com/bernierllc/tools/compare/@bernierllc/email-mitm-masking@1.2.1...@bernierllc/email-mitm-masking@1.2.2) (2026-03-09)
58
-
59
- **Note:** Version bump only for package @bernierllc/email-mitm-masking
60
-
61
-
62
-
63
-
64
-
65
- ## [1.2.1](https://github.com/bernierllc/tools/compare/@bernierllc/email-mitm-masking@1.2.0...@bernierllc/email-mitm-masking@1.2.1) (2026-03-03)
66
-
67
- **Note:** Version bump only for package @bernierllc/email-mitm-masking
68
-
69
-
70
-
71
-
72
-
73
- # 1.2.0 (2025-12-25)
74
-
75
-
76
- ### Bug Fixes
77
-
78
- * **ci:** add lerna version step before publish ([3d20300](https://github.com/bernierllc/tools/commit/3d203002143bf353fffafe4f8a78a99009567347))
79
- * **ci:** correct jest testEnvironment paths for CI ([c47144c](https://github.com/bernierllc/tools/commit/c47144c3d78aec2be1e1454066c235c2227823fd))
80
- * **ci:** fix release workflow + convert internal deps to workspace:* ([01c078b](https://github.com/bernierllc/tools/commit/01c078b49d6025f7eef750f79207a1c71c8d85dc))
81
- * **jest:** move global options to root config and fix typos ([c14710c](https://github.com/bernierllc/tools/commit/c14710c11e8fc34dd7f773edf01328151564323a))
82
- * **jest:** resolve Node.js v25+ localStorage SecurityError ([8ffc512](https://github.com/bernierllc/tools/commit/8ffc512805519bc5ba523bdbcd1c457e84998c9e))
83
- * update neverhub-adapter deps to workspace:* and publish 0.1.2 ([f0e3d04](https://github.com/bernierllc/tools/commit/f0e3d04d8d4f094e3bb899ddf81e93243d16e2c2))
84
-
85
-
86
- ### Features
87
-
88
- * **email-mitm-masking:** complete implementation with 97.33% coverage ([389d51b](https://github.com/bernierllc/tools/commit/389d51b4519a12187a3b706ef7be836af0f7daae))
89
- * **service:** implement @bernierllc/email-mitm-masking package ([356ef64](https://github.com/bernierllc/tools/commit/356ef64ba497d61f5d69486cb8745577fca780d2))
90
-
91
-
92
-
93
-
94
-
95
- # 1.1.0 (2025-12-25)
96
-
97
-
98
- ### Bug Fixes
99
-
100
- * **ci:** correct jest testEnvironment paths for CI ([c47144c](https://github.com/bernierllc/tools/commit/c47144c3d78aec2be1e1454066c235c2227823fd))
101
- * **ci:** fix release workflow + convert internal deps to workspace:* ([01c078b](https://github.com/bernierllc/tools/commit/01c078b49d6025f7eef750f79207a1c71c8d85dc))
102
- * **jest:** move global options to root config and fix typos ([c14710c](https://github.com/bernierllc/tools/commit/c14710c11e8fc34dd7f773edf01328151564323a))
103
- * **jest:** resolve Node.js v25+ localStorage SecurityError ([8ffc512](https://github.com/bernierllc/tools/commit/8ffc512805519bc5ba523bdbcd1c457e84998c9e))
104
- * update neverhub-adapter deps to workspace:* and publish 0.1.2 ([f0e3d04](https://github.com/bernierllc/tools/commit/f0e3d04d8d4f094e3bb899ddf81e93243d16e2c2))
105
-
106
-
107
- ### Features
108
-
109
- * **email-mitm-masking:** complete implementation with 97.33% coverage ([389d51b](https://github.com/bernierllc/tools/commit/389d51b4519a12187a3b706ef7be836af0f7daae))
110
- * **service:** implement @bernierllc/email-mitm-masking package ([356ef64](https://github.com/bernierllc/tools/commit/356ef64ba497d61f5d69486cb8745577fca780d2))
111
-
112
-
113
-
114
-
115
-
116
- # @bernierllc/email-mitm-masking
117
-
118
- ## 1.0.5
119
-
120
- ### Patch Changes
121
-
122
- - Updated dependencies [[`73c1d1e`](https://github.com/bernierllc/tools/commit/73c1d1e46114cf2ccfd5b74b83743361247f4502), [`73c1d1e`](https://github.com/bernierllc/tools/commit/73c1d1e46114cf2ccfd5b74b83743361247f4502)]:
123
- - @bernierllc/email-sender@3.1.0
124
- - @bernierllc/logger@1.1.0
125
-
126
- ## 1.0.4
127
-
128
- ### Patch Changes
129
-
130
- - Updated dependencies [[`24899fa`](https://github.com/bernierllc/tools/commit/24899fa4eaf80ae329f7bd74483cf97a132f5d4c)]:
131
- - @bernierllc/logger@1.0.4
132
-
133
- ## 1.0.3
134
-
135
- ### Patch Changes
136
-
137
- - Updated dependencies [[`a314763`](https://github.com/bernierllc/tools/commit/a31476336717301e410da2b0b64c8f1ee44c0e8d), [`a314763`](https://github.com/bernierllc/tools/commit/a31476336717301e410da2b0b64c8f1ee44c0e8d)]:
138
- - @bernierllc/crypto-utils@1.0.4
139
- - @bernierllc/email-sender@3.0.5
140
-
141
- ## 1.0.2
142
-
143
- ### Patch Changes
144
-
145
- - Updated dependencies [[`0d8ac29`](https://github.com/bernierllc/tools/commit/0d8ac297659a9eda3fe0b0bdbc943e6dc6abc806)]:
146
- - @bernierllc/email-parser@0.1.3
147
-
148
- ## 1.0.1
149
-
150
- ### Patch Changes
151
-
152
- - [`a65f28c`](https://github.com/bernierllc/tools/commit/a65f28c2a1d09da8e8c7c23dcebd8f6606d9783f) - Fix dependency versions - update to use correct versions of crypto-utils, email-parser, and email-sender that are now published
153
-
154
- - Updated dependencies [[`a65f28c`](https://github.com/bernierllc/tools/commit/a65f28c2a1d09da8e8c7c23dcebd8f6606d9783f), [`a65f28c`](https://github.com/bernierllc/tools/commit/a65f28c2a1d09da8e8c7c23dcebd8f6606d9783f), [`a65f28c`](https://github.com/bernierllc/tools/commit/a65f28c2a1d09da8e8c7c23dcebd8f6606d9783f)]:
155
- - @bernierllc/crypto-utils@1.0.3
156
- - @bernierllc/email-parser@0.1.2
157
- - @bernierllc/email-sender@3.0.4
package/TESTING.md DELETED
@@ -1,237 +0,0 @@
1
- # Email MITM Masking - Testing Documentation
2
-
3
- ## Overview
4
-
5
- This package now includes comprehensive database mocking to enable testing without requiring a PostgreSQL database connection.
6
-
7
- ## Changes Made
8
-
9
- ### 1. Database Mock Implementation
10
-
11
- **File**: `__tests__/__mocks__/database.ts`
12
-
13
- Created an in-memory database mock that:
14
- - Implements PostgreSQL `Pool` class interface
15
- - Provides in-memory storage for `proxy_addresses` and `routing_audit` tables
16
- - Handles all SQL operations (INSERT, SELECT, UPDATE)
17
- - Maintains referential integrity and indexes
18
- - Supports UUID generation
19
- - Auto-resets between tests for isolation
20
-
21
- **Key Features**:
22
- - Zero external dependencies
23
- - Fast test execution (<1 second for all 32 tests)
24
- - Full CRUD operation support
25
- - Query pattern matching for SQL operations
26
-
27
- ### 2. Test Setup Configuration
28
-
29
- **File**: `__tests__/setup.ts`
30
-
31
- Added test setup that:
32
- - Resets mock database before each test
33
- - Ensures test isolation
34
- - Prevents state leakage between tests
35
-
36
- **File**: `jest.config.cjs`
37
-
38
- Updated Jest configuration to:
39
- - Include setup file: `setupFilesAfterEnv: ['<rootDir>/__tests__/setup.ts']`
40
- - Mock `pg` module: Maps to database mock
41
- - Mock `database.js` module: Ensures consistent mocking
42
-
43
- ### 3. Implementation Fixes
44
-
45
- Fixed two implementation issues that were preventing tests from passing:
46
-
47
- #### Issue 1: Expired Proxy Creation
48
-
49
- **Problem**: The original implementation treated all `ttl <= 0` as "no expiration", preventing creation of already-expired proxies for testing.
50
-
51
- **Fix**: Changed logic to:
52
- - Allow negative TTL values (creates already-expired proxies)
53
- - Only treat `ttl === 0` as "no expiration"
54
- - Distinguish between "undefined TTL" (use default) and "explicit 0 TTL" (no expiration)
55
-
56
- **File**: `src/EmailMaskingService.ts` (lines 81-84)
57
-
58
- ```typescript
59
- // Before
60
- const ttl = options?.ttlDays || this.config.defaultTTL || 0;
61
- const expiresAt = ttl > 0
62
- ? new Date(Date.now() + ttl * 24 * 60 * 60 * 1000)
63
- : null;
64
-
65
- // After
66
- const ttl = options?.ttlDays !== undefined ? options.ttlDays : (this.config.defaultTTL || 0);
67
- const expiresAt = ttl !== 0
68
- ? new Date(Date.now() + ttl * 24 * 60 * 60 * 1000)
69
- : null;
70
- ```
71
-
72
- #### Issue 2: Inactive Proxy Detection
73
-
74
- **Problem**: The `getProxyForContact()` method only found ACTIVE proxies, causing duplicate proxies to be created when an inactive proxy already existed for a contact.
75
-
76
- **Fix**: Changed query to:
77
- - Find ANY proxy for a user-contact pair (not just active ones)
78
- - Return most recent proxy (ORDER BY created_at DESC)
79
- - Let caller check proxy status and handle accordingly
80
-
81
- **File**: `src/EmailMaskingService.ts` (lines 280-287)
82
-
83
- ```typescript
84
- // Before
85
- SELECT * FROM proxy_addresses
86
- WHERE user_id = $1
87
- AND real_email = $2
88
- AND external_email = $3
89
- AND status = 'active'
90
- LIMIT 1
91
-
92
- // After
93
- SELECT * FROM proxy_addresses
94
- WHERE user_id = $1
95
- AND real_email = $2
96
- AND external_email = $3
97
- ORDER BY created_at DESC
98
- LIMIT 1
99
- ```
100
-
101
- ## Test Results
102
-
103
- ### Test Pass Rate
104
- - **Total Tests**: 32
105
- - **Passed**: 32 (100%)
106
- - **Failed**: 0
107
- - **Execution Time**: <1 second
108
-
109
- ### Coverage Metrics
110
-
111
- Exceeds all 85% thresholds:
112
-
113
- | Metric | Coverage | Threshold | Status |
114
- |------------|----------|-----------|--------|
115
- | Statements | 97.33% | 85% | ✅ PASS |
116
- | Branches | 96.42% | 85% | ✅ PASS |
117
- | Functions | 90.9% | 85% | ✅ PASS |
118
- | Lines | 97.29% | 85% | ✅ PASS |
119
-
120
- **Uncovered Lines**: 384-392 (cleanup interval timer - not triggered during tests)
121
-
122
- ### Build & Lint Status
123
-
124
- - ✅ **Build**: Passes with zero errors
125
- - ✅ **Lint**: Passes with zero warnings or errors
126
-
127
- ## Test Categories
128
-
129
- ### 1. Create Proxy (7 tests)
130
- - Default TTL configuration
131
- - Custom TTL values (including negative for expired proxies)
132
- - Per-contact masking with external email
133
- - Conversation ID support
134
- - Metadata attachment
135
- - User quota enforcement
136
- - Unlimited quota mode
137
-
138
- ### 2. Inbound Routing (8 tests)
139
- - Basic email routing to real address
140
- - Name <email> format parsing
141
- - Unknown proxy rejection
142
- - Inactive proxy rejection
143
- - Revoked proxy rejection
144
- - Expired proxy rejection
145
- - Missing proxy address handling
146
- - Usage statistics updates
147
-
148
- ### 3. Outbound Routing (5 tests)
149
- - Auto-creation of proxies for new contacts
150
- - Proxy reuse for known contacts
151
- - Quota limit enforcement during auto-creation
152
- - Inactive proxy rejection
153
- - Usage statistics updates
154
-
155
- ### 4. Proxy Management (5 tests)
156
- - Deactivation
157
- - Revocation
158
- - Retrieval by ID
159
- - Non-existent proxy handling
160
-
161
- ### 5. Audit Logging (2 tests)
162
- - Audit entry creation when enabled
163
- - No audit when disabled
164
-
165
- ### 6. Configuration (3 tests)
166
- - Default TTL usage
167
- - Unlimited TTL (0 value)
168
- - Proxy domain configuration
169
-
170
- ### 7. Edge Cases (3 tests)
171
- - Concurrent proxy creation (race conditions)
172
- - Empty metadata handling
173
- - Special characters in email addresses
174
-
175
- ## Running Tests
176
-
177
- ```bash
178
- # Run tests with watch mode (for development)
179
- npm test
180
-
181
- # Run tests once
182
- npm run test:run
183
-
184
- # Run tests with coverage report
185
- npm run test:coverage
186
-
187
- # Run build
188
- npm run build
189
-
190
- # Run lint
191
- npm run lint
192
- ```
193
-
194
- ## Mock Implementation Details
195
-
196
- ### SQL Operations Supported
197
-
198
- 1. **CREATE TABLE** - Schema initialization (no-op)
199
- 2. **INSERT INTO proxy_addresses** - Creates proxy with UUID generation
200
- 3. **INSERT INTO routing_audit** - Creates audit entries
201
- 4. **SELECT by ID** - Retrieves proxies by UUID
202
- 5. **SELECT by proxy_email** - Finds proxy by email address
203
- 6. **SELECT by user/real/external** - Finds proxy for specific contact pair
204
- 7. **COUNT** - Counts active proxies per user
205
- 8. **UPDATE status** - Deactivates/revokes proxies
206
- 9. **UPDATE routing stats** - Increments usage counters
207
- 10. **UPDATE expired** - Bulk expiration updates
208
-
209
- ### Data Storage
210
-
211
- - **In-memory Maps**: Stores data in JavaScript Map objects
212
- - **Indexes**: Maintains `proxy_email -> id` index for fast lookups
213
- - **UUID Generation**: Custom implementation matching PostgreSQL format
214
- - **Date Handling**: Stores as ISO strings, converts to Date objects in results
215
-
216
- ### Query Matching
217
-
218
- The mock uses SQL pattern matching to identify query types:
219
- - Normalized SQL (lowercase, trimmed)
220
- - Keyword detection (INSERT, SELECT, UPDATE, WHERE, etc.)
221
- - Parameter extraction and matching
222
- - Result formatting to match PostgreSQL structure
223
-
224
- ## Benefits
225
-
226
- 1. **No Database Required**: Tests run without PostgreSQL installation
227
- 2. **Fast Execution**: In-memory operations complete in milliseconds
228
- 3. **Deterministic**: No external dependencies or timing issues
229
- 4. **Isolated**: Each test runs with clean state
230
- 5. **Maintainable**: Mock closely mirrors actual database behavior
231
-
232
- ## Future Considerations
233
-
234
- 1. **Mock Validation**: Consider adding tests for the mock itself to ensure it matches PostgreSQL behavior
235
- 2. **Query Coverage**: Add logging for unhandled queries to catch missing implementations
236
- 3. **Performance**: Current mock handles 32 tests in <1s - monitor as test suite grows
237
- 4. **Cleanup Timer**: Consider mocking or testing the cleanup interval (lines 384-392)