Data Masking and Tokenization

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220

// Enterprise Data Masking Service
// Applies configurable masking strategies to sensitive data
 
interface MaskingRule {
  fieldPattern: string;  // Field name pattern (regex)
  dataType: DataType;
  strategy: MaskingStrategy;
  config: MaskingConfig;
}
 
enum MaskingStrategy {
  CHARACTER_MASK = 'character_mask',
  SUBSTITUTION = 'substitution',
  HASH = 'hash',
  SHUFFLE = 'shuffle',
  VARIANCE = 'variance',
  TRUNCATE = 'truncate',
  NULLIFY = 'nullify',
  FORMAT_PRESERVING = 'format_preserving',
}
 
interface MaskingConfig {
  maskChar?: string;           // Character for masking (default: *)
  revealFirst?: number;        // Characters to show at start
  revealLast?: number;         // Characters to show at end
  hashAlgorithm?: string;      // For hash strategy
  variancePercent?: number;    // For numeric variance
  substitutionSource?: string; // Data source for substitutions
  preserveFormat?: boolean;    // Maintain character types (letter→letter)
}
 
class DataMaskingService {
  private rules: Map<string, MaskingRule[]>;
  private substitutionData: SubstitutionDataProvider;
  private deterministicSeed: string;
 
  constructor(config: MaskingServiceConfig) {
    this.rules = this.loadRules(config.rulesPath);
    this.substitutionData = new SubstitutionDataProvider(config.substitutionDb);
    this.deterministicSeed = config.seed || crypto.randomBytes(32).toString('hex');
  }
 
  async maskRecord<T extends object>(
    record: T,
    context: MaskingContext
  ): Promise<T> {
    const masked = { ...record } as any;
    
    for (const [fieldPath, value] of this.traverseObject(record)) {
      const applicableRules = this.findApplicableRules(fieldPath, value);
      
      if (applicableRules.length > 0) {
        const rule = applicableRules[0]; // First matching rule
        const maskedValue = await this.applyMasking(
          value,
          rule,
          context,
          fieldPath
        );
        this.setFieldValue(masked, fieldPath, maskedValue);
      }
    }
    
    return masked;
  }
 
  private async applyMasking(
    value: any,
    rule: MaskingRule,
    context: MaskingContext,
    fieldPath: string
  ): Promise<any> {
    if (value === null || value === undefined) {
      return value;
    }
    
    switch (rule.strategy) {
      case MaskingStrategy.CHARACTER_MASK:
        return this.characterMask(String(value), rule.config);
        
      case MaskingStrategy.SUBSTITUTION:
        return this.substitute(value, rule, context);
        
      case MaskingStrategy.HASH:
        return this.hashMask(String(value), rule.config, fieldPath);
        
      case MaskingStrategy.VARIANCE:
        return this.applyVariance(Number(value), rule.config);
        
      case MaskingStrategy.TRUNCATE:
        return this.truncate(String(value), rule.config);
        
      case MaskingStrategy.NULLIFY:
        return null;
        
      case MaskingStrategy.FORMAT_PRESERVING:
        return this.formatPreservingMask(String(value), rule.config);
        
      case MaskingStrategy.SHUFFLE:
        // Shuffle is applied at dataset level, not individual record
        throw new Error('Shuffle strategy requires dataset-level masking');
        
      default:
        return this.characterMask(String(value), { maskChar: '*' });
    }
  }
 
  private characterMask(value: string, config: MaskingConfig): string {
    const maskChar = config.maskChar || '*';
    const revealFirst = config.revealFirst || 0;
    const revealLast = config.revealLast || 0;
    
    if (value.length <= revealFirst + revealLast) {
      return maskChar.repeat(value.length);
    }
    
    const start = value.substring(0, revealFirst);
    const end = value.substring(value.length - revealLast);
    const middleLength = value.length - revealFirst - revealLast;
    const masked = maskChar.repeat(middleLength);
    
    return start + masked + end;
  }
 
  private async substitute(
    value: any,
    rule: MaskingRule,
    context: MaskingContext
  ): Promise<any> {
    // Deterministic substitution for consistency across records
    const seed = this.generateDeterministicSeed(value, context.recordId);
    
    switch (rule.dataType) {
      case DataType.NAME:
        return this.substitutionData.getRandomName(seed);
      case DataType.EMAIL:
        return this.substitutionData.getRandomEmail(seed);
      case DataType.PHONE:
        return this.substitutionData.getRandomPhone(seed);
      case DataType.ADDRESS:
        return this.substitutionData.getRandomAddress(seed);
      case DataType.SSN:
        return this.substitutionData.getRandomSSN(seed);
      default:
        return value;
    }
  }
 
  private hashMask(
    value: string,
    config: MaskingConfig,
    fieldPath: string
  ): string {
    const algorithm = config.hashAlgorithm || 'sha256';
    // Include field path and seed to prevent cross-field rainbow attacks
    const saltedValue = `${this.deterministicSeed}:${fieldPath}:${value}`;
    return crypto
      .createHash(algorithm)
      .update(saltedValue)
      .digest('hex')
      .substring(0, 16); // Truncate for readability
  }
 
  private formatPreservingMask(value: string, config: MaskingConfig): string {
    // Replace each character with same type (letter→letter, digit→digit)
    let result = '';
    const revealFirst = config.revealFirst || 0;
    const revealLast = config.revealLast || 0;
    
    for (let i = 0; i < value.length; i++) {
      if (i < revealFirst || i >= value.length - revealLast) {
        result += value[i];
      } else {
        result += this.replacePreservingFormat(value[i]);
      }
    }
    
    return result;
  }
 
  private replacePreservingFormat(char: string): string {
    if (/[a-z]/.test(char)) return 'x';
    if (/[A-Z]/.test(char)) return 'X';
    if (/[0-9]/.test(char)) return '0';
    return char; // Preserve special characters, spaces, etc.
  }
 
  private applyVariance(value: number, config: MaskingConfig): number {
    const variancePercent = config.variancePercent || 10;
    const variance = value * (variancePercent / 100);
    const offset = (Math.random() * 2 - 1) * variance;
    return Math.round(value + offset);
  }
 
  // Dataset-level shuffling for referential consistency
  async shuffleDataset(
    records: any[],
    fieldsToShuffle: string[]
  ): Promise<any[]> {
    const shuffled = records.map(r => ({ ...r }));
    
    for (const field of fieldsToShuffle) {
      // Extract all values for this field
      const values = shuffled.map(r => this.getFieldValue(r, field));
      
      // Shuffle the values array
      for (let i = values.length - 1; i > 0; i--) {
        const j = Math.floor(Math.random() * (i + 1));
        [values[i], values[j]] = [values[j], values[i]];
      }
      
      // Apply shuffled values back
      shuffled.forEach((record, index) => {
        this.setFieldValue(record, field, values[index]);
      });
    }
    
    return shuffled;
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172

// Application-Level Dynamic Data Masking
// Masks query results based on caller authorization
 
interface MaskingPolicy {
  fieldPath: string;
  defaultMask: MaskingStrategy;
  exemptRoles: string[];      // Roles that see unmasked data
  exemptPurposes: string[];   // Approved purposes for full access
}
 
interface DataAccessContext {
  userId: string;
  roles: string[];
  accessPurpose: string;
  clientType: 'internal' | 'external' | 'api';
}
 
class DynamicMaskingMiddleware {
  private policies: Map<string, MaskingPolicy>;
  private maskingService: DataMaskingService;
  private auditLogger: DataAccessAuditLogger;
 
  async processQueryResult<T>(
    results: T[],
    entityType: string,
    context: DataAccessContext
  ): Promise<T[]> {
    const entityPolicies = this.getPoliciesForEntity(entityType);
    
    if (entityPolicies.length === 0) {
      return results; // No masking policies for this entity
    }
    
    const maskedResults: T[] = [];
    const accessLog: FieldAccessLog[] = [];
    
    for (const record of results) {
      const maskedRecord = { ...record } as any;
      
      for (const policy of entityPolicies) {
        const fieldValue = this.getFieldValue(record, policy.fieldPath);
        
        if (fieldValue === undefined || fieldValue === null) {
          continue;
        }
        
        // Check if user is exempt from masking
        const isExempt = this.checkExemption(policy, context);
        
        if (!isExempt) {
          // Apply masking
          const maskedValue = await this.maskingService.maskValue(
            fieldValue,
            policy.defaultMask
          );
          this.setFieldValue(maskedRecord, policy.fieldPath, maskedValue);
          
          accessLog.push({
            field: policy.fieldPath,
            masked: true,
            reason: 'policy_enforcement',
          });
        } else {
          accessLog.push({
            field: policy.fieldPath,
            masked: false,
            reason: this.getExemptionReason(policy, context),
          });
        }
      }
      
      maskedResults.push(maskedRecord);
    }
    
    // Audit log the access
    await this.auditLogger.logDataAccess({
      userId: context.userId,
      entityType,
      recordCount: results.length,
      fieldAccess: accessLog,
      timestamp: new Date(),
      purpose: context.accessPurpose,
    });
    
    return maskedResults;
  }
 
  private checkExemption(
    policy: MaskingPolicy,
    context: DataAccessContext
  ): boolean {
    // Check role-based exemption
    if (policy.exemptRoles.some(role => context.roles.includes(role))) {
      return true;
    }
    
    // Check purpose-based exemption
    if (policy.exemptPurposes.includes(context.accessPurpose)) {
      return true;
    }
    
    return false;
  }
 
  // SQL View approach for database-level DDM
  generateMaskedView(
    tableName: string,
    policies: MaskingPolicy[],
    roleVariable: string = 'CURRENT_ROLE()'
  ): string {
    const selectClauses = [];
    const columns = this.getTableColumns(tableName);
    
    for (const column of columns) {
      const policy = policies.find(p => p.fieldPath === column.name);
      
      if (!policy) {
        selectClauses.push(column.name);
        continue;
      }
      
      // Generate CASE statement for role-based masking
      const exemptRolesStr = policy.exemptRoles
        .map(r => `'${r}'`)
        .join(', ');
      
      const maskExpression = this.generateSQLMaskExpression(
        column.name,
        column.type,
        policy.defaultMask
      );
      
      selectClauses.push(`
        CASE 
          WHEN ${roleVariable} IN (${exemptRolesStr}) THEN ${column.name}
          ELSE ${maskExpression}
        END AS ${column.name}
      `);
    }
    
    return `
      CREATE OR REPLACE VIEW ${tableName}_masked AS
      SELECT 
        ${selectClauses.join(',
        ')}
      FROM ${tableName}
    `;
  }
 
  private generateSQLMaskExpression(
    columnName: string,
    columnType: string,
    strategy: MaskingStrategy
  ): string {
    switch (strategy) {
      case MaskingStrategy.CHARACTER_MASK:
        return `CONCAT(SUBSTRING(${columnName}, 1, 1), '****')`;
        
      case MaskingStrategy.TRUNCATE:
        return `RIGHT(${columnName}, 4)`;
        
      case MaskingStrategy.NULLIFY:
        return 'NULL';
        
      case MaskingStrategy.HASH:
        return `LEFT(SHA2(${columnName}, 256), 16)`;
        
      default:
        return `'[MASKED]'`;
    }
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241

// Enterprise Tokenization Vault Service
// Securely stores sensitive data and issues non-sensitive tokens
 
interface TokenRecord {
  token: string;
  vault: string;                // Logical vault (e.g., 'payment_cards', 'ssn')
  encryptedValue: Buffer;       // AES-256-GCM encrypted original
  keyVersion: number;           // For key rotation
  metadata: TokenMetadata;
  createdAt: Date;
  expiresAt?: Date;
  accessCount: number;
  lastAccessedAt?: Date;
}
 
interface TokenMetadata {
  format: string;               // Original format for validation
  lastFour?: string;            // For display (cards, SSN)
  dataType: string;
  ownerId: string;              // Data subject ID
  createdBy: string;            // System that created token
}
 
interface TokenizationRequest {
  value: string;
  vault: string;
  ownerId: string;
  expirationDays?: number;
  preserveFormat?: boolean;
}
 
class TokenizationVaultService {
  private db: TokenDatabase;
  private keyManager: KeyManagementService;
  private auditLogger: VaultAuditLogger;
  private formatPreserver: FormatPreservingEncryptor;
 
  async tokenize(request: TokenizationRequest): Promise<TokenResult> {
    // Validate input format matches expected pattern
    this.validateFormat(request.value, request.vault);
    
    // Check for existing token (idempotency)
    const existingToken = await this.findExistingToken(
      request.value,
      request.vault,
      request.ownerId
    );
    
    if (existingToken) {
      return {
        token: existingToken.token,
        isNew: false,
        metadata: existingToken.metadata,
      };
    }
    
    // Generate token
    const token = request.preserveFormat
      ? await this.generateFormatPreservingToken(request.value, request.vault)
      : this.generateRandomToken(request.vault);
    
    // Encrypt the sensitive value
    const currentKey = await this.keyManager.getCurrentKey('tokenization');
    const encryptedValue = await this.encrypt(request.value, currentKey);
    
    // Extract safe metadata (last 4 digits, etc.)
    const metadata = this.extractSafeMetadata(request.value, request.vault);
    
    // Store token record
    const record: TokenRecord = {
      token,
      vault: request.vault,
      encryptedValue,
      keyVersion: currentKey.version,
      metadata: {
        ...metadata,
        ownerId: request.ownerId,
        createdBy: this.getCurrentSystemId(),
      },
      createdAt: new Date(),
      expiresAt: request.expirationDays
        ? new Date(Date.now() + request.expirationDays * 24 * 60 * 60 * 1000)
        : undefined,
      accessCount: 0,
    };
    
    await this.db.store(record);
    
    // Audit log
    await this.auditLogger.logTokenization({
      token,
      vault: request.vault,
      ownerId: request.ownerId,
      timestamp: new Date(),
    });
    
    return {
      token,
      isNew: true,
      metadata: record.metadata,
    };
  }
 
  async detokenize(
    token: string,
    context: DetokenizationContext
  ): Promise<string> {
    // Fetch token record
    const record = await this.db.getByToken(token);
    
    if (!record) {
      throw new TokenNotFoundError(`Token ${token} not found`);
    }
    
    // Check expiration
    if (record.expiresAt && record.expiresAt < new Date()) {
      throw new TokenExpiredError(`Token ${token} has expired`);
    }
    
    // Authorize the detokenization request
    await this.authorizeDetokenization(record, context);
    
    // Retrieve encryption key (may need old version for rotation)
    const key = await this.keyManager.getKey(
      'tokenization',
      record.keyVersion
    );
    
    // Decrypt the value
    const value = await this.decrypt(record.encryptedValue, key);
    
    // Update access metadata
    await this.db.updateAccessMetadata(token, {
      accessCount: record.accessCount + 1,
      lastAccessedAt: new Date(),
    });
    
    // Audit log
    await this.auditLogger.logDetokenization({
      token,
      vault: record.vault,
      accessedBy: context.requesterId,
      purpose: context.purpose,
      timestamp: new Date(),
    });
    
    return value;
  }
 
  async deleteToken(token: string, context: DeletionContext): Promise<void> {
    const record = await this.db.getByToken(token);
    
    if (!record) {
      return; // Idempotent deletion
    }
    
    // Verify deletion authorization
    await this.authorizeDeletion(record, context);
    
    // Delete the record (actual value is gone)
    await this.db.delete(token);
    
    // Audit log
    await this.auditLogger.logTokenDeletion({
      token,
      vault: record.vault,
      ownerId: record.metadata.ownerId,
      deletedBy: context.requesterId,
      reason: context.reason,
      timestamp: new Date(),
    });
  }
 
  // Batch operations for efficient processing
  async batchTokenize(
    requests: TokenizationRequest[]
  ): Promise<Map<string, TokenResult>> {
    const results = new Map<string, TokenResult>();
    
    // Use transaction for atomicity
    await this.db.transaction(async (tx) => {
      for (const request of requests) {
        const result = await this.tokenize(request);
        results.set(request.value, result);
      }
    });
    
    return results;
  }
 
  // For data subject rights - delete all tokens for a user
  async deleteAllForOwner(ownerId: string, reason: string): Promise<number> {
    const tokens = await this.db.getByOwner(ownerId);
    
    for (const token of tokens) {
      await this.deleteToken(token.token, {
        requesterId: 'system',
        reason: reason,
      });
    }
    
    return tokens.length;
  }
 
  private generateRandomToken(vault: string): string {
    const prefix = vault.substring(0, 3).toLowerCase();
    const random = crypto.randomBytes(16).toString('hex');
    return `${prefix}_${random}`;
  }
 
  private async generateFormatPreservingToken(
    value: string,
    vault: string
  ): Promise<string> {
    // Format-preserving encryption keeps the token the same format as original
    // Useful for systems expecting specific formats (e.g., 16-digit card number)
    return this.formatPreserver.encrypt(value, vault);
  }
 
  private extractSafeMetadata(value: string, vault: string): Partial<TokenMetadata> {
    switch (vault) {
      case 'payment_cards':
        return {
          format: 'card',
          lastFour: value.slice(-4),
          dataType: 'credit_card',
        };
      case 'ssn':
        return {
          format: 'ssn',
          lastFour: value.replace(/-/g, '').slice(-4),
          dataType: 'ssn',
        };
      default:
        return {
          format: 'general',
          dataType: vault,
        };
    }
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163

// Format-Preserving Encryption Implementation
// Uses FF1 algorithm per NIST SP 800-38G
 
interface FPEConfig {
  key: Buffer;           // 128, 192, or 256 bits
  tweak: Buffer;         // Context-specific tweak
  alphabet: string;      // Valid characters (e.g., '0123456789')
}
 
class FormatPreservingEncryptor {
  private ff1: FF1Algorithm;
 
  constructor() {
    this.ff1 = new FF1Algorithm();
  }
 
  async encryptPreservingFormat(
    plaintext: string,
    config: FPEConfig
  ): Promise<string> {
    // Validate input contains only alphabet characters
    this.validateAlphabet(plaintext, config.alphabet);
    
    // Extract format-relevant characters and their positions
    const { extracted, template } = this.extractCharacters(
      plaintext,
      config.alphabet
    );
    
    if (extracted.length === 0) {
      return plaintext; // No encryptable characters
    }
    
    // Convert to numeric representation
    const numericPlaintext = this.toNumeric(extracted, config.alphabet);
    
    // Apply FF1 encryption
    const numericCiphertext = await this.ff1.encrypt(
      numericPlaintext,
      config.key,
      config.tweak,
      config.alphabet.length
    );
    
    // Convert back to original alphabet
    const encryptedChars = this.fromNumeric(
      numericCiphertext,
      config.alphabet
    );
    
    // Reinsert into original format template
    return this.applyTemplate(encryptedChars, template);
  }
 
  async decryptPreservingFormat(
    ciphertext: string,
    config: FPEConfig
  ): Promise<string> {
    const { extracted, template } = this.extractCharacters(
      ciphertext,
      config.alphabet
    );
    
    const numericCiphertext = this.toNumeric(extracted, config.alphabet);
    
    const numericPlaintext = await this.ff1.decrypt(
      numericCiphertext,
      config.key,
      config.tweak,
      config.alphabet.length
    );
    
    const decryptedChars = this.fromNumeric(
      numericPlaintext,
      config.alphabet
    );
    
    return this.applyTemplate(decryptedChars, template);
  }
 
  // Extract alphabet characters while preserving format template
  private extractCharacters(
    input: string,
    alphabet: string
  ): { extracted: string; template: (number | string)[] } {
    const extracted: string[] = [];
    const template: (number | string)[] = [];
    let extractedIndex = 0;
    
    for (const char of input) {
      if (alphabet.includes(char)) {
        extracted.push(char);
        template.push(extractedIndex++);
      } else {
        template.push(char); // Non-alphabet char preserved in template
      }
    }
    
    return {
      extracted: extracted.join(''),
      template,
    };
  }
 
  // Apply encrypted characters back into format template
  private applyTemplate(
    chars: string,
    template: (number | string)[]
  ): string {
    let result = '';
    
    for (const item of template) {
      if (typeof item === 'number') {
        result += chars[item];
      } else {
        result += item; // Preserved non-alphabet character
      }
    }
    
    return result;
  }
 
  // Example: Encrypt credit card preserving format
  encryptCreditCard(cardNumber: string, key: Buffer): Promise<string> {
    // Remove spaces/dashes for encryption, preserve positions
    const config: FPEConfig = {
      key,
      tweak: Buffer.from('credit_card'), // Domain-specific tweak
      alphabet: '0123456789',
    };
    
    return this.encryptPreservingFormat(cardNumber, config);
  }
 
  // Example: Encrypt SSN preserving format
  encryptSSN(ssn: string, key: Buffer): Promise<string> {
    const config: FPEConfig = {
      key,
      tweak: Buffer.from('social_security'),
      alphabet: '0123456789',
    };
    
    // Input: 123-45-6789
    // Output: xxx-xx-xxxx (different digits, same format)
    return this.encryptPreservingFormat(ssn, config);
  }
}
 
// Usage example
async function example() {
  const fpe = new FormatPreservingEncryptor();
  const key = crypto.randomBytes(32); // 256-bit key
  
  // Credit card encryption
  const card = '4532-1234-5678-9012';
  const encryptedCard = await fpe.encryptCreditCard(card, key);
  console.log(encryptedCard); // '8291-7456-3012-4567' (same format)
  
  // SSN encryption
  const ssn = '123-45-6789';
  const encryptedSSN = await fpe.encryptSSN(ssn, key);
  console.log(encryptedSSN); // '847-92-1356' (same format)
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217

// Realistic Test Data Generation Service
// Generates synthetic data that mimics production characteristics
 
import { faker } from '@faker-js/faker';
 
interface DataGenerationSchema {
  tableName: string;
  count: number;
  fields: FieldGenerator[];
  relationships?: RelationshipSpec[];
}
 
interface FieldGenerator {
  name: string;
  type: GeneratorType;
  options?: GeneratorOptions;
}
 
class TestDataGeneratorService {
  private generatedData: Map<string, any[]> = new Map();
  private relationshipResolver: RelationshipResolver;
 
  constructor() {
    this.relationshipResolver = new RelationshipResolver();
  }
 
  async generateDataset(
    schemas: DataGenerationSchema[]
  ): Promise<Map<string, any[]>> {
    // Sort by dependencies to ensure foreign keys are satisfied
    const sortedSchemas = this.topologicalSort(schemas);
    
    for (const schema of sortedSchemas) {
      const records = await this.generateTable(schema);
      this.generatedData.set(schema.tableName, records);
    }
    
    return this.generatedData;
  }
 
  private async generateTable(schema: DataGenerationSchema): Promise<any[]> {
    const records: any[] = [];
    
    for (let i = 0; i < schema.count; i++) {
      const record: any = {};
      
      for (const field of schema.fields) {
        record[field.name] = await this.generateField(field, i, schema);
      }
      
      // Resolve foreign key relationships
      if (schema.relationships) {
        for (const rel of schema.relationships) {
          record[rel.foreignKey] = this.relationshipResolver.resolve(
            rel,
            this.generatedData,
            i
          );
        }
      }
      
      records.push(record);
    }
    
    return records;
  }
 
  private async generateField(
    field: FieldGenerator,
    index: number,
    schema: DataGenerationSchema
  ): Promise<any> {
    const options = field.options || {};
    
    switch (field.type) {
      // Personal Information (all synthetic)
      case 'firstName':
        return faker.person.firstName();
        
      case 'lastName':
        return faker.person.lastName();
        
      case 'fullName':
        return faker.person.fullName();
        
      case 'email':
        // Generate unique, testable emails
        return `user${index}@testdomain-${schema.tableName}.example.com`;
        
      case 'phone':
        // Use clearly fake patterns
        return faker.phone.number('555-###-####');
        
      // Financial Data (valid format, fake values)
      case 'creditCard':
        // Generate Luhn-valid test card numbers
        return this.generateTestCreditCard(options.cardType);
        
      case 'ssn':
        // Use reserved test SSN ranges (900-999 prefix)
        return `9${faker.string.numeric(2)}-${faker.string.numeric(2)}-${faker.string.numeric(4)}`;
        
      case 'bankAccount':
        return faker.finance.accountNumber();
        
      // Addresses (real-looking but fictional)
      case 'address':
        return {
          street: faker.location.streetAddress(),
          city: faker.location.city(),
          state: faker.location.state(),
          zip: faker.location.zipCode(),
          country: 'Test Country',
        };
        
      // Temporal Data
      case 'dateOfBirth':
        return faker.date.birthdate({
          min: options.minAge || 18,
          max: options.maxAge || 80,
          mode: 'age',
        });
        
      case 'timestamp':
        return faker.date.between({
          from: options.from || new Date('2020-01-01'),
          to: options.to || new Date(),
        });
        
      // Business Data
      case 'companyName':
        return faker.company.name();
        
      case 'jobTitle':
        return faker.person.jobTitle();
        
      case 'amount':
        return faker.number.float({
          min: options.min || 0,
          max: options.max || 10000,
          multipleOf: 0.01,
        });
        
      // Sequential/Reference Fields
      case 'uuid':
        return faker.string.uuid();
        
      case 'sequence':
        return index + (options.startAt || 1);
        
      // Custom Patterns
      case 'pattern':
        return faker.helpers.replaceSymbols(options.pattern);
        
      case 'enum':
        return faker.helpers.arrayElement(options.values);
        
      case 'weighted':
        return this.weightedRandom(options.weights);
        
      default:
        return faker.lorem.word();
    }
  }
 
  private generateTestCreditCard(type?: string): string {
    // Test card numbers that pass Luhn but are clearly fake
    const testCards: Record<string, string> = {
      visa: '4111111111111111',
      mastercard: '5500000000000004',
      amex: '340000000000009',
      discover: '6011000000000004',
    };
    
    return testCards[type || 'visa'];
  }
 
  private weightedRandom(weights: Record<string, number>): string {
    const entries = Object.entries(weights);
    const total = entries.reduce((sum, [_, w]) => sum + w, 0);
    let random = Math.random() * total;
    
    for (const [value, weight] of entries) {
      random -= weight;
      if (random <= 0) return value;
    }
    
    return entries[0][0];
  }
 
  // Generate consistent test datasets for reproducible tests
  generateDeterministic(
    schemas: DataGenerationSchema[],
    seed: number
  ): Promise<Map<string, any[]>> {
    faker.seed(seed);
    return this.generateDataset(schemas);
  }
}
 
// Usage Example
const schema: DataGenerationSchema = {
  tableName: 'customers',
  count: 1000,
  fields: [
    { name: 'id', type: 'uuid' },
    { name: 'firstName', type: 'firstName' },
    { name: 'lastName', type: 'lastName' },
    { name: 'email', type: 'email' },
    { name: 'phone', type: 'phone' },
    { name: 'ssn', type: 'ssn' },
    { name: 'createdAt', type: 'timestamp' },
    { name: 'tier', type: 'weighted', options: {
      weights: { 'free': 0.7, 'premium': 0.25, 'enterprise': 0.05 }
    }},
  ],
};