Crypto Utilities - rehydra.ai

Rehydra uses AES-256-GCM encryption via the Web Crypto API for securing PII maps.

Key Providers

InMemoryKeyProvider

Generates a random key in memory. Key is lost when the process ends.

import { InMemoryKeyProvider } from 'rehydra';

const keyProvider = new InMemoryKeyProvider();
const key = await keyProvider.getKey();  // Uint8Array (32 bytes)

Only for development/testing. The key is not persisted.

ConfigKeyProvider

Uses a pre-configured key from your environment.

import { ConfigKeyProvider } from 'rehydra';

// Generate key: openssl rand -base64 32
const keyBase64 = process.env.PII_ENCRYPTION_KEY;
const keyProvider = new ConfigKeyProvider(keyBase64);

KeyProvider Interface

interface KeyProvider {
  getKey(): Promise<Uint8Array>;
}

Implement for custom key storage:

class VaultKeyProvider implements KeyProvider {
  async getKey(): Promise<Uint8Array> {
    const secret = await vault.getSecret('pii-encryption-key');
    return base64ToUint8Array(secret);
  }
}

Encryption Functions

encryptPIIMap()

Encrypts a PII map.

import { encryptPIIMap } from 'rehydra';

const piiMap = new Map([
  ['EMAIL:1', 'john@example.com'],
  ['PERSON:1', 'John Smith'],
]);

const encrypted = await encryptPIIMap(piiMap, key);
// { ciphertext: '...', iv: '...', authTag: '...' }

decryptPIIMap()

Decrypts a PII map.

import { decryptPIIMap } from 'rehydra';

const piiMap = await decryptPIIMap(encrypted, key);
// Map { 'EMAIL:1' => 'john@example.com', ... }

Key Generation

generateKey()

Generate a random 256-bit key.

import { generateKey } from 'rehydra';

const key = generateKey();  // Uint8Array (32 bytes)

generateSalt()

Generate a random salt for key derivation.

import { generateSalt } from 'rehydra';

const salt = generateSalt();  // Uint8Array (16 bytes)

deriveKey()

Derive a key from a password using PBKDF2.

import { deriveKey, generateSalt } from 'rehydra';

const password = 'user-password';
const salt = generateSalt();

const key = await deriveKey(password, salt);
// Store salt with encrypted data for later derivation

Utility Functions

validateKey()

Check if a key is valid.

import { validateKey } from 'rehydra';

if (validateKey(key)) {
  console.log('Key is valid');
} else {
  throw new Error('Invalid key');
}

secureCompare()

Constant-time comparison to prevent timing attacks.

import { secureCompare } from 'rehydra';

if (secureCompare(key1, key2)) {
  console.log('Keys match');
}

uint8ArrayToBase64()

Convert Uint8Array to Base64.

import { uint8ArrayToBase64 } from 'rehydra';

const base64 = uint8ArrayToBase64(key);
// Store this string securely

base64ToUint8Array()

Convert Base64 to Uint8Array.

import { base64ToUint8Array } from 'rehydra';

const key = base64ToUint8Array(base64);

EncryptedPIIMap Structure

interface EncryptedPIIMap {
  ciphertext: string;  // Base64-encoded encrypted data
  iv: string;          // Base64-encoded initialization vector
  authTag: string;     // Base64-encoded authentication tag
}

Complete Example

import { 
  generateKey,
  encryptPIIMap,
  decryptPIIMap,
  uint8ArrayToBase64,
  base64ToUint8Array
} from 'rehydra';

// Generate and store key
const key = generateKey();
const keyBase64 = uint8ArrayToBase64(key);
// Store keyBase64 securely (env var, keychain, etc.)

// Later: encrypt
const piiMap = new Map([['EMAIL:1', 'secret@example.com']]);
const encrypted = await encryptPIIMap(piiMap, key);

// Later: decrypt
const restoredKey = base64ToUint8Array(keyBase64);
const decrypted = await decryptPIIMap(encrypted, restoredKey);

Security Notes

Key Storage

Never commit keys to version control
Use environment variables or secrets managers
Consider platform keystores (iOS Keychain, Android Keystore)

Key Rotation

Implement key rotation for long-running applications:

// Re-encrypt with new key
const piiMap = await decryptPIIMap(encrypted, oldKey);
const newEncrypted = await encryptPIIMap(piiMap, newKey);

Browser Security

In browsers:

Keys in memory can be accessed by malicious scripts
Consider using SubtleCrypto key wrapping
Clear keys when no longer needed

Encryption Concept - How encryption works
createAnonymizer - Key provider configuration

​Key Providers

​InMemoryKeyProvider

​ConfigKeyProvider

​KeyProvider Interface

​Encryption Functions

​encryptPIIMap()

​decryptPIIMap()

​Key Generation

​generateKey()

​generateSalt()

​deriveKey()

​Utility Functions

​validateKey()

​secureCompare()

​uint8ArrayToBase64()

​base64ToUint8Array()

​EncryptedPIIMap Structure

​Complete Example

​Security Notes

​Related

Key Providers

InMemoryKeyProvider

ConfigKeyProvider

KeyProvider Interface

Encryption Functions

encryptPIIMap()

decryptPIIMap()

Key Generation

generateKey()

generateSalt()

deriveKey()

Utility Functions

validateKey()

secureCompare()

uint8ArrayToBase64()

base64ToUint8Array()

EncryptedPIIMap Structure

Complete Example

Security Notes

Related