@private.me/xbind 3.0.3 → 3.1.0

package/README.md.backup

@@ -1,2121 +0,0 @@
-# @private.me/xbind
-
-![npm version](https://img.shields.io/npm/v/@private.me/xbind)
-![version](https://img.shields.io/badge/version-3.0.3-blue)
-![tests](https://img.shields.io/badge/tests-2762%20passing-brightgreen)
-![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue)
-![license](https://img.shields.io/badge/license-Proprietary-blue)
-
-**Authenticated agent-to-agent messaging with post-quantum cryptographic identity.**
-
-Build AI agents that communicate securely using ML-DSA-65 DID identity, ML-KEM-768 + AES-256-GCM encryption, and information-theoretic split-channel delivery (XorIDA). Every message is signed and encrypted. No API keys, no rotation, no sprawl.
-
-Part of the **Private.Me** platform—where APIs have keys, but ACIs have identity.
-
-**Version 3.0.3** — **Major Features:** LoopbackTransport export for testing (GAP-CORE-2), describeSecurityModeStructured export (GAP-API-3), Agent.quickstart() signature fixes. Full Control IP Protection (PLAN-13) - Vault Store architecture with payment-gated algorithm delivery. Store Front (npm) contains Share 1 only, Vault Store (EC2) contains Share 2 (payment-gated). Runtime crypto loading, 4-layer security (DID auth + usage quotas + rate limiting + audit logging). Usage-based model: Free tier 100K ops/month (includes vault access), Pro tier unlimited. Previous v3.0.2: Full Control IP Protection launch. Previous v1.4.2: Runtime compatibility, API enhancements.
-
-## Install
-
-```bash
-# Node.js / TypeScript
-npm install @private.me/xbind
-
-# Python
-pip install private-me-xbind
-```
-
-**Distribution Model:** xBind uses Full Control IP protection (2-share XorIDA). Share 1 (Store Front) is distributed via npm registry. Share 2 (Vault Store) is served via `/api/full-control/share2/:package/:version` and requires payment verification and xBind authentication.
-
-[Python SDK documentation](./python/README.md) • [Complete docs](./docs/README.md) • [White paper](https://private.me/docs/xbind.html)
-
-## Security Notice
-
-**Post-Quantum Cryptography:** xBind uses `mldsa-wasm@0.0.4` for post-quantum digital signatures (ML-DSA-65/FIPS 204). This package is pre-1.0 beta software. While based on audited upstream cryptography ([PQCA mldsa](https://github.com/dajiaji/mldsa)), it has not been independently audited.
-
-**Risk Acceptance:** We have accepted this risk for the following reasons:
-- Based on NIST FIPS 204 standardized algorithm
-- Zero production dependencies (minimal supply chain risk)
-- No known CVEs
-- Version pinned (not using semver range) for stability
-
-**Migration Plan:** We plan to migrate to [@noble/post-quantum](https://www.npmjs.com/package/@noble/post-quantum) in Q4 2026 (xBind v2.0.0), which offers broader ecosystem support and maturity.
-
-For production deployments requiring formal cryptographic assurance, please contact contact@private.me for enterprise options.
-
-## Secure Key Storage
-
-**⚠️ CRITICAL SECURITY WARNING:** All post-quantum cryptography in xBind is undermined if seeds/keys are stored in plaintext.
-
-### ❌ NEVER Store Keys in Plaintext
-
-**Dangerous practices that expose your identity:**
-
-<!-- ANTI-PATTERN -->
-```typescript
-// ❌ WRONG: Plaintext file storage
-const seed = agent.exportSeeds();
-fs.writeFileSync('seed.txt', seed);              // Readable by any process
-fs.writeFileSync('.env', `XBIND_SEED=${seed}`);  // Committed to git by accident
-localStorage.setItem('seed', seed);               // Accessible to XSS attacks
-
-// ❌ WRONG: Hardcoded in source code
-const agent = await Agent.fromSeed('0123456789abcdef...');  // Visible in repository
-
-// ❌ WRONG: Unencrypted database
-await db.run('INSERT INTO config VALUES (?, ?)', ['seed', seed]);  // SQL injection risk
-```
-<!-- /ANTI-PATTERN -->
-
-**Why this is critical:**
-- **Identity Theft**: Attacker gains your DID and can impersonate your agent
-- **Message Decryption**: All past and future messages can be decrypted
-- **Billing Fraud**: Attacker can exhaust your quota or make unauthorized charges
-- **Post-Quantum Broken**: ML-KEM and ML-DSA offer no protection if seed is leaked
-
-### ✅ Use OS-Level Keystore APIs
-
-**Recommended secure storage by platform:**
-
-#### macOS: Keychain Services
-
-<!-- SNIPPET -->
-```typescript
-import { exec } from 'node:child_process';
-import { promisify } from 'node:util';
-const execAsync = promisify(exec);
-
-// Store seed in macOS Keychain
-async function storeSeed(seed: string): Promise<void> {
-  await execAsync(
-    `security add-generic-password -a xbind -s "xBind Agent Seed" -w "${seed}" -U`
-  );
-}
-
-// Retrieve seed from macOS Keychain
-async function getSeed(): Promise<string> {
-  const { stdout } = await execAsync(
-    'security find-generic-password -a xbind -s "xBind Agent Seed" -w'
-  );
-  return stdout.trim();
-}
-
-// Create agent from keychain
-import { Agent, HttpTrustRegistry, HttpsTransportAdapter } from '@private.me/xbind';
-
-const seed = await getSeed();
-const result = await Agent.fromSeed(Buffer.from(seed, 'hex'), {
-  registry: new HttpTrustRegistry({ baseUrl: 'https://private.me/registry' }),
-  transport: new HttpsTransportAdapter({ baseUrl: 'https://private.me/relay' }),
-  postQuantumSig: false
-});
-
-if (!result.ok) {
-  throw new Error(`Failed to create agent: ${result.error.message}`);
-}
-
-const agent = result.value;
-```
-<!-- /SNIPPET -->
-
-#### Windows: Credential Manager (DPAPI)
-
-<!-- SNIPPET -->
-```typescript
-// Using keytar package for cross-platform keychain access
-import keytar from 'keytar';
-
-// Store seed in Windows Credential Manager
-await keytar.setPassword('xbind', 'agent-seed', seed);
-
-// Retrieve seed from Windows Credential Manager
-import { Agent, HttpTrustRegistry, HttpsTransportAdapter } from '@private.me/xbind';
-
-const seed = await keytar.getPassword('xbind', 'agent-seed');
-if (!seed) throw new Error('Seed not found in credential store');
-
-const result = await Agent.fromSeed(Buffer.from(seed, 'hex'), {
-  registry: new HttpTrustRegistry({ baseUrl: 'https://private.me/registry' }),
-  transport: new HttpsTransportAdapter({ baseUrl: 'https://private.me/relay' }),
-  postQuantumSig: false
-});
-
-if (!result.ok) {
-  throw new Error(`Failed to create agent: ${result.error.message}`);
-}
-
-const agent = result.value;
-```
-<!-- /SNIPPET -->
-
-#### Linux: Secret Service API (gnome-keyring, KWallet)
-
-<!-- SNIPPET -->
-```typescript
-import keytar from 'keytar';
-
-// Store seed in Secret Service (libsecret)
-await keytar.setPassword('xbind', 'agent-seed', seed);
-
-// Retrieve seed from Secret Service
-import { Agent, HttpTrustRegistry, HttpsTransportAdapter } from '@private.me/xbind';
-
-const seed = await keytar.getPassword('xbind', 'agent-seed');
-if (!seed) throw new Error('Seed not found in Secret Service');
-
-const result = await Agent.fromSeed(Buffer.from(seed, 'hex'), {
-  registry: new HttpTrustRegistry({ baseUrl: 'https://private.me/registry' }),
-  transport: new HttpsTransportAdapter({ baseUrl: 'https://private.me/relay' }),
-  postQuantumSig: false
-});
-
-if (!result.ok) {
-  throw new Error(`Failed to create agent: ${result.error.message}`);
-}
-
-const agent = result.value;
-```
-<!-- /SNIPPET -->
-
-**Cross-platform library:**
-```bash
-npm install keytar  # Unified API for macOS/Windows/Linux keystores
-```
-
-### 🏢 Production: Hardware Security Modules (HSM)
-
-For production deployments with compliance requirements (PCI-DSS, HIPAA, SOC 2):
-
-<!-- SNIPPET -->
-```typescript
-// Using AWS CloudHSM or Azure Key Vault
-import { KMSClient, DecryptCommand } from '@aws-sdk/client-kms';
-
-const kms = new KMSClient({ region: 'us-west-2' });
-
-// Encrypt seed with KMS (one-time setup)
-const encryptedSeed = await kms.send(new EncryptCommand({
-  KeyId: 'arn:aws:kms:us-west-2:...',
-  Plaintext: Buffer.from(seed)
-}));
-
-// Store encrypted seed in database (safe)
-await db.run('INSERT INTO config VALUES (?, ?)', ['seed', encryptedSeed.CiphertextBlob]);
-
-// Decrypt seed with KMS at runtime
-import { Agent, HttpTrustRegistry, HttpsTransportAdapter } from '@private.me/xbind';
-
-const decryptedSeed = await kms.send(new DecryptCommand({
-  CiphertextBlob: encryptedSeedFromDB
-}));
-
-const result = await Agent.fromSeed(Buffer.from(decryptedSeed.Plaintext), {
-  registry: new HttpTrustRegistry({ baseUrl: 'https://private.me/registry' }),
-  transport: new HttpsTransportAdapter({ baseUrl: 'https://private.me/relay' }),
-  postQuantumSig: false
-});
-
-if (!result.ok) {
-  throw new Error(`Failed to create agent: ${result.error.message}`);
-}
-
-const agent = result.value;
-```
-<!-- /SNIPPET -->
-
-**HSM Benefits:**
-- **FIPS 140-2 Level 3** certified hardware
-- **Tamper-evident**: Keys destroyed if physical breach detected
-- **Audit logging**: All key access operations logged
-- **Access control**: IAM policies restrict who can decrypt
-
-### 📋 Key Storage Best Practices
-
-1. **Encrypt at Rest**: If storing in database/filesystem, use AES-256-GCM with a separate encryption key
-2. **Least Privilege**: Only the agent process should have access to the seed
-3. **Rotation**: Plan for key rotation (see Succession API section)
-4. **Backup**: Encrypted backups to separate storage (3-2-1 rule)
-5. **Monitoring**: Alert on unauthorized seed access attempts
-6. **Destruction**: Securely wipe seeds when decommissioning agents
-
-### 🔒 Environment Variable Security
-
-If you MUST use environment variables (not recommended):
-
-```bash
-# ✅ Better: Encrypted environment variable (AWS Secrets Manager)
-export XBIND_SEED=$(aws secretsmanager get-secret-value --secret-id xbind-seed --query SecretString --output text)
-
-# ❌ Avoid: Plaintext in shell history
-export XBIND_SEED="0123456789abcdef..."  # Visible in ~/.bash_history
-```
-
-**Limitations of environment variables:**
-- Visible to all processes (ps, /proc/PID/environ)
-- Logged by process managers (systemd, Docker logs)
-- Inherited by child processes
-- Difficult to rotate without restart
-
-### 🚨 Incident Response
-
-**If your seed is compromised:**
-
-1. **Revoke immediately**: Use the Succession API to rotate to a new identity
-2. **Audit access**: Check all messages sent/received during exposure window
-3. **Notify recipients**: Inform peers to distrust the old DID
-4. **Update registry**: Register new DID, revoke old DID
-5. **Forensics**: Determine how seed was leaked to prevent recurrence
-
-**Contact contact@private.me for incident assistance** (24-hour SLA for Pro/VIP tiers).
-
----
-
-## Dependencies
-
-xBind requires the following runtime dependencies for cryptographic operations and network communication:
-
-### Post-Quantum Cryptography
-
-- **mlkem** — Post-quantum key encapsulation mechanism (ML-KEM-768, FIPS 203)
-  - Purpose: Quantum-resistant key agreement for message encryption
-  - Security: NIST-approved lattice-based cryptography, 192-bit security level
-  - Usage: Establishes shared secrets between agents resistant to quantum attacks
-
-- **mldsa-wasm@0.0.4** — Post-quantum digital signatures (ML-DSA-65, FIPS 204)
-  - Purpose: Quantum-resistant DID identity and message signing
-  - Security: NIST-approved lattice-based signatures, 192-bit security level
-  - Usage: Signs all agent messages and verifies peer identity
-
-### Network Communication
-
-- **bonjour-service** — mDNS service discovery (Peer Discovery model)
-  - Purpose: Zero-configuration local network device pairing
-  - Security: LAN-only discovery with user confirmation and cryptographic verification
-  - Usage: Enables IoT devices and offline pairing without internet connectivity
-
-- **nodemailer@8.0.7** — Email transport for invitation delivery
-  - Purpose: Delivers single-use invite codes for customer onboarding
-  - Security: 6-character codes with 24-hour TTL, rate-limited generation
-  - Usage: Supports Invite Code connection model for remote agent pairing
-
-### Internal Dependencies (Bundled)
-
-The following @private.me/* packages are bundled into xBind's distribution and do not require separate installation:
-
-- **@private.me/shared** — Core types and Result<T,E> error handling primitives
-- **@private.me/crypto** — XorIDA threshold sharing, HMAC verification, cryptographic primitives
-- **@private.me/xchange** — Transport envelope formatting and message serialization
-- **@private.me/ux-helpers** — Abuse prevention and rate limiting utilities
-- **@private.me/xregistry** — Trust registry interface and DID resolution
-
-These dependencies are compiled into `dist-standalone/` with relative import paths. Users install xBind as a single package - no separate installation of building blocks required.
-
-All cryptographic dependencies are production-grade implementations. No test or mock crypto is used in production builds.
-
-## Setup & Configuration
-
-### Environment Variables
-
-#### FULL_CONTROL_MASTER_KEY (Required)
-
-**Critical for Production:** This key is required for Share 2 decryption in the Full Control vault store. Without it, the package cannot access proprietary XorIDA algorithms.
-
-```bash
-# Generate a new key (one-time setup)
-openssl rand -base64 32
-
-# Set in your environment
-export FULL_CONTROL_MASTER_KEY="<generated-key-here>"
-
-# Verify length (should be 44 characters)
-echo ${#FULL_CONTROL_MASTER_KEY}
-```
-
-**Key Details:**
-- **Purpose:** Master key for Share 2 decryption in Full Control vault store
-- **Format:** 32-byte random value, base64-encoded (44 characters)
-- **When Required:**
-  - ✅ Required in production for Full Control operations
-  - ✅ Required for server health checks to pass
-  - ⚠️ Optional for basic testing (package will use fallback behavior)
-- **Security:** Store in `.env` file with `chmod 600` permissions
-- **Validation:** Server health check at `/aci/billing/health` validates this key
-
-**Troubleshooting:**
-
-If you see errors like `FULL_CONTROL_MASTER_KEY not configured` or `Share 2 decryption failed`:
-1. Verify the key is set: `echo $FULL_CONTROL_MASTER_KEY`
-2. Check the length is exactly 44 characters
-3. Ensure `.env` file is loaded (if using dotenv)
-4. Verify file permissions: `chmod 600 .env`
-5. For production deployments, confirm the key is set in your deployment configuration
-
-See [Configuration Guide](./docs/configuration.md) for complete setup instructions and advanced configuration options.
-
-## Pricing
-
-**Free tier available** — No credit card required.
-
-See [pricing details](../../docs/pricing-reference.md) for current rates and tier comparison.
-
-[Subscribe now](https://private.me/subscribe?product=xbind)
-
-## Quick Start
-
-**Complete setup in under 2 minutes:**
-
-### Step 1: Email Verification (Required)
-
-**ALL API calls are blocked until you verify your email address.** This links your usage to a verified contact for security notifications and billing.
-
-```bash
-npx xbind setup --email user@example.com
-```
-
-**What happens:**
-1. **DID Generation**: Creates Ed25519 cryptographic identity (did:key:z6Mk...)
-2. **DeploymentID Creation**: Generates persistent economic identity (DEP-202605-XXXXXXXXXX)
-3. **Email Code Delivery**: Sends 6-digit verification code to your email
-4. **Code Verification**: Enter code to link email to DeploymentID
-5. **Identity Storage**: Saves to `~/.xbind/identity.json` (chmod 600)
-6. **Ready to Use**: No additional configuration needed
-
-**Dual-Mode Verification:**
-- **CLI/Programmatic**: 6-digit code (this method)
-- **Web/Browser**: Magic link (auto-verifies on click)
-
-**Command Options:**
-```bash
-npx xbind setup --email user@example.com  # Standard setup
-npx xbind setup --email user@example.com --force  # Overwrite existing identity
-npx xbind setup --dev  # Development mode (mock email provider)
-```
-
-**Security Notes:**
-- Disposable email services blocked (Mailinator, Guerrilla Mail, etc.)
-- Device fingerprinting active (100+ signals for abuse prevention)
-- DID ≠ DeploymentID (see Identity Model section below)
-
----
-
-### Identity Model: DID vs DeploymentID
-
-**Two complementary identities for different purposes:**
-
-#### DID (Decentralized Identifier)
-- **Format**: `did:key:z6Mk...` (Ed25519 public key)
-- **Purpose**: Cryptographic authentication (message signing)
-- **Lifespan**: Ephemeral - can be rotated for security
-- **Use case**: Proving "I sent this message"
-- **Storage**: `~/.xbind/identity.json` (local only)
-
-#### DeploymentID (Persistent Economic Identity)
-- **Format**: `DEP-YYYYMM-XXXXXXXXXX` (month prefix + 10 hex digits)
-- **Purpose**: Billing and usage tracking (persistent across DIDs)
-- **Lifespan**: Permanent - never changes for your account
-- **Use case**: "This deployment used 50K operations this month"
-- **Prevents**: Economic state reset attacks (DID rotation to bypass usage limits)
-
-**Why Both?**
-- **Security**: Rotate DID without losing billing history
-- **Privacy**: DID is pseudonymous, DeploymentID links to verified email
-- **Billing**: Usage tracked by DeploymentID, even if DID changes
-- **Attack Prevention**: Cannot reset free tier quota by generating new DID
-
-**Example:**
-```
-User creates account:
-  - DID: did:key:z6MkABC123...  (for signing messages)
-  - DeploymentID: DEP-202605-7F3A2B1C  (for billing)
-
-User rotates DID for security:
-  - DID: did:key:z6MkXYZ789...  (NEW cryptographic identity)
-  - DeploymentID: DEP-202605-7F3A2B1C  (SAME billing identity)
-  - Usage history: Preserved ✅
-  - Free tier quota: Cannot reset ✅
-```
-
----
-
-### Device Fingerprinting & Privacy
-
-**xBind collects device fingerprints for abuse prevention:**
-
-**What We Collect (100+ Signals):**
-1. **Browser**: User agent, language, timezone, screen resolution
-2. **OS**: Platform, CPU cores, memory (approximate)
-3. **Hardware**: GPU vendor, audio context, canvas fingerprint
-4. **Network**: IP address (hashed), connection type
-5. **Behavior**: Timing patterns, interaction signals
-6. **Fonts**: Installed font list (system fingerprint)
-
-**Why We Collect:**
-- Detect multi-accounting (creating unlimited free accounts)
-- Identify coordinated abuse patterns
-- Link DeploymentIDs across devices (same user, different machines)
-- Risk scoring (0-100 scale, manual review ≥70)
-
-**Privacy Protections:**
-- **SHA-256 hashed**: Fingerprints stored as hashes, not raw data
-- **No PII**: Individual signals don't identify you personally
-- **GDPR compliant**: Right to access, deletion, opt-out
-- **Minimization**: Only signals necessary for abuse detection
-- **Retention**: 90 days for fingerprints, 30 days for raw signals
-
-**Opt-Out:**
-Email contact@private.me with subject "Fingerprint Opt-Out" and your DeploymentID. Note: Opting out may trigger manual review for new accounts.
-
-**Transparency:**
-Full fingerprinting source code available at `apps/server/src/device-fingerprinting.ts`
-
-**Note:** Disposable email services (Mailinator, Guerrilla Mail, etc.) are blocked. Use a real email address.
-
-### Step 2: Create Agent & Send Messages
-
-```typescript
-import { Agent } from '@private.me/xbind';
-
-// Create agent (auto-generates cryptographic identity, throws on error)
-const agent = await Agent.quickstart({ name: 'my-service' });
-
-// Send authenticated message
-const sendResult = await agent.send({
-  to: 'did:key:z6Mk...', // recipient DID
-  payload: { action: 'createCharge', amount: 100 },
-  scope: 'billing'
-});
-
-if (!sendResult.ok) {
-  console.error(`Failed: ${sendResult.error}`);
-  return;
-}
-
-console.log('Message sent with cryptographic identity');
-console.log('Agent DID:', agent.did);
-```
-
-### Step 3: Understand Your Free Tier
-
-- **100,000 operations/month** (free tier)
-- **120,000 hard cap** (20% grace buffer)
-- **Monthly reset:** 1st of each month at 00:00 UTC
-- **Milestone emails:** Sent at 50%, 80%, 100%, 120% usage
-
-**At 100K operations:** Email verification enforced (if not already verified)
-**At 120K operations:** Hard cap reached. Upgrade to Pro for unlimited operations.
-
-**Prerequisites:** The `FULL_CONTROL_MASTER_KEY` environment variable is required for Share 2 operations in production but optional for basic testing. See [Environment Variables](#environment-variables) for setup.
-
-**JITR (Just-in-Time Registration):** Agents created with `Agent.fromSeed()` automatically register with the trust registry on first use. No manual registration scripts required. Includes all encryption keys (Ed25519, X25519, ML-KEM, ML-DSA) for zero-config encrypted messaging.
-
-[More examples](./docs/examples.md) • [Python examples](./python/README.md)
-
-## Programmatic Quickstart
-
-**Complete, copy-paste ready examples** tested in clean environments:
-
-### Example 1: Create Agent & Get DID
-
-<!-- RUNNABLE-EXAMPLE -->
-```typescript
-import { Agent } from '@private.me/xbind';
-
-// Create agent with automatic identity generation
-const agent = await Agent.quickstart({ name: 'test-agent' });
-
-console.log('Agent DID:', agent.did);
-console.log('Agent name:', agent.name);
-```
-<!-- /RUNNABLE-EXAMPLE -->
-
-**Expected output:**
-```
-Agent DID: did:key:z6Mk...
-Agent name: test-agent
-```
-
-### Example 2: Agent Identity Details
-
-<!-- RUNNABLE-EXAMPLE -->
-```typescript
-import { Agent } from '@private.me/xbind';
-
-// Create agent
-const agent = await Agent.quickstart({ name: 'identity-test' });
-
-// Access identity information
-console.log('DID:', agent.did);
-console.log('Has Ed25519 keys:', !!agent.identity.publicKey);
-console.log('Has X25519 keys:', !!agent.identity.x25519PublicKey);
-console.log('Has ML-KEM keys:', !!agent.identity.mlKemPublicKey);
-```
-<!-- /RUNNABLE-EXAMPLE -->
-
-**Expected output:**
-```
-DID: did:key:z6Mk...
-Has Ed25519 keys: true
-Has X25519 keys: true
-Has ML-KEM keys: true
-```
-
-### Example 3: Registry & Transport Configuration
-
-<!-- RUNNABLE-EXAMPLE -->
-```typescript
-import { Agent } from '@private.me/xbind';
-
-// Quickstart uses defaults: MemoryRegistry + HttpsTransport
-const agent = await Agent.quickstart({ name: 'config-test' });
-
-// Check configuration
-console.log('Registry type:', agent.registry.constructor.name);
-console.log('Transports count:', agent.transports.length);
-console.log('Transport type:', agent.transports[0].constructor.name);
-```
-<!-- /RUNNABLE-EXAMPLE -->
-
-**Expected output:**
-```
-Registry type: MemoryTrustRegistry
-Transports count: 1
-Transport type: HttpsTransportAdapter
-```
-
-**Note:** These examples work immediately after `npm install @private.me/xbind`. Email verification is NOT required for basic agent creation and local operations. Verification is enforced when:
-- Sending messages to other agents
-- Exceeding 100K operations/month
-- Accessing production features
-
-[More examples](./docs/examples.md) • [Python examples](./python/README.md)
-
-## Post-Quantum Cryptography & Envelopes
-
-**Complete examples for ML-DSA signatures, key export, and envelope operations:**
-
-### Example 4: ML-DSA-65 Signing and Verification
-
-<!-- RUNNABLE-EXAMPLE -->
-```typescript
-import { Agent, signMlDsa65, verifyMlDsa65 } from '@private.me/xbind';
-
-// Create agent with post-quantum signatures enabled
-const agent = await Agent.quickstart({
-  name: 'pq-test',
-  postQuantumSig: true
-});
-
-// Sign data with ML-DSA-65
-const data = new TextEncoder().encode('Critical transaction data');
-const mlDsaSecretKey = agent.identity.mlDsaSecretKey;
-
-if (!mlDsaSecretKey) {
-  throw new Error('ML-DSA keys not available');
-}
-
-const signResult = await signMlDsa65(mlDsaSecretKey, data);
-if (!signResult.ok) {
-  throw new Error(`Signing failed: ${signResult.error}`);
-}
-
-console.log('ML-DSA-65 signature length:', signResult.value.length); // 3309 bytes
-
-// Verify signature
-const mlDsaPublicKey = agent.identity.mlDsaPublicKey!;
-const verifyResult = await verifyMlDsa65(mlDsaPublicKey, signResult.value, data);
-
-if (verifyResult.ok && verifyResult.value) {
-  console.log('Post-quantum signature verified successfully');
-} else {
-  console.error('Signature verification failed');
-}
-```
-<!-- /RUNNABLE-EXAMPLE -->
-
-**Expected output:**
-```
-ML-DSA-65 signature length: 3309
-Post-quantum signature verified successfully
-```
-
-### Example 5: Export Post-Quantum Keys
-
-<!-- RUNNABLE-EXAMPLE -->
-```typescript
-import {
-  Agent,
-  exportMlDsaSecretKey,
-  exportMlDsaPublicKey,
-  exportMlKemSecretKey,
-  exportMlKemPublicKey
-} from '@private.me/xbind';
-
-// Create agent with post-quantum cryptography
-const agent = await Agent.quickstart({
-  name: 'export-test',
-  postQuantumSig: true
-});
-
-// Export ML-DSA keys (signatures)
-const mlDsaSecret = exportMlDsaSecretKey(agent.identity);
-const mlDsaPublic = exportMlDsaPublicKey(agent.identity);
-
-console.log('ML-DSA-65 secret key:', mlDsaSecret ? `${mlDsaSecret.length} bytes` : 'N/A');
-console.log('ML-DSA-65 public key:', mlDsaPublic ? `${mlDsaPublic.length} bytes` : 'N/A');
-
-// Export ML-KEM keys (encryption)
-const mlKemSecret = exportMlKemSecretKey(agent.identity);
-const mlKemPublic = exportMlKemPublicKey(agent.identity);
-
-console.log('ML-KEM-768 secret key:', mlKemSecret ? `${mlKemSecret.length} bytes` : 'N/A');
-console.log('ML-KEM-768 public key:', mlKemPublic ? `${mlKemPublic.length} bytes` : 'N/A');
-```
-<!-- /RUNNABLE-EXAMPLE -->
-
-**Expected output:**
-```
-ML-DSA-65 secret key: 32 bytes
-ML-DSA-65 public key: 1952 bytes
-ML-KEM-768 secret key: 2400 bytes
-ML-KEM-768 public key: 1184 bytes
-```
-
-### Example 6: Key Rotation with Backward Compatibility
-
-<!-- RUNNABLE-EXAMPLE -->
-```typescript
-import { Agent, rotateKeys } from '@private.me/xbind';
-
-// Create agent
-const agent = await Agent.quickstart({ name: 'rotation-test' });
-
-// Store original X25519 public key
-const originalX25519 = Buffer.from(agent.identity.rawX25519PublicKey).toString('hex');
-
-// Rotate encryption keys (X25519 + ML-KEM)
-const rotatedResult = await rotateKeys(agent.identity);
-
-if (!rotatedResult.ok) {
-  throw new Error(`Key rotation failed: ${rotatedResult.error}`);
-}
-
-const rotatedIdentity = rotatedResult.value;
-
-// New keys are active
-const newX25519 = Buffer.from(rotatedIdentity.rawX25519PublicKey).toString('hex');
-console.log('Keys rotated successfully');
-console.log('Original X25519:', originalX25519.substring(0, 16) + '...');
-console.log('New X25519:', newX25519.substring(0, 16) + '...');
-
-// Old keys preserved for decryption
-console.log('Rotation history:', rotatedIdentity.rotatedKeys?.length ?? 0);
-console.log('DID unchanged:', agent.identity.did === rotatedIdentity.did);
-```
-<!-- /RUNNABLE-EXAMPLE -->
-
-**Expected output:**
-```
-Keys rotated successfully
-Original X25519: a1b2c3d4e5f6g7h8...
-New X25519: 9i0j1k2l3m4n5o6p...
-Rotation history: 1
-DID unchanged: true
-```
-
-### Example 7: Create V1 Envelope (Classical Crypto)
-
-<!-- RUNNABLE-EXAMPLE -->
-```typescript
-import { Agent, createEnvelope, generateSharedKey } from '@private.me/xbind';
-
-// Generate shared AES-256-GCM key
-const sharedKey = await generateSharedKey();
-
-// Create agent
-const agent = await Agent.quickstart({ name: 'envelope-test' });
-
-// Create encrypted envelope
-const plaintext = new TextEncoder().encode(JSON.stringify({
-  action: 'transfer',
-  amount: 1000
-}));
-
-const envelopeResult = await createEnvelope({
-  senderDid: agent.did,
-  recipientDid: 'did:key:z6MkRecipient...',
-  scope: 'billing:write',
-  plaintext,
-  privateKey: agent.identity.privateKey,
-  sharedKey
-});
-
-if (!envelopeResult.ok) {
-  throw new Error(`Envelope creation failed: ${envelopeResult.error}`);
-}
-
-const envelope = envelopeResult.value;
-console.log('Envelope version:', envelope.v);
-console.log('Algorithm:', envelope.alg);
-console.log('Signature length:', envelope.signature.length);
-console.log('Encrypted payload:', envelope.payload.substring(0, 32) + '...');
-```
-<!-- /RUNNABLE-EXAMPLE -->
-
-**Expected output:**
-```
-Envelope version: 1
-Algorithm: Ed25519
-Signature length: 88
-Encrypted payload: aGVsbG8gd29ybGQgdGhpcyBpcyBhIHRl...
-```
-
-### Example 8: Create V2 Envelope (Hybrid KEM)
-
-<!-- RUNNABLE-EXAMPLE -->
-```typescript
-import { Agent, createEnvelopeV2, generateSharedKey } from '@private.me/xbind';
-import { createMlKem768 } from 'mlkem';
-
-// Generate shared AES-256-GCM key
-const sharedKey = await generateSharedKey();
-
-// Generate ephemeral X25519 keypair
-const x25519Pair = await crypto.subtle.generateKey(
-  { name: 'X25519' },
-  true,
-  ['deriveBits']
-);
-const ephemeralPub = new Uint8Array(
-  await crypto.subtle.exportKey('raw', x25519Pair.publicKey)
-);
-
-// Generate ML-KEM-768 ciphertext (mocked for example)
-const mlkem = await createMlKem768();
-const recipientMlKemPub = mlkem.generateKeyPair()[0]; // Mock recipient public key
-const [kemCiphertext] = mlkem.encap(recipientMlKemPub);
-
-const agent = await Agent.quickstart({ name: 'v2-envelope-test' });
-
-const envelope = await createEnvelopeV2({
-  senderDid: agent.did,
-  recipientDid: 'did:key:z6MkRecipient...',
-  scope: 'messaging',
-  plaintext: new TextEncoder().encode('Hybrid KEM message'),
-  privateKey: agent.identity.privateKey,
-  sharedKey,
-  ephemeralPublicKey: ephemeralPub,
-  kemCiphertext
-});
-
-if (envelope.ok) {
-  console.log('Envelope version:', envelope.value.v);
-  console.log('KEM mode:', envelope.value.kem);
-  console.log('ML-KEM ciphertext length:', envelope.value.kemCiphertext.length);
-}
-```
-<!-- /RUNNABLE-EXAMPLE -->
-
-**Expected output:**
-```
-Envelope version: 2
-KEM mode: X25519-MLKEM768
-ML-KEM ciphertext length: 1452
-```
-
-### Example 9: Create V3 Envelope (Dual Signatures)
-
-<!-- RUNNABLE-EXAMPLE -->
-```typescript
-import { Agent, createEnvelopeV3, generateSharedKey } from '@private.me/xbind';
-import { createMlKem768 } from 'mlkem';
-
-// Create agent with ML-DSA enabled
-const agent = await Agent.quickstart({
-  name: 'v3-envelope-test',
-  postQuantumSig: true
-});
-
-if (!agent.identity.mlDsaSecretKey) {
-  throw new Error('ML-DSA keys required for V3 envelopes');
-}
-
-// Generate shared key and KEM materials
-const sharedKey = await generateSharedKey();
-const x25519Pair = await crypto.subtle.generateKey(
-  { name: 'X25519' },
-  true,
-  ['deriveBits']
-);
-const ephemeralPub = new Uint8Array(
-  await crypto.subtle.exportKey('raw', x25519Pair.publicKey)
-);
-
-const mlkem = await createMlKem768();
-const recipientMlKemPub = mlkem.generateKeyPair()[0];
-const [kemCiphertext] = mlkem.encap(recipientMlKemPub);
-
-const envelope = await createEnvelopeV3({
-  senderDid: agent.did,
-  recipientDid: 'did:key:z6MkRecipient...',
-  scope: 'high-security',
-  plaintext: new TextEncoder().encode('Dual-signature message'),
-  privateKey: agent.identity.privateKey,
-  sharedKey,
-  ephemeralPublicKey: ephemeralPub,
-  kemCiphertext,
-  mlDsaSecretKey: agent.identity.mlDsaSecretKey
-});
-
-if (envelope.ok) {
-  console.log('Envelope version:', envelope.value.v);
-  console.log('Signature scheme:', envelope.value.sig);
-  console.log('Ed25519 signature:', envelope.value.signature.substring(0, 16) + '...');
-  console.log('ML-DSA signature:', envelope.value.pqSignature.substring(0, 16) + '...');
-}
-```
-<!-- /RUNNABLE-EXAMPLE -->
-
-**Expected output:**
-```
-Envelope version: 3
-Signature scheme: Ed25519+MLDSA65
-Ed25519 signature: SGVsbG8gd29ybGQ...
-ML-DSA signature: cG9zdC1xdWFudHV...
-```
-
-### Example 10: Create V4 Envelope (Xchange Mode)
-
-<!-- RUNNABLE-EXAMPLE -->
-```typescript
-import { Agent, createEnvelopeV4 } from '@private.me/xbind';
-
-const agent = await Agent.quickstart({ name: 'xchange-test' });
-
-// Xchange mode: Share data is the payload (no encryption layer)
-const shareData = new TextEncoder().encode('XorIDA share data');
-
-const envelope = await createEnvelopeV4({
-  senderDid: agent.did,
-  recipientDid: 'did:key:z6MkRecipient...',
-  scope: 'xchange',
-  shareData,
-  privateKey: agent.identity.privateKey,
-  shareIndex: 0,
-  shareTotal: 3,
-  shareThreshold: 2,
-  shareGroupId: 'group-uuid-1234',
-  shareHmacKey: 'base64-hmac-key',
-  shareHmacSig: 'base64-hmac-sig'
-});
-
-if (envelope.ok) {
-  console.log('Envelope version:', envelope.value.v);
-  console.log('KEM mode:', envelope.value.kem);
-  console.log('Share index:', envelope.value.shareIndex);
-  console.log('Threshold:', `${envelope.value.shareThreshold}-of-${envelope.value.shareTotal}`);
-}
-```
-<!-- /RUNNABLE-EXAMPLE -->
-
-**Expected output:**
-```
-Envelope version: 4
-KEM mode: Xchange
-Share index: 0
-Threshold: 2-of-3
-```
-
-### Example 11: Decrypt Envelope Payload
-
-<!-- RUNNABLE-EXAMPLE -->
-```typescript
-import {
-  Agent,
-  createEnvelope,
-  decryptPayload,
-  generateSharedKey
-} from '@private.me/xbind';
-
-// Create and encrypt envelope
-const sharedKey = await generateSharedKey();
-const agent = await Agent.quickstart({ name: 'decrypt-test' });
-
-const originalMessage = 'Secret payment details';
-const plaintext = new TextEncoder().encode(originalMessage);
-
-const envelopeResult = await createEnvelope({
-  senderDid: agent.did,
-  recipientDid: 'did:key:z6MkRecipient...',
-  scope: 'payments',
-  plaintext,
-  privateKey: agent.identity.privateKey,
-  sharedKey
-});
-
-if (!envelopeResult.ok) {
-  throw new Error('Envelope creation failed');
-}
-
-// Decrypt the payload
-const decryptResult = await decryptPayload(envelopeResult.value, sharedKey);
-
-if (!decryptResult.ok) {
-  throw new Error(`Decryption failed: ${decryptResult.error}`);
-}
-
-const decryptedMessage = new TextDecoder().decode(decryptResult.value);
-console.log('Decrypted:', decryptedMessage);
-console.log('Match:', decryptedMessage === originalMessage);
-```
-<!-- /RUNNABLE-EXAMPLE -->
-
-**Expected output:**
-```
-Decrypted: Secret payment details
-Match: true
-```
-
-### Example 12: Serialize and Deserialize Envelope
-
-<!-- RUNNABLE-EXAMPLE -->
-```typescript
-import {
-  Agent,
-  createEnvelope,
-  serializeEnvelope,
-  deserializeEnvelope,
-  generateSharedKey
-} from '@private.me/xbind';
-
-// Create envelope
-const sharedKey = await generateSharedKey();
-const agent = await Agent.quickstart({ name: 'serialize-test' });
-
-const envelope = await createEnvelope({
-  senderDid: agent.did,
-  recipientDid: 'did:key:z6MkRecipient...',
-  scope: 'test',
-  plaintext: new TextEncoder().encode('Test message'),
-  privateKey: agent.identity.privateKey,
-  sharedKey
-});
-
-if (!envelope.ok) {
-  throw new Error('Envelope creation failed');
-}
-
-// Serialize to bytes
-const serialized = serializeEnvelope(envelope.value);
-console.log('Serialized length:', serialized.length, 'bytes');
-
-// Deserialize back to envelope
-const deserialized = deserializeEnvelope(serialized);
-
-if (deserialized.ok) {
-  console.log('Deserialized version:', deserialized.value.v);
-  console.log('Sender DID:', deserialized.value.sender.substring(0, 20) + '...');
-  console.log('Round-trip successful');
-}
-```
-<!-- /RUNNABLE-EXAMPLE -->
-
-**Expected output:**
-```
-Serialized length: 512 bytes
-Deserialized version: 1
-Sender DID: did:key:z6Mk...
-Round-trip successful
-```
-
-### Example 13: Validate Envelope Structure
-
-<!-- RUNNABLE-EXAMPLE -->
-```typescript
-import { validateEnvelope } from '@private.me/xbind';
-
-// Valid envelope structure
-const validEnvelope = {
-  v: 1,
-  alg: 'Ed25519',
-  sender: 'did:key:z6MkSender...',
-  recipient: 'did:key:z6MkRecipient...',
-  timestamp: Date.now(),
-  nonce: 'YmFzZTY0LW5vbmNl',
-  scope: 'test',
-  payload: 'ZW5jcnlwdGVkLXBheWxvYWQ=',
-  signature: 'c2lnbmF0dXJlLWRhdGE='
-};
-
-const validation = validateEnvelope(validEnvelope);
-
-if (validation.ok) {
-  console.log('Envelope valid');
-  console.log('Version:', validation.value.v);
-  console.log('Algorithm:', validation.value.alg);
-} else {
-  console.error('Validation error:', validation.error);
-}
-
-// Invalid envelope (missing required field)
-const invalidEnvelope = {
-  v: 1,
-  alg: 'Ed25519',
-  sender: 'did:key:z6MkSender...'
-  // Missing recipient, timestamp, nonce, etc.
-};
-
-const invalidValidation = validateEnvelope(invalidEnvelope);
-console.log('Invalid envelope error:', invalidValidation.ok ? 'N/A' : invalidValidation.error);
-```
-<!-- /RUNNABLE-EXAMPLE -->
-
-**Expected output:**
-```
-Envelope valid
-Version: 1
-Algorithm: Ed25519
-Invalid envelope error: INVALID_FIELDS
-```
-
-
-## Identity & CLI Operations
-
-### CLI Initialization
-
-<!-- RUNNABLE-EXAMPLE -->
-```typescript
-import { initCommand } from '@private.me/xbind';
-
-// Initialize xBind project with invite code
-await initCommand({
-  invite: 'https://xbind.to/invite/XBD-abc123',
-  name: 'my-xbind-app',
-  runtime: 'node-typescript',
-  yes: true // Skip interactive prompts
-});
-
-// Or use CLI directly:
-// npx xbind-init --invite XBD-abc123 --name my-app --runtime node-typescript --yes
-```
-<!-- /RUNNABLE-EXAMPLE -->
-
-### DID Conversions
-
-<!-- RUNNABLE-EXAMPLE -->
-```typescript
-import { generateIdentity, publicKeyToDid, didToPublicKeyBytes } from '@private.me/xbind';
-
-// Generate identity and extract DID
-const result = await generateIdentity();
-if (!result.ok) throw new Error(result.error);
-
-const identity = result.value;
-console.log('DID:', identity.did); // did:key:z6Mk...
-
-// Convert public key to DID
-const did = publicKeyToDid(identity.rawPublicKey);
-console.log('Derived DID:', did);
-
-// Convert DID back to public key bytes
-const keyResult = didToPublicKeyBytes(did);
-if (!keyResult.ok) throw new Error(keyResult.error);
-
-console.log('Public key bytes:', keyResult.value); // Uint8Array(32)
-```
-<!-- /RUNNABLE-EXAMPLE -->
-
-### PKCS8 Key Export
-
-<!-- RUNNABLE-EXAMPLE -->
-```typescript
-import { generateIdentity, exportPKCS8, exportX25519PKCS8 } from '@private.me/xbind';
-
-const result = await generateIdentity();
-if (!result.ok) throw new Error(result.error);
-
-const identity = result.value;
-
-// Export Ed25519 private key as PKCS8 (for persistent storage)
-const ed25519Result = await exportPKCS8(identity.privateKey);
-if (!ed25519Result.ok) throw new Error(ed25519Result.error);
-
-console.log('Ed25519 PKCS8:', ed25519Result.value); // Uint8Array(48)
-
-// Export X25519 private key as PKCS8
-const x25519Result = await exportX25519PKCS8(identity.x25519PrivateKey);
-if (!x25519Result.ok) throw new Error(x25519Result.error);
-
-console.log('X25519 PKCS8:', x25519Result.value); // Uint8Array(48)
-```
-<!-- /RUNNABLE-EXAMPLE -->
-
-### PKCS8 Key Import
-
-<!-- RUNNABLE-EXAMPLE -->
-```typescript
-import { exportPKCS8, exportX25519PKCS8, importFromPKCS8, importIdentity } from '@private.me/xbind';
-
-// Assume we have PKCS8 bytes from previous export
-const ed25519Pkcs8 = new Uint8Array(48); // From exportPKCS8()
-const x25519Pkcs8 = new Uint8Array(48);  // From exportX25519PKCS8()
-
-// Import Ed25519 identity (generates new X25519 keypair)
-const simpleResult = await importFromPKCS8(ed25519Pkcs8);
-if (!simpleResult.ok) throw new Error(simpleResult.error);
-
-console.log('Restored DID:', simpleResult.value.did);
-
-// Import full identity (preserves both Ed25519 + X25519 keys)
-const fullResult = await importIdentity(ed25519Pkcs8, x25519Pkcs8);
-if (!fullResult.ok) throw new Error(fullResult.error);
-
-console.log('Full identity restored:', fullResult.value.did);
-console.log('Has X25519 keys:', !!fullResult.value.x25519PublicKey);
-```
-<!-- /RUNNABLE-EXAMPLE -->
-
-### Deterministic Identity from Seed
-
-<!-- RUNNABLE-EXAMPLE -->
-```typescript
-import { identityFromSeed } from '@private.me/xbind';
-
-// Generate 32-byte seed (high-entropy random bytes)
-const seed = crypto.getRandomValues(new Uint8Array(32));
-
-// Derive deterministic identity (same seed = same DID)
-const result = await identityFromSeed(seed);
-if (!result.ok) throw new Error(result.error);
-
-console.log('DID:', result.value.did);
-console.log('Has Ed25519 keys:', !!result.value.publicKey);
-console.log('Has X25519 keys:', !!result.value.x25519PublicKey);
-console.log('Has ML-KEM keys:', !!result.value.mlKemPublicKey);
-
-// Same seed produces identical DID
-const result2 = await identityFromSeed(seed);
-if (!result2.ok) throw new Error(result2.error);
-
-console.log('DIDs match:', result.value.did === result2.value.did); // true
-```
-<!-- /RUNNABLE-EXAMPLE -->
-
-### Raw Key Extraction
-
-<!-- RUNNABLE-EXAMPLE -->
-```typescript
-import { exportPKCS8, exportX25519PKCS8, extractRawEd25519, extractRawX25519 } from '@private.me/xbind';
-import { generateIdentity } from '@private.me/xbind';
-
-const identity = (await generateIdentity()).value!;
-
-// Export PKCS8 format
-const ed25519Pkcs8 = (await exportPKCS8(identity.privateKey)).value!;
-const x25519Pkcs8 = (await exportX25519PKCS8(identity.x25519PrivateKey)).value!;
-
-// Extract raw 32-byte private keys
-const ed25519Raw = extractRawEd25519(ed25519Pkcs8);
-if (!ed25519Raw.ok) throw new Error(ed25519Raw.error);
-
-console.log('Ed25519 raw key:', ed25519Raw.value); // Uint8Array(32)
-
-const x25519Raw = extractRawX25519(x25519Pkcs8);
-if (!x25519Raw.ok) throw new Error(x25519Raw.error);
-
-console.log('X25519 raw key:', x25519Raw.value); // Uint8Array(32)
-```
-<!-- /RUNNABLE-EXAMPLE -->
-
-### ML-KEM Key Export
-
-<!-- RUNNABLE-EXAMPLE -->
-```typescript
-import { generateIdentity, exportMlKemSecretKey, exportMlKemPublicKey } from '@private.me/xbind';
-
-const result = await generateIdentity();
-if (!result.ok) throw new Error(result.error);
-
-const identity = result.value;
-
-// Export ML-KEM-768 secret key (2400 bytes)
-const secretKey = exportMlKemSecretKey(identity);
-if (secretKey) {
-  console.log('ML-KEM secret key size:', secretKey.length); // 2400
-}
-
-// Export ML-KEM-768 public key (1184 bytes)
-const publicKey = exportMlKemPublicKey(identity);
-if (publicKey) {
-  console.log('ML-KEM public key size:', publicKey.length); // 1184
-}
-```
-<!-- /RUNNABLE-EXAMPLE -->
-
-## Advanced Networking & Resilience
-
-xBind provides production-grade retry strategies, replay prevention, and circuit breakers for fault-tolerant distributed systems.
-
-### Replay Prevention with MemoryNonceStore
-
-<!-- RUNNABLE-EXAMPLE -->
-```typescript
-import { MemoryNonceStore } from '@private.me/xbind';
-
-// Create in-memory nonce store (10-minute TTL, 60-second cleanup)
-const nonceStore = new MemoryNonceStore({
-  ttlMs: 10 * 60 * 1000,
-  cleanupIntervalMs: 60 * 1000,
-});
-
-// Check nonce freshness (returns true if new, false if duplicate)
-const nonce1 = 'unique-nonce-abc123';
-const senderDid = 'did:key:z6Mk...';
-
-const isNewNonce = await nonceStore.check(nonce1, senderDid);
-console.log('Nonce accepted:', isNewNonce); // true (first use)
-
-const isDuplicate = await nonceStore.check(nonce1, senderDid);
-console.log('Nonce rejected:', !isDuplicate); // false (replay attack)
-
-// Clean up
-nonceStore.dispose();
-```
-<!-- /RUNNABLE-EXAMPLE -->
-
-### Redis Nonce Store (Multi-Node)
-
-<!-- RUNNABLE-EXAMPLE -->
-```typescript
-import { RedisNonceStore } from '@private.me/xbind';
-import Redis from 'ioredis';
-
-// Create Redis client
-const redis = new Redis({ host: 'localhost', port: 6379 });
-
-// Create Redis nonce store (distributed across all nodes)
-const nonceStore = new RedisNonceStore({
-  client: {
-    setNX: async (key, value, ttl) => {
-      const result = await redis.set(key, value, 'EX', ttl, 'NX');
-      return result === 'OK' ? 'OK' : null;
-    },
-    del: (key) => redis.del(key),
-    quit: () => redis.quit(),
-  },
-  ttlSeconds: 600, // 10 minutes
-  keyPrefix: 'xbind:nonce:',
-});
-
-// Use nonce store (same API as MemoryNonceStore)
-const isNewNonce = await nonceStore.check('nonce-xyz', 'did:key:z6Mk...');
-console.log('Distributed nonce check:', isNewNonce);
-
-// Clean up
-await nonceStore.dispose();
-```
-<!-- /RUNNABLE-EXAMPLE -->
-
-### Exponential Backoff Retry
-
-<!-- RUNNABLE-EXAMPLE -->
-```typescript
-import { ExponentialBackoffStrategy, executeWithRetry } from '@private.me/xbind';
-import { err, ok } from '@private.me/shared';
-
-// Create exponential backoff strategy (3 attempts, 1s → 2s → 4s)
-const retryStrategy = new ExponentialBackoffStrategy({
-  maxAttempts: 3,
-  initialDelayMs: 1000,
-  maxDelayMs: 30000,
-  multiplier: 2,
-  jitter: true,
-});
-
-// Simulate flaky operation
-let attemptCount = 0;
-async function flakyOperation() {
-  attemptCount++;
-  console.log(`Attempt ${attemptCount}`);
-
-  if (attemptCount < 3) {
-    return err('NETWORK_ERROR' as const);
-  }
-  return ok({ data: 'Success after retries' });
-}
-
-// Execute with retry
-const result = await executeWithRetry(flakyOperation, retryStrategy);
-
-if (result.ok) {
-  console.log('Operation succeeded:', result.value.data);
-} else {
-  console.error('Operation failed:', result.error);
-}
-```
-<!-- /RUNNABLE-EXAMPLE -->
-
-### Linear Backoff Strategy
-
-<!-- RUNNABLE-EXAMPLE -->
-```typescript
-import { LinearBackoffStrategy, executeWithRetry } from '@private.me/xbind';
-import { err, ok } from '@private.me/shared';
-
-// Create linear backoff strategy (delays: 1s, 2s, 3s, 4s)
-const retryStrategy = new LinearBackoffStrategy({
-  maxAttempts: 4,
-  initialDelayMs: 1000,
-  delayIncrementMs: 1000,
-  maxDelayMs: 10000,
-  jitter: true,
-});
-
-// Simulate operation
-async function operation() {
-  return ok({ message: 'Linear backoff demo' });
-}
-
-const result = await executeWithRetry(operation, retryStrategy);
-console.log('Result:', result.ok ? result.value.message : result.error);
-```
-<!-- /RUNNABLE-EXAMPLE -->
-
-### Fixed Delay Strategy
-
-<!-- RUNNABLE-EXAMPLE -->
-```typescript
-import { FixedDelayStrategy, executeWithRetry } from '@private.me/xbind';
-import { err, ok } from '@private.me/shared';
-
-// Create fixed delay strategy (constant 2s delay between retries)
-const retryStrategy = new FixedDelayStrategy({
-  maxAttempts: 3,
-  delayMs: 2000,
-  jitter: false,
-});
-
-// Simulate operation
-async function operation() {
-  return ok({ message: 'Fixed delay demo' });
-}
-
-const result = await executeWithRetry(operation, retryStrategy);
-console.log('Result:', result.ok ? result.value.message : result.error);
-```
-<!-- /RUNNABLE-EXAMPLE -->
-
-### No Retry Strategy
-
-<!-- RUNNABLE-EXAMPLE -->
-```typescript
-import { NoRetryStrategy, executeWithRetry } from '@private.me/xbind';
-import { err } from '@private.me/shared';
-
-// Create no-retry strategy (fail immediately)
-const retryStrategy = new NoRetryStrategy();
-
-// Simulate failing operation
-async function operation() {
-  return err('NETWORK_ERROR' as const);
-}
-
-const result = await executeWithRetry(operation, retryStrategy);
-console.log('Failed immediately:', !result.ok);
-console.log('Error:', result.ok ? null : result.error);
-```
-<!-- /RUNNABLE-EXAMPLE -->
-
-### Circuit Breaker Pattern
-
-<!-- RUNNABLE-EXAMPLE -->
-```typescript
-import { CircuitBreaker } from '@private.me/xbind';
-
-// Create circuit breaker (5 failures → open, 60s reset, 2 successes → close)
-const breaker = new CircuitBreaker({
-  failureThreshold: 5,
-  resetTimeoutMs: 60000,
-  successThreshold: 2,
-  windowMs: 60000,
-});
-
-// Simulate failures to trip circuit
-for (let i = 0; i < 5; i++) {
-  breaker.recordFailure();
-}
-
-console.log('Circuit state after 5 failures:', breaker.getStats().state); // OPEN
-
-// Attempt request while circuit is open
-const canProceed = breaker.allowRequest();
-console.log('Request allowed:', canProceed); // false
-
-// Get circuit statistics
-const stats = breaker.getStats();
-console.log('Stats:', {
-  state: stats.state,
-  totalFailures: stats.totalFailures,
-  consecutiveFailures: stats.consecutiveFailures,
-});
-```
-<!-- /RUNNABLE-EXAMPLE -->
-
-### Retry with Circuit Breaker
-
-<!-- RUNNABLE-EXAMPLE -->
-```typescript
-import {
-  ExponentialBackoffStrategy,
-  CircuitBreaker,
-  executeWithRetry,
-} from '@private.me/xbind';
-import { err, ok } from '@private.me/shared';
-
-// Create retry strategy and circuit breaker
-const retryStrategy = new ExponentialBackoffStrategy({
-  maxAttempts: 3,
-  initialDelayMs: 1000,
-});
-
-const circuitBreaker = new CircuitBreaker({
-  failureThreshold: 2,
-  resetTimeoutMs: 5000,
-});
-
-// Simulate operation that succeeds after circuit recovery
-let callCount = 0;
-async function operation() {
-  callCount++;
-  if (callCount === 1) {
-    return err('NETWORK_ERROR' as const);
-  }
-  return ok({ data: `Success on attempt ${callCount}` });
-}
-
-// Execute with retry + circuit breaker
-const result = await executeWithRetry(operation, retryStrategy, circuitBreaker);
-
-console.log('Operation result:', result.ok ? result.value.data : result.error);
-console.log('Circuit state:', circuitBreaker.getStats().state);
-```
-<!-- /RUNNABLE-EXAMPLE -->
-
-### RetryTransportAdapter (Automatic Retry)
-
-<!-- RUNNABLE-EXAMPLE -->
-```typescript
-import { RetryTransportAdapter, HttpsTransportAdapter, Agent } from '@private.me/xbind';
-
-// Create base transport
-const baseTransport = new HttpsTransportAdapter({
-  baseUrl: 'https://gateway.private.me',
-});
-
-// Wrap with retry decorator (exponential backoff, 3 attempts)
-const retryTransport = new RetryTransportAdapter(baseTransport, {
-  maxAttempts: 3,
-  initialDelayMs: 1000,
-  maxDelayMs: 10000,
-  strategy: 'exponential',
-});
-
-// Create agent with retry transport
-const agent = await Agent.quickstart({
-  name: 'retry-demo',
-  transports: [retryTransport],
-});
-
-console.log('Agent created with retry transport');
-console.log('Transport type:', agent.transports[0].constructor.name);
-```
-<!-- /RUNNABLE-EXAMPLE -->
-
-### Shared Key Generation
-
-<!-- RUNNABLE-EXAMPLE -->
-```typescript
-import { generateSharedKey } from '@private.me/xbind';
-
-// Generate random AES-256-GCM shared key
-const sharedKeyResult = await generateSharedKey();
-
-if (!sharedKeyResult.ok) {
-  throw new Error(`Failed to generate key: ${sharedKeyResult.error}`);
-}
-
-const sharedKey = sharedKeyResult.value;
-
-// Export key material for inspection
-const keyMaterial = await crypto.subtle.exportKey('raw', sharedKey);
-console.log('Shared key generated (256 bits):', keyMaterial.byteLength * 8);
-console.log('Key algorithm:', sharedKey.algorithm.name);
-console.log('Key usages:', sharedKey.usages);
-```
-<!-- /RUNNABLE-EXAMPLE -->
-
-### Signed Envelopes
-
-<!-- RUNNABLE-EXAMPLE -->
-```typescript
-import { createSignedEnvelope, openSignedEnvelope, Agent } from '@private.me/xbind';
-
-// Create agents
-const sender = await Agent.quickstart({ name: 'sender' });
-const recipient = await Agent.quickstart({ name: 'recipient' });
-
-// Create signed envelope
-const payload = { action: 'transfer', amount: 100 };
-const envelopeResult = await createSignedEnvelope(
-  sender.identity,
-  recipient.did,
-  payload,
-  'billing'
-);
-
-if (!envelopeResult.ok) {
-  throw new Error(`Failed to create envelope: ${envelopeResult.error}`);
-}
-
-const envelope = envelopeResult.value;
-console.log('Envelope created with signature');
-console.log('Sender DID:', envelope.sender);
-console.log('Recipient DID:', envelope.recipient);
-console.log('Signature length:', envelope.signature.length);
-
-// Verify and open envelope
-const openResult = await openSignedEnvelope(envelope, sender.identity.publicKey);
-
-if (!openResult.ok) {
-  throw new Error(`Failed to open envelope: ${openResult.error}`);
-}
-
-console.log('Envelope verified and opened');
-console.log('Payload:', openResult.value);
-```
-<!-- /RUNNABLE-EXAMPLE -->
-
-## Python SDK
-
-Complete Python bindings for agent identity and messaging:
-
-```python
-from private_me.xbind import Agent
-
-# Create agent from private key
-agent = Agent.from_private_key(private_key_bytes)
-
-# Make authenticated call
-result = agent.call('stripe:createCharge', {
-    'amount': 100,
-    'currency': 'usd',
-    'description': 'AI agent purchase'
-})
-
-if result['ok']:
-    print(f"Charge ID: {result['data']['id']}")
-    print(f"Agent DID: {result['audit']['agent']}")
-else:
-    print(f"Error: {result['error']['message']}")
-```
-
-See [Python SDK documentation](./python/README.md) for complete API reference and examples.
-
-## Why xBind?
-
-Zero key management, zero cascade failures, zero bearer credentials. Cryptographic identity replaces API keys. See [white paper](https://private.me/docs/xbind.html) for architecture details and benchmarks.
-
-## Getting Started
-
-**[Guide](../../docs/xbind-integrations/getting-started/index.md)** — Concepts, migration
-**[Quickstart](../../docs/xbind-integrations/getting-started/quickstart.md)** — 15-second setup
-
-## Features
-
-**Zero-config JITR:** Just-in-Time Registration auto-registers agents with trust registry on first use (AWS IoT JITR, OAuth DCR, MCP 2025 standards).
-
-### Core Security
-- **Post-quantum cryptography:** ML-KEM-768 key encapsulation, ML-DSA-65 digital signatures (FIPS 203/204)
-- **Hybrid key agreement:** X-Wing combiner (IETF draft-10) with 6-parameter domain separation
-- **XorIDA split-channel delivery:** Information-theoretic threshold sharing (2-of-2, 2-of-3, 3-of-5)
-- **Cryptographic request signing:** Ed25519 signatures prevent DID header forgery
-- **Key rotation:** ML-KEM + X25519 rotation with fallback decryption (10 rotation history)
-- **Proof-of-Possession:** Ed25519 signature verification prevents DID spoofing
-- **Share-aware nonce deduplication:** Prevents replay attacks with composite keys
-
-### Runtime Compatibility (4 Platforms)
-- **Browser:** WebCrypto API, IndexedDB/localStorage adapters, WASM support, service workers
-- **React Native:** AsyncStorage, Buffer polyfills, crypto detection, iOS/Android platform support
-- **Edge Runtime:** Cloudflare Workers, Vercel Edge, Deno Deploy, KV storage, <1MB optimization
-- **Node.js:** Native crypto module, filesystem storage, full feature set
-
-### Operations Patterns
-- **Health checks:** Startup/liveness/readiness probes, Kubernetes-compatible, Express/Fastify middleware
-- **Circuit breakers:** 3-state machine (closed/open/half-open), registry/gateway/S3 presets, automatic recovery
-- **Graceful degradation:** QoS tiers, intelligent caching, service health tracking, fallback strategies
-- **Performance benchmarks:** Latency histograms with baselines for key ops (ML-KEM, ML-DSA, encryption)
-- **Structured logging:** 4 levels (DEBUG/INFO/WARN/ERROR), automatic sensitive data redaction, correlation IDs
-- **Telemetry:** Prometheus-compatible metrics (counters, histograms, gauges), operation latency tracking
-
-### Security Audit Preparation
-- **STRIDE threat modeling:** 66 threats analyzed across 6 categories
-- **Crypto claims documentation:** 41 cryptographic claims documented with evidence
-- **Known limitations disclosure:** 24 limitations disclosed for auditor transparency
-- **Audit-ready:** NCC Group / Trail of Bits preparation ($100K-$150K, 12-week timeline)
-
-### API Enhancements
-- **Batch operations:** 6-8x speedup for parallel operations with single network round-trip
-- **Async iterators:** `for await...of` syntax support for streaming message processing
-- **Plugin/middleware system:** 6-phase lifecycle hooks with 3 built-in plugins
-- **Event emitters:** Type-safe events with 5 event types, priority execution, bubbling
-- **Cancellation tokens:** AbortController integration with timeout support
-- **Progress callbacks:** 4 specialized trackers (operation, transfer, share, encryption)
-- **Retry strategies:** 4 strategies (exponential, linear, immediate, jittered) + circuit breaker integration
-- **Request timeouts:** Per-operation config with inheritance and cancellation
-- **Connection pooling:** 60-70% latency reduction with keep-alive and metrics
-- **Serialization formats:** JSON/MessagePack/CBOR support with auto-detection and negotiation
-- **Configuration validation:** Comprehensive validation with clear error messages
-- **Debug mode:** Performance profiling, network/crypto tracing, state inspection
-- **SDK version info:** Capability detection, deprecation warnings, compatibility checking
-
-### Developer Experience
-- **Type safety:** `Result<T, E>` error handling with 96+ error codes
-- **TypeScript strict mode:** Zero type errors, complete type coverage
-- **Python SDK:** Complete bindings for identity, messaging, and encryption
-- **User-friendly errors:** 75+ errors with actionable recovery hints
-- **Complete API docs:** 2,587 lines with 50+ usage examples
-- **CHANGELOG generation:** Automated Keep a Changelog format with semver discipline
-- **Dependency audit:** Weekly Dependabot scans, 5-layer vulnerability scanning
-- **Crypto license compliance:** Automated MIT/MIT-0 validation with GPL/AGPL detection
-
-### Enterprise Features
-- **Version negotiation:** Explicit SDK version fields prevent "404 Route not found" in mixed fleets
-- **Multi-device session resume:** AES-256-GCM encrypted session state sync with PBKDF2 (100k iterations)
-- **Encrypted backup/restore:** Password-protected identity export with PBKDF2-SHA256 (310k iterations)
-- **Offline sync:** Message queueing for offline devices (max 1000 messages, 24-hour TTL)
-- **Registry expiration:** TTL support with cleanup (default 7 days)
-- **Server-side spending limits:** Redis-backed enforcement with deployment-level aggregation
-- **Rate limiting:** Three-tier protection (per-DID, per-IP, global)
-- **Full Control IP protection:** Store Front (npm) + Vault Store (EC2) with payment verification
-
-### Testing & Quality
-- **2,762 tests:** Comprehensive coverage (96.6% passing)
-- **End-to-end integration:** Full message flow tests (Agent A → Gateway → Agent B)
-- **Gateway concurrency:** 100 concurrent sends, race condition detection
-- **Network partition recovery:** Disconnect/reconnect cycles with retry logic
-- **PLAN-3 hybrid signatures:** Bilateral authorization with composite verification
-
-## Bundle Size Optimization (Tree-Shaking)
-
-**New in v3.0.3:** LoopbackTransport export (testing workflow), describeSecurityModeStructured export (white paper examples), Agent.quickstart() signature fixes (README correctness). Full Control IP Protection (v3.0.2) - cryptographic algorithms delivered via payment-gated Vault Store. Share 1 in npm (useless alone), Share 2 in EC2 (completes algorithm). Information-theoretic security for proprietary IP.
-
-### Full Import (Convenience)
-
-```typescript
-import { Agent, generateIdentity } from '@private.me/xbind';
-
-// Bundle size: ~450 KB
-```
-
-### Granular Import (Optimized)
-
-```typescript
-import { Agent } from '@private.me/xbind/agent';
-import { generateIdentity } from '@private.me/xbind/identity';
-
-// Bundle size: ~180 KB (60% reduction)
-```
-
-### Available Entry Points
-
-| Entry Point | Exports | Bundle Impact |
-|-------------|---------|---------------|
-| `@private.me/xbind` | All exports | Full package (~450 KB) |
-| `@private.me/xbind/agent` | `Agent`, `AgentOptions` | ~180 KB |
-| `@private.me/xbind/identity` | `generateIdentity`, `Identity` | ~120 KB |
-| `@private.me/xbind/trust-registry` | Registry classes | ~200 KB |
-| `@private.me/xbind/key-agreement` | Key exchange functions | ~90 KB |
-| `@private.me/xbind/errors` | Error types | 0 KB (types only) |
-
-**Bundler Support:** Works with webpack 5+, Rollup, esbuild, and Vite. Tree-shaking is automatic in production mode.
-
-**See:** [Tree-Shaking Guide](./docs/packaging/tree-shaking.md) for detailed usage and configuration.
-
-## Automatic XorIDA Split-Channel Protection
-
-xBind automatically activates information-theoretic XorIDA threshold sharing for high-risk operations. No code changes required—security is transparent.
-
-### Risk Tags (Recommended for Crypto)
-
-For cryptocurrency transactions (BTC, ETH, etc.), use explicit risk tags in your payload:
-
-```typescript
-// Low risk: 2-of-2 threshold
-await agent.send({
-  to: recipientDid,
-  payload: { amount: 0.5, currency: 'BTC', risk: 'low' }
-});
-
-// Medium risk: 2-of-3 threshold
-await agent.send({
-  to: recipientDid,
-  payload: { amount: 5.0, currency: 'ETH', risk: 'medium' }
-});
-
-// High risk: 3-of-5 threshold
-await agent.send({
-  to: recipientDid,
-  payload: { amount: 50, currency: 'BTC', risk: 'high' }
-});
-
-// Critical risk: 3-of-5 threshold
-await agent.send({
-  to: recipientDid,
-  payload: { amount: 100, currency: 'BTC', risk: 'critical' }
-});
-```
-
-### Fiat Currency Auto-Detection
-
-For fiat currencies (USD, EUR, GBP), xBind uses numeric thresholds:
-
-```typescript
-// Automatically triggers 2-of-3 (amount >= $100,000)
-await agent.send({
-  to: recipientDid,
-  payload: { amount: 500000, currency: 'USD', action: 'transfer' }
-});
-
-// Automatically triggers 3-of-5 (amount >= $1,000,000)
-await agent.send({
-  to: recipientDid,
-  payload: { amount: 2500000, currency: 'USD', action: 'transfer' }
-});
-```
-
-### Manual Security Override
-
-Override automatic detection with explicit security levels:
-
-```typescript
-// Force 2-of-3 regardless of amount/risk
-await agent.send({
-  to: recipientDid,
-  payload: data,
-  security: 'high'
-});
-
-// Force 3-of-5 for maximum security
-await agent.send({
-  to: recipientDid,
-  payload: data,
-  security: 'critical'
-});
-
-// Disable XorIDA (standard encrypted transport)
-await agent.send({
-  to: recipientDid,
-  payload: data,
-  security: 'standard'
-});
-```
-
-### Threshold Schemes
-
-| Risk Tag / Threshold | Shares | Required | Security Level |
-|---------------------|--------|----------|----------------|
-| `low` | 2 | 2 | 2-of-2 threshold |
-| `medium` / $100k-$1M | 3 | 2 | 2-of-3 threshold |
-| `high` / `critical` / >$1M | 5 | 3 | 3-of-5 threshold |
-| No tag / <$100k | — | — | Standard encrypted transport |
-
-**Key Insight:** XorIDA is information-theoretically secure. Any K-1 shares reveal zero information about the secret, even with unlimited computing power. Quantum computers cannot break XorIDA.
-
-## Billing & Metering
-
-xBind includes usage-based billing with automated milestone notifications:
-
-- **Free Tier:** Generous monthly limits (no email verification required upfront)
-- **Grace Buffer:** Additional operations available after email verification
-- **Pro Tier:** Usage-based billing with unlimited operations
-- **Monthly Reset:** 1st of each month at 00:00 UTC
-
-See [pricing](../../docs/pricing-reference.md) for current rates and tier details.
-
-### Milestone Notifications
-
-Automated email notifications at usage thresholds with progress bars and CTAs for upgrades.
-
-**Email verification:** Required at free tier limit to access grace buffer.
-
-**Implementation:**
-- Metering logic: `apps/server/src/customer-metering.ts`
-- Milestone system: `apps/server/src/usage-milestone-notifications.ts`
-- Tier pattern: See `docs/gold-package.md` section 7.6.5
-
-## Gateway
-
-Non-authoritative coordination for discovery, relay, push notifications, and state checkpoints. Cannot forge identity or decide trust. See [Gateway Architecture](./docs/gateway-architecture.md).
-
-## Connection Models
-
-xBind provides four connection models for entity-to-entity authentication: Invite Code (email-based onboarding), QR Code (physical proximity pairing), Trust Registry (pre-authorized enterprise), and Peer Discovery (mDNS local network). All use cryptographic DIDs.
-
-| Model | Security | UX | Best For |
-|-------|----------|-----|----------|
-| Invite Code | Single-use, 24h TTL | 6-char code | Customer onboarding |
-| QR Code | Physical proximity, 60s TTL | Scan & tap | Mobile/desktop pairing |
-| Trust Registry | Admin pre-auth, scoped | Zero (automated) | Enterprise/CI/CD |
-| Peer Discovery | LAN proximity, user confirm | Scan & confirm | IoT devices, offline |
-
-See [Entity-to-Entity Connection UX Guide](../../docs/ENTITY-TO-ENTITY-CONNECTION-UX.md) for implementation patterns and code examples.
-
-## Configuration
-
-### Basic Setup
-
-```typescript
-import { HttpTrustRegistry } from '@private.me/xbind';
-
-// Documentation example - use your actual gateway URL
-const registry = new HttpTrustRegistry({
-  baseUrl: 'https://gateway.private.me'
-});
-```
-
-### Advanced Features
-
-Checkpoints, sequence numbers, subscription proofs, XorIDA configuration, key backup (2-of-3 default), DID succession. See [Configuration Guide](./docs/configuration.md) and [Examples](./docs/examples.md).
-
-## Type Safety
-
-xbind returns `Result<T, E>` types for type-safe error handling.
-
-<!-- SNIPPET -->
-```typescript
-import { call, type CallResult } from '@private.me/xbind';
-
-interface User { id: number; name: string; email: string; }
-
-const result: CallResult<User> = await call('getUser', { id: 123 });
-if (result.ok) {
-  console.log(result.value.data.name);
-  console.log(result.value.audit.signature);
-} else {
-  console.error(result.error.message);
-}
-```
-<!-- /SNIPPET -->
-
-Error types: `ConnectionError`, `AuthenticationError`, `ValidationError`, `RateLimitError`, `ServerError`
-
-## Documentation
-
-- **[API Reference](./docs/api-reference.md)** — Complete API documentation
-- **[Configuration Guide](./docs/configuration.md)** — All configuration options
-- **[Examples](./docs/examples.md)** — Common usage patterns
-- **[Troubleshooting](./docs/troubleshooting.md)** — Common issues and solutions
-- **[Advanced Guide](./docs/advanced.md)** — Multi-backend failover, retry strategies
-- **[White Paper](https://private.me/docs/xbind.html)** — Architecture and design
-- **[AGENTS.md](./AGENTS.md)** — AI agent patterns
-- **[SECURITY.md](./SECURITY.md)** — Threat model
-
-## Testing
-
-**1,245/1,245 tests passing** — Comprehensive coverage including post-quantum cryptography (ML-KEM-768, ML-DSA-65), hybrid signature verification, DID generation, message encryption, transport layer, multi-agent coordination, error handling, Python SDK bindings, and Full Control protection.
-
-```bash
-pnpm test                # All tests
-pnpm test:coverage       # Coverage report
-pnpm test:watch          # Watch mode
-```
-
-## Full Control IP Protection
-
-xBind uses **Full Control** (2-share XorIDA) to protect proprietary cryptographic algorithms while maintaining a seamless developer experience.
-
-### Architecture: Store Front + Vault Store
-
-**Store Front (npm registry):**
-- Contains wrapper code, types, and non-proprietary utilities
-- Includes Share 1 (`share1.dat`) — useless alone, safe to distribute publicly
-- Installed via standard `npm install @private.me/xbind`
-
-**Vault Store (private.me gateway):**
-- Contains Share 2 (encrypted, payment-gated)
-- Delivered via `/api/vault-store/crypto` endpoint
-- Requires xBind DID authentication + usage quota verification
-- AES-256-GCM encrypted with `FULL_CONTROL_MASTER_KEY`
-
-When combined, Share 1 + Share 2 reconstruct the complete XorIDA algorithm at runtime.
-
-### Usage-Based Access Model
-
-**IMPORTANT:** Full Control uses **usage-based metering**, NOT feature-gating.
-
-**All tiers** can access the Vault Store (crypto algorithms + Share 2) **within their usage quota**:
-
-- **Free Tier:** 100,000 operations/month
-  - Grace buffer: 120,000 hard cap (includes 20% overage)
-  - Email verification required
-  - Vault access included (no additional payment needed)
-  - At 120K ops: 402 Quota Exceeded → Upgrade prompt
-
-- **Pro Tier:** Unlimited operations
-  - $5 per 100,000 operations (after first 100K free)
-  - No quota checks
-  - Vault access unlimited
-  - Example: 400K ops = $15/month (100K free + 300K @ $5/100K)
-
-- **VIP Tier:** Custom limits per account
-  - Bronze: 200K, Silver: 500K, Gold: 1M, Platinum: Unlimited
-  - Vault access within custom quota
-
-### Upgrade to Pro
-
-If you exceed the free tier quota, upgrade to Pro for unlimited operations:
-
-```bash
-# Visit the upgrade page
-https://private.me/subscribe?product=xbind&tier=pro
-
-# Or upgrade programmatically via xBind API
-const result = await agent.send({
-  to: 'did:key:z6MkBillingService...',
-  payload: { action: 'upgradeTier', tier: 'pro' }
-});
-```
-
-### 4-Layer Security
-
-1. **DID Authentication:** Ed25519 signature verification (cryptographic proof of identity)
-2. **Usage Quota Verification:** Monthly operation count checked against tier limits
-3. **Rate Limiting:** Free: 100 req/hour, Pro: 1000 req/hour, VIP: 5000 req/hour
-4. **Audit Logging:** Every vault access logged with DID, timestamp, IP, and success status
-
-### Runtime Flow
-
-```typescript
-// 1. Install package (includes Share 1)
-// npm install @private.me/xbind
-
-// 2. Create agent (auto-fetches Share 2 on first use)
-const agent = await Agent.create(seed);
-
-// 3. Vault Store loader detects missing crypto
-// 4. POST /api/vault-store/crypto
-//    - Auth: DID signature
-//    - Verify: Usage quota (Free: <120K, Pro: unlimited)
-//    - Response: { cryptoBundle, share2, version }
-
-// 5. Load crypto dynamically (Share 1 + Share 2 = complete algorithm)
-// 6. Cache in memory (session-only, 7-day expiration)
-// 7. Use reconstructed XorIDA algorithm
-
-await agent.send({
-  to: recipientDid,
-  payload: { amount: 100, currency: 'BTC' },
-  security: 'high' // Uses XorIDA (2-of-3 threshold)
-});
-```
-
-### Why This Matters
-
-**Without Full Control:**
-- Complete XorIDA algorithm exposed in npm tarball
-- Anyone can download and use without payment
-- Patent protection (US 11,972,000) defeated
-- Revenue model bypassed
-
-**With Full Control:**
-- Share 1 alone is mathematically useless (information-theoretic security)
-- Share 2 requires usage-based quota verification
-- Patent-protected algorithms delivered only to paying users (or within free tier quota)
-- Reverse engineering requires breaking AES-256-GCM encryption
-
-**Revenue Protection:**
-- Free tier: 100K ops/month (generous for experimentation)
-- Pro tier: Usage-based billing scales with value delivered
-- DeploymentID tracking prevents quota reset attacks (DID rotation doesn't bypass limits)
-
-See [IP Protection Documentation](./docs/ip-protection.md) for complete technical details.
-
-## Data Collection
-
-xBind makes network connections for three purposes, each with different security and privacy characteristics:
-
-### 1. Local Network Discovery (Peer Discovery Model Only)
-
-**When:** Only when using the Peer Discovery connection model for IoT devices and offline pairing.
-
-**What:** Sends mDNS (multicast DNS) broadcast messages on your local network to discover nearby xBind-compatible devices.
-
-**Data transmitted:**
-- Device DID (cryptographic identity, public key)
-- Device type identifier
-- Service announcement (port, protocol version)
-
-**Security:** Broadcast messages are visible to all devices on the local network. Does NOT transmit private keys, message content, or personal data. Recipients cannot impersonate your device without the private key.
-
-**Privacy:** Other connection models (Invite Code, QR Code, Trust Registry) do NOT use local network discovery.
-
-### 2. Gateway Communication (gateway.private.me)
-
-**When:** During message delivery, Share 2 retrieval, and connection establishment.
-
-**What:** Encrypted communication with gateway.private.me for coordination and IP protection.
-
-**Data transmitted:**
-- **Share 2 delivery:** Encrypted share required for Full Control vault store reconstruction (payment-gated)
-- **Usage metrics:** Operation counts, error codes, latency (anonymized, no message content)
-- **Connection metadata:** DID identifiers, sequence numbers, checkpoints (for message ordering)
-- **Push notifications:** Delivery receipts, presence signals (encrypted, no content)
-
-**Security:** All communication uses TLS 1.3. Gateway is non-authoritative and cannot forge identity or decrypt messages. See [Gateway Architecture](./docs/gateway-architecture.md).
-
-**Privacy:** No message content, API credentials, or plaintext data transmitted. DIDs are pseudonymous identifiers.
-
-### 3. Full Control Share Retrieval
-
-**When:** During initial setup and algorithm reconstruction.
-
-**What:** Downloads Share 2 (Vault Store) from gateway.private.me after payment verification.
-
-**Data transmitted:**
-- Payment proof (Stripe subscription ID)
-- xBind authentication token (cryptographic proof of identity)
-- Package identifier and version
-
-**Security:** Share 2 is AES-256-GCM encrypted with FULL_CONTROL_MASTER_KEY. Without both Share 1 (npm) and Share 2 (gateway), the algorithm cannot execute.
-
-**Privacy:** Payment verification uses Stripe (see [Stripe Privacy](https://stripe.com/privacy)). xBind does not store credit card data.
-
-### Data Retention
-
-- **Usage metrics:** 90 days (aggregated, anonymized)
-- **Connection metadata:** 30 days (sequence numbers, checkpoints)
-- **Share 2 downloads:** Access logs retained per payment verification requirements
-
-### Opt-Out
-
-**Local network discovery:** Disable by not using Peer Discovery connection model.
-
-**Gateway communication:** Required for message delivery. Self-hosted gateway option available for enterprise (contact contact@private.me).
-
-**Usage metrics:** Cannot be disabled (required for billing and abuse prevention).
-
-For complete privacy details, see [Privacy Policy](https://private.me/privacy).
-
-## Legal
-
-[Terms of Service](https://private.me/terms) • [Privacy Policy](https://private.me/privacy) • [License](./LICENSE.md)
-
-## Export Control Notice
-
-This package contains cryptographic software. Export restrictions may apply. Users are responsible for compliance with U.S. Export Administration Regulations (EAR) and jurisdiction-specific export control requirements.
-
----
-
-**License:** Proprietary
-
----
-
-**Questions?** [Documentation](./docs/README.md) • [White paper](https://private.me/docs/xbind.html) • [Issues](https://github.com/xail-io/xail/issues)