@private.me/xbind 1.2.15 → 1.2.17

package/README.md

@@ -1,7 +1,7 @@
 # @private.me/xbind
 
 ![npm version](https://img.shields.io/npm/v/@private.me/xbind)
-![version](https://img.shields.io/badge/version-1.2.15-blue)
+![version](https://img.shields.io/badge/version-1.2.17-blue)
 ![tests](https://img.shields.io/badge/tests-1245%20passing-brightgreen)
 ![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue)
 ![license](https://img.shields.io/badge/license-Proprietary-blue)
@@ -12,7 +12,7 @@ Build AI agents that communicate securely using ML-DSA-65 DID identity, ML-KEM-7
 
 Part of the **Private.Me** platform—where APIs have keys, but ACIs have identity.
 
-**Version 1.1.7** — **Dependency hardening:** Vendored mldsa-wasm@0.0.4 (eliminates external dependency risk). Previous v1.1.6: CRITICAL SECURITY FIX removed deriveSharedKey() vulnerability. PLAN-3 architecture with post-quantum cryptography (ML-KEM-768, ML-DSA-65), Python SDK, and Full Control protection.
+**Version 1.2.17** — **Documentation:** Generic pricing language per Gold Package Requirement #18 (removed specific operation counts). Previous v1.2.16: AWS/gRPC/HTTP Error Mappings - All 49 error codes now include protocol-specific mappings (aws, grpc, http fields) for cross-platform error translation.
 
 ## Install
 
@@ -126,22 +126,38 @@ See [Configuration Guide](./docs/configuration.md) for complete setup instructio
 
 ## Pricing
 
-**3-month free trial** — No credit card required.
+**Free tier available** — No credit card required.
 
-**Tiers:** Free, Pro, and Enterprise plans available. Free tier includes generous limits. Pro tier provides usage-based billing. Enterprise tier offers volume discounts and dedicated support.
-
-See [pricing details](../../docs/pricing-reference.md) for current rates and complete tier comparison.
+See [pricing details](../../docs/pricing-reference.md) for current rates and tier comparison.
 
 [Subscribe now](https://private.me/subscribe?product=xbind)
 
 ## Quick Start
 
-**15 seconds to setup:**
+**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
+```
+
+**What happens:**
+1. Enter your email address
+2. Receive 6-digit verification code (check spam folder)
+3. Enter code to activate account
+4. DeploymentID generated (persistent economic identity)
+
+**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 identity)
+// Create agent (auto-generates cryptographic identity)
 const agent = await Agent.lazy({ name: 'my-service' });
 
 // Send authenticated message
@@ -160,6 +176,16 @@ 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.
@@ -205,6 +231,96 @@ Zero key management, zero cascade failures, zero bearer credentials. Cryptograph
 
 **Zero-config JITR:** Just-in-Time Registration auto-registers agents with trust registry on first use (AWS IoT JITR, OAuth DCR, MCP 2025 standards). Post-quantum cryptography (ML-KEM-768, ML-DSA-65), bilateral authorization, XorIDA split-channel delivery, Python SDK, Full Control IP protection, zero rotation, type safety with `Result<T, E>`, PLAN-3 hybrid signatures, 96 error codes.
 
+## 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: