uxnan-bridge 0.0.1-alpha.20260621

package/dist/src/transport/message-io.js

@@ -0,0 +1,87 @@
+/**
+ * Transport-agnostic binary message channel. Both the relay client and the LAN
+ * server adapt their WebSocket to this interface so the secure session logic is
+ * written once.
+ *
+ * Frames are raw bytes: UTF-8 JSON for handshake control messages and encrypted
+ * envelopes (matching the mobile app, which sends binary frames).
+ */
+/**
+ * An async FIFO over inbound frames. `next()` resolves with the next frame or
+ * rejects once the channel is closed and drained. Used to drive the request/
+ * response handshake sequentially.
+ */
+export class MessageQueue {
+    #buffer = [];
+    #waiters = [];
+    #closed = false;
+    push(bytes) {
+        const waiter = this.#waiters.shift();
+        if (waiter) {
+            waiter.resolve(bytes);
+        }
+        else {
+            this.#buffer.push(bytes);
+        }
+    }
+    close() {
+        this.#closed = true;
+        while (this.#waiters.length > 0) {
+            this.#waiters.shift().reject(new Error('message channel closed'));
+        }
+    }
+    next() {
+        const buffered = this.#buffer.shift();
+        if (buffered !== undefined)
+            return Promise.resolve(buffered);
+        if (this.#closed)
+            return Promise.reject(new Error('message channel closed'));
+        return new Promise((resolve, reject) => {
+            this.#waiters.push({ resolve, reject });
+        });
+    }
+}
+/** Attach a {@link MessageQueue} to a {@link MessageIO}. */
+export function queueFor(io) {
+    const queue = new MessageQueue();
+    io.onMessage((bytes) => queue.push(bytes));
+    io.onClose(() => queue.close());
+    return queue;
+}
+/** Create a connected in-memory pair of {@link MessageIO}s (for tests). */
+export function createInMemoryIoPair() {
+    const listeners = { a: [], b: [] };
+    const closers = { a: [], b: [] };
+    let open = true;
+    const closeBoth = () => {
+        if (!open)
+            return;
+        open = false;
+        for (const c of closers.a)
+            c();
+        for (const c of closers.b)
+            c();
+    };
+    const a = {
+        send: (bytes) => {
+            if (open)
+                for (const l of listeners.b)
+                    l(bytes);
+        },
+        onMessage: (l) => listeners.a.push(l),
+        onClose: (l) => closers.a.push(l),
+        close: closeBoth,
+    };
+    const b = {
+        send: (bytes) => {
+            if (open)
+                for (const l of listeners.a)
+                    l(bytes);
+        },
+        onMessage: (l) => listeners.b.push(l),
+        onClose: (l) => closers.b.push(l),
+        close: closeBoth,
+    };
+    return [a, b];
+}
+//# sourceMappingURL=message-io.js.map

package/dist/src/transport/message-io.js.map

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

package/dist/src/transport/outbound-log.d.ts

@@ -0,0 +1,24 @@
+/** A retained outbound message: its sequence number and the plaintext bytes. */
+export interface OutboundLogEntry {
+    seq: number;
+    plaintext: Buffer;
+}
+export declare class OutboundLog {
+    #private;
+    constructor(maxMessages?: number, maxBytes?: number);
+    /**
+     * Assign the next `seq` to a plaintext payload, retain it in the window, and
+     * return the assigned seq. Called for EVERY bridge→phone message (replies and
+     * notifications), whether sent live or buffered while offline.
+     */
+    record(plaintext: Buffer): number;
+    /**
+     * Retained entries with `seq` strictly greater than `lastAppliedSeq`, oldest
+     * first — i.e. exactly what the phone is missing and must be replayed.
+     */
+    entriesAfter(lastAppliedSeq: number): OutboundLogEntry[];
+    /** The seq that the next `record` will assign. */
+    get nextSeq(): number;
+    get length(): number;
+    get byteLength(): number;
+}

package/dist/src/transport/outbound-log.js

@@ -0,0 +1,78 @@
+/**
+ * Per-device outbound (bridge → phone) log: assigns every bridge→phone payload a
+ * continuous, monotonic `seq` and retains the recent plaintext in a sliding
+ * window so it can be REPLAYED after a reconnect (seq-based catch-up).
+ *
+ * Why plaintext (not encrypted envelopes): every reconnect derives a FRESH
+ * session key (X25519 ephemeral handshake), so retained envelopes encrypted
+ * under the previous key are useless to the new channel. The log keeps the
+ * plaintext + its seq; on reconnect the new channel re-encrypts the entries the
+ * phone is missing (`encryptReplay`).
+ *
+ * The `seq` counter is owned HERE (not by the per-connection channel) precisely
+ * so it survives a reconnect: a new `BridgeSecureChannel` built over the same
+ * log continues the sequence instead of restarting at 1.
+ *
+ * Caps follow the spec (architecture/02a §5.9.2): at most
+ * MAX_BRIDGE_OUTBOUND_MESSAGES messages and MAX_BRIDGE_OUTBOUND_BYTES total; the
+ * oldest entries are evicted first. At least one message is always kept. When
+ * the phone's `lastAppliedBridgeOutboundSeq` predates the oldest retained entry
+ * (the bridge already evicted it, or restarted and lost the log), those messages
+ * are unrecoverable here — the phone falls back to `turn/list` re-sync.
+ */
+import { MAX_BRIDGE_OUTBOUND_BYTES, MAX_BRIDGE_OUTBOUND_MESSAGES } from '@uxnan/shared';
+export class OutboundLog {
+    #entries = [];
+    #maxMessages;
+    #maxBytes;
+    #totalBytes = 0;
+    /** Next sequence number to hand out (1-based, never reset across reconnects). */
+    #nextSeq = 1;
+    constructor(maxMessages = MAX_BRIDGE_OUTBOUND_MESSAGES, maxBytes = MAX_BRIDGE_OUTBOUND_BYTES) {
+        this.#maxMessages = maxMessages;
+        this.#maxBytes = maxBytes;
+    }
+    /**
+     * Assign the next `seq` to a plaintext payload, retain it in the window, and
+     * return the assigned seq. Called for EVERY bridge→phone message (replies and
+     * notifications), whether sent live or buffered while offline.
+     */
+    record(plaintext) {
+        const seq = this.#nextSeq;
+        this.#nextSeq += 1;
+        const bytes = plaintext.byteLength;
+        this.#entries.push({ seq, plaintext, bytes });
+        this.#totalBytes += bytes;
+        while (this.#entries.length > this.#maxMessages ||
+            (this.#totalBytes > this.#maxBytes && this.#entries.length > 1)) {
+            const evicted = this.#entries.shift();
+            if (!evicted)
+                break;
+            this.#totalBytes -= evicted.bytes;
+        }
+        return seq;
+    }
+    /**
+     * Retained entries with `seq` strictly greater than `lastAppliedSeq`, oldest
+     * first — i.e. exactly what the phone is missing and must be replayed.
+     */
+    entriesAfter(lastAppliedSeq) {
+        const out = [];
+        for (const entry of this.#entries) {
+            if (entry.seq > lastAppliedSeq)
+                out.push({ seq: entry.seq, plaintext: entry.plaintext });
+        }
+        return out;
+    }
+    /** The seq that the next `record` will assign. */
+    get nextSeq() {
+        return this.#nextSeq;
+    }
+    get length() {
+        return this.#entries.length;
+    }
+    get byteLength() {
+        return this.#totalBytes;
+    }
+}
+//# sourceMappingURL=outbound-log.js.map

package/dist/src/transport/outbound-log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"outbound-log.js","sourceRoot":"","sources":["../../../src/transport/outbound-log.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EAAE,yBAAyB,EAAE,4BAA4B,EAAE,MAAM,eAAe,CAAC;AAYxF,MAAM,OAAO,WAAW;IACb,QAAQ,GAAoB,EAAE,CAAC;IAC/B,YAAY,CAAS;IACrB,SAAS,CAAS;IAC3B,WAAW,GAAG,CAAC,CAAC;IAChB,iFAAiF;IACjF,QAAQ,GAAG,CAAC,CAAC;IAEb,YACE,cAAsB,4BAA4B,EAClD,WAAmB,yBAAyB;QAE5C,IAAI,CAAC,YAAY,GAAG,WAAW,CAAC;QAChC,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAC;IAC5B,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,SAAiB;QACtB,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC;QAC1B,IAAI,CAAC,QAAQ,IAAI,CAAC,CAAC;QACnB,MAAM,KAAK,GAAG,SAAS,CAAC,UAAU,CAAC;QACnC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,CAAC;QAC9C,IAAI,CAAC,WAAW,IAAI,KAAK,CAAC;QAC1B,OACE,IAAI,CAAC,QAAQ,CAAC,MAAM,GAAG,IAAI,CAAC,YAAY;YACxC,CAAC,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,EAC/D,CAAC;YACD,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC;YACtC,IAAI,CAAC,OAAO;gBAAE,MAAM;YACpB,IAAI,CAAC,WAAW,IAAI,OAAO,CAAC,KAAK,CAAC;QACpC,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IAED;;;OAGG;IACH,YAAY,CAAC,cAAsB;QACjC,MAAM,GAAG,GAAuB,EAAE,CAAC;QACnC,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAClC,IAAI,KAAK,CAAC,GAAG,GAAG,cAAc;gBAAE,GAAG,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,CAAC,CAAC;QAC3F,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IAED,kDAAkD;IAClD,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;IAED,IAAI,MAAM;QACR,OAAO,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC;IAC9B,CAAC;IAED,IAAI,UAAU;QACZ,OAAO,IAAI,CAAC,WAAW,CAAC;IAC1B,CAAC;CACF"}

package/dist/src/transport/relay-client.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Connects the bridge to the relay as the `mac` role for a given session, so a
+ * phone connecting with the same `x-session-id` is paired and its E2EE frames
+ * are forwarded here. Relay headers per architecture/02a §5.10.1.
+ */
+import { WebSocket } from 'ws';
+import type { MessageIO } from './message-io.js';
+export interface ConnectRelayOptions {
+    relayUrl: string;
+    sessionId: string;
+    macDeviceId: string;
+    macIdentityPublicKey: string;
+    machineName: string;
+}
+export interface RelayConnection {
+    ws: WebSocket;
+    io: MessageIO;
+}
+export declare function connectRelayAsMac(options: ConnectRelayOptions): Promise<RelayConnection>;

package/dist/src/transport/relay-client.js

@@ -0,0 +1,27 @@
+/**
+ * Connects the bridge to the relay as the `mac` role for a given session, so a
+ * phone connecting with the same `x-session-id` is paired and its E2EE frames
+ * are forwarded here. Relay headers per architecture/02a §5.10.1.
+ */
+import { WebSocket } from 'ws';
+import { wsToMessageIO } from './ws-adapter.js';
+export function connectRelayAsMac(options) {
+    return new Promise((resolve, reject) => {
+        const ws = new WebSocket(options.relayUrl, {
+            headers: {
+                'x-role': 'mac',
+                'x-session-id': options.sessionId,
+                'x-mac-device-id': options.macDeviceId,
+                'x-mac-identity-public-key': options.macIdentityPublicKey,
+                'x-machine-name': options.machineName,
+            },
+        });
+        const onError = (err) => reject(err);
+        ws.once('error', onError);
+        ws.once('open', () => {
+            ws.removeListener('error', onError);
+            resolve({ ws, io: wsToMessageIO(ws) });
+        });
+    });
+}
+//# sourceMappingURL=relay-client.js.map

package/dist/src/transport/relay-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"relay-client.js","sourceRoot":"","sources":["../../../src/transport/relay-client.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AAE/B,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAehD,MAAM,UAAU,iBAAiB,CAAC,OAA4B;IAC5D,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,MAAM,EAAE,GAAG,IAAI,SAAS,CAAC,OAAO,CAAC,QAAQ,EAAE;YACzC,OAAO,EAAE;gBACP,QAAQ,EAAE,KAAK;gBACf,cAAc,EAAE,OAAO,CAAC,SAAS;gBACjC,iBAAiB,EAAE,OAAO,CAAC,WAAW;gBACtC,2BAA2B,EAAE,OAAO,CAAC,oBAAoB;gBACzD,gBAAgB,EAAE,OAAO,CAAC,WAAW;aACtC;SACF,CAAC,CAAC;QACH,MAAM,OAAO,GAAG,CAAC,GAAU,EAAQ,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAClD,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QAC1B,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE;YACnB,EAAE,CAAC,cAAc,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YACpC,OAAO,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,aAAa,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;QACzC,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/src/transport/secure-channel.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Encrypted channel over an established session (bridge side).
+ *
+ * Outbound (bridge → phone) sequence numbers are 1-based; inbound (phone →
+ * bridge) envelopes must have a strictly increasing `seq` (replay protection),
+ * matching the mobile `SecureChannel` (architecture/02a §5.9.1, 02b §5.3).
+ */
+import type { SecureEnvelope } from '@uxnan/shared';
+import type { OutboundLog } from './outbound-log.js';
+export declare class ReplayError extends Error {
+    constructor(message: string);
+}
+export declare class BridgeSecureChannel {
+    #private;
+    constructor(key: Buffer, sessionId: string, log?: OutboundLog);
+    get sessionId(): string;
+    get nextOutboundSeq(): number;
+    get lastInboundSeq(): number;
+    /**
+     * Encrypt a plaintext payload into the next outbound envelope. The seq is
+     * drawn from (and the plaintext retained in) the outbound log when one is
+     * attached, so the message can be replayed after a reconnect.
+     */
+    encrypt(plaintext: Buffer): SecureEnvelope;
+    /**
+     * Re-encrypt a retained plaintext under THIS channel's (new) key with its
+     * ORIGINAL seq, for seq-based catch-up after a reconnect. Does NOT advance the
+     * counter or record into the log — the entry already lives there.
+     */
+    encryptReplay(seq: number, plaintext: Buffer): SecureEnvelope;
+    /** Decrypt an inbound envelope, enforcing session and replay checks. */
+    decrypt(envelope: SecureEnvelope): Buffer;
+}

package/dist/src/transport/secure-channel.js

@@ -0,0 +1,81 @@
+import { aesGcmDecrypt, aesGcmEncrypt } from './crypto.js';
+export class ReplayError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ReplayError';
+    }
+}
+export class BridgeSecureChannel {
+    #key;
+    #sessionId;
+    /**
+     * Per-device outbound log that owns the seq counter + retains plaintext for
+     * catch-up. When present, `encrypt` records here and the seq continues across
+     * reconnects. When absent (tests, the phone-side peer), an internal 1-based
+     * counter is used and nothing is retained.
+     */
+    #log;
+    #fallbackSeq;
+    #lastInboundSeq;
+    constructor(key, sessionId, log) {
+        this.#key = key;
+        this.#sessionId = sessionId;
+        this.#log = log;
+        this.#fallbackSeq = 1;
+        this.#lastInboundSeq = 0;
+    }
+    get sessionId() {
+        return this.#sessionId;
+    }
+    get nextOutboundSeq() {
+        return this.#log ? this.#log.nextSeq : this.#fallbackSeq;
+    }
+    get lastInboundSeq() {
+        return this.#lastInboundSeq;
+    }
+    /**
+     * Encrypt a plaintext payload into the next outbound envelope. The seq is
+     * drawn from (and the plaintext retained in) the outbound log when one is
+     * attached, so the message can be replayed after a reconnect.
+     */
+    encrypt(plaintext) {
+        const seq = this.#log ? this.#log.record(plaintext) : this.#fallbackSeq++;
+        return this.#seal(seq, plaintext);
+    }
+    /**
+     * Re-encrypt a retained plaintext under THIS channel's (new) key with its
+     * ORIGINAL seq, for seq-based catch-up after a reconnect. Does NOT advance the
+     * counter or record into the log — the entry already lives there.
+     */
+    encryptReplay(seq, plaintext) {
+        return this.#seal(seq, plaintext);
+    }
+    #seal(seq, plaintext) {
+        const parts = aesGcmEncrypt(this.#key, plaintext);
+        return {
+            kind: 'encryptedEnvelope',
+            sessionId: this.#sessionId,
+            seq,
+            nonce: parts.nonceHex,
+            ciphertext: parts.ciphertextB64,
+            tag: parts.tagB64,
+        };
+    }
+    /** Decrypt an inbound envelope, enforcing session and replay checks. */
+    decrypt(envelope) {
+        if (envelope.sessionId !== this.#sessionId) {
+            throw new Error('envelope sessionId mismatch');
+        }
+        if (envelope.seq <= this.#lastInboundSeq) {
+            throw new ReplayError(`envelope seq ${envelope.seq} <= last applied ${this.#lastInboundSeq}`);
+        }
+        const plaintext = aesGcmDecrypt(this.#key, {
+            nonceHex: envelope.nonce,
+            ciphertextB64: envelope.ciphertext,
+            tagB64: envelope.tag,
+        });
+        this.#lastInboundSeq = envelope.seq;
+        return plaintext;
+    }
+}
+//# sourceMappingURL=secure-channel.js.map

package/dist/src/transport/secure-channel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"secure-channel.js","sourceRoot":"","sources":["../../../src/transport/secure-channel.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAG3D,MAAM,OAAO,WAAY,SAAQ,KAAK;IACpC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;IAC5B,CAAC;CACF;AAED,MAAM,OAAO,mBAAmB;IACrB,IAAI,CAAS;IACb,UAAU,CAAS;IAC5B;;;;;OAKG;IACM,IAAI,CAA0B;IACvC,YAAY,CAAS;IACrB,eAAe,CAAS;IAExB,YAAY,GAAW,EAAE,SAAiB,EAAE,GAAiB;QAC3D,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC;QAChB,IAAI,CAAC,UAAU,GAAG,SAAS,CAAC;QAC5B,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC;QAChB,IAAI,CAAC,YAAY,GAAG,CAAC,CAAC;QACtB,IAAI,CAAC,eAAe,GAAG,CAAC,CAAC;IAC3B,CAAC;IAED,IAAI,SAAS;QACX,OAAO,IAAI,CAAC,UAAU,CAAC;IACzB,CAAC;IAED,IAAI,eAAe;QACjB,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,YAAY,CAAC;IAC3D,CAAC;IAED,IAAI,cAAc;QAChB,OAAO,IAAI,CAAC,eAAe,CAAC;IAC9B,CAAC;IAED;;;;OAIG;IACH,OAAO,CAAC,SAAiB;QACvB,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC;QAC1E,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;IACpC,CAAC;IAED;;;;OAIG;IACH,aAAa,CAAC,GAAW,EAAE,SAAiB;QAC1C,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;IACpC,CAAC;IAED,KAAK,CAAC,GAAW,EAAE,SAAiB;QAClC,MAAM,KAAK,GAAG,aAAa,CAAC,IAAI,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;QAClD,OAAO;YACL,IAAI,EAAE,mBAAmB;YACzB,SAAS,EAAE,IAAI,CAAC,UAAU;YAC1B,GAAG;YACH,KAAK,EAAE,KAAK,CAAC,QAAQ;YACrB,UAAU,EAAE,KAAK,CAAC,aAAa;YAC/B,GAAG,EAAE,KAAK,CAAC,MAAM;SAClB,CAAC;IACJ,CAAC;IAED,wEAAwE;IACxE,OAAO,CAAC,QAAwB;QAC9B,IAAI,QAAQ,CAAC,SAAS,KAAK,IAAI,CAAC,UAAU,EAAE,CAAC;YAC3C,MAAM,IAAI,KAAK,CAAC,6BAA6B,CAAC,CAAC;QACjD,CAAC;QACD,IAAI,QAAQ,CAAC,GAAG,IAAI,IAAI,CAAC,eAAe,EAAE,CAAC;YACzC,MAAM,IAAI,WAAW,CAAC,gBAAgB,QAAQ,CAAC,GAAG,oBAAoB,IAAI,CAAC,eAAe,EAAE,CAAC,CAAC;QAChG,CAAC;QACD,MAAM,SAAS,GAAG,aAAa,CAAC,IAAI,CAAC,IAAI,EAAE;YACzC,QAAQ,EAAE,QAAQ,CAAC,KAAK;YACxB,aAAa,EAAE,QAAQ,CAAC,UAAU;YAClC,MAAM,EAAE,QAAQ,CAAC,GAAG;SACrB,CAAC,CAAC;QACH,IAAI,CAAC,eAAe,GAAG,QAAQ,CAAC,GAAG,CAAC;QACpC,OAAO,SAAS,CAAC;IACnB,CAAC;CACF"}

package/dist/src/transport/server-handshake.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Server (bridge) side of the E2EE handshake
+ * (architecture/02a §5.9.1, Phase 2): clientHello → serverHello → clientAuth →
+ * ready. Interoperates byte-for-byte with the mobile `SecureTransportLayer`.
+ */
+import { type HandshakeMode } from '@uxnan/shared';
+import type { SecureDeviceState } from '../secure-device-state.js';
+import type { MessageQueue } from './message-io.js';
+import type { TrustStore } from './trust-store.js';
+import { BridgeSecureChannel } from './secure-channel.js';
+import type { OutboundLog } from './outbound-log.js';
+export declare class HandshakeError extends Error {
+    constructor(message: string);
+}
+export interface ServerHandshakeOptions {
+    queue: MessageQueue;
+    send: (message: unknown) => void;
+    deviceState: SecureDeviceState;
+    trustStore: TrustStore;
+    displayName: string;
+    now: () => number;
+    /** If set, the clientHello sessionId must match (active pairing session). */
+    expectedSessionId?: string;
+    /** Key epoch to advertise (default 1). */
+    keyEpoch?: number;
+    /**
+     * Resolve the per-device outbound log (seq counter + catch-up window) for the
+     * phone identified in the clientHello. The channel is built over it so its
+     * `seq` continues across reconnects and every outbound message is retained.
+     * Omitted in tests that don't exercise catch-up (channel uses its fallback
+     * counter, nothing retained).
+     */
+    outboundLogFor?: (phoneDeviceId: string) => OutboundLog;
+}
+export interface ServerHandshakeResult {
+    sessionId: string;
+    phoneDeviceId: string;
+    phoneIdentityPublicKey: string;
+    mode: HandshakeMode;
+    keyEpoch: number;
+    channel: BridgeSecureChannel;
+    /**
+     * Highest bridge→phone `seq` the phone reports having applied, from
+     * `clientHello.resumeState` (0 when absent/invalid). The caller replays the
+     * outbound log's entries with a greater seq.
+     */
+    lastAppliedBridgeOutboundSeq: number;
+}
+export declare function performServerHandshake(options: ServerHandshakeOptions): Promise<ServerHandshakeResult>;

package/dist/src/transport/server-handshake.js

@@ -0,0 +1,137 @@
+/**
+ * Server (bridge) side of the E2EE handshake
+ * (architecture/02a §5.9.1, Phase 2): clientHello → serverHello → clientAuth →
+ * ready. Interoperates byte-for-byte with the mobile `SecureTransportLayer`.
+ */
+import { MAX_PAIRING_AGE_MS, SECURE_PROTOCOL_VERSION, buildHandshakeTranscript, } from '@uxnan/shared';
+import { BridgeSecureChannel } from './secure-channel.js';
+import { deriveSessionKey, generateEphemeralKeyPair, randomHex, verifyEd25519 } from './crypto.js';
+export class HandshakeError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'HandshakeError';
+    }
+}
+function requireString(obj, key) {
+    const value = obj[key];
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new HandshakeError(`clientHello missing field: ${key}`);
+    }
+    return value;
+}
+export async function performServerHandshake(options) {
+    const { queue, send, deviceState, trustStore, now } = options;
+    const helloRaw = await queue.next();
+    const hello = parseJson(helloRaw);
+    if (hello['kind'] !== 'clientHello') {
+        throw new HandshakeError(`expected clientHello, got ${String(hello['kind'])}`);
+    }
+    const sessionId = requireString(hello, 'sessionId');
+    if (options.expectedSessionId && sessionId !== options.expectedSessionId) {
+        throw new HandshakeError('sessionId does not match the active pairing session');
+    }
+    const phoneDeviceId = requireString(hello, 'phoneDeviceId');
+    const phoneIdentityPublicKey = requireString(hello, 'phoneIdentityPublicKey');
+    const phoneEphemeralPublicKey = requireString(hello, 'phoneEphemeralPublicKey');
+    const clientNonce = requireString(hello, 'clientNonce');
+    const lastAppliedBridgeOutboundSeq = parseResumeSeq(hello['resumeState']);
+    const mode = hello['handshakeMode'] === 'trusted_reconnect' ? 'trusted_reconnect' : 'qr_bootstrap';
+    if (mode === 'trusted_reconnect') {
+        const trusted = await trustStore.get(phoneDeviceId);
+        if (!trusted || trusted.publicKey !== phoneIdentityPublicKey) {
+            throw new HandshakeError('trusted reconnect: phone identity is not trusted');
+        }
+    }
+    const ephemeral = generateEphemeralKeyPair();
+    const serverNonce = randomHex(32);
+    const keyEpoch = options.keyEpoch ?? 1;
+    const expiresAtForTranscript = now() + MAX_PAIRING_AGE_MS;
+    const identity = deviceState.identity;
+    const transcript = buildHandshakeTranscript({
+        clientNonce,
+        phoneEphemeralPublicKey,
+        macEphemeralPublicKey: ephemeral.publicKeyHex,
+        serverNonce,
+        sessionId,
+        keyEpoch,
+        expiresAtForTranscript,
+    });
+    const transcriptBytes = Buffer.from(transcript, 'utf-8');
+    const macSignature = deviceState.sign(transcriptBytes);
+    send({
+        kind: 'serverHello',
+        protocolVersion: SECURE_PROTOCOL_VERSION,
+        sessionId,
+        macDeviceId: identity.macDeviceId,
+        macIdentityPublicKey: identity.macIdentityPublicKey,
+        macEphemeralPublicKey: ephemeral.publicKeyHex,
+        serverNonce,
+        keyEpoch,
+        expiresAtForTranscript,
+        macSignature,
+        clientNonce,
+        displayName: options.displayName,
+    });
+    const authRaw = await queue.next();
+    const auth = parseJson(authRaw);
+    if (auth['kind'] !== 'clientAuth') {
+        throw new HandshakeError(`expected clientAuth, got ${String(auth['kind'])}`);
+    }
+    if (auth['sessionId'] !== sessionId) {
+        throw new HandshakeError('clientAuth sessionId mismatch');
+    }
+    const phoneSignature = requireString(auth, 'phoneSignature');
+    if (!verifyEd25519(transcriptBytes, phoneSignature, phoneIdentityPublicKey)) {
+        throw new HandshakeError('phone signature verification failed');
+    }
+    const key = deriveSessionKey({
+        privateKey: ephemeral.privateKey,
+        peerPublicHex: phoneEphemeralPublicKey,
+        clientNonceHex: clientNonce,
+        serverNonceHex: serverNonce,
+    });
+    if (mode === 'qr_bootstrap') {
+        await trustStore.upsert({
+            deviceId: phoneDeviceId,
+            displayName: phoneDeviceId,
+            publicKey: phoneIdentityPublicKey,
+            pairedAt: now(),
+            lastSeen: now(),
+        });
+    }
+    send({ kind: 'ready', sessionId, keyEpoch, macDeviceId: identity.macDeviceId });
+    // Build the channel over this phone's persistent outbound log so its seq
+    // continues across reconnects and every outbound message is retained for
+    // catch-up.
+    const outboundLog = options.outboundLogFor?.(phoneDeviceId);
+    return {
+        sessionId,
+        phoneDeviceId,
+        phoneIdentityPublicKey,
+        mode,
+        keyEpoch,
+        channel: new BridgeSecureChannel(key, sessionId, outboundLog),
+        lastAppliedBridgeOutboundSeq,
+    };
+}
+/**
+ * Read `clientHello.resumeState.lastAppliedBridgeOutboundSeq` defensively: a
+ * non-negative integer is honored, anything else (absent, NaN, negative, wrong
+ * type) means "no catch-up" → 0.
+ */
+function parseResumeSeq(resumeState) {
+    if (!resumeState || typeof resumeState !== 'object')
+        return 0;
+    const value = resumeState['lastAppliedBridgeOutboundSeq'];
+    if (typeof value !== 'number' || !Number.isFinite(value) || value < 0)
+        return 0;
+    return Math.floor(value);
+}
+function parseJson(bytes) {
+    const decoded = JSON.parse(bytes.toString('utf-8'));
+    if (typeof decoded !== 'object' || decoded === null) {
+        throw new HandshakeError('handshake frame is not a JSON object');
+    }
+    return decoded;
+}
+//# sourceMappingURL=server-handshake.js.map

package/dist/src/transport/server-handshake.js.map

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

package/dist/src/transport/session-handler.d.ts

@@ -0,0 +1,19 @@
+import type { BridgeContext } from '../bridge-context.js';
+import type { HandlerRouter } from '../handler-router.js';
+import type { SecureDeviceState } from '../secure-device-state.js';
+import { type MessageIO } from './message-io.js';
+import type { TrustStore } from './trust-store.js';
+export interface SecureConnectionOptions {
+    io: MessageIO;
+    ctx: BridgeContext;
+    router: HandlerRouter;
+    deviceState: SecureDeviceState;
+    trustStore: TrustStore;
+    displayName: string;
+    expectedSessionId?: string;
+}
+/**
+ * Handle a connection end-to-end. Resolves when the connection closes. Never
+ * throws — handshake/transport failures are logged and the channel is closed.
+ */
+export declare function handleSecureConnection(options: SecureConnectionOptions): Promise<void>;