@capsara/sdk 1.0.1 → 1.0.2

package/LICENSE

@@ -1,74 +1,74 @@
-Capsara SDK License
-
-Copyright (c) 2024-2026 Tessarai, LLC and Laird Rixford (the "License Holders"). All rights reserved.
-
-TERMS AND CONDITIONS
-
-1. GRANT OF LICENSE
-
-   Subject to the terms and conditions of this License, Tessarai, LLC
-   ("Licensor") grants you a limited, non-exclusive, non-transferable,
-   non-sublicensable, revocable license to use the Capsara SDK ("Software")
-   solely in connection with the Capsara platform and services provided by
-   Licensor.
-
-2. RESTRICTIONS
-
-   You may NOT:
-
-   a. Redistribute, sublicense, sell, lease, or otherwise transfer the
-      Software or any portion thereof to any third party;
-   b. Modify, adapt, translate, reverse engineer, decompile, disassemble,
-      or create derivative works based on the Software;
-   c. Use the Software to build, support, or operate any product or service
-      that competes with the Capsara platform;
-   d. Use the Software independently of or outside the Capsara platform;
-   e. Remove, alter, or obscure any copyright, trademark, or other
-      proprietary notices in the Software.
-
-3. PLATFORM BINDING
-
-   This license is valid only for use with the Capsara platform. Any use of
-   the Software outside the Capsara platform, including but not limited to
-   integration with competing or unrelated services, is strictly prohibited.
-
-4. INTELLECTUAL PROPERTY
-
-   The Software and all copies thereof are proprietary to and the property
-   of the License Holders. All right, title, and interest in and to the
-   Software, including all intellectual property rights therein, remain
-   exclusively with the License Holders. No rights are
-   granted to you other than as expressly set forth in this License.
-
-5. TERMINATION
-
-   This License is effective until terminated. Licensor may terminate this
-   License at any time, with or without cause, upon written notice. This
-   License will terminate automatically if you fail to comply with any term
-   or condition of this License. Upon termination, you must cease all use
-   of the Software and destroy all copies in your possession or control.
-
-6. GOVERNING TERMS
-
-   Use of the Software is governed by the Capsara Terms of Service, which
-   are incorporated herein by reference. In the event of any conflict
-   between this License and the Terms of Service, the Terms of Service
-   shall prevail.
-
-7. DISCLAIMER OF WARRANTIES
-
-   THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EXPRESS
-   OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT.
-   IN NO EVENT SHALL THE LICENSE HOLDERS OR ANY CONTRIBUTORS BE
-   LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER IN AN ACTION
-   OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION
-   WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-
-8. LIMITATION OF LIABILITY
-
-   IN NO EVENT SHALL LICENSOR BE LIABLE FOR ANY INDIRECT, INCIDENTAL,
-   SPECIAL, CONSEQUENTIAL, OR PUNITIVE DAMAGES, OR ANY LOSS OF PROFITS OR
-   REVENUE, WHETHER INCURRED DIRECTLY OR INDIRECTLY, OR ANY LOSS OF DATA,
-   USE, GOODWILL, OR OTHER INTANGIBLE LOSSES, RESULTING FROM YOUR USE OF
-   OR INABILITY TO USE THE SOFTWARE.
+Capsara SDK License
+
+Copyright (c) 2024-2026 Tessarai, LLC and Laird Rixford (the "License Holders"). All rights reserved.
+
+TERMS AND CONDITIONS
+
+1. GRANT OF LICENSE
+
+   Subject to the terms and conditions of this License, Tessarai, LLC
+   ("Licensor") grants you a limited, non-exclusive, non-transferable,
+   non-sublicensable, revocable license to use the Capsara SDK ("Software")
+   solely in connection with the Capsara platform and services provided by
+   Licensor.
+
+2. RESTRICTIONS
+
+   You may NOT:
+
+   a. Redistribute, sublicense, sell, lease, or otherwise transfer the
+      Software or any portion thereof to any third party;
+   b. Modify, adapt, translate, reverse engineer, decompile, disassemble,
+      or create derivative works based on the Software;
+   c. Use the Software to build, support, or operate any product or service
+      that competes with the Capsara platform;
+   d. Use the Software independently of or outside the Capsara platform;
+   e. Remove, alter, or obscure any copyright, trademark, or other
+      proprietary notices in the Software.
+
+3. PLATFORM BINDING
+
+   This license is valid only for use with the Capsara platform. Any use of
+   the Software outside the Capsara platform, including but not limited to
+   integration with competing or unrelated services, is strictly prohibited.
+
+4. INTELLECTUAL PROPERTY
+
+   The Software and all copies thereof are proprietary to and the property
+   of the License Holders. All right, title, and interest in and to the
+   Software, including all intellectual property rights therein, remain
+   exclusively with the License Holders. No rights are
+   granted to you other than as expressly set forth in this License.
+
+5. TERMINATION
+
+   This License is effective until terminated. Licensor may terminate this
+   License at any time, with or without cause, upon written notice. This
+   License will terminate automatically if you fail to comply with any term
+   or condition of this License. Upon termination, you must cease all use
+   of the Software and destroy all copies in your possession or control.
+
+6. GOVERNING TERMS
+
+   Use of the Software is governed by the Capsara Terms of Service, which
+   are incorporated herein by reference. In the event of any conflict
+   between this License and the Terms of Service, the Terms of Service
+   shall prevail.
+
+7. DISCLAIMER OF WARRANTIES
+
+   THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EXPRESS
+   OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT.
+   IN NO EVENT SHALL THE LICENSE HOLDERS OR ANY CONTRIBUTORS BE
+   LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER IN AN ACTION
+   OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION
+   WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+8. LIMITATION OF LIABILITY
+
+   IN NO EVENT SHALL LICENSOR BE LIABLE FOR ANY INDIRECT, INCIDENTAL,
+   SPECIAL, CONSEQUENTIAL, OR PUNITIVE DAMAGES, OR ANY LOSS OF PROFITS OR
+   REVENUE, WHETHER INCURRED DIRECTLY OR INDIRECTLY, OR ANY LOSS OF DATA,
+   USE, GOODWILL, OR OTHER INTANGIBLE LOSSES, RESULTING FROM YOUR USE OF
+   OR INABILITY TO USE THE SOFTWARE.

package/README.md

@@ -1,230 +1,230 @@
-# Capsara SDK — TypeScript
-
-Zero-knowledge encrypted messaging and file sharing for multi-party collaboration.
-
-## Features
-
-- **AES-256-GCM** encryption with unique keys per capsa
-- **RSA-4096-OAEP** key encryption for multi-party access
-- **Compression** — gzip before encryption
-- **Digital signatures** — RSA-SHA256 sender authenticity
-- **Encrypted subject, body, and structured data**
-- **Batch sending** with automatic chunking
-
-## Installation
-
-```bash
-npm install @capsara/sdk
-```
-
-## Initialize the Client
-
-```typescript
-import { CapsaraClient } from '@capsara/sdk';
-
-const client = new CapsaraClient('https://api.capsara.com');
-```
-
-## Authentication
-
-Authentication requires two steps: login with your credentials, then set your private key for cryptographic operations.
-
-### Login
-
-```typescript
-await client.login({
-  email: 'you@example.com',
-  password: '...'
-});
-```
-
-### Set Private Key
-
-After logging in, set your private key for signing and decryption. Generate and register your keypair using `generateKeyPair()` and `addPublicKey()`, then store the private key securely.
-
-```typescript
-// Load your private key from secure storage (key vault, HSM, etc.)
-const privateKey = loadPrivateKeyFromSecureStorage();
-
-client.setPrivateKey(privateKey);
-```
-
-## Sending Capsas
-
-Use the `CapsaBuilder` to create capsas with recipients and files. Always use `sendCapsas()` even for a single capsa — it handles encryption and batching efficiently.
-
-```typescript
-import { CapsaraClient, CapsaraError, FileInput } from '@capsara/sdk';
-
-try {
-  // Create a builder for each capsa you want to send
-  const builder = await client.createCapsaBuilder();
-
-  // Add recipients — can add multiple
-  builder.addRecipient('party_recipient1');
-  builder.addRecipient('party_recipient2');
-
-  // Add files from path or buffer
-  builder.addFile(FileInput.fromPath('./documents/policy.pdf'));
-  builder.addFile(FileInput.fromBuffer(
-    Buffer.from('Policy data here'),
-    'policy-data.txt'
-  ));
-
-  // Add optional metadata
-  builder.withSubject('Policy Documents — Q1 2025');
-  builder.withBody('Please review the attached policy documents.');
-  builder.withStructured({
-    policyNumber: 'POL-12345',
-    effectiveDate: '2025-01-01'
-  });
-
-  // Set expiration
-  builder.withExpiration(new Date(Date.now() + 90 * 24 * 60 * 60 * 1000));
-
-  // Send
-  const result = await client.sendCapsas([builder]);
-  console.log(`Sent ${result.successful} capsa(s)`);
-
-  if (result.failed > 0) {
-    console.error(`${result.failed} capsas failed to send`);
-  }
-} catch (error) {
-  if (error instanceof CapsaraError) {
-    console.error('Failed to send:', error.message);
-  }
-}
-```
-
-A **capsa** maps one-to-one with a *matter* — a unique combination of sender, recipient, client, and action. Send multiple capsas in one call:
-
-```typescript
-const matter1 = await client.createCapsaBuilder();
-matter1
-  .addRecipient('party_org_b')
-  .withSubject('Client 1 — New Home Policy')
-  .addFile(FileInput.fromPath('./policy.pdf'));
-
-const matter2 = await client.createCapsaBuilder();
-matter2
-  .addRecipient('party_org_b')
-  .withSubject('Client 1 — Auto Endorsement')
-  .withBody('Endorsement effective 3/1. No documents required.');
-
-await client.sendCapsas([matter1, matter2]);
-```
-
-The SDK automatically splits large batches to stay within server limits.
-
-## Receiving Capsas
-
-### List Capsas
-
-```typescript
-const response = await client.listCapsas({
-  status: 'active',
-  limit: 50
-});
-
-console.log(`Found ${response.capsas.length} capsas`);
-
-for (const capsa of response.capsas) {
-  console.log(`- ${capsa.id}: ${capsa.fileCount} files`);
-  console.log(`  Created: ${capsa.createdAt}`);
-  console.log(`  From: ${capsa.creatorId}`);
-}
-
-// Pagination
-if (response.pagination.hasMore) {
-  const nextPage = await client.listCapsas({
-    after: response.pagination.nextCursor
-  });
-}
-```
-
-### Get Capsa and Download Files
-
-```typescript
-import fs from 'node:fs';
-
-const capsa = await client.getCapsa('cap_abc123');
-
-console.log('Subject:', capsa.subject);
-console.log('Body:', capsa.body);
-console.log('Structured data:', capsa.structured);
-
-// Download each file
-for (const file of capsa.files) {
-  const { data, filename } = await client.downloadFile(capsa.packageId, file.id);
-  fs.writeFileSync(`./downloads/${filename}`, data);
-}
-```
-
-## Delegation
-
-Capsara supports delegation for scenarios where a system acts on behalf of a party — for example, an agency management system (AMS) processing capsas on behalf of the agencies it serves. When a capsa is sent to a delegated recipient, the delegate receives its own RSA-encrypted copy of the master key. If the recipient also has a public key registered in the system, they receive their own encrypted copy as well; otherwise, only the delegate can decrypt on their behalf.
-
-If you're a delegate, the flow is identical to receiving. List your capsas and check the `actingFor` field on each one to see which party it belongs to. This lets you route the data to the correct recipient in your system.
-
-```typescript
-// Authenticate as the delegate (e.g., an AMS)
-const client = new CapsaraClient('https://api.capsara.com');
-await client.login({ email: 'ams@example.com', password: '...' });
-client.setPrivateKey(loadPrivateKeyFromSecureStorage());
-
-// List capsas — includes capsas for all parties you represent
-const response = await client.listCapsas();
-
-for (const summary of response.capsas) {
-  const capsa = await client.getCapsa(summary.id);
-
-  // Check who this capsa is for
-  if (capsa.actingFor) {
-    console.log(`Capsa ${summary.id} is for agency ${capsa.actingFor}`);
-    routeToAgency(capsa.actingFor, capsa);
-  }
-
-  // Download and process files
-  for (const file of capsa.files) {
-    const { data, filename } = await client.downloadFile(summary.id, file.id);
-    processFile(capsa.actingFor, filename, data);
-  }
-}
-```
-
-## Encryption
-
-Every capsa is protected by a unique AES-256-GCM symmetric key (the "master key") generated at send time. Files and metadata — subject, body, and structured data — are each encrypted with this master key using a fresh random IV, producing authenticated ciphertext that guarantees both confidentiality and tamper detection. The master key itself is then encrypted once per authorized party and any authorized delegates using their RSA-4096 public key with OAEP-SHA256 padding, so only the holder of the corresponding private key can recover it. Each file is independently hashed with SHA-256 before encryption, and these hashes — along with all IVs — are bound into a canonical string that the sender signs using RS256 (RSA-SHA256 in JWS format). Recipients and the server validate this signature against the sender's public key before trusting any content, ensuring both authenticity and integrity of the entire capsa. Key fingerprints are SHA-256 hashes of the public key PEM, providing a compact identifier for key verification. Files are gzip-compressed before encryption by default to reduce storage and transfer costs. All encryption, decryption, signing, and verification happen locally in the SDK — Capsara's servers only ever store ciphertext and cannot read your files, your metadata, or your keys.
-
-## Private Key Security
-
-Your private key is the sole point of access to every capsa encrypted for you. Capsara uses zero-knowledge encryption — your private key never leaves your environment, is never transmitted to Capsara's servers, and is never stored by Capsara. There is no recovery mechanism, no master backdoor, and no support override. If your private key is lost, every capsa encrypted for your party becomes permanently inaccessible. No one — not Capsara, not the sender, not an administrator — can recover your data without your private key.
-
-You are fully responsible for your private key's lifecycle: generation, secure storage, and backup. Store it in a cloud key vault (Azure Key Vault, AWS Secrets Manager, HashiCorp Vault), a hardware security module, or at minimum an encrypted secrets manager — never in source code, configuration files, or logs. Back it up to a secondary secure location so that a single infrastructure failure does not result in permanent data loss.
-
-The SDK provides a `rotateKey()` method that generates a new RSA-4096 key pair and registers the new public key with Capsara. New capsas sent to you will be encrypted with your new key. However, capsas are immutable once created — their keychain and encrypted contents never change. Existing capsas remain accessible only with the private key that was active when they were created. Keep prior private keys available for as long as you need access to capsas encrypted under them.
-
-## API Reference
-
-| Method | Description |
-|--------|-------------|
-| `CapsaraClient.generateKeyPair()` | Generate an RSA-4096 key pair (static) |
-| `login(credentials)` | Authenticate with email and password |
-| `logout()` | Log out and clear cached data |
-| `setPrivateKey(privateKey)` | Set the private key for signing and decryption |
-| `createCapsaBuilder()` | Create a `CapsaBuilder` pre-loaded with server limits |
-| `sendCapsas(builders)` | Encrypt and send one or more capsas |
-| `getCapsa(capsaId)` | Fetch and decrypt a capsa |
-| `listCapsas(filters?)` | List capsas with optional filters |
-| `deleteCapsa(capsaId)` | Soft-delete a capsa |
-| `downloadFile(capsaId, fileId)` | Download and decrypt a file |
-| `getAuditEntries(capsaId)` | Get audit trail entries |
-| `addPublicKey(key, fingerprint)` | Register a new public key |
-| `rotateKey()` | Generate and register a new key pair |
-| `getKeyHistory()` | Get previous public keys |
-| `getLimits()` | Get server-enforced limits |
-| `destroy()` | Release resources and clear keys |
-
-## License
-
-Capsara SDK License — see [LICENSE](./LICENSE) for details.
+# Capsara SDK — TypeScript
+
+Zero-knowledge encrypted messaging and file sharing for multi-party collaboration.
+
+## Features
+
+- **AES-256-GCM** encryption with unique keys per capsa
+- **RSA-4096-OAEP** key encryption for multi-party access
+- **Compression** — gzip before encryption
+- **Digital signatures** — RSA-SHA256 sender authenticity
+- **Encrypted subject, body, and structured data**
+- **Batch sending** with automatic chunking
+
+## Installation
+
+```bash
+npm install @capsara/sdk
+```
+
+## Initialize the Client
+
+```typescript
+import { CapsaraClient } from '@capsara/sdk';
+
+const client = new CapsaraClient('https://api.capsara.com');
+```
+
+## Authentication
+
+Authentication requires two steps: login with your credentials, then set your private key for cryptographic operations.
+
+### Login
+
+```typescript
+await client.login({
+  email: 'you@example.com',
+  password: '...'
+});
+```
+
+### Set Private Key
+
+After logging in, set your private key for signing and decryption. Generate and register your keypair using `generateKeyPair()` and `addPublicKey()`, then store the private key securely.
+
+```typescript
+// Load your private key from secure storage (key vault, HSM, etc.)
+const privateKey = loadPrivateKeyFromSecureStorage();
+
+client.setPrivateKey(privateKey);
+```
+
+## Sending Capsas
+
+Use the `CapsaBuilder` to create capsas with recipients and files. Always use `sendCapsas()` even for a single capsa — it handles encryption and batching efficiently.
+
+```typescript
+import { CapsaraClient, CapsaraError, FileInput } from '@capsara/sdk';
+
+try {
+  // Create a builder for each capsa you want to send
+  const builder = await client.createCapsaBuilder();
+
+  // Add recipients — can add multiple
+  builder.addRecipient('party_recipient1');
+  builder.addRecipient('party_recipient2');
+
+  // Add files from path or buffer
+  builder.addFile(FileInput.fromPath('./documents/policy.pdf'));
+  builder.addFile(FileInput.fromBuffer(
+    Buffer.from('Policy data here'),
+    'policy-data.txt'
+  ));
+
+  // Add optional metadata
+  builder.withSubject('Policy Documents — Q1 2025');
+  builder.withBody('Please review the attached policy documents.');
+  builder.withStructured({
+    policyNumber: 'POL-12345',
+    effectiveDate: '2025-01-01'
+  });
+
+  // Set expiration
+  builder.withExpiration(new Date(Date.now() + 90 * 24 * 60 * 60 * 1000));
+
+  // Send
+  const result = await client.sendCapsas([builder]);
+  console.log(`Sent ${result.successful} capsa(s)`);
+
+  if (result.failed > 0) {
+    console.error(`${result.failed} capsas failed to send`);
+  }
+} catch (error) {
+  if (error instanceof CapsaraError) {
+    console.error('Failed to send:', error.message);
+  }
+}
+```
+
+A **capsa** maps one-to-one with a *matter* — a unique combination of sender, recipient, client, and action. Send multiple capsas in one call:
+
+```typescript
+const matter1 = await client.createCapsaBuilder();
+matter1
+  .addRecipient('party_org_b')
+  .withSubject('Client 1 — New Home Policy')
+  .addFile(FileInput.fromPath('./policy.pdf'));
+
+const matter2 = await client.createCapsaBuilder();
+matter2
+  .addRecipient('party_org_b')
+  .withSubject('Client 1 — Auto Endorsement')
+  .withBody('Endorsement effective 3/1. No documents required.');
+
+await client.sendCapsas([matter1, matter2]);
+```
+
+The SDK automatically splits large batches to stay within server limits.
+
+## Receiving Capsas
+
+### List Capsas
+
+```typescript
+const response = await client.listCapsas({
+  status: 'active',
+  limit: 50
+});
+
+console.log(`Found ${response.capsas.length} capsas`);
+
+for (const capsa of response.capsas) {
+  console.log(`- ${capsa.id}: ${capsa.fileCount} files`);
+  console.log(`  Created: ${capsa.createdAt}`);
+  console.log(`  From: ${capsa.creatorId}`);
+}
+
+// Pagination
+if (response.pagination.hasMore) {
+  const nextPage = await client.listCapsas({
+    after: response.pagination.nextCursor
+  });
+}
+```
+
+### Get Capsa and Download Files
+
+```typescript
+import fs from 'node:fs';
+
+const capsa = await client.getCapsa('cap_abc123');
+
+console.log('Subject:', capsa.subject);
+console.log('Body:', capsa.body);
+console.log('Structured data:', capsa.structured);
+
+// Download each file
+for (const file of capsa.files) {
+  const { data, filename } = await client.downloadFile(capsa.packageId, file.id);
+  fs.writeFileSync(`./downloads/${filename}`, data);
+}
+```
+
+## Delegation
+
+Capsara supports delegation for scenarios where a system acts on behalf of a party — for example, an agency management system (AMS) processing capsas on behalf of the agencies it serves. When a capsa is sent to a delegated recipient, the delegate receives its own RSA-encrypted copy of the master key. If the recipient also has a public key registered in the system, they receive their own encrypted copy as well; otherwise, only the delegate can decrypt on their behalf.
+
+If you're a delegate, the flow is identical to receiving. List your capsas and check the `actingFor` field on each one to see which party it belongs to. This lets you route the data to the correct recipient in your system.
+
+```typescript
+// Authenticate as the delegate (e.g., an AMS)
+const client = new CapsaraClient('https://api.capsara.com');
+await client.login({ email: 'ams@example.com', password: '...' });
+client.setPrivateKey(loadPrivateKeyFromSecureStorage());
+
+// List capsas — includes capsas for all parties you represent
+const response = await client.listCapsas();
+
+for (const summary of response.capsas) {
+  const capsa = await client.getCapsa(summary.id);
+
+  // Check who this capsa is for
+  if (capsa.actingFor) {
+    console.log(`Capsa ${summary.id} is for agency ${capsa.actingFor}`);
+    routeToAgency(capsa.actingFor, capsa);
+  }
+
+  // Download and process files
+  for (const file of capsa.files) {
+    const { data, filename } = await client.downloadFile(summary.id, file.id);
+    processFile(capsa.actingFor, filename, data);
+  }
+}
+```
+
+## Encryption
+
+Every capsa is protected by a unique AES-256-GCM symmetric key (the "master key") generated at send time. Files and metadata — subject, body, and structured data — are each encrypted with this master key using a fresh random IV, producing authenticated ciphertext that guarantees both confidentiality and tamper detection. The master key itself is then encrypted once per authorized party and any authorized delegates using their RSA-4096 public key with OAEP-SHA256 padding, so only the holder of the corresponding private key can recover it. Each file is independently hashed with SHA-256 before encryption, and these hashes — along with all IVs — are bound into a canonical string that the sender signs using RS256 (RSA-SHA256 in JWS format). Recipients and the server validate this signature against the sender's public key before trusting any content, ensuring both authenticity and integrity of the entire capsa. Key fingerprints are SHA-256 hashes of the public key PEM, providing a compact identifier for key verification. Files are gzip-compressed before encryption by default to reduce storage and transfer costs. All encryption, decryption, signing, and verification happen locally in the SDK — Capsara's servers only ever store ciphertext and cannot read your files, your metadata, or your keys.
+
+## Private Key Security
+
+Your private key is the sole point of access to every capsa encrypted for you. Capsara uses zero-knowledge encryption — your private key never leaves your environment, is never transmitted to Capsara's servers, and is never stored by Capsara. There is no recovery mechanism, no master backdoor, and no support override. If your private key is lost, every capsa encrypted for your party becomes permanently inaccessible. No one — not Capsara, not the sender, not an administrator — can recover your data without your private key.
+
+You are fully responsible for your private key's lifecycle: generation, secure storage, and backup. Store it in a cloud key vault (Azure Key Vault, AWS Secrets Manager, HashiCorp Vault), a hardware security module, or at minimum an encrypted secrets manager — never in source code, configuration files, or logs. Back it up to a secondary secure location so that a single infrastructure failure does not result in permanent data loss.
+
+The SDK provides a `rotateKey()` method that generates a new RSA-4096 key pair and registers the new public key with Capsara. New capsas sent to you will be encrypted with your new key. However, capsas are immutable once created — their keychain and encrypted contents never change. Existing capsas remain accessible only with the private key that was active when they were created. Keep prior private keys available for as long as you need access to capsas encrypted under them.
+
+## API Reference
+
+| Method | Description |
+|--------|-------------|
+| `CapsaraClient.generateKeyPair()` | Generate an RSA-4096 key pair (static) |
+| `login(credentials)` | Authenticate with email and password |
+| `logout()` | Log out and clear cached data |
+| `setPrivateKey(privateKey)` | Set the private key for signing and decryption |
+| `createCapsaBuilder()` | Create a `CapsaBuilder` pre-loaded with server limits |
+| `sendCapsas(builders)` | Encrypt and send one or more capsas |
+| `getCapsa(capsaId)` | Fetch and decrypt a capsa |
+| `listCapsas(filters?)` | List capsas with optional filters |
+| `deleteCapsa(capsaId)` | Soft-delete a capsa |
+| `downloadFile(capsaId, fileId)` | Download and decrypt a file |
+| `getAuditEntries(capsaId)` | Get audit trail entries |
+| `addPublicKey(key, fingerprint)` | Register a new public key |
+| `rotateKey()` | Generate and register a new key pair |
+| `getKeyHistory()` | Get previous public keys |
+| `getLimits()` | Get server-enforced limits |
+| `destroy()` | Release resources and clear keys |
+
+## License
+
+Capsara SDK License — see [LICENSE](./LICENSE) for details.

package/package.json

@@ -1,61 +1,61 @@
-{
-  "name": "@capsara/sdk",
-  "version": "1.0.1",
-  "description": "Capsara SDK for TypeScript",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "type": "module",
-  "scripts": {
-    "clean": "rm -rf dist",
-    "build": "npm run clean && tsc",
-    "dev": "tsc --watch",
-    "test": "vitest",
-    "test:coverage": "vitest --coverage",
-    "lint": "eslint src/**/*.ts",
-    "prepublishOnly": "npm run build"
-  },
-  "keywords": [
-    "encryption",
-    "zero-knowledge",
-    "secure-sharing",
-    "pgp",
-    "rsa",
-    "aes",
-    "file-sharing",
-    "multi-party",
-    "insurance",
-    "compliance",
-    "hipaa"
-  ],
-  "author": "Tessarai, LLC",
-  "license": "SEE LICENSE IN LICENSE",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/tessarai-corpus/capsara-typescript.git"
-  },
-  "bugs": {
-    "url": "https://github.com/tessarai-corpus/capsara-typescript/issues"
-  },
-  "homepage": "https://github.com/tessarai-corpus/capsara-typescript#readme",
-  "engines": {
-    "node": ">=20.0.0"
-  },
-  "dependencies": {
-    "axios": "^1.7.9"
-  },
-  "devDependencies": {
-    "@eslint/js": "^9.39.1",
-    "@types/node": "^20.17.10",
-    "@typescript-eslint/eslint-plugin": "^8.18.2",
-    "@typescript-eslint/parser": "^8.18.2",
-    "@vitest/coverage-v8": "^2.1.8",
-    "eslint": "^9.18.0",
-    "typescript": "^5.9.0",
-    "vitest": "^2.1.8"
-  },
-  "files": [
-    "dist",
-    "README.md",
-    "LICENSE"
-  ]
-}
+{
+  "name": "@capsara/sdk",
+  "version": "1.0.2",
+  "description": "Capsara SDK for TypeScript",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "type": "module",
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "npm run clean && tsc",
+    "dev": "tsc --watch",
+    "test": "vitest",
+    "test:coverage": "vitest --coverage",
+    "lint": "eslint src/**/*.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "encryption",
+    "zero-knowledge",
+    "secure-sharing",
+    "pgp",
+    "rsa",
+    "aes",
+    "file-sharing",
+    "multi-party",
+    "insurance",
+    "compliance",
+    "hipaa"
+  ],
+  "author": "Tessarai, LLC",
+  "license": "Capsara SDK License",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tessarai-corpus/capsara-typescript.git"
+  },
+  "bugs": {
+    "url": "https://github.com/tessarai-corpus/capsara-typescript/issues"
+  },
+  "homepage": "https://github.com/tessarai-corpus/capsara-typescript#readme",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "dependencies": {
+    "axios": "^1.7.9"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.1",
+    "@types/node": "^20.17.10",
+    "@typescript-eslint/eslint-plugin": "^8.18.2",
+    "@typescript-eslint/parser": "^8.18.2",
+    "@vitest/coverage-v8": "^2.1.8",
+    "eslint": "^9.18.0",
+    "typescript": "^5.9.0",
+    "vitest": "^2.1.8"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ]
+}