Replace any API connection in minutes

Executive Summary

Xlink establishes entity-to-entity connections where both sides have cryptographic identities and verify each other's messages. No API keys, no asymmetric trust, no centralized gateways — just two independent entities with a bilateral trust relationship.

Two functions cover 80% of use cases: Agent.quickstart() generates an Ed25519 + X25519 identity with hybrid post-quantum key exchange (X25519 + ML-KEM-768, always-on) and registers it with default settings — zero configuration required. agent.send() encrypts a payload with AES-256-GCM, signs it with Ed25519 (+ ML-DSA-65 when postQuantumSig: true), and delivers it via any transport adapter. The receiver verifies signatures, checks replay protection, validates scope, and decrypts — automatically. Both sides perform the same verification steps, enforcing mutual trust rather than client-server hierarchy. For advanced use cases, Agent.create() accepts custom registry and transport configuration.

When you need information-theoretic security, split-channel mode shards messages via XorIDA (threshold sharing over GF(2)) and routes each share independently. An attacker who compromises any single channel learns nothing about the plaintext — not computationally hard to break, but mathematically impossible.

This entity-to-entity model removes the architectural assumptions of traditional APIs: no bearer tokens to rotate, no central auth servers to scale, no DNS dependency for trust. Each entity generates its own identity once, registers trusted peers, and communicates directly. The connection is symmetric, decentralized, and quantum-resistant by default.

Zero configuration out of the box. Zero npm runtime dependencies. Runs anywhere the Web Crypto API is available — Node.js, Deno, Bun, Cloudflare Workers, browsers. Dual ESM and CJS builds ship in a single package.

Multi-Agent Communication

Two agents establish cryptographic identities and communicate with full mutual authentication — no API keys, no central gateway, no configuration.

Alice and Bob: Peer-to-Peer Messaging

The following example demonstrates the complete lifecycle: both agents create identities using Agent.quickstart(), register with a shared trust registry, exchange messages with automatic encryption and signature verification, and validate each other's scope permissions.

import { Agent, MemoryTrustRegistry, LoopbackTransport } from '@private.me/agent-sdk';

// Shared infrastructure (in production, use HttpTrustRegistry + HttpsTransportAdapter)
const registry = new MemoryTrustRegistry();
const transport = new LoopbackTransport();

// Alice creates her identity
const alice = await Agent.quickstart({
  name: 'Alice',
  registry,
  transport,
});
console.log(`Alice DID: ${alice.did}`);
// Alice DID: did:key:z6MksZP8ChwZYSNgozYq...

// Bob creates his identity
const bob = await Agent.quickstart({
  name: 'Bob',
  registry,
  transport,
});
console.log(`Bob DID: ${bob.did}`);
// Bob DID: did:key:z6MkpH7eQ2KvYnPWbD...

// Alice sends a message to Bob
const sendResult = await alice.send({
  to: bob.did,
  payload: { type: 'greeting', text: 'Hello Bob!' },
  scope: 'chat',
});

if (!sendResult.ok) {
  throw new Error(`Send failed: ${sendResult.error}`);
}

// Bob receives and verifies the message
const envelope = transport.outbox[0];
const receiveResult = await bob.receive(envelope);

if (!receiveResult.ok) {
  throw new Error(`Receive failed: ${receiveResult.error}`);
}

console.log(`From: ${receiveResult.value.sender}`);
// From: did:key:z6MksZP8ChwZYSNgozYq...
console.log(`Payload:` , receiveResult.value.payload);
// Payload: { type: 'greeting', text: 'Hello Bob!' }
console.log(`Scope: ${receiveResult.value.scope}`);
// Scope: chat

// Bob replies to Alice
await bob.send({
  to: alice.did,
  payload: { type: 'response', text: 'Hi Alice!' },
  scope: 'chat',
});

// Alice receives Bob's reply
const reply = await alice.receive(transport.outbox[1]);
console.log(`Bob says: ${reply.value.payload.text}`);
// Bob says: Hi Alice!

Service-to-Service Communication

The same pattern applies to backend services. Here's a Payment service communicating with a Billing service:

// Shared infrastructure
const registry = new HttpTrustRegistry({ baseUrl: 'https://trust.corp.example.com' });
const transport = new HttpsTransportAdapter({ baseUrl: 'https://relay.corp.example.com' });

// Payment service creates its identity
const paymentService = await Agent.quickstart({
  name: 'payment-service',
  registry,
  transport,
});

// Billing service creates its identity
const billingService = await Agent.quickstart({
  name: 'billing-service',
  registry,
  transport,
});

// Payment service notifies Billing about a completed transaction
await paymentService.send({
  to: billingService.did,
  payload: {
    transactionId: 'txn_abc123',
    amount: 99.50,
    currency: 'USD',
    customerId: 'cust_xyz789',
  },
  scope: 'payment:notify',
});

// Billing service receives and processes the notification
const txn = await billingService.receive(envelope);
console.log(`Transaction from: ${txn.value.sender}`);
console.log(`Amount: $${txn.value.payload.amount}`);

// Billing service sends confirmation back to Payment service
await billingService.send({
  to: paymentService.did,
  payload: {
    status: 'recorded',
    invoiceId: 'inv_2024_001',
  },
  scope: 'billing:confirm',
});

What Happens Under the Hood

When Alice calls send():

1. Lookup: Queries the trust registry to retrieve Bob's public keys (Ed25519 signing, X25519 key agreement, ML-KEM-768 post-quantum KEM)
2. Key Agreement: Performs hybrid ECDH (X25519 + ML-KEM-768 encapsulation) to derive a shared symmetric key
3. Encryption: Encrypts the payload with AES-256-GCM using the derived key
4. Signing: Signs the envelope with Alice's Ed25519 private key
5. Transport: Sends the signed envelope to Bob via the transport adapter

When Bob calls receive():

1. Signature Verification: Verifies Alice's Ed25519 signature using her public key from the registry
2. Replay Protection: Checks the nonce store to ensure this envelope hasn't been seen before
3. Scope Validation: Confirms Alice has permission to use the specified scope
4. Key Agreement: Performs hybrid ECDH (X25519 + ML-KEM-768 decapsulation) to derive the same shared key
5. Decryption: Decrypts the payload with AES-256-GCM
6. Returns Result: Delivers the verified, decrypted payload to the application

Both sides perform the same verification steps — mutual authentication, mutual scope enforcement, mutual replay protection. Neither side has elevated privileges. The connection is truly peer-to-peer.

Developer Experience

Xlink provides real-time progress tracking and 45+ structured error codes to help developers build reliable, debuggable M2M systems.

Progress Callbacks

Both send() and receive() operations support onProgress callbacks for tracking long-running operations, especially useful for split-channel mode where multiple shares are transmitted independently.

const envelope = await agent.send({
  to: recipientDid,
  payload: largeData,
  onProgress: async (event) => {
    switch (event.stage) {
      case 'encrypting':
        console.log('Encrypting payload...');
        break;
      case 'signing':
        console.log('Signing envelope...');
        break;
      case 'sending':
        console.log(`Sending share ${event.current}/${event.total}...`);
        break;
      case 'complete':
        console.log('Message sent successfully');
        break;
    }
  }
});

// Receive with progress tracking
const result = await agent.receive(envelope, {
  onProgress: async (event) => {
    if (event.stage === 'reconstructing') {
      console.log(`Reconstructing from ${event.current} shares...`);
    }
  }
});

Structured Error Handling

Xlink uses a Result<T, E> pattern with detailed error structures. Every error includes a machine-readable code, human-readable message, actionable hint, and documentation URL.

interface ErrorDetail {
  code: string;         // e.g., 'INVALID_DID'
  message: string;      // Human-readable description
  hint?: string;        // Actionable suggestion
  field?: string;       // Field that caused the error
  docs?: string;        // Documentation URL
}

Error Categories

Xlink organizes 45+ error codes across 7 categories, making it easy to handle errors systematically:

Fast Onboarding: < 2 Minute Setup

Zero-config service discovery and invite flow enable rapid M2M adoption. Setup time: < 2 minutes (vs 42-67 minutes for API keys).

The 2-Minute Setup Flow

Traditional API key setup requires 42-67 minutes of developer time per integration: account creation, API key generation, secret management setup, documentation reading, SDK installation, configuration, testing, and deployment. Xlink reduces this to under 2 minutes through zero-config service discovery and automatic trust establishment:

// Step 1: Initialize local identity (< 30 sec)
$ xlink init --name my-service
{
  "status": "initialized",
  "did": "did:key:z6MksZP8ChwZYSNgozYq...",
  "name": "my-service"
}

// Step 2: Connect to a service (< 90 sec)
$ xlink connect payments-service
{
  "status": "connected",
  "service": "payments-service",
  "did": "did:key:z6Mkf2rR8...",
  "endpoint": "https://api.payments.example.com",
  "elapsed_seconds": 1.3
}

// Step 3: Use it immediately
const { connect } = require('@private.me/agent-sdk');
const connection = await connect('payments-service');
await connection.value.agent.send({
  to: connection.value.did,
  payload: { action: 'createCharge', amount: 100 },
  scope: 'payments'
});

Zero-Config Discovery (3-Tier Lookup)

The connect() function accepts service names, domains, or URLs and automatically discovers connection details through a 3-tier lookup system:

Invite Flow (< 10 sec creation, < 60 sec acceptance)

The invite system enables effortless service-to-service connections. Creating an invite takes < 10 seconds, accepting takes < 60 seconds, and the invite recipient can immediately use the connection.

$ xlink invite billing-service --email billing@example.com
{
  "status": "created",
  "invite_url": "https://xlink.to/invite/a7Km9x...",
  "qr_code": "data:image/svg+xml,...",
  "expires_at": "2026-04-19T...",
  "message": "Share this link: https://xlink.to/invite/a7Km9x..."
}

When the recipient clicks the invite link, they see a one-click acceptance page with the inviter's service info. Accepting the invite automatically establishes the connection and adds both services to each other's trust registries.

Zero-Downtime Migration (Dual-Mode Adapter)

For existing M2M connections using API keys, Xlink provides a DualModeAdapter that runs Xlink and API key authentication simultaneously. This enables zero-downtime migration with gradual rollout and usage tracking:

const { DualModeAdapter } = require('@private.me/agent-sdk');

// Create dual-mode adapter (tries Xlink first, falls back to API key)
const adapter = new DualModeAdapter({
  xlink: xlinkAgent,        // Optional: add when ready
  fallback: {
    type: 'api-key',
    key: process.env.API_KEY,
    url: 'https://api.example.com',
  },
});

// Make calls (automatically tries Xlink → API key)
const result = await adapter.call('createCharge', { amount: 100 });

// Track migration progress
const metrics = adapter.getMetrics();
console.log(`Xlink usage: ${metrics.xlinkPercentage}%`);
// Output: "Xlink usage: 78%"

// Remove fallback when 100% migrated
adapter.removeFallback();

Comparison: Xlink vs Traditional API Keys

Three Paths to Production

Xlink adoption follows three distinct business paths: greenfield connections (new builds), migration (existing APIs), and enterprise deployment (governance at scale). Each path has its own optimal onboarding flow.

Path 1: Greenfield (New Connections)

For new M2M connections with no existing API infrastructure, Xlink offers three speed tiers. All three accomplish the same goal — establishing a secure identity-based connection — but at different setup speeds and automation levels.

Speed Tier 1: Zero-Click (15 seconds)

Fastest onboarding for developers trying Xlink for the first time. Share an invite code, paste it into your environment variables, and the SDK auto-discovers the recipient's identity and auto-registers your DID. First send succeeds immediately with zero manual configuration.

// .env file
XLINK_INVITE_CODE=XLK-abc123def456

// Your code
const { Agent } = require('@private.me/agent-sdk');

// Agent auto-accepts invite and configures trust on first use
const agent = Agent.lazy({ name: 'my-service' });

// First send triggers identity generation + auto-registration
await agent.send({
  to: 'did:key:z6MkPartnerDID...',
  payload: { action: 'processData', data: { ... } },
  scope: 'integration'
});

Setup time: ~15 seconds
Best for: First-time developers, rapid prototyping, quick demos
Key benefit: Instant working demo → share invite with colleagues → immediate connection

Speed Tier 2: CLI-Guided (90 seconds)

Interactive CLI command that guides developers through framework-specific setup. Generates boilerplate code for Node.js, Python, Go, or Rust. Validates the connection with a test message before completing.

# Both commands are equivalent (xlink-onboard is an alias)
$ npx @private.me/agent-sdk init --invite XLK-abc123def456
# OR
$ npx @private.me/agent-sdk xlink-onboard --invite XLK-abc123def456

? Select your framework: Node.js (Express)
? Project name: my-integration

✓ Generated identity: did:key:z6MksZP8ChwZYSNgozYq...
✓ Configured trust registry
✓ Created src/xlink-client.ts
✓ Created .env with connection details
✓ Test message sent successfully

Ready to integrate. Run: npm start

Setup time: ~90 seconds
Best for: Developers integrating into existing systems, production setup
Key benefit: Production-ready code generated, validated connection before completion

Speed Tier 3: Deploy Button (10 minutes)

One-click infrastructure deployment for teams. Provisions complete production environment with Xlink pre-configured — Docker containers, Nginx reverse proxy, SSL certificates, health checks, and monitoring. Outputs production URLs when complete.

<!-- Add to README.md -->
[![Deploy to Cloud](https://deploy.private.me/button)](https://github.com/private-me/xlink-infra/actions)

// Click button → GitHub Actions provisions:
// - DigitalOcean Droplet (or AWS EC2 / Google Cloud)
// - Docker Compose with Xlink services
// - Nginx reverse proxy + Let's Encrypt SSL
// - Prometheus monitoring + Grafana dashboards
// - Health check endpoints

// Outputs after 10 minutes:
{
  "service_url": "https://xlink.your-company.com",
  "did": "did:key:z6MksZP8ChwZYSNgozYq...",
  "status": "healthy"
}

Setup time: ~10 minutes
Best for: Teams deploying production infrastructure, platform integrations
Key benefit: Complete infrastructure → SSL, monitoring, backups — zero DevOps work

Speed Tier Comparison

Path 2: Migration (Existing APIs)

Already have a working API connection? Migrate safely to Xlink using Xfuse — the threshold identity fusion bridge that runs ACI connections in parallel with your existing API, shifts traffic gradually, and deprecates the API when you're ready.

// Step 1: Deploy ACI alongside existing API (no downtime)
const { Xfuse } = require('@private.me/xfuse');

const bridge = await Xfuse.create({
  legacy: { apiKey: process.env.API_KEY, endpoint: 'https://api.legacy.com' },
  modern: { agent: xlinkAgent }
});

// Step 2: Mirror traffic (validate both paths)
const result = await bridge.send({
  mode: 'mirror',  // Send to both, compare results
  payload: { action: 'transfer', amount: 100 }
});

// Step 3: Shift traffic (10% → 50% → 100%)
bridge.setTrafficRatio({ aci: 0.5, api: 0.5 });

// Step 4: Deprecate API when ACI proves stable
bridge.setTrafficRatio({ aci: 1.0, api: 0.0 });

Migration time: Days to weeks (gradual traffic shift)
Downtime: Zero (parallel deployment)
Rollback: Instant (shift ratio back to API)
Learn more: Xfuse White Paper

Path 3: Enterprise (Governance at Scale)

Large organizations require centralized trust management, audit trails, and policy enforcement across hundreds of services. Enterprise deployment focuses on governance infrastructure rather than individual connection speed.

// Step 1: Configure centralized trust registry
const registry = await TrustRegistry.enterprise({
  mode: 'centralized',
  endpoint: 'https://trust.corp.example.com'
});

// Step 2: Define org-wide policies
const policy = await PolicyEngine.create({
  rules: [
    { scope: 'finance', require: ['2FA', 'audit-log'] },
    { scope: 'public', require: ['rate-limit'] }
  ]
});

// Step 3: Enable audit trail for compliance
const audit = await AuditLog.enterprise({
  retention: '7-years',  // SOX / SEC 17a-4
  encryption: 'org-key'
});

// All services inherit org config automatically
const agent = await Agent.create({
  name: 'payment-service',
  registry,  // Shared across org
  policy,    // Enforced centrally
  audit      // Compliance copy to SOC
});

Deployment scope: Organization-wide (10s–1000s of services)
Configuration: Once (all services inherit)
Compliance: SOC 2, ISO 27001, FedRAMP, HIPAA-ready
Learn more: Authorization • Audit Logs • Credentials

Choosing Your Path

Your adoption path depends on your starting point:

1. Building something new? → Greenfield Path — Start with Zero-Click (15s) for instant demo, upgrade to CLI (90s) for production code, or use Deploy Button (10min) for full infrastructure.
2. Already have an API? → Migration Path — Use Xfuse to run ACI parallel, shift traffic gradually (10% → 50% → 100%), deprecate API when stable. Zero downtime.
3. Deploying across an organization? → Enterprise Path — Configure trust registry, policies, and audit once. All services inherit org-wide governance automatically.

The Problem

Machine-to-machine security today is a patchwork of API keys, OAuth client credentials, mTLS certificates, and API gateways — each with its own rotation schedule, configuration surface, and failure modes.

API keys leak. They end up in logs, git commits, environment variables shared over Slack, and CI pipelines with overly broad access. Rotation means touching every service that holds the key — a manual, error-prone process.

OAuth is complex. Client credentials flow requires token endpoints, scopes, refresh logic, and revocation. Every new service needs a registration, a secret, and a grant configuration.

mTLS certs expire. Certificate lifecycle management is a full-time job. Renewal failures cause outages. CA compromise is a single point of failure for the entire mesh.

Gateways add latency and cost. Centralized API gateways become bottlenecks, introduce single points of failure, and charge per-request fees that scale with traffic.

* Ed25519 identity keys are permanent. No expiry, no renewal. New identity = new DID. See Limitations for details.

Two-Way Communication (vs One-Way APIs)

Traditional APIs provide one-way request/response flows. When bidirectional communication is needed, systems cobble together separate mechanisms: the client makes HTTP requests in one direction, and the server sends webhooks or uses SSE/WebSockets in the reverse direction. This creates architectural complexity, separate authentication flows, and webhook delivery failures.

Xlink provides native two-way peer-to-peer communication. Both services are agents with DIDs, public keys, and the ability to send and receive messages. There is no client/server distinction at the protocol level — both parties are peers. This eliminates the need for webhooks, polling, and separate bidirectional channels.

// Service A sends request to Service B
const request = await serviceA.send({
  to: serviceBDid,
  payload: { action: 'processPayment', amount: 100 },
  scope: 'payments',
});

// Service B receives request
const inbound = await serviceB.receive(request);

// Service B sends response back to Service A
const response = await serviceB.send({
  to: serviceADid,
  payload: { status: 'success', transactionId: 'tx_123' },
  scope: 'payments',
});

// Service A receives response (no webhook needed)
const result = await serviceA.receive(response);

With APIs, the reverse direction would require Service A to expose a webhook endpoint, implement authentication, handle delivery failures, and manage retries. With Xlink, both directions use the same authenticated message-passing primitives. The relay server handles store-and-forward, delivery guarantees, and NAT traversal automatically.

The Old Way

The New Way

Real-World Use Cases

Six scenarios where Xlink replaces traditional API key management with Authenticated Cryptographic Interfaces.

Solution Architecture

Six composable modules. Each can be used independently or combined through the high-level Agent ACI.

The One-Time Setup

Five lines of code. No configuration files, no gateway dashboards, no certificate authorities.

import { Agent, MemoryTrustRegistry, HttpsTransportAdapter } from '@private.me/agent-sdk';

const registry  = new MemoryTrustRegistry();
const transport = new HttpsTransportAdapter({ baseUrl: 'https://api.example.com' });
const agent    = (await Agent.create({ name: 'MyService', registry, transport })).value!;

// That's it. agent.did is your identity. agent.send() encrypts + signs + delivers.
await agent.send({ to: recipientDid, payload: { action: 'hello' }, scope: 'chat' });

Forward Secrecy

Hybrid post-quantum key agreement: X25519 ECDH + ML-KEM-768 KEM (always-on for v2+ agents). Ephemeral key pairs provide forward secrecy.

The sender generates a fresh ephemeral X25519 key pair per message. The shared secret is derived from the sender's ephemeral private key and the recipient's static X25519 public key. The ephemeral public key is included in the envelope so the receiver can derive the same shared secret.

Compromise of long-term keys does not reveal past messages. Each message uses a unique shared secret derived from a unique ephemeral key pair. Past messages are protected even if both parties' long-term keys are later compromised.

Split-Channel Mode

Information-theoretic security via XorIDA threshold secret sharing. Automatic risk-based activation.

The SDK automatically applies split-channel protection (2-of-3 XorIDA threshold sharing) for high-risk operations: high-value transfers, cross-organization communication, and sensitive scopes. The plaintext is split into N shares (default 3) over GF(2), with a reconstruction threshold of K (default 2). Each share is independently encrypted, signed, and transmitted via separate channels.

// SDK auto-applies split-channel for high-risk operations
await agent.send({
  to: recipientDid,
  payload: { amount: 500000, action: 'transfer' },  // High value → auto 2-of-3
  scope: 'custody',                              // Sensitive scope → auto 2-of-3
  action: 'execute'                             // Critical action → auto 2-of-3
});

// Manual override if needed (most users won't use this)
await agent.send({
  to: recipientDid,
  payload: { data: 'classified' },
  scope: 'secure',
  security: 'high',  // Force 2-of-3 even if policy wouldn't auto-apply
});

Multi-Transport Routing

For true channel separation, provide one transport adapter per share. The SDK routes share[i] to transports[i % transports.length] using modulo arithmetic. With 3 shares and 3 transports, share 0 goes to transport 0, share 1 to transport 1, share 2 to transport 2. With 3 shares and 2 transports, shares route as 0→0, 1→1, 2→0 (wraps around).

const agent = await Agent.create({
  name: 'SecureAgent',
  registry,
  transport: [
    new HttpsTransportAdapter({ baseUrl: 'https://ch1.example.com' }),
    new HttpsTransportAdapter({ baseUrl: 'https://ch2.example.com' }),
    new HttpsTransportAdapter({ baseUrl: 'https://ch3.example.com' }),
  ],
});

// Shares route: [0 → ch1, 1 → ch2, 2 → ch3]
await agent.send({
  to: recipientDid,
  payload: sensitiveData,
  scope: 'classified',
  security: 'high',  // Auto 2-of-3 split across 3 transports
});

Channel independence is the developer’s responsibility. For maximum security, use different infrastructure providers, different network paths, or different geographic regions for each transport. The SDK warns at runtime if transports.length < totalShares.

V3 Protocol (Default for Split-Channel)

When split-channel mode is activated (via automatic policy or explicit security: 'high') without Xchange, the SDK uses V3 envelopes with full post-quantum protection and three independent cryptographic layers:

V3 is the default for split-channel mode. Each share is independently encrypted with AES-256-GCM using a session key derived from hybrid KEM. The sender generates an ephemeral X25519 key pair AND performs ML-KEM-768 encapsulation per message. Both shared secrets combine via HKDF-SHA256. Authentication uses Ed25519 (always) plus ML-DSA-65 (when enabled). V3 provides defense-in-depth: compromise of any single cryptographic primitive does not break the system.

Xchange Mode (Opt-In Performance)

For latency-critical workloads (IoT, high-frequency M2M, real-time agents), Xchange mode trades per-share encryption and KEM for ~180x faster operation. Activated explicitly via xchange: true on both agent creation and send.

// Agent opts in to Xchange support
const agent = await Agent.create({
  name: 'FastAgent',
  registry, transport,
  xchange: true,
});

// Xchange on send (security policy still applies)
await agent.send({
  to: recipientDid,
  payload: sensorReading,
  scope: 'telemetry',
  security: 'high',  // Split-channel with Xchange speed
});

Default split-channel uses V3 with three independent cryptographic layers: XorIDA payload split, hybrid PQ KEM (X25519 + ML-KEM-768), and dual signatures (Ed25519 + ML-DSA-65). Xchange mode is for scenarios where latency matters more than defense-in-depth.

Identity Layers in PRIVATE.ME

Three composable identity layers. Xlink is Layer 1. XID adds ephemeral unlinkability. Xfuse adds threshold convergence for high-assurance scenarios.

The PRIVATE.ME platform provides a three-layer identity architecture. Each layer builds on the previous, offering progressively stronger privacy guarantees and multi-factor assurance. Applications choose the layer that matches their security requirements.

Layer 1: Xlink — Cryptographic Identity

Xlink provides the foundational identity layer. Every agent has a persistent DID (did:key:z6Mk...) backed by Ed25519 signing and X25519 key agreement. This is the identity used for most M2M communication, agent-to-agent messaging, and service authentication.

import { Agent } from '@private.me/agent-sdk';

// Create a persistent agent identity
const agent = (await Agent.create({
  name: 'MyService',
  registry,
  transport
})).value!;

// DID is stable across sessions
console.log(agent.did);
// did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH

// Same DID on every restart (if keys persisted)
const pkcs8 = await agent.exportPKCS8();
const restored = (await Agent.importIdentity({ pkcs8, registry, transport })).value!;
console.log(restored.did === agent.did);  // true

Layer 2: XID — Ephemeral Unlinkable Identity

XID adds per-verifier ephemeral DIDs derived from a master seed via HKDF. Each relationship sees a different DID. Cross-context tracking becomes impossible. DIDs rotate on a configurable schedule (epoch-based). The master seed is XorIDA-split and never stored in plaintext.

import { EphemeralIdentity } from '@private.me/xid';

// Create ephemeral identity manager (master seed is split-protected)
const eph = await EphemeralIdentity.create({
  epochDurationMs: 86400000,  // 24 hours
  splitConfig: { totalShares: 3, threshold: 2 }
});

// Derive ephemeral DID for specific verifier
const did1 = await eph.deriveForVerifier('ServiceA');
const did2 = await eph.deriveForVerifier('ServiceB');

console.log(did1 !== did2);  // true — unlinkable across contexts

// DID rotates on epoch boundary
const nextEpoch = await eph.deriveForVerifier('ServiceA', epoch + 1);
console.log(nextEpoch !== did1);  // true — unlinkable across time

See the XID white paper for full technical details on HKDF derivation schedules, epoch management, and split-protected seed storage.

Layer 3: Xfuse — Threshold Identity Convergence

Xfuse adds K-of-N threshold convergence for high-assurance scenarios. Identity is established by presenting K independent signals (password + biometric + device credential + trusted third party attestation). Signals converge via XorIDA to derive a session-bound DID. No single signal is sufficient.

import { FusionManager } from '@private.me/xfuse';

// Configure threshold identity fusion
const fusion = new FusionManager({
  threshold: 2,
  totalSignals: 3,
  ial: 'IAL2',  // NIST 800-63A assurance level
});

// Enroll three independent signals
await fusion.enrollSignal({
  type: 'password',
  value: hashedPassword
});
await fusion.enrollSignal({
  type: 'biometric',
  value: fingerprintTemplate
});
await fusion.enrollSignal({
  type: 'device',
  value: tpmAttestation
});

// Authenticate with any 2 of 3 signals
const result = await fusion.converge([
  { type: 'password', value: hashedPassword },
  { type: 'biometric', value: currentFingerprint },
]);

// Session-bound DID derived from converged signals
console.log(result.did);  // did:key:z6Mk... (ephemeral, session-scoped)
console.log(result.assuranceLevel);  // IAL2

See the Xfuse white paper for threshold convergence algorithms, signal diversity requirements, assurance level mapping (IAL1/IAL2/IAL3), and MPC-verified convergence.

Composability & Layer Selection

Applications select the identity layer at integration time. The three layers are independent but composable. A single codebase can use Layer 1 for internal services, Layer 2 for customer-facing endpoints, and Layer 3 for administrative access.

// Internal service — Layer 1 (persistent identity)
const internalAgent = await Agent.create({ name: 'InternalService', registry, transport });

// Customer app — Layer 2 (ephemeral unlinkable)
const customerEph = await EphemeralIdentity.create({ epochDurationMs: 3600000 });
const customerDid = await customerEph.deriveForVerifier('CustomerPortal');

// Admin access — Layer 3 (threshold convergence)
const adminFusion = new FusionManager({ threshold: 3, totalSignals: 4, ial: 'IAL3' });
const adminResult = await adminFusion.converge(signals);

Layer 1 (Xlink) is the foundation. Layer 2 (XID) and Layer 3 (Xfuse) are optional enhancements. Most applications use Layer 1 exclusively. Add Layer 2 when unlinkability is required. Add Layer 3 when regulatory compliance demands multi-factor high-assurance identity.

Identity & Persistence

Ed25519 signing + X25519 key agreement via Web Crypto API. Hybrid post-quantum: ML-KEM-768 for key exchange (always-on), ML-DSA-65 for signatures (opt-in). Multiple persistence strategies for different environments.

DID:key Format

Each agent identity is encoded as a did:key DID string: did:key:z6Mk.... The DID embeds the raw Ed25519 public key with a multicodec prefix (0xed01) and base58btc encoding. Anyone with the DID can verify signatures without a network lookup.

Persistence Strategies

Complete Flow

End-to-end: identity creation through message delivery and verification.

Sender Pipeline

1. Agent.create() generates Ed25519 + X25519 keys (+ ML-DSA-65 keys when postQuantumSig: true) and registers with the trust registry.
2. agent.send() resolves the recipient DID from the registry.
3. Hybrid key exchange: X25519 ECDH + ML-KEM-768 KEM, combined via HKDF-SHA256 (always-on for v2+ agents). SHA-256 fallback for v1 peers.
4. Payload encrypted with AES-256-GCM (12-byte IV, fresh per message).
5. Ciphertext signed with Ed25519 (+ ML-DSA-65 dual signature in v3 envelopes).
6. Envelope assembled: v2/v3, sender DID, recipient DID, timestamp, nonce, scope, payload, signature(s), ephemeralPub, kemCiphertext.
7. Transport adapter delivers the envelope.

Receiver Pipeline

8. agent.receive() validates envelope version (v1/v2/v3) and algorithm.
9. Timestamp checked against configurable window (default 30s).
10. Nonce checked against NonceStore — rejects duplicates (replay prevention).
11. Sender DID resolved from trust registry — must be registered and not revoked.
12. Ed25519 signature verified. ML-DSA-65 signature also verified if present (v3 envelopes).
13. Sender's scope validated against the claimed scope in the envelope.
14. Shared key derived via hybrid KEM (X25519 + ML-KEM-768) or SHA-256 fallback for v1.
15. Payload decrypted with AES-256-GCM.
16. JSON parsed and returned as AgentMessage.

Integration Patterns

Four patterns for different deployment contexts.

Express Middleware

import express from 'express';
const app = express();

// Verify incoming agent envelopes
app.post('/api/messages', agent.middleware(), (req, res) => {
  const msg = req.agentMessage;
  console.log('From:', msg.sender, 'Scope:', msg.scope);
  res.json({ ok: true });
});

Registry Auth Middleware

import { createRegistryAuthMiddleware } from '@private.me/agent-sdk';

// GET /registry/resolve/:did  → public (no auth)
// POST /registry/register     → requires Bearer token
app.use('/registry', createRegistryAuthMiddleware(process.env.REGISTRY_ADMIN_TOKEN));

IoT Composable Pattern

import { generateIdentity, createSignedEnvelope, splitForChannel } from '@private.me/agent-sdk';

const id = (await generateIdentity()).value!;
const reading = new TextEncoder().encode(JSON.stringify({ temp: 22.5 }));

// Signed-only envelope (no encryption, integrity-only)
const envelope = await createSignedEnvelope({
  senderDid: id.did, recipientDid: gatewayDid,
  scope: 'telemetry', plaintext: reading, privateKey: id.privateKey,
});

// Or split across channels for redundancy
const shares = await splitForChannel(reading, { totalShares: 3, threshold: 2 });

Signed-Only Telemetry

// Gateway accepts both encrypted and signed-only envelopes
const msg = await gateway.receive(envelope, { allowCleartext: true });
if (msg.ok) {
  console.log(msg.value.payload); // works for both modes
}

Security Properties

Seven layers of defense. Each independently verifiable.

Supply Chain Security

Zero npm runtime dependencies. The SDK depends only on workspace packages (@private.me/shared, @private.me/crypto) which are part of the same monorepo. No third-party code executes at runtime. This eliminates the entire class of supply chain attacks from compromised npm packages.

Comparison to Alternatives

Benchmarks

Performance characteristics measured on Node.js 22, Apple M2.

XorIDA vs AES-256-GCM — API Payload Performance

Typical ACI traffic — auth tokens, JSON responses, webhooks, chat messages — is under 1 KB. At these sizes, XorIDA’s simple XOR-only arithmetic completes a full split-and-reconstruct roundtrip 2–11× faster than AES-256-GCM can encrypt-and-decrypt, while providing strictly stronger (information-theoretic) security.

256-Byte Roundtrip — Visual Comparison

Full Comparison — API Payload Sizes

Node.js 22 • 2,000 iterations per size • Median roundtrip (split+reconstruct / encrypt+decrypt)

Xlink vs Competitors — API Crypto Overhead

Full send + receive roundtrip measured end-to-end with real crypto operations. Competitor estimates use our measured primitive timings (same algorithms, same JS runtime) as reference. All columns use Xchange mode (opt-in performance path) for an apples-to-apples comparison; Xlink’s default split-channel adds KEM + per-share encryption (~9ms roundtrip) for three independent security layers.

256-Byte API Payload — Full Roundtrip

Full Comparison — All API Payload Sizes

Node.js 22 • 200 iterations per size • Median send+receive roundtrip • 2-of-3 split

Crypto Overhead as % of Total API Latency (256B)

Xchange mode shown. Default split-channel overhead is higher (~9ms roundtrip). At 10ms+ latency, even split-channel overhead is modest.

Security vs Performance

Ranked by roundtrip speed at 256B. Xlink appears twice: Xchange (opt-in performance mode, single information-theoretic layer) and split-channel default (three independent layers including hybrid PQ KEM).

Honest Limitations

Eight known limitations documented transparently. No product is perfect — here is what Xlink does not do.

Post-Quantum Security

Xlink is end-to-end post-quantum. XorIDA payload splitting is information-theoretically quantum-safe. Key exchange uses hybrid X25519 + ML-KEM-768 (always-on, FIPS 203). Signatures use dual Ed25519 + ML-DSA-65 (opt-in via postQuantumSig: true, FIPS 204). All three cryptographic layers — payload, key exchange, and authentication — have quantum-safe implementations deployed.

Two Security Layers

The Xlink architecture has two distinct cryptographic layers with different quantum profiles:

Migration Strategy

The upgrade follows a three-phase hybrid-first approach. Each phase maintains backward compatibility with the previous one.

Algorithm Profile

Latency Impact

Post-quantum operations add minimal computational overhead. The dominant latency remains network I/O, not cryptography.

Envelope Version

The envelope format uses a v2 version tag signaling hybrid PQ support. Agents negotiate capabilities automatically:

• v1 agents communicate using classical crypto (X25519-only ECDH)
• v2 agents communicate using hybrid PQ + classical crypto (X25519 + ML-KEM-768)
• v2 agents automatically fall back to v1 when communicating with v1 peers
• v3 agents add dual signatures (Ed25519 + ML-DSA-65) — deployed, opt-in via postQuantumSig: true

Protocol Security Stack

The Xlink protocol secures messages at three independent cryptographic layers. Each layer addresses a different threat surface. Together, they provide full-stack quantum safety with no single point of cryptographic failure.

Three-Layer Architecture

Layer 1 — Payload (Information-Theoretic)

XorIDA splits the plaintext into threshold shares using XOR operations over GF(2). Each share is individually indistinguishable from random noise. No computation — classical or quantum — can extract information from fewer than k shares. This is not computational hardness; it is a mathematical proof. The payload layer is immune to harvest-now-decrypt-later attacks because there is no key to break, no structure to exploit, and no algorithm that reduces the problem.

Layer 2 — Key Exchange (Hybrid Post-Quantum KEM)

Session keys are established using a hybrid key encapsulation mechanism: classical X25519 ECDH combined with ML-KEM-768 (FIPS 203, formerly CRYSTALS-Kyber). Both shared secrets are combined via HKDF-SHA256 to derive the session key. The session key is secure as long as either X25519 or ML-KEM-768 remains unbroken — defense in depth. Hybrid KEM is live in v2 envelopes (Phase 1, deployed).

Layer 3 — Authentication (Dual Signatures)

Message authentication and sender identity use dual signatures: classical Ed25519 plus post-quantum ML-DSA-65 (FIPS 204). Both signatures must verify for the message to be accepted. ML-DSA-65 signatures are opt-in via postQuantumSig: true in the agent configuration. When enabled, v3 envelopes carry both signatures. Classical-only agents continue to work with v1/v2 envelopes.

Envelope Version Progression

• v1 — Classical only. X25519 ECDH key exchange, Ed25519 signatures.
• v2 — Hybrid PQ KEM. X25519 + ML-KEM-768 key exchange, Ed25519 signatures. Backward-compatible with v1 peers.
• v3 — Full PQ. Hybrid KEM + dual signatures (Ed25519 + ML-DSA-65). Backward-compatible with v1/v2 peers. Default for split-channel.
• Xchange — Opt-in performance mode. XorIDA key transport replaces KEM. Single security layer (information-theoretic) + Ed25519 authentication. ~180x faster than V3 split-channel. Activated explicitly via xchange: true.

V1, V2, V3 are the version progression. Xchange is a separate opt-in mode, not a version. Agents negotiate capabilities automatically. A v3 agent communicating with a v1 peer falls back to v1 envelope format. No developer action required — the protocol handles version negotiation internally.

Enterprise CLI

Self-hosted identity server. Docker-ready. Air-gapped capable. Port 3300. 73 tests. Part of the Enterprise CLI Suite.

@private.me/xlink-cli provides a production-grade identity management server with full REST API, agent lifecycle operations, trust registry management, and envelope processing. Integrates the complete @private.me/agent-sdk for enterprise M2M deployments.

CLI Commands

# Start the Xlink identity server
xlink serve --port 3300
  → HTTP server on :3300 with agent management + trust registry

# Create a new agent identity
xlink create --name "MyService"
  → Generates Ed25519 + X25519 keypairs, returns DID

# Send an encrypted envelope
xlink send --from "did:key:z6Mk..." --to "did:key:z6Mk..." --payload '{"action":"hello"}'
  → Creates v3 envelope, encrypts, signs, delivers

# Receive and decrypt an envelope
xlink receive --agent "did:key:z6Mk..." --envelope "base64-envelope"
  → Verifies signature, decrypts, validates nonce, returns payload

# Register a DID in trust registry
xlink register --did "did:key:z6Mk..." --name "Production API" --scope "api"
  → Adds to trust registry with scope-based permissions

# Revoke a compromised agent
xlink revoke --did "did:key:z6Mk..." --reason "key_compromise"
  → Marks DID as revoked, future envelopes rejected

# Query trust registry
xlink lookup --did "did:key:z6Mk..."
  → Returns registration status, scopes, metadata

Docker Deployment

# Pull and run the Xlink identity server
docker compose up -d xlink

# Verify health
curl http://localhost:3300/health
# {"status":"ok","version":"0.1.0","uptime":42}

# Air-gapped deployment
docker save private.me/xlink-cli > xlink-cli.tar
# Transfer to air-gapped environment
docker load < xlink-cli.tar
docker compose up -d

Migration from API Keys

Zero-downtime migration. Gradual traffic shifting. Version negotiation. DualModeAdapter for API key + Xlink hybrid deployments.

Migrating from API key-based authentication to Xlink cryptographic identity is a gradual process. The SDK provides a DualModeAdapter that handles both legacy API key requests and modern Xlink envelope requests simultaneously. Traffic shifts progressively from keys to identity over weeks or months, with zero service interruption.

DualModeAdapter Overview

The DualModeAdapter sits at your service boundary and inspects incoming requests. If the request contains a traditional API key (Authorization header, query parameter, or custom header), it routes to your existing authentication logic. If the request contains a Xlink envelope (Content-Type: application/xlink-envelope), it verifies the signature, checks the nonce, and extracts the payload.

import { DualModeAdapter, Agent } from '@private.me/agent-sdk';
import express from 'express';

// Create Xlink agent for your service
const agent = (await Agent.create({
  name: 'ProductionAPI',
  registry, transport
})).value!;

// Initialize DualModeAdapter with legacy key validator
const adapter = new DualModeAdapter({
  agent,
  legacyKeyValidator: async (apiKey) => {
    // Your existing API key validation logic
    const user = await db.users.findOne({ apiKey });
    return user ? { userId: user.id, scopes: user.scopes } : null;
  },
  mode: 'hybrid',  // Accept both keys and Xlink envelopes
});

// Express middleware integration
const app = express();
app.use(adapter.middleware());

app.post('/api/data', async (req, res) => {
  // req.auth contains either legacy user data OR Xlink sender DID
  if (req.auth.mode === 'xlink') {
    console.log(`Request from Xlink DID: ${req.auth.did}`);
  } else {
    console.log(`Legacy API key user: ${req.auth.userId}`);
  }
  res.json({ status: 'ok' });
});

Traffic Shifting Strategy

Migration proceeds in three phases: hybrid mode (both keys and Xlink accepted), deprecation warnings (keys still work but clients receive upgrade prompts), and enforcement (keys rejected, Xlink required). The DualModeAdapter mode parameter controls this progression.

// Week 0-12: Hybrid mode (both accepted)
adapter.setMode('hybrid');

// Week 12-20: Deprecation warnings
adapter.setMode('deprecation');
// API key requests receive X-Deprecated-Auth: "true" header
// Response includes upgrade instructions in X-Migration-Url

// Week 20+: Xlink enforcement
adapter.setMode('xlink-only');
// API key requests return 401 with migration guide URL

Monitor Xlink adoption via adapter.getMetrics(). Once 95%+ of traffic uses Xlink (typically 8-12 weeks in hybrid mode), activate deprecation warnings. After another 4-8 weeks, enforce Xlink-only mode. Adjust timelines based on your client base and communication channels.

Version Negotiation

Xlink envelope versions (v1, v2, v3, Xchange) auto-negotiate based on sender and receiver capabilities. Agents inspect the recipient's registered keys in the trust registry and select the highest mutually supported version. No manual configuration required.

// Agent A: v3-capable (Ed25519 + X25519 + ML-KEM + ML-DSA)
const agentA = (await Agent.create({
  name: 'ServiceA',
  registry, transport,
  postQuantumSig: true,  // Enables ML-DSA-65
})).value!;

// Agent B: v2-capable (no ML-DSA support)
const agentB = (await Agent.create({
  name: 'ServiceB',
  registry, transport,
  postQuantumSig: false,  // Only Ed25519 signatures
})).value!;

// When A sends to B, SDK auto-negotiates to v2
await agentA.send({ to: agentB.did, payload: data });
// Uses v2 envelope (ML-KEM-768 + Ed25519, no ML-DSA)

// When A sends to another v3 agent, SDK uses v3
await agentA.send({ to: v3RecipientDid, payload: data });
// Uses v3 envelope (ML-KEM-768 + Ed25519 + ML-DSA-65)

Zero-Downtime Cutover Procedure

The recommended deployment pattern uses a phased rollout with canary testing and incremental traffic shifting. This procedure assumes a load-balanced multi-instance deployment behind a reverse proxy or API gateway.

# Load balancer config (example: nginx upstream weights)
upstream api_backend {
  server instance1.internal:3000 weight=19;  # Legacy (95%)
  server instance2.internal:3000 weight=1;   # Canary DualMode (5%)
}

# Week 1: 10% DualMode
weight=18 (legacy), weight=2 (DualMode)

# Week 2: 25% DualMode
weight=15 (legacy), weight=5 (DualMode)

# Week 3: 50% DualMode
weight=10 (legacy), weight=10 (DualMode)

# Week 4: 100% DualMode (all instances)
all instances running DualModeAdapter in hybrid mode

Monitoring & Metrics

DualModeAdapter exposes real-time metrics for tracking migration progress and identifying adoption blockers.

const metrics = adapter.getMetrics();

console.log(metrics);
// {
//   totalRequests: 142850,
//   xlinkRequests: 98420,
//   apiKeyRequests: 44430,
//   xlinkPercentage: 68.9,
//   failedAuth: 47,
//   avgLatencyMs: { xlink: 12.4, apiKey: 8.7 }
// }

// Export to monitoring system
setInterval(() => {
  const m = adapter.getMetrics();
  prometheus.gauge('xlink_adoption_pct').set(m.xlinkPercentage);
  prometheus.counter('xlink_requests_total').inc(m.xlinkRequests);
}, 60000);

Track the xlinkPercentage metric daily. A healthy migration shows steady week-over-week growth: 10% → 25% → 45% → 65% → 85% → 95%. If growth stalls, investigate client-side integration blockers (SDK confusion, documentation gaps, support tickets).

Error Hierarchy

Typed error classes for structured error handling. Supplementary to the Result<T,E> string code pattern.

XlinkError                    // Base class (code, subCode, docUrl)
  ├── XlinkIdentityError       // Ed25519/X25519 keygen, sign, verify, DID
  ├── XlinkEnvelopeError       // Envelope create, encrypt, decrypt, parse
  ├── XlinkTransportError      // Send failures, network, timeouts
  ├── XlinkRegistryError       // Lookup, registration, revocation
  ├── XlinkKeyAgreementError   // X25519 ECDH derivation
  ├── XlinkSplitChannelError   // XorIDA split, reconstruct, HMAC
  └── XlinkAgentError          // High-level Agent lifecycle

import { toXlinkError, isXlinkError } from '@private.me/agent-sdk';

const result = await agent.receive(envelope);
if (!result.ok) {
  const err = toXlinkError(result.error);
  console.log(err.code);     // 'DECRYPT_FAILED'
  console.log(err.subCode);  // 'KEY_AGREEMENT'
  console.log(err.docUrl);   // 'https://xail.io/docs/packages/xlink#envelope'
  console.log(err.name);     // 'XlinkEnvelopeError'
}

Trust Registry

Four implementations covering development through production.

Production Persistence with FileTrustRegistry

For production single-node deployments, FileTrustRegistry provides persistent JSONL-based storage with automatic crash recovery. All operations append to an immutable log, replayed into memory on initialization.

import { Agent, FileTrustRegistry, HttpsTransportAdapter } from '@private.me/agent-sdk';

// JSONL file persists across restarts
const registry = new FileTrustRegistry({ path: '/opt/app/trust.jsonl' });
const transport = new HttpsTransportAdapter({ baseUrl: 'https://api.example.com' });

const agent = (await Agent.create({ name: 'ProductionService', registry, transport })).value!;

// Registry automatically persists all add/update/remove operations
// Survives process restarts, crashes, and power failures

Enterprise Multi-Backend Factory

For enterprise deployments requiring centralized trust management with local fallback, createEnterpriseTrustRegistry() provides a factory function that combines HTTP primary + File fallback in a single interface.

import { createEnterpriseTrustRegistry } from '@private.me/agent-sdk';

// Primary: centralized HTTP registry
// Fallback: local JSONL file when HTTP unreachable
const registry = createEnterpriseTrustRegistry({
  http: { baseUrl: 'https://trust.corp.example.com', authToken: process.env.TRUST_TOKEN },
  file: { path: '/var/lib/trust-fallback.jsonl' }
});

// Reads try HTTP first, fall back to file on network failure
// Writes go to both backends for redundancy

Nonce Store & Anti-Replay Protection

Replay prevention via unique nonce tracking. Every envelope carries a cryptographically random 16-byte nonce generated via crypto.getRandomValues().

Nonce-Based Replay Attack Prevention

A nonce (number used once) is a cryptographic value that ties each envelope to a single use. When an envelope arrives, the receiver checks whether its nonce has been seen before. If the nonce exists in the store, the envelope is rejected with REPLAY_DETECTED — preventing an attacker from capturing a valid envelope and re-sending it to execute the same action twice. This pattern is based on established cryptographic nonce practices used in OAuth 2.0, OIDC, and blockchain protocols.

Implementation Options

import { RedisNonceStore } from '@private.me/agent-sdk';
import Redis from 'ioredis';

const redis = new Redis({ host: 'redis.example.com' });

const nonceStore = new RedisNonceStore({
  client: redis,
  ttlSeconds: 600,        // 10 minutes (default)
  keyPrefix: 'nonce:',     // Redis key namespace
});

const agent = await Agent.create({
  name: 'DistributedAgent',
  registry, transport,
  nonceStore,              // Cross-node protection
});

Production deployments should use RedisNonceStore or an equivalent distributed store. Memory-based stores clear on process restart, allowing replay attacks within the timestamp window until the TTL expires. Redis provides atomic SET NX EX semantics, ensuring that even under high concurrency, a nonce is either accepted once or rejected as a duplicate — no race conditions.

Transport Adapters

Pluggable delivery mechanism. Two built-in adapters plus a custom interface.

interface XailTransportAdapter {
  send(envelope: TransportEnvelope, to: string): Promise<Result<void, TransportError>>;
  onReceive(handler: (envelope: TransportEnvelope) => void): void;
  dispose(): void;
}

Full ACI Surface

Complete Authenticated Cryptographic Interface organized by module.

Agent

Identity

Envelope

Split-Channel

Key Agreement

Error Taxonomy

Complete error code table with sub-codes and error classes.

Codebase Stats

Xlink v0.1.0 — Gold Standard Bronze tier achieved.

Module Inventory