Xlink: Secure Machine-to-Machine

Executive Summary

Xlink gives every AI agent, microservice, and IoT device a cryptographic identity and a way to exchange messages that are encrypted, signed, and replay-protected — in under 50 lines of code.

Two functions cover 80% of use cases: Agent.create() generates an Ed25519 + X25519 identity with hybrid post-quantum key exchange (X25519 + ML-KEM-768, always-on) and registers it with a trust registry. agent.send() encrypts a payload with AES-256-GCM, signs it with Ed25519 (+ ML-DSA-65 when postQuantumSig: true), and delivers it via any transport adapter. The receiver verifies signatures, checks replay protection, validates scope, and decrypts — automatically.

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

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

The Problem

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

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

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

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

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

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

The Old Way

The New Way

Real-World Use Cases

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

Solution Architecture

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

The One-Time Setup

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

import { Agent, MemoryTrustRegistry, HttpsTransportAdapter } from '@xail/agent-sdk';

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

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

Forward Secrecy

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

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

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

Split-Channel Mode

Information-theoretic security via XorIDA threshold secret sharing. One-line opt-in.

When splitChannel: true is set on agent.send(), the plaintext is split into N shares (default 3) using XorIDA over GF(2), with a reconstruction threshold of K (default 2). Each share is independently encrypted, signed, and transmitted via separate channels.

await agent.send({
  to: recipientDid,
  payload: { secret: 'classified-data' },
  scope: 'secure',
  splitChannel: true,
  splitChannelConfig: { totalShares: 3, threshold: 2 },
});

Identity & Persistence

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

DID:key Format

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

Persistence Strategies

Complete Flow

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

Sender Pipeline

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

Receiver Pipeline

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

Integration Patterns

Four patterns for different deployment contexts.

Express Middleware

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

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

Registry Auth Middleware

import { createRegistryAuthMiddleware } from '@xail/agent-sdk';

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

IoT Composable Pattern

import { generateIdentity, createSignedEnvelope, splitForChannel } from '@xail/agent-sdk';

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

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

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

Signed-Only Telemetry

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

Security Properties

Seven layers of defense. Each independently verifiable.

Supply Chain Security

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

Comparison to Alternatives

Benchmarks

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

XorIDA vs AES-256-GCM — API Payload Performance

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

256-Byte Roundtrip — Visual Comparison

Full Comparison — API Payload Sizes

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

Xlink vs Competitors — API Crypto Overhead

Full send + receive roundtrip measured end-to-end with real crypto operations. Competitor estimates use our measured primitive timings (same algorithms, same JS runtime) as reference. Xlink uses split-channel (2-of-3); competitors use single-channel delivery.

256-Byte API Payload — Full Roundtrip

Full Comparison — All API Payload Sizes

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

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

Lower % = less crypto tax on your API calls. At 10ms+ latency, Xlink overhead is negligible.

Security vs Performance

Ranked by roundtrip speed at 256B. Xlink is the fastest system with post-quantum protection—and the only one providing information-theoretic security.

Honest Limitations

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

Post-Quantum Security

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

Two Security Layers

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

Migration Strategy

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

Algorithm Profile

Latency Impact

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

Envelope Version

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

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

Protocol Security Stack

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

Three-Layer Architecture

Layer 1 — Payload (Information-Theoretic)

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

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

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

Layer 3 — Authentication (Dual Signatures)

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

Envelope Version Progression

• v1 — Classical only. X25519 ECDH key exchange, Ed25519 signatures.
• v2 — Hybrid PQ KEM. X25519 + ML-KEM-768 key exchange, Ed25519 signatures. Backward-compatible with v1 peers.
• v3 — Full PQ. Hybrid KEM + dual signatures (Ed25519 + ML-DSA-65). Backward-compatible with v1/v2 peers.

Agents negotiate capabilities automatically. A v3 agent communicating with a v1 peer falls back to v1 envelope format. No developer action required — the protocol handles version negotiation internally.

Error Hierarchy

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

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

import { toXlinkError, isXlinkError } from '@xail/agent-sdk';

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

Trust Registry

Three implementations covering development through production.

Nonce Store

Replay prevention via unique nonce tracking. Every envelope carries a cryptographic 16-byte nonce.

Transport Adapters

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

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

Full ACI Surface

Complete Authenticated Cryptographic Interface organized by module.

Agent

Identity

Envelope

Split-Channel

Key Agreement

Error Taxonomy

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

Codebase Stats

Xlink v0.1.0 — Gold Standard Bronze tier achieved.

Module Inventory

Documentation

22 documentation files including: SECURITY.md, CHANGELOG.md, QUICKSTART.md, MIGRATION.md, CONTRIBUTING.md, AGENTS.md, threat model, data flow diagrams, security whitepaper, failure modes, Gold Standard assessment, and 4 example scripts.