@capsara/sdk 1.0.2 → 1.0.3

package/README.md

@@ -1,13 +1,13 @@
-# Capsara SDK — TypeScript
+# Capsara SDK - TypeScript
 
-Zero-knowledge encrypted messaging and file sharing for multi-party collaboration.
+A **capsa** is a zero-knowledge encrypted envelope for securely exchanging files and data between multiple parties. Each capsa is sealed with its own encryption key and can only be opened by the parties explicitly authorized to access it. Capsara never sees your content, your keys, or your metadata.
 
 ## 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
+- **Compression** with gzip before encryption
+- **Digital signatures** using RSA-SHA256 for sender authenticity
 - **Encrypted subject, body, and structured data**
 - **Batch sending** with automatic chunking
 
@@ -43,7 +43,7 @@ await client.login({
 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.)
+// Your code to load the private key from secure storage (key vault, HSM, etc.)
 const privateKey = loadPrivateKeyFromSecureStorage();
 
 client.setPrivateKey(privateKey);
@@ -51,7 +51,7 @@ 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.
+Use the `CapsaBuilder` to create capsas with recipients and files. Always use `sendCapsas()` even for a single capsa since it handles encryption and batching efficiently.
 
 ```typescript
 import { CapsaraClient, CapsaraError, FileInput } from '@capsara/sdk';
@@ -60,7 +60,7 @@ try {
   // Create a builder for each capsa you want to send
   const builder = await client.createCapsaBuilder();
 
-  // Add recipients — can add multiple
+  // Add recipients (can add multiple)
   builder.addRecipient('party_recipient1');
   builder.addRecipient('party_recipient2');
 
@@ -72,7 +72,7 @@ try {
   ));
 
   // Add optional metadata
-  builder.withSubject('Policy Documents — Q1 2025');
+  builder.withSubject('Policy Documents - Q1 2025');
   builder.withBody('Please review the attached policy documents.');
   builder.withStructured({
     policyNumber: 'POL-12345',
@@ -96,19 +96,19 @@ try {
 }
 ```
 
-A **capsa** maps one-to-one with a *matter* — a unique combination of sender, recipient, client, and action. Send multiple capsas in one call:
+A **capsa** maps one-to-one with a *matter*, which is a unique combination of sender, recipient, client, and action. You can send multiple capsas in one call:
 
 ```typescript
 const matter1 = await client.createCapsaBuilder();
 matter1
   .addRecipient('party_org_b')
-  .withSubject('Client 1 — New Home Policy')
+  .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')
+  .withSubject('Client 1 - Auto Endorsement')
   .withBody('Endorsement effective 3/1. No documents required.');
 
 await client.sendCapsas([matter1, matter2]);
@@ -147,7 +147,7 @@ if (response.pagination.hasMore) {
 ```typescript
 import fs from 'node:fs';
 
-const capsa = await client.getCapsa('cap_abc123');
+const capsa = await client.getCapsa('capsa_abc-123');
 
 console.log('Subject:', capsa.subject);
 console.log('Body:', capsa.body);
@@ -162,7 +162,7 @@ for (const file of capsa.files) {
 
 ## 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.
+Capsara supports delegation for scenarios where a system acts on behalf of a party. For example, an agency management system (AMS) might process 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.
 
@@ -172,7 +172,7 @@ 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
+// List capsas (includes capsas for all parties you represent)
 const response = await client.listCapsas();
 
 for (const summary of response.capsas) {
@@ -194,15 +194,15 @@ for (const summary of response.capsas) {
 
 ## 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.
+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.
+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.
+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 store it 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.
+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 and 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
 
@@ -227,4 +227,4 @@ The SDK provides a `rotateKey()` method that generates a new RSA-4096 key pair a
 
 ## License
 
-Capsara SDK License — see [LICENSE](./LICENSE) for details.
+Capsara SDK License. See [LICENSE](./LICENSE) for details.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capsara/sdk",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "Capsara SDK for TypeScript",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",