@cryptforge/auth 0.1.0

package/README.md

@@ -0,0 +1,914 @@
+# @cryptforge/auth
+
+Browser-compatible authentication and key management for cryptocurrency wallets. Built on industry-standard BIP39/BIP44 with secure keystore encryption.
+
+## Features
+
+- 🔐 **Secure Key Management** - BIP39 mnemonics encrypted with PBKDF2 + AES-256-CBC
+- 🌐 **Browser-First** - Zero configuration, works everywhere (browser, Node.js, Electron, React Native)
+- 🔗 **Multi-Blockchain** - Pluggable adapter system for any blockchain
+- 👤 **Multi-Identity** - Manage multiple wallets with separate keystores
+- 🔒 **Auto-Lock** - Configurable session timeouts for security
+- ⏱️ **Key Expiration** - Automatic tracking with live countdowns
+- 💾 **IndexedDB Storage** - Encrypted keystores persisted locally
+- 🎯 **Type-Safe** - Full TypeScript support
+- 📦 **Lightweight** - ~26 KB minified
+
+## Installation
+
+```bash
+npm install @cryptforge/auth @cryptforge/blockchain-evm @cryptforge/blockchain-btc
+```
+
+## Quick Start
+
+```typescript
+import { createAuthClient } from "@cryptforge/auth";
+import { EVMAdapter } from "@cryptforge/blockchain-evm";
+import { BitcoinAdapter } from "@cryptforge/blockchain-btc";
+
+// Create auth client
+const auth = createAuthClient();
+
+// Register blockchain adapters
+auth.registerAdapter(
+  "ethereum",
+  new EVMAdapter({
+    chainData: { name: "Ethereum", symbol: "ETH", cmc_id: 1027 },
+    coinType: 60,
+  })
+);
+
+auth.registerAdapter("bitcoin", new BitcoinAdapter());
+
+// Generate mnemonic
+const mnemonic = auth.generateMnemonic({ wordCount: 12 });
+
+// Create identity
+const { identity, keys } = await auth.createIdentity({
+  mnemonic,
+  password: "secure-password",
+  label: "Personal Wallet",
+  chainId: "ethereum",
+});
+
+console.log("Address:", keys.address);
+```
+
+## Usage Guide
+
+### First Time Setup
+
+#### 1. Generate and Backup Mnemonic
+
+```typescript
+// Generate a new mnemonic
+const mnemonic = auth.generateMnemonic({ wordCount: 12 });
+// Example: "abandon ability able about above absent absorb abstract absurd abuse access accident"
+
+// ⚠️ CRITICAL: Display to user and require backup confirmation
+// User must write down or securely store the mnemonic
+```
+
+#### 2. Create Identity
+
+```typescript
+const { identity, keys } = await auth.createIdentity({
+  mnemonic: mnemonic,
+  password: "user-chosen-password",
+  label: "Personal Wallet",
+  metadata: {
+    createdBy: "MyApp",
+    version: "1.0.0",
+  },
+  chainId: "ethereum", // Optional: unlock with specific chain
+});
+
+// Identity created and encrypted in IndexedDB
+// If chainId provided, wallet is unlocked and ready to use
+```
+
+### Returning User Flow
+
+#### 1. List Available Identities
+
+```typescript
+const identities = await auth.listIdentities();
+// [
+//   {
+//     id: 'identity_A1B2C3D4',
+//     label: 'Personal Wallet',
+//     fingerprint: 'A1B2C3D4',
+//     createdAt: Date,
+//     lastAccess: Date
+//   }
+// ]
+```
+
+#### 2. Select and Unlock
+
+```typescript
+// Select an identity
+await auth.switchIdentity(identities[0].id);
+
+// Unlock with password
+const { keys } = await auth.unlock({
+  password: "user-chosen-password",
+  chainId: "ethereum",
+  duration: 10 * 60 * 1000, // Auto-lock after 10 minutes
+});
+
+// Wallet is now unlocked and ready to sign
+console.log("Address:", keys.address);
+console.log("Expires in:", auth.currentExpiresIn, "seconds");
+```
+
+## Core Features
+
+### Identity Management
+
+#### Create Identity
+
+```typescript
+const { identity, keys } = await auth.createIdentity({
+  mnemonic: "word1 word2 ... word12",
+  password: "secure-password",
+  label: "Trading Wallet",
+  metadata: { purpose: "trading" },
+  chainId: "ethereum", // Optional
+});
+```
+
+#### Import Identity
+
+```typescript
+// From mnemonic backup
+const { identity } = await auth.importIdentity(
+  "word1 word2 ... word12",
+  "new-password",
+  "mnemonic"
+);
+
+// From keystore JSON
+const { identity } = await auth.importIdentity(
+  keystoreJsonString,
+  "password",
+  "keystore"
+);
+```
+
+#### Export Identity
+
+```typescript
+// Export as mnemonic (for backup)
+const { data: mnemonic } = await auth.exportIdentity(identity.id, {
+  password: "password",
+  format: "mnemonic",
+});
+
+// Export as keystore JSON
+const { data: keystore } = await auth.exportIdentity(identity.id, {
+  password: "password",
+  format: "keystore",
+});
+```
+
+#### Delete Identity
+
+```typescript
+// Permanently delete (requires password)
+await auth.deleteIdentity(identity.id, "password");
+// ⚠️ Make sure mnemonic is backed up first!
+```
+
+#### Update Identity
+
+```typescript
+await auth.updateIdentity(identity.id, {
+  label: "Updated Wallet Name",
+  metadata: { theme: "dark" },
+});
+```
+
+#### Change Password
+
+```typescript
+await auth.changePassword(identity.id, "old-password", "new-password");
+```
+
+### Session Management
+
+#### Unlock
+
+```typescript
+const { keys } = await auth.unlock({
+  password: "password",
+  chainId: "ethereum",
+  duration: 15 * 60 * 1000, // Optional: auto-lock after 15 min
+});
+
+// Access derived keys
+console.log("Address:", keys.address);
+console.log("Public Key:", keys.publicKeyHex);
+console.log("Derivation Path:", keys.derivationPath);
+console.log("Expires At:", keys.expiresAt);
+```
+
+#### Lock
+
+```typescript
+await auth.lock();
+// Clears keys from memory
+// Keystore remains encrypted in IndexedDB
+```
+
+### Blockchain Operations
+
+#### Switch Chain
+
+```typescript
+// Switch to different blockchain (if already unlocked)
+await auth.switchChain("bitcoin");
+
+// Switch when locked (requires password)
+await auth.switchChain("bitcoin", "password");
+```
+
+#### Get Addresses
+
+```typescript
+// Get multiple addresses for a chain
+const addresses = await auth.getAddresses("ethereum", 0, 5);
+// [
+//   { address: '0x...', path: "m/44'/60'/0'/0/0", index: 0 },
+//   { address: '0x...', path: "m/44'/60'/0'/0/1", index: 1 },
+//   ...
+// ]
+
+// Get specific address by index
+const { address, publicKey, derivationPath } = await auth.getAddressForChain(
+  "bitcoin",
+  0
+);
+```
+
+#### Find Used Addresses (Account Discovery)
+
+```typescript
+// Find all addresses with balance
+const usedAddresses = await auth.findUsedAddresses(
+  "ethereum",
+  async (address) => {
+    // Your balance checking logic
+    const balance = await checkBalance(address);
+    return balance > 0;
+  }
+);
+// Scans with BIP44 gap limit of 20
+```
+
+### Cryptographic Operations
+
+#### Sign Message
+
+```typescript
+const { signature, address, publicKey } = await auth.signMessage({
+  message: "Hello CryptForge!",
+});
+
+// Sign with different derivation path
+const result = await auth.signMessage({
+  message: "Custom path",
+  derivationPath: "m/44'/60'/0'/0/1",
+});
+```
+
+#### Sign Transaction
+
+```typescript
+const { signedTransaction, signature } = await auth.signTransaction({
+  transaction: {
+    to: "0x...",
+    value: "1000000000000000000", // 1 ETH in wei
+    gasLimit: 21000,
+  },
+});
+
+// Sign with different key
+const result = await auth.signTransaction({
+  transaction: tx,
+  derivationPath: "m/44'/60'/0'/0/5",
+});
+```
+
+#### Verify Signature
+
+```typescript
+const isValid = await auth.verifySignature(
+  "Hello CryptForge!",
+  signature,
+  publicKey
+);
+```
+
+### Key Management
+
+#### Rotate Keys
+
+```typescript
+// Rotate to next address index
+const { keys } = await auth.rotateKeys();
+console.log("New address:", keys.address);
+
+// Rotate to custom derivation path
+const { keys } = await auth.rotateKeys("m/44'/60'/0'/0/5");
+```
+
+#### Derive Custom Key
+
+```typescript
+// One-time key derivation (not stored in session)
+const { privateKey, publicKey, address, path } = await auth.deriveKey({
+  path: "m/44'/60'/1'/0/0", // Different account
+});
+```
+
+## State Management
+
+### Getters
+
+```typescript
+// Identity state
+auth.currentIdentity; // Identity | null
+auth.hasIdentity; // boolean
+
+// Keys state
+auth.currentKeys; // Keys | null
+auth.currentAddress; // string | null
+auth.currentPublicKey; // string | null (hex)
+
+// Chain state
+auth.currentChain; // Chain | null
+
+// Lock state
+auth.isLocked; // boolean
+auth.isUnlocked; // boolean
+
+// Expiration state
+auth.currentExpiresAt; // Date | null
+auth.currentExpiresIn; // number | null (seconds remaining)
+
+// Available chains
+auth.getRegisteredChains(); // string[]
+```
+
+### Event Subscription
+
+```typescript
+const unsubscribe = auth.onAuthStateChange((event, keys) => {
+  console.log("Event:", event);
+
+  switch (event) {
+    case "IDENTITY_CREATED":
+      console.log("New identity created");
+      break;
+    case "UNLOCKED":
+      console.log("Wallet unlocked:", keys?.address);
+      break;
+    case "LOCKED":
+      console.log("Wallet locked");
+      break;
+    case "CHAIN_SWITCHED":
+      console.log("Switched to:", keys?.chain.name);
+      break;
+    case "KEYS_ROTATED":
+      console.log("Keys rotated to:", keys?.address);
+      break;
+    case "KEYS_EXPIRED":
+      console.log("Keys expired, please unlock again");
+      break;
+    // ... other events
+  }
+});
+
+// Unsubscribe when done
+unsubscribe();
+```
+
+### Available Events
+
+- `IDENTITY_CREATED` - New identity created
+- `IDENTITY_RESTORED` - Identity imported/restored
+- `IDENTITY_SWITCHED` - Switched to different identity
+- `IDENTITY_UPDATED` - Identity metadata updated
+- `IDENTITY_DELETED` - Identity removed
+- `PASSWORD_CHANGED` - Password updated
+- `UNLOCKED` - Wallet unlocked with keys
+- `LOCKED` - Wallet locked
+- `KEYS_ROTATED` - Keys rotated to new address
+- `KEYS_EXPIRED` - Keys passed expiration time
+- `KEY_DERIVED` - Custom key derived
+- `CHAIN_SWITCHED` - Switched to different blockchain
+
+## Blockchain Adapters
+
+### Registering Adapters
+
+```typescript
+import { EVMAdapter } from "@cryptforge/blockchain-evm";
+import { BitcoinAdapter } from "@cryptforge/blockchain-btc";
+
+// Ethereum
+auth.registerAdapter(
+  "ethereum",
+  new EVMAdapter({
+    chainData: { name: "Ethereum", symbol: "ETH", cmc_id: 1027 },
+    coinType: 60,
+    networks: {
+      mainnet: {
+        name: "Ethereum Mainnet",
+        rpcUrl: "https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY",
+        chainId: 1,
+      },
+    },
+  })
+);
+
+// Bitcoin
+auth.registerAdapter("bitcoin", new BitcoinAdapter());
+
+// Polygon (EVM-compatible)
+auth.registerAdapter(
+  "polygon",
+  new EVMAdapter({
+    chainData: { name: "Polygon", symbol: "MATIC", cmc_id: 3890 },
+    coinType: 60,
+    networks: {
+      mainnet: {
+        name: "Polygon Mainnet",
+        rpcUrl: "https://polygon-rpc.com",
+        chainId: 137,
+      },
+    },
+  })
+);
+```
+
+### Creating Custom Adapters
+
+Implement the `BlockchainAdapter` interface to add support for new blockchains:
+
+```typescript
+import type { BlockchainAdapter, KeyData, ChainData } from "@cryptforge/core";
+
+class SolanaAdapter implements BlockchainAdapter {
+  readonly chainData: ChainData = {
+    name: "Solana",
+    symbol: "SOL",
+    cmc_id: 5426,
+  };
+
+  async deriveKeys(mnemonic: string): Promise<KeyData> {
+    // Implement Solana key derivation
+  }
+
+  async deriveKeysAtIndex(mnemonic: string, index: number): Promise<KeyData> {
+    // Implement indexed derivation
+  }
+
+  // ... implement all required methods
+}
+
+// Register your custom adapter
+auth.registerAdapter("solana", new SolanaAdapter());
+```
+
+## API Reference
+
+### Methods
+
+#### Identity Management
+
+| Method             | Parameters                                                          | Returns                       | Description             |
+| ------------------ | ------------------------------------------------------------------- | ----------------------------- | ----------------------- |
+| `generateMnemonic` | `options?: { wordCount?: 12 \| 24 }`                                | `string`                      | Generate BIP39 mnemonic |
+| `createIdentity`   | `CreateIdentityOptions & { chainId?: string }`                      | `Promise<{ identity, keys }>` | Create new identity     |
+| `importIdentity`   | `data: string, password: string, format?: 'mnemonic' \| 'keystore'` | `Promise<{ identity }>`       | Import from backup      |
+| `exportIdentity`   | `identityId: string, options: ExportOptions`                        | `Promise<{ format, data }>`   | Export identity         |
+| `listIdentities`   | -                                                                   | `Promise<Identity[]>`         | Get all identities      |
+| `switchIdentity`   | `identityId: string`                                                | `Promise<{ identity }>`       | Switch active identity  |
+| `updateIdentity`   | `identityId: string, updates: { label?, metadata? }`                | `Promise<{ identity }>`       | Update metadata         |
+| `deleteIdentity`   | `identityId: string, password: string`                              | `Promise<void>`               | Delete identity         |
+| `changePassword`   | `identityId: string, oldPassword: string, newPassword: string`      | `Promise<void>`               | Change password         |
+
+#### Session Management
+
+| Method   | Parameters      | Returns             | Description            |
+| -------- | --------------- | ------------------- | ---------------------- |
+| `unlock` | `UnlockOptions` | `Promise<{ keys }>` | Decrypt and load keys  |
+| `lock`   | -               | `Promise<void>`     | Clear keys from memory |
+
+#### Chain Management
+
+| Method                | Parameters                                    | Returns             | Description              |
+| --------------------- | --------------------------------------------- | ------------------- | ------------------------ |
+| `registerAdapter`     | `chainId: string, adapter: BlockchainAdapter` | `void`              | Register blockchain      |
+| `switchChain`         | `chainId: string, password?: string`          | `Promise<{ keys }>` | Switch blockchain        |
+| `getRegisteredChains` | -                                             | `string[]`          | Get registered chain IDs |
+
+#### Key Operations
+
+| Method       | Parameters                   | Returns                                             | Description            |
+| ------------ | ---------------------------- | --------------------------------------------------- | ---------------------- |
+| `rotateKeys` | `newDerivationPath?: string` | `Promise<{ keys }>`                                 | Rotate to next address |
+| `deriveKey`  | `DeriveKeyOptions`           | `Promise<{ privateKey, publicKey, address, path }>` | One-time derivation    |
+
+#### Cryptographic Operations
+
+| Method            | Parameters                      | Returns                                      | Description      |
+| ----------------- | ------------------------------- | -------------------------------------------- | ---------------- |
+| `signMessage`     | `SignMessageOptions`            | `Promise<{ signature, address, publicKey }>` | Sign message     |
+| `signTransaction` | `SignTransactionOptions`        | `Promise<{ signedTransaction, signature }>`  | Sign transaction |
+| `verifySignature` | `message, signature, publicKey` | `Promise<boolean>`                           | Verify signature |
+
+#### Address Management
+
+| Method               | Parameters                                        | Returns                                           | Description            |
+| -------------------- | ------------------------------------------------- | ------------------------------------------------- | ---------------------- |
+| `getAddressForChain` | `chainId: string, index?: number`                 | `Promise<{ address, publicKey, derivationPath }>` | Get single address     |
+| `getAddresses`       | `chainId: string, start?: number, count?: number` | `Promise<Array<{ address, path, index }>>`        | Get multiple addresses |
+| `findUsedAddresses`  | `chainId: string, checkBalance: Function`         | `Promise<Array<{ address, path, index }>>`        | Account discovery      |
+
+#### Event Management
+
+| Method              | Parameters                     | Returns      | Description                               |
+| ------------------- | ------------------------------ | ------------ | ----------------------------------------- |
+| `onAuthStateChange` | `callback: AuthChangeCallback` | `() => void` | Subscribe to events (returns unsubscribe) |
+
+### Types
+
+#### CreateIdentityOptions
+
+```typescript
+interface CreateIdentityOptions {
+  mnemonic: string; // BIP39 mnemonic (12 or 24 words)
+  password: string; // Password to encrypt keystore
+  label?: string; // Human-readable label
+  metadata?: Record<string, any>; // Custom metadata
+  chainId?: string; // Optional: unlock with specific chain
+}
+```
+
+#### UnlockOptions
+
+```typescript
+interface UnlockOptions {
+  password: string; // Keystore decryption password
+  identityId?: string; // Which identity to unlock (defaults to current)
+  chainId?: string; // Which blockchain to use (required)
+  derivationPath?: string; // Custom derivation path (advanced)
+  duration?: number; // Auto-lock duration in ms
+}
+```
+
+#### Identity
+
+```typescript
+interface Identity {
+  id: string; // Unique identifier
+  publicKey: string; // Master public key (xpub)
+  fingerprint: string; // Master key fingerprint
+  label?: string; // User-defined label
+  metadata: Record<string, any>;
+  createdAt: Date;
+  lastAccess?: Date;
+}
+```
+
+#### Keys
+
+```typescript
+interface Keys {
+  privateKey: Uint8Array; // Derived private key (binary)
+  privateKeyHex: string; // Derived private key (hex)
+  publicKey: Uint8Array; // Derived public key (binary)
+  publicKeyHex: string; // Derived public key (hex)
+  address: string; // Blockchain address
+  derivationPath: string; // BIP44 path (e.g., "m/44'/60'/0'/0/0")
+  chain: Chain; // Current blockchain
+  expiresAt: Date; // When keys expire
+  expiresIn: number; // Seconds until expiration (at creation)
+  identity: Identity; // Associated identity
+}
+```
+
+#### Chain
+
+```typescript
+interface Chain {
+  id: string; // Chain identifier (e.g., 'ethereum')
+  name: string; // Display name (e.g., 'Ethereum')
+  symbol: string; // Token symbol (e.g., 'ETH')
+}
+```
+
+## Security Best Practices
+
+### 1. Mnemonic Backup
+
+```typescript
+// Always require user confirmation before creating identity
+const mnemonic = auth.generateMnemonic({ wordCount: 12 });
+
+// Show to user with clear warnings:
+// ⚠️ Write down these words in order
+// ⚠️ Never share with anyone
+// ⚠️ Store in a secure location
+// ⚠️ Losing these words = losing access to funds
+
+// Only proceed after confirmation
+await auth.createIdentity({ mnemonic, password, ... });
+```
+
+### 2. Password Requirements
+
+```typescript
+// Enforce strong passwords
+function isStrongPassword(password: string): boolean {
+  return (
+    password.length >= 12 &&
+    /[A-Z]/.test(password) &&
+    /[a-z]/.test(password) &&
+    /[0-9]/.test(password) &&
+    /[^A-Za-z0-9]/.test(password)
+  );
+}
+```
+
+### 3. Auto-Lock
+
+```typescript
+// Always use auto-lock for security
+await auth.unlock({
+  password,
+  chainId: "ethereum",
+  duration: 5 * 60 * 1000, // Lock after 5 minutes of inactivity
+});
+```
+
+### 4. Key Expiration Monitoring
+
+```typescript
+// Monitor expiration in your UI
+setInterval(() => {
+  const remaining = auth.currentExpiresIn;
+  if (remaining !== null && remaining < 60) {
+    console.warn("Keys expiring soon!");
+    // Show UI warning
+  }
+}, 1000);
+
+// Listen for expiration event
+auth.onAuthStateChange((event) => {
+  if (event === "KEYS_EXPIRED") {
+    // Prompt user to unlock again
+  }
+});
+```
+
+### 5. Secure Key Handling
+
+```typescript
+// Never log private keys in production
+if (process.env.NODE_ENV !== "production") {
+  console.log("Private Key:", keys.privateKeyHex);
+}
+
+// Use public key for verification
+console.log("Public Key:", keys.publicKeyHex); // Safe to log
+
+// Lock when not in use
+window.addEventListener("beforeunload", () => {
+  auth.lock();
+});
+```
+
+## Advanced Usage
+
+### Multiple Identities
+
+```typescript
+// Create multiple wallets
+const personal = await auth.createIdentity({
+  mnemonic: generateMnemonic(),
+  password: "password1",
+  label: "Personal",
+});
+
+const trading = await auth.createIdentity({
+  mnemonic: generateMnemonic(),
+  password: "password2",
+  label: "Trading",
+});
+
+// Switch between them
+await auth.switchIdentity(trading.identity.id);
+await auth.unlock({ password: "password2", chainId: "ethereum" });
+```
+
+### Custom Derivation Paths
+
+```typescript
+// Derive keys at custom path
+const customKey = await auth.deriveKey({
+  path: "m/44'/60'/1'/0/0", // Account 1 instead of 0
+});
+
+// Sign with custom path
+const { signature } = await auth.signMessage({
+  message: "Hello",
+  derivationPath: "m/44'/60'/1'/0/0",
+});
+```
+
+### React/Vue Integration
+
+```typescript
+import { ref, onMounted, onUnmounted } from "vue";
+
+const currentAddress = ref(auth.currentAddress);
+const expiresIn = ref(auth.currentExpiresIn);
+
+// Subscribe to changes
+const unsubscribe = auth.onAuthStateChange((event, keys) => {
+  currentAddress.value = auth.currentAddress;
+  expiresIn.value = auth.currentExpiresIn;
+});
+
+// Live expiration countdown
+const interval = setInterval(() => {
+  expiresIn.value = auth.currentExpiresIn;
+}, 1000);
+
+// Cleanup
+onUnmounted(() => {
+  unsubscribe();
+  clearInterval(interval);
+});
+```
+
+## Master Public Key
+
+Get the master public key derived from the mnemonic.
+
+### Security Note
+
+This returns ONLY the public key bytes (33 bytes, compressed secp256k1), NOT the extended public key (xpub). This is safe to expose publicly because:
+
+1. ✅ Cannot derive child keys (no chaincode included)
+2. ✅ Cannot compute private keys
+3. ✅ Standard public key cryptography - public keys are meant to be public
+4. ✅ Chain-independent - same key regardless of blockchain
+
+### Use Cases
+
+- Document ownership verification
+- Identity verification across different blockchains
+- Signature verification
+- Access control (e.g., "owner" field in documents)
+
+### What This Is NOT
+
+- ❌ NOT an extended public key (xpub) - does not include chaincode
+- ❌ NOT a blockchain address - this is the raw master public key
+- ❌ NOT blockchain-specific - same for all chains
+
+### Usage
+
+```typescript
+await auth.unlock({ password: 'my-password' });
+
+const masterPubKey = auth.masterPublicKey;
+// "02a1b2c3d4e5f6..." (33 bytes hex, compressed secp256k1)
+
+// Use for document ownership
+const document = {
+  id: 'doc_123',
+  owner: masterPubKey, // ← Chain-independent identity!
+  data: { ... }
+};
+
+// Sign with current blockchain key
+const signature = await auth.signMessage({
+  message: `${document.id}:update:${Date.now()}`
+});
+
+// Server can verify ownership regardless of chain
+```
+
+## BIP44 Document ID
+
+Derives a deterministic document ID using BIP44-style hierarchical derivation.
+
+This creates chain-independent, deterministic document IDs that can be used with Automerge or any other document system. The ID is derived from your mnemonic using BIP44 HD key derivation, ensuring the same inputs always produce the same ID.
+
+**How it works:** `deriveBIP44DocumentID()` generates a 32-byte seed from your mnemonic. When passed to `store.create()` as the second parameter, Automerge uses this seed with UUID v5 to create a deterministic document URL. Same seed = same document every time!
+
+### Path Structure
+
+`m/44'/[appId]'/[account]'/[purpose]/[index]`
+
+### Purpose Parameter Guidance
+
+The `purpose` parameter (4th level) can represent document types or categories. This is flexible and application-specific. Examples:
+
+- 0: Profile/Settings
+- 1: Notes
+- 2: Tasks
+- 3: Documents
+- 100+: Custom types
+
+### Parameters
+
+- `options.appId` - Application identifier (1000000+ recommended, will be hardened)
+- `options.account` - Account/workspace number (default: 0, hardened)
+- `options.purpose` - Document type/category (default: 0, non-hardened)
+- `options.index` - Document instance number (default: 0, non-hardened)
+
+### Returns
+
+Hex-encoded document ID (32 bytes / 64 hex chars)
+
+### Usage
+
+```typescript
+// Derive document ID
+const docId = await auth.deriveBIP44DocumentID({
+  appId: 1000000,
+  purpose: 0, // Settings type
+  index: 0, // First settings doc
+});
+
+// Create document with deterministic ID
+await store.create({ type: "settings", theme: "dark" }, docId);
+
+// Later, re-derive the same ID
+const sameId = await auth.deriveBIP44DocumentID({
+  appId: 1000000,
+  purpose: 0,
+  index: 0,
+});
+const settings = await store.get(sameId); // Gets existing doc!
+```
+
+See `BIP44_DOCUMENT_ID.md` for detailed documentation and examples.
+
+## Browser Compatibility
+
+This package is **100% browser-compatible** with zero configuration:
+
+- ✅ Chrome, Firefox, Safari, Edge
+- ✅ Node.js (v16+)
+- ✅ Electron (main and renderer)
+- ✅ React Native
+- ✅ Web Workers
+- ✅ Service Workers
+
+**No polyfills required.** Uses native browser APIs:
+
+- `crypto.subtle` for encryption
+- `indexedDB` for storage
+- `Uint8Array` for binary data
+
+## Dependencies
+
+```json
+{
+  "@scure/bip39": "^1.2.1",
+  "@scure/bip32": "^1.3.2",
+  "@cryptforge/core": "workspace:*"
+}
+```
+
+All dependencies are browser-safe, audited, and actively maintained.
+
+## Examples
+
+See the complete working example in `examples/vue-electron-example/src/AuthTest.vue`.
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions welcome! Please ensure:
+
+- All code is browser-compatible (use `@scure` and `@noble` libraries)
+- TypeScript types are properly defined
+- Examples are updated
+- Tests pass (when implemented)
+
+## Support
+
+For issues, questions, or feature requests, please open an issue on GitHub.