The .nx Binary Specification
GN-Apex stores offline data in custom .nx binary files instead of plaintext JSON to guarantee privacy, prevent repository data leaks, and enforce cryptographic anti-tamper verification.
“Offline development data is protected with the same cryptographic standard used in hardware security modules.”
Why Binary Containers?
Storing raw JSON files (e.g., donors.json, grades.json, users.json) in local project directories introduces severe compliance risks if source code is accidentally pushed to public repositories. The BinaryCompiler ensures that all local data remains encrypted at rest.
The Cryptographic Pipeline
Key Derivation (HKDF)
Derives a 32-byte AES key and a separate HMAC integrity key from your project API Key.
AES-256-CBC Payload
Encrypts the JSON content payload with a randomly generated 16-byte initialization vector (IV).
HMAC-SHA256 Digest
Signs the entire prefix block (header + metadata + payload) and appends a 32-byte signature to the end.
Constant-Time Verification
Compares signatures in constant time to prevent side-channel timing attacks.
Binary Layout Specification
Every .nx file is laid out as a contiguous byte stream:
| Parameter | Type | Requirement | Description |
|---|---|---|---|
| Magic Header | 4 Bytes (ASCII) | Optional | The ASCII string 'NEXS'. Identifies the file as a valid GN-Apex binary container. |
| Meta Length | 4 Bytes (UInt32BE) | Optional | The byte length of the unencrypted JSON metadata block. |
| Metadata Block | Variable (JSON) | Optional | Contains { version, compiledAt, projectId, schemaChecksum }. |
| Payload Length | 4 Bytes (UInt32BE) | Optional | The total byte length of the encrypted content block (IV + Ciphertext). |
| IV (Init Vector) | 16 Bytes (Raw) | Optional | The unique initialization vector generated for this file's AES-256-CBC cipher. |
| Encrypted Ciphertext | Variable (AES-256) | Optional | The AES-256-CBC encrypted JSON content payload. |
| HMAC Signature | 32 Bytes (SHA-256) | Optional | Cryptographic HMAC-SHA256 signature appended to the end of the file. |
Constant-Time Tamper Verification
When the SDK reads a .nx file, it slices off the trailing 32 bytes and computes the expected HMAC:
crypto.timingSafeEqual() fails, and the SDK aborts with a security violation.