# Encryption Algorithms and Key Derivation Functions in ClosedClaw: A Technical Deep Dive

> Explore ClosedClaw's security stack using XChaCha20-Poly1305 encryption and Argon2id key derivation. Protect your data with these advanced cryptographic functions.

- Repository: [aSafeLobotomy/closedclaw](https://github.com/asafelobotomy/closedclaw)
- Tags: deep-dive
- Published: 2026-02-25

---

**ClosedClaw utilizes XChaCha20-Poly1305 for authenticated encryption and Argon2id for secure key derivation, implemented via the @noble/ciphers and @noble/hashes libraries to protect data at rest.**

ClosedClaw’s end-to-end encryption layer relies on modern, audited cryptographic primitives to secure sensitive payloads. This article examines the specific encryption algorithms and key derivation functions (KDFs) implemented in the repository’s security stack, analyzing how [`src/security/crypto.ts`](https://github.com/asafelobotomy/closedclaw/blob/main/src/security/crypto.ts) orchestrates XChaCha20-Poly1305 and Argon2id to provide authenticated confidentiality for stored data.

## XChaCha20-Poly1305: The Authenticated Encryption Standard

The primary **encryption algorithm** is **XChaCha20-Poly1305**, an extended-nonce variant of ChaCha20-Poly1305 that uses a 192-bit (24-byte) nonce. In [`src/security/crypto.ts`](https://github.com/asafelobotomy/closedclaw/blob/main/src/security/crypto.ts), the implementation imports from `@noble/ciphers/chacha`, specifically using the `xchacha20poly1305` constructor for all encryption and decryption operations.

This algorithm provides authenticated encryption with associated data (AEAD), ensuring both confidentiality and integrity of stored payloads. The 192-bit nonce eliminates the risk of collision when using random nonces, a critical safety improvement over the standard 64-bit nonce ChaCha20-Poly1305 variant.

## Argon2id: Memory-Hard Key Derivation

For **key derivation**, ClosedClaw employs **Argon2id**, the recommended hybrid variant of the Argon2 KDF that provides resistance against both GPU cracking attacks and side-channel analysis. The `deriveKey` function in [`src/security/crypto.ts`](https://github.com/asafelobotomy/closedclaw/blob/main/src/security/crypto.ts) imports the implementation from `@noble/hashes/argon2`.

KDF parameters—including memory cost, iteration count, parallelism factor, and output key length—are strictly defined in [`src/security/encryption-types.ts`](https://github.com/asafelobotomy/closedclaw/blob/main/src/security/encryption-types.ts) via the `EncryptionConfig` interface and the `DEFAULT_ENCRYPTION_CONFIG` constant. These tunable parameters allow the system to balance security margins with performance constraints across different hardware environments.

## Security Stack Implementation

### Encryption Flow and Key Hierarchy

The security stack follows a deterministic sequence implemented across the core files:

1. `randomBytes` generates a 32-byte **salt** and 24-byte **nonce** for each encryption operation.
2. The user's passphrase feeds into `deriveKey` alongside these parameters and the Argon2id configuration, producing a 256-bit symmetric key.
3. This key encrypts plaintext via XChaCha20-Poly1305, generating an authenticated ciphertext envelope.
4. The final payload includes the ciphertext, KDF parameters, salt, nonce, and optional key rotation metadata.

### Core Source Files

- **[`src/security/crypto.ts`](https://github.com/asafelobotomy/closedclaw/blob/main/src/security/crypto.ts)**: Contains the `encrypt()`, `decrypt()`, `deriveKey()`, and `generateKeyId()` implementations that constitute the low-level cryptographic API.
- **[`src/security/encryption-types.ts`](https://github.com/asafelobotomy/closedclaw/blob/main/src/security/encryption-types.ts)**: Defines TypeScript interfaces for algorithm specifications, KDF parameter structures, and the payload envelope format.
- **[`src/security/encrypted-store.ts`](https://github.com/asafelobotomy/closedclaw/blob/main/src/security/encrypted-store.ts)**: High-level wrapper providing transparent JSON file encryption using the primitives above, handling serialization and storage I/O.
- **[`src/security/skill-signing.ts`](https://github.com/asafelobotomy/closedclaw/blob/main/src/security/skill-signing.ts)**: Implements **Ed25519** signatures for skill authentication, operating independently from the encryption-at-rest stack.

### Practical Usage Example

The following TypeScript demonstrates the complete encryption workflow using the actual API surface:

```typescript
import {
  encrypt,
  decrypt,
  deriveKey,
  generateKeyId,
  DEFAULT_ENCRYPTION_CONFIG,
} from "./src/security/crypto.js";
import type { EncryptionConfig } from "./src/security/encryption-types.js";

/* 1️⃣ Derive a symmetric key from a passphrase (Argon2id) */
const passphrase = "my‑strong‑password";
const salt = crypto.getRandomValues(new Uint8Array(32));
const kdfParams = DEFAULT_ENCRYPTION_CONFIG.kdfParams; // memory, iterations, …
const key = deriveKey({ passphrase, salt, kdfParams });

/* 2️⃣ Encrypt a message (XChaCha20‑Poly1305) */
const plaintext = "Sensitive data that must be stored securely.";
const encrypted = encrypt({
  plaintext,
  passphrase,
  config: DEFAULT_ENCRYPTION_CONFIG,
  keyId: generateKeyId(),
});

/* 3️⃣ Decrypt the payload */
const recovered = decrypt({ payload: encrypted, passphrase });
console.assert(recovered === plaintext);

```

The [`encrypted-store.ts`](https://github.com/asafelobotomy/closedclaw/blob/main/encrypted-store.ts) module utilizes this same API to transparently encrypt and decrypt JSON persistence files, ensuring all data at rest is protected by these primitives.

## Summary

- ClosedClaw implements **XChaCha20-Poly1305** via `@noble/ciphers/chacha` for authenticated encryption, utilizing 192-bit nonces to prevent collision vulnerabilities.
- **Argon2id** from `@noble/hashes/argon2` handles secure **key derivation functions** with memory-hard parameters defined in [`encryption-types.ts`](https://github.com/asafelobotomy/closedclaw/blob/main/encryption-types.ts).
- The `deriveKey` function in [`src/security/crypto.ts`](https://github.com/asafelobotomy/closedclaw/blob/main/src/security/crypto.ts) produces 256-bit symmetric keys from user passphrases combined with 32-byte random salts.
- Encrypted payloads include the ciphertext, nonce, salt, and KDF parameters in a structured envelope managed by the core crypto module.
- Ed25519 signatures in [`skill-signing.ts`](https://github.com/asafelobotomy/closedclaw/blob/main/skill-signing.ts) provide complementary signing capabilities distinct from the encryption layer.

## Frequently Asked Questions

### Does ClosedClaw use AES-256 for encryption?

No. According to the source code in [`src/security/crypto.ts`](https://github.com/asafelobotomy/closedclaw/blob/main/src/security/crypto.ts), ClosedClaw exclusively uses **XChaCha20-Poly1305** for symmetric encryption. This modern stream cipher eliminates timing side-channels present in AES software implementations and supports safer nonce handling with its extended 192-bit nonce space, reducing the complexity of nonce management schemes.

### What Argon2id parameters does ClosedClaw use for key derivation?

The specific memory cost, iterations, and parallelism settings are encapsulated in `DEFAULT_ENCRYPTION_CONFIG` within [`src/security/encryption-types.ts`](https://github.com/asafelobotomy/closedclaw/blob/main/src/security/encryption-types.ts). These parameters feed into the `deriveKey` function to tune the memory-hard property of Argon2id, allowing the system to adapt to target security levels and hardware constraints without modifying the core cryptographic implementation.

### How does ClosedClaw handle nonce generation?

The implementation generates a 24-byte (192-bit) random nonce using `randomBytes` for every encryption operation in [`src/security/crypto.ts`](https://github.com/asafelobotomy/closedclaw/blob/main/src/security/crypto.ts). This extended nonce size, specific to XChaCha20-Poly1305, allows for safer random nonce generation without requiring complex stateful nonce-management schemes, as the probability of collision becomes statistically negligible even with billions of encrypted messages.

### Where is the encrypted data stored in ClosedClaw?

The [`src/security/encrypted-store.ts`](https://github.com/asafelobotomy/closedclaw/blob/main/src/security/encrypted-store.ts) module provides the storage abstraction, transparently reading and writing JSON files encrypted with the XChaCha20-Poly1305 and Argon2id stack. This module utilizes the same `encrypt` and `decrypt` functions exposed in [`crypto.ts`](https://github.com/asafelobotomy/closedclaw/blob/main/crypto.ts) to ensure consistent cryptographic handling across the application, managing the serialization of KDF parameters and metadata alongside the ciphertext.