Replace any API connection in minutes

Getting Started

Complete setup in under 2 minutes. Install the package, verify your email, and start sending authenticated messages with cryptographic identity.

Step 1: Install Package

# Node.js / TypeScript
npm install @private.me/xbind

# Python
pip install private-me-xbind

Step 2: Email Verification (At 100K Operations)

Your first 100,000 operations are free — no email, no credit card. Email verification is required at 100K operations to unlock the recurring free tier. This links your usage to a verified contact for security notifications and billing.

npx xbind setup

What happens:

• Enter your email address
• Receive 6-digit verification code (check spam folder)
• Enter code to activate account
• DeploymentID generated (persistent economic identity)

Step 3: Create Agent & Send Messages

import { Agent } from '@private.me/xbind';

// Create agent (auto-generates cryptographic identity)
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 4: Understand Your Free Tier

• Generous free tier — See pricing details
• Grace buffer included for usage overages
• Monthly reset: 1st of each month at 00:00 UTC
• Milestone emails: Sent at usage milestones

At free tier limit: Email verification enforced (if not already verified)

What's New in v3.2.0

Eight major features for enterprise agent orchestration, compliance, and IP protection. 200+ new tests (4,001 total passing). Full Control activated.

Previous: v3.1.x Fixes

Eight customer-driven improvements based on independent production testing. Resolved two P0 blockers, added backward-compatible APIs, and enhanced developer experience.

P0 Blocker #1: ESM Import & Optional Dependencies

Problem: Users importing xBind in ESM projects encountered runtime errors when optional peer dependencies (bonjour-service, nodemailer) were not installed, even if those features weren't being used.

Solution: Implemented lazy loading for all optional features using dynamic import(). Dependencies are only loaded when you call specific functions:

• mDNS discovery — Requires bonjour-service only when calling agent.discover()
• Email invitations — Requires nodemailer only when calling agent.sendInvite()

// If you call discover() without bonjour-service:
Error: mDNS discovery requires 'bonjour-service'
Install: npm install bonjour-service

// If you call sendInvite() without nodemailer:
Error: Email invitations require 'nodemailer'
Install: npm install nodemailer

Impact: Core xBind functionality (Agent.quickstart(), send(), receive()) works without any peer dependencies. Optional features fail gracefully with clear installation instructions.

P0 Blocker #2: CommonJS CLI Support

Problem: The xbind-init CLI command was missing from the npm package, preventing users from running setup in CommonJS projects.

Solution: Added cli/init.js to package files, now available via three equivalent commands:

npx xbind setup
npx xbind-init
npx xbind-onboard

Impact: Email verification setup now works in all project types (ESM, CommonJS, TypeScript).

Issue #1: Backward-Compatible transport.outbox API

Problem: Documentation showed transport.outbox[0] but actual API was transport.sent[0]?.envelope, causing confusion for users migrating from earlier versions.

Solution: Added backward-compatible .outbox getter that maps to .sent[].envelope internally. Both APIs now work:

import { LoopbackTransport } from '@private.me/xbind';

const transport = new LoopbackTransport();

// New API (recommended): Direct array access
const envelope1 = transport.sent[0]?.envelope;

// Legacy API (backward-compatible): Getter property
const envelope2 = transport.outbox[0];

// Both return the same envelope
console.assert(envelope1 === envelope2);

Technical implementation: The .outbox getter is implemented as a computed property that extracts envelopes from the .sent array on-the-fly. No data duplication, zero performance overhead.

Issue #2: Enhanced send() Return Type

Problem: agent.send() returned Result<void, string>, providing no metadata about successful sends (no envelope ID, timestamp, or recipient confirmation).

Solution: Upgraded return type to Result<AgentSendResult, string> with detailed send metadata:

interface AgentSendResult {
  /** Unique envelope identifier (16-char base64url) */
  readonly envelopeId: string;

  /** Send timestamp (Unix milliseconds) */
  readonly timestamp: number;

  /** Recipient DID */
  readonly recipientDid: string;
}

const result = await agent.send({
  to: recipientDid,
  payload: { action: 'createOrder', items: [...] },
  scope: 'orders'
});

if (result.ok) {
  // Access detailed send metadata
  console.log('Envelope ID:', result.value.envelopeId);
  console.log('Sent to:', result.value.recipientDid);
  console.log('Timestamp:', new Date(result.value.timestamp));

  // Store envelope ID for audit logs
  await db.logTransaction({
    envelopeId: result.value.envelopeId,
    timestamp: result.value.timestamp,
    recipient: result.value.recipientDid
  });
}

EnvelopeId format: 16-character base64url string (e.g., k7Jx3mP9qR2wL4nT), generated from cryptographic envelope signature. Globally unique, collision-resistant.

Backward compatibility: Existing code checking result.ok continues to work—metadata is additive, not breaking.

Issue #4: receiveScopes Configuration

Problem: Agents received all messages regardless of authorization scope, requiring manual filtering in application code. No built-in protection against out-of-scope messages.

Solution: Added receiveScopes configuration to Agent constructor for scope-based message filtering:

const agent = await Agent.quickstart({
  name: 'payment-processor',
  // Only accept messages with 'payments' or 'refunds' scope
  receiveScopes: ['payments', 'refunds']
});

// Messages with scope='chat' will be rejected with SCOPE_DENIED
const result = await agent.receive(chatEnvelope);
if (!result.ok) {
  console.error(result.error); // 'SCOPE_DENIED'
}

Performance optimization: Scope checking happens BEFORE decryption, providing a fast rejection path for unauthorized messages (~0.1ms vs ~10ms for full decryption).

Error details: When scope is denied, the error includes:

• code: SCOPE_DENIED
• message: "Message scope 'X' not in agent's receiveScopes"
• hint: Lists allowed scopes for debugging

const result = await agent.receive(envelope);
if (!result.ok && result.error === 'SCOPE_DENIED') {
  // Extract scope from error metadata (if you enhanced error handling)
  console.error('Rejected message with unauthorized scope');
  // Allowed scopes: ['payments', 'refunds']
}

Default behavior: If receiveScopes is not specified, all scopes are accepted (backward-compatible).

Issue #5: Fixed Spurious Split-Channel Warning

Problem: Users reported seeing "Split-channel mode activated" warnings in logs even when using standard encrypted transport (not XorIDA high-security mode).

Solution: Fixed conditional logic in transport layer to only emit warnings when security: 'high' is explicitly set or auto-detected (high-value transfers, admin operations).

Impact: Cleaner logs for 90% of users who run on default security mode. Split-channel warnings now accurately reflect XorIDA activation.

Minor: VERSION Export

Added VERSION constant to public API for programmatic version checking:

import { VERSION } from '@private.me/xbind';

console.log(`xBind v${VERSION}`);  // "xBind v3.2.0"

// Useful for telemetry, support tickets, version compatibility checks
if (VERSION < '3.1.0') {
  console.warn('Please upgrade to xBind 3.1+ for receiveScopes support');
}

Minor: llms.txt Corrections

Fixed outdated ACI count and feature descriptions in llms.txt (AI agent discovery file). Now accurately reflects 224 ACIs, current pricing tiers, and authentication methods.

Try It Live

Explore xBind's identity, signing, encryption, and trust features in an interactive browser playground — no server, no signup, no keys.

Deployment Identity & Billing

xBind includes persistent economic identity (DeploymentID) to prevent quota bypass attacks while maintaining cryptographic security. This architecture separates authentication identity (DID) from billing identity (DeploymentID).

DID vs DeploymentID Model

xBind uses a dual identity architecture: DIDs (Decentralized Identifiers) for message authentication, and DeploymentIDs for persistent economic tracking.

Email Verification (At 100K Operations)

First 100K operations are free with no email required. At 100K operations, email verification is required to unlock the recurring free tier. Verification creates your DeploymentID and links usage to a verified contact for security notifications. Over 100K/month requires a credit card (Pro tier, $5 per 100K ops).

CLI Setup (Recommended)

npx xbind setup --email user@example.com

# Interactive prompts:
# 1. Enter email address
# 2. Receive 6-digit code (check spam folder)
# 3. Enter code to verify
# 4. DeploymentID generated (DEP-202605-A3F2B9C1E7)
# 5. Identity saved to ~/.xbind/identity.json (chmod 600)

Web-Based Verification (Magic Link)

For web apps and browser environments, email verification uses passwordless magic links:

// 1. User enters email on signup page
// 2. Server sends magic link (15-min expiry, one-time use)
// 3. User clicks link → email verified → DeploymentID created
// 4. Redirected to dashboard, API calls unblocked

Identity Verification & Privacy

xBind uses a Deployment Root Key (DRK) — a customer-held Ed25519 keypair — as the cryptographic trust anchor for each deployment. The private key is generated client-side and never leaves the customer's environment, providing non-spoofable identity verification without covert device surveillance.

How It Works

• Key generation: Ed25519 keypair created locally via Web Crypto API — private key never transmitted
• DRP verification: 6-point Deployment Root Protocol chain (signature presence, root DID format, registry registration, revocation status, expiry, Ed25519 binding)
• Key rotation: Automatic rotation with cryptographic continuity — old key signs endorsement of new key
• Persistence: Pluggable RootKeyStore interface (memory, filesystem, or custom backends)

Privacy by Design

• No covert collection: No browser fingerprinting, no device signal harvesting, no canvas hashing
• Customer-controlled: You generate and hold the private key — we only see the public key
• GDPR by design: No PII collected, no tracking signals, no behavioral profiling
• Transparent: Full source code in packages/xbind/src/deployment-root-key.ts

Progressive Offline Warnings

If your deployment stops syncing (offline for extended period), xBind sends progressive email warnings before enforcing failsafe mode:

Emergency Override (3-Layer Backup)

Cannot sync your device? Emergency override system provides 3 backup channels for critical deployments blocked by connectivity issues:

npx xbind override --code XXXXXX

# Temporarily lifts failsafe mode (48 hours)
# Full quota restored during override period
# Auto-reverts to failsafe after expiry

Auto-Registration (JITR)

Agent.fromSeed() includes automatic trust registry registration following industry standards (AWS IoT JITR, OAuth DCR, MCP 2025). No manual registration required.

Zero-Config Onboarding

Just-In-Time Registration (JITR) automatically registers all cryptographic keys with the trust registry on first use:

import { Agent, TrustRegistry } from '@private.me/xbind';

const registry = new TrustRegistry({ endpoint: 'https://private.me' });
const seed = crypto.getRandomValues(new Uint8Array(32));

// Automatic registration on creation
const agent = await Agent.fromSeed(seed, {
  name: 'iot-device-1',
  registry,
  transport: httpTransport
});

// Agent is immediately ready to use
// No manual registration required
const result = await agent.send({
  to: 'did:key:z6Mk...',
  payload: { temperature: 22.5 },
  scope: 'telemetry'
});

What Gets Registered

• Ed25519 — Signing key (32 bytes public key)
• X25519 — Encryption key for KEY_AGREEMENT (32 bytes)
• ML-KEM-768 — Post-quantum encryption (1,184 bytes public key)
• ML-DSA-65 — Post-quantum signatures (1,952 bytes public key)
• Scopes — Authorization permissions (e.g., ['*'] or ['telemetry', 'control'])

Key Features

Industry Standards

JITR follows established patterns from:

• AWS IoT JITR — Devices auto-register certificates on first connection
• OAuth DCR (RFC 7591) — Clients self-register at runtime
• MCP 2025 — Agentic self-onboarding without human intervention

Bilateral Authorization (Pro Tier)

Defense-in-depth security where both sender and receiver independently validate scopes — even if one side is compromised, the other side blocks unauthorized operations.

Traditional APIs enforce authorization server-side only. If the server is compromised or misconfigured, it may accept requests with elevated scopes. xBind's bilateral authorization adds receiver-side scope validation as a second layer of defense.

The scopes parameter defines which scopes a receiver will accept. When a message arrives, the receiver validates that the sender's scope is within the allowed set — independent of what the sender claims or what the trust registry permits. This prevents scope escalation attacks and limits blast radius if sender credentials are compromised.

import { Agent } from '@private.me/xbind';

// Payment processor restricts incoming scopes to payment operations only
const processor = await Agent.create({
  registry,
  transport,
  scopes: ['payment:process', 'payment:refund']
});

// If sender tries to send 'admin:config' scope, receiver rejects it
// even if sender has that scope in the trust registry
const result = await processor.receive();
if (!result.ok) {
  console.error('Rejected: scope not in scopes allowlist');
}

Defense-in-depth benefit: Even if an attacker compromises the sender's credentials or the trust registry itself, they cannot execute operations outside the receiver's scopes allowlist. The receiver enforces its own security policy independently.

This pattern is especially valuable in multi-tenant environments, regulated industries (healthcare, finance), and IoT deployments where devices must reject commands outside their operational scope.

Same Topologies. Different Identity Models.

When developers first encounter xBind, a reasonable assumption is that ACIs enable architectures that APIs cannot. That assumption is incorrect, and stating it that way would be marketing rather than engineering. APIs over HTTP are remarkably flexible — they support every connection topology a distributed system needs. The actual difference between APIs and ACIs is not what they can connect, but how they prove who is connecting.

Connection Topologies

Both APIs and ACIs support the four canonical patterns that distributed systems depend on:

• Point-to-point (1-to-1). A single client communicates with a single service. An application calls a payment processor; an agent queries a model-serving endpoint.
• Hub-and-spoke (1-to-N). A single source distributes requests across many destinations. An orchestrator dispatches work to a pool of workers; a gateway authenticates against a set of internal services.
• Fan-in (N-to-1). Many sources converge on a single destination. A fleet of edge devices reports telemetry to a central aggregator; multiple agents log activity to a shared audit sink.
• Mesh (N-to-N). Every participant can communicate with every other participant. A swarm of autonomous agents coordinates peer-to-peer; a microservice fabric authenticates between every pair of services.

xBind imposes no topological constraint that APIs do not also satisfy. A 200-service mesh authenticated by API keys is operationally feasible. A 200-service mesh authenticated by ACIs is also operationally feasible. Topology, in itself, is not the differentiator.

Identity is the Differentiator

The substantive difference between APIs and ACIs becomes visible once a system scales beyond a single connection.

How APIs Handle Multi-Party Authentication

Authenticating one machine to one service is straightforward in the API model: the client presents a bearer credential — an API key, an OAuth token, an mTLS certificate — and the server validates it against a stored reference. The model is well-understood and works well at this scale.

The model becomes operationally costly as the number of authenticating parties grows.

A system of 100 services, each authenticating to the other 99, needs some discipline about how credentials are issued and managed. The discipline takes one of four forms:

• Shared credential across all parties. One key, distributed everywhere. Operationally simple. The cost is that compromise anywhere is compromise everywhere — there is no way to attribute a request to a specific service or revoke a single party's access without rotating the credential for all parties simultaneously.
• Per-pair credentials. Each service holds a distinct key for each peer. A 100-service mesh requires up to 9,900 credentials to provision, distribute, rotate, and revoke. The credentials live in environment variables, secrets managers, configuration files, container images, and CI/CD pipelines. Each storage location is an attack surface, and rotation at this scale is rarely performed on schedule because the operational cost is high.
• Centralized authorization server. A protocol such as OAuth 2.0 client-credentials issues short-lived tokens from a central server. The number of stored secrets is reduced to one per service. The trade-off is that the authorization server becomes a point of coordination — every authenticating party depends on its availability — and the bearer-secret model itself is preserved. Tokens still leak; rotation of the underlying secrets is still operationally heavy.
• Mutual TLS with per-service certificates. Each service holds an X.509 certificate signed by an internal certificate authority. Authentication is bound to the connection rather than to individual messages, and certificate distribution, rotation, and revocation become a product in their own right. Service mesh implementations such as Istio, Linkerd, and SPIFFE/SPIRE exist to manage exactly this complexity.

Each of these approaches works. Each carries a continuous operational cost that scales with the number of parties and the rate of change in the system.

How ACIs Handle Multi-Party Authentication

An ACI has a single property that changes the model: each ACI possesses its own keypair, and that keypair is its identity. The decentralized identifier (DID) derived from the public key is the identity. There is no separate credential to provision, distribute, or rotate.

A 100-service mesh authenticated by ACIs has 100 keypairs, one per service. There are no additional secrets, because the public keys are not secrets. There are no per-pair credentials, because authentication is performed by signing each message with the sender's private key and verifying it with the sender's published public key. There is no central authorization server, because verification requires only the message, the signature, and the public key — all of which the verifier can obtain locally.

The shift is from bearer-secret authentication (proving identity by possessing a shared secret) to cryptographic-proof authentication (proving identity by demonstrating control of a private key without revealing it). The protocol that emerges from this shift is structurally simpler at scale, because the operational cost of bearer-secret management — provisioning, distribution, rotation, revocation — does not exist.

The topology rows are identical. Every other row reflects the difference in identity model.

A Note on Service Meshes

A reasonable question from any platform engineer running production infrastructure: if my service mesh already provides workload identity, what is xBind doing that Istio with SPIRE doesn't already do?

The honest answer is that xBind and a SPIFFE-based service mesh operate at different layers of the stack and solve overlapping but distinct problems. They are complementary in most architectures, not competitive.

Where Service Meshes Excel

A service mesh — Istio, Linkerd, Cilium, or any equivalent — provides identity at the connection layer, typically through an Envoy sidecar that terminates mTLS on behalf of the workload. SPIFFE/SPIRE, the standard identity framework adopted by these meshes, issues SVIDs (SPIFFE Verifiable Identity Documents) as X.509 certificates or JWTs scoped to a SPIFFE ID of the form spiffe://<trust-domain>/ns/<namespace>/sa/<service-account>.

This model works exceptionally well for what it was designed to do: authenticating Kubernetes workloads to each other within a cluster, enforcing network policy at the connection level, managing certificate rotation transparently to the application, providing a unified identity plane across multiple clusters and clouds, and federating trust between organizations through SPIFFE Federation.

If a platform engineer has Istio with SPIRE running smoothly, they have solved a real problem and they should keep that infrastructure. xBind is not a replacement for it.

Where the Layers Differ

The differences become relevant when authentication needs extend beyond what a connection-layer mesh provides:

• Granularity. A service mesh authenticates the connection. Once two workloads have established mTLS, the application code on either side does not see — and cannot enforce — per-message identity. xBind authenticates each message, so the application receives a verified sender identity on every call, not just on session establishment.
• Bearer credentials. SPIFFE SVIDs are still bearer credentials. An X.509 SVID with a one-hour TTL is shorter-lived than a typical API key but operates on the same model: possession of the document grants the bearer the identity it encodes. xBind ACIs replace the bearer-credential model with proof-of-private-key-possession on every message. There is no document to steal, because the private key never crosses the network.
• Reach. Service meshes are scoped to infrastructure under the operator's control — Kubernetes clusters, VMs, sometimes federated peer organizations. ACIs are designed to extend identity beyond the operator's infrastructure boundary: to AI agents running on customer hardware, to IoT devices in the field, to partners and counterparties whose infrastructure the operator cannot configure. The trust registry is the coordination layer, not a service mesh control plane.
• Cross-protocol authentication. A service mesh authenticates connections that the mesh itself routes — typically HTTP, gRPC, and TCP within the data plane. ACI authentication is bound to the message rather than the transport, so the same identity proof remains valid as a request crosses from HTTP to a message queue to an event stream to a gRPC bridge. Re-authentication at protocol boundaries is not required.
• Operational footprint. A production SPIRE deployment requires a highly available SPIRE server with a backing datastore, agent DaemonSets on every node, careful trust-domain naming, and registration entries for every workload. The xBind trust registry is a simpler artifact — public keys and capability sets, with no certificate authority, no rotation schedule, and no central datastore on the verification path.

A Combined Deployment

In practice, the two layers can compose. A workload inside a service mesh can hold both an SVID (issued by SPIRE, used for connection-layer mTLS within the mesh) and an ACI (used for message-layer authentication that extends beyond the mesh). The SVID protects the network channel; the ACI protects the message contents and identifies the sender to the application.

Engineers familiar with SPIFFE will recognize a useful analogy: a SPIFFE ID identifies where a workload runs (trust domain, namespace, service account); an ACI's DID identifies what cryptographic identity a workload possesses, independent of where it runs. The two are orthogonal, and both can be true of the same workload at the same time.

What This Means in Practice

The framing for engineers evaluating xBind is not that ACIs unlock architectures their APIs cannot reach. It is that ACIs let them build the architectures they are already building — agent fleets, service meshes, IoT deployments, multi-region distributed systems — without the operational tax of bearer-secret management.

A platform engineer running 200 services on Kubernetes already has mesh topology. The question is whether the authentication layer is an asset or a liability. With API keys, it is a continuous source of operational work and a recurring source of security incidents. With ACIs, it is a property of the identity model itself — emergent rather than maintained.

This is the substance of the platform tagline. APIs have keys. ACIs have identity. The first is a thing you possess and must protect. The second is a thing you are.

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/xbind';

// 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',
  // Optional: security: 'standard' | 'high' | 'critical' (defaults to 'standard')
});

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

// Bob receives and verifies the message
const { envelope } = transport.sent[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.sent[1]!.envelope);
console.log(`Bob says: ${reply.value.payload.text}`);
// Bob says: Hi Alice!

await alice.send({
  to: bob.did,
  payload: { amount: 50, currency: 'BTC' },
  security: 'high',  // Requires 3+ transports
});

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

xBind 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

xBind 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

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

Authorization Errors (New in v3.2.0)

The SCOPE_DENIED error occurs when an agent attempts to receive a message with a scope not in its receiveScopes configuration. This provides application-level authorization on top of cryptographic authentication.

const agent = await Agent.quickstart({
  name: 'payment-processor',
  receiveScopes: ['payments', 'refunds']  // Only accept these scopes
});

// Attempt to receive message with unauthorized scope
const result = await agent.receive(envelope);

if (!result.ok) {
  if (result.error === 'SCOPE_DENIED') {
    // Fast rejection (checked before decryption, ~0.1ms)
    console.error('Message rejected: unauthorized scope');
    // Log security event, notify admin, etc.
  } else {
    // Handle other errors (ENVELOPE_DECRYPTION_FAILED, etc.)
    console.error(`Receive failed: ${result.error}`);
  }
}

Performance characteristic: Scope validation happens before cryptographic operations, providing a fast-path rejection for unauthorized messages (~0.1ms vs ~10ms for full envelope decryption).

Use cases:

• Separation of concerns — Payment processors only accept 'payments', chat services only accept 'chat'
• Defense in depth — Even if an attacker compromises transport layer, they can't inject out-of-scope messages
• Compliance — Enforces authorization boundaries required by SOC 2, ISO 27001, HIPAA

Three Paths to Production

xBind 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, xBind 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 xBind 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
XBIND_INVITE_CODE=XLK-abc123def456

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

// 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 (xbind-onboard is an alias)
$ npx xbind-init --invite XLK-abc123def456
# OR
$ npx xbind-onboard --invite XLK-abc123def456

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

 Generated identity: did:key:z6MksZP8ChwZYSNgozYq...
 Configured trust registry
 Created src/xbind-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 xBind 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/xbind-infra/actions)

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

// Outputs after 10 minutes:
{
  "service_url": "https://xbind.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 xBind using DualModeAdapter — runs xBind in parallel with your existing API, shifts traffic gradually, and deprecates the API when ready.

// Step 1: Deploy xBind alongside existing API (no downtime)
const { DualModeAdapter } = require('@private.me/xbind');

const adapter = new DualModeAdapter({
  xbind: agent,
  fallback: {
    type: 'api-key',
    key: process.env.API_KEY,
    url: 'https://api.legacy.com'
  }
});

// Step 2: Try xBind first, fall back to API if needed
const result = await adapter.call('createCharge', { amount: 100 });

// Step 3: Monitor usage metrics
const metrics = adapter.getMetrics();
// { xbindPercentage: 85, fallbackPercentage: 15 }

// Step 4: Remove fallback when xBind proves stable
// adapter.fallback = null;

Migration time: Days to weeks (gradual adoption)
Downtime: Zero (automatic fallback)
Rollback: Instant (adapter uses API key if xBind fails)
Implementation: DualModeAdapter built into @private.me/xbind

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 DualModeAdapter to run xBind parallel with fallback to API key, shift traffic gradually as xBind proves stable. Zero downtime.
3. Deploying across an organization? → Enterprise Path — Configure trust registry, policies, and audit once. All services inherit org-wide governance automatically.

Entity-to-Entity Connection Models

xBind provides four distinct connection models to accommodate different deployment scenarios. Each model offers a different trade-off between security, user experience, and operational complexity. All four models are cryptographically sound and production-ready—the choice depends on your specific use case.

Model 1: Invite Code (Email-Based Onboarding)

Use case: Customer onboarding, viral growth, B2C applications
Security: Medium (single-use codes, time-limited)
UX: Low friction (familiar 6-character code entry)

// Vendor generates invite code for customer
const invite = await xBind.createInvite({
  vendorServer: 'https://vendor.com',
  scope: 'full-control:share2',
  customerEmail: 'customer@example.com',
  expiryHours: 24
});

// Returns: { inviteCode: "INVITE-A1B2C3", inviteUrl, expiresAt }
// Email automatically sent to customer with invite link

// Customer accepts invite (separate device)
const connection = await xBind.acceptInvite({
  inviteCode: 'INVITE-A1B2C3',
  customerDid: 'did:key:z6Mk...',
  customerPublicKey
});

// Returns: { connectionId, vendorDid, vendorPublicKey, scope }
// Trust registry updated bidirectionally

How it works: Vendor generates a 6-character code (format: INVITE-XXXXXX, 2.1 billion combinations). Email delivered automatically with branded template. Customer clicks link, enters code, connection established. Code is single-use and expires after 24 hours (configurable). Trust registry stores the connection with specified scopes.

Model 2: QR Code (Physical Proximity Pairing)

Use case: Mobile/desktop device pairing, physical security contexts
Security: High (physical proximity required, 60-second expiry)
UX: Minimal friction (scan and confirm)

// Desktop generates QR code (auto-refreshes every 60s)
const { qrDataUrl, nonce, expiresAt } = await generatePairingQR(desktopDid);

// Mobile scans QR code
const payload = parsePairingQR(scannedData);
// Validates: { desktopDid, nonce, timestamp, action: 'device-pairing' }
// Checks expiry (60-second window)

// Mobile confirms pairing (sends to backend)
const result = await fetch('/gateway/pair', {
  method: 'POST',
  body: JSON.stringify({ desktopDid, mobileDid, nonce })
});

// Backend validates nonce (single-use, prevents replay attacks)
// Trust registry updated bidirectionally with 'device:sync' scope

How it works: Desktop displays QR code containing DID + cryptographically secure nonce + timestamp. QR refreshes every 60 seconds automatically. Mobile scans, shows confirmation dialog with device details, user taps "Pair". Nonce validated by backend (single-use, 60-second TTL). Vibration feedback on successful scan (mobile only). Both devices immediately trust each other in their respective trust registries.

Model 3: Trust Registry (Pre-Authorized Enterprise)

Use case: Enterprise deployment, CI/CD automation, zero-UX scenarios
Security: Highest (admin pre-authorization, scope-limited)
UX: Zero (fully automated, no user interaction)

// Admin pre-authorizes DID in trust registry (one-time setup)
await registry.register(
  'did:key:z6Mk...agentDid',
  agentPublicKey,
  ['write:data', 'read:analytics']  // Scope-limited permissions
);

// Agent auto-connects (no user interaction needed)
const connection = await xBind.connect({
  serverUrl: 'https://api.example.com',
  did: 'did:key:z6Mk...agentDid',
  privateKey: agentPrivateKey  // From secure storage (OS keychain)
});

// Connection succeeds immediately (no invite, no QR, no prompt)
// Server validates signature, checks trust registry, applies scopes

How it works: Enterprise admin pre-populates trust registry with authorized DIDs and their scopes. Agents connect automatically on startup—no manual pairing step. Server validates cryptographic signature against trust registry. Scopes enforce least-privilege access (e.g., CI agent can read but not write production data). Instant revocation via registry update (no key rotation needed). Perfect for GitLab CI, Kubernetes deployments, scheduled jobs.

Model 4: Peer Discovery (mDNS Local Network)

Use case: IoT devices, local network pairing, offline scenarios
Security: Medium (physical network proximity, user confirmation)
UX: Low friction (scan for devices, tap to pair)

// Device A advertises service on local network (mDNS)
const manager = new MdnsDiscoveryManager();
manager.advertise('Desktop', 'did:key:z6MkA...', 58472);
// Service: _privateme._tcp.local (RFC 6763 compliant)

// Device B scans local network (5-second timeout)
const devices = await manager.scan('did:key:z6MkB...', 5000);
// Returns: [{ name: 'Desktop', did: 'did:key:z6MkA...', endpoint, addresses }]

// Device B initiates pairing (sends challenge)
const pairingMgr = new PairingManager('did:key:z6MkB...', registry);
const request = pairingMgr.createRequest();  // Generates 16-byte nonce

const response = await fetch(`${device.endpoint}/pair`, {
  method: 'POST',
  body: JSON.stringify(request)
});

// Device A shows prompt: "Device B wants to pair. Accept?"
// User confirms → response includes nonce echo + acceptance

// Device B finalizes pairing (validates nonce echo)
await pairingMgr.finalizePairing(response, request.nonce);
// Trust registry updated bidirectionally

How it works: Devices broadcast mDNS announcements with DID + HTTP endpoint. 5-second scan discovers all Private.Me devices on same LAN. Initiator sends challenge with cryptographically secure nonce. Responder shows confirmation prompt with initiator's DID. On acceptance, nonce echoed back (prevents MITM substitution). 60-second timeout limits attack window. Both devices store pairing in trust registry with 'pairing' scope. No internet connection required—works entirely on local network.

Cascading Failure Elimination

Critical Failure #1: Secret Sprawl

Before you can leak a key, you have to store it. API keys exist in dozens of locations across every deployment: .env files, CI/CD secrets, developer laptops, Kubernetes manifests, Docker images, team chat messages, documentation, git history. Each copy is an attack surface.

The real cost pattern: One developer commits a .env file to GitHub (happens thousands of times daily). That key was copied to staging, production, 14 microservices, 3 documentation repos, and 2 troubleshooting chat threads. You now must rotate hundreds of dependent keys, update every deployment, restart every service, and notify every team—because one file got committed.

// Developer workstation
.env
.env.local
.env.production
~/.aws/credentials
~/.config/gcloud/credentials
docker-compose.yml

// Version control (even after deletion, git history persists)
.git/objects/ab/cd1234...  ← Key committed 18 months ago

// CI/CD platforms
GitHub Actions secrets
GitLab CI variables
Jenkins credentials store
CircleCI environment variables

// Production infrastructure
Kubernetes secrets (base64 encoded, not encrypted)
Docker image layers
EC2 instance user data
Lambda environment variables
API Gateway configuration

// Communication channels
Team chat: "Hey try this key: sk_live_..."
Email: "API credentials for new service"
Wiki: "Setup Instructions" page
Documentation: "Onboarding Checklist"

//  ONE LEAK = ROTATE ALL 17 LOCATIONS 

// Identity is generated on-device, never leaves
const agent = await Agent.quickstart({
  name: 'payment-service'
  //  No API key parameter
  //  No secret to copy
  //  No .env file needed
  //  No git history risk
});

// Device generates Ed25519 keypair locally
// Public key → DID (shared in trust registry)
// Private key → OS keychain (never transmitted, never stored in plaintext)

// If device compromised → only THAT device affected
// No cascade. No hundreds of rotations. No system-wide incident.

The architectural difference:

Critical Failure #2: Rotation Nightmare

Even if you never leak a key, compliance requirements force you to rotate it. SOC 2, ISO 27001, and PCI-DSS mandate regular API key rotation—typically every 90 days. Every rotation requires downtime, cross-team coordination, and risks breaking production systems.

The quarterly rotation ritual: Your security team sends the "Q2 API Key Rotation" email. Every team must coordinate a maintenance window. You update production secrets, restart services, monitor for breakage, and hope nothing was missed. Four times per year, your entire engineering organization stops building to rotate credentials that shouldn't exist in the first place.

// Week 1: Generate new key, store in secret manager
aws secretsmanager create-secret \
  --name prod/api-key-v2 \
  --secret-string "sk_live_new..."

// Week 2: Deploy new key to all services (parallel)
kubectl set env deployment/payments API_KEY=sk_live_new...
kubectl set env deployment/billing API_KEY=sk_live_new...
kubectl set env deployment/invoicing API_KEY=sk_live_new...
// ... repeat for 47 more services

// Week 3: Coordinate rollout
//  Can't deploy during business hours (risk of downtime)
//  Can't deploy Friday (weekend incident risk)
//  Can't deploy during month-end close (finance freeze)
//  2am Sunday maintenance window (engineers on-call)

// Week 4: Monitor for breakage
// Did we miss a service? Is caching causing old key usage?
// Are background jobs still using the old key?

// Week 5: Finally revoke old key
// (after monitoring period proves new key works)
aws secretsmanager delete-secret --secret-id prod/api-key-v1

//  Repeat every 90 days. Forever. 

// Identity keys are never transmitted, so they can't be intercepted
const agent = await Agent.quickstart({
  name: 'payment-service'
});

// Each message signed with fresh cryptographic proof
const result = await agent.send({
  to: 'billing-service',
  action: 'process-payment',
  payload: { amount, currency }
  //  Ed25519 signature generated for THIS message
  //  Non-reusable (nonce prevents replay)
  //  Verified via public DID (no secret transmitted)
});

// Compliance requirement satisfied by architecture:
// - No long-lived credentials exist → Nothing to rotate
// - Each signature is single-use → Replay impossible
// - Private key never leaves device → Interception impossible

// SOC 2 auditor: "How often do you rotate API keys?"
// You: "We don't have API keys. We use cryptographic identity."
// Auditor: "...approved."

Why rotation exists (and why it fails):

Rotation policies assume credentials will leak eventually. The logic: if a key leaked 60 days ago and you rotate every 90 days, the exposure window is limited. But this assumes you detect the leak, which most organizations don't. Verizon's 2025 Data Breach Report found the median time to discover a breach is 28 days—but API key leaks in git history can go undetected for years.

Worse, rotation itself causes incidents. Every rotation is a chance to misconfigure, miss a service, or break a production flow. The very mechanism designed to reduce risk becomes a source of operational instability.

Critical Failure #3: Shared Secrets Cascade

From 10 workers to 500 AI agents to 1,000 distributed services: 1 API key shared = total system compromise.

2024: 1 developer = 3 environments. 2026: 1 developer = 500 AI agents.

The scale problem isn't theoretical anymore. LangChain workflows, CrewAI teams, AutoGPT instances—modern developers spawn hundreds of AI agents to handle document processing, customer support, code generation, data analysis, and orchestration tasks. Each agent needs API access to payments, databases, third-party services, and internal systems.

Most production systems share credentials across fleets of workers, services, or AI agents. This isn't negligence—it's the only way to operate with traditional API architecture. Whether you have 10 microservices, 500 AI agents, or 1,000 payment processing workers, sharing one API key creates a single point of failure where one compromised entity forces a system-wide shutdown.

The architectural problem: When every entity (worker, agent, service) shares the same API key, you can't isolate failures. You can't identify which entity made which request. You can't enforce per-entity rate limits—all entities share the same quota. You can't revoke access to one misbehaving entity without shutting down the entire fleet. And when one entity is compromised, you must rotate the key, which stops everything simultaneously.

At AI agent scale, shared credentials completely break down:

• Shared API keys: All entities use the same credential. One key leaked = entire fleet compromised.
• Quota chaos: All entities hit the same rate limit. Agent #47 runs wild → all 500 agents throttled.
• Zero attribution: Logs show "API_KEY: sk_live_xyz made 10,000 calls." Which agent? No idea.
• Blast radius: One agent misbehaves → revoke the key → all entities stop → production outage.
• No per-entity control: Can't give Agent #12 read-only access while Agent #89 has write access. Everyone gets the same permissions.

// Every worker uses the same API key
const workers = await Promise.all(
  Array.from({ length: 1000 }, (_, i) =>
    createWorker({
      id: `worker-${i}`,
      apiKey: process.env.API_KEY // ️ Same key for all 1,000
    })
  )
);

// Problems this creates:
//  Can't identify which worker made which request (no attribution)
//  Can't rate-limit per-worker (all share same quota)
//  Can't revoke one worker (must revoke entire fleet)
//  One compromised worker = rotate key = 1,000 workers offline
//  No isolation—one misbehaving worker affects entire system

// Each worker generates its own unique cryptographic identity
const workers = await Promise.all(
  Array.from({ length: 1000 }, async (_, i) => {
    const agent = await Agent.quickstart({
      name: `worker-${i}`
      //  Unique Ed25519 keypair per worker
      //  Unique DID per worker
      //  No shared secrets
    });
    return agent;
  })
);

// Benefits of unique identity:
//  Cryptographic attribution—know exactly which worker sent each message
//  Per-worker rate limits—one worker's quota doesn't affect others
//  Selective revocation—remove one worker from trust registry, others unaffected
//  Isolated failures—compromised worker only affects itself
//  No coordination required—each worker operates independently

The cascade effect:

When 1,000 workers share one API key and that key leaks, you don't have a "worker 437 is compromised" problem—you have a "shut down the entire fleet" problem. The architectural design forces a system-wide response to a localized failure.

Real-world example: A financial services company runs 500 payment processing workers, each handling transactions for different customers. All 500 workers share the same Stripe API key. When worker 237's container is compromised through an unrelated vulnerability, the attacker now has access to Stripe credentials that work for the entire fleet.

The company has no choice: rotate the Stripe API key immediately. All 500 workers must be redeployed with the new key. Payment processing stops system-wide during the rotation window. [Illustrative scenario]: The incident response: hours of downtime, significant lost revenue, multiple engineers pulled from other work, and a compliance report explaining why one compromised container took down the entire payment infrastructure.

With xBind: Worker 237's identity is removed from the trust registry. That specific worker can no longer authenticate. The other 499 workers continue processing payments without interruption. No emergency rotation. No system-wide coordination. No downtime. The incident is isolated to the compromised component, as it should be.

The contrast:

Why This Costs Multi-Million Dollar Incidents

Industry-wide API failures cost billions annually according to industry research. But that's abstract. Here's what it means for your systems:

When your 4-hour ETL pipeline fails at hour 3 due to token expiry and restarts from zero, that's not a "slight delay"—it's tripled compute cost, missed SLA, and manual intervention at 2am.

Documented Real-World Failures

This isn't hypothetical. Every major platform ships this failure mode:

The Root Cause (Code Every Vendor Ships)

OAuth refresh failures aren't implementation bugs—they're architectural. Bearer tokens create stateful authentication that expires:

// OAuth transport: token baked in at connection time
class OAuthTransport {
  constructor(accessToken) {
    this.headers = { Authorization: `Bearer ${accessToken}` };
    // ️ Token expires, headers don't refresh → 401 → restart
  }

  async call(api) {
    return fetch(api, { headers: this.headers });
    // Workflow restarts from zero. Every time.
  }
}

// Fresh signature per message—nothing to expire
class IdentityTransport {
  async call(api, payload) {
    const signature = this.agent.sign(payload);
    return fetch(api, {
      headers: {
        'X-Agent-DID': this.agent.did,
        'X-Signature': signature // Fresh every call
      },
      body: payload
    });
    //  This failure mode cannot exist
  }
}

Enterprise Value: Seven Dimensions

When cascading failures can't happen, operational reality changes across every layer:

Who Ships This Bug? Everyone.

Lower-Level Failures Force Higher-Level Redos

Every workflow builds expensive work on top of cheap API calls. When the cheap call fails, the expensive work disappears. This is the hidden cost pattern that makes cascading failures economically devastating.

// High-level workflow: "Process invoice and send payment"
async function processInvoice(invoiceData) {
  // Step 1: AI parses invoice (5 minutes of expensive inference)
  const parsed = await aiService.parseInvoice(invoiceData);

  // Step 2: Validate against accounting rules (database queries)
  const validated = await accounting.validate(parsed);

  // Step 3: Generate payment authorization
  const auth = await payments.authorize(validated);

  // Step 4: Send payment → OAuth token expires HERE
  const result = await payments.send(auth); //  401 Unauthorized

  // RESULT: Entire workflow restarts from Step 1
  // Lost work: 5 min AI + validation + auth generation
  // Redo cost: 100% of all previous work thrown away
}

The multiplication math:

• Low-level failure: 1 API call fails (payment.send())
• Local redo: In a typical 4-step workflow (parse → validate → authorize → execute), one failure forces all 4 steps to restart (4× local waste per workflow)
• Fleet cascade: Multiply by 1,000 concurrent agents running the same integration
• Total waste: [Real cost example]: In a 4-step workflow running across 1,000 parallel agents, one auth failure forces 4,000 operations to restart (1 local redo × 4 steps × 1,000 agents). This creates significant wasted compute costs per incident. At typical incident rates, this translates to thousands of dollars annually in discarded compute. [Calculation assumes 4-step workflow - adjust based on your stack]

Expensive Work Destroyed by Cheap Failures

The economic absurdity of cascading failures: the cheapest operation in your stack destroys work that's hundreds of thousands of times more expensive.

xBind Eliminates Redo Cascades Architecturally

When an agent fails, that agent restarts. Your expensive GPU job completes. The signature generation happens AFTER the work is done, not before.

• Work completes → signature generated → message sent
• Auth fails → signature invalid → only that send operation retries
• The 10-minute inference result is preserved

No shared state = no cascade = no redo multiplication.

The architectural difference: xBind eliminates workflow resets by reversing the execution order. Work completes FIRST, then gets signed. If the signature fails, only that send operation retries - the completed work is preserved. No shared state = no cascade = no redo.

This isn't better retry logic. This is removing the failure mode from the system.

The Mechanism (One Sentence)

A cheap auth failure can force expensive work to be repeated.

This happens because authentication happens BEFORE work execution in API architectures. When auth fails, all downstream work must restart.

xBind reverses this: work completes first, then gets signed. Authentication failure affects only the signature, not the work.

// Same workflow, zero redo risk
async function processInvoice(invoiceData) {
  const parsed = await aiService.parseInvoice(invoiceData);
  const validated = await accounting.validate(parsed);
  const auth = await payments.authorize(validated);

  // Fresh cryptographic signature—always works
  const result = await agent.send({
    to: paymentsService,
    payload: auth
  }); //  No token to expire, no redo possible

  // Result: 0× waste multiplication, ever
}

Why xBind Can't Cascade

There's no token to leak. No refresh to fail. No state to corrupt. Cascades require reusable credentials. Signatures aren't reusable.

The Strategic Reality

Without cascading failure elimination, xBind is "better."
With it, xBind is necessary.

You don't replace working systems for 10% improvement. You replace systems when you realize the current architecture is fundamentally broken.

Every vendor rediscovers this bug. Microsoft, GitHub, and other major platforms all ship the same architectural flaw because OAuth's stateful authentication creates reusable credentials that cascade failures across systems.

xBind removes the mechanism. Not better refresh handling. Not smarter retry logic. No authentication state to expire.

No Granular Revocation

The Problem: Security vs Availability

You have 1,000 AI agents running in production. They all authenticate using the same API key or OAuth client credentials because that's how shared secrets work — one credential shared across the fleet.

Agent #47 starts behaving suspiciously. Maybe it's compromised. Maybe it's misbehaving. Maybe you just need to rotate it out for maintenance.

You face an impossible choice:

This isn't a theoretical problem. It's the fundamental architecture of shared secrets.

API keys: One key shared across the entire fleet. Revoking it kills everything that uses it.

OAuth client credentials: One client_id/client_secret pair per application. Revoking the client kills every instance of that application.

Service accounts: One service account shared by 1,000 workers. Disable the account, disable all workers.

The xBind Solution: Identity-Based Revocation

With xBind, every agent has its own cryptographic identity. Agent #47 has a unique DID. Agent #48 has a different DID. They don't share credentials.

// Trust registry manages per-agent access
await trustRegistry.revoke('did:key:z6Mk...Agent47')

// Agent #47 stops immediately
// Agents #1-46, #48-1000 keep running
// Zero blast radius

Zero Blast Radius

One compromised identity affects exactly one agent.

The trust registry holds per-agent authorization state. Revoking one DID removes that specific agent's access. The registry check happens on every message — the revoked agent's next send or receive fails immediately.

Why This Is Impossible with Shared Secrets

Shared secrets are identity-agnostic. The API key doesn't know which agent holds it. When you revoke the key, you revoke access for everyone who has that key.

You can't revoke "just Agent #47's copy of the key." That concept doesn't exist. The key is the same everywhere. Revoking it revokes it everywhere.

The Business Impact

Shared secrets force you to keep compromised agents running.

In production, you can't afford total outages. So security teams delay revocation. They wait for maintenance windows. They coordinate cross-team deployments to re-key everything at once.

The compromised agent keeps running for hours or days because shutting it down means shutting down everything.

xBind Makes This Trivial

Granular revocation isn't a feature you configure. It's how identity-based authentication works by default.

// Add agent to allowlist
await trustRegistry.add('did:key:z6Mk...Agent47', {
  scopes: ['payments:read', 'payments:write']
})

// Revoke specific agent
await trustRegistry.revoke('did:key:z6Mk...Agent47')

// Update scopes for specific agent
await trustRegistry.updateScopes('did:key:z6Mk...Agent48', {
  scopes: ['payments:read'] // remove write access
})

Every agent send/receive goes through the trust registry. Revoked DIDs fail immediately. Updated scopes take effect on the next message. No cache invalidation. No eventual consistency. Instant enforcement.

Granular revocation isn't a feature. It's the absence of shared secrets.

When every agent has a unique identity, revoking one identity affects one agent. This isn't advanced configuration — it's the default behavior of identity-based systems.

You don't choose between security and availability anymore. You get both.

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 team chat, 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.

Critical Failure #5: Compliance Audit Hell

"Which of your 200 agents made this call?" — When a SOC 2 auditor asks this question during your compliance review, you freeze. With shared API keys, you literally cannot answer. Every agent uses the same credential. Your logs show thousands of calls, but zero agent-level attribution. You promise to "improve logging" and hope they accept it.

The audit failure cascade:

// Server logs from API gateway
2024-04-20 14:32:18 | API_KEY: sk_live_abc123 | POST /orders | 201 Created
2024-04-20 14:32:22 | API_KEY: sk_live_abc123 | POST /payments | 200 OK
2024-04-20 14:32:25 | API_KEY: sk_live_abc123 | DELETE /inventory/1847 | 204 No Content

// QUESTION FROM AUDITOR: Which agent deleted inventory item 1847?
// YOUR ANSWER: "We don't know. All 200 agents share that API key."
// AUDITOR'S RESPONSE: "That's a control deficiency. SOC 2 Type II fails."

You scramble to provide a narrative explanation—maybe correlate timestamps with deployment logs, cross-reference with CI/CD pipelines, check Kubernetes pod names. But that's not cryptographic evidence. It's forensic guesswork. And your auditor knows it.

Why this matters for compliance frameworks:

• SOC 2 (Type II): Requires attribution of actions to specific entities. Shared credentials fail CC6.1 (Logical Access Controls) and CC6.6 (Audit Logging). Auditors require cryptographic proof, not log correlation.
• ISO 27001 (A.9.2.1): "User registration and de-registration" mandates unique identifiers per entity. API keys shared across 200 agents violate this control. Surveillance controls (A.12.4.1) require individual accountability.
• HIPAA (§164.312(b)): Audit controls must record "which person or entity accessed" PHI. Shared API keys cannot satisfy this requirement. OCR enforcement actions cite inability to attribute access.
• GDPR (Article 32(1)(d)): "Ability to ensure ongoing confidentiality" requires knowing who accessed what. Shared keys destroy this capability. GDPR Article 5(2) accountability principle demands attributable actions.

The xBind solution: DID-based cryptographic audit trail

Every xBind message is signed by the sender's DID-based signature. The signature proves which agent (by DID) sent the message. No shared credentials. No ambiguity. No forensic correlation required.

// Audit log with cryptographic attribution
2024-04-20 14:32:18 | FROM: did:key:z6MkOrderAgent47Qp... | action: createOrder | orderId: 8472 | SIG: Ed25519(valid)
2024-04-20 14:32:22 | FROM: did:key:z6MkPaymentAgent89x... | action: processPayment | amount: 127.50 | SIG: Ed25519(valid)
2024-04-20 14:32:25 | FROM: did:key:z6MkInventoryAgent12... | action: deleteItem | itemId: 1847 | SIG: Ed25519(valid)

// QUESTION FROM AUDITOR: Which agent deleted inventory item 1847?
// YOUR ANSWER: "did:key:z6MkInventoryAgent12..., verified via cryptographic signature."
// AUDITOR'S RESPONSE: "Perfect. Cryptographic proof of attribution. Control satisfied."

For details on how DID-based signatures provide cryptographic proof and non-repudiation, see Critical Failure #7: Zero Cryptographic Proof.

Retention and immutability:

The enterprise AuditLog module stores signed envelopes with 7-year retention (configurable for SOX, SEC 17a-4, or other regulations). Each envelope includes timestamp, sender DID, recipient DID, scope, and cryptographic signature. Logs are append-only and HMAC-chained to detect tampering. This satisfies regulatory requirements for audit trail immutability and long-term retention.

// Configure audit log for financial services (SEC 17a-4 compliance)
const audit = await AuditLog.enterprise({
  retention: '7-years',        // SOX / SEC 17a-4 / FINRA 4511
  encryption: 'org-key',        // Encrypt at rest with org key
  hmacChain: true,              // Tamper-evident HMAC chain
  immutable: true               // Append-only, no deletions
});

// Every agent action is automatically logged with cryptographic proof
const agent = await Agent.create({
  name: 'trading-agent-47',
  audit                        // Compliance copy to audit log
});

// This send() creates an audit entry with:
// - Timestamp (ISO 8601 UTC)
// - Sender DID (did:key:z6Mk...)
// - Recipient DID
// - Action payload
// - Cryptographic signature (non-repudiable proof)
// - HMAC linking to previous entry (tamper-detection)
await agent.send({
  to: counterpartyDid,
  payload: { action: 'submitTradeOrder', symbol: 'AAPL', qty: 1000 },
  scope: 'trading'
});

The contrast that auditors see:

When the auditor leaves satisfied:

With xBind, compliance audits go from "explain why your logs don't prove attribution" to "here's cryptographic proof of every agent action." SOC 2 Type II, ISO 27001, HIPAA, and GDPR requirements for accountability, non-repudiation, and audit trails are met at the protocol level—not bolted on via application logging. Your auditor sees cryptographic signatures and HMAC-chained immutable logs, and checks the box.

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

Critical Failure #7: Zero Cryptographic Proof

Bearer tokens: "Trust me, I have the key." Signatures: Mathematical proof.

When your security team investigates a suspicious API call, the forensic trail goes cold immediately. The logs show "Authorization: Bearer abc123" — but that token could have been used by anyone who had access to it. There's no cryptographic proof of who made the call. Just proof that someone had the token.

The problem with bearer credentials:

API keys and OAuth tokens are bearer credentials. If you possess the secret, you are authenticated. There is no cryptographic binding between the credential and the entity using it. This creates fundamental problems:

• Anyone with the token is trusted: If Agent A leaks an API key, Agent B can use it to impersonate Agent A. The server has no way to distinguish them.
• No proof of origin: Logs show "API key sk_123 made this call" — but they don't show which agent used that key. Multiple agents sharing the same key are indistinguishable.
• Forensic guesswork: To determine who made a suspicious call, you correlate timestamps with deployment logs, Kubernetes pod names, and CI/CD pipelines. That's not proof. It's a narrative reconstruction.
• No non-repudiation: An agent can claim "someone else must have used the shared API key." Without cryptographic signatures, you cannot definitively prove they made the call.

Code comparison: bearer token vs cryptographic signature

// HTTP request with bearer credential
POST /api/payments HTTP/1.1
Host: payments.example.com
Authorization: Bearer sk_live_abc123xyz

// Server logs this request
2024-04-20 15:42:18 | API_KEY: sk_live_abc123xyz | POST /payments | amount: 50000 | 200 OK

// PROBLEM: Anyone with this token can make this request
// - Agent A, Agent B, Agent C all share sk_live_abc123xyz
// - Server cannot tell which agent sent this
// - No cryptographic proof of sender identity
// - Forensics: correlate timestamps, guess from deployment logs

// xBind envelope with Ed25519 signature
{
  "from": "did:key:z6MkPaymentAgent89xQp...",  // Sender's DID (public key)
  "to": "did:key:z6MkPaymentService47...",
  "payload": {
    "action": "processPayment",
    "amount": 50000
  },
  "nonce": "7f3a9c2b...",                // Prevents replay attacks
  "signature": "8d4e5f..."              // Ed25519(from + to + payload + nonce)
}

// Recipient verifies signature BEFORE processing
const isValid = await ed25519.verify(
  envelope.signature,
  envelope.from,                // Public key from DID
  envelope.to + envelope.payload + envelope.nonce
);

if (!isValid) {
  throw new Error('Invalid signature - message rejected');
}

// PROOF: This message was signed by did:key:z6MkPaymentAgent89xQp...
// - Only the holder of the PRIVATE key could create this signature
// - Signature mathematically binds the message to the sender's identity
// - Cannot be forged (would require breaking Ed25519, computationally infeasible)
// - Audit trail: cryptographic verification, not log correlation

The fundamental difference:

What cryptographic proof means for your systems:

Every xBind message includes an Ed25519 signature that binds the message content to the sender's identity (DID). The signature is computed over the entire envelope: sender DID, recipient DID, payload, nonce, and timestamp. This provides:

• Cryptographic attribution: Logs don't say "API key abc123 made this call." They say "did:key:z6MkAgent47... signed this message with Ed25519, signature verified." That's mathematical proof, not narrative correlation.
• Non-repudiation: The agent cannot later claim "I didn't send that message." Their private key signed it. The signature verification proves it. This satisfies legal and regulatory requirements for non-repudiable audit trails.
• Tamper detection: If any field in the envelope is modified after signing, the signature verification fails. You know immediately that the message was altered in transit or in storage.
• No shared credentials: Each agent has a unique DID and Ed25519 keypair. There is no "shared API key" problem. Every message is cryptographically attributable to exactly one sender.

Why this matters for compliance and legal contexts:

Regulatory frameworks increasingly require non-repudiation—cryptographic proof that a specific entity performed a specific action. Bearer credentials cannot provide this. Shared API keys make it impossible. xBind's Ed25519 signatures satisfy these requirements at the protocol level:

• Financial services (SEC 17a-4, FINRA 4511): Trade orders must have non-repudiable attribution. Ed25519 signatures on xBind envelopes prove which agent submitted each order. No "someone else had the API key" defense.
• Healthcare (HIPAA § 164.312(c)(1)): Integrity controls must detect unauthorized modifications. xBind signatures fail verification if any field is altered, providing tamper-evidence at the message level.
• Government (NIST SP 800-53 AU-10): Non-repudiation control requires binding actions to identities. DID + Ed25519 satisfies this requirement without application-level workarounds.
• European eIDAS Regulation: Advanced electronic signatures require proof of signer identity and message integrity. xBind envelopes meet both criteria—Ed25519 proves the signer, HMAC proves the integrity.
• Legal discovery: When opposing counsel subpoenas your API logs, "we think Agent A did this based on timestamps" won't survive cross-examination. "Agent A's Ed25519 signature is mathematically verified on this message" will.

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.

xBind 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 xBind, 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

Mathematical Instability

Shared secret authentication doesn't degrade gracefully. It collapses exponentially.

The fundamental problem with API keys, OAuth tokens, and shared secrets is compound probability. When multiple systems depend on a single authentication credential, failures don't add linearly—they multiply catastrophically.

The Collapse Formula

P(failure) = 1 − (1 − p)N

Where p is the per-system failure rate and N is the number of dependent systems. This isn't a linear relationship—it's exponential. As you add more services sharing the same credential, the probability of at least one failure approaches 100% rapidly.

Failure Curve: Exponential Collapse

The chart below shows how system reliability degrades as you add more services sharing the same credential. Notice the sharp collapse beyond N=50 systems.

Breakpoint Analysis

Critical thresholds where shared-secret systems transition from stable to unstable:

Zone Definitions

Why xBind Eliminates This Problem

xBind uses cryptographic identity instead of shared secrets. Each agent has its own Ed25519 key pair. When Agent #47 fails, it doesn't cascade to the other 499 agents—the failure is isolated.

P(xbind_cascade) = 0

With independent identities, the compound probability formula no longer applies. There's no shared credential to expire, leak, or fail system-wide. Failures remain local, exactly where they occur.

Real-World Use Cases

Seven scenarios where xBind replaces traditional API key management with Authenticated Cryptographic Interfaces.

import { Agent, MemoryTrustRegistry, LoopbackTransport } from '@private.me/xbind';

const registry = new MemoryTrustRegistry();
const transport = new LoopbackTransport();

// Create orchestrator + worker agents
const orchestrator = await Agent.quickstart({
  name: 'Orchestrator',
  registry,
  transport,
  sendScopes: ['task:assign', 'task:cancel']
});

const worker1 = await Agent.quickstart({
  name: 'Worker-1',
  registry,
  transport,
  sendScopes: ['task:result'],
  scopes: ['task:assign']  // Only accepts task assignments
});

// Orchestrator dispatches work
await orchestrator.send({
  to: worker1.did,
  payload: { taskId: 't-001', action: 'process-pdf' },
  scope: 'task:assign'
});

// Worker receives and processes
const { envelope } = transport.sent[0]!;
const task = await worker1.receive(envelope);
console.log(task.value.payload.action);  // 'process-pdf'

import { Agent, MemoryTrustRegistry } from '@private.me/xbind';

// Sender: Payment Service
// Recipient: Analytics Service

const registry = new MemoryTrustRegistry();

// Analytics only accepts 'payments' scope, rejects 'orders'
await registry.register(
  analyticsDid,
  analyticsPublicKey,
  'Analytics Service',
  ['analytics'],                    // Send scopes
  undefined, undefined, undefined, false,
  ['payments']                      // Receive scopes (only accepts payments)
);

// This succeeds (both sides accept 'payments')
await sender.send({ to: analyticsDid, payload: txData, scope: 'payments' });

// This fails with RECEIVER_SCOPE_DENIED (analytics doesn't accept 'orders')
const result = await sender.send({
  to: analyticsDid,
  payload: orderData,
  scope: 'orders'
});

if (!result.ok && result.error === 'RECEIVER_SCOPE_DENIED') {
  console.error('Recipient does not accept this scope');
}

import { Agent } from '@private.me/xbind';

// Temperature sensor only accepts telemetry commands
const sensor = await Agent.create({
  registry,
  transport,
  scopes: [
    'telemetry:read',
    'telemetry:configure'
  ]
});

// Control system sends command
const result = await sensor.receive();

// Device rejects 'firmware:update' scope even if sender has it
if (!result.ok && result.error === 'SCOPE_NOT_ALLOWED') {
  // Log security event - attacker may have compromised control system
  logger.security('Rejected out-of-scope command', result.error);
}

import { Agent } from '@private.me/xbind';

// EHR system only accepts medical data operations
const ehr = await Agent.create({
  registry,
  transport,
  scopes: [
    'patient:read',
    'patient:write',
    'clinical:labs',
    'clinical:imaging'
  ]
});

// Billing service tries to access administrative functions
const result = await ehr.receive();

// EHR rejects 'admin:users' or 'billing:export' scopes
// even if billing service has those scopes in registry

import { Agent } from '@private.me/xbind';

// Payment processor only accepts payment operations
const processor = await Agent.create({
  registry,
  transport,
  scopes: [
    'payment:authorize',
    'payment:capture'
  ]
});

// Merchant tries to issue refund (requires separate flow)
const result = await processor.receive();

// Processor rejects 'payment:refund' or 'settlement:export'
// These operations require elevated authentication

import { Agent } from '@private.me/xbind';

// Each tenant defines which scopes they accept
const tenantService = await Agent.create({
  registry,
  transport,
  scopes: [
    'tenant:read',
    'tenant:write',
    'data:query'
  ]
});

// Another tenant tries to access admin or export functions
const result = await tenantService.receive();

// Service rejects 'admin:config', 'data:export', 'tenant:list'
// These are platform-level scopes, not tenant-level

import { Agent } from '@private.me/xbind';

// Provisioning service authenticates via cryptographic identity
const provisioningAgent = await Agent.create({
  registry,
  transport,
  sendScopes: [
    'provisioning:notify',
    'provisioning:deploy'
  ]
});

// Send provisioning notification (no API key stored)
const result = await provisioningAgent.send({
  to: emailServiceDid,
  payload: {
    recipient: customer.email,
    deployment: connectionId,
    status: 'active'
  },
  scope: 'provisioning:notify'
});

// If service crashes, no credentials are exposed
// Attacker gets Ed25519 keypair, not API keys

Purchasing ACIs with xBind

AI agents can purchase ACIs using xBind M2M authentication instead of email addresses. Cryptographic signatures prevent impersonation, and identity-based rate limits are 6× faster than email-based flows.

Why Use xBind for Purchases

• Privacy: Email optional — fallback generated as agent-{did_suffix}@private.me if missing
• Security: Signed envelopes prevent purchase request impersonation (no stolen API keys)
• Performance: 60 requests/min rate limit vs 10 requests/min for email-based purchases
• M2M-native: No human intervention required for subscription management

Pricing Tiers

Usage-based billing with a generous free tier. AI agents can purchase programmatically using xBind identity. See pricing details or subscribe now.

Free tier: Generous monthly operations at no cost. Pro tier: Unlimited operations with usage-based pricing. See pricing details.

Get Started →

Commercial use: Enterprise tier required if ACIs contribute to customer-facing functionality. Pro tier restricted to internal use only. Agent-based purchases inherit organization-level pricing automatically via DID-to-organization mapping. See pricing details.

How It Works

Runtime Compatibility

xBind runs everywhere JavaScript runs. Four runtime platforms are supported with platform-specific adapters for storage, crypto, and networking.

Compatibility Matrix

Browser

Full support for Chrome, Firefox, Safari, and Edge with IndexedDB persistence and service worker background processing.

import { Agent } from '@private.me/xbind';
import { IndexedDBAdapter } from '@private.me/xbind/runtime/browser';

// Initialize browser storage
const storage = new IndexedDBAdapter('xbind-db', 'keyval', 1);

// Create agent with persistent identity
const agent = await Agent.create({
  registryUrl: 'https://private.me/aci/registry',
  storage,
});

// Send encrypted message
const result = await agent.send({
  to: 'did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK',
  payload: { message: 'Hello from browser!' },
  channels: ['https'],
});

// Store identity for next session
await storage.setItem('identity', {
  did: agent.identity.did,
  keys: agent.identity.keys,
});

React Native

iOS and Android support with AsyncStorage persistence and native crypto integration (react-native-quick-crypto or expo-crypto).

import { Agent } from '@private.me/xbind';
import AsyncStorage from '@react-native-async-storage/async-storage';
import { AsyncStorageAdapter } from '@private.me/xbind/runtime/react-native';

// Initialize AsyncStorage adapter
const storage = new AsyncStorageAdapter({
  storage: AsyncStorage,
  storagePrefix: '@myapp:xbind:'
});

// Create or restore agent
const seedResult = await storage.get('identity:seed');

const agent = seedResult.success && seedResult.value
  ? await Agent.fromSeed(seedResult.value)
  : await Agent.create({ identity: 'persistent' });

// Store seed for persistence
if (!seedResult.success) {
  await storage.set('identity:seed', agent.identity.seed);
}

// Send message from mobile app
const result = await agent.send({
  to: recipientDid,
  payload: { type: 'message', content: messageText },
});

Edge Runtime

Cloudflare Workers, Vercel Edge Functions, and Deno Deploy support with KV storage for distributed nonce stores and trust registry.

import { Agent } from '@private.me/xbind';
import { CloudflareKVAdapter, createEdgeAgent } from '@private.me/xbind/runtime/edge';

export default {
  async fetch(request: Request, env: Env) {
    // Initialize edge-compatible components
    const kv = new CloudflareKVAdapter(env.XBIND_KV);
    const { nonceStore, trustRegistry, transport } = createEdgeAgent({
      kv,
      baseUrl: 'https://private.me/aci/relay',
    });

    // Create agent with edge components
    const agent = new Agent({
      identity: 'persistent',
      nonceStore,
      trustRegistry,
      transport,
    });

    // Authenticate request at the edge
    const authHeader = request.headers.get('Authorization');
    if (authHeader?.startsWith('Bearer ')) {
      const token = authHeader.slice(7);
      const verification = await agent.verify(token);

      if (verification.ok) {
        return new Response('Authenticated', { status: 200 });
      }
    }

    return new Response('Unauthorized', { status: 401 });
  },
};

Installation by Platform

Node.js: Default runtime. See Agent ACI Reference for standard usage. File system storage recommended for production deployments.

Code Examples

Example 1: Basic Purchase with xBind Envelope

import { Agent } from '@private.me/xbind';

// Create agent (or use existing)
const agent = await Agent.quickstart({ name: 'purchase-agent' });

// Send authenticated purchase request
const sendResult = await agent.send({
  to: 'did:key:z6Mkp...',  // Private.Me server DID
  payload: {
    aci: 'xbind',
    tier: 'basic',          // 'basic' | 'middle' | 'enterprise'
    paymentMethod: 'pm_card_visa'
  },
  scope: 'aci:purchase'
});

if (!sendResult.ok) {
  console.error('Purchase failed:', sendResult.error);
  return;
}

// Purchase successful
console.log('Purchase completed');
console.log('Connection ID:', sendResult.value);

Example 2: Side-by-Side Comparison

Example 3: Response Handling

// Purchase response structure
const result = await response.json();

if (result.xbindAuthenticated) {
  // xBind signature verified — higher trust
  console.log('Purchase authenticated via xBind identity');
  console.log(`Connection ID: ${result.connectionId}`);
  console.log(`Agent DID: ${result.agentDid}`);
  console.log(`Email (fallback): ${result.email}`);
} else {
  // Email-based purchase (legacy flow)
  console.log('Purchase using email address');
}

// Common fields (both flows)
console.log(`Subscription ID: ${result.subscriptionId}`);
console.log(`Tier: ${result.tier}`);  // "free", "pro", or "enterprise"

Migration Timeline

Rate Limits & Performance

Include X-Client-Type: ai-agent header to receive the higher 60 req/min rate limit. Without this header, xBind purchases default to 10 req/min (same as email-based).

Performance at Scale: 1 Million Endpoints

Benchmarked against SPIRE/SPIFFE (deployed by Uber for 250,000+ microservices). xBind delivers dramatically lower infrastructure cost, 50× faster bootstrap, and 1,000× less network bandwidth—with post-quantum security included by default.

Performance Comparison: xBind vs SPIRE/SPIFFE

Visual Comparison

Real-World Pain Points

Data Sources & Methodology

Building Blocks

xBind is composed of three foundational building blocks that combine to create a complete identity-based authentication system.

crypto

The crypto building block provides information-theoretic security through XorIDA threshold sharing. This patented algorithm enables unconditional security without relying on computational assumptions, offering protection against both classical and quantum attacks. The crypto block handles HMAC-SHA256 verification, PKCS#7 padding, TLV serialization, and the core threshold secret sharing operations.

shareformat

The shareformat building block defines the standardized structure for how cryptographic shares are encoded, transmitted, and reconstructed. It ensures interoperability across different transport mechanisms and provides the protocol-level guarantees needed for secure multi-channel communication. This includes share header formatting, base64 encoding, and the wire format that makes split-channel delivery possible.

xchange

The xchange building block implements the key transport protocol that enables secure key agreement between parties. It coordinates the exchange of cryptographic material needed to establish authenticated channels, handling ephemeral key generation, hybrid post-quantum key agreement (X25519 + ML-KEM-768), and the forward secrecy guarantees that protect past communications even if long-term keys are compromised.

Gateway Architecture: Non-Authoritative Coordination

The gateway provides four coordination functions without authoritative control over identity or trust decisions.

Gateway Role: Coordination, Not Authentication

The xBind gateway is a non-authoritative coordination layer that facilitates agent communication without holding power over authentication or authorization. It coordinates but does not decide, observes but does not authenticate, and facilitates but does not control.

Four Coordination Functions

Critical Security Distinction

The gateway coordinates but does not authenticate. It cannot forge messages (no private keys), cannot decide trust (agents verify signatures independently), and cannot suppress state changes permanently (signed checkpoints are independently verifiable).

Compromised Gateway Mitigation

Gateway Deployment Models

Organizations choose gateway deployment based on trust requirements:

The One-Time Setup

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

import { Agent } from '@private.me/xbind';

// ✅ RECOMMENDED: Auto-generates identity, no Vault Store required (throws on error)
const agent = await Agent.quickstart({ name: 'MyService' });

// 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 enabled). 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
});

Risk Tags (Recommended for Crypto)

For cryptocurrency transactions (BTC, ETH, etc.), use explicit risk tags in your payload to control XorIDA threshold security:

// No risk tag (default): Standard encrypted transport, no XorIDA
await agent.send({
  to: recipientDid,
  payload: { amount: 0.1, currency: 'BTC' }
  // No XorIDA overhead (~10ms)
});

// Low risk: 2-of-2 threshold (minimal overhead)
await agent.send({
  to: recipientDid,
  payload: { amount: 0.5, currency: 'BTC', risk: 'low' }
});

// Medium risk: 2-of-3 threshold (fault tolerant)
await agent.send({
  to: recipientDid,
  payload: { amount: 5.0, currency: 'ETH', risk: 'medium' }
});

// High risk: 3-of-5 threshold (maximum security)
await agent.send({
  to: recipientDid,
  payload: { amount: 50, currency: 'BTC', risk: 'high' }
});

// Critical risk: 3-of-5 threshold (same as high)
await agent.send({
  to: recipientDid,
  payload: { amount: 100, currency: 'BTC', risk: 'critical' }
});

Threshold Schemes

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 up to 180× faster operation (estimated). 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. xBind 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: xBind — Cryptographic Identity

xBind 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/xbind';

// Create a persistent agent identity from seed
const seed = crypto.getRandomValues(new Uint8Array(32)); // Store securely
const agent = (await Agent.fromSeed(seed, {
  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.quickstart({ name: 'InternalService' });

// 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 (xBind) 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.

Trust Infrastructure

Automated discovery, trust-on-first-use workflows, DID succession, push notifications, and configurable cache failure modes.

Discovery Mechanisms

xBind provides four-tier discovery with automatic fallback:

1. DNS TXT Records: Query _xbind.example.com for DID (5-minute cache)
2. .well-known: Fetch https://example.com/.well-known/xbind
3. Central Registry: Query gateway.private.me/registry/resolve
4. Email-based: Extract domain from email address, restart discovery

Trust-on-First-Use (TOFU)

xBind implements address-book-style trust with automatic key acceptance:

• First contact: Accept and cache DID → public key mapping
• Key changes: Require explicit user confirmation (prevent MITM)
• Trust upgrade: Verified → Pinned → Trusted hierarchy

DID Succession Protocol

Cryptographic key rotation with zero trust loss:

• Format: did:key:OLD||did:key:NEW||timestamp||sig_OLD||sig_NEW
• Dual signatures: Both old and new keys sign the succession announcement
• Grace period: 7 days for gradual rollout, 5 minutes for xID (ephemeral identity)
• Post-quantum: ML-DSA-65 signatures for continuity proofs

Push Notifications vs. Signed Checkpoints

Two complementary mechanisms for trust state propagation:

Push Notifications (Acceleration)

Real-time event delivery via WebSocket for fast propagation:

• Purpose: Speed, not guaranteed delivery — best-effort propagation
• Events: trust:revocation, trust:succession
• Delivery: 3-retry exponential backoff (1s, 2s, 4s delays with jitter)
• Subscriptions: Bloom filter bandwidth optimization (10k DIDs → 1.2 KB at 1% FPR)
• State model: Online-only (gateway forgets on disconnect)

Signed Checkpoints (Correctness Anchor)

Verifiable trust state with bounded staleness:

• Purpose: Safety, not speed — cryptographically verifiable correctness
• Staleness bound: 30 seconds (cache TTL) — maximum delay between revocation and enforcement
• Failure mode: Fail-secure (default) — reject messages on cache miss during network partition
• Role: Push provides fast propagation; checkpoints ensure eventual consistency

Cache Failure Modes

Configurable behavior for network partitions:

• Fail-secure (default): Reject messages if cache refresh fails
• Fail-open: Accept messages using stale cache (trade security for availability)
• Cache TTL: 30 seconds (bounds exposure window for revoked keys)

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.

import { Agent } from '@private.me/xbind';

// did:key format (ephemeral, local testing)
const agent = await Agent.quickstart({ name: 'Alice' });
console.log(agent.did);  // did:key:z6MkrR...

// did:web format (production, resolvable)
const prodAgent = await Agent.create({
  did: 'did:web:example.com:alice',
  registry,
  transport
});

// DIDs are self-certifying identifiers (decentralized)
// No registration server needed - generate locally

Persistence Strategies

Complete Flow

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

Sender Pipeline

1. Agent.quickstart() or Agent.fromSeed() 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 enabled). 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.

AI Framework Integrations

Drop-in identity layer for 6 major AI frameworks. Replace API keys with cryptographic identity, eliminate cascading failures, accelerate authentication 603×.

Benefits Across All Frameworks

Integration Examples

Haystack RAG Pipeline

from haystack import Pipeline
from private_me.haystack_xbind import xBindAuthComponent

# Create pipeline with xBind identity
pipeline = Pipeline()
pipeline.add_component("auth", xBindAuthComponent(did=agent_did))
pipeline.add_component("retriever", retriever)

# All downstream components inherit xBind identity
# No API keys, no rotation, no downtime
results = pipeline.run({"query": "What is XorIDA?"})

Semantic Kernel (C#)

using PrivateMe.SemanticKernel.xBind;

var kernel = Kernel.CreateBuilder()
    .AddxBindIdentity(agentDid, privateKey)
    .Build();

// All plugin executions signed with xBind identity
// Replaces Azure AD tokens
var result = await kernel.InvokeAsync("SummarizePlugin", "Summarize", new { text });

AutoGen Group Chat

from autogen import AssistantAgent, UserProxyAgent
from private_me.autogen_xbind import xBindGroupChat

# Each agent gets unique DID
assistant = AssistantAgent(
    name="assistant",
    identity=xBindIdentity("did:key:z6Mkp...")
)

user_proxy = UserProxyAgent(
    name="user",
    identity=xBindIdentity("did:key:z6Mkq...")
)

# Group chat with identity verification
groupchat = xBindGroupChat(agents=[assistant, user_proxy])
# Every message cryptographically signed, no shared secrets

SuperAGI Tool Security

from superagi.tools.base_tool import BaseTool
from private_me.superagi_xbind import xbind_tool

@xbind_tool(scope="database:write")
class DatabaseTool(BaseTool):
    def execute(self, query):
        # Tool execution cryptographically signed
        # Scope "database:write" enforced by trust registry
        return self.run_query(query)

# Agent identity verified before tool execution
# Revoke agent → all tool access revoked instantly

Flowise Low-Code Integration

import { xBindAuthNode } from '@private.me/flowise';

// Custom node for Flowise canvas
export class xBindAuth implements INode {
  label = 'xBind Identity';
  name = 'xbindAuth';
  category = 'Authentication';

  async init(nodeData) {
    const agent = await Agent.quickstart({ name: nodeData.name });
    return agent; // Identity flows to all downstream nodes
  }
}

// Visual workflow: xBind Auth → LLM → Tool → Output
// No API key configuration required

MCP Transport: Universal Identity Layer

The @private.me/mcp-transport package provides a universal identity layer for Model Context Protocol (MCP) compliant tools. Any AI framework that supports MCP can use xBind for authentication without framework-specific adapters.

import { McpTransport } from '@private.me/mcp-transport';
import { Agent } from '@private.me/xbind';

// Create xBind agent
const agent = await Agent.quickstart({ name: 'mcp-agent' });

// MCP transport wraps xBind identity
const transport = new McpTransport({ agent });

// Any MCP-compliant tool now uses xBind identity
await transport.send({
  tool: 'search',
  params: { query: 'XorIDA threshold sharing' }
});

// Works with: Claude Desktop, Haystack, LangChain, LlamaIndex, and any MCP client

Use Cases: Multi-Agent Orchestration

Problem: In multi-agent systems, a single expired OAuth token can cascade into 500+ agent restarts. Traditional API keys create a shared failure point.
Solution: xBind gives every agent a cryptographic identity (DID). No shared secrets, no cascading failures. One agent failure is isolated, not systemic. See Cascading Failure Elimination for complete analysis.

Use Cases: MCP-Compliant Tool Execution

Problem: MCP tools require authentication but lack identity standards. Every framework reinvents authentication.
Solution: xBind + MCP transport = universal identity layer. One authentication protocol, all frameworks supported.

Integration Patterns

Five 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/xbind';

// 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/xbind';

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
}

Purchase API Integration

import { Agent } from '@private.me/xbind';

// Create agent (or use existing)
const agent = await Agent.quickstart({ name: 'purchase-agent' });

// Send authenticated purchase request
const sendResult = await agent.send({
  to: 'did:key:z6Mkp...',  // Private.Me server DID
  payload: {
    aci: 'xbind',
    tier: 'basic',
    paymentMethod: 'pm_card_visa'
  },
  scope: 'aci:purchase'
});

if (!sendResult.ok) {
  console.error('Purchase failed:', sendResult.error);
  return;
}

// Purchase successful
console.log('Purchase completed');
console.log('Connection ID:', sendResult.value);

xBind Agent ACI

The xBind Agent ACI is the primary interface for building M2M applications with xBind. It provides high-level abstractions for identity, discovery, policy enforcement, and audit trails while handling all cryptographic operations automatically.

Quick Start with Agent.quickstart()

The fastest path to a working agent. Agent.quickstart() generates an identity, creates an agent instance, and optionally connects to a service in a single call. Ideal for prototyping, demos, and tutorials.

import { Agent } from '@private.me/xbind';

// Create agent with auto-generated identity (throws on error)
const agent = await Agent.quickstart({ name: 'my-service' });

// Use immediately
await agent.send({
  to: 'did:key:z6Mk...',
  payload: { action: 'processData', data: [...] },
  scope: 'integration'
});

try {
  const agent = await Agent.quickstart({ name: 'my-service' });
  // Success path
} catch (error) {
  console.error('Failed to create agent:', (error as Error).message);
}

const result = await Agent.create({ name: 'my-service', registry, transport });
if (result.ok) {
  const agent = result.value;
} else {
  console.error('Error:', result.error);
}

Just-in-Time Registration (JITR)

xBind implements Just-in-Time Registration following AWS IoT JITR, OAuth DCR (RFC 7591), and MCP 2025 standards. Agents created with Agent.fromSeed() automatically register with the trust registry on first use — no manual registration scripts required.

The trust registry accepts all cryptographic key types: Ed25519 signing keys, X25519 encryption keys, ML-KEM-768 post-quantum key encapsulation, and ML-DSA-65 signatures. Complete identity registration ensures recipients can send encrypted messages immediately without configuration errors.

Creating Agents (Three Patterns)

Beyond quickstart, the xBind Agent ACI supports three creation patterns for different deployment contexts: explicit identity, lazy initialization, and invite-based onboarding.

Pattern 1: Explicit Identity (Full Control)

import { generateIdentity, Agent } from '@private.me/xbind';

// Generate identity first
const idResult = await generateIdentity();
if (!idResult.ok) throw idResult.error;
const identity = idResult.value;

// Create agent with explicit identity
const agent = new Agent({
  name: 'payments-service',
  identity: identity,
  trustRegistry: myRegistry,
  transport: myTransport
});

// Identity can be persisted to disk/env for reuse
process.env.AGENT_DID = identity.did;
process.env.AGENT_PRIVATE_KEY = Buffer.from(identity.privateKey).toString('base64');

Pattern 2: Lazy Initialization (Auto-Generate)

import { Agent } from '@private.me/xbind';

// Create lazy agent (no identity yet)
const agent = Agent.lazy({ name: 'my-service' });

// Identity generated automatically on first send
await agent.send({ to: recipientDid, payload: {...}, scope: 'data' });

Pattern 3: Invite-Based (Environment Variable)

// .env file
XBIND_INVITE_CODE=XLK-abc123def456

// Code
const agent = Agent.lazy({ name: 'my-service' });

// SDK auto-accepts invite and configures trust on first send
await agent.send({ to: partnerDid, payload: {...}, scope: 'integration' });

Tool Discovery with agent.discover()

Agents can advertise capabilities (tools/actions they support) and discover other agents' capabilities. This enables dynamic service composition and reduces manual configuration.

// Service advertises capabilities
const agent = new Agent({
  name: 'payments-service',
  identity: identity,
  capabilities: [
    { name: 'createCharge', scopes: ['payments'] },
    { name: 'refundCharge', scopes: ['payments'] },
    { name: 'getBalance', scopes: ['payments:read'] }
  ]
});

// Other agents discover capabilities
const disco = await agent.discover('did:key:z6MkPayments...');
if (disco.ok) {
  console.log(disco.value.capabilities);
  // Output: ['createCharge', 'refundCharge', 'getBalance']

  // Check if service supports specific capability
  const canRefund = disco.value.capabilities.includes('refundCharge');
}

Per-Agent Policy Enforcement

Each agent instance can have its own policy configuration: allowed scopes, rate limits, message size limits, and trust rules. Policies are enforced at the agent level before messages reach the network.

import { Agent, MemoryTrustRegistry } from '@private.me/xbind';

const registry = new MemoryTrustRegistry();

// Register recipient with allowed scopes
await registry.register(
  recipientDid,
  recipientPublicKey,
  'Analytics Service',
  ['analytics'],                    // Can send analytics data
  undefined, undefined, undefined, false,
  ['payments', 'orders']            // Can receive payments + orders ONLY
);

const agent = new Agent({
  name: 'payments-service',
  identity: myIdentity,
  trustRegistry: registry,
  policy: {
    maxMessageSize: 1024 * 1024,          // 1 MB limit
    rateLimits: {
      maxPerMinute: 100,
      maxPerHour: 5000
    },
    allowedScopes: ['payments', 'orders'],
    requireMutualTrust: true                // Reject messages from unregistered DIDs
  }
});

// Policy enforced on send
const result = await agent.send({
  to: recipientDid,
  payload: { action: 'processOrder', ... },
  scope: 'payments'                       // OK: scope allowed by recipient
});

// This fails: scope not in recipient's receive list
const blocked = await agent.send({
  to: recipientDid,
  payload: {...},
  scope: 'admin'                           // ERROR: ScopeViolation
});

Audit Receipts (Proof of Delivery)

Every sent message can optionally return an audit receipt: a signed acknowledgment from the recipient proving they received and processed the message. Receipts include timestamps, message hashes, and processing status.

const result = await agent.send({
  to: recipientDid,
  payload: { action: 'createCharge', amount: 10000 },
  scope: 'payments',
  requestReceipt: true                      // Request signed receipt
});

if (result.ok && result.value.receipt) {
  const receipt = result.value.receipt;

  console.log('Receipt from:', receipt.signer);
  console.log('Message hash:', receipt.messageHash);
  console.log('Received at:', new Date(receipt.timestamp));
  console.log('Processing status:', receipt.status);

  // Verify receipt signature (automatic, but can verify again)
  const valid = await agent.verifyReceipt(receipt);
  console.log('Receipt valid:', valid.ok);

  // Store receipt for compliance/audit
  await auditLog.store(receipt);
}

Enterprise Integration: Cross-Platform Error Mappings

All xBind error codes include protocol-specific mappings for seamless integration with AWS IoT, gRPC services, and HTTP APIs. Each error provides standardized codes for cross-platform consistency.

Protocol Mappings

Every error code includes three standardized mappings:

• aws — AWS IoT error codes (e.g., RequestTimeout, InvalidParameterValue, ServiceUnavailable)
• grpc — gRPC status codes (e.g., 3=INVALID_ARGUMENT, 14=UNAVAILABLE, 4=DEADLINE_EXCEEDED)
• http — HTTP status codes (e.g., 400, 408, 503)

import { ERROR_DETAILS } from '@private.me/xbind';

// Access error mappings
const details = ERROR_DETAILS.TIMESTAMP_EXPIRED;

console.log(details.message); // Human-readable message
console.log(details.aws);     // 'RequestTimeout'
console.log(details.grpc);    // 4 (DEADLINE_EXCEEDED)
console.log(details.http);    // 408 (Request Timeout)
console.log(details.hint);    // Actionable recovery guidance

// Platform-specific error handling
const result = await agent.send({ to: recipientDid, payload });

if (!result.ok) {
  const errorInfo = ERROR_DETAILS[result.error];

  // AWS IoT integration
  await cloudwatch.putMetricData({
    MetricName: errorInfo.aws,
    Value: 1
  });

  // gRPC service response
  return {
    code: errorInfo.grpc,
    message: errorInfo.message
  };

  // HTTP API response
  res.status(errorInfo.http).json({
    error: result.error,
    message: errorInfo.message,
    hint: errorInfo.hint
  });
}

Agent ACI Reference (Core Methods)

const result = await agent.send({
  to: 'did:key:z6Mk...',
  payload: { message: 'Hello' },
  scope: 'messaging'
});

if (result.ok) {
  console.log('Message sent successfully');
  // No return value - just void
} else {
  console.error('Send failed:', result.error);
  // result.error is a string error code
}

Advanced Agent ACIs

Beyond the core Agent ACI, xBind exports specialized interfaces for advanced deployment patterns, custom integrations, and fine-grained control over agent lifecycle and security policies.

LazyAgent — Deferred Initialization

LazyAgent delays identity generation and trust registry setup until first use. Useful for serverless functions, CLI tools, and environments where startup time matters more than eager validation.

import { LazyAgent } from '@private.me/xbind';

// No identity generated yet
const agent = new LazyAgent({ name: 'background-processor' });

// Identity generated on first send/receive
await agent.send({ to: recipientDid, payload: {...} });

AgentBuilder — Fluent Configuration

AgentBuilder provides a chainable API for constructing agents with complex configurations. Useful when multiple optional parameters need to be set conditionally.

import { AgentBuilder } from '@private.me/xbind';

const agent = new AgentBuilder()
  .withName('analytics-pipeline')
  .withTrustRegistry(registry)
  .withTransport(transport)
  .withPolicy({ maxPayloadSize: 10_000_000 })
  .enableAuditTrail()
  .build();

InvitationClient — Invite Flow Management

InvitationClient handles the complete invitation lifecycle: code generation, email delivery, acceptance tracking, and trust establishment. Used internally by Agent.lazy() but exposed for custom onboarding flows.

import { InvitationClient } from '@private.me/xbind';

const client = new InvitationClient({ gatewayUrl });

// Generate invite code (6-char, 24h TTL)
const result = await client.generateInvite({
  recipientEmail: 'partner@example.com',
  scope: 'integration',
  ttlHours: 24
});

// Accept invite from recipient side
const accepted = await client.acceptInvite({
  inviteCode: 'XLK-abc123',
  recipientDid: agent.did
});

PairingManager — QR Code Pairing

PairingManager implements the QR code connection model with proximity verification. Generates scannable codes with 60-second TTL, validates physical proximity, and establishes mutual trust after user confirmation.

import { PairingManager } from '@private.me/xbind';

const manager = new PairingManager({ agent });

// Device A: Generate QR code
const qrData = await manager.generatePairingCode();
displayQRCode(qrData.qrCodeDataUrl);  // Show to user

// Device B: Scan and pair
const scanned = await manager.scanPairingCode(qrCodeData);
if (scanned.ok) {
  // Trust established after both sides confirm
  console.log('Paired with:', scanned.value.peerDid);
}

MdnsDiscoveryManager — Local Network Discovery

MdnsDiscoveryManager broadcasts and discovers agents on the local network via mDNS/Bonjour. Useful for IoT devices, offline-first applications, and LAN-based coordination without a central gateway.

import { MdnsDiscoveryManager } from '@private.me/xbind';

const discovery = new MdnsDiscoveryManager({ agent });

// Advertise this agent on LAN
await discovery.advertise({
  serviceName: 'sensor-hub',
  capabilities: ['temperature', 'humidity']
});

// Discover other agents
const peers = await discovery.discover({ timeout: 5000 });
peers.forEach(peer => {
  console.log('Found:', peer.did, peer.capabilities);
});

HTTP Client Compatibility Adapters

createAxiosCompat() and createGotCompat() wrap xBind agent messaging in familiar HTTP client interfaces. Allows gradual migration from API key-based HTTP clients to cryptographic identity without rewriting application logic.

import { createAxiosCompat } from '@private.me/xbind';

// Create axios-compatible client backed by xBind
const client = createAxiosCompat(agent);

// Use like axios (authenticated via DID signatures)
const response = await client.post('/api/charge', {
  amount: 100,
  currency: 'usd'
});

console.log(response.data);  // Standard axios response

DualModeAdapter — API Key Fallback

DualModeAdapter enables gradual migration by supporting both xBind cryptographic auth and legacy API key auth simultaneously. Attempts xBind first, falls back to API key if recipient doesn't support xBind.

import { DualModeAdapter } from '@private.me/xbind';

const adapter = new DualModeAdapter({
  agent: myAgent,
  apiKey: process.env.LEGACY_API_KEY,
  preferXBind: true
});

// Automatically uses xBind if recipient supports it
// Falls back to API key auth if not
const result = await adapter.call('service:action', payload);

PolicyEngine & Guardrails

PolicyEngine enforces constraint rules on outbound messages (payload size limits, allowed recipients, rate limits). Guardrails enriches error messages with hints and documentation links for common failure modes.

import { PolicyEngine, Guardrails } from '@private.me/xbind';

const policy = new PolicyEngine({
  maxPayloadSize: 5_000_000,        // 5 MB limit
  allowedRecipients: ['did:key:z6Mk...'],
  rateLimit: { maxPerMinute: 60 }
});

const agent = new Agent({
  name: 'api-gateway',
  policy: policy,
  guardrails: new Guardrails()  // Enhanced error messages
});

When to Use the Agent ACI vs Lower-Level APIs

The Agent ACI handles 95% of use cases. For IoT, embedded systems, and custom protocols, see Integration Patterns for lower-level APIs like createSignedEnvelope() and splitForChannel().

Trust Configuration

Configure trust infrastructure with push-based revocation notifications, cache failure modes, and bloom filter bandwidth optimization. The HttpTrustRegistry supports real-time trust events for immediate enforcement of key revocations and rotations.

import { connect, HttpTrustRegistry } from '@private.me/xbind';

const agent = await connect({
  did: 'did:key:z6Mk...',
  trustRegistry: new HttpTrustRegistry({
    gatewayUrl: 'https://gateway.private.me',
    cacheTtlMs: 30_000,              // 30-second cache TTL
    cacheFailureMode: 'fail-secure', // Reject on cache miss (default)
    enablePush: true,                // WebSocket notifications
    bloomFilterSize: 10_000,         // Bandwidth optimization: reduce query overhead for 10k subscriptions
    bloomFilterFpr: 0.01             // 1% false positive rate (trade memory vs network round-trips)
  })
});

// Subscribe to revocation/rotation events
const unsubscribe = await agent.subscribeTrustEvents([
  'did:key:z6Mk...',  // Monitor specific DIDs
  'did:key:z6Mp...'
]);

// Rotate DID with succession proof
await agent.rotateDid({
  oldDid: 'did:key:z6MkOld...',
  newDid: 'did:key:z6MkNew...',
  gracePeriodMs: 7 * 24 * 60 * 60 * 1000  // 7 days
});

Cache Failure Modes

Configure behavior during network partitions when cache refresh fails.

// Reject messages if cache refresh fails during network partition
const registry = new HttpTrustRegistry({
  gatewayUrl: 'https://gateway.private.me',
  cacheFailureMode: 'fail-secure'  // Default behavior
});

// Accept messages using stale cache (trade security for availability)
const registry = new HttpTrustRegistry({
  gatewayUrl: 'https://gateway.private.me',
  cacheFailureMode: 'fail-open'
});

Retry Configuration

Wrap any transport adapter with exponential backoff retry logic for resilient push notification delivery.

import { RetryTransportAdapter } from '@private.me/xbind';

const transport = new RetryTransportAdapter(baseTransport, {
  maxRetries: 3,        // Exponential backoff: 1s, 2s, 4s
  baseDelayMs: 1000,
  maxJitterMs: 200      // ±200ms randomization
});

Python SDK

Complete Python bindings provide full access to xBind's identity and messaging capabilities. The Python SDK wraps the Node.js implementation with native Python interfaces, enabling Python-based AI agents, data pipelines, and automation scripts to use cryptographic M2M authentication.

Installation

The Python SDK wraps the Node.js implementation using subprocess execution. Node.js must be installed first as a runtime prerequisite.

# Step 1: Install Node.js package (required dependency)
npm install -g @private.me/xbind

# Step 2: Install Python package
pip install private-me-xbind

# Step 3: Verify installation
python -c "from private_me.xbind import Agent; print('xBind Python SDK ready')"

Quick Start (Python)

from private_me.xbind import Agent

# Create agent from private key
agent = Agent.from_private_key(private_key_bytes)

# Send authenticated message
result = agent.send(
    to='did:peer:recipient123',
    payload={
        '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']}")

Agent Creation Patterns (Python)

from private_me.xbind import Agent, generate_identity

# Pattern 1: Quickstart (auto-generate identity)
agent = Agent.quickstart(name='my-service')

# Pattern 2: Explicit identity
identity = generate_identity()
agent = Agent(
    name='payments-service',
    identity=identity,
    trust_registry=my_registry
)

# Pattern 3: From existing private key
agent = Agent.from_private_key(
    private_key=key_bytes,
    name='analytics-service'
)

Multi-Agent Coordination (Python)

from private_me.xbind import connect

# Create two agents
alice = Agent.quickstart(name='alice')
bob = Agent.quickstart(name='bob')

# Establish connection
result = connect(alice, bob)
if result['ok']:
    print("Agents connected successfully")

# Send encrypted message from Alice to Bob
message_result = alice.send(
    to=bob.did,
    payload={'action': 'processData', 'data': [1, 2, 3]},
    scope='integration'
)

# Bob receives and verifies
if message_result['ok']:
    envelope = message_result['envelope']
    received = bob.receive(envelope)
    print(f"Verified sender: {received['sender']}")
    print(f"Payload: {received['payload']}")

Error Handling (Python)

Python SDK returns dictionaries with 'ok' boolean field for Result pattern compatibility. All error codes from the TypeScript implementation are preserved with detailed messages.

from private_me.xbind import Agent, XBindError
from typing import Dict, Any

def process_with_retry(agent: Agent, recipient_did: str, payload: Dict[str, Any]) -> bool:
    result = agent.send(to=recipient_did, payload=payload)

    if result['ok']:
        data = result['data']
        audit = result['audit']
        print(f"Success: {data}")
        print(f"Signed by: {audit['agent']}")
        return True
    else:
        error = result['error']
        print(f"Error code: {error['code']}")
        print(f"Message: {error['message']}")

        # Retry on network errors
        if error['code'].startswith('TRANSPORT_'):
            return process_with_retry(agent, payload)  # Retry

        return False

What xBind Eliminates

Identity-based auth removes entire classes of operational burden. No keys to distribute, rotate, or revoke. No shared secrets to leak. No cascading failures when tokens expire.

Operations Patterns

Production-ready observability and reliability patterns. Health checks, graceful degradation, and circuit breakers ensure continuous operation even when dependencies fail.

Health Check Endpoint

Kubernetes-compatible health probes for operational monitoring. Three probe types provide comprehensive service health visibility: startup (one-time initialization check), liveness (basic responsiveness), and readiness (dependency availability).

import { createHealthChecker, healthEndpoint } from '@private.me/xbind';

const checker = createHealthChecker({
  registry: myTrustRegistry,
  transport: myTransport,
  serviceName: 'xbind-gateway',
  timeoutMs: 3000
});

// Kubernetes-compatible endpoints
app.get('/health/startup', healthEndpoint(checker, 'startup'));
app.get('/health/liveness', healthEndpoint(checker, 'liveness'));
app.get('/health/readiness', healthEndpoint(checker, 'readiness'));

// Mark initialization complete after setup
await agent.register();
checker.markStartupComplete();

Response format (readiness probe):

{
  "healthy": true,
  "timestamp": "2026-05-28T12:34:56.789Z",
  "uptimeSeconds": 120,
  "components": [
    {
      "name": "registry",
      "status": "healthy",
      "latencyMs": 15
    },
    {
      "name": "transport",
      "status": "healthy",
      "latencyMs": 1
    }
  ]
}

Graceful Degradation

Quality-of-service controls and intelligent fallback mechanisms maintain service continuity during transient failures. Operations are tagged with QoS levels (CRITICAL, HIGH, NORMAL, LOW) to control retry behavior and cache usage.

import { registryLookupWithFallback, GracefulDegradationManager } from '@private.me/xbind';

const manager = new GracefulDegradationManager({
  defaultTTL: 600_000,      // 10 minutes cache
  maxStaleMs: 7200_000,    // 2 hours max staleness
  allowStale: true          // Use stale cache for NORMAL/LOW QoS
});

const result = await registryLookupWithFallback(
  trustRegistry,
  'did:key:z6MkExample',
  { qos: 'HIGH', type: 'registry:lookup' },
  manager
);

if (result.ok) {
  console.log('DID resolved:', result.value.publicKey);
} else {
  // Error is a string error code
  console.error(result.error);
}

QoS level behaviors:

Circuit Breaker Pattern

Automatic fault tolerance protects applications from cascading failures. Circuit breakers monitor external service health (registry, gateway, S3) and automatically "open" after repeated failures, failing fast instead of repeatedly attempting doomed calls. Three-state machine (CLOSED → OPEN → HALF_OPEN) provides automatic recovery.

import { CircuitBreakerManager } from '@private.me/xbind/circuit-breaker';

// Manager creates pre-configured breakers (registry, gateway, s3)
const manager = new CircuitBreakerManager();

// Protected registry call
const result = await manager.executeRegistry(async () => {
  return await registry.lookup(did);
});

// Protected gateway call
const sendResult = await manager.executeGateway(async () => {
  return await gateway.send(envelope);
});

// Monitor circuit health
const metrics = manager.getAllMetrics();
console.log('Registry state:', metrics.registry.state);  // CLOSED | OPEN | HALF_OPEN

State machine transitions:

Security Audit Preparation

Comprehensive audit-ready documentation with STRIDE threat model, cryptographic claims, and known limitations. 5,833 lines of security analysis prepared for third-party review.

STRIDE Threat Model Analysis

Complete threat analysis using the STRIDE framework (Spoofing, Tampering, Repudiation, Information Disclosure, Denial of Service, Elevation of Privilege). 66 identified threats across 6 categories with documented mitigations.

Cryptographic Claims Documentation

41 cryptographic claims documented with mathematical proofs, implementation references, and test coverage. Each claim specifies the security property, mechanism, and verification procedure.

// CLAIM: Hybrid key agreement provides 128-bit classical + 192-bit PQ security
// MECHANISM: X25519 ECDH + ML-KEM-768 combined via HKDF-SHA256
// VERIFICATION:
//   1. X25519 produces 32-byte shared secret (classical security)
//   2. ML-KEM-768 produces 32-byte shared secret (PQ security)
//   3. HKDF combines both: HKDF(x25519_secret || mlkem_secret)
//   4. Attacker must break BOTH to compromise session key
// TEST COVERAGE: src/__tests__/hybrid-kem.test.ts (43 tests)

const { sharedSecret } = await deriveSharedSecret(
  x25519PublicKey,
  mlkemCiphertext,
  recipientPrivateKeys
);
// sharedSecret is 32 bytes, cryptographically bound to both algorithms

Known Limitations and Residual Risks

24 documented limitations with honest disclosure of trade-offs. Auditors receive complete picture of security properties and boundaries.

Vendor Guidance and Deliverables

Audit preparation document recommends qualified vendors (NCC Group, Trail of Bits, Kudelski Security) and specifies deliverables: cryptographic review, implementation analysis, protocol security assessment, penetration testing, and final security report.

Advanced ACI Features

14 developer experience features for production-grade messaging. Batch operations, async iterators, cancellation, progress tracking, retry strategies, and more.

Batch Operations (6-8x Speedup)

Process multiple operations in parallel with automatic concurrency control. Reduces latency from sequential round-trips to parallelized execution.

import { batchSend } from '@private.me/xbind';

const recipients = ['did:key:alice', 'did:key:bob', 'did:key:carol'];
const results = await batchSend(agent, recipients, {
  payload: { message: 'Notification' },
  maxConcurrency: 10,  // Parallel execution limit
  continueOnError: true  // Don't stop on individual failures
});

// Results array matches input order
results.forEach((result, i) => {
  if (result.ok) {
    console.log(`Sent to ${recipients[i]}`);
  } else {
    console.error(`Failed ${recipients[i]}: ${result.error}`);
  }
});

Async Iterators (for await...of)

Stream-process large result sets without loading entire collection into memory. Ideal for paginated registry queries and message archives.

import { streamRegistryLookups } from '@private.me/xbind';

const dids = [...];  // Large array of DIDs

for await (const entry of streamRegistryLookups(registry, dids)) {
  if (entry.ok) {
    processEntry(entry.value);  // Process one at a time
  }
  // Memory usage stays constant regardless of array size
}

Cancellation Tokens (AbortController)

Cancel long-running operations using standard AbortController API. Works across all async xBind operations.

const controller = new AbortController();

// Start long operation
const sendPromise = agent.send({
  to: recipientDid,
  payload: largeData,
  signal: controller.signal  // Pass abort signal
});

// Cancel after 5 seconds
setTimeout(() => controller.abort(), 5000);

try {
  await sendPromise;
} catch (err) {
  if (err.name === 'AbortError') {
    console.log('Operation cancelled');
  }
}

Progress Callbacks

Track operation progress for long-running tasks. Four tracker types: percentage, item count, byte transfer, stage progression.

await batchSend(agent, recipients, {
  payload: data,
  onProgress: (progress) => {
    console.log(`${progress.completed}/${progress.total} sent`);
    updateProgressBar(progress.percentage);  // 0-100
  }
});

Retry Strategies

Automatic retry with exponential backoff, jitter, and circuit breaker integration. Four built-in strategies: exponential, linear, constant, custom.

import { retryWithBackoff } from '@private.me/xbind';

const result = await retryWithBackoff(
  async () => await agent.send({ to: did, payload: data }),
  {
    maxAttempts: 5,
    initialDelayMs: 1000,   // Start with 1s delay
    backoffMultiplier: 2,    // Double each retry
    maxDelayMs: 30000,       // Cap at 30s
    jitter: true              // Randomize delays ±25%
  }
);

Request Timeouts

Per-operation timeout configuration prevents hung requests. Integrates with circuit breakers and retry strategies.

const result = await agent.send({
  to: recipientDid,
  payload: data,
  timeoutMs: 5000  // Fail after 5 seconds
});

if (!result.ok && result.error === 'TIMEOUT') {
  console.error('Request timed out');
}

Event Emitters (Type-Safe)

Listen to agent lifecycle events: message sent/received, connection established, errors, state changes. Type-safe event payloads with TypeScript.

import { Agent } from '@private.me/xbind';

const agent = await Agent.create({ name: 'listener' });

// Type-safe event handlers
agent.on('message:sent', (event) => {
  console.log(`Sent to ${event.recipient}`);
});

agent.on('message:received', (event) => {
  console.log(`Received from ${event.sender}`);
});

agent.on('error', (event) => {
  console.error(`Error: ${event.message}`);
});

Config Validation

Schema-based validation for agent configuration. Catches errors at startup instead of runtime.

import { validateConfig, Agent } from '@private.me/xbind';

const config = {
  name: 'my-agent',
  registry: { url: 'https://private.me/aci/registry' },
  policy: { maxPayloadSize: 10_000_000 }
};

// Validate before agent creation
const validation = validateConfig(config);
if (!validation.ok) {
  console.error('Invalid config:', validation.errors);
  process.exit(1);
}

const agent = await Agent.create(config);  // Guaranteed valid

Debug Mode

Detailed operation tracing with profiling and distributed tracing support. Toggle debug mode at runtime without restarting.

import { Agent, enableDebugMode } from '@private.me/xbind';

// Global debug mode
enableDebugMode({
  logLevel: 'trace',        // trace | debug | info
  profiling: true,           // Measure operation latency
  tracing: true,             // Distributed trace headers
  includeStackTraces: true   // Error stack traces
});

const agent = await Agent.create({ name: 'debug-agent' });
await agent.send({ to: did, payload: data });

// Output includes detailed traces:
// [TRACE] agent.send() starting (correlationId: abc123)
// [TRACE]   envelope.create() - 2.3ms
// [TRACE]   registry.lookup() - 15.1ms
// [TRACE]   transport.send() - 42.7ms
// [TRACE] agent.send() complete - 60.1ms total

Version Info & Capability Detection

Runtime version checking and capability detection. Enables forward-compatible code that adapts to available features.

import { getVersionInfo, hasCapability } from '@private.me/xbind';

const version = getVersionInfo();
console.log(`xBind v${version.version}`);
console.log(`Build date: ${version.buildDate}`);

// Feature detection
if (hasCapability('ml-kem-768')) {
  // Use post-quantum key agreement
  await agent.send({ ..., quantumSafe: true });
} else {
  // Fallback to X25519 only
  await agent.send({ ... });
}

Connection Pooling (60-70% Latency Reduction)

Reuse HTTP connections across operations. Reduces latency from TCP handshake and TLS negotiation overhead.

import { Agent, HttpTransport } from '@private.me/xbind';

const transport = new HttpTransport({
  pooling: {
    enabled: true,
    maxSockets: 50,          // Max connections per host
    keepAlive: true,          // Reuse TCP connections
    keepAliveMsecs: 30000    // 30s idle timeout
  }
});

const agent = await Agent.create({ transport });

// First request: ~100ms (TCP handshake + TLS)
// Subsequent requests: ~30ms (connection reused)

Serialization (JSON / MessagePack / CBOR)

Multiple serialization formats for different use cases. JSON for debugging, MessagePack for bandwidth efficiency, CBOR for IoT.

import { Agent, MessagePackSerializer } from '@private.me/xbind';

const agent = await Agent.create({
  serializer: new MessagePackSerializer()
});

// Payloads automatically serialized to MessagePack
await agent.send({
  to: recipientDid,
  payload: { large: 'object', with: ['arrays'] }
});

// 30-50% smaller than JSON, faster parsing

Key Rotation (Succession API)

Rotate cryptographic identities securely using the Succession protocol. Supports dual signatures (old + new keys), grace periods, and sequence numbers to prevent rollback attacks.

import { Agent, createSuccession, verifySuccession } from '@private.me/xbind';

// Generate new identity
const newAgent = await Agent.quickstart({ name: 'service-v2' });

// Create succession announcement (dual signed by old + new keys)
const succession = await createSuccession(
  oldAgent.did,              // Old DID being rotated
  oldAgent.mlDsaPrivateKey,  // Old ML-DSA-65 key
  newAgent.did,              // New DID
  newAgent.mlDsaPrivateKey,  // New ML-DSA-65 key
  1,                         // Rotation sequence number
  7 * 24 * 60 * 60 * 1000  // 7-day grace period
);

// Broadcast succession to all peers
await registry.announceSuccession(succession.value);

// Peers verify dual signatures before updating trust
const valid = await verifySuccession(
  announcement,
  oldPublicKey,  // Verify old key signed
  newPublicKey   // Verify new key signed
);

if (valid.ok) {
  registry.updateDid(oldDid, newDid);  // Trust updated
}

Features: Dual signatures prevent spoofing, sequence numbers prevent rollback, grace periods allow gradual migration, 30-day proof validity, fork detection.
Use case: Compromised identity recovery, scheduled key rotation, organizational handoffs.

Agent.call() for Tool Invocation

High-level API for AI agents to call tools and services with automatic identity management, security policy enforcement, audit receipts, and structured error handling. Every call produces a cryptographically signed audit trail — no configuration required.

import { call, setToolRegistry } from '@private.me/xbind';

// Set global tool registry
setToolRegistry(registry);

// Call a tool with automatic DID resolution
const result = await call('stripe:createCharge', {
  amount: 100,
  currency: 'usd'
}, {
  policy: {
    limits: {
      amountPerTxn: 500,     // Max $500 per transaction
      dailyAmount: 5000       // Max $5000 per day
    }
  },
  onProgress: (event) => {
    console.log(`Step: ${event.step}, ${event.progress}%`);
  }
});

if (result.ok) {
  console.log(result.value.data);        // Tool response
  console.log(result.value.audit);       // Audit receipt
  console.log(result.value.formats.json); // Structured output
}

SecurityMode

Every call() selects a transport security mode. The policy engine chooses automatically based on risk classification, or you can override explicitly. Three modes cover the full spectrum from development to regulated production.

import { call } from '@private.me/xbind';

// standard — direct transport, lowest latency
const fast = await call('analytics:track', params, {
  mode: { type: 'standard' }
});

// split — 2-of-3 split-channel transport (XorIDA)
const secure = await call('payments:charge', params, {
  mode: { type: 'split', shares: 3, threshold: 2 }
});

// xchange — full key-exchange transport
const regulated = await call('compliance:submit', params, {
  mode: { type: 'xchange' }
});

PolicyConstraints

Constrain what an agent can do before the call executes. Rate limits cap spend, allowed tools restrict scope, and data filters redact sensitive fields from responses. Policy violations are blocked before any data leaves the process.

const result = await call('crm:searchContacts', { query: 'john' }, {
  policy: {
    allowedTools: ['crm:searchContacts', 'crm:getContact'],
    scopes: ['contacts:read'],
    limits: {
      callsPerMinute: 60,
      amountPerTxn: 1000,
      dailyAmount: 10000,
      monthlyAmount: 50000
    },
    dataFilters: [
      { field: 'user.ssn',   action: 'remove' },
      { field: 'user.email', action: 'hash' },
      { field: 'user.phone', action: 'redact' }
    ]
  }
});

AuditReceipt

Every call() returns a signed audit receipt recording who called what, when, under which policy, with cryptographic proof. Receipts are attached to the result — no separate logging infrastructure needed.

const result = await call('payments:charge', { amount: 50 });

if (result.ok) {
  const { audit } = result.value;
  console.log(audit.agent);           // "did:privateme:z6Mk..."
  console.log(audit.agentName);       // "payment-service"
  console.log(audit.tool);            // "payments:charge"
  console.log(audit.scope);           // "payments"
  console.log(audit.timestamp);       // "2026-06-12T..."
  console.log(audit.signature);       // "valid"
  console.log(audit.policy);          // "passed"
  console.log(audit.policyConstraints); // { limits: { ... } }
}

Error Handling

Failed calls return typed errors with machine-readable codes, human-readable context, root cause analysis, and suggested fixes. Six error codes cover the complete failure space.

import { call, AgentErrorCode, ERROR_DETAILS } from '@private.me/xbind';

const result = await call('payments:charge', { amount: 99999 });

if (!result.ok) {
  const { code, message } = result.error;
  const details = ERROR_DETAILS[code];

  console.log(code);            // AgentErrorCode.POLICY_VIOLATION
  console.log(message);         // "Amount 99999 exceeds limit 500"
  console.log(details.context); // "The operation was blocked by policy constraints"
  console.log(details.cause);   // "Request exceeds spending limits..."
  console.log(details.fix);     // "Reduce transaction amount..."
}

// All error codes:
// TOOL_NOT_FOUND        — tool alias not in registry
// POLICY_VIOLATION      — blocked by rate/spend/scope limits
// TIMEOUT               — response deadline exceeded
// NETWORK_ERROR         — transport failure
// AUTHENTICATION_FAILED — DID rejected or signature invalid
// INVALID_PARAMS        — schema validation failed

ResultFormats

Every successful result includes four output formatters optimized for different consumption patterns — from compact status lines to structured JSON for programmatic access.

const result = await call('crm:getContact', { id: 'c-123' });

if (result.ok) {
  const { formats } = result.value;

  formats.multiline();   // Human-readable prose (logs, debugging)
  formats.singleline(); // Compact one-liner (status updates)
  formats.json();       // Raw JSON string (APIs, programmatic access)
  formats.markdown();   // Formatted markdown (documentation, reports)
}

Batch Tool Calls

Execute multiple tool calls in parallel with automatic concurrency control and failure isolation. Each call in the batch gets its own audit receipt and policy evaluation.

import { batchCall } from '@private.me/xbind';

// Execute multiple tool calls in parallel
const results = await batchCall([
  { tool: 'stripe:createCharge', params: { amount: 100 } },
  { tool: 'sendgrid:sendEmail', params: { to: 'user@example.com' } },
  { tool: 'analytics:track', params: { event: 'purchase' } }
]);

// Results array matches input order
results.forEach((result, i) => {
  if (result.ok) {
    console.log(`Call ${i} succeeded:`, result.value.data);
  } else {
    console.error(`Call ${i} failed:`, result.error);
  }
});

Streaming Responses

Stream long-running tool responses using async iterators. Ideal for LLM text generation, video processing, and large file transfers. Memory usage stays constant regardless of response size.

import { stream } from '@private.me/xbind';

// Stream tokens from LLM
for await (const chunk of stream('llm:chat', {
  model: 'default',
  prompt: 'Explain quantum computing'
})) {
  if (chunk.ok) {
    process.stdout.write(chunk.value);  // Stream to output
  }
}

// Memory usage stays constant regardless of response size

Security Properties

Seven layers of defense. Each independently verifiable.

Revocation and Rotation

30-second exposure window: Cache TTL limits maximum delay between revocation and enforcement.

Fail-secure default: Network partitions default to reject (no silent security degradation).

Dual-signature succession: Both old and new keys must sign rotation announcement (prevents key substitution attacks).

Post-quantum signatures: ML-DSA-65 resists quantum attacks on continuity proofs.

import { MemoryTrustRegistry } from '@private.me/xbind';

const registry = new MemoryTrustRegistry();

// Register sender with send scopes
await registry.register(
  senderDid,
  senderPublicKey,
  'Payment Service',
  ['payments', 'orders'],           // Send scopes
  undefined, undefined, undefined, false,
  ['payments', 'receipts'],         // Receive scopes (accepts only these)
);

// Register receiver with receive scopes
await registry.register(
  receiverDid,
  receiverPublicKey,
  'Analytics Service',
  ['analytics'],                    // Send scopes
  undefined, undefined, undefined, false,
  ['payments'],                     // Receive scopes (accepts only payments data)
);

import { Agent } from '@private.me/xbind';

// Standard mode: AES-256-GCM + Ed25519 + ML-DSA-65
await agent.send({
  to: recipientDID,
  payload: data,
  scope: 'regular',
  security: 'standard'  // Default
});

// Forward Secrecy: + X25519 ECDH + ML-KEM-768
await agent.send({
  to: recipientDID,
  payload: data,
  scope: 'sensitive',
  security: 'high'  // When both parties publish X25519 keys
});

// Split-Channel: + XorIDA (information-theoretic)
await agent.send({
  to: recipientDID,
  payload: highValueData,
  scope: 'financial',
  security: 'critical'  // Shards via threshold sharing (2-of-3)
});

Supply Chain Security

Zero runtime dependencies from npm. All external code is vendored directly into the package:

• mlkem (ML-KEM-768 WASM) — Vendored for deterministic builds
• mldsa-wasm (ML-DSA-65 WASM) — Vendored for post-quantum signatures
• Internal packages (@private.me/crypto, @private.me/xchange, @private.me/shared) — Vendored for IP protection

Benefits: No npm registry attacks (event-stream, ua-parser-js incidents). Full auditability (one package to audit). Air-gapped deployments (works fully offline). Deterministic builds (reproducible for compliance). Typical enterprise SDKs have 150-200+ dependencies — xBind has zero.

Comparison to Alternatives

Deployment Root Key

A client-generated Ed25519 keypair that serves as a persistent, device-independent trust anchor. Every agent gets a root key that binds its identity across sessions, restarts, and device migrations — a cryptographic birth certificate for an agent.

The Problem

Before DRK, agent identity was tied to ephemeral sessions or device fingerprinting. If an agent restarted, moved to a new server, or scaled horizontally, it lost identity continuity. Enterprise customers running fleets of 10,000+ agents could not guarantee which agent was which after infrastructure changes — container restarts, auto-scaling events, blue-green deployments.

How It Works

• generateRootKey() creates an Ed25519 keypair (32-byte public key, CryptoKey private key)
• The root key derives a did:key:z6Mk... identifier that never changes
• Every outgoing envelope is signed via the rootKeySignature field in Envelope v5
• Receivers call verifyDeploymentRoot() to validate the binding
• Root keys support rotation with sequence tracking — old key signs handoff to new key, creating an unbroken chain of custody
• DRP (Deployment Root Protocol) performs 6 verification checks: key presence, DID validity, registry registration, revocation status, expiry, and binding integrity

interface DeploymentRootKey {
  readonly publicKey: Uint8Array;       // Ed25519 public key (32 bytes)
  readonly privateKey: CryptoKey;      // Ed25519 private key
  readonly rawPublicKey: Uint8Array;   // Raw public key for export
  readonly did: string;              // did:key:z6Mk... derived from publicKey
  readonly createdAt: number;         // Timestamp (ms since epoch)
  readonly rotationSequence: number;  // Monotonically increasing (0 = initial)
}

import { generateRootKey, signWithRootKey, verifyDeploymentRoot,
         MemoryRootKeyStore, MemoryTrustRegistry } from '@private.me/xbind';

// Generate a persistent root key for this deployment
const rootResult = await generateRootKey();
if (!rootResult.ok) throw new Error(rootResult.error);
const rootKey = rootResult.value;
console.log('Root DID:', rootKey.did);

// Persist across restarts
const store = new MemoryRootKeyStore();
await store.save(rootKey);

// Sign an envelope's critical fields
const sig = await signWithRootKey(rootKey, {
  sender: rootKey.did,
  recipient: 'did:key:z6MkRecipient...',
  timestamp: Date.now(),
  nonce: 'unique-nonce',
});

// Receiver verifies the root key binding
const registry = new MemoryTrustRegistry();
const verification = await verifyDeploymentRoot(envelope, registry);
if (verification.ok && verification.value.valid) {
  console.log('Verified: signed by', verification.value.rootDid);
}

Why This Matters

Fleet operators need to know that agent-7429 today is the same agent-7429 from yesterday, even if the container was replaced. DRK provides cryptographic proof of identity continuity without relying on infrastructure state (hostnames, IPs, container IDs). Root key rotation ensures long-term deployments can refresh keys without losing identity lineage — the sequence counter creates an unbroken chain from original key to current key.

Envelope v5 Format

The fifth generation of xBind’s transport envelope. Extends v4 with optional fields for delegation, provenance, taint tracking, and influence authorization. Fully backward compatible — a v5 envelope with no new fields is a valid v4 envelope.

The Problem

As agent systems grow more complex, envelopes need to carry more than a payload and signature. Enterprise workflows require delegation chains (who authorized this agent to act?), audit trails (who touched this message and when?), data lineage tracking (is this payload derived from PII?), and authorization proofs (does this agent have permission to influence this decision?). Envelope v4 had no extensible metadata structure for these concerns.

How It Works

• All new fields are optional — existing v4 code ignores them
• Each field is independently verifiable — check delegation without checking provenance
• v5 envelopes received by v4 agents are processed normally (unknown fields ignored)
• All v5-specific fields are covered by the Ed25519 signature (tamper-proof)

interface TransportEnvelopeV5 extends TransportEnvelopeV4 {
  readonly v: 5;

  // Deployment Root Key binding (Section: DRK)
  readonly rootKeySignature?: string;
  readonly rootDid?: string;
  readonly rootRotationSequence?: number;

  // Delegation chain (Section: Delegation)
  readonly delegation?: DelegationChain;

  // Provenance trail (Section: Provenance)
  readonly provenance?: ProvenanceEntry[];

  // Taint labels (Section: Taint Tracking)
  readonly taint?: TaintLabel[];

  // Influence authorization (Section: Influence Auth)
  readonly influenceAuth?: InfluenceToken;
}

import { createEnvelopeV5, validateEnvelopeV5, isEnvelopeV5 } from '@private.me/xbind';

// Create a v5 envelope with optional metadata
const result = await createEnvelopeV5({
  senderDid: agent.did,
  recipientDid: recipient.did,
  scope: 'data-pipeline',
  plaintext: new TextEncoder().encode(payload),
  privateKey: agent.identity.privateKey,
  sharedKey: derivedKey,
  provenance: provenanceChain,  // Audit trail
  taint: [piiLabel],            // Data lineage
});

// Validate a received v5 envelope
const validated = validateEnvelopeV5(parsed);
if (validated.ok) {
  console.log('Delegation:', validated.value.delegation);
  console.log('Provenance hops:', validated.value.provenance?.length);
}

Why This Matters

Regulated industries (finance, healthcare, government) require envelope-level metadata for compliance. SOC 2 auditors want provenance trails. HIPAA requires data lineage tracking. FedRAMP demands delegation accountability. Envelope v5 embeds all of this directly in the message format rather than requiring separate sidecar systems. One envelope, complete audit context.

Delegation Chains

Macaroon-style HMAC caveat chains for agent-to-agent authority transfer. Each delegation in the chain can only narrow permissions, never widen them — a compromised intermediate agent cannot escalate privileges.

The Problem

In enterprise agent systems, a manager agent often needs to delegate tasks to worker agents. Without delegation, the worker either needs full permissions (dangerous) or the manager must proxy every operation (bottleneck). There is no way to prove that agent C was authorized by agent B who was authorized by agent A, with each step having progressively narrower permissions.

How It Works

• Agent A creates a DelegationReceipt granting Agent B specific permissions with caveats
• Agent B can re-delegate to Agent C, but only with equal or narrower caveats
• Each receipt contains an HMAC chain link — tampering with any receipt is detectable
• The chain is embedded in the Envelope v5 delegation field
• Receivers call verifyDelegationChain() to validate the full chain from root to leaf

type Caveat =
  | { type: 'scope';  allowed: string[] }       // Restrict to specific scopes
  | { type: 'expiry'; notAfter: number }       // Must be ≤ parent's expiry
  | { type: 'rate';   maxPerMinute: number }   // Must be ≤ parent's rate
  | { type: 'data';   allowedFields: string[] } // Restrict accessible fields
  | { type: 'depth';  maxDepth: number };      // Limit re-delegation depth

interface DelegationChain {
  readonly receipts: DelegationReceipt[];  // Ordered: root → leaf
  readonly rootDid: string;              // Original delegator's DID
}

interface DelegationReceipt {
  readonly delegator: string;    // DID of entity granting authority
  readonly delegate: string;     // DID of entity receiving authority
  readonly caveats: Caveat[];    // Narrowing constraints
  readonly signature: string;   // Ed25519 over canonical receipt
  readonly hmac: string;        // HMAC chain (macaroon-style)
  readonly issuedAt: number;
  readonly expiresAt?: number;
}

import { createDelegationReceipt, createDelegationChain,
         verifyDelegationChain, MemoryTrustRegistry } from '@private.me/xbind';

// Manager delegates to worker with constraints
const receipt = await createDelegationReceipt({
  delegatorDid: manager.did,
  delegatorPrivateKey: manager.identity.privateKey,
  delegateDid: worker.did,
  caveats: [
    { type: 'scope', allowed: ['read:sensors'] },
    { type: 'expiry', notAfter: Date.now() + 3600000 },
    { type: 'rate', maxPerMinute: 10 },
  ],
});

// Build the chain
const chain = createDelegationChain(manager.did, [receipt.value]);

// Recipient verifies the full chain
const verification = await verifyDelegationChain(chain, registry);
if (verification.ok && verification.value.valid) {
  console.log('Root:', verification.value.rootDid);
  console.log('Leaf:', verification.value.leafDid);
  console.log('Effective caveats:', verification.value.effectiveCaveats);
}

Security Property: Narrowing-Only Enforcement

A compromised intermediate agent cannot escalate permissions. If agent B is compromised after receiving a delegation from A, it can only create sub-delegations with equal or fewer permissions — never more. The validateAttenuation() function enforces this mathematically: child scopes must be subsets, child expiry must be earlier, child rates must be lower. Widening attempts are rejected with specific violation details.

Provenance Chain

An append-only, cryptographically signed audit trail embedded in every envelope. Each agent that touches a message appends a signed entry, providing complete chain-of-custody from origin to destination.

The Problem

When a message passes through five agents in a pipeline, the final recipient has no way to answer: Who created this message? Who forwarded it? Was it modified along the way? Did it pass through an unauthorized intermediary? Traditional logging is external, forgeable, and often incomplete. There is no cryptographic proof of the message’s journey.

How It Works

• Each ProvenanceEntry contains: agent DID, action type, timestamp, Ed25519 signature, and SHA-256 hash of the previous entry
• The hash chain ensures integrity — removing or modifying any entry breaks the chain downstream
• Four action types: originate (first creation), forward (pass-through), transform (content modified), delegate (acting on behalf of another)
• appendProvenance() signs a new entry and chains it to the previous one
• verifyProvenanceChain() validates every signature and hash link in the chain

interface ProvenanceEntry {
  readonly agent: string;       // DID of this agent
  readonly action: 'originate' | 'forward' | 'transform' | 'delegate';
  readonly timestamp: number;
  readonly signature: string;   // Ed25519 over canonical(entry + parentHash)
  readonly parentHash?: string; // SHA-256 of previous entry (chain integrity)
  readonly metadata?: Record<string, unknown>;
}

import { appendProvenance, verifyProvenanceChain,
         extractAgentPath } from '@private.me/xbind';

// Agent A originates — first provenance entry (no parentHash)
let chain = await appendProvenance([], {
  agent: agentA.did,
  action: 'originate',
}, agentA.identity.privateKey);

// Agent B forwards — second entry, hash-linked to first
chain = await appendProvenance(chain.value, {
  agent: agentB.did,
  action: 'forward',
}, agentB.identity.privateKey);

// Agent C verifies the full chain
const verification = await verifyProvenanceChain(chain.value, registry);
if (verification.ok && verification.value.valid) {
  console.log('Chain verified:', chain.value.length, 'hops');
  console.log('Path:', extractAgentPath(chain.value));
  // ['did:key:z6MkA...', 'did:key:z6MkB...']
}

Why This Matters

SOC 2 Type II audits require complete data lineage. Healthcare systems under HIPAA need to prove who accessed patient data and when. Financial systems under SEC 17a-4 need immutable audit trails. Provenance chains provide all of this embedded in the message itself — no separate audit logging infrastructure needed. The proof is the message. Tampering with any entry is mathematically detectable because breaking one hash link invalidates the entire chain downstream.

Patent claims: C14 (append-only provenance), C17 (chain-of-custody verification).

Taint Label Tracking

Signed data lineage labels that propagate forward through message chains automatically. Once data is tainted, every derivative message carries the label — compliance requirements enforced at the transport layer.

The Problem

In complex agent pipelines, data from different sensitivity levels gets mixed. An agent might combine PII (customer names) with public data (weather reports) and forward the result. The downstream agent has no way to know the output contains PII. Manual classification does not scale to millions of messages per day.

How It Works

• Any agent can apply a TaintLabel with a category (e.g., pii, confidential, external, phi)
• The label includes the source DID, timestamp, and Ed25519 signature (proving who classified it)
• When a tainted message is forwarded or transformed, labels propagate to the outgoing envelope via propagateTaint()
• Labels merge across chains — if message A has pii and message B has confidential, a derivative carries both
• xBind handles propagation only — taint detection (scanning content to auto-apply labels) is a separate package

interface TaintLabel {
  readonly source: string;     // DID of agent that applied the label
  readonly category: string;   // e.g., 'pii', 'confidential', 'phi'
  readonly applied: number;    // Timestamp when label was applied
  readonly signature: string;  // Source signs the label
}

import { createTaintLabel, propagateTaint, hasTaint,
         getTaintCategories } from '@private.me/xbind';

// Apply a PII taint label
const label = await createTaintLabel(
  agent.did,                    // Who is classifying
  'pii',                         // Category
  agent.identity.privateKey,    // Signs the label
);

// When forwarding, taint propagates automatically
const outgoing = propagateTaint(
  incomingEnvelope.taint,  // Labels from incoming message
  [label.value],           // Plus our new label
);

// Downstream compliance agent can inspect
if (hasTaint(outgoing, 'pii')) {
  console.log('Contains PII-derived data');
  console.log('Categories:', getTaintCategories(outgoing));
  // Route to PII-compliant storage, apply retention policies
}

Why This Matters

GDPR requires knowing where personal data flows. HIPAA requires tracking PHI through every system. CMMC (defense) requires classified data handling. Taint tracking turns these compliance requirements from manual spreadsheet exercises into automatic, cryptographically signed, machine-readable metadata. A compliance agent at the edge of your network can automatically block PII-tainted data from leaving the perimeter — no human review needed.

Influence Authorization

Scope-based tokens controlling which agents can drive decisions. A signed, time-limited credential that proves “agent X has been authorized by agent Y to influence decisions in scope Z.”

The Problem

In autonomous agent systems, not every agent should influence every decision. A market data agent should provide price feeds but not execute trades. A summarization agent should read documents but not modify them. Without influence authorization, any agent that can send a message can influence any decision — no distinction between “providing information” and “authorized to drive action.”

How It Works

• issueInfluenceToken() creates a signed token with subject DID, allowed scopes, and TTL
• The subject attaches the token to envelopes via the influenceAuth field in Envelope v5
• Recipients call verifyInfluenceAuth() to check: valid signature? trusted issuer? correct scope? expired? issuer revoked?
• Tokens are time-limited — expired tokens are automatically rejected

interface InfluenceToken {
  readonly issuer: string;     // DID of authorizing agent
  readonly subject: string;    // DID authorized to influence
  readonly scopes: string[];   // What influence is authorized
  readonly issuedAt: number;
  readonly expiresAt: number;
  readonly signature: string;  // Issuer signs the token
}

import { issueInfluenceToken, verifyInfluenceAuth } from '@private.me/xbind';

// Manager authorizes analyst to provide recommendations (not execute)
const token = await issueInfluenceToken(
  manager.did,                         // Issuer
  analyst.did,                         // Subject
  ['influence:trade-recommendation'],  // Scope: recommend, NOT execute
  manager.identity.privateKey,         // Manager signs
  3600000,                             // TTL: 1 hour
);

// Trading engine verifies before acting on the recommendation
const auth = await verifyInfluenceAuth(
  token.value,
  'influence:trade-recommendation',
  registry,
);
if (auth.ok) {
  console.log('Authorized recommendation from', token.value.subject);
} else {
  console.log('Rejected: unauthorized influence attempt');
}

Why This Matters

As autonomous agents make more consequential decisions (trading, medical triage, infrastructure management), organizations need cryptographic proof of authorization chains. “Who authorized this agent to make this recommendation?” is a question auditors, regulators, and liability counsel will ask. Influence tokens provide a machine-verifiable answer embedded in the message itself. Combined with delegation chains and provenance, you get complete accountability: who authorized it, who executed it, and what path it took.

Injection Defense

Transport-layer payload sanitization against prompt injection, data manipulation, and encoding attacks. Protects agent pipelines before payloads reach application code or language models.

The Problem

Agent-to-agent communication is the new attack surface. A prompt injection in a forwarded message could cause an LLM-powered agent to leak data, ignore instructions, or execute unauthorized actions. Malformed envelopes could crash agents or bypass security checks. Traditional web application firewalls do not understand agent-to-agent communication protocols.

How It Works

• sanitizePayload() scans payloads against known attack patterns (prompt override, role injection, delimiter injection, encoding attacks)
• Returns a SanitizationResult with: clean (boolean), sanitized (cleaned payload), threats (what was found)
• validateEnvelopeStructure() checks required fields, correct types, and format constraints
• Configurable rules: max nesting depth, max string length, max array length, custom threat patterns
• hasInjectionRisk() provides a fast boolean pre-screen before full sanitization

interface SanitizationResult {
  readonly clean: boolean;         // true if no threats found
  readonly sanitized: unknown;    // Cleaned payload (safe to process)
  readonly threats: ThreatIndicator[];
}

interface ThreatIndicator {
  readonly type: 'prompt_injection' | 'payload_manipulation'
            | 'encoding_attack' | 'structural';
  readonly description: string;
  readonly path: string;           // Where in the payload (e.g., "body.text")
  readonly severity: 'low' | 'medium' | 'high' | 'critical';
}

import { sanitizePayload, validateEnvelopeStructure,
         hasInjectionRisk } from '@private.me/xbind';

// Quick pre-screen
if (hasInjectionRisk(rawInput)) {
  console.warn('Potential injection detected — running full sanitization');
}

// Validate envelope structure
const structErrors = validateEnvelopeStructure(envelope);
if (structErrors.length > 0) {
  console.error('Malformed envelope:', structErrors);
  return; // Reject
}

// Sanitize the payload before passing to business logic
const result = sanitizePayload(envelope.payload);

if (!result.clean) {
  console.warn('Threats neutralized:', result.threats.length);
  result.threats.forEach(t => {
    console.warn(`  [${t.severity}] ${t.type}: ${t.description}`);
  });
}

// Process the sanitized version
processMessage(result.sanitized);

Why This Matters

A single prompt injection in a multi-agent pipeline can cascade through every downstream agent. Injection defense at the transport layer — before the payload ever reaches application code — provides defense-in-depth that does not depend on each individual agent implementing its own sanitization. One line of code, all incoming payloads protected.

Full Control Activation

The XorIDA algorithm is now split into two shares using information-theoretic threshold sharing. Share 1 ships in the npm package (useless alone). Share 2 is stored on the EC2 vault store behind payment gates. Each share alone reveals zero information about the algorithm — mathematical impossibility, not computational difficulty.

The Problem

Publishing a cryptographic algorithm as an npm package exposes the full implementation to anyone who runs npm install. For patented algorithms like XorIDA (US 11,972,000 B2), this creates enforcement challenges. Traditional code obfuscation is reversible. License-only protection depends on legal enforcement, which is slow and expensive.

How It Works

• The XorIDA algorithm (compiled JavaScript) is split via XorIDA itself into 2 shares (2-of-2 threshold)
• share1.dat (63,484 bytes) ships in the npm tarball — statistically independent of the algorithm
• share2.dat (63,484 bytes) is deployed to EC2 at /opt/private.me/vault-store/ with 600 permissions
• Share 2 is served via POST /api/full-control/share2, gated by Stripe payment verification + xBind DID authentication
• Reconstruction requires both shares — information-theoretic security means no amount of computation can recover the algorithm from Share 1 alone

npm install @private.me/xbind
    └── share1.dat (63,484 bytes) — useless alone

EC2 Vault Store (/opt/private.me/vault-store/)
    └── share2.dat (63,484 bytes) — payment-gated
         └── POST /api/full-control/share2
              └── Requires: Stripe subscription + xBind DID auth

share1 + share2 → XorIDA algorithm (reconstructed at runtime)

Why This Matters

Full Control provides information-theoretic IP protection — not computational security that can be broken with faster hardware, but mathematical impossibility. Each share alone is statistically independent of the algorithm. This means npm packages can be freely distributed without exposing trade secrets. Payment verification happens at the Share 2 retrieval point, not at install time — so developers can npm install, explore the API, read the types, and run offline tests before committing to a subscription.

Transparent Fetch Upgrade

xfetch() is a drop-in replacement for fetch() — it detects xBind support via an OPTIONS probe and upgrades to encrypted transport automatically, falling back to standard HTTPS when unavailable.

The Problem

Applications already use fetch() everywhere. Migrating to xBind means rewriting every HTTP call — changing imports, wrapping payloads in envelopes, managing identities. Developers should not have to choose between convenience and security.

How It Works

• Capability detection: Before the first request to a host, xfetch() sends an OPTIONS probe. If the server advertises xBind support, all subsequent requests to that host use encrypted transport.
• Auto-upgrade: When xBind is available, the request is wrapped in a signed envelope and sent through split-channel transport. The response is verified and unwrapped transparently — the caller receives a standard Response object.
• Graceful fallback: When the host does not support xBind, xfetch() falls back to standard HTTPS with no error and no retry. The usedXBind flag on the response indicates which path was taken.

import { xfetch } from '@private.me/xbind';

// Drop-in replacement for fetch()
const response = await xfetch('https://api.example.com/data', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ query: 'sensitive-search' })
});

// Standard Response API — works exactly like fetch()
const data = await response.json();

// Transport metadata
console.log(response.usedXBind);           // true (auto-upgraded)
console.log(response.transport.protocol);  // "xbind"
console.log(response.transport.latency);   // 42 (ms)
console.log(response.transport.peerDID);   // "did:privateme:z6Mk..."

import { xfetch, isXBindSupported, getXBindCapability } from '@private.me/xbind';

// Force xBind — fail if server does not support it
const secure = await xfetch('https://api.example.com/data', {
  forceXBind: true
});

// Disable xBind — always use plain HTTPS
const plain = await xfetch('https://api.example.com/data', {
  disableXBind: true
});

// Check capabilities before calling
const supported = await isXBindSupported('https://api.example.com');
const caps = await getXBindCapability('https://api.example.com');
console.log(caps); // { supported: true, version: "3.2.0", ... }

Why This Matters

Zero-migration-cost adoption. Replace fetch with xfetch in existing code and every request that can be upgraded is upgraded — automatically, transparently, with no changes to request or response handling.

did:privateme Identity

A dedicated DID method (did:privateme:z…) for PRIVATE.ME infrastructure. Same Ed25519 cryptography as did:key, a distinct method identifier that signals platform backing. Backward-compatible — agents accept both formats.

The Problem

did:key is generic. There is no way to distinguish a platform-backed identity from an arbitrary self-issued key. In multi-vendor deployments, namespace collision becomes a real risk — two unrelated systems can produce identical did:key URIs that resolve to different trust contexts.

How It Works

The format mirrors did:key encoding: did:privateme:z + base58btc(0xed01 || 32-byte Ed25519 public key). The multicodec prefix (0xed01) identifies the key type. Conversion functions translate between formats without re-keying — the underlying public key bytes are identical.

import {
  publicKeyToPrivateMeDid,
  privateMeDidToPublicKeyBytes,
  convertDidFormat,
  isPrivateMeDid,
  isDidKeyFormat
} from '@private.me/xbind';

// Create a did:privateme from a raw 32-byte Ed25519 public key
const did = publicKeyToPrivateMeDid(publicKey);
// "did:privateme:z6MkhaXgBZD..."

// Extract the public key bytes
const keyResult = privateMeDidToPublicKeyBytes(did);
if (keyResult.ok) {
  console.log(keyResult.value);  // Uint8Array(32)
}

// Convert between formats
const didKey = convertDidFormat(did);     // did:privateme → did:key
const didPm  = convertDidFormat(didKey.value); // did:key → did:privateme

// Format detection
isPrivateMeDid(did);        // true
isDidKeyFormat(did);        // false

import { normalizeDid, parseDid } from '@private.me/xbind';

// Normalize any supported DID to did:privateme canonical form
const normalized = normalizeDid('did:key:z6MkhaXgBZD...');
if (normalized.ok) {
  console.log(normalized.value); // "did:privateme:z6MkhaXgBZD..."
}

// Parse into components
const parsed = parseDid('did:privateme:z6MkhaXgBZD...#key-1');
if (parsed.ok) {
  console.log(parsed.value.method);     // "privateme"
  console.log(parsed.value.identifier); // "z6MkhaXgBZD..."
  console.log(parsed.value.fragment);   // "key-1"
}

Why This Matters

Platform identity branding. A did:privateme URI immediately communicates that the identity is backed by PRIVATE.ME infrastructure — registered in a trust registry, bound to a deployment root key, and subject to platform governance. Interoperability with did:key is preserved for systems that have not yet adopted the method.

Trust Infrastructure

Eight subsystems that turn a basic registry into auditable, resilient, self-healing trust infrastructure. Quorum approvals, transparency logs, revocation feeds, offline bootstrap, identity checkpoints, gateway portability, encrypted backup, and enterprise consent — each independently deployable.

Quorum Approvals

K-of-N approval collection where a threshold of approvers must sign off before an action proceeds. Each approval is individually signed (Ed25519) and verified — no single party can authorize alone.

import {
  validateQuorumPolicy,
  createApproval,
  verifyApproval,
  evaluateQuorum
} from '@private.me/xbind';

// Define policy: 2-of-3 approvers required
const policy = {
  threshold: 2,
  approvers: [adminDid, managerDid, auditorDid],
  timeout: 3600000  // 1 hour
};
validateQuorumPolicy(policy);  // Validates threshold ≤ approvers.length

// Each approver creates a signed approval
const approval = await createApproval(requestId, adminDid, adminKey);
const verified = await verifyApproval(approval);  // Verify signature

// Evaluate quorum: are enough approvals collected?
const result = await evaluateQuorum(policy, [approval1, approval2]);
console.log(result.approved); // true (2-of-3 met)
console.log(result.missing);  // 0

Transparency Log

Self-hosted append-only Merkle tree for registry operations. Produces inclusion proofs (a specific entry exists) and consistency proofs (the log has not been tampered with). Customer-operated — no dependency on a third-party certificate transparency service.

import { MerkleTransparencyLog, MemoryLogStorage } from '@private.me/xbind';

const log = new MerkleTransparencyLog(new MemoryLogStorage());

// Append registry operations
const entry = await log.append(JSON.stringify({
  action: 'register', did: agentDid, timestamp: Date.now()
}));

// Generate inclusion proof (entry exists in log)
const proof = await log.inclusionProof(entry.value.index);

// Verify proof against tree head
const valid = await log.verifyInclusion(proof.value);
console.log(valid.ok); // true