AES-256-GCM Encryption

sovseal uses the standard AES-256-GCM (Advanced Encryption Standard in Galois/Counter Mode) authenticated encryption algorithm to secure memory payloads before replication.

Technical Details

• Key Size: 256 bits (32 bytes), generated locally using a cryptographically secure pseudorandom number generator (CSPRNG).
• IV Size: 96 bits (12 bytes), generated fresh for every encryption call.
• Tag Size: 128 bits (16 bytes), ensuring integrity checks are mathematically robust.
• Library Compatibility: Implemented using standard Web Crypto API (crypto.subtle.encrypt), ensuring compatibility across Node.js, Deno, Bun, Cloudflare Workers, and modern browsers.

Envelope Wire Format

The serialized snapshot payload consists of the ciphertext base64 string and associated verification hashes:

{
  "agent_id": "sha256_hash",
  "sequence_number": 42,
  "parent_snapshot": "previous_tx_hash",
  "client_payload_hash": "sha256_hash_of_plaintext",
  "ciphertext_b64": "base64_encoded_iv_and_ciphertext",
  "byte_size": 256
}

The ciphertext bytes contain:

1. IV Prefix: First 12 bytes of the raw binary payload represent the initialization vector.
2. Ciphertext Body: The middle bytes.
3. AES-GCM Auth Tag: The final 16 bytes.

Verified Semantic Recall (VSR)

When an agent triggers a memory restore operation, sovseal executes Verified Semantic Recall (VSR):

1. Downloads the ciphertext from the replication endpoint.
2. Extracts the 12-byte IV prefix and the 16-byte auth tag.
3. Decrypts the body using the locally held 256-bit key.
4. Re-derives sha256(canonicalize(decrypted_payload)).
5. Compares it against the server-returned client_payload_hash.
6. If any verification step fails (tag mismatch or hash mismatch), the client immediately fails closed throwing a vsr_hash_mismatch error, preventing corrupted or tampered inputs from being processed by the agent.