@sideband/secure-relay 0.2.1 → 0.2.3

package/dist/crypto.js.map

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

package/dist/frame.d.ts

@@ -0,0 +1,213 @@
+import type { EncryptedMessage, HandshakeAccept, HandshakeInit, SessionId } from "./types.js";
+import { SbrpErrorCode, SignalCode, SignalReason } from "./types.js";
+/**
+ * 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 declare const FrameType: {
+    readonly HandshakeInit: 1;
+    readonly HandshakeAccept: 2;
+    readonly Data: 3;
+    readonly Signal: 4;
+    readonly Ping: 16;
+    readonly Pong: 17;
+    readonly Control: 32;
+};
+export type FrameType = (typeof FrameType)[keyof typeof FrameType];
+/**
+ * Wire control codes (uint16, §14).
+ *
+ * Codes use ranges for categorization:
+ * - 0x01xx: Authentication (terminal)
+ * - 0x02xx: Routing (varies)
+ * - 0x03xx: Session (terminal)
+ * - 0x04xx: Wire format (terminal)
+ * - 0x09xx: Rate limiting (non-terminal)
+ * - 0x10xx: Session state (non-terminal)
+ */
+export declare const WireControlCode: {
+    readonly Unauthorized: 257;
+    readonly Forbidden: 258;
+    readonly DaemonNotFound: 513;
+    readonly DaemonOffline: 514;
+    readonly SessionNotFound: 769;
+    readonly SessionExpired: 770;
+    readonly MalformedFrame: 1025;
+    readonly PayloadTooLarge: 1026;
+    readonly InvalidFrameType: 1027;
+    readonly InvalidSessionId: 1028;
+    readonly DisallowedSender: 1029;
+    readonly InternalError: 1537;
+    readonly RateLimited: 2305;
+    readonly SessionPaused: 4097;
+    readonly SessionResumed: 4098;
+    readonly SessionEnded: 4099;
+    readonly SessionPending: 4100;
+};
+export type WireControlCode = (typeof WireControlCode)[keyof typeof WireControlCode];
+/** Check if a control code is terminal (closes connection) */
+export declare function isTerminalCode(code: WireControlCode): boolean;
+/** Decoded frame header */
+export interface FrameHeader {
+    type: FrameType;
+    length: number;
+    sessionId: SessionId;
+}
+/** Decoded frame (header + payload) */
+export interface Frame extends FrameHeader {
+    payload: Uint8Array;
+}
+/** Decoded Control frame payload */
+export interface ControlPayload {
+    code: WireControlCode;
+    message: string;
+}
+/** Decoded Signal frame payload */
+export interface SignalPayload {
+    signal: SignalCode;
+    reason: SignalReason;
+}
+/** Convert SbrpErrorCode to wire format (for relay-transmittable codes only) */
+export declare function toWireControlCode(code: SbrpErrorCode): WireControlCode;
+/** Convert wire control code to SbrpErrorCode */
+export declare function fromWireControlCode(code: WireControlCode): SbrpErrorCode;
+/**
+ * Encode a frame to binary wire format.
+ *
+ * @throws {SbrpError} if payload exceeds MAX_PAYLOAD_SIZE or sessionId is invalid
+ */
+export declare function encodeFrame(type: FrameType, sessionId: SessionId, payload: Uint8Array): Uint8Array;
+/**
+ * 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 declare function readFrameHeader(data: Uint8Array): FrameHeader;
+/**
+ * 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 declare function decodeFrame(data: Uint8Array): Frame;
+/**
+ * Encode HandshakeInit to wire frame.
+ *
+ * @throws {SbrpError} if initPublicKey is not exactly 32 bytes or sessionId is invalid
+ */
+export declare function encodeHandshakeInit(sessionId: SessionId, init: HandshakeInit): Uint8Array;
+/**
+ * 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 declare function encodeHandshakeAccept(sessionId: SessionId, accept: HandshakeAccept): Uint8Array;
+/**
+ * Encode Data frame (encrypted message).
+ *
+ * @throws {SbrpError} if data is too short (< nonce + authTag) or sessionId is invalid
+ */
+export declare function encodeData(sessionId: SessionId, message: EncryptedMessage): Uint8Array;
+/**
+ * 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 declare function encodeSignal(sessionId: SessionId, signal: SignalCode, reason?: SignalReason): Uint8Array;
+/**
+ * Encode Ping frame (connection-scoped keepalive).
+ *
+ * @param payload Optional 0-8 byte payload for RTT measurement
+ */
+export declare function encodePing(payload?: Uint8Array): Uint8Array;
+/**
+ * Encode Pong frame (connection-scoped keepalive response).
+ *
+ * @param payload Payload from corresponding Ping (must be copied)
+ */
+export declare function encodePong(payload?: Uint8Array): Uint8Array;
+/**
+ * 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 declare function encodeControl(sessionId: SessionId, code: WireControlCode, message?: string): Uint8Array;
+/**
+ * Decode HandshakeInit from frame.
+ *
+ * @throws {SbrpError} if frame type or payload size is invalid
+ */
+export declare function decodeHandshakeInit(frame: Frame): HandshakeInit;
+/**
+ * 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 declare function decodeHandshakeAccept(frame: Frame): HandshakeAccept;
+/**
+ * Decode Data frame (encrypted message).
+ *
+ * @throws {SbrpError} if frame type or payload is invalid
+ */
+export declare function decodeData(frame: Frame): EncryptedMessage;
+/**
+ * Decode Signal frame (daemon → relay).
+ *
+ * @throws {SbrpError} if frame type, payload size, or signal values are invalid
+ */
+export declare function decodeSignal(frame: Frame): SignalPayload;
+/**
+ * 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 declare function decodeControl(frame: Frame): ControlPayload;
+/**
+ * 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 declare class FrameDecoder {
+    private buffer;
+    /**
+     * Push data and yield any complete frames.
+     */
+    push(data: Uint8Array): Generator<Frame>;
+    /** Reset decoder state, discarding any buffered data */
+    reset(): void;
+    /** Number of bytes currently buffered */
+    get bufferedBytes(): number;
+}
+//# sourceMappingURL=frame.d.ts.map

package/dist/frame.d.ts.map

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