CEX-65 new encryption

[Dosexe]

Changes

Please describe

Checklist

• Apply one of following labels; major, minor, patch or skip-release
• I've updated the documentation, or no changes were necessary
• I've updated the tests, or no changes were necessary

[coderabbitai]

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository: lokalise/coderabbit/.coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 5fa4473c-cdfb-4534-9b58-70591217ba82

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

📝 Walkthrough

Walkthrough

The pull request introduces a new EnvelopeEncryptor module providing AES-256-GCM symmetric encryption with key rotation, deterministic HMAC-based hashing, and self-contained envelope ciphertexts formatted with a prefix and key identifier. Configuration is parsed from environment variables via a dedicated parser that validates key formats, pepper length, and active key existence. Three error types handle configuration validation and decryption failures. The deprecated EncryptionUtility is marked for migration, with new exports surfacing the EnvelopeEncryptor class, configuration type, parser, and error types in the public module entrypoint.

Sequence Diagrams

sequenceDiagram
    actor User
    participant App as Application
    participant Parser as parseEnvelopeEncryptorConfig
    participant ConfigScope
    participant Encryptor as EnvelopeEncryptor
    participant Crypto as AES-256-GCM

    User->>App: Initialize application
    App->>Parser: Parse encryption config
    Parser->>ConfigScope: Read ENCRYPTION_KEYS,<br/>ENCRYPTION_ACTIVE_KEY_ID,<br/>ENCRYPTION_HASH_PEPPER
    ConfigScope-->>Parser: Config values
    Parser->>Parser: Validate & decode<br/>base64 keys
    Parser-->>App: EnvelopeEncryptorConfig
    App->>Encryptor: new EnvelopeEncryptor(config)
    Encryptor->>Encryptor: Validate config at<br/>construction
    Encryptor-->>App: Ready instance

    Note over App,Crypto: Encryption flow
    User->>App: encrypt(plaintext)
    App->>Encryptor: encrypt(plaintext)
    Encryptor->>Crypto: Generate random IV
    Crypto-->>Encryptor: IV
    Encryptor->>Crypto: AES-256-GCM encrypt<br/>with active key
    Crypto-->>Encryptor: ciphertext + authTag
    Encryptor->>Encryptor: Format envelope:<br/>prefix+keyId:base64url(iv||authTag||ciphertext)
    Encryptor-->>App: envelope
    App-->>User: encrypted result

    Note over App,Crypto: Decryption flow
    User->>App: decrypt(envelope)
    App->>Encryptor: decrypt(envelope)
    Encryptor->>Encryptor: Check envelope prefix
    alt Has prefix
        Encryptor->>Encryptor: Parse keyId & extract<br/>iv||authTag||ciphertext
        Encryptor->>Encryptor: Lookup key by keyId
        alt Key found
            Encryptor->>Crypto: AES-256-GCM decrypt<br/>with selected key
            Crypto-->>Encryptor: plaintext (or auth fail)
            Encryptor-->>App: plaintext
        else Key not found
            Encryptor-->>App: EncryptionKeyNotConfiguredError
        end
    else No prefix
        Encryptor-->>App: Plaintext passthrough
    end
    App-->>User: decrypted result

Loading

sequenceDiagram
    actor User
    participant Encryptor as EnvelopeEncryptor
    participant HMAC as HMAC-SHA256
    participant User2 as Lookup Hash

    User->>Encryptor: hash(plaintext)
    Encryptor->>HMAC: HMAC-SHA256(pepper, plaintext)
    HMAC-->>Encryptor: hex digest (64 chars)
    Encryptor-->>User2: Deterministic hash
    Note over Encryptor,User2: Hash is independent<br/>of encryption key rotation

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

🚥 Pre-merge checks | ✅ 2 | ❌ 3

❌ Failed checks (2 warnings, 1 inconclusive)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 25.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.
Description check	⚠️ Warning	The pull request description is largely incomplete; it only contains the template placeholder 'Please describe' with no actual details about the changes, and checklist items are marked complete despite no substantive description being provided.	Replace 'Please describe' with a detailed summary of the changes: new EnvelopeEncryptor encryption module with AES-256-GCM support, key rotation, configuration parsing, error handling, and comprehensive tests. Explain the deprecation of EncryptionUtility and migration path.
Title check	❓ Inconclusive	The title 'CEX-65 new encryption' is vague and does not clearly convey the primary change; it lacks specificity about what the new encryption functionality entails.	Use a more descriptive title that clearly explains the main change, e.g., 'Add EnvelopeEncryptor with AES-256-GCM key rotation support' or similar.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/CEX-65_imporve-encryption

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@src/utils/envelopeEncryptor/EnvelopeEncryptor.ts`:
- Around line 181-183: encryptJson currently calls JSON.stringify(value) and
passes the result directly to this.encrypt, which leads to a raw crypto error
when JSON.stringify returns undefined for non-serializable top-level values
(e.g., undefined, functions, symbols). Update encryptJson (and keep reference to
this.encrypt) to capture the result of JSON.stringify, check if it returned
undefined, and if so throw a clear, descriptive application error (e.g., "Value
is not JSON-serializable") before calling this.encrypt; otherwise pass the
stringified value into this.encrypt as before.
- Around line 105-107: The constructor of EnvelopeEncryptor stores caller-owned
references (config.keys, config.hashPepper) which allows external mutation; fix
by cloning the key material on assignment: create a new Map for this.keys and
for each entry copy the key id and clone the Buffer value (e.g.,
Buffer.from(value)) before inserting, assign this.activeKeyId from
config.activeKeyId (string copy) and clone this.hashPepper with
Buffer.from(config.hashPepper) so the class holds independent buffers; update
the constructor assignment logic in EnvelopeEncryptor to use these clones.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository: lokalise/coderabbit/.coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 1a7212db-a525-413f-94bc-fe68326ea6c5

📥 Commits

Reviewing files that changed from the base of the PR and between 040e31f and 592407e.

📒 Files selected for processing (7)

• src/index.ts
• src/utils/encryptionUtility.ts
• src/utils/envelopeEncryptor/EnvelopeEncryptor.spec.ts
• src/utils/envelopeEncryptor/EnvelopeEncryptor.ts
• src/utils/envelopeEncryptor/envelopeEncryptorErrors.ts
• src/utils/envelopeEncryptor/parseEnvelopeEncryptorConfig.spec.ts
• src/utils/envelopeEncryptor/parseEnvelopeEncryptorConfig.ts