@ajna-inc/vaults 0.1.3 → 0.1.4

package/README.md

@@ -0,0 +1,436 @@
+# Post-Quantum Encrypted Vaults
+
+Post-quantum encrypted vaults with DIDComm protocol for Credo. Client-side encryption using ML-KEM-768, AES-256-GCM, and Shamir secret sharing with P2P sharing via DIDComm messages.
+
+## Overview
+
+The Vaults module provides secure, client-side encrypted storage with peer-to-peer sharing capabilities. All cryptographic operations happen locally on the agent - no server ever sees plaintext data. It supports multiple encryption suites including post-quantum ML-KEM-768, flexible access policies (passphrase, any-of, all-of, threshold), and optional external storage (S3) for large files.
+
+## Table of Contents
+
+- [Features](#features)
+- [How It Works](#how-it-works)
+- [Encryption Suites](#encryption-suites)
+- [Access Policies](#access-policies)
+- [Protocol Flows](#protocol-flows)
+- [Usage Examples](#usage-examples)
+- [Installation](#installation)
+- [Message Types](#message-types)
+- [Event System](#event-system)
+- [Security Considerations](#security-considerations)
+
+## Features
+
+### Encryption Suites
+- **S3 Suite**: Passphrase-based encryption (Argon2id KDF + AES-256-GCM)
+- **P1 Suite**: Post-quantum encryption (ML-KEM-768 + AES-256-GCM)
+- **H1 Suite**: Hybrid mode (planned)
+
+### Access Policies
+- **Passphrase**: Single-user encryption with passphrase-derived key
+- **Any-of**: Multiple recipients, any one can decrypt independently
+- **All-of**: Multiple recipients, all must cooperate to decrypt
+- **Threshold**: Shamir secret sharing with configurable t-of-n threshold
+
+### Vault Operations
+- Create, open, update, delete encrypted vaults
+- List vaults and get metadata without decrypting
+- KEM keypair generation and management
+- Document signing vault workflows
+
+### DIDComm Protocol
+- 15 message types for P2P vault sharing
+- Request, grant, and deny access to vaults
+- Threshold share request and distribution
+- External storage operator support
+- Problem reporting for error handling
+
+### Storage
+- Inline storage in agent wallet
+- External S3 storage for large files
+- Configurable inline/external threshold
+- Storage operator mode
+
+## How It Works
+
+### Architecture
+
+```
+                     Application Code
+                          |
+                      VaultsApi
+          create / open / update / delete / list
+          KEM key mgmt / signing vaults
+                          |
+         +----------------+----------------+
+         |                |                |
+    VaultService    KEM Service    SigningVaultSvc
+         |                |                |
+         +--------+-------+-------+--------+
+                  |               |
+           EncryptionSvc    HPKEService
+                  |               |
+              WASM Crypto (30+ functions)
+                  |
+       +----------+----------+
+       |          |          |
+     AEAD       KEM      Shamir
+   AES-256   ML-KEM-768  Secret
+    GCM                  Sharing
+       |          |          |
+  VaultRepository    StorageService
+       |                   |
+  Agent Wallet       S3 / External
+```
+
+### Encryption Flow
+
+1. **Passphrase vault**: Passphrase -> Argon2id KDF -> 256-bit CEK -> AES-256-GCM encrypt
+2. **Post-quantum vault**: ML-KEM-768 encapsulate -> shared secret -> HKDF -> CEK -> AES-256-GCM encrypt
+3. **Threshold vault**: CEK -> Shamir split into n shares -> wrap each share with recipient's KEM public key
+
+### Key Commitment
+
+Every vault includes a key commitment (`kcmp`) in the header to verify the correct key was used during decryption, preventing key confusion attacks.
+
+## Encryption Suites
+
+### S3 Suite (Passphrase)
+
+**KDF**: Argon2id (configurable memory and iterations)
+**AEAD**: AES-256-GCM
+**Use Case**: Personal vaults protected by a passphrase
+
+- Passphrase is stretched via Argon2id with random salt
+- Derived key encrypts data with AES-256-GCM
+- Key commitment ensures correct passphrase verification
+
+### P1 Suite (Post-Quantum)
+
+**KEM**: ML-KEM-768 (NIST PQC standard)
+**AEAD**: AES-256-GCM
+**Use Case**: Sharing vaults between agents with quantum-resistant security
+
+- Recipient's ML-KEM public key encapsulates a shared secret
+- Shared secret is expanded via HKDF to derive CEK
+- CEK encrypts data with AES-256-GCM
+
+## Access Policies
+
+### Passphrase Policy
+Single user, passphrase-derived encryption key.
+
+### Any-of Policy
+Multiple recipients each get an independently-encrypted copy of the CEK wrapped with their KEM public key. Any single recipient can decrypt.
+
+### All-of Policy
+All participants must cooperate. The CEK is split such that every participant's contribution is required for reconstruction.
+
+### Threshold Policy
+Shamir secret sharing splits the CEK into `n` shares with a threshold of `t`. Any `t` shares can reconstruct the CEK. Each share is wrapped with the respective participant's KEM public key.
+
+## Protocol Flows
+
+### 1. Create and Open a Vault
+
+```
+Agent
+  |-- create(passphrase, data) --> Argon2id + AES-256-GCM --> VaultRecord stored
+  |-- open(passphrase) --> derive key --> AES-256-GCM decrypt --> plaintext
+```
+
+### 2. Share Vault via DIDComm
+
+```
+Owner                                  Recipient
+  |                                        |
+  |  1. GrantAccessMessage (header + CT)   |
+  |--------------------------------------->|
+  |                                        |
+  |  2. VaultStoredAckMessage              |
+  |<---------------------------------------|
+```
+
+### 3. Request Access
+
+```
+Requester                                Owner
+  |                                        |
+  |  1. RequestAccessMessage               |
+  |--------------------------------------->|
+  |                                        |
+  |  2. GrantAccessMessage / DenyAccess    |
+  |<---------------------------------------|
+```
+
+### 4. Threshold Reconstruction
+
+```
+Requester                   ShareHolder1    ShareHolder2
+  |                              |               |
+  |  RequestShareMessage         |               |
+  |----------------------------->|               |
+  |  RequestShareMessage                         |
+  |--------------------------------------------->|
+  |                              |               |
+  |  ProvideShareMessage         |               |
+  |<-----------------------------|               |
+  |  ProvideShareMessage                         |
+  |<---------------------------------------------|
+  |                                              |
+  |  [Reconstruct CEK from t shares]             |
+```
+
+### 5. Document Signing Vault
+
+```
+Owner                                    Signer
+  |                                        |
+  |  createSigningVault(doc, recipientDid) |
+  |  shareSigningVault(connectionId)       |
+  |--------------------------------------->|
+  |                                        |
+  |                      openSigningVault()|
+  |                      sign document     |
+  |  returnSignedDocument()                |
+  |<---------------------------------------|
+```
+
+## Usage Examples
+
+### Basic Vault Operations
+
+```typescript
+import { Agent } from '@credo-ts/core'
+import { VaultsModule } from '@ajna-inc/vaults'
+
+const agent = new Agent({
+  config: { /* ... */ },
+  modules: {
+    vaults: new VaultsModule()
+  }
+})
+
+await agent.initialize()
+
+// Create a vault
+const vault = await agent.modules.vaults.create({
+  passphrase: 'my-secure-passphrase',
+  data: Buffer.from('sensitive document content'),
+  metadata: {
+    description: 'Contract draft',
+    tags: ['legal', 'draft']
+  }
+})
+
+// Open (decrypt) a vault
+const plaintext = await agent.modules.vaults.open(vault.vaultId, {
+  passphrase: 'my-secure-passphrase'
+})
+
+// List all vaults
+const vaults = await agent.modules.vaults.list()
+
+// Get vault info without decrypting
+const info = await agent.modules.vaults.getInfo(vault.vaultId)
+
+// Update vault data
+await agent.modules.vaults.update(vault.vaultId, {
+  passphrase: 'my-secure-passphrase',
+  data: Buffer.from('updated content')
+})
+
+// Delete a vault
+await agent.modules.vaults.delete(vault.vaultId)
+```
+
+### KEM Key Management
+
+```typescript
+// Generate an ML-KEM-768 keypair
+const keypair = await agent.modules.vaults.generateKemKeypair()
+
+// Store a peer's KEM public key
+await agent.modules.vaults.storePeerKemKey(connectionId, peerPublicKey)
+
+// Retrieve peer's key for encryption
+const peerKey = await agent.modules.vaults.getPeerKemKey(connectionId)
+```
+
+### Signing Vault Workflow
+
+```typescript
+// Owner creates a signing vault for a specific recipient
+const signingVault = await agent.modules.vaults.createSigningVault({
+  data: documentBytes,
+  recipientDid: signerDid
+})
+
+// Owner shares the vault with the signer
+await agent.modules.vaults.shareSigningVault(connectionId, signingVault.vaultId)
+
+// Signer opens the vault
+const doc = await agent.modules.vaults.openSigningVault(vaultId)
+
+// Signer signs and returns the document
+await agent.modules.vaults.returnSignedDocument(connectionId, {
+  vaultId,
+  signedData: signedDocBytes
+})
+```
+
+### S3 Storage Configuration
+
+```typescript
+const agent = new Agent({
+  modules: {
+    vaults: new VaultsModule({
+      storage: {
+        bucket: 'my-vault-bucket',
+        region: 'us-east-1',
+        accessKeyId: 'AKIA...',
+        secretAccessKey: '...'
+      },
+      inlineThreshold: 1024 * 1024, // 1MB - larger vaults go to S3
+      operatorMode: false
+    })
+  }
+})
+```
+
+## Installation
+
+```bash
+pnpm add @ajna-inc/vaults
+```
+
+## Message Types
+
+| Message | Purpose |
+|---------|---------|
+| `CreateVaultMessage` | Notify of vault creation |
+| `UpdateVaultMessage` | Update vault data |
+| `DeleteVaultMessage` | Delete vault |
+| `RequestAccessMessage` | Request access to a vault |
+| `GrantAccessMessage` | Grant access with encrypted data |
+| `DenyAccessMessage` | Deny access request |
+| `RequestShareMessage` | Request a threshold share |
+| `ProvideShareMessage` | Provide a threshold share |
+| `DenyShareMessage` | Deny share request |
+| `StoreVaultMessage` | Store vault at storage service |
+| `VaultStoredAckMessage` | Confirm storage |
+| `RetrieveVaultMessage` | Retrieve vault from storage |
+| `VaultDataMessage` | Vault data transmission |
+| `VaultReferenceMessage` | Storage reference |
+| `VaultProblemReportMessage` | Error reporting |
+
+## Event System
+
+Subscribe to vault lifecycle events:
+
+```typescript
+import { VaultEventTypes } from '@ajna-inc/vaults'
+
+agent.events.on(VaultEventTypes.VaultCreated, (event) => {
+  console.log('Vault created:', event.payload.vaultId)
+})
+
+agent.events.on(VaultEventTypes.AccessGranted, (event) => {
+  console.log('Access granted to vault:', event.payload.vaultId)
+})
+
+agent.events.on(VaultEventTypes.ThresholdMet, (event) => {
+  console.log('Threshold met, vault can be decrypted')
+})
+```
+
+### Available Events
+
+- `VaultCreated`, `VaultOpened`, `VaultUpdated`, `VaultDeleted`
+- `VaultShared`, `VaultError`
+- `AccessRequested`, `AccessGranted`, `AccessDenied`
+- `ThresholdMet`, `ShareProvided`, `ShareRequested`, `ShareDenied`
+- `StorageAllocated`, `StorageUploaded`, `StorageDownloaded`
+
+## Security Considerations
+
+### Cryptographic Primitives
+- **ML-KEM-768**: NIST post-quantum standard for key encapsulation
+- **AES-256-GCM**: Authenticated encryption with 256-bit keys
+- **Argon2id**: Memory-hard KDF resistant to GPU/ASIC attacks
+- **Shamir Secret Sharing**: Information-theoretically secure threshold scheme
+- **Key Commitment**: Prevents key confusion and related attacks
+
+### Best Practices
+1. Use strong passphrases for passphrase-based vaults
+2. Configure adequate Argon2id memory (default is reasonable for most use cases)
+3. Store KEM private keys securely in the agent wallet
+4. Verify key commitments are checked on every decryption
+5. Use threshold policies for high-value data requiring multi-party authorization
+6. Consider external storage for large files to keep wallet lean
+
+### Client-Side Only
+All encryption and decryption happens locally on the agent. No server, mediator, or storage operator ever has access to plaintext data or encryption keys.
+
+## Vault Header Format
+
+```typescript
+{
+  v: 1,                          // Protocol version
+  suite: 'S3' | 'P1' | 'H1',   // Encryption suite
+  aead: 'AES-256-GCM',          // AEAD algorithm
+  docId: string,                 // Document identifier
+  vaultId: string,               // Vault identifier
+  epoch: number,                 // Version counter
+  nonce: string,                 // base64url nonce
+  kcmp: string,                  // Key commitment
+  salt?: string,                 // Argon2id salt (S3 suite)
+  argon2?: {                     // KDF parameters (S3 suite)
+    memory: number,
+    iterations: number
+  },
+  policy?: {                     // Access policy
+    mode: 'passphrase' | 'any-of' | 'all-of' | 'threshold'
+  },
+  recipients?: RecipientWrap[],  // Per-recipient wrapped keys
+  shares?: ThresholdShare[],     // Threshold shares
+  metadata?: {                   // Optional metadata
+    description?: string,
+    tags?: string[]
+  }
+}
+```
+
+## Error Handling
+
+```typescript
+import { VaultError, BadSuiteError, DecryptKemError, DecryptAeadError, PolicyError } from '@ajna-inc/vaults'
+
+try {
+  await agent.modules.vaults.open(vaultId, { passphrase: 'wrong' })
+} catch (error) {
+  if (error instanceof DecryptAeadError) {
+    console.log('Wrong passphrase or corrupted data')
+  } else if (error instanceof DecryptKemError) {
+    console.log('KEM decapsulation failed - wrong key')
+  } else if (error instanceof PolicyError) {
+    console.log('Access policy violation')
+  } else if (error instanceof BadSuiteError) {
+    console.log('Unknown encryption suite')
+  }
+}
+```
+
+## Testing
+
+```bash
+# Run vault tests
+pnpm test
+
+# Watch mode
+pnpm test:watch
+```
+
+## License
+
+Apache-2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ajna-inc/vaults",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Post-quantum encrypted vaults with DIDComm protocol for Credo",
   "license": "Apache-2.0",
   "main": "build/index.js",