# @wrnexus/encryption

Authenticated encryption, hashing, HMAC, key rotation, and optional encrypted HTTP exchanges for WRNexusJS.

## Core helpers

- `generateKey()` — random 256-bit AES key encoded as base64.
- `deriveKey(password, salt)` — PBKDF2-derived AES key.
- `encrypt(plaintext, key)` / `decrypt(payload, key)` — AES-256-GCM.
- `sha256(data)` — SHA-256 digest.
- `hmacSign(data, secret)` / `hmacVerify(...)` — HMAC-SHA256.
- `createKeyring(keys)` — active/previous key management.
- `seal()` / `open()` — versioned ciphertext with key ID.

## Encrypted HTTP envelope

```ts
import {
  createEncryptedRequest,
  createKeyring,
  createMemoryReplayStore,
  decryptEncryptedResponse,
  encryptedExchange,
} from "@wrnexus/encryption";

const keyring = createKeyring([{ id: "2026-08", secret: process.env.API_BODY_KEY!, active: true }]);

const replayStore = createMemoryReplayStore();

// Server middleware.
app.use(
  encryptedExchange({
    keyring,
    replayStore,
    maxAgeMs: 60_000,
    maxBodyBytes: 1_048_576,
  }),
);

// Controlled service/native client.
const request = await createEncryptedRequest(
  "https://api.example.com/private/report",
  { reportId: "report-1" },
  { method: "POST", keyring },
);
const response = await fetch(request);
const result = await decryptEncryptedResponse(response, request, { keyring });
```

The envelope binds authenticated ciphertext to:

- HTTP method
- URL path and query
- request ID
- timestamp and expiry window
- encryption key ID
- optional replay-store consumption

`encryptedBody()` decrypts request bodies only. `encryptedExchange()` also encrypts successful downstream responses while allowing application exceptions to propagate normally. `encryptedFetch()` provides a convenient controlled-client call.

## Security boundary

Encrypted HTTP bodies **do not replace TLS/HTTPS**. Always use HTTPS.

This layer is appropriate for service-to-service traffic, native/mobile applications, controlled agents, and selected fields protected with server-managed keys. It cannot conceal data from an end user when browser JavaScript receives the decryption key. Never ship a long-lived server encryption key to a browser.

Use a shared replay store such as Redis in multi-instance deployments. The memory replay store is process-local.