@xiotbox/e2e-channel 0.1.0

package/lib/crypto.js

@@ -0,0 +1,283 @@
+/**
+ * XiotBox E2E Secure Channel — generic cryptographic primitives.
+ *
+ * Application-agnostic building blocks for the `xiotbox-e2e` protocol:
+ * X25519 key agreement, HKDF-SHA256 session-key derivation, AES-256-GCM
+ * frame sealing, Ed25519 identity signing, and per-device key persistence.
+ *
+ * Nothing here knows about DSH, OpenClaw, tunnels or chat: any agent channel
+ * that relays opaque bytes through the XiotBox Gateway can reuse this module.
+ * The wire protocol is documented in `docs/e2e-secure-channel.md`.
+ */
+import crypto from 'node:crypto';
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
+import { join } from 'node:path';
+export const E2E_PROTOCOL = 'xiotbox-e2e';
+export const E2E_VERSION = 1;
+export const E2E_MODE_STREAM = 'stream';
+/** Ed25519 SPKI DER prefix: SEQUENCE { SEQUENCE { OID 1.3.101.112 }, BIT STRING } */
+export const ED25519_SPKI_PREFIX = Buffer.from('302a300506032b6570032100', 'hex');
+function x25519ToJwk(raw, isPrivate) {
+    return {
+        kty: 'OKP',
+        crv: 'X25519',
+        x: raw.toString('base64url'),
+        ...(isPrivate ? { d: raw.toString('base64url') } : {}),
+    };
+}
+export function x25519Keypair() {
+    const { publicKey, privateKey } = crypto.generateKeyPairSync('x25519');
+    const pubJwk = publicKey.export({ format: 'jwk' });
+    const privJwk = privateKey.export({ format: 'jwk' });
+    const pub = Buffer.from(pubJwk.x ?? '', 'base64url');
+    const priv = Buffer.from(privJwk.d ?? '', 'base64url');
+    if (priv.length !== 32 || pub.length !== 32) {
+        throw new Error('x25519 keypair export failed');
+    }
+    return { priv, pub };
+}
+export function x25519Shared(priv, pub) {
+    if (priv.length !== 32 || pub.length !== 32) {
+        throw new Error('invalid_x25519_key_len');
+    }
+    const privateKey = crypto.createPrivateKey({ key: x25519ToJwk(priv, true), format: 'jwk' });
+    const publicKey = crypto.createPublicKey({ key: x25519ToJwk(pub, false), format: 'jwk' });
+    return crypto.diffieHellman({ privateKey, publicKey });
+}
+export function b64e(value) {
+    return Buffer.from(value).toString('base64');
+}
+export function b64d(value) {
+    if (typeof value !== 'string' || value.length === 0)
+        return undefined;
+    try {
+        return Buffer.from(value, 'base64');
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Key id: first 16 hex chars of SHA-256(public key) — matches OpenClaw / client. */
+export function computeKeyId(pubRaw) {
+    return crypto.createHash('sha256').update(pubRaw).digest('hex').slice(0, 16);
+}
+/** Identity fingerprint: full SHA-256 hex of the SPKI DER public key. */
+export function computeIdentityFingerprint(pubDer) {
+    return crypto.createHash('sha256').update(pubDer).digest('hex');
+}
+/**
+ * Human-readable fingerprint for out-of-band verification: uppercase hex in
+ * groups of 4, e.g. `A1B2 C3D4 E5F6 …`. Host logs and client UIs must format
+ * identically so a user can compare them.
+ */
+export function formatFingerprint(fingerprint) {
+    const hex = (fingerprint ?? '').toLowerCase().replace(/[^0-9a-f]/g, '');
+    const groups = [];
+    for (let i = 0; i < hex.length; i += 4) {
+        groups.push(hex.slice(i, i + 4).toUpperCase());
+    }
+    return groups.join(' ');
+}
+/** Extract the raw 32-byte Ed25519 public key from SPKI DER. */
+export function ed25519RawFromDer(pubDer) {
+    if (pubDer.length !== 44 || !pubDer.subarray(0, 12).equals(ED25519_SPKI_PREFIX)) {
+        throw new Error('invalid_ed25519_spki_der');
+    }
+    return pubDer.subarray(12);
+}
+/** Normalize a peer Ed25519 public key (raw 32B or SPKI DER 44B) to raw 32B. */
+export function normalizeEd25519Pub(value) {
+    if (value.length === 32)
+        return value;
+    if (value.length === 44) {
+        try {
+            return ed25519RawFromDer(value);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return undefined;
+}
+// ---------------------------------------------------------------------------
+// Session keys & AEAD
+// ---------------------------------------------------------------------------
+/**
+ * Derive the per-channel session key.
+ *   session_key = HKDF-SHA256(ECDH(eph), salt=channel_id, info='xiotbox-e2e|v=1|stream')
+ */
+export function deriveSessionKey(shared, channelId) {
+    const info = Buffer.from(`${E2E_PROTOCOL}|v=${E2E_VERSION}|${E2E_MODE_STREAM}`, 'utf8');
+    const derived = crypto.hkdfSync('sha256', shared, Buffer.from(channelId, 'utf8'), info, 32);
+    return Buffer.from(derived);
+}
+/**
+ * AAD bound to every encrypted frame:
+ *   'xiotbox-e2e|v=1|stream|{channel_id}|{dir}|{seq}'
+ * `dir` is the direction the frame travels ('c2p' client→plugin, 'p2c' plugin→client).
+ */
+export function buildFrameAad(channelId, dir, seq) {
+    return Buffer.from(`${E2E_PROTOCOL}|v=${E2E_VERSION}|${E2E_MODE_STREAM}|${channelId}|${dir}|${seq}`, 'utf8');
+}
+/**
+ * Handshake transcript signed by each side's Ed25519 identity key.
+ *
+ * Fields use a canonical role-agnostic order (`c_` = client/initiator side,
+ * `p_` = plugin/responder side) so both peers compute the identical string
+ * for the same `dir`, regardless of which side is signing.
+ */
+export function buildHandshakeTranscript(opts) {
+    return Buffer.from(`${E2E_PROTOCOL}|v=${E2E_VERSION}|channel=${opts.channelId}|dir=${opts.dir}|` +
+        `c_eph=${opts.cEphPubB64}|p_eph=${opts.pEphPubB64}|c_kid=${opts.cKid}|` +
+        `p_kid=${opts.pKid}|c_nonce=${opts.cNonce}|p_nonce=${opts.pNonce}`, 'utf8');
+}
+/**
+ * Registration identity claim, mirroring the OpenClaw `ocid|...` canonical
+ * format so Lite/clients that already verify bot identity claims accept the
+ * same signature scheme.
+ */
+export function buildRegistrationSigPayload(opts) {
+    const parts = [
+        'v=1',
+        `device=${opts.deviceId}`,
+        `peer_pub=${opts.peerPubB64}`,
+        `peer_key_id=${opts.keyId}`,
+        `ts=${opts.ts}`,
+        `nonce=${opts.nonce}`,
+    ];
+    return Buffer.from(`ocid|${parts.join('|')}`, 'utf-8');
+}
+/** AES-256-GCM seal: returns { iv, tag, ct } all base64 for wire transport. */
+export function sealFrame(key, plaintext, aad) {
+    const iv = crypto.randomBytes(12);
+    const cipher = crypto.createCipheriv('aes-256-gcm', key, iv);
+    cipher.setAAD(aad);
+    const ct = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    return { iv: iv.toString('base64'), tag: tag.toString('base64'), ct: ct.toString('base64') };
+}
+/** AES-256-GCM open: returns the plaintext Buffer, or undefined on auth failure. */
+export function openFrame(key, frame, aad) {
+    const iv = b64d(frame.iv);
+    const tag = b64d(frame.tag);
+    const ct = b64d(frame.ct);
+    if (iv === undefined || iv.length !== 12 || tag === undefined || tag.length !== 16 || ct === undefined) {
+        return undefined;
+    }
+    try {
+        const decipher = crypto.createDecipheriv('aes-256-gcm', key, iv);
+        decipher.setAAD(aad);
+        decipher.setAuthTag(tag);
+        return Buffer.concat([decipher.update(ct), decipher.final()]);
+    }
+    catch {
+        return undefined;
+    }
+}
+// ---------------------------------------------------------------------------
+// Ed25519 identity
+// ---------------------------------------------------------------------------
+export function generateEd25519Identity() {
+    const { publicKey, privateKey } = crypto.generateKeyPairSync('ed25519');
+    const pubDer = publicKey.export({ format: 'der', type: 'spki' });
+    return {
+        privKey: privateKey,
+        pubRaw: ed25519RawFromDer(pubDer),
+        pubDer,
+        fingerprint: computeIdentityFingerprint(pubDer),
+    };
+}
+export function signMessage(privKey, message) {
+    return crypto.sign(null, message, privKey);
+}
+/** Verify an Ed25519 signature against a raw (32B) or SPKI DER (44B) public key. */
+export function verifyMessage(pubKey, message, signature) {
+    if (pubKey.length !== 32 && pubKey.length !== 44)
+        return false;
+    try {
+        const der = pubKey.length === 32
+            ? Buffer.concat([ED25519_SPKI_PREFIX, pubKey])
+            : pubKey;
+        const key = crypto.createPublicKey({ key: der, format: 'der', type: 'spki' });
+        return crypto.verify(null, message, key, signature);
+    }
+    catch {
+        return false;
+    }
+}
+// ---------------------------------------------------------------------------
+// Per-device key persistence
+// ---------------------------------------------------------------------------
+/** Default key directory: `~/.xiotbox/e2e`. Consumers may pass their own. */
+export function defaultE2EKeyDir() {
+    return join(os.homedir(), '.xiotbox', 'e2e');
+}
+export function deviceKeyPath(keyDir, deviceId) {
+    const safe = String(deviceId).replace(/[^A-Za-z0-9_.-]/g, '_');
+    return join(keyDir, `keys_${safe}.json`);
+}
+/** Load persisted keys for a device, creating them on first run. */
+export function loadOrCreateDeviceKeys(deviceId, keyDir, log) {
+    const dir = keyDir ?? defaultE2EKeyDir();
+    const path = deviceKeyPath(dir, deviceId);
+    let stored;
+    if (existsSync(path)) {
+        try {
+            const raw = JSON.parse(readFileSync(path, 'utf8'));
+            if (raw?.v === 1 && raw.x25519?.priv_b64 && raw.x25519?.pub_b64 && raw.identity?.priv_der_b64) {
+                stored = raw;
+            }
+        }
+        catch (error) {
+            log?.('warn', `[E2E] ignoring corrupt key file ${path}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    if (stored === undefined) {
+        const keypair = x25519Keypair();
+        const identity = generateEd25519Identity();
+        stored = {
+            v: 1,
+            x25519: {
+                priv_b64: keypair.priv.toString('base64'),
+                pub_b64: keypair.pub.toString('base64'),
+                key_id: computeKeyId(keypair.pub),
+            },
+            identity: {
+                priv_der_b64: identity.privKey.export({ format: 'der', type: 'pkcs8' }).toString('base64'),
+                pub_der_b64: identity.pubDer.toString('base64'),
+                fingerprint: identity.fingerprint,
+            },
+        };
+        try {
+            mkdirSync(dir, { recursive: true });
+            writeFileSync(path, JSON.stringify(stored, null, 2));
+            chmodSync(path, 0o600);
+        }
+        catch (error) {
+            log?.('warn', `[E2E] key persistence failed (keys live in memory only): ${error instanceof Error ? error.message : String(error)}`);
+        }
+        log?.('info', `[E2E] generated fresh device keys device=${deviceId} keyId=${stored.x25519.key_id} fp=${stored.identity.fingerprint.slice(0, 12)}…`);
+        return {
+            keypair: {
+                priv: Buffer.from(stored.x25519.priv_b64, 'base64'),
+                pub: Buffer.from(stored.x25519.pub_b64, 'base64'),
+                keyId: stored.x25519.key_id,
+            },
+            identity,
+        };
+    }
+    const keypair = {
+        priv: Buffer.from(stored.x25519.priv_b64, 'base64'),
+        pub: Buffer.from(stored.x25519.pub_b64, 'base64'),
+        keyId: stored.x25519.key_id,
+    };
+    const identity = {
+        privKey: crypto.createPrivateKey({ key: Buffer.from(stored.identity.priv_der_b64, 'base64'), format: 'der', type: 'pkcs8' }),
+        pubRaw: ed25519RawFromDer(Buffer.from(stored.identity.pub_der_b64, 'base64')),
+        pubDer: Buffer.from(stored.identity.pub_der_b64, 'base64'),
+        fingerprint: stored.identity.fingerprint,
+    };
+    return { keypair, identity };
+}
+//# sourceMappingURL=crypto.js.map

package/lib/crypto.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"crypto.js","sourceRoot":"","sources":["../src/crypto.ts"],"names":[],"mappings":"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"}

package/lib/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * XiotBox E2E Secure Channel — public entry point.
+ *
+ * Generic end-to-end encrypted relay protocol for the XiotBox Gateway:
+ * any agent channel (DSH, OpenClaw, future Codex/Claude Code runtimes)
+ * relays opaque frames through the Gateway and wraps them with this layer.
+ *
+ * See `docs/e2e-secure-channel.md` for the wire protocol specification and
+ * cross-language (Dart / Python) implementation guidance.
+ */
+export * from './crypto.js';
+export * from './secure-channel.js';

package/lib/index.js

@@ -0,0 +1,13 @@
+/**
+ * XiotBox E2E Secure Channel — public entry point.
+ *
+ * Generic end-to-end encrypted relay protocol for the XiotBox Gateway:
+ * any agent channel (DSH, OpenClaw, future Codex/Claude Code runtimes)
+ * relays opaque frames through the Gateway and wraps them with this layer.
+ *
+ * See `docs/e2e-secure-channel.md` for the wire protocol specification and
+ * cross-language (Dart / Python) implementation guidance.
+ */
+export * from './crypto.js';
+export * from './secure-channel.js';
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,cAAc,aAAa,CAAA;AAC3B,cAAc,qBAAqB,CAAA"}

package/lib/secure-channel.d.ts

@@ -0,0 +1,111 @@
+/**
+ * XiotBox E2E Secure Channel — generic end-to-end encrypted channel.
+ *
+ * Sits between an application protocol and the XiotBox Gateway relay: any
+ * channel that relays opaque JSON frames (DSH web tunnel, agent RPC, PTY
+ * streams, …) can wrap them with this layer and get:
+ *
+ *  - confidentiality   — the Gateway only ever sees ciphertext frames
+ *  - integrity         — AES-256-GCM AEAD rejects any modified frame
+ *  - anti-replay       — per-direction sequence counters bound in the AAD
+ *  - forward secrecy   — fresh ephemeral X25519 key pair per channel
+ *  - peer authentication — Ed25519 identity signatures over the handshake
+ *    transcript, pinned TOFU by the application via `peerIdentityPolicy`
+ *
+ * Wire format (all frames are JSON, base64-encoded by the relay):
+ *   handshake:  {t:'hello', v:1, pub, kid, nonce}
+ *               {t:'hello_ack', v:1, pub, kid, nonce}
+ *               {t:'ident', v:1, id, fp, sig}      (identity claim, signed)
+ *               {t:'ident_ack', v:1, id, fp, sig}
+ *   data:       {t:'enc', v:1, iv, tag, ct}        (ct = encrypted app frame)
+ *
+ * Application keepalives (e.g. the tunnel's ping/pong) stay outside this
+ * layer and are relayed plaintext; they carry no sensitive content.
+ *
+ * See `docs/e2e-secure-channel.md` for the full protocol specification.
+ */
+import { type Ed25519Identity, type X25519Keypair } from './crypto.js';
+export type ChannelDirection = 'c2p' | 'p2c';
+export interface PeerIdentityResult {
+    ok: boolean;
+    reason?: string;
+}
+/**
+ * Application-provided trust policy for the peer's Ed25519 identity.
+ * The protocol always verifies the signature; this decides whether the
+ * claimed public key is *trusted* as the peer (TOFU pinning, registered
+ * identity comparison, …).
+ */
+export type PeerIdentityPolicy = (peerIdRaw: Buffer, fingerprint: string, transcript: Buffer, signature: Buffer) => PeerIdentityResult;
+export interface SecureChannelOptions {
+    channelId: string;
+    /** Client = 'initiator' (sends hello), host/plugin = 'responder'. */
+    role: 'initiator' | 'responder';
+    /** Long-term X25519 keypair of this side (kid in hello/hello_ack). */
+    keypair: X25519Keypair;
+    /** Ed25519 identity of this side; required to complete the handshake. */
+    identity: Ed25519Identity;
+    /** Registered key id of the peer; verified when set (mismatch → reject). */
+    peerKid?: string;
+    /** Trust policy for the peer's identity claim. Default: accept (TOFU). */
+    peerIdentityPolicy?: PeerIdentityPolicy;
+    /** Emit a frame onto the relay. Must return false when the channel is gone. */
+    send: (frame: Record<string, unknown>) => boolean;
+    /** Called once when the channel closes (timeout, security failure, …) so
+     *  the transport can tear down the relay channel. */
+    onClose?: (reason: string) => void;
+    log?: (level: 'debug' | 'info' | 'warn', message: string) => void;
+    handshakeTimeoutMs?: number;
+}
+/**
+ * One E2E session bound to one relay channel. Created per channel; the
+ * session key lives only in memory and is dropped on close.
+ */
+export declare class SecureChannel {
+    private readonly opts;
+    private state;
+    private readonly eph;
+    private readonly myNonce;
+    private readonly myKid;
+    private peerEphPubB64;
+    private peerKid;
+    private peerNonce;
+    private peerIdentityFp;
+    private sessionKey;
+    private sendSeq;
+    private recvSeq;
+    private timeout;
+    private closedReason;
+    constructor(options: SecureChannelOptions);
+    get ready(): boolean;
+    get channelId(): string;
+    get direction(): ChannelDirection;
+    /** Initiate (initiator) or arm the handshake timeout (responder). */
+    start(): void;
+    /**
+     * Feed an inbound relay frame. Returns:
+     *   { status: 'ok', app?: Record }  — app frame decrypted (when ready)
+     *   { status: 'ok' }                — handshake/control frame consumed
+     *   { status: 'closed', reason }    — protocol/security failure
+     */
+    receive(frame: Record<string, unknown>): {
+        status: 'ok';
+        app?: Record<string, unknown>;
+    } | {
+        status: 'closed';
+        reason: string;
+    };
+    /** Wrap an application frame into an encrypted relay frame. */
+    wrap(app: Record<string, unknown>): Record<string, unknown>;
+    /** Close the channel; clears the session key and timers. */
+    close(reason?: string): void;
+    private handleHello;
+    private handleHelloAck;
+    private handleIdent;
+    private handleIdentAck;
+    private verifyIdentityClaim;
+    private buildTranscript;
+    private handleEnc;
+    private armTimeout;
+    private clearTimeout;
+}