edge-ai-client-ts 1.0.0

package/dist/session/sftp.js

@@ -0,0 +1,335 @@
+/**
+ * SFTP-over-frame — structured file RPC over the shell binary channel.
+ * Mirrors `edge-client/src/session/sftp.rs`.
+ *
+ * A frame type `FrameType::Sftp = 6` carries a JSON request/response payload
+ * on the existing 17-byte shell frame. The relay is a dumb byte-pump:
+ * it forwards Sftp frames verbatim; ALL filesystem logic lives here.
+ * Under the hood this is JSON RPC over `node:fs` — we do NOT shell out
+ * to `sftp` (the edge-client already runs as the Standard User with full
+ * filesystem access).
+ *
+ * ## Protocol
+ * Request (browser → edge, Sftp frame payload = UTF-8 JSON):
+ * ```json
+ * {"op":"list|read|write|delete|stat","path":"/abs/path"[,"content":"..."],"reqId":1}
+ * ```
+ * Response (edge → browser):
+ * ```json
+ * {"reqId":1,"ok":true,"data":{...}}
+ * {"reqId":1,"ok":false,"error":"..."}
+ * ```
+ *
+ * ## P1-a / R-MED-2 — per-session SFTP chroot
+ * When the relay sends an `SftpRoot` control frame (frame type 7) on shell
+ * session open, the edge stores the supplied root path in a per-session map.
+ * Every subsequent Sftp op for that session is resolved under the root.
+ * A `null` root (or absent) means "no chroot" (default).
+ *
+ * ## E-H2 — max file size for read/write ops
+ * Files larger than 32 MiB are refused to prevent browser OOM.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { EventEmitter } from 'node:events';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Maximum file size for read/write ops (32 MiB). Mirrors Rust MAX_SFTP_BYTES. */
+const MAX_SFTP_BYTES = 32 * 1024 * 1024;
+function okResponse(reqId, data) {
+    return { reqId, ok: true, data };
+}
+function errResponse(reqId, error) {
+    return { reqId, ok: false, error };
+}
+/** Serialize response to JSON bytes. Cannot fail (mirrors Rust SftpResponse::to_bytes). */
+function responseToBytes(resp) {
+    try {
+        return Buffer.from(JSON.stringify(resp), 'utf8');
+    }
+    catch {
+        return Buffer.from('{"reqId":-1,"ok":false,"error":"serialize failed"}', 'utf8');
+    }
+}
+// ---------------------------------------------------------------------------
+// Per-session chroot map (mirrors Rust SESSION_ROOTS)
+// ---------------------------------------------------------------------------
+const sessionRoots = new Map();
+function setSessionRoot(sessionId, payload) {
+    let msg;
+    try {
+        msg = JSON.parse(payload.toString('utf8'));
+    }
+    catch {
+        // Malformed payload — ignored (mirrors Rust behavior)
+        return;
+    }
+    const root = msg.root;
+    if (root === undefined || root === null || root === '') {
+        sessionRoots.delete(sessionId);
+        return;
+    }
+    // Validation: absolute, no null bytes, length <= 4096
+    if (!root.startsWith('/'))
+        return;
+    if (root.includes('\0'))
+        return;
+    if (root.length > 4096)
+        return;
+    if (root === '/') {
+        sessionRoots.delete(sessionId);
+        return;
+    }
+    sessionRoots.set(sessionId, root);
+}
+// ---------------------------------------------------------------------------
+// Path resolution (mirrors Rust resolve_sftp_path)
+// ---------------------------------------------------------------------------
+function resolveSftpPath(sessionId, userPath) {
+    const root = sessionRoots.get(sessionId);
+    // No chroot → pass through
+    if (root === undefined) {
+        if (userPath.includes('\0')) {
+            throw new Error('path contains null byte');
+        }
+        return userPath;
+    }
+    // Chroot active — reject absolute paths and traversal
+    if (userPath.includes('\0')) {
+        throw new Error('path contains null byte');
+    }
+    // Empty path = root itself
+    if (userPath === '' || userPath === '.') {
+        return root;
+    }
+    // Reject absolute paths
+    if (path.isAbsolute(userPath)) {
+        throw new Error('absolute path not allowed under chroot');
+    }
+    // Reject .. traversal
+    const parts = userPath.split(path.sep).filter((p) => p !== '' && p !== '.');
+    for (const part of parts) {
+        if (part === '..') {
+            throw new Error('path traversal not allowed (..)');
+        }
+    }
+    // Concatenate root + user_path
+    const resolved = path.join(root, userPath);
+    // Containment check: resolved path must start with root
+    const resolvedAbs = path.resolve(resolved);
+    const rootAbs = path.resolve(root);
+    if (!resolvedAbs.startsWith(rootAbs + path.sep) && resolvedAbs !== rootAbs) {
+        throw new Error(`path escapes chroot root (resolved outside ${rootAbs})`);
+    }
+    return resolved;
+}
+// ---------------------------------------------------------------------------
+// File operations (mirrors Rust op_list, op_read, etc.)
+// ---------------------------------------------------------------------------
+function opList(reqPath, reqId) {
+    let entries = [];
+    try {
+        const dirEntries = fs.readdirSync(reqPath, { withFileTypes: true });
+        for (const entry of dirEntries) {
+            let size = 0;
+            let modified = 0;
+            try {
+                const stat = fs.statSync(path.join(reqPath, entry.name));
+                size = stat.isDirectory() ? 0 : stat.size;
+                modified = Math.floor(stat.mtimeMs / 1000);
+            }
+            catch {
+                // skip entries we can't stat
+                continue;
+            }
+            entries.push({
+                name: entry.name,
+                kind: entry.isDirectory() ? 'dir' : 'file',
+                size,
+                modified,
+            });
+        }
+        // Sort: dirs first, then name ascending
+        entries.sort((a, b) => {
+            if (a.kind !== b.kind)
+                return a.kind === 'dir' ? -1 : 1;
+            return a.name.localeCompare(b.name);
+        });
+    }
+    catch (e) {
+        return errResponse(reqId, `list failed: ${String(e)}`);
+    }
+    return okResponse(reqId, { entries });
+}
+function opRead(reqPath, reqId) {
+    // Size check first
+    try {
+        const stat = fs.statSync(reqPath);
+        if (stat.size > MAX_SFTP_BYTES) {
+            return errResponse(reqId, `file too large: ${stat.size} bytes (max ${MAX_SFTP_BYTES} bytes / ${MAX_SFTP_BYTES / (1024 * 1024)} MiB)`);
+        }
+    }
+    catch {
+        // stat failed — proceed to read (will surface the I/O error)
+    }
+    try {
+        const content = fs.readFileSync(reqPath, 'utf8');
+        return okResponse(reqId, { content });
+    }
+    catch (e) {
+        const err = e;
+        if (err.code === 'EEXIST' || (e instanceof Error && e.message.includes('invalid'))) {
+            return errResponse(reqId, 'not UTF-8 / binary');
+        }
+        return errResponse(reqId, `read failed: ${String(e)}`);
+    }
+}
+function opWrite(reqPath, content, reqId) {
+    if (content === undefined) {
+        return errResponse(reqId, "write requires 'content'");
+    }
+    // Size cap
+    if (Buffer.byteLength(content, 'utf8') > MAX_SFTP_BYTES) {
+        return errResponse(reqId, `content too large: ${Buffer.byteLength(content, 'utf8')} bytes (max ${MAX_SFTP_BYTES} bytes / ${MAX_SFTP_BYTES / (1024 * 1024)} MiB)`);
+    }
+    // Check parent exists
+    const parent = path.dirname(reqPath);
+    if (parent !== '' && parent !== '.' && !fs.existsSync(parent)) {
+        return errResponse(reqId, 'parent does not exist');
+    }
+    const bytes = Buffer.byteLength(content, 'utf8');
+    try {
+        fs.writeFileSync(reqPath, content, 'utf8');
+        return okResponse(reqId, { bytes });
+    }
+    catch (e) {
+        return errResponse(reqId, `write failed: ${String(e)}`);
+    }
+}
+function opDelete(reqPath, reqId) {
+    let stat;
+    try {
+        stat = fs.lstatSync(reqPath);
+    }
+    catch (e) {
+        return errResponse(reqId, `delete failed: ${String(e)}`);
+    }
+    if (stat.isDirectory()) {
+        // Check if empty
+        try {
+            const children = fs.readdirSync(reqPath);
+            if (children.length > 0) {
+                return errResponse(reqId, 'directory not empty');
+            }
+        }
+        catch (e) {
+            return errResponse(reqId, `delete failed: ${String(e)}`);
+        }
+        try {
+            fs.rmdirSync(reqPath);
+            return okResponse(reqId, { deleted: true });
+        }
+        catch (e) {
+            return errResponse(reqId, `delete failed: ${String(e)}`);
+        }
+    }
+    else {
+        try {
+            fs.unlinkSync(reqPath);
+            return okResponse(reqId, { deleted: true });
+        }
+        catch (e) {
+            return errResponse(reqId, `delete failed: ${String(e)}`);
+        }
+    }
+}
+function opStat(reqPath, reqId) {
+    let stat;
+    try {
+        stat = fs.statSync(reqPath);
+    }
+    catch (e) {
+        return errResponse(reqId, `stat failed: ${String(e)}`);
+    }
+    const isDir = stat.isDirectory();
+    return okResponse(reqId, {
+        kind: isDir ? 'dir' : 'file',
+        size: isDir ? 0 : stat.size,
+        modified: Math.floor(stat.mtimeMs / 1000),
+    });
+}
+function dispatch(sessionId, req) {
+    let resolvedPath;
+    try {
+        resolvedPath = resolveSftpPath(sessionId, req.path);
+    }
+    catch (e) {
+        return errResponse(reqId(req), String(e));
+    }
+    switch (req.op) {
+        case 'list':
+            return opList(resolvedPath, reqId(req));
+        case 'read':
+            return opRead(resolvedPath, reqId(req));
+        case 'write':
+            return opWrite(resolvedPath, req.content, reqId(req));
+        case 'delete':
+            return opDelete(resolvedPath, reqId(req));
+        case 'stat':
+            return opStat(resolvedPath, reqId(req));
+        default:
+            return errResponse(reqId(req), `unknown op: ${req.op}`);
+    }
+}
+function reqId(req) {
+    return typeof req.reqId === 'number' ? req.reqId : -1;
+}
+export class SftpForwarder {
+    emitter = new EventEmitter();
+    /**
+     * Handle an inbound Sftp frame. Mirrors Rust `handle_sftp_request`.
+     * Parses the JSON request, dispatches the file op, and emits the response
+     * frame (to be sent back to the relay/browser).
+     */
+    handleFrame(sessionId, frameType, payload) {
+        // SftpRoot (frame type 7) → store the session root
+        if (frameType === 7) {
+            setSessionRoot(sessionId, payload);
+            return;
+        }
+        // Sftp (frame type 6) → dispatch the file op
+        const req = (() => {
+            try {
+                return JSON.parse(payload.toString('utf8'));
+            }
+            catch {
+                return { op: 'parse-error', path: '', reqId: -1 };
+            }
+        })();
+        if (req.op === 'parse-error') {
+            const resp = errResponse(-1, 'bad request');
+            const respBytes = responseToBytes(resp);
+            this.emitter.emit('frame', sessionId, frameType, respBytes);
+            return;
+        }
+        const resp = dispatch(sessionId, req);
+        const respBytes = responseToBytes(resp);
+        this.emitter.emit('frame', sessionId, frameType, respBytes);
+    }
+    /**
+     * Register a handler for outbound Sftp response frames.
+     * The handler receives (sessionId, frameType, payloadBytes).
+     */
+    onFrame(handler) {
+        this.emitter.on('frame', handler);
+    }
+}
+// ---------------------------------------------------------------------------
+// Exports for testing
+// ---------------------------------------------------------------------------
+/** Clear all session roots (for tests only). */
+export function clearSessionRoots() {
+    sessionRoots.clear();
+}
+export { setSessionRoot, resolveSftpPath, dispatch };

package/dist/session/shell-frame.d.ts

@@ -0,0 +1,77 @@
+/** Header length: 16-byte session_id + 1-byte frame_type. */
+export declare const SHELL_HEADER_LEN = 17;
+/** 16-byte raw UUID length (matches Rust `Uuid::as_bytes()` length). */
+export declare const SESSION_ID_LEN = 16;
+/** Resize payload length: cols (u16 BE) + rows (u16 BE). */
+export declare const RESIZE_PAYLOAD_LEN = 4;
+/** Wire-numeric frame type. Values are part of the public protocol — DO NOT renumber. */
+export declare const FrameType: {
+    readonly Data: 0;
+    readonly Resize: 1;
+    readonly Close: 2;
+    readonly OpenControl: 3;
+    readonly CloseControl: 4;
+    readonly Sftp: 6;
+    readonly SftpRoot: 7;
+};
+export type FrameTypeValue = (typeof FrameType)[keyof typeof FrameType];
+/**
+ * Inverse lookup: byte → typed name. Returns `null` for unknown / reserved.
+ * Mirrors Rust `FrameType::from_u8` exactly.
+ */
+export declare function frameTypeFromByte(b: number): FrameTypeValue | null;
+/** Generate a fresh 16-byte session id (UUID v4 raw bytes). */
+export declare function newSessionId(): Buffer;
+/**
+ * Convert a UUID string ("550e8400-e29b-41d4-a716-446655440000" or
+ * already-stripped 32-hex form) to the 16-byte session id used on the wire.
+ * Returns null on invalid input. Mirrors Rust `Uuid::parse_str` then `as_bytes`.
+ */
+export declare function sessionIdFromString(id: string): Buffer | null;
+/** Convert a 16-byte session id back to canonical UUID string (with dashes). */
+export declare function sessionIdToString(bytes: Uint8Array): string | null;
+export interface ShellFrame {
+    /** 16-byte raw session id (NOT a hex string). */
+    readonly sessionId: Uint8Array;
+    readonly frameType: FrameTypeValue;
+    readonly payload: Uint8Array;
+}
+/**
+ * Build a `data` frame carrying raw PTY bytes (or browser keystrokes, the
+ * wire is symmetric). Mirrors Rust `ShellFrame::data`.
+ */
+export declare function dataFrame(sessionId: Uint8Array, payload: Uint8Array): ShellFrame;
+/**
+ * Build a `resize` frame. Payload is 4 big-endian bytes: cols u16 BE + rows u16 BE.
+ * Mirrors Rust `ShellFrame::resize`.
+ */
+export declare function resizeFrame(sessionId: Uint8Array, cols: number, rows: number): ShellFrame;
+/**
+ * Build a `close` frame (no payload). Mirrors Rust `ShellFrame::close`.
+ */
+export declare function closeFrame(sessionId: Uint8Array): ShellFrame;
+/**
+ * Encode a frame to its on-wire byte representation. Matches the Rust
+ * `ShellFrame::encode` exactly: `[16 session_id][1 frame_type][payload...]`.
+ */
+export declare function encodeFrame(frame: ShellFrame): Buffer;
+/**
+ * Decode the on-wire bytes into a frame. Returns null if the buffer is
+ * shorter than `SHELL_HEADER_LEN` (17 bytes) or the frame-type byte is
+ * unknown / reserved. Mirrors Rust `ShellFrame::decode`.
+ *
+ * The payload is COPIED (not aliased) so callers can safely reuse the input
+ * buffer for the next frame — mirrors the Rust comment about copying into
+ * the reader task buffer.
+ */
+export declare function decodeFrame(bytes: Uint8Array): ShellFrame | null;
+/**
+ * Decode a resize frame's payload into [cols, rows]. Returns null if the
+ * payload is not exactly 4 bytes (defensive — encoder always emits 4 bytes
+ * but a malformed peer might send something else).
+ */
+export declare function decodeResizePayload(payload: Uint8Array): {
+    cols: number;
+    rows: number;
+} | null;
+export declare const __RESERVED_FRAME_TYPE_5__: 5;

package/dist/session/shell-frame.js

@@ -0,0 +1,199 @@
+/**
+ * Shell frame codec — the on-wire binary protocol for `/shell-edge`.
+ *
+ * Mirrors `edge-client/src/session/shell.rs` BYTE-FOR-BYTE. A Rust
+ * edge-client and this TS client must produce identical bytes so they can
+ * talk to the same relay-server / browser endpoint interchangeably.
+ *
+ * Wire format (§2b of docs/SHELL_DESIGN.md):
+ *
+ *   ┌─────────────────────────────────┬──────────────┬─────────────────────┐
+ *   │ session_id (16 raw UUID bytes)  │ frame_type   │ payload             │
+ *   │ 0..15                           │ byte 16      │ 17.. (raw bytes)    │
+ *   └─────────────────────────────────┴──────────────┴─────────────────────┘
+ *
+ * Resize frames encode the payload as 4 big-endian bytes: [cols u16 BE][rows u16 BE].
+ *
+ * Frame types (mirror Rust `FrameType` enum EXACTLY — do not renumber):
+ *   Data         = 0   Raw PTY bytes (edge→browser stdout OR browser→edge keystrokes).
+ *   Resize       = 1   Browser→edge request to resize the PTY (payload = cols,rows u16 BE).
+ *   Close        = 2   Browser→edge request to close the session (no payload).
+ *   OpenControl  = 3   Relay→edge: spawn the PTY (payload = JSON {cols,rows,shell?}).
+ *   CloseControl = 4   Relay→edge: tear-down the PTY (no payload).
+ *   Sftp         = 6   SFTP frame (payload = UTF-8 JSON request OR raw SFTP bytes).
+ *   SftpRoot     = 7   Relay→edge: SFTP root directory announcement (payload = UTF-8 JSON).
+ *
+ * Frame types 5 is RESERVED (not used in either Rust or TS — must not collide
+ * with future wire assignments).
+ */
+import { randomUUID } from 'node:crypto';
+// ──────────────────────────── constants ────────────────────────────
+/** Header length: 16-byte session_id + 1-byte frame_type. */
+export const SHELL_HEADER_LEN = 17;
+/** 16-byte raw UUID length (matches Rust `Uuid::as_bytes()` length). */
+export const SESSION_ID_LEN = 16;
+/** Resize payload length: cols (u16 BE) + rows (u16 BE). */
+export const RESIZE_PAYLOAD_LEN = 4;
+/** Reserved frame type (must not be assigned). */
+const FRAME_TYPE_RESERVED = 5;
+// ──────────────────────────── frame type ───────────────────────────
+/** Wire-numeric frame type. Values are part of the public protocol — DO NOT renumber. */
+export const FrameType = {
+    Data: 0,
+    Resize: 1,
+    Close: 2,
+    OpenControl: 3,
+    CloseControl: 4,
+    // 5 is RESERVED — never assigned (see FRAME_TYPE_RESERVED above).
+    Sftp: 6,
+    SftpRoot: 7,
+};
+/**
+ * Inverse lookup: byte → typed name. Returns `null` for unknown / reserved.
+ * Mirrors Rust `FrameType::from_u8` exactly.
+ */
+export function frameTypeFromByte(b) {
+    switch (b) {
+        case FrameType.Data:
+            return FrameType.Data;
+        case FrameType.Resize:
+            return FrameType.Resize;
+        case FrameType.Close:
+            return FrameType.Close;
+        case FrameType.OpenControl:
+            return FrameType.OpenControl;
+        case FrameType.CloseControl:
+            return FrameType.CloseControl;
+        case FrameType.Sftp:
+            return FrameType.Sftp;
+        case FrameType.SftpRoot:
+            return FrameType.SftpRoot;
+        default:
+            // 5 and any other value (incl. reserved 5) → unknown.
+            return null;
+    }
+}
+// ──────────────────────────── session id ───────────────────────────
+/** Generate a fresh 16-byte session id (UUID v4 raw bytes). */
+export function newSessionId() {
+    // crypto.randomUUID() is RFC 4122 v4 — exactly the same shape as Rust Uuid::new_v4().
+    const u = randomUUID();
+    // Strip dashes → 32 hex chars → 16 raw bytes.
+    const hex = u.replace(/-/g, '');
+    return Buffer.from(hex, 'hex');
+}
+/**
+ * Convert a UUID string ("550e8400-e29b-41d4-a716-446655440000" or
+ * already-stripped 32-hex form) to the 16-byte session id used on the wire.
+ * Returns null on invalid input. Mirrors Rust `Uuid::parse_str` then `as_bytes`.
+ */
+export function sessionIdFromString(id) {
+    if (typeof id !== 'string' || id.length === 0)
+        return null;
+    const stripped = id.includes('-') ? id.replace(/-/g, '') : id;
+    if (!/^[0-9a-fA-F]{32}$/.test(stripped))
+        return null;
+    try {
+        return Buffer.from(stripped, 'hex');
+    }
+    catch {
+        return null;
+    }
+}
+/** Convert a 16-byte session id back to canonical UUID string (with dashes). */
+export function sessionIdToString(bytes) {
+    if (bytes.length !== SESSION_ID_LEN)
+        return null;
+    const hex = Buffer.from(bytes).toString('hex');
+    // 8-4-4-4-12 layout
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+/**
+ * Build a `data` frame carrying raw PTY bytes (or browser keystrokes, the
+ * wire is symmetric). Mirrors Rust `ShellFrame::data`.
+ */
+export function dataFrame(sessionId, payload) {
+    assertSessionId(sessionId);
+    return { sessionId, frameType: FrameType.Data, payload };
+}
+/**
+ * Build a `resize` frame. Payload is 4 big-endian bytes: cols u16 BE + rows u16 BE.
+ * Mirrors Rust `ShellFrame::resize`.
+ */
+export function resizeFrame(sessionId, cols, rows) {
+    assertSessionId(sessionId);
+    assertU16(cols, 'cols');
+    assertU16(rows, 'rows');
+    const payload = new Uint8Array(RESIZE_PAYLOAD_LEN);
+    // DataView writes big-endian explicitly (matches Rust u16::to_be_bytes).
+    new DataView(payload.buffer).setUint16(0, cols, false);
+    new DataView(payload.buffer).setUint16(2, rows, false);
+    return { sessionId, frameType: FrameType.Resize, payload };
+}
+/**
+ * Build a `close` frame (no payload). Mirrors Rust `ShellFrame::close`.
+ */
+export function closeFrame(sessionId) {
+    assertSessionId(sessionId);
+    return { sessionId, frameType: FrameType.Close, payload: new Uint8Array(0) };
+}
+// ──────────────────────────── encode / decode ──────────────────────
+/**
+ * Encode a frame to its on-wire byte representation. Matches the Rust
+ * `ShellFrame::encode` exactly: `[16 session_id][1 frame_type][payload...]`.
+ */
+export function encodeFrame(frame) {
+    assertSessionId(frame.sessionId);
+    const buf = Buffer.allocUnsafe(SHELL_HEADER_LEN + frame.payload.length);
+    buf.set(frame.sessionId, 0);
+    buf[16] = frame.frameType;
+    buf.set(frame.payload, SHELL_HEADER_LEN);
+    return buf;
+}
+/**
+ * Decode the on-wire bytes into a frame. Returns null if the buffer is
+ * shorter than `SHELL_HEADER_LEN` (17 bytes) or the frame-type byte is
+ * unknown / reserved. Mirrors Rust `ShellFrame::decode`.
+ *
+ * The payload is COPIED (not aliased) so callers can safely reuse the input
+ * buffer for the next frame — mirrors the Rust comment about copying into
+ * the reader task buffer.
+ */
+export function decodeFrame(bytes) {
+    if (bytes.length < SHELL_HEADER_LEN)
+        return null;
+    const ft = frameTypeFromByte(bytes[16]);
+    if (ft === null)
+        return null;
+    const sessionId = new Uint8Array(SESSION_ID_LEN);
+    sessionId.set(bytes.subarray(0, SESSION_ID_LEN), 0);
+    const payload = new Uint8Array(bytes.length - SHELL_HEADER_LEN);
+    payload.set(bytes.subarray(SHELL_HEADER_LEN), 0);
+    return { sessionId, frameType: ft, payload };
+}
+// ──────────────────────────── resize helpers ──────────────────────
+/**
+ * Decode a resize frame's payload into [cols, rows]. Returns null if the
+ * payload is not exactly 4 bytes (defensive — encoder always emits 4 bytes
+ * but a malformed peer might send something else).
+ */
+export function decodeResizePayload(payload) {
+    if (payload.length !== RESIZE_PAYLOAD_LEN)
+        return null;
+    const dv = new DataView(payload.buffer, payload.byteOffset, payload.byteLength);
+    // false = big-endian (matches Rust u16::from_be_bytes).
+    return { cols: dv.getUint16(0, false), rows: dv.getUint16(2, false) };
+}
+// ──────────────────────────── guards (internal) ────────────────────
+function assertSessionId(id) {
+    if (!(id instanceof Uint8Array) || id.length !== SESSION_ID_LEN) {
+        throw new RangeError(`sessionId must be a ${SESSION_ID_LEN}-byte Uint8Array (got ${id?.length ?? 'undefined'})`);
+    }
+}
+function assertU16(v, name) {
+    if (!Number.isInteger(v) || v < 0 || v > 0xffff) {
+        throw new RangeError(`${name} must be an integer in [0, 65535] (got ${v})`);
+    }
+}
+// Re-export the reserved sentinel so tests can assert it's not assignable.
+export const __RESERVED_FRAME_TYPE_5__ = FRAME_TYPE_RESERVED;