@sideband/secure-relay 0.2.2 → 0.3.0

package/dist/frame.js

@@ -0,0 +1,554 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Binary wire format for Sideband Relay Protocol (SBRP).
+ *
+ * Frame structure (§13):
+ * ```
+ * ┌───────────┬──────────────┬────────────────┬─────────────────────┐
+ * │ Type (1B) │ Length (4B)  │ SessionID (8B) │ Payload (0..64KB)   │
+ * └───────────┴──────────────┴────────────────┴─────────────────────┘
+ * ```
+ *
+ * All multi-byte integers are big-endian.
+ */
+import { ED25519_PUBLIC_KEY_LENGTH, ED25519_SIGNATURE_LENGTH, FRAME_HEADER_SIZE, HANDSHAKE_ACCEPT_PAYLOAD_SIZE, HANDSHAKE_INIT_PAYLOAD_SIZE, MAX_PAYLOAD_SIZE, MAX_PING_PAYLOAD_SIZE, MIN_CONTROL_PAYLOAD_SIZE, MIN_ENCRYPTED_PAYLOAD_SIZE, SIGNAL_PAYLOAD_SIZE, X25519_PUBLIC_KEY_LENGTH, } from "./constants.js";
+import { extractSequence } from "./crypto.js";
+import { SbrpError, SbrpErrorCode, SignalCode, SignalReason } from "./types.js";
+const textEncoder = new TextEncoder();
+const textDecoder = new TextDecoder("utf-8", { fatal: false });
+/**
+ * Frame type discriminant (wire byte).
+ *
+ * Frame types are organized by authority:
+ * - Endpoint frames (0x01-0x03): Forwarded by relay, E2EE
+ * - Signal frame (0x04): Daemon → Relay only
+ * - Keepalive frames (0x10-0x11): Connection-scoped, never forwarded
+ * - Control frame (0x20): Relay → Endpoint only
+ */
+export const FrameType = {
+    // Endpoint frames (forwarded, E2EE)
+    HandshakeInit: 0x01,
+    HandshakeAccept: 0x02,
+    Data: 0x03, // Renamed from Encrypted for clarity
+    // Signal frame (daemon → relay)
+    Signal: 0x04,
+    // Keepalive frames (connection-scoped, never forwarded)
+    Ping: 0x10,
+    Pong: 0x11,
+    // Control frame (relay → endpoint)
+    Control: 0x20,
+};
+/**
+ * Wire control codes (uint16, §14).
+ *
+ * Codes use ranges for categorization:
+ * - 0x01xx: Authentication (terminal)
+ * - 0x02xx: Routing (terminal)
+ * - 0x03xx: Session (terminal)
+ * - 0x04xx: Wire format (terminal)
+ * - 0x09xx: Throttling (varies: rate_limited=N, backpressure=T)
+ * - 0x10xx: Session state (non-terminal)
+ */
+export const WireControlCode = {
+    // Authentication (0x01xx) - Terminal
+    Unauthorized: 0x0101,
+    Forbidden: 0x0102,
+    // Routing (0x02xx) - Terminal
+    DaemonNotFound: 0x0201,
+    DaemonOffline: 0x0202, // Terminal
+    // Session (0x03xx) - Terminal
+    SessionNotFound: 0x0301,
+    SessionExpired: 0x0302,
+    // Wire Format (0x04xx) - Terminal
+    MalformedFrame: 0x0401,
+    PayloadTooLarge: 0x0402,
+    InvalidFrameType: 0x0403,
+    InvalidSessionId: 0x0404,
+    DisallowedSender: 0x0405,
+    // Internal (0x06xx) - Terminal
+    InternalError: 0x0601,
+    // Throttling (0x09xx) - Varies (RateLimited=N, Backpressure=T)
+    RateLimited: 0x0901,
+    Backpressure: 0x0902,
+    // Session State (0x10xx) - Non-terminal
+    SessionPaused: 0x1001,
+    SessionResumed: 0x1002,
+    SessionEnded: 0x1003,
+    SessionPending: 0x1004,
+};
+/**
+ * Check if a control code is terminal (relay closes WebSocket after sending).
+ *
+ * Fail-safe pattern: only enumerate non-terminal exceptions; unknown/new codes
+ * default to terminal so they never silently keep a session alive.
+ */
+export function isTerminalCode(code) {
+    switch (code) {
+        case WireControlCode.RateLimited:
+        case WireControlCode.SessionPaused:
+        case WireControlCode.SessionResumed:
+        case WireControlCode.SessionEnded:
+        case WireControlCode.SessionPending:
+            return false;
+        default:
+            return true;
+    }
+}
+// ============================================================================
+// Control code mapping
+// ============================================================================
+const sbrpToWire = {
+    // Authentication
+    [SbrpErrorCode.Unauthorized]: WireControlCode.Unauthorized,
+    [SbrpErrorCode.Forbidden]: WireControlCode.Forbidden,
+    // Routing
+    [SbrpErrorCode.DaemonNotFound]: WireControlCode.DaemonNotFound,
+    [SbrpErrorCode.DaemonOffline]: WireControlCode.DaemonOffline,
+    // Session
+    [SbrpErrorCode.SessionNotFound]: WireControlCode.SessionNotFound,
+    [SbrpErrorCode.SessionExpired]: WireControlCode.SessionExpired,
+    // Wire Format
+    [SbrpErrorCode.MalformedFrame]: WireControlCode.MalformedFrame,
+    [SbrpErrorCode.PayloadTooLarge]: WireControlCode.PayloadTooLarge,
+    [SbrpErrorCode.InvalidFrameType]: WireControlCode.InvalidFrameType,
+    [SbrpErrorCode.InvalidSessionId]: WireControlCode.InvalidSessionId,
+    [SbrpErrorCode.DisallowedSender]: WireControlCode.DisallowedSender,
+    // Internal
+    [SbrpErrorCode.InternalError]: WireControlCode.InternalError,
+    // Rate Limiting / Backpressure
+    [SbrpErrorCode.RateLimited]: WireControlCode.RateLimited,
+    [SbrpErrorCode.Backpressure]: WireControlCode.Backpressure,
+    // Session State
+    [SbrpErrorCode.SessionPaused]: WireControlCode.SessionPaused,
+    [SbrpErrorCode.SessionResumed]: WireControlCode.SessionResumed,
+    [SbrpErrorCode.SessionEnded]: WireControlCode.SessionEnded,
+    [SbrpErrorCode.SessionPending]: WireControlCode.SessionPending,
+};
+const wireToSbrp = {
+    // Authentication
+    [WireControlCode.Unauthorized]: SbrpErrorCode.Unauthorized,
+    [WireControlCode.Forbidden]: SbrpErrorCode.Forbidden,
+    // Routing
+    [WireControlCode.DaemonNotFound]: SbrpErrorCode.DaemonNotFound,
+    [WireControlCode.DaemonOffline]: SbrpErrorCode.DaemonOffline,
+    // Session
+    [WireControlCode.SessionNotFound]: SbrpErrorCode.SessionNotFound,
+    [WireControlCode.SessionExpired]: SbrpErrorCode.SessionExpired,
+    // Wire Format
+    [WireControlCode.MalformedFrame]: SbrpErrorCode.MalformedFrame,
+    [WireControlCode.PayloadTooLarge]: SbrpErrorCode.PayloadTooLarge,
+    [WireControlCode.InvalidFrameType]: SbrpErrorCode.InvalidFrameType,
+    [WireControlCode.InvalidSessionId]: SbrpErrorCode.InvalidSessionId,
+    [WireControlCode.DisallowedSender]: SbrpErrorCode.DisallowedSender,
+    // Internal
+    [WireControlCode.InternalError]: SbrpErrorCode.InternalError,
+    // Rate Limiting / Backpressure
+    [WireControlCode.RateLimited]: SbrpErrorCode.RateLimited,
+    [WireControlCode.Backpressure]: SbrpErrorCode.Backpressure,
+    // Session State
+    [WireControlCode.SessionPaused]: SbrpErrorCode.SessionPaused,
+    [WireControlCode.SessionResumed]: SbrpErrorCode.SessionResumed,
+    [WireControlCode.SessionEnded]: SbrpErrorCode.SessionEnded,
+    [WireControlCode.SessionPending]: SbrpErrorCode.SessionPending,
+};
+/** Convert SbrpErrorCode to wire format (for relay-transmittable codes only) */
+export function toWireControlCode(code) {
+    const wire = sbrpToWire[code];
+    if (wire === undefined) {
+        throw new Error(`Unknown or non-wire SbrpErrorCode: ${code}`);
+    }
+    return wire;
+}
+/** Convert wire control code to SbrpErrorCode */
+export function fromWireControlCode(code) {
+    const sbrp = wireToSbrp[code];
+    if (sbrp === undefined) {
+        throw new Error(`Unknown WireControlCode: 0x${code.toString(16).padStart(4, "0")}`);
+    }
+    return sbrp;
+}
+// ============================================================================
+// Validation helpers
+// ============================================================================
+const MAX_UINT64 = 0xffffffffffffffffn;
+/**
+ * Check if frame type requires non-zero sessionId (§13.2).
+ *
+ * Session-bound: HandshakeInit, HandshakeAccept, Data, Signal
+ * Connection-scoped (sessionId must be 0): Ping, Pong
+ * Variable (depends on content): Control
+ */
+function isSessionBound(type) {
+    return (type === FrameType.HandshakeInit ||
+        type === FrameType.HandshakeAccept ||
+        type === FrameType.Data ||
+        type === FrameType.Signal);
+}
+/** Check if frame type requires sessionId = 0 (connection-scoped) */
+function isConnectionScoped(type) {
+    return type === FrameType.Ping || type === FrameType.Pong;
+}
+function validateSessionId(sessionId, type) {
+    if (sessionId < 0n || sessionId > MAX_UINT64) {
+        throw new SbrpError(SbrpErrorCode.MalformedFrame, `SessionId out of uint64 range: ${sessionId}`);
+    }
+    if (isSessionBound(type) && sessionId === 0n) {
+        throw new SbrpError(SbrpErrorCode.MalformedFrame, `Session-bound frame type 0x${type.toString(16).padStart(2, "0")} requires non-zero sessionId`);
+    }
+    if (isConnectionScoped(type) && sessionId !== 0n) {
+        throw new SbrpError(SbrpErrorCode.MalformedFrame, `Connection-scoped frame type 0x${type.toString(16).padStart(2, "0")} requires sessionId = 0`);
+    }
+}
+// ============================================================================
+// Low-level frame encoding/decoding
+// ============================================================================
+/**
+ * Encode a frame to binary wire format.
+ *
+ * @throws {SbrpError} if payload exceeds MAX_PAYLOAD_SIZE or sessionId is invalid
+ */
+export function encodeFrame(type, sessionId, payload) {
+    validateSessionId(sessionId, type);
+    if (payload.length > MAX_PAYLOAD_SIZE) {
+        throw new SbrpError(SbrpErrorCode.PayloadTooLarge, `Payload size ${payload.length} exceeds maximum ${MAX_PAYLOAD_SIZE}`);
+    }
+    const frame = new Uint8Array(FRAME_HEADER_SIZE + payload.length);
+    const view = new DataView(frame.buffer);
+    frame[0] = type;
+    view.setUint32(1, payload.length, false);
+    view.setBigUint64(5, sessionId, false);
+    frame.set(payload, FRAME_HEADER_SIZE);
+    return frame;
+}
+/**
+ * Read frame header without decoding payload.
+ * Useful for routing decisions before full decode.
+ *
+ * Validates wire format constraints including non-zero sessionId
+ * for session-bound frames (§13.2).
+ *
+ * @throws {SbrpError} if buffer is too short, length exceeds max, or sessionId invalid
+ */
+export function readFrameHeader(data) {
+    if (data.length < FRAME_HEADER_SIZE) {
+        throw new SbrpError(SbrpErrorCode.MalformedFrame, `Frame too short: ${data.length} < ${FRAME_HEADER_SIZE}`);
+    }
+    const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+    const type = data[0];
+    switch (type) {
+        case FrameType.HandshakeInit:
+        case FrameType.HandshakeAccept:
+        case FrameType.Data:
+        case FrameType.Signal:
+        case FrameType.Ping:
+        case FrameType.Pong:
+        case FrameType.Control:
+            break;
+        default:
+            throw new SbrpError(SbrpErrorCode.InvalidFrameType, `Unknown frame type: 0x${type.toString(16).padStart(2, "0")}`);
+    }
+    const length = view.getUint32(1, false);
+    const sessionId = view.getBigUint64(5, false);
+    if (length > MAX_PAYLOAD_SIZE) {
+        throw new SbrpError(SbrpErrorCode.PayloadTooLarge, `Payload length ${length} exceeds maximum ${MAX_PAYLOAD_SIZE}`);
+    }
+    // Wire format constraint: session-bound frames require non-zero sessionId
+    if (isSessionBound(type) && sessionId === 0n) {
+        throw new SbrpError(SbrpErrorCode.MalformedFrame, `Session-bound frame type 0x${type.toString(16).padStart(2, "0")} requires non-zero sessionId`);
+    }
+    // Wire format constraint: connection-scoped frames require sessionId = 0
+    if (isConnectionScoped(type) && sessionId !== 0n) {
+        throw new SbrpError(SbrpErrorCode.MalformedFrame, `Connection-scoped frame type 0x${type.toString(16).padStart(2, "0")} requires sessionId = 0`);
+    }
+    return { type, length, sessionId };
+}
+/**
+ * Decode a complete frame from binary data.
+ *
+ * Rejects trailing bytes to catch framing mistakes. Use `FrameDecoder`
+ * for streaming scenarios with multiple frames per buffer.
+ *
+ * @throws {SbrpError} if frame is malformed or has trailing bytes
+ */
+export function decodeFrame(data) {
+    const header = readFrameHeader(data);
+    const expectedSize = FRAME_HEADER_SIZE + header.length;
+    if (data.length < expectedSize) {
+        throw new SbrpError(SbrpErrorCode.MalformedFrame, `Frame truncated: got ${data.length}, expected ${expectedSize}`);
+    }
+    if (data.length > expectedSize) {
+        throw new SbrpError(SbrpErrorCode.MalformedFrame, `Frame has ${data.length - expectedSize} trailing bytes`);
+    }
+    const payload = data.subarray(FRAME_HEADER_SIZE, expectedSize);
+    return { ...header, payload };
+}
+// ============================================================================
+// High-level frame encoding (typed message → binary)
+// ============================================================================
+/**
+ * Encode HandshakeInit to wire frame.
+ *
+ * @throws {SbrpError} if initPublicKey is not exactly 32 bytes or sessionId is invalid
+ */
+export function encodeHandshakeInit(sessionId, init) {
+    if (init.initPublicKey.length !== HANDSHAKE_INIT_PAYLOAD_SIZE) {
+        throw new SbrpError(SbrpErrorCode.MalformedFrame, `initPublicKey must be ${HANDSHAKE_INIT_PAYLOAD_SIZE} bytes, got ${init.initPublicKey.length}`);
+    }
+    return encodeFrame(FrameType.HandshakeInit, sessionId, init.initPublicKey);
+}
+/**
+ * Encode HandshakeAccept to wire frame.
+ *
+ * Wire layout (128 bytes): identityPublicKey(32) + acceptPublicKey(32) + signature(64)
+ *
+ * @throws {SbrpError} if field sizes are wrong or sessionId is invalid
+ */
+export function encodeHandshakeAccept(sessionId, accept) {
+    if (accept.identityPublicKey.length !== ED25519_PUBLIC_KEY_LENGTH) {
+        throw new SbrpError(SbrpErrorCode.MalformedFrame, `identityPublicKey must be ${ED25519_PUBLIC_KEY_LENGTH} bytes, got ${accept.identityPublicKey.length}`);
+    }
+    if (accept.acceptPublicKey.length !== X25519_PUBLIC_KEY_LENGTH) {
+        throw new SbrpError(SbrpErrorCode.MalformedFrame, `acceptPublicKey must be ${X25519_PUBLIC_KEY_LENGTH} bytes, got ${accept.acceptPublicKey.length}`);
+    }
+    if (accept.signature.length !== ED25519_SIGNATURE_LENGTH) {
+        throw new SbrpError(SbrpErrorCode.MalformedFrame, `signature must be ${ED25519_SIGNATURE_LENGTH} bytes, got ${accept.signature.length}`);
+    }
+    const payload = new Uint8Array(HANDSHAKE_ACCEPT_PAYLOAD_SIZE);
+    payload.set(accept.identityPublicKey, 0);
+    payload.set(accept.acceptPublicKey, ED25519_PUBLIC_KEY_LENGTH);
+    payload.set(accept.signature, ED25519_PUBLIC_KEY_LENGTH + X25519_PUBLIC_KEY_LENGTH);
+    return encodeFrame(FrameType.HandshakeAccept, sessionId, payload);
+}
+/**
+ * Encode Data frame (encrypted message).
+ *
+ * @throws {SbrpError} if data is too short (< nonce + authTag) or sessionId is invalid
+ */
+export function encodeData(sessionId, message) {
+    if (message.data.length < MIN_ENCRYPTED_PAYLOAD_SIZE) {
+        throw new SbrpError(SbrpErrorCode.MalformedFrame, `Data payload must be at least ${MIN_ENCRYPTED_PAYLOAD_SIZE} bytes, got ${message.data.length}`);
+    }
+    return encodeFrame(FrameType.Data, sessionId, message.data);
+}
+/**
+ * Encode Signal frame (daemon → relay).
+ *
+ * @param sessionId Session being signaled
+ * @param signal Signal code (ready or close)
+ * @param reason Reason code (for close signal)
+ */
+export function encodeSignal(sessionId, signal, reason = SignalReason.None) {
+    const payload = new Uint8Array(SIGNAL_PAYLOAD_SIZE);
+    payload[0] = signal;
+    payload[1] = reason;
+    return encodeFrame(FrameType.Signal, sessionId, payload);
+}
+/**
+ * Encode Ping frame (connection-scoped keepalive).
+ *
+ * @param payload Optional 0-8 byte payload for RTT measurement
+ */
+export function encodePing(payload = new Uint8Array(0)) {
+    if (payload.length > MAX_PING_PAYLOAD_SIZE) {
+        throw new SbrpError(SbrpErrorCode.PayloadTooLarge, `Ping payload must be 0-${MAX_PING_PAYLOAD_SIZE} bytes, got ${payload.length}`);
+    }
+    return encodeFrame(FrameType.Ping, 0n, payload);
+}
+/**
+ * Encode Pong frame (connection-scoped keepalive response).
+ *
+ * @param payload Payload from corresponding Ping (must be copied)
+ */
+export function encodePong(payload = new Uint8Array(0)) {
+    if (payload.length > MAX_PING_PAYLOAD_SIZE) {
+        throw new SbrpError(SbrpErrorCode.PayloadTooLarge, `Pong payload must be 0-${MAX_PING_PAYLOAD_SIZE} bytes, got ${payload.length}`);
+    }
+    return encodeFrame(FrameType.Pong, 0n, payload);
+}
+/**
+ * Encode Control frame (relay → endpoint).
+ *
+ * @param sessionId Session ID (non-zero for session events, 0 for connection errors)
+ * @param code Control code from WireControlCode
+ * @param message Optional diagnostic message (for errors only)
+ */
+export function encodeControl(sessionId, code, message) {
+    const msgBytes = message ? textEncoder.encode(message) : null;
+    const payload = new Uint8Array(2 + (msgBytes?.length ?? 0));
+    new DataView(payload.buffer).setUint16(0, code, false);
+    if (msgBytes)
+        payload.set(msgBytes, 2);
+    return encodeFrame(FrameType.Control, sessionId, payload);
+}
+// ============================================================================
+// High-level frame decoding (Frame → typed message)
+// ============================================================================
+/**
+ * Decode HandshakeInit from frame.
+ *
+ * @throws {SbrpError} if frame type or payload size is invalid
+ */
+export function decodeHandshakeInit(frame) {
+    if (frame.type !== FrameType.HandshakeInit) {
+        throw new SbrpError(SbrpErrorCode.InvalidFrameType, `Expected HandshakeInit (0x01), got 0x${frame.type.toString(16).padStart(2, "0")}`);
+    }
+    if (frame.payload.length !== HANDSHAKE_INIT_PAYLOAD_SIZE) {
+        throw new SbrpError(SbrpErrorCode.MalformedFrame, `HandshakeInit payload must be ${HANDSHAKE_INIT_PAYLOAD_SIZE} bytes, got ${frame.payload.length}`);
+    }
+    return {
+        type: "handshake.init",
+        initPublicKey: frame.payload.slice(),
+    };
+}
+/**
+ * Decode HandshakeAccept from frame.
+ *
+ * Wire layout (128 bytes): identityPublicKey(32) + acceptPublicKey(32) + signature(64)
+ *
+ * @throws {SbrpError} if frame type or payload size is invalid
+ */
+export function decodeHandshakeAccept(frame) {
+    if (frame.type !== FrameType.HandshakeAccept) {
+        throw new SbrpError(SbrpErrorCode.InvalidFrameType, `Expected HandshakeAccept (0x02), got 0x${frame.type.toString(16).padStart(2, "0")}`);
+    }
+    if (frame.payload.length !== HANDSHAKE_ACCEPT_PAYLOAD_SIZE) {
+        throw new SbrpError(SbrpErrorCode.MalformedFrame, `HandshakeAccept payload must be ${HANDSHAKE_ACCEPT_PAYLOAD_SIZE} bytes, got ${frame.payload.length}`);
+    }
+    const keyEnd = ED25519_PUBLIC_KEY_LENGTH + X25519_PUBLIC_KEY_LENGTH;
+    return {
+        type: "handshake.accept",
+        identityPublicKey: frame.payload.slice(0, ED25519_PUBLIC_KEY_LENGTH),
+        acceptPublicKey: frame.payload.slice(ED25519_PUBLIC_KEY_LENGTH, keyEnd),
+        signature: frame.payload.slice(keyEnd, keyEnd + ED25519_SIGNATURE_LENGTH),
+    };
+}
+/**
+ * Decode Data frame (encrypted message).
+ *
+ * @throws {SbrpError} if frame type or payload is invalid
+ */
+export function decodeData(frame) {
+    if (frame.type !== FrameType.Data) {
+        throw new SbrpError(SbrpErrorCode.InvalidFrameType, `Expected Data (0x03), got 0x${frame.type.toString(16).padStart(2, "0")}`);
+    }
+    if (frame.payload.length < MIN_ENCRYPTED_PAYLOAD_SIZE) {
+        throw new SbrpError(SbrpErrorCode.MalformedFrame, `Data payload must be at least ${MIN_ENCRYPTED_PAYLOAD_SIZE} bytes, got ${frame.payload.length}`);
+    }
+    const seq = extractSequence(frame.payload);
+    return {
+        type: "encrypted",
+        seq,
+        data: frame.payload.slice(),
+    };
+}
+/**
+ * Decode Signal frame (daemon → relay).
+ *
+ * @throws {SbrpError} if frame type, payload size, or signal values are invalid
+ */
+export function decodeSignal(frame) {
+    if (frame.type !== FrameType.Signal) {
+        throw new SbrpError(SbrpErrorCode.InvalidFrameType, `Expected Signal (0x04), got 0x${frame.type.toString(16).padStart(2, "0")}`);
+    }
+    if (frame.payload.length !== SIGNAL_PAYLOAD_SIZE) {
+        throw new SbrpError(SbrpErrorCode.MalformedFrame, `Signal payload must be ${SIGNAL_PAYLOAD_SIZE} bytes, got ${frame.payload.length}`);
+    }
+    // Length validated above (exactly SIGNAL_PAYLOAD_SIZE = 2 bytes)
+    const signal = frame.payload[0];
+    const reason = frame.payload[1];
+    if (signal !== SignalCode.Ready && signal !== SignalCode.Close) {
+        throw new SbrpError(SbrpErrorCode.MalformedFrame, `Unknown signal code: 0x${signal.toString(16).padStart(2, "0")}`);
+    }
+    switch (reason) {
+        case SignalReason.None:
+        case SignalReason.StateLost:
+        case SignalReason.Shutdown:
+        case SignalReason.Policy:
+        case SignalReason.Error:
+            break;
+        default:
+            throw new SbrpError(SbrpErrorCode.MalformedFrame, `Unknown signal reason: 0x${reason.toString(16).padStart(2, "0")}`);
+    }
+    return { signal: signal, reason: reason };
+}
+/**
+ * Decode Control frame (relay → endpoint).
+ *
+ * Invalid UTF-8 sequences in message are replaced with U+FFFD.
+ *
+ * @throws {SbrpError} if frame type or payload is invalid
+ */
+export function decodeControl(frame) {
+    if (frame.type !== FrameType.Control) {
+        throw new SbrpError(SbrpErrorCode.InvalidFrameType, `Expected Control (0x20), got 0x${frame.type.toString(16).padStart(2, "0")}`);
+    }
+    if (frame.payload.length < MIN_CONTROL_PAYLOAD_SIZE) {
+        throw new SbrpError(SbrpErrorCode.MalformedFrame, `Control payload must be at least ${MIN_CONTROL_PAYLOAD_SIZE} bytes, got ${frame.payload.length}`);
+    }
+    const view = new DataView(frame.payload.buffer, frame.payload.byteOffset, frame.payload.byteLength);
+    const rawCode = view.getUint16(0, false);
+    if (wireToSbrp[rawCode] === undefined) {
+        throw new SbrpError(SbrpErrorCode.MalformedFrame, `Unknown control code: 0x${rawCode.toString(16).padStart(4, "0")}`);
+    }
+    const code = rawCode;
+    // TextDecoder with fatal:false replaces invalid UTF-8 with U+FFFD
+    const message = textDecoder.decode(frame.payload.subarray(2));
+    return { code, message };
+}
+// ============================================================================
+// Streaming frame decoder
+// ============================================================================
+/**
+ * Streaming frame decoder for incremental parsing.
+ *
+ * Accumulates bytes and yields complete frames. Useful when frames
+ * may be fragmented across WebSocket messages or TCP reads.
+ *
+ * @example
+ * ```typescript
+ * const decoder = new FrameDecoder();
+ * ws.on("message", (data) => {
+ *   for (const frame of decoder.push(data)) {
+ *     handleFrame(frame);
+ *   }
+ * });
+ * ```
+ */
+export class FrameDecoder {
+    buffer = new Uint8Array(0);
+    /**
+     * Push data and yield any complete frames.
+     */
+    *push(data) {
+        // Append to buffer
+        if (this.buffer.length === 0) {
+            this.buffer = data;
+        }
+        else {
+            const combined = new Uint8Array(this.buffer.length + data.length);
+            combined.set(this.buffer, 0);
+            combined.set(data, this.buffer.length);
+            this.buffer = combined;
+        }
+        // Yield complete frames
+        while (this.buffer.length >= FRAME_HEADER_SIZE) {
+            const header = readFrameHeader(this.buffer);
+            const frameSize = FRAME_HEADER_SIZE + header.length;
+            if (this.buffer.length < frameSize) {
+                break; // Incomplete frame, wait for more data
+            }
+            const payload = this.buffer.subarray(FRAME_HEADER_SIZE, frameSize);
+            yield { ...header, payload };
+            this.buffer = this.buffer.subarray(frameSize);
+        }
+    }
+    /** Reset decoder state, discarding any buffered data */
+    reset() {
+        this.buffer = new Uint8Array(0);
+    }
+    /** Number of bytes currently buffered */
+    get bufferedBytes() {
+        return this.buffer.length;
+    }
+}
+//# sourceMappingURL=frame.js.map

package/dist/frame.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame.js","sourceRoot":"","sources":["../src/frame.ts"],"names":[],"mappings":"AAAA,sCAAsC;AAEtC;;;;;;;;;;;GAWG;AAEH,OAAO,EACL,yBAAyB,EACzB,wBAAwB,EACxB,iBAAiB,EACjB,6BAA6B,EAC7B,2BAA2B,EAC3B,gBAAgB,EAChB,qBAAqB,EACrB,wBAAwB,EACxB,0BAA0B,EAC1B,mBAAmB,EACnB,wBAAwB,GACzB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAO9C,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAEhF,MAAM,WAAW,GAAG,IAAI,WAAW,EAAE,CAAC;AACtC,MAAM,WAAW,GAAG,IAAI,WAAW,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;AAE/D;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG;IACvB,oCAAoC;IACpC,aAAa,EAAE,IAAI;IACnB,eAAe,EAAE,IAAI;IACrB,IAAI,EAAE,IAAI,EAAE,qCAAqC;IAEjD,gCAAgC;IAChC,MAAM,EAAE,IAAI;IAEZ,wDAAwD;IACxD,IAAI,EAAE,IAAI;IACV,IAAI,EAAE,IAAI;IAEV,mCAAmC;IACnC,OAAO,EAAE,IAAI;CACL,CAAC;AAIX;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,qCAAqC;IACrC,YAAY,EAAE,MAAM;IACpB,SAAS,EAAE,MAAM;IAEjB,8BAA8B;IAC9B,cAAc,EAAE,MAAM;IACtB,aAAa,EAAE,MAAM,EAAE,WAAW;IAElC,8BAA8B;IAC9B,eAAe,EAAE,MAAM;IACvB,cAAc,EAAE,MAAM;IAEtB,kCAAkC;IAClC,cAAc,EAAE,MAAM;IACtB,eAAe,EAAE,MAAM;IACvB,gBAAgB,EAAE,MAAM;IACxB,gBAAgB,EAAE,MAAM;IACxB,gBAAgB,EAAE,MAAM;IAExB,+BAA+B;IAC/B,aAAa,EAAE,MAAM;IAErB,+DAA+D;IAC/D,WAAW,EAAE,MAAM;IACnB,YAAY,EAAE,MAAM;IAEpB,wCAAwC;IACxC,aAAa,EAAE,MAAM;IACrB,cAAc,EAAE,MAAM;IACtB,YAAY,EAAE,MAAM;IACpB,cAAc,EAAE,MAAM;CACd,CAAC;AAKX;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,IAAqB;IAClD,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,eAAe,CAAC,WAAW,CAAC;QACjC,KAAK,eAAe,CAAC,aAAa,CAAC;QACnC,KAAK,eAAe,CAAC,cAAc,CAAC;QACpC,KAAK,eAAe,CAAC,YAAY,CAAC;QAClC,KAAK,eAAe,CAAC,cAAc;YACjC,OAAO,KAAK,CAAC;QACf;YACE,OAAO,IAAI,CAAC;IAChB,CAAC;AACH,CAAC;AA0BD,+EAA+E;AAC/E,uBAAuB;AACvB,+EAA+E;AAE/E,MAAM,UAAU,GAAoC;IAClD,iBAAiB;IACjB,CAAC,aAAa,CAAC,YAAY,CAAC,EAAE,eAAe,CAAC,YAAY;IAC1D,CAAC,aAAa,CAAC,SAAS,CAAC,EAAE,eAAe,CAAC,SAAS;IAEpD,UAAU;IACV,CAAC,aAAa,CAAC,cAAc,CAAC,EAAE,eAAe,CAAC,cAAc;IAC9D,CAAC,aAAa,CAAC,aAAa,CAAC,EAAE,eAAe,CAAC,aAAa;IAE5D,UAAU;IACV,CAAC,aAAa,CAAC,eAAe,CAAC,EAAE,eAAe,CAAC,eAAe;IAChE,CAAC,aAAa,CAAC,cAAc,CAAC,EAAE,eAAe,CAAC,cAAc;IAE9D,cAAc;IACd,CAAC,aAAa,CAAC,cAAc,CAAC,EAAE,eAAe,CAAC,cAAc;IAC9D,CAAC,aAAa,CAAC,eAAe,CAAC,EAAE,eAAe,CAAC,eAAe;IAChE,CAAC,aAAa,CAAC,gBAAgB,CAAC,EAAE,eAAe,CAAC,gBAAgB;IAClE,CAAC,aAAa,CAAC,gBAAgB,CAAC,EAAE,eAAe,CAAC,gBAAgB;IAClE,CAAC,aAAa,CAAC,gBAAgB,CAAC,EAAE,eAAe,CAAC,gBAAgB;IAElE,WAAW;IACX,CAAC,aAAa,CAAC,aAAa,CAAC,EAAE,eAAe,CAAC,aAAa;IAE5D,+BAA+B;IAC/B,CAAC,aAAa,CAAC,WAAW,CAAC,EAAE,eAAe,CAAC,WAAW;IACxD,CAAC,aAAa,CAAC,YAAY,CAAC,EAAE,eAAe,CAAC,YAAY;IAE1D,gBAAgB;IAChB,CAAC,aAAa,CAAC,aAAa,CAAC,EAAE,eAAe,CAAC,aAAa;IAC5D,CAAC,aAAa,CAAC,cAAc,CAAC,EAAE,eAAe,CAAC,cAAc;IAC9D,CAAC,aAAa,CAAC,YAAY,CAAC,EAAE,eAAe,CAAC,YAAY;IAC1D,CAAC,aAAa,CAAC,cAAc,CAAC,EAAE,eAAe,CAAC,cAAc;CAC/D,CAAC;AAEF,MAAM,UAAU,GAAkC;IAChD,iBAAiB;IACjB,CAAC,eAAe,CAAC,YAAY,CAAC,EAAE,aAAa,CAAC,YAAY;IAC1D,CAAC,eAAe,CAAC,SAAS,CAAC,EAAE,aAAa,CAAC,SAAS;IAEpD,UAAU;IACV,CAAC,eAAe,CAAC,cAAc,CAAC,EAAE,aAAa,CAAC,cAAc;IAC9D,CAAC,eAAe,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC,aAAa;IAE5D,UAAU;IACV,CAAC,eAAe,CAAC,eAAe,CAAC,EAAE,aAAa,CAAC,eAAe;IAChE,CAAC,eAAe,CAAC,cAAc,CAAC,EAAE,aAAa,CAAC,cAAc;IAE9D,cAAc;IACd,CAAC,eAAe,CAAC,cAAc,CAAC,EAAE,aAAa,CAAC,cAAc;IAC9D,CAAC,eAAe,CAAC,eAAe,CAAC,EAAE,aAAa,CAAC,eAAe;IAChE,CAAC,eAAe,CAAC,gBAAgB,CAAC,EAAE,aAAa,CAAC,gBAAgB;IAClE,CAAC,eAAe,CAAC,gBAAgB,CAAC,EAAE,aAAa,CAAC,gBAAgB;IAClE,CAAC,eAAe,CAAC,gBAAgB,CAAC,EAAE,aAAa,CAAC,gBAAgB;IAElE,WAAW;IACX,CAAC,eAAe,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC,aAAa;IAE5D,+BAA+B;IAC/B,CAAC,eAAe,CAAC,WAAW,CAAC,EAAE,aAAa,CAAC,WAAW;IACxD,CAAC,eAAe,CAAC,YAAY,CAAC,EAAE,aAAa,CAAC,YAAY;IAE1D,gBAAgB;IAChB,CAAC,eAAe,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC,aAAa;IAC5D,CAAC,eAAe,CAAC,cAAc,CAAC,EAAE,aAAa,CAAC,cAAc;IAC9D,CAAC,eAAe,CAAC,YAAY,CAAC,EAAE,aAAa,CAAC,YAAY;IAC1D,CAAC,eAAe,CAAC,cAAc,CAAC,EAAE,aAAa,CAAC,cAAc;CAC/D,CAAC;AAEF,gFAAgF;AAChF,MAAM,UAAU,iBAAiB,CAAC,IAAmB;IACnD,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;IAC9B,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CAAC,sCAAsC,IAAI,EAAE,CAAC,CAAC;IAChE,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,iDAAiD;AACjD,MAAM,UAAU,mBAAmB,CAAC,IAAqB;IACvD,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;IAC9B,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CACb,8BAA8B,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CACnE,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,+EAA+E;AAC/E,qBAAqB;AACrB,+EAA+E;AAE/E,MAAM,UAAU,GAAG,mBAAsB,CAAC;AAE1C;;;;;;GAMG;AACH,SAAS,cAAc,CAAC,IAAe;IACrC,OAAO,CACL,IAAI,KAAK,SAAS,CAAC,aAAa;QAChC,IAAI,KAAK,SAAS,CAAC,eAAe;QAClC,IAAI,KAAK,SAAS,CAAC,IAAI;QACvB,IAAI,KAAK,SAAS,CAAC,MAAM,CAC1B,CAAC;AACJ,CAAC;AAED,qEAAqE;AACrE,SAAS,kBAAkB,CAAC,IAAe;IACzC,OAAO,IAAI,KAAK,SAAS,CAAC,IAAI,IAAI,IAAI,KAAK,SAAS,CAAC,IAAI,CAAC;AAC5D,CAAC;AAED,SAAS,iBAAiB,CAAC,SAAoB,EAAE,IAAe;IAC9D,IAAI,SAAS,GAAG,EAAE,IAAI,SAAS,GAAG,UAAU,EAAE,CAAC;QAC7C,MAAM,IAAI,SAAS,CACjB,aAAa,CAAC,cAAc,EAC5B,kCAAkC,SAAS,EAAE,CAC9C,CAAC;IACJ,CAAC;IACD,IAAI,cAAc,CAAC,IAAI,CAAC,IAAI,SAAS,KAAK,EAAE,EAAE,CAAC;QAC7C,MAAM,IAAI,SAAS,CACjB,aAAa,CAAC,cAAc,EAC5B,8BAA8B,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,8BAA8B,CAC/F,CAAC;IACJ,CAAC;IACD,IAAI,kBAAkB,CAAC,IAAI,CAAC,IAAI,SAAS,KAAK,EAAE,EAAE,CAAC;QACjD,MAAM,IAAI,SAAS,CACjB,aAAa,CAAC,cAAc,EAC5B,kCAAkC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,yBAAyB,CAC9F,CAAC;IACJ,CAAC;AACH,CAAC;AAED,+EAA+E;AAC/E,oCAAoC;AACpC,+EAA+E;AAE/E;;;;GAIG;AACH,MAAM,UAAU,WAAW,CACzB,IAAe,EACf,SAAoB,EACpB,OAAmB;IAEnB,iBAAiB,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;IAEnC,IAAI,OAAO,CAAC,MAAM,GAAG,gBAAgB,EAAE,CAAC;QACtC,MAAM,IAAI,SAAS,CACjB,aAAa,CAAC,eAAe,EAC7B,gBAAgB,OAAO,CAAC,MAAM,oBAAoB,gBAAgB,EAAE,CACrE,CAAC;IACJ,CAAC;IAED,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACjE,MAAM,IAAI,GAAG,IAAI,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAExC,KAAK,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAChB,IAAI,CAAC,SAAS,CAAC,CAAC,EAAE,OAAO,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IACzC,IAAI,CAAC,YAAY,CAAC,CAAC,EAAE,SAAS,EAAE,KAAK,CAAC,CAAC;IACvC,KAAK,CAAC,GAAG,CAAC,OAAO,EAAE,iBAAiB,CAAC,CAAC;IAEtC,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAAC,IAAgB;IAC9C,IAAI,IAAI,CAAC,MAAM,GAAG,iBAAiB,EAAE,CAAC;QACpC,MAAM,IAAI,SAAS,CACjB,aAAa,CAAC,cAAc,EAC5B,oBAAoB,IAAI,CAAC,MAAM,MAAM,iBAAiB,EAAE,CACzD,CAAC;IACJ,CAAC;IAED,MAAM,IAAI,GAAG,IAAI,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;IACzE,MAAM,IAAI,GAAG,IAAI,CAAC,CAAC,CAAc,CAAC;IAElC,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,SAAS,CAAC,aAAa,CAAC;QAC7B,KAAK,SAAS,CAAC,eAAe,CAAC;QAC/B,KAAK,SAAS,CAAC,IAAI,CAAC;QACpB,KAAK,SAAS,CAAC,MAAM,CAAC;QACtB,KAAK,SAAS,CAAC,IAAI,CAAC;QACpB,KAAK,SAAS,CAAC,IAAI,CAAC;QACpB,KAAK,SAAS,CAAC,OAAO;YACpB,MAAM;QACR;YACE,MAAM,IAAI,SAAS,CACjB,aAAa,CAAC,gBAAgB,EAC9B,yBAA0B,IAAe,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAC1E,CAAC;IACN,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;IACxC,MAAM,SAAS,GAAG,IAAI,CAAC,YAAY,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;IAE9C,IAAI,MAAM,GAAG,gBAAgB,EAAE,CAAC;QAC9B,MAAM,IAAI,SAAS,CACjB,aAAa,CAAC,eAAe,EAC7B,kBAAkB,MAAM,oBAAoB,gBAAgB,EAAE,CAC/D,CAAC;IACJ,CAAC;IAED,0EAA0E;IAC1E,IAAI,cAAc,CAAC,IAAI,CAAC,IAAI,SAAS,KAAK,EAAE,EAAE,CAAC;QAC7C,MAAM,IAAI,SAAS,CACjB,aAAa,CAAC,cAAc,EAC5B,8BAA8B,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,8BAA8B,CAC/F,CAAC;IACJ,CAAC;IAED,yEAAyE;IACzE,IAAI,kBAAkB,CAAC,IAAI,CAAC,IAAI,SAAS,KAAK,EAAE,EAAE,CAAC;QACjD,MAAM,IAAI,SAAS,CACjB,aAAa,CAAC,cAAc,EAC5B,kCAAkC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,yBAAyB,CAC9F,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;AACrC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CAAC,IAAgB;IAC1C,MAAM,MAAM,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;IACrC,MAAM,YAAY,GAAG,iBAAiB,GAAG,MAAM,CAAC,MAAM,CAAC;IAEvD,IAAI,IAAI,CAAC,MAAM,GAAG,YAAY,EAAE,CAAC;QAC/B,MAAM,IAAI,SAAS,CACjB,aAAa,CAAC,cAAc,EAC5B,wBAAwB,IAAI,CAAC,MAAM,cAAc,YAAY,EAAE,CAChE,CAAC;IACJ,CAAC;IAED,IAAI,IAAI,CAAC,MAAM,GAAG,YAAY,EAAE,CAAC;QAC/B,MAAM,IAAI,SAAS,CACjB,aAAa,CAAC,cAAc,EAC5B,aAAa,IAAI,CAAC,MAAM,GAAG,YAAY,iBAAiB,CACzD,CAAC;IACJ,CAAC;IAED,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,iBAAiB,EAAE,YAAY,CAAC,CAAC;IAC/D,OAAO,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,CAAC;AAChC,CAAC;AAED,+EAA+E;AAC/E,qDAAqD;AACrD,+EAA+E;AAE/E;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CACjC,SAAoB,EACpB,IAAmB;IAEnB,IAAI,IAAI,CAAC,aAAa,CAAC,MAAM,KAAK,2BAA2B,EAAE,CAAC;QAC9D,MAAM,IAAI,SAAS,CACjB,aAAa,CAAC,cAAc,EAC5B,yBAAyB,2BAA2B,eAAe,IAAI,CAAC,aAAa,CAAC,MAAM,EAAE,CAC/F,CAAC;IACJ,CAAC;IACD,OAAO,WAAW,CAAC,SAAS,CAAC,aAAa,EAAE,SAAS,EAAE,IAAI,CAAC,aAAa,CAAC,CAAC;AAC7E,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CACnC,SAAoB,EACpB,MAAuB;IAEvB,IAAI,MAAM,CAAC,iBAAiB,CAAC,MAAM,KAAK,yBAAyB,EAAE,CAAC;QAClE,MAAM,IAAI,SAAS,CACjB,aAAa,CAAC,cAAc,EAC5B,6BAA6B,yBAAyB,eAAe,MAAM,CAAC,iBAAiB,CAAC,MAAM,EAAE,CACvG,CAAC;IACJ,CAAC;IACD,IAAI,MAAM,CAAC,eAAe,CAAC,MAAM,KAAK,wBAAwB,EAAE,CAAC;QAC/D,MAAM,IAAI,SAAS,CACjB,aAAa,CAAC,cAAc,EAC5B,2BAA2B,wBAAwB,eAAe,MAAM,CAAC,eAAe,CAAC,MAAM,EAAE,CAClG,CAAC;IACJ,CAAC;IACD,IAAI,MAAM,CAAC,SAAS,CAAC,MAAM,KAAK,wBAAwB,EAAE,CAAC;QACzD,MAAM,IAAI,SAAS,CACjB,aAAa,CAAC,cAAc,EAC5B,qBAAqB,wBAAwB,eAAe,MAAM,CAAC,SAAS,CAAC,MAAM,EAAE,CACtF,CAAC;IACJ,CAAC;IACD,MAAM,OAAO,GAAG,IAAI,UAAU,CAAC,6BAA6B,CAAC,CAAC;IAC9D,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,iBAAiB,EAAE,CAAC,CAAC,CAAC;IACzC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,eAAe,EAAE,yBAAyB,CAAC,CAAC;IAC/D,OAAO,CAAC,GAAG,CACT,MAAM,CAAC,SAAS,EAChB,yBAAyB,GAAG,wBAAwB,CACrD,CAAC;IACF,OAAO,WAAW,CAAC,SAAS,CAAC,eAAe,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;AACpE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,UAAU,CACxB,SAAoB,EACpB,OAAyB;IAEzB,IAAI,OAAO,CAAC,IAAI,CAAC,MAAM,GAAG,0BAA0B,EAAE,CAAC;QACrD,MAAM,IAAI,SAAS,CACjB,aAAa,CAAC,cAAc,EAC5B,iCAAiC,0BAA0B,eAAe,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,CAChG,CAAC;IACJ,CAAC;IACD,OAAO,WAAW,CAAC,SAAS,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;AAC9D,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAC1B,SAAoB,EACpB,MAAkB,EAClB,SAAuB,YAAY,CAAC,IAAI;IAExC,MAAM,OAAO,GAAG,IAAI,UAAU,CAAC,mBAAmB,CAAC,CAAC;IACpD,OAAO,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC;IACpB,OAAO,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC;IACpB,OAAO,WAAW,CAAC,SAAS,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;AAC3D,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,UAAU,CACxB,UAAsB,IAAI,UAAU,CAAC,CAAC,CAAC;IAEvC,IAAI,OAAO,CAAC,MAAM,GAAG,qBAAqB,EAAE,CAAC;QAC3C,MAAM,IAAI,SAAS,CACjB,aAAa,CAAC,eAAe,EAC7B,0BAA0B,qBAAqB,eAAe,OAAO,CAAC,MAAM,EAAE,CAC/E,CAAC;IACJ,CAAC;IACD,OAAO,WAAW,CAAC,SAAS,CAAC,IAAI,EAAE,EAAE,EAAE,OAAO,CAAC,CAAC;AAClD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,UAAU,CACxB,UAAsB,IAAI,UAAU,CAAC,CAAC,CAAC;IAEvC,IAAI,OAAO,CAAC,MAAM,GAAG,qBAAqB,EAAE,CAAC;QAC3C,MAAM,IAAI,SAAS,CACjB,aAAa,CAAC,eAAe,EAC7B,0BAA0B,qBAAqB,eAAe,OAAO,CAAC,MAAM,EAAE,CAC/E,CAAC;IACJ,CAAC;IACD,OAAO,WAAW,CAAC,SAAS,CAAC,IAAI,EAAE,EAAE,EAAE,OAAO,CAAC,CAAC;AAClD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAC3B,SAAoB,EACpB,IAAqB,EACrB,OAAgB;IAEhB,MAAM,QAAQ,GAAG,OAAO,CAAC,CAAC,CAAC,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAC9D,MAAM,OAAO,GAAG,IAAI,UAAU,CAAC,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,IAAI,CAAC,CAAC,CAAC,CAAC;IAC5D,IAAI,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;IACvD,IAAI,QAAQ;QAAE,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC;IACvC,OAAO,WAAW,CAAC,SAAS,CAAC,OAAO,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;AAC5D,CAAC;AAED,+EAA+E;AAC/E,oDAAoD;AACpD,+EAA+E;AAE/E;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAY;IAC9C,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC,aAAa,EAAE,CAAC;QAC3C,MAAM,IAAI,SAAS,CACjB,aAAa,CAAC,gBAAgB,EAC9B,wCAAwC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CACnF,CAAC;IACJ,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,KAAK,2BAA2B,EAAE,CAAC;QACzD,MAAM,IAAI,SAAS,CACjB,aAAa,CAAC,cAAc,EAC5B,iCAAiC,2BAA2B,eAAe,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,CAClG,CAAC;IACJ,CAAC;IACD,OAAO;QACL,IAAI,EAAE,gBAAgB;QACtB,aAAa,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE;KACrC,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAAY;IAChD,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC,eAAe,EAAE,CAAC;QAC7C,MAAM,IAAI,SAAS,CACjB,aAAa,CAAC,gBAAgB,EAC9B,0CAA0C,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CACrF,CAAC;IACJ,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,KAAK,6BAA6B,EAAE,CAAC;QAC3D,MAAM,IAAI,SAAS,CACjB,aAAa,CAAC,cAAc,EAC5B,mCAAmC,6BAA6B,eAAe,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,CACtG,CAAC;IACJ,CAAC;IACD,MAAM,MAAM,GAAG,yBAAyB,GAAG,wBAAwB,CAAC;IACpE,OAAO;QACL,IAAI,EAAE,kBAAkB;QACxB,iBAAiB,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,yBAAyB,CAAC;QACpE,eAAe,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,yBAAyB,EAAE,MAAM,CAAC;QACvE,SAAS,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,wBAAwB,CAAC;KAC1E,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAC,KAAY;IACrC,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC,IAAI,EAAE,CAAC;QAClC,MAAM,IAAI,SAAS,CACjB,aAAa,CAAC,gBAAgB,EAC9B,+BAA+B,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAC1E,CAAC;IACJ,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,GAAG,0BAA0B,EAAE,CAAC;QACtD,MAAM,IAAI,SAAS,CACjB,aAAa,CAAC,cAAc,EAC5B,iCAAiC,0BAA0B,eAAe,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,CACjG,CAAC;IACJ,CAAC;IACD,MAAM,GAAG,GAAG,eAAe,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAC3C,OAAO;QACL,IAAI,EAAE,WAAW;QACjB,GAAG;QACH,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE;KAC5B,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,KAAY;IACvC,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC,MAAM,EAAE,CAAC;QACpC,MAAM,IAAI,SAAS,CACjB,aAAa,CAAC,gBAAgB,EAC9B,iCAAiC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAC5E,CAAC;IACJ,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,KAAK,mBAAmB,EAAE,CAAC;QACjD,MAAM,IAAI,SAAS,CACjB,aAAa,CAAC,cAAc,EAC5B,0BAA0B,mBAAmB,eAAe,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,CACnF,CAAC;IACJ,CAAC;IACD,iEAAiE;IACjE,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,CAAE,CAAC;IACjC,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,CAAE,CAAC;IACjC,IAAI,MAAM,KAAK,UAAU,CAAC,KAAK,IAAI,MAAM,KAAK,UAAU,CAAC,KAAK,EAAE,CAAC;QAC/D,MAAM,IAAI,SAAS,CACjB,aAAa,CAAC,cAAc,EAC5B,0BAA0B,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CACjE,CAAC;IACJ,CAAC;IACD,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,YAAY,CAAC,IAAI,CAAC;QACvB,KAAK,YAAY,CAAC,SAAS,CAAC;QAC5B,KAAK,YAAY,CAAC,QAAQ,CAAC;QAC3B,KAAK,YAAY,CAAC,MAAM,CAAC;QACzB,KAAK,YAAY,CAAC,KAAK;YACrB,MAAM;QACR;YACE,MAAM,IAAI,SAAS,CACjB,aAAa,CAAC,cAAc,EAC5B,4BAA4B,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CACnE,CAAC;IACN,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,MAAoB,EAAE,MAAM,EAAE,MAAsB,EAAE,CAAC;AAC1E,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,KAAY;IACxC,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC,OAAO,EAAE,CAAC;QACrC,MAAM,IAAI,SAAS,CACjB,aAAa,CAAC,gBAAgB,EAC9B,kCAAkC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAC7E,CAAC;IACJ,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,GAAG,wBAAwB,EAAE,CAAC;QACpD,MAAM,IAAI,SAAS,CACjB,aAAa,CAAC,cAAc,EAC5B,oCAAoC,wBAAwB,eAAe,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,CAClG,CAAC;IACJ,CAAC;IACD,MAAM,IAAI,GAAG,IAAI,QAAQ,CACvB,KAAK,CAAC,OAAO,CAAC,MAAM,EACpB,KAAK,CAAC,OAAO,CAAC,UAAU,EACxB,KAAK,CAAC,OAAO,CAAC,UAAU,CACzB,CAAC;IACF,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;IACzC,IAAI,UAAU,CAAC,OAAO,CAAC,KAAK,SAAS,EAAE,CAAC;QACtC,MAAM,IAAI,SAAS,CACjB,aAAa,CAAC,cAAc,EAC5B,2BAA2B,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CACnE,CAAC;IACJ,CAAC;IACD,MAAM,IAAI,GAAG,OAA0B,CAAC;IACxC,kEAAkE;IAClE,MAAM,OAAO,GAAG,WAAW,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9D,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;AAC3B,CAAC;AAED,+EAA+E;AAC/E,0BAA0B;AAC1B,+EAA+E;AAE/E;;;;;;;;;;;;;;;GAeG;AACH,MAAM,OAAO,YAAY;IACf,MAAM,GAAe,IAAI,UAAU,CAAC,CAAC,CAAC,CAAC;IAE/C;;OAEG;IACH,CAAC,IAAI,CAAC,IAAgB;QACpB,mBAAmB;QACnB,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC7B,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QACrB,CAAC;aAAM,CAAC;YACN,MAAM,QAAQ,GAAG,IAAI,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC;YAClE,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;YAC7B,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YACvC,IAAI,CAAC,MAAM,GAAG,QAAQ,CAAC;QACzB,CAAC;QAED,wBAAwB;QACxB,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,IAAI,iBAAiB,EAAE,CAAC;YAC/C,MAAM,MAAM,GAAG,eAAe,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YAC5C,MAAM,SAAS,GAAG,iBAAiB,GAAG,MAAM,CAAC,MAAM,CAAC;YAEpD,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,SAAS,EAAE,CAAC;gBACnC,MAAM,CAAC,uCAAuC;YAChD,CAAC;YAED,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,iBAAiB,EAAE,SAAS,CAAC,CAAC;YACnE,MAAM,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,CAAC;YAC7B,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;QAChD,CAAC;IACH,CAAC;IAED,wDAAwD;IACxD,KAAK;QACH,IAAI,CAAC,MAAM,GAAG,IAAI,UAAU,CAAC,CAAC,CAAC,CAAC;IAClC,CAAC;IAED,yCAAyC;IACzC,IAAI,aAAa;QACf,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC;IAC5B,CAAC;CACF"}

package/dist/handshake.d.ts

@@ -0,0 +1,39 @@
+import type { DaemonId, EphemeralKeyPair, HandshakeAccept, HandshakeInit, IdentityKeyPair, SessionKeys } from "./types.js";
+/**
+ * Create a handshake init message (client side).
+ *
+ * Generates an ephemeral X25519 keypair for this session.
+ */
+export declare function createHandshakeInit(): {
+    message: HandshakeInit;
+    ephemeralKeyPair: EphemeralKeyPair;
+};
+/**
+ * Process handshake init and create accept message (daemon side).
+ *
+ * 1. Generate ephemeral X25519 keypair
+ * 2. Sign ephemeral public key with identity key (context-bound)
+ * 3. Derive session keys
+ *
+ * NOTE: Callers MUST enforce a 30-second handshake timeout per SBRP §1.4.
+ * This function does not track time; timeout enforcement is a transport concern.
+ */
+export declare function processHandshakeInit(init: HandshakeInit, daemonId: DaemonId, identityKeyPair: IdentityKeyPair): {
+    message: HandshakeAccept;
+    sessionKeys: SessionKeys;
+};
+/**
+ * Process handshake accept message (client side).
+ *
+ * 1. Verify signature using PINNED identity key (TOFU)
+ * 2. Derive session keys using same transcript hash as daemon
+ *
+ * NOTE: Callers MUST enforce a 30-second handshake timeout per SBRP §1.4.
+ * This function does not track time; timeout enforcement is a transport concern.
+ *
+ * @param ephemeralKeyPair The privateKey is zeroized in-place after key derivation.
+ * @throws {SbrpError} IdentityKeyChanged if advertised key doesn't match pinned key
+ * @throws {SbrpError} HandshakeFailed if signature verification fails
+ */
+export declare function processHandshakeAccept(accept: HandshakeAccept, daemonId: DaemonId, pinnedIdentityPublicKey: Uint8Array, ephemeralKeyPair: EphemeralKeyPair): SessionKeys;
+//# sourceMappingURL=handshake.d.ts.map

package/dist/handshake.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handshake.d.ts","sourceRoot":"","sources":["../src/handshake.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EACV,QAAQ,EACR,gBAAgB,EAChB,eAAe,EACf,aAAa,EACb,eAAe,EACf,WAAW,EACZ,MAAM,YAAY,CAAC;AAGpB;;;;GAIG;AACH,wBAAgB,mBAAmB,IAAI;IACrC,OAAO,EAAE,aAAa,CAAC;IACvB,gBAAgB,EAAE,gBAAgB,CAAC;CACpC,CASA;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,aAAa,EACnB,QAAQ,EAAE,QAAQ,EAClB,eAAe,EAAE,eAAe,GAC/B;IAAE,OAAO,EAAE,eAAe,CAAC;IAAC,WAAW,EAAE,WAAW,CAAA;CAAE,CAqCxD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,eAAe,EACvB,QAAQ,EAAE,QAAQ,EAClB,uBAAuB,EAAE,UAAU,EACnC,gBAAgB,EAAE,gBAAgB,GACjC,WAAW,CAoDb"}