Add support of encrypted payload for Cloud Device API

[gcatanese]

Summary

This PR adds support for encrypted payloads in the Cloud Device API, enabling end-to-end encryption for terminal communication.

Changes

New service

• EncryptedCloudDeviceApi — support sending and receiving encrypted payloads

New models

• CloudDeviceApiSecuredRequest / CloudDeviceApiSecuredResponse — wrappers for encrypted request/response payloads
• SaleToPOISecuredMessage — represents a secured (encrypted) Sale-to-POI message
• clouddevice/security/NexoDerivedKey — derived key model used in the encryption scheme
• clouddevice/security/SecurityTrailer — security trailer attached to encrypted messages

New security classes

• EncryptionCredentialDetails — holds the encryption credential configuration
• NexoCryptoPrimitives — low-level crypto primitives (AES, HMAC, etc.)
• NexoDerivedKeyGenerator — derives session keys from a master key
• NexoSecurityException — dedicated exception for security/encryption errors
• NexoSecurityManager — orchestrates encryption and decryption of Cloud Device API messages

Tests

• NexoSecurityManagerTest — unit tests for the encryption/decryption logic
• EncryptedCloudDeviceApiTest — integration-style tests for the full encrypted request/response flow, backed by fixture JSON files

[gemini-code-assist]

Code Review

This pull request introduces the EncryptedCloudDeviceApi service along with cryptographic utilities (NexoSecurityManager, nexoCryptoPrimitives, and nexoDerivedKeyGenerator) to support encrypted payloads (AES-256-CBC and HMAC-SHA256) for the Cloud Device API. It also adds comprehensive unit tests and updates terminal specs to verify encrypted requests. The code review identified several important issues, including a security vulnerability in crypt due to missing ivNonce length validation, side effects from directly mutating request parameters in the API methods, a potential runtime crash in decryptNotification when parsing non-object JSON payloads, and performance concerns regarding synchronous key derivation blocking the event loop.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[thomasc-adyen]

How did we get this blob? Wondering if we can document the procedure so we can make it repeatable for creating future tests

[gcatanese]

Using the Terminal and the encryption payload. That's a good point, I will add the "How to" to the Runbook about Testing IPP (we can then decide if we want it also on GitHub)

[thomasc-adyen]

Can we link to our docs for this reference?

[gcatanese]

@thomasc-adyen Done

[thomasc-adyen]

[Critical] Unencrypted responses are blindly trusted — no way to authenticate whether a response was actually protected

const encryptedResponse = response.SaleToPOIResponse;
if (!encryptedResponse?.NexoBlob) {
    // Terminal returned an unencrypted error response (e.g. terminal unreachable)
    return response as unknown as CloudDeviceApiResponse;
}

The test suite (syncUnencryptedErrorResponse / asyncUnencryptedErrorResponse) confirms this fallback is intentional: whenever NexoBlob is absent, the raw JSON body is returned to the caller with zero verification — no HMAC, no signature, no shape validation. The only gate is "does this JSON happen to contain a NexoBlob key."

Any actor able to inject/modify the plaintext response between Adyen's cloud relay and the merchant SDK (exactly the threat this feature exists to defend against) can omit NexoBlob and supply an arbitrary body — including a fabricated Result: "Success" payment response — and it will be handed to application code with the same trust level as a cryptographically verified response. This defeats the integrity guarantee the encrypted API is meant to provide.

Suggested fix: Never return an unverified plaintext body as if it were authenticated. At minimum: (a) only accept the unencrypted fallback for a narrow, explicitly whitelisted set of gateway-generated error shapes (e.g. ErrorCondition === "UnreachableHost", never a Result: "Success"), and (b) surface to the caller that the result was not cryptographically verified (distinct field or response type) so app code can decide whether to trust it for financial decisions.

Effort: Medium — requires adding a whitelist check + a new "verified" flag/type on the response and updating the existing fallback tests.
Fixable in SDK only: Yes, this is purely client-side response handling logic; no API change needed. (Though it relies on the API's synthetic unreachable-host errors continuing to use a stable, recognizable shape — worth confirming with the API team.)

[thomasc-adyen]

[High] Decrypt-before-authenticate ordering reintroduces a CBC padding-oracle side channel

const decryptedBytes = crypt(encryptedBytes, dk, ivNonce, "decrypt"); // decrypts first
const receivedHmac = Buffer.from(secured.SecurityTrailer.Hmac, "base64");
validateHmac(receivedHmac, decryptedBytes, dk);                      // then authenticates

createDecipheriv(...).final() throws on invalid PKCS#7 padding. Because decryption happens before HMAC verification, the two failure modes are distinguishable: a padding/cipher failure surfaces as NexoSecurityException("Cannot decrypt the SaleToPOISecuredMessage", e), while a valid-padding-but-wrong-HMAC case surfaces as NexoSecurityException("HMAC validation failed") (re-thrown verbatim via if (e instanceof NexoSecurityException) throw e; in the caller's catch block). An attacker able to inject/modify NexoBlob ciphertext (the same threat model this feature targets) can use this oracle to run a Vaudenay-style CBC padding-oracle attack, defeating confidentiality without the passphrase-derived key.

Suggested fix: Verify the HMAC over the received ciphertext before calling crypt(..., "decrypt"), and ensure both failure paths throw an identical, generic exception message so no information about why it failed leaks to the caller.

Effort: Low — reorder the two operations in decrypt() and normalize the two catch messages; the existing unit tests should still pass with a small tweak to the error-message assertions.
Fixable in SDK only: Yes, purely a local reordering of client-side crypto operations; no API/protocol change needed (the wire format already carries both Nonce and Hmac before decryption is attempted).

[thomasc-adyen]

[Low] Weak, protocol-mandated KDF parameters reintroduced verbatim in new code

const iterations = 4000; // Iteration count fixed at 4000 as mandated by the Nexo protocol specification
const key = pbkdf2Sync(pass, salt, iterations, keylen, "sha1");

4000 iterations of PBKDF2-SHA1 with a fixed, publicly-known salt ("AdyenNexoV1Salt") is weak by modern KDF standards, making offline brute-forcing of a captured ciphertext+HMAC pair against a weak passphrase comparatively cheap. This mirrors the existing legacy src/security/nexoDerivedKeyGenerator.ts exactly (verified the derived key bytes are identical between the old keylen*8-then-slice approach and this new keylen-only approach, since PBKDF2 output has the prefix property) — so this isn't a new correctness bug, just a knowingly-inherited protocol constraint duplicated into new code instead of being shared/centralized.

Suggested fix: If the Nexo protocol truly mandates these exact KDF parameters, no algorithmic change is possible from the SDK side. Consider at minimum: (a) enforcing a minimum passphrase length/entropy in validateCredentials() (currently only checks presence, not strength), and (b) deduplicating this logic against the legacy generator rather than maintaining two copies.

Effort: Low for the passphrase-strength check; N/A for the KDF parameters themselves.
Fixable in SDK only: Partially. The passphrase-strength guard is SDK-only. The iteration count/salt/digest themselves are dictated by the Nexo/AdyenNexoV1 protocol spec and the terminal's own KDF implementation — changing them would require a protocol-level change coordinated with the terminal firmware and API side, not just this SDK.

[thomasc-adyen]

[Low / Informational] decrypt() never checks that the response's declared KeyIdentifier/KeyVersion/AdyenCryptoVersion match the configured credentials

The method only uses secured.SecurityTrailer.Nonce and .Hmac; it ignores SecurityTrailer.KeyIdentifier/KeyVersion/AdyenCryptoVersion entirely when deciding which key to use (there's only ever one configured key per NexoSecurityManager instance, so a mismatch just causes the single configured key to be tried anyway). This fails closed today (wrong key → HMAC check fails), so it isn't directly exploitable on its own — but it means a server-side key-rotation mismatch surfaces as a generic NexoSecurityException instead of a clear "key/version mismatch" diagnostic, which is a debuggability gap rather than a vulnerability.

Suggested fix (optional): Validate the trailer's key metadata against this.credentials before attempting decryption and raise a distinct, clearly-worded error for that case — while being careful this doesn't reopen the oracle described in the padding-oracle comment above (i.e. do this check after HMAC validation, or make sure the two error messages remain otherwise indistinguishable from a tampering perspective).

Effort: Low — a few lines of comparison plus a new error message.
Fixable in SDK only: Yes, purely local validation of metadata that's already present in the wire payload; no API change needed.