@sovseal/sdk (Node)

The @sovseal/sdk package provides a programmatic client for the sovseal zero-knowledge memory replication protocol. All cryptographic encryption, key wrapping, and integrity hashing are executed client-side.

Install

npm install @sovseal/sdk

Configuration

Initialize the client with endpoint URL and key settings:

import { AgentStateClient } from "@sovseal/sdk";

const client = new AgentStateClient({
  endpoint: "https://ksrlmubaxzwufziwarps.supabase.co/functions/v1/v2-agent-state",
  apiKey: "sov_live_abc123...", // or project token "sov_proj_..."
});

`AgentStateClientConfig` Options

endpoint (string): The base Edge Function URL.
apiKey (string): Bearer credential starting with sov_live_ or sov_proj_.
fetch (typeof fetch, optional): Custom fetch override (useful for Deno, Cloudflare Workers, or mock testing runtimes).

Method Catalog

1. `snapshot`

Encrypts an AgentPayload client-side using Web Crypto AES-256-GCM and publishes the encrypted snapshot to the replication server.

const key = await CryptoService.generateAesKey(); // AES-256-GCM key

const receipt = await client.snapshot({
  payload: {
    agent_id: "agent-id-hash",
    sequence_number: 0,
    parent_snapshot: null,
    policy_hash: "0000000000000000000000000000000000000000000000000000000000000000",
    active_context: { content: "User prefers dark mode" },
    timestamp: new Date().toISOString(),
  },
  key,
});

Arguments:
- payload: Object omitting client_payload_hash (derived on-the-fly).
- key: A Web Crypto CryptoKey.
Exceptions: Throws RangeError if the encrypted ciphertext size exceeds MAX_PAYLOAD_BYTES (10 MB).

2. `restore`

Fetch metadata and the ciphertext download URL for the latest confirmed checkpoint of an agent.

const { receipt, ciphertextUrl } = await client.restore({
  agentId: "agent-id-hash",
});

3. `restoreAt`

Fetch metadata and download URL for a checkpoint at a specific sequence number.

const { receipt, ciphertextUrl } = await client.restoreAt({
  agentId: "agent-id-hash",
  sequence: 4,
});

4. `lineage`

Walk backward along the parental snapshot chain to retrieve historical sequence headers.

const lineageHistory = await client.lineage({
  agentId: "agent-id-hash",
  limit: 50,
});

Re-exported Crypto Primitives

For developer convenience, the SDK re-exports cryptographic utilities from the underlying core-protocol package:

export {
  CryptoService,                 // SHA-256 and AES-256 helper classes
  canonicalize,                  // Deterministic JSON stringifier
  encryptJson,                   // AES-256-GCM encryption helper
  decryptJson,                   // AES-256-GCM decryption helper
  MAX_PAYLOAD_BYTES,             // 10 MB payload limit constant
}

On this page