@cryptforge/cryptography 0.2.0

package/README.md

@@ -0,0 +1,331 @@
+# @cryptforge/cryptography
+
+Cryptographic operations for CryptForge applications with support for both client (browser) and server (Node.js) environments.
+
+## Features
+
+- 🔐 **Encryption & Decryption**: Symmetric and asymmetric encryption operations
+- 🌐 **Cross-Platform**: Separate implementations for browser and Node.js environments
+- 🔑 **Key Management**: Utilities for key generation, derivation, and storage
+- 🛡️ **Type-Safe**: Full TypeScript support with comprehensive type definitions
+- 📦 **Tree-Shakeable**: Optimized bundle sizes with separate entry points
+
+## Installation
+
+```bash
+npm install @cryptforge/cryptography
+```
+
+## Usage
+
+### Client/Browser Usage
+
+The client export provides `CryptoBrowser`, which uses the Web Crypto API for encryption/decryption:
+
+```typescript
+import { CryptoBrowser } from '@cryptforge/cryptography';
+import { createAuthClient } from '@cryptforge/auth';
+
+// Create auth client and unlock wallet
+const auth = createAuthClient();
+await auth.unlock({ password: 'your-password', chainId: 'ethereum' });
+
+// Derive encryption key from wallet
+const encryptionKey = await auth.deriveDataEncryptionKey({
+  purpose: 'my-app-data',
+  version: 1,
+});
+
+// Create CryptoBrowser instance
+const crypto = new CryptoBrowser();
+crypto.setEncryptionKey(encryptionKey);
+
+// Encrypt data
+const encrypted = await crypto.encrypt()('Hello, World!');
+console.log('Encrypted:', encrypted); // Base64-encoded string
+
+// Decrypt data
+const decrypted = await crypto.decrypt()(encrypted);
+console.log('Decrypted:', decrypted); // "Hello, World!"
+```
+
+### Using with Callback Pattern
+
+```typescript
+import { CryptoBrowser } from '@cryptforge/cryptography';
+
+// Create instance with dynamic key retrieval
+const crypto = new CryptoBrowser();
+
+// Set key when wallet is unlocked
+const unlockWallet = async () => {
+  await auth.unlock({ password: 'password', chainId: 'ethereum' });
+  const key = await auth.deriveDataEncryptionKey({
+    purpose: 'my-app-data',
+  });
+  crypto.setEncryptionKey(key);
+};
+
+// Use encryption after unlocking
+await unlockWallet();
+const encrypted = await crypto.encrypt()('Secret message');
+```
+
+### Encryption Details
+
+`CryptoBrowser` uses **AES-256-GCM** encryption:
+
+- **Algorithm**: AES-GCM (Galois/Counter Mode)
+- **Key Size**: 256 bits
+- **IV Size**: 12 bytes (96 bits)
+- **Output Format**: Base64-encoded (IV + ciphertext)
+
+The initialization vector (IV) is randomly generated for each encryption operation and prepended to the ciphertext. This ensures each encryption produces a unique result, even for the same plaintext.
+
+### Server/Node.js Usage
+
+The server export provides both browser and server-specific functionality:
+
+```typescript
+import { CryptoServer } from '@cryptforge/cryptography/server';
+
+// CryptoServer provides Node.js-specific crypto operations
+const crypto = new CryptoServer();
+
+// Server-side encryption/decryption
+// (Implementation similar to CryptoBrowser but optimized for Node.js)
+```
+
+**Note**: The server implementation is currently under development. For now, you can use `CryptoBrowser` in Node.js environments as the Web Crypto API is available in Node.js v15+.
+
+## Architecture
+
+This package maintains strict separation between client and server environments:
+
+- **`src/client/`**: Browser-compatible implementations using Web Crypto API
+- **`src/server/`**: Node.js-specific implementations using Node's crypto module
+- **`src/shared/`**: Environment-agnostic utilities and helpers
+- **`src/types/`**: Shared TypeScript type definitions
+
+## Entry Points
+
+- **`@cryptforge/cryptography`**: Client/browser-safe exports (default)
+- **`@cryptforge/cryptography/server`**: Server-specific exports + client exports
+
+## API Reference
+
+### CryptoBrowser
+
+Browser-compatible cryptographic operations using Web Crypto API.
+
+#### Constructor
+
+```typescript
+new CryptoBrowser()
+```
+
+Creates a new CryptoBrowser instance. The encryption key must be set before using encrypt/decrypt methods.
+
+#### Methods
+
+##### `setEncryptionKey(key: CryptoKey): void`
+
+Sets the encryption key for subsequent operations. Key must be:
+- Algorithm: AES-GCM
+- Length: 256 bits
+- Usages: `['encrypt', 'decrypt']`
+
+```typescript
+const key = await auth.deriveDataEncryptionKey({
+  purpose: 'my-data',
+  algorithm: 'AES-GCM',
+  length: 256,
+});
+
+crypto.setEncryptionKey(key);
+```
+
+##### `encrypt(): (data: string) => Promise<string>`
+
+Returns a curried function that encrypts string data.
+
+```typescript
+const encryptFn = crypto.encrypt();
+const encrypted = await encryptFn('Hello, World!');
+```
+
+**Returns**: Base64-encoded string containing IV + ciphertext
+
+##### `decrypt(): (encryptedData: string) => Promise<string>`
+
+Returns a curried function that decrypts encrypted string data.
+
+```typescript
+const decryptFn = crypto.decrypt();
+const decrypted = await decryptFn(encrypted);
+```
+
+**Throws**: Error if decryption fails (wrong key, corrupted data, etc.)
+
+## Examples
+
+### Basic Encryption/Decryption
+
+```typescript
+import { CryptoBrowser } from '@cryptforge/cryptography';
+import { createAuthClient } from '@cryptforge/auth';
+
+// Setup
+const auth = createAuthClient();
+await auth.unlock({ password: 'password', chainId: 'ethereum' });
+
+const key = await auth.deriveDataEncryptionKey({
+  purpose: 'user-documents',
+});
+
+const crypto = new CryptoBrowser();
+crypto.setEncryptionKey(key);
+
+// Encrypt
+const data = JSON.stringify({ title: 'My Document', content: 'Secret data' });
+const encrypted = await crypto.encrypt()(data);
+
+// Store encrypted data
+localStorage.setItem('myDocument', encrypted);
+
+// Later... decrypt
+const stored = localStorage.getItem('myDocument');
+const decrypted = await crypto.decrypt()(stored!);
+const document = JSON.parse(decrypted);
+```
+
+### Encrypting Multiple Items
+
+```typescript
+const encrypt = crypto.encrypt();
+const decrypt = crypto.decrypt();
+
+// Encrypt multiple items
+const items = ['Item 1', 'Item 2', 'Item 3'];
+const encryptedItems = await Promise.all(
+  items.map(item => encrypt(item))
+);
+
+// Decrypt multiple items
+const decryptedItems = await Promise.all(
+  encryptedItems.map(item => decrypt(item))
+);
+```
+
+### Error Handling
+
+```typescript
+try {
+  const encrypted = await crypto.encrypt()('Secret data');
+  const decrypted = await crypto.decrypt()(encrypted);
+} catch (error) {
+  if (error.message.includes('Encryption key not available')) {
+    // Key not set - unlock wallet first
+    await auth.unlock({ password: 'password' });
+    const key = await auth.deriveDataEncryptionKey({ purpose: 'data' });
+    crypto.setEncryptionKey(key);
+  } else {
+    // Decryption failed - wrong key or corrupted data
+    console.error('Decryption failed:', error);
+  }
+}
+```
+
+### With Automerge Documents
+
+Perfect for encrypting Automerge documents:
+
+```typescript
+import { CryptoBrowser } from '@cryptforge/cryptography';
+import * as Automerge from '@automerge/automerge';
+
+// Create Automerge document
+let doc = Automerge.init();
+doc = Automerge.change(doc, doc => {
+  doc.notes = 'Secret notes';
+});
+
+// Encrypt document
+const docBytes = Automerge.save(doc);
+const docString = btoa(String.fromCharCode(...docBytes));
+const encrypted = await crypto.encrypt()(docString);
+
+// Store encrypted document
+await storage.save('doc_id', encrypted);
+
+// Later... decrypt and load
+const stored = await storage.load('doc_id');
+const decrypted = await crypto.decrypt()(stored);
+const docBytesRestored = Uint8Array.from(atob(decrypted), c => c.charCodeAt(0));
+const restoredDoc = Automerge.load(docBytesRestored);
+```
+
+## Security Considerations
+
+### Best Practices
+
+1. **Key Management**: Never hardcode encryption keys. Always derive them from user credentials or secure key storage.
+
+2. **Key Rotation**: Use the `version` parameter in `deriveDataEncryptionKey` to support key rotation:
+
+```typescript
+// Old data encrypted with v1
+const keyV1 = await auth.deriveDataEncryptionKey({ purpose: 'data', version: 1 });
+
+// New data encrypted with v2
+const keyV2 = await auth.deriveDataEncryptionKey({ purpose: 'data', version: 2 });
+```
+
+3. **Secure Key Storage**: The encryption key is kept in memory only. When the user locks their wallet, the key is cleared.
+
+4. **No Key Export**: Keys are created with `extractable: false` by default, preventing them from being exported.
+
+### What's Protected
+
+✅ **Data at Rest** - Encrypted data stored in IndexedDB, localStorage, or disk  
+✅ **Data in Transit** - Can encrypt before sending over network  
+✅ **Memory Safety** - Keys cleared when wallet locks  
+
+### What's NOT Protected
+
+❌ **Data in Use** - Decrypted data in application memory  
+❌ **Side Channels** - Timing attacks, power analysis  
+❌ **Compromised Device** - Malware, keyloggers  
+
+Always follow security best practices for your specific use case.
+
+## Cross-Platform Compatibility
+
+This package uses **AES-256-GCM**, which is supported across all platforms:
+
+| Platform | Support | Notes |
+|----------|---------|-------|
+| **Browser** | ✅ | Web Crypto API (all modern browsers) |
+| **Node.js** | ✅ | Native crypto module (v15+) |
+| **Electron** | ✅ | Both main and renderer processes |
+| **React Native** | ✅ | Via polyfills |
+| **Web Workers** | ✅ | Web Crypto API available |
+
+## Development
+
+```bash
+# Build the package
+npm run build
+
+# Run tests
+npm test
+```
+
+## Related Packages
+
+- **[@cryptforge/auth](../auth)** - Key derivation using `deriveDataEncryptionKey()`
+- **[@cryptforge/core](../core)** - Core types and interfaces
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,125 @@
+/**
+ * Generic interface for cryptographic operations.
+ *
+ * @template TKey - The encryption key type (CryptoKey for browser, Buffer for Node.js)
+ */
+interface CryptoOperations<TKey = unknown> {
+    /**
+     * Encryption key for all document operations.
+     * All documents are encrypted at rest using this key.
+     * Browser implementations use CryptoKey, Node.js implementations use Buffer.
+     */
+    setEncryptionKey?: (key: TKey) => void;
+    /**
+     * Creates an encryption function that encrypts string data using AES-GCM encryption.
+     * Returns a curried function that uses the instance's encryption key from `setEncryptionKey`.
+     *
+     * The returned function signature:
+     * - `data`: The plaintext string to encrypt
+     * - Returns: A promise resolving to the encrypted data as a string
+     */
+    encrypt: () => (data: string) => Promise<string>;
+    /**
+     * Creates a decryption function that decrypts encrypted string data using AES-GCM decryption.
+     * Returns a curried function that uses the instance's encryption key from `setEncryptionKey`.
+     *
+     * The returned function signature:
+     * - `encryptedData`: The encrypted string data to decrypt
+     * - Returns: A promise resolving to the decrypted plaintext string
+     */
+    decrypt: () => (encryptedData: string) => Promise<string>;
+}
+/**
+ * Configuration options for cryptographic operations
+ */
+interface CryptoConfig {
+    /**
+     * Algorithm to use for encryption/decryption
+     */
+    algorithm?: string;
+    /**
+     * Key derivation iterations (if applicable)
+     */
+    iterations?: number;
+}
+/**
+ * Result of an encryption operation
+ */
+interface EncryptionResult {
+    /**
+     * Encrypted data
+     */
+    ciphertext: Uint8Array;
+    /**
+     * Initialization vector or nonce
+     */
+    iv: Uint8Array;
+    /**
+     * Authentication tag (for authenticated encryption)
+     */
+    tag?: Uint8Array;
+}
+/**
+ * Result of a decryption operation
+ */
+interface DecryptionResult {
+    /**
+     * Decrypted plaintext data
+     */
+    plaintext: Uint8Array;
+}
+/**
+ * Key pair for asymmetric cryptography
+ */
+interface KeyPair {
+    /**
+     * Public key
+     */
+    publicKey: Uint8Array;
+    /**
+     * Private key
+     */
+    privateKey: Uint8Array;
+}
+
+/**
+ * Browser implementation of cryptographic operations using Web Crypto API.
+ * Uses CryptoKey for encryption/decryption operations.
+ */
+declare class CryptoBrowser implements CryptoOperations<CryptoKey> {
+    private encryptionKey?;
+    /**
+     * Creates a new CryptoBrowser instance.
+     * @param getEncryptionKey - Function that returns the encryption key for this instance
+     */
+    constructor();
+    /**
+     * Sets the encryption key for the encrypt and decrypt operations.
+     * Validates that the key is AES-GCM with 256-bit length for cross-platform compatibility.
+     *
+     * @param key - The encryption key to set (must be AES-GCM 256-bit)
+     * @throws {Error} If key is not AES-GCM or not 256-bit
+     */
+    setEncryptionKey: (key: CryptoKey) => void;
+    /**
+     * Creates an encryption function that encrypts string data using AES-GCM encryption.
+     * Uses a random initialization vector (IV) for each encryption operation.
+     * The IV is prepended to the ciphertext and the result is base64-encoded.
+     * Uses the encryption key provided via the `setEncryptionKey` method.
+     *
+     * @returns A curried function that encrypts data
+     */
+    encrypt: () => (data: string) => Promise<string>;
+    /**
+     * Creates a decryption function that decrypts encrypted string data using AES-GCM decryption.
+     * Extracts the IV from the beginning of the encrypted data and uses it to decrypt the ciphertext.
+     * Uses the encryption key provided via the constructor.
+     *
+     * @returns A curried function that decrypts data
+     */
+    decrypt: () => (encryptedData: string) => Promise<string>;
+}
+
+declare const version = "0.1.0";
+
+export { CryptoBrowser, type CryptoConfig, type CryptoOperations, type DecryptionResult, type EncryptionResult, type KeyPair, version };

package/dist/index.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Generic interface for cryptographic operations.
+ *
+ * @template TKey - The encryption key type (CryptoKey for browser, Buffer for Node.js)
+ */
+interface CryptoOperations<TKey = unknown> {
+    /**
+     * Encryption key for all document operations.
+     * All documents are encrypted at rest using this key.
+     * Browser implementations use CryptoKey, Node.js implementations use Buffer.
+     */
+    setEncryptionKey?: (key: TKey) => void;
+    /**
+     * Creates an encryption function that encrypts string data using AES-GCM encryption.
+     * Returns a curried function that uses the instance's encryption key from `setEncryptionKey`.
+     *
+     * The returned function signature:
+     * - `data`: The plaintext string to encrypt
+     * - Returns: A promise resolving to the encrypted data as a string
+     */
+    encrypt: () => (data: string) => Promise<string>;
+    /**
+     * Creates a decryption function that decrypts encrypted string data using AES-GCM decryption.
+     * Returns a curried function that uses the instance's encryption key from `setEncryptionKey`.
+     *
+     * The returned function signature:
+     * - `encryptedData`: The encrypted string data to decrypt
+     * - Returns: A promise resolving to the decrypted plaintext string
+     */
+    decrypt: () => (encryptedData: string) => Promise<string>;
+}
+/**
+ * Configuration options for cryptographic operations
+ */
+interface CryptoConfig {
+    /**
+     * Algorithm to use for encryption/decryption
+     */
+    algorithm?: string;
+    /**
+     * Key derivation iterations (if applicable)
+     */
+    iterations?: number;
+}
+/**
+ * Result of an encryption operation
+ */
+interface EncryptionResult {
+    /**
+     * Encrypted data
+     */
+    ciphertext: Uint8Array;
+    /**
+     * Initialization vector or nonce
+     */
+    iv: Uint8Array;
+    /**
+     * Authentication tag (for authenticated encryption)
+     */
+    tag?: Uint8Array;
+}
+/**
+ * Result of a decryption operation
+ */
+interface DecryptionResult {
+    /**
+     * Decrypted plaintext data
+     */
+    plaintext: Uint8Array;
+}
+/**
+ * Key pair for asymmetric cryptography
+ */
+interface KeyPair {
+    /**
+     * Public key
+     */
+    publicKey: Uint8Array;
+    /**
+     * Private key
+     */
+    privateKey: Uint8Array;
+}
+
+/**
+ * Browser implementation of cryptographic operations using Web Crypto API.
+ * Uses CryptoKey for encryption/decryption operations.
+ */
+declare class CryptoBrowser implements CryptoOperations<CryptoKey> {
+    private encryptionKey?;
+    /**
+     * Creates a new CryptoBrowser instance.
+     * @param getEncryptionKey - Function that returns the encryption key for this instance
+     */
+    constructor();
+    /**
+     * Sets the encryption key for the encrypt and decrypt operations.
+     * Validates that the key is AES-GCM with 256-bit length for cross-platform compatibility.
+     *
+     * @param key - The encryption key to set (must be AES-GCM 256-bit)
+     * @throws {Error} If key is not AES-GCM or not 256-bit
+     */
+    setEncryptionKey: (key: CryptoKey) => void;
+    /**
+     * Creates an encryption function that encrypts string data using AES-GCM encryption.
+     * Uses a random initialization vector (IV) for each encryption operation.
+     * The IV is prepended to the ciphertext and the result is base64-encoded.
+     * Uses the encryption key provided via the `setEncryptionKey` method.
+     *
+     * @returns A curried function that encrypts data
+     */
+    encrypt: () => (data: string) => Promise<string>;
+    /**
+     * Creates a decryption function that decrypts encrypted string data using AES-GCM decryption.
+     * Extracts the IV from the beginning of the encrypted data and uses it to decrypt the ciphertext.
+     * Uses the encryption key provided via the constructor.
+     *
+     * @returns A curried function that decrypts data
+     */
+    decrypt: () => (encryptedData: string) => Promise<string>;
+}
+
+declare const version = "0.1.0";
+
+export { CryptoBrowser, type CryptoConfig, type CryptoOperations, type DecryptionResult, type EncryptionResult, type KeyPair, version };

package/dist/index.js

@@ -0,0 +1,119 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  CryptoBrowser: () => CryptoBrowser,
+  version: () => version
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/client/CryptoBrowser.ts
+var CryptoBrowser = class {
+  encryptionKey;
+  /**
+   * Creates a new CryptoBrowser instance.
+   * @param getEncryptionKey - Function that returns the encryption key for this instance
+   */
+  constructor() {
+  }
+  /**
+   * Sets the encryption key for the encrypt and decrypt operations.
+   * Validates that the key is AES-GCM with 256-bit length for cross-platform compatibility.
+   *
+   * @param key - The encryption key to set (must be AES-GCM 256-bit)
+   * @throws {Error} If key is not AES-GCM or not 256-bit
+   */
+  setEncryptionKey = (key) => {
+    if (key.algorithm.name !== "AES-GCM") {
+      throw new Error(
+        `Invalid key algorithm: ${key.algorithm.name}. Key must be AES-GCM for cross-platform compatibility with CryptoServer.`
+      );
+    }
+    const keyLength = key.algorithm.length;
+    if (keyLength !== 256) {
+      throw new Error(
+        `Invalid key length: ${keyLength} bits. Key must be 256-bit for cross-platform compatibility with CryptoServer (AES-256-GCM).`
+      );
+    }
+    this.encryptionKey = key;
+  };
+  /**
+   * Creates an encryption function that encrypts string data using AES-GCM encryption.
+   * Uses a random initialization vector (IV) for each encryption operation.
+   * The IV is prepended to the ciphertext and the result is base64-encoded.
+   * Uses the encryption key provided via the `setEncryptionKey` method.
+   *
+   * @returns A curried function that encrypts data
+   */
+  encrypt = () => async (data) => {
+    const key = this.encryptionKey;
+    if (!key) {
+      throw new Error(
+        "Encryption key not available. You must call `setEncryptionKey` before using this instance."
+      );
+    }
+    const iv = crypto.getRandomValues(new Uint8Array(12));
+    const encrypted = await crypto.subtle.encrypt(
+      { name: "AES-GCM", iv },
+      key,
+      new TextEncoder().encode(data)
+    );
+    const combined = new Uint8Array(iv.length + encrypted.byteLength);
+    combined.set(iv);
+    combined.set(new Uint8Array(encrypted), iv.length);
+    return btoa(String.fromCharCode(...combined));
+  };
+  /**
+   * Creates a decryption function that decrypts encrypted string data using AES-GCM decryption.
+   * Extracts the IV from the beginning of the encrypted data and uses it to decrypt the ciphertext.
+   * Uses the encryption key provided via the constructor.
+   *
+   * @returns A curried function that decrypts data
+   */
+  decrypt = () => async (encryptedData) => {
+    const key = this.encryptionKey;
+    if (!key) {
+      throw new Error(
+        "Encryption key not available. You must call `setEncryptionKey` before using this instance."
+      );
+    }
+    const combined = Uint8Array.from(
+      atob(encryptedData),
+      (c) => c.charCodeAt(0)
+    );
+    const iv = combined.slice(0, 12);
+    const ciphertext = combined.slice(12);
+    const decrypted = await crypto.subtle.decrypt(
+      { name: "AES-GCM", iv },
+      key,
+      ciphertext
+    );
+    return new TextDecoder().decode(decrypted);
+  };
+};
+
+// src/index.ts
+var version = "0.1.0";
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CryptoBrowser,
+  version
+});