@sovseal/sdk

The official TypeScript SDK for sovseal — build applications with client-side zero-knowledge state continuity and replication.

Installation

npm install @sovseal/sdk

Quick Start

Initialize the AgentStateClient with your endpoint URL and credentials:

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

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

// Generate or import an encryption key
const key = await CryptoService.generateAESKey();

// Snapshot agent state (client-side encrypted before replication)
const receipt = await client.snapshot({
  payload: {
    agent_id: "my-agent-id",
    policy_hash:
      "0000000000000000000000000000000000000000000000000000000000000000",
    active_context: {
      user_preference: "dark mode",
      recent_conversations: [{ role: "user", content: "hello" }],
    },
    parent_snapshot: null,
    sequence_number: 0,
    timestamp: new Date().toISOString(),
  },
  key,
});

// Later, restore the latest state checkpoint
const { receipt: latestReceipt, ciphertextUrl } = await client.restore({
  agentId: "my-agent-id",
});

Encryption

The SDK includes client-side cryptographic primitives via Web Crypto API:

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

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

// Encrypt payload JSON
const encryptedBytes = await encryptJson({ secret: "data" }, key);

// Decrypt back to JSON
const decrypted = await decryptJson(encryptedBytes, key);

API Reference

AgentStateClient

| Method | Description | | ------------------- | ----------------------------------------------------------------------- | | snapshot(params) | Encrypts active_context and publishes a new snapshot | | restore(params) | Fetches the latest confirmed checkpoint receipt and ciphertext URL | | restoreAt(params) | Fetches a checkpoint at a specific sequence number | | lineage(params) | Walks parental snapshot lineage to retrieve historical sequence headers |

Crypto Primitives (re-exported)

• CryptoService: AES-256-GCM key generation, raw export/import, and SHA-256 helpers.
• encryptJson(value, key): JCS-canonicalizes and encrypts value using AES-256-GCM.
• decryptJson(bytes, key): Decrypts and parses the JSON envelope.
• canonicalize(value): RFC 8785 JSON Canonicalization Scheme implementation.

License

Apache-2.0 — See LICENSE for details.