Zero-Knowledge Guarantees: What the Server Can and Cannot See

​

What the server sees vs. cannot see

                  ┌─────────────────────────────────┐
                  │  Replication Server's View      │
                  ├─────────────────────────────────┤
SEES         ►    │  • AES-256-GCM ciphertext bytes │
                  │  • client_payload_hash (SHA-256)│
                  │  • agent_id, sequence_number    │
                  │  • byte size, timestamp         │
                  ├─────────────────────────────────┤
CANNOT SEE   ►    │  • plaintext content            │
                  │  • the fact's semantic meaning  │
                  │  • embedding vector             │
                  │  • the encryption key           │
                  └─────────────────────────────────┘

​

Formal threat model — four attacker profiles

​

1. Passive network observer (MITM)

• Attacker goal. Intercept sync packets on the public network to read agent memory.
• Mitigation. All replication traffic runs over HTTPS. Even if TLS is terminated or compromised, the observer only sees AES-256-GCM ciphertext bytes and non-secret metadata (agent_id, sequence_number, client_payload_hash) — nothing recoverable without the client key.

​

2. Malicious or compromised replication server

• Attacker goal. Read stored memories or inject false state to poison the agent’s context.
• Mitigation. The server does not hold the decryption keys. Payload integrity and chronological substitution are both closed by Verified Semantic Recall (VSR) — a check you run on restore, not one the SDK runs for you (see “Fail-closed behavior” below).

​

3. Local host machine compromise

• Attacker goal. Extract encryption keys and cached database records directly from the client device.
• Mitigation. The master key lives in the OS keychain (not a plaintext file), and memory text is encrypted at rest in local LanceDB under an HKDF-derived k_rest. A stolen disk or cold backup yields ciphertext, not memories. A fully compromised live host with root or code-execution access as your user can still read the running agent’s process memory or unlock the OS keychain. Zero-knowledge protects transit and storage — it cannot protect a live, fully-owned device.

​

4. Wholesale ciphertext substitution

• Attacker goal. Swap a valid ciphertext record with a different valid ciphertext from an older write to replay stale state.
• Mitigation. client_payload_hash — sha256(canonicalize(payload)) — covers the entire payload, including its sequence_number and parent_snapshot, so a substituted (older or different) snapshot’s re-derived hash will not match the one issued at its original write. This is combined with the server’s strict sequence_number enforcement (must equal latest confirmed + 1, or 409 sequence_gap) — see Deterministic Lineage for the full ordering model. Neither check runs automatically; you implement the hash comparison on restore (below).

​

What actually reaches the server

• AES-256-GCM ciphertext — the encrypted active_context.
• client_payload_hash — a SHA-256 integrity anchor over the whole payload, used for idempotency and as the tamper/substitution check’s comparison target.
• agent_id and sequence_number — used for auth scoping and ordering. agent_id is a value you choose (a common convention is sha256(project_id + ":" + some_stable_identifier), but it’s not a mandated derivation — see Authentication).

​

Dual verification strategy

​

Key custody

​

Fail-closed behavior

import {
  AgentStateClient,
  CryptoService,
  canonicalize,
  decryptJson,
} from "@sovseal/sdk";

const client = new AgentStateClient({
  endpoint: process.env.SOVSEAL_ENDPOINT!,
  apiKey: process.env.SOVSEAL_API_KEY!,
});

try {
  const { receipt, ciphertextUrl } = await client.restore({ agentId });
  const ciphertext = await fetch(ciphertextUrl).then((r) => r.text());

  // Throws if the AES-256-GCM auth tag fails — tampered or truncated bytes.
  const state = await decryptJson(ciphertext, key);

  // Re-derive the VSR anchor and compare before trusting the payload.
  const expected = await CryptoService.sha256Hex(
    new TextEncoder().encode(canonicalize(state)),
  );

  if (expected !== receipt.client_payload_hash) {
    // Fail closed — valid ciphertext, wrong lineage. Do not hand it to the agent.
    alertOncall({ agentId, expected, got: receipt.client_payload_hash });
    return;
  }

  useConfiguration(state);
} catch (err) {
  // Decrypt failure or transport error. Never fall back to partial state.
  alertOncall({ agentId, err });
  return;
}

​

Technical limitations

​

Next steps