@ursalock/agent 0.4.0

package/README.md

@@ -0,0 +1,192 @@
+# @ursalock/agent
+
+Headless Node.js SDK for AI agents to read/write E2E encrypted documents.
+
+## Overview
+
+`@ursalock/agent` is a **thin wrapper** around `@ursalock/client` that provides:
+
+- **Base64 key handling** — Agents receive keys as strings, not Uint8Arrays
+- **API key authentication** — Simple bearer token auth
+- **Clean, self-documenting API** — Purpose-built for agent use
+- **Zero crypto reimplementation** — Delegates to `@ursalock/client` and `@ursalock/crypto`
+
+## Installation
+
+```bash
+npm install @ursalock/agent
+```
+
+## Quick Start
+
+```typescript
+import { AgentVault } from '@ursalock/agent';
+
+// Create vault with explicit keys
+const vault = new AgentVault({
+  serverUrl: 'https://vault.ndlz.net',
+  apiKey: 'ulk_your_api_key',
+  vaultUid: 'vault-123',
+  encryptionKey: 'base64-encoded-key',
+  hmacKey: 'base64-encoded-hmac-key',
+});
+
+// Access a typed collection
+interface Note {
+  title: string;
+  content: string;
+}
+
+const notes = vault.collection<Note>('notes');
+
+// Create encrypted document
+await notes.create({
+  title: 'Secret Note',
+  content: 'This is encrypted end-to-end',
+});
+
+// List all notes
+const allNotes = await notes.list();
+
+// Get specific note
+const note = await notes.get('doc-uid');
+
+// Update note
+await notes.update('doc-uid', { title: 'Updated Title' });
+
+// Delete note
+await notes.delete('doc-uid');
+```
+
+## Using Master Key
+
+If you have the full master key (highest trust level):
+
+```typescript
+import { createAgentVaultFromMasterKey } from '@ursalock/agent';
+
+const vault = await createAgentVaultFromMasterKey({
+  serverUrl: 'https://vault.ndlz.net',
+  apiKey: 'ulk_your_api_key',
+  vaultUid: 'vault-123',
+  masterKey: 'base64-encoded-master-key',
+});
+
+// Vault keys are automatically derived using HKDF
+const notes = vault.collection<Note>('notes');
+```
+
+## API Reference
+
+### `AgentVault`
+
+#### Constructor
+
+```typescript
+new AgentVault(options: AgentVaultOptions)
+```
+
+**Options:**
+- `serverUrl` — Vault server URL
+- `apiKey` — API key for authentication (starts with `ulk_`)
+- `vaultUid` — Vault unique identifier
+- `encryptionKey` — Base64-encoded 32-byte encryption key
+- `hmacKey` — Optional base64-encoded 32-byte HMAC key
+
+#### Methods
+
+##### `collection<T>(name: string): Collection<T>`
+
+Get a typed collection.
+
+**Example:**
+```typescript
+const tasks = vault.collection<{ task: string; done: boolean }>('tasks');
+```
+
+### `createAgentVaultFromMasterKey`
+
+```typescript
+async function createAgentVaultFromMasterKey(options: {
+  serverUrl: string;
+  apiKey: string;
+  vaultUid: string;
+  masterKey: string; // base64-encoded
+}): Promise<AgentVault>
+```
+
+Derives vault-specific encryption and HMAC keys from a master key using HKDF.
+
+### `Collection<T>`
+
+See [@ursalock/client documentation](../client/README.md) for full Collection API.
+
+**Methods:**
+- `create(content: T): Promise<Document<T>>`
+- `get(uid: string): Promise<Document<T>>`
+- `list(options?: ListOptions): Promise<Document<T>[]>`
+- `update(uid: string, content: Partial<T>): Promise<Document<T>>`
+- `delete(uid: string): Promise<void>`
+- `sync(since?: number): Promise<SyncResult<T>>`
+
+## Security
+
+### Key Handling
+
+- **Never hardcode keys** — Load from environment variables or secure storage
+- **Use HMAC keys** — Provides integrity verification (Encrypt-then-MAC)
+- **Rotate API keys** — If compromised, revoke and generate new keys
+
+### API Key Format
+
+API keys start with `ulk_` and should be treated as secrets:
+
+```typescript
+const vault = new AgentVault({
+  serverUrl: process.env.VAULT_URL!,
+  apiKey: process.env.VAULT_API_KEY!,
+  vaultUid: process.env.VAULT_UID!,
+  encryptionKey: process.env.VAULT_ENC_KEY!,
+  hmacKey: process.env.VAULT_HMAC_KEY,
+});
+```
+
+### Trust Model
+
+1. **Explicit keys** — Agent has encryption key only (read/write documents)
+2. **Master key** — Agent has full vault access (highest trust)
+3. **API key** — Server-side authentication (revocable)
+
+## Architecture
+
+This package is a **thin wrapper** with ~150 lines of code:
+
+```
+@ursalock/agent (this package)
+  ↓ wraps
+@ursalock/client (Collection implementation)
+  ↓ uses
+@ursalock/crypto (AES-GCM, HMAC, HKDF)
+```
+
+**Design principles:**
+- **DRY** — No crypto/collection logic duplication
+- **Minimal** — Only agent-specific concerns (base64, API key auth)
+- **Reusable** — Delegates to battle-tested client/crypto packages
+
+## Development
+
+```bash
+# Build
+pnpm build
+
+# Test
+pnpm test
+
+# Type check
+pnpm typecheck
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,140 @@
+import { Collection } from '@ursalock/client';
+export { Collection, Document, ListOptions, SyncResult } from '@ursalock/client';
+
+/**
+ * AgentVault - Headless SDK for AI agents
+ *
+ * Thin wrapper around DocumentClient with:
+ * - Base64 key decoding (agents receive keys as strings)
+ * - API key authentication
+ * - Clean, self-documenting interface
+ */
+
+/**
+ * Configuration options for AgentVault
+ */
+interface AgentVaultOptions {
+    /** Server URL (e.g., "https://vault.ndlz.net") */
+    serverUrl: string;
+    /** API key for authentication (starts with "ulk_") */
+    apiKey: string;
+    /** Vault UID to access */
+    vaultUid: string;
+    /**
+     * Encryption key (base64-encoded 32-byte key)
+     * This is the vault's encryption key shared by the human
+     */
+    encryptionKey: string;
+    /**
+     * Optional HMAC key (base64-encoded 32-byte key)
+     * If not provided, HMAC integrity checking is disabled
+     */
+    hmacKey?: string;
+}
+/**
+ * AgentVault provides headless access to encrypted documents
+ *
+ * This is a thin wrapper around DocumentClient that:
+ * 1. Handles base64 key encoding/decoding
+ * 2. Injects API key authentication
+ * 3. Provides a clean API for agent use
+ *
+ * All encryption/decryption logic is delegated to Collection from @ursalock/client
+ *
+ * @example
+ * ```ts
+ * const vault = new AgentVault({
+ *   serverUrl: 'https://vault.ndlz.net',
+ *   apiKey: 'ulk_abc123...',
+ *   vaultUid: 'vault-xyz',
+ *   encryptionKey: 'base64-encoded-key',
+ *   hmacKey: 'base64-encoded-hmac-key',
+ * });
+ *
+ * const notes = vault.collection<{ title: string; content: string }>('notes');
+ * await notes.create({ title: 'Secret', content: 'Hello world' });
+ * const allNotes = await notes.list();
+ * ```
+ */
+declare class AgentVault {
+    private client;
+    constructor(options: AgentVaultOptions);
+    /**
+     * Get a typed collection
+     *
+     * Collections provide CRUD operations on encrypted documents.
+     * All documents are encrypted client-side before being sent to the server.
+     *
+     * @param name - Collection name (e.g., "notes", "tasks")
+     * @returns Typed collection instance
+     *
+     * @example
+     * ```ts
+     * interface Note {
+     *   title: string;
+     *   content: string;
+     * }
+     *
+     * const notes = vault.collection<Note>('notes');
+     * await notes.create({ title: 'Shopping list', content: 'Milk, eggs' });
+     * ```
+     */
+    collection<T>(name: string): Collection<T>;
+}
+/**
+ * Create an AgentVault from a master key
+ *
+ * For cases where the agent has the full master key (highest trust level),
+ * this helper derives vault-specific encryption and HMAC keys using HKDF.
+ *
+ * The master key is typically:
+ * - Derived from a recovery key via Argon2id
+ * - Derived from ZKC PRF (passkey-based key derivation)
+ * - Shared directly by the human in a secure channel
+ *
+ * @param options - Configuration with master key
+ * @returns AgentVault instance ready to use
+ *
+ * @example
+ * ```ts
+ * const vault = await createAgentVaultFromMasterKey({
+ *   serverUrl: 'https://vault.ndlz.net',
+ *   apiKey: 'ulk_abc123...',
+ *   vaultUid: 'vault-xyz',
+ *   masterKey: 'base64-encoded-master-key',
+ * });
+ *
+ * const notes = vault.collection<Note>('notes');
+ * ```
+ */
+declare function createAgentVaultFromMasterKey(options: {
+    serverUrl: string;
+    apiKey: string;
+    vaultUid: string;
+    masterKey: string;
+}): Promise<AgentVault>;
+
+/**
+ * Base64 encoding utilities for Node.js
+ *
+ * Agents receive encryption keys as base64 strings (for easy serialization)
+ * and need to convert them to Uint8Array for crypto operations.
+ */
+/**
+ * Decode base64 string to Uint8Array
+ * Uses Node.js Buffer API (not available in browser)
+ *
+ * @param base64 - Base64-encoded string
+ * @returns Raw bytes as Uint8Array
+ */
+declare function base64ToBytes(base64: string): Uint8Array;
+/**
+ * Encode Uint8Array to base64 string
+ * Uses Node.js Buffer API (not available in browser)
+ *
+ * @param bytes - Raw bytes
+ * @returns Base64-encoded string
+ */
+declare function bytesToBase64(bytes: Uint8Array): string;
+
+export { AgentVault, type AgentVaultOptions, base64ToBytes, bytesToBase64, createAgentVaultFromMasterKey };

package/dist/index.js

@@ -0,0 +1,69 @@
+// src/agent-vault.ts
+import { DocumentClient } from "@ursalock/client";
+import { deriveVaultKeys } from "@ursalock/crypto";
+
+// src/types.ts
+function base64ToBytes(base64) {
+  return new Uint8Array(Buffer.from(base64, "base64"));
+}
+function bytesToBase64(bytes) {
+  return Buffer.from(bytes).toString("base64");
+}
+
+// src/agent-vault.ts
+var AgentVault = class {
+  client;
+  constructor(options) {
+    const encKey = base64ToBytes(options.encryptionKey);
+    const hmacKey = options.hmacKey ? base64ToBytes(options.hmacKey) : void 0;
+    this.client = new DocumentClient({
+      serverUrl: options.serverUrl,
+      vaultUid: options.vaultUid,
+      encryptionKey: encKey,
+      hmacKey,
+      getAuthHeader: () => ({
+        Authorization: `Bearer ${options.apiKey}`
+      })
+    });
+  }
+  /**
+   * Get a typed collection
+   * 
+   * Collections provide CRUD operations on encrypted documents.
+   * All documents are encrypted client-side before being sent to the server.
+   * 
+   * @param name - Collection name (e.g., "notes", "tasks")
+   * @returns Typed collection instance
+   * 
+   * @example
+   * ```ts
+   * interface Note {
+   *   title: string;
+   *   content: string;
+   * }
+   * 
+   * const notes = vault.collection<Note>('notes');
+   * await notes.create({ title: 'Shopping list', content: 'Milk, eggs' });
+   * ```
+   */
+  collection(name) {
+    return this.client.collection(name);
+  }
+};
+async function createAgentVaultFromMasterKey(options) {
+  const masterKeyBytes = base64ToBytes(options.masterKey);
+  const keys = await deriveVaultKeys(masterKeyBytes, options.vaultUid);
+  return new AgentVault({
+    serverUrl: options.serverUrl,
+    apiKey: options.apiKey,
+    vaultUid: options.vaultUid,
+    encryptionKey: bytesToBase64(keys.encryptionKey),
+    hmacKey: bytesToBase64(keys.hmacKey)
+  });
+}
+export {
+  AgentVault,
+  base64ToBytes,
+  bytesToBase64,
+  createAgentVaultFromMasterKey
+};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@ursalock/agent",
+  "version": "0.4.0",
+  "description": "Headless Node.js SDK for AI agents to read/write encrypted documents",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@ursalock/crypto": "^0.4.0",
+    "@ursalock/client": "^0.4.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^1.6.0"
+  },
+  "keywords": [
+    "agent",
+    "sdk",
+    "e2ee",
+    "encryption",
+    "headless",
+    "nodejs",
+    "ai-agent"
+  ],
+  "license": "MIT",
+  "author": "Nicolas de Luz <ndlz@pm.me>",
+  "homepage": "https://github.com/nicodlz/ursalock#readme",
+  "bugs": {
+    "url": "https://github.com/nicodlz/ursalock/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nicodlz/ursalock.git",
+    "directory": "packages/agent"
+  }
+}