# xBind Migration Guide

## 3.1.0 → 3.1.1 (Current)

### Fully Bundled Architecture

**Strategic Change:** Customer feedback prioritized UX over IP protection architecture. xBind now ships as a fully bundled package.

**What Changed:**
- ✅ **All crypto vendored:** No more Share 2 fetching, no payment validation during crypto loading
- ✅ **Works offline:** Instant startup after `npm install`—no network calls required
- ✅ **Deprecated APIs:** `loadCryptoPackage()` still works (no-op for backward compatibility)
- ✅ **Security fixes:** Removed eval(), fixed KEM signature coverage

**Migration:** Update package version - no code changes required:
```bash
npm install @private.me/xbind@3.1.1
```

**Benefits:**
- Fast: Zero latency from dynamic loading
- Predictable: No runtime fetch failures
- Enterprise-friendly: Works in air-gapped environments
- AI-optimized: No async initialization needed

**Legal Protection:**
- ToS acceptance required during registration (server-enforced)
- Payment verification for xChange operations (not crypto loading)

---

## 3.0.4 → 3.1.0

### Documentation Improvements

**No Breaking Changes** - This is a documentation-only release:

- ✅ **Migration Guide:** Added this MIGRATING.md file with upgrade paths for all versions
- ✅ **Error Reference:** Comprehensive error code documentation with fixes for common issues
- ✅ **Security API:** Clarified `security` parameter (official API) vs `payload.risk` (application data)
- ✅ **Bundled README:** Fixed broken relative links, removed internal tracking codes, consistent PQ examples

**Migration:** Update package version - no code changes required:
```bash
npm install @private.me/xbind@3.1.0
```

---

## 3.0.3 → 3.0.4

### Bug Fixes

**H1 Security Tier Fix:**
- **Issue:** `agent.send({ security: 'high' })` threw synchronously instead of returning `Result<T,E>`
- **Fixed:** Now returns `Result` with error code `ENVELOPE_FAILED:SPLIT` when split-channel requires 3+ transports but fewer are configured
- **Migration:** No code changes required. If you had try-catch around `send()`, you can now use standard Result handling

**Loopback URL Support:**
- **Issue:** v3.0.3 broke dev/test workflows by rejecting `http://127.0.0.1` and `http://localhost`
- **Fixed:** RFC 6761 loopback addresses now work without HTTPS requirement
- **Migration:** No code changes required. Remove any HTTPS workarounds for local development

### Supported Loopback Addresses
- `http://127.0.0.1` (IPv4 loopback)
- `http://localhost` (standard hostname)
- `http://[::1]` or `http://::1` (IPv6 loopback)
- `http://*.localhost` (RFC 6761 reserved)

---

## 2.x → 3.x (Major Version)

### Breaking Changes

**1. Result<T,E> Error Handling (Required)**

v3.x replaced exception-based APIs with Result types:

```typescript
// v2.x: Exception-based
try {
  const agent = await Agent.create({ name: 'MyAgent' });
  await agent.send({ to: did, payload: data });
} catch (error) {
  console.error('Failed:', error);
}

// v3.x: Result-based
const agentResult = await Agent.create({ name: 'MyAgent' });
if (!agentResult.ok) {
  console.error('Agent creation failed:', agentResult.error);
  return;
}

const sendResult = await agentResult.value.send({ to: did, payload: data });
if (!sendResult.ok) {
  console.error('Send failed:', sendResult.error);
}
```

**Migration:** Update all API calls to check `result.ok` before accessing `result.value`.

**2. Bundled Architecture (v3.1.1+)**

v3.1.1 restored fully bundled crypto for better UX:

```bash
# v2.x: All crypto bundled
npm install @private.me/xbind@2.3.0

# v3.1.1+: Also fully bundled (no migration needed)
npm install @private.me/xbind@3.1.1
```

**Migration:** No code changes—crypto works offline immediately.

**3. Registry API Changes**

v3.x introduced options objects for cleaner APIs:

```typescript
// v2.x: Positional parameters
await registry.register(did, pubKey, name, scopes, x25519Key);

// v3.x: Options object
await registry.register({
  did,
  rawPublicKey: pubKey,
  name,
  scopes,
  rawX25519PublicKey: x25519Key
});
```

**Migration:** Update all `registry.register()` calls to use options objects.

See [Error Reference](./ERROR-REFERENCE.md) for common migration errors and fixes.

---

## 1.x → 3.x (Major Version)

### Breaking Changes

**1. Bundled Architecture (as of v3.1.1)**

v3.1.1 restored fully bundled crypto (like v1.x) for better UX:

```typescript
// v1.x: All crypto bundled in npm package
npm install @private.me/xbind@1.4.2  // 8MB package

// v3.0.x-3.1.0: Share 1 in npm, Share 2 payment-gated (deprecated)
npm install @private.me/xbind@3.1.0  // 1.2MB package

// v3.1.1+: All crypto bundled again (current)
npm install @private.me/xbind@3.1.1  // Works offline immediately
```

**Migration:**
- **No code changes required**—crypto always available
- **Offline support:** Works immediately after install, no network calls
- **Deprecated:** `loadCryptoPackage()` (still works as no-op for compatibility)

**2. Result<T,E> Error Handling**

All APIs now return `Result<T,E>` instead of throwing:

```typescript
// v1.x: Exception-based
try {
  const agent = await Agent.create({ ... });
  await agent.send({ ... });
} catch (error) {
  console.error('Failed:', error);
}

// v3.x: Result-based
const agentResult = await Agent.create({ ... });
if (!agentResult.ok) {
  console.error('Agent creation failed:', agentResult.error);
  return;
}

const agent = agentResult.value;
const sendResult = await agent.send({ ... });
if (!sendResult.ok) {
  console.error('Send failed:', sendResult.error);
}
```

**3. Security Tier API**

Explicit `security` parameter for split-channel:

```typescript
// v1.x: Implicit/auto-detection
await agent.send({
  to: recipientDid,
  payload: { sensitive: true }
});

// v3.x: Explicit security parameter
await agent.send({
  to: recipientDid,
  security: 'high',  // 2-of-3 threshold
  payload: { sensitive: true }
});
```

Options: `'standard'` (default), `'high'` (2-of-3), `'critical'` (3-of-5)

**4. Transport Configuration**

v3.x requires explicit transport configuration:

```typescript
// v1.x: Auto-configured
const agent = await Agent.create({ name: 'MyAgent' });

// v3.x: Explicit transport
import { HttpsTransportAdapter } from '@private.me/xbind';

const agent = await Agent.create({
  name: 'MyAgent',
  transport: new HttpsTransportAdapter({
    baseUrl: 'https://private.me/relay'
  })
});
```

---

## Common Migration Issues

### Issue: npm install silently downgrades version

**Symptom:** Running `npm install @private.me/xbind@latest` after local `file:` testing uninstalls xBind

**Cause:** npm's `file:` protocol creates a local package reference that persists across installs

**Fix:**
```bash
# Remove cached local reference
npm uninstall @private.me/xbind
rm -rf node_modules/@private.me
rm package-lock.json

# Clean install from registry
npm install @private.me/xbind@3.1.0
```

### Issue: ENVELOPE_FAILED:SPLIT error

**Symptom:** `security:'high'` or `security:'critical'` returns `ENVELOPE_FAILED:SPLIT`

**Cause:** Split-channel requires 3+ transports for `'high'`, 5+ for `'critical'`

**Fix:**
```typescript
// Add multiple transports
const agent = await Agent.create({
  name: 'MyAgent',
  transport: new HttpsTransportAdapter({ baseUrl: 'https://relay1.private.me' }),
  // OR use quickstart which auto-configures transports
});

// Add more transports after creation
agent.addTransport(new HttpsTransportAdapter({ baseUrl: 'https://relay2.private.me' }));
agent.addTransport(new HttpsTransportAdapter({ baseUrl: 'https://relay3.private.me' }));

// Now 'high' security will work
const result = await agent.send({
  to: recipientDid,
  security: 'high',
  payload: { message: 'Secured' }
});
```

### Issue: IDENTITY_FAILED:VAULT_STORE error

**Symptom:** Agent creation fails with `IDENTITY_FAILED:VAULT_STORE`

**Cause:** Using legacy version (v3.0.x - v3.1.0) with unavailable Share 2

**Fix:**
```bash
# Upgrade to v3.1.1+ which includes bundled crypto
npm install @private.me/xbind@3.1.1
```

**Legacy Fix (v3.0.x - v3.1.0 only):**
- Ensure billing is active (free tier: 100K ops/month)
- Check internet connectivity
- Or set `FULL_CONTROL_MASTER_KEY` environment variable

---

## Support

- **Documentation:** https://private.me/docs/xbind.html
- **npm:** https://www.npmjs.com/package/@private.me/xbind
- **Email:** contact@private.me

For enterprise migration assistance, contact contact@private.me
