The JavaScript/TypeScript frontend/client-side counterpart to alterion-encrypt — X25519 ECDH key exchange, AES-256-GCM session encryption, and a MessagePack + Deflate request/response pipeline, all in a framework-agnostic package.

Frontend only. This package is intended for use in browser environments and client-side runtimes. The server-side implementation lives in the alterion-encrypt Rust crate. Do not use this package as a server-side encryption backend.

What it does

Each request to the server is packaged as a Request:

Client → Request { data: AES-256-GCM ciphertext, kx, client_pk: ephemeral X25519, key_id, ts }

Request path (buildRequestPacket):

1. JSON-serialise the payload and deflate-compress it.
2. Generate a random 32-byte AES-256 enc_key per request.
3. AES-256-GCM encrypt the payload with enc_key.
4. Generate an ephemeral X25519 key pair, perform ECDH against the server's public key.
5. Derive a wrap_key via HKDF-SHA256, use it to AES-GCM wrap enc_key → kx.
6. Encode a Request { data, kx, client_pk, key_id, ts } with MessagePack.
7. Store enc_key client-side keyed by request ID — it is never sent in plaintext.

Response path (decodeResponsePacket):

1. MessagePack-decode the Response { payload, hmac }.
2. Derive the HMAC key from enc_key via HKDF-SHA256 ("alterion-response-mac" info label).
3. Constant-time verify the HMAC — reject if invalid.
4. AES-256-GCM decrypt payload with enc_key.
5. MessagePack-decode → deflate-decompress → JSON-parse → typed result.

No second ECDH round-trip is needed for the response; the server re-uses the enc_key it unwrapped from the request. The server side is implemented in alterion-encrypt.

Package layout

alterion-encrypt (JS)
├── serializer   buildRequestPacket / decodeResponsePacket — the main public API
├── crypt        aesEncrypt / aesDecrypt — AES-256-GCM with prepended nonce
├── compress     compress / decompress — deflate-raw via CompressionStream
└── keys         deriveWrapKey / deriveResponseMacKey — HKDF-SHA256 key derivation

Quick start

1. Add the dependency

npm install alterion-encrypt

2. Fetch the server's public key

The server exposes a POST /api/ecdh/init endpoint (from the alterion-encrypt Rust crate) that returns a one-time ephemeral key pair:

const { handshake_id, public_key } = await fetch("/api/ecdh/init", { method: "POST" })
    .then(r => r.json());

const serverPk = Uint8Array.from(atob(public_key), c => c.charCodeAt(0));
const keyId    = handshake_id;

3. Encrypt a request

import { buildRequestPacket } from "alterion-encrypt";

const { wireBytes, encKey } = await buildRequestPacket(
    { username: "alice", action: "login" },
    serverPk,
    keyId,
);

// Store encKey client-side, keyed by request ID, to decrypt the response.
// Send wireBytes as application/octet-stream body.

4. Decrypt the response

import { decodeResponsePacket } from "alterion-encrypt";

const rawResponse = await fetch("/api/example", {
    method:  "POST",
    body:    wireBytes,
    headers: { "Content-Type": "application/octet-stream" },
});
const bytes = new Uint8Array(await rawResponse.arrayBuffer());

const result = await decodeResponsePacket<{ token: string }>(bytes, encKey);
console.log(result.token);

API

buildRequestPacket

function buildRequestPacket(
    value:    unknown,
    serverPk: Uint8Array,
    keyId:    string,
): Promise<{ wireBytes: Uint8Array; encKey: Uint8Array }>

Encrypts value and returns the wire bytes to send and the enc_key to hold client-side.

| Parameter | Description | |---|---| | value | Any JSON-serialisable payload | | serverPk | Server's 32-byte X25519 public key (base64-decoded from the key endpoint) | | keyId | Key identifier returned alongside the server's public key |

Returns { wireBytes, encKey }. Store encKey indexed by request ID and pass it to decodeResponsePacket when the response arrives.

decodeResponsePacket

function decodeResponsePacket<T = unknown>(
    wireBytes: Uint8Array,
    encKey:    Uint8Array,
): Promise<T>

Verifies and decodes a server response. Throws if the HMAC is invalid or decryption fails.

| Parameter | Description | |---|---| | wireBytes | Raw bytes from the server response body | | encKey | The AES key returned by the matching buildRequestPacket call |

Lower-level exports

import { aesEncrypt, aesDecrypt }         from "alterion-encrypt";
import { compress, decompress }            from "alterion-encrypt";
import { deriveWrapKey, deriveResponseMacKey } from "alterion-encrypt";

| Function | Description | |---|---| | aesEncrypt(plaintext, key) | AES-256-GCM encrypt — 12-byte nonce prepended to output | | aesDecrypt(data, key) | AES-256-GCM decrypt — reads nonce from first 12 bytes | | compress(data) | Deflate-raw compress via CompressionStream | | decompress(data) | Deflate-raw decompress via DecompressionStream | | deriveWrapKey(sharedSecret, clientPk, serverPk) | HKDF-SHA256 wrap key — salt = clientPk ‖ serverPk, info = "alterion-wrap" | | deriveResponseMacKey(encKey) | HKDF-SHA256 HMAC key — info = "alterion-response-mac" |

Pipelines

Client request (buildRequestPacket)

Any JSON-serialisable value
        │
        ▼
  JSON.stringify → TextEncoder
        │
        ▼
  deflate-raw compress (CompressionStream)
        │
        ▼
  MessagePack encode  ──→  Uint8Array
        │
        ▼
  AES-256-GCM encrypt  (random enc_key — stored client-side by request ID)
        │
        ▼
  Ephemeral X25519 keygen  ──→  ECDH(client_sk, server_pk)  ──→  HKDF-SHA256  ──→  wrap_key
        │
        ▼
  AES-256-GCM wrap enc_key  (wrap_key)  ──→  kx
        │
        ▼
  Request { data, kx, client_pk, key_id, ts }
        │
        ▼
  MessagePack encode  ──→  wire bytes  ──→  sent to server

enc_key is returned to the caller and must be stored client-side (e.g. keyed by request ID). kx lets the server recover enc_key via ECDH without it ever appearing in plaintext on the wire.

Server response (decodeResponsePacket)

wire bytes received from server
        │
        ▼
  MessagePack decode  ──→  Response { payload, hmac }
        │
        ▼
  HKDF-SHA256(enc_key, info="alterion-response-mac")  ──→  mac_key
        │
        ▼
  HMAC-SHA256 verify (mac_key, payload)  ──  reject if invalid
        │
        ▼
  AES-256-GCM decrypt payload  (enc_key)
        │
        ▼
  MessagePack decode  ──→  Uint8Array
        │
        ▼
  deflate-raw decompress (DecompressionStream)
        │
        ▼
  JSON.parse  ──→  T

Compatibility

Requires CompressionStream / DecompressionStream — available in all modern browsers and Node.js 18+.

Contributing

See CONTRIBUTING.md. Open an issue before writing any code.

License

GNU General Public License v3.0 — see LICENSE.

Made with ❤️ by the Alterion Software team