@livedesk/hub 0.1.55 → 0.1.57

package/src/console-direct.test.mjs

@@ -0,0 +1,984 @@
+import assert from 'node:assert/strict';
+import { EventEmitter } from 'node:events';
+import { readFileSync } from 'node:fs';
+import test from 'node:test';
+import nodeDataChannel from 'node-datachannel';
+import {
+  createDirectConsoleWireAssembler,
+  encodeDirectConsoleWireMessage
+} from '../../runtime-core/src/console-direct-wire.js';
+import { consoleDirectContract, createHubConsoleDirect } from './console-direct.js';
+
+assert.equal(consoleDirectContract.maxDefaultRetryDelayMs, 20_000);
+assert.equal(consoleDirectContract.peerDisconnectedTimeoutMs, 5_000);
+assert.equal(consoleDirectContract.maxPendingMediaWireMessages, 8);
+assert.equal(consoleDirectContract.reliableAssemblyTimeoutMs, 15_000);
+
+const HUB_EPOCH = '11111111-1111-4111-8111-111111111111';
+const HUB_EPOCH_TWO = '77777777-7777-4777-8777-777777777777';
+const CONSOLE_ID = '22222222-2222-4222-8222-222222222222';
+const CONNECTION_ONE = '33333333-3333-4333-8333-333333333333';
+const CONNECTION_TWO = '44444444-4444-4444-8444-444444444444';
+const CHANNEL_ID = '55555555-5555-4555-8555-555555555555';
+const REQUEST_ID = '66666666-6666-4666-8666-666666666666';
+
+class FakeSocket extends EventEmitter {
+  static CONNECTING = 0;
+  static OPEN = 1;
+  static CLOSING = 2;
+  static CLOSED = 3;
+  static instances = [];
+
+  constructor(url, options = {}) {
+    super();
+    this.url = String(url);
+    this.options = options;
+    this.readyState = FakeSocket.CONNECTING;
+    this.bufferedAmount = 0;
+    this.sent = [];
+    this.closeCode = 0;
+    this.closeReason = '';
+    this.constructor.instances.push(this);
+  }
+
+  open() {
+    this.readyState = FakeSocket.OPEN;
+    this.emit('open');
+  }
+
+  send(value) {
+    if (this.readyState !== FakeSocket.OPEN) throw new Error('fake-socket-not-open');
+    this.sent.push(Buffer.isBuffer(value) ? Buffer.from(value) : value);
+  }
+
+  receive(value, binary = Buffer.isBuffer(value)) {
+    this.emit('message', value, binary);
+  }
+
+  close(code = 1000, reason = '') {
+    if (this.readyState === FakeSocket.CLOSED) return;
+    this.closeCode = code;
+    this.closeReason = String(reason);
+    this.readyState = FakeSocket.CLOSED;
+    this.emit('close', code, Buffer.from(this.closeReason));
+  }
+
+  terminate() {
+    this.close(1006, 'terminated');
+  }
+}
+
+class FakeSignalSocket extends FakeSocket {
+  static instances = [];
+}
+
+class FakeLocalSocket extends FakeSocket {
+  static instances = [];
+}
+
+class FakeDataChannel {
+  constructor(label) {
+    this.label = label;
+    this.opened = false;
+    this.closed = false;
+    this.buffered = 0;
+    this.sent = [];
+    this.callbacks = {};
+  }
+
+  getLabel() { return this.label; }
+  isOpen() { return this.opened && !this.closed; }
+  bufferedAmount() { return this.buffered; }
+  setBufferedAmountLowThreshold(value) { this.lowThreshold = value; }
+  onMessage(callback) { this.callbacks.message = callback; }
+  onClosed(callback) { this.callbacks.closed = callback; }
+  onError(callback) { this.callbacks.error = callback; }
+  onOpen(callback) { this.callbacks.open = callback; }
+
+  open() {
+    this.opened = true;
+    this.callbacks.open?.();
+  }
+
+  receive(value) {
+    this.callbacks.message?.(value);
+  }
+
+  sendMessageBinary(value) {
+    if (!this.isOpen()) return false;
+    this.sent.push(new Uint8Array(value));
+    return true;
+  }
+
+  close() {
+    if (this.closed) return;
+    this.closed = true;
+    this.callbacks.closed?.();
+  }
+}
+
+class FakePeerConnection {
+  static instances = [];
+
+  constructor(name, config) {
+    this.name = name;
+    this.config = config;
+    this.callbacks = {};
+    this.closed = false;
+    this.local = null;
+    this.remote = null;
+    this.remoteCandidates = [];
+    this.selectedPair = null;
+    FakePeerConnection.instances.push(this);
+  }
+
+  onLocalDescription(callback) { this.callbacks.localDescription = callback; }
+  onLocalCandidate(callback) { this.callbacks.localCandidate = callback; }
+  onDataChannel(callback) { this.callbacks.dataChannel = callback; }
+  onStateChange(callback) { this.callbacks.state = callback; }
+  onIceStateChange(callback) { this.callbacks.iceState = callback; }
+
+  setRemoteDescription(sdp, type) {
+    this.remote = { sdp, type };
+    if (type === 'offer') {
+      this.local = { type: 'answer', sdp: `v=0\r\na=fake-${this.name}\r\n` };
+      this.callbacks.localDescription?.(this.local.sdp, this.local.type);
+    }
+  }
+
+  setLocalDescription(type) {
+    this.local = { type, sdp: `v=0\r\na=fake-${this.name}\r\n` };
+    this.callbacks.localDescription?.(this.local.sdp, type);
+  }
+
+  localDescription() { return this.local; }
+  addRemoteCandidate(candidate, sdpMid) { this.remoteCandidates.push({ candidate, sdpMid }); }
+  getSelectedCandidatePair() { return this.selectedPair; }
+
+  emitDataChannel(channel) { this.callbacks.dataChannel?.(channel); }
+  emitLocalCandidate(candidate, sdpMid = '0') { this.callbacks.localCandidate?.(candidate, sdpMid); }
+  emitState(state) { this.callbacks.state?.(state); }
+
+  close() { this.closed = true; }
+}
+
+function resetFakes() {
+  FakeSignalSocket.instances.length = 0;
+  FakeLocalSocket.instances.length = 0;
+  FakePeerConnection.instances.length = 0;
+}
+
+async function settle() {
+  await new Promise(resolve => setImmediate(resolve));
+}
+
+async function waitFor(predicate, timeoutMs = 250) {
+  const deadline = Date.now() + timeoutMs;
+  while (!predicate()) {
+    if (Date.now() >= deadline) throw new Error('test-condition-timeout');
+    await new Promise(resolve => setTimeout(resolve, 2));
+  }
+}
+
+function signalingMessages(socket) {
+  return socket.sent
+    .filter(value => typeof value === 'string')
+    .map(value => JSON.parse(value));
+}
+
+function decodeWireMessages(chunks, maxMessageBytes = 12 * 1024 * 1024) {
+  const assembler = createDirectConsoleWireAssembler({ maxMessageBytes });
+  const messages = [];
+  for (const chunk of chunks) {
+    const message = assembler.push(chunk);
+    if (message) messages.push(message);
+  }
+  assembler.dispose();
+  return messages;
+}
+
+function sendWire(channel, payload, { messageId = 1, kind = 'control', maxMessageBytes = 12 * 1024 * 1024 } = {}) {
+  const value = kind === 'binary' ? payload : typeof payload === 'string' ? payload : JSON.stringify(payload);
+  for (const chunk of encodeDirectConsoleWireMessage(value, { messageId, kind, maxMessageBytes })) {
+    channel.receive(chunk);
+  }
+}
+
+async function connectedDirect(options = {}) {
+  resetFakes();
+  const direct = createHubConsoleDirect({
+    url: 'https://signal.example.test',
+    deviceId: 'hub-device',
+    hubInstanceId: options.hubInstanceId || HUB_EPOCH,
+    httpBaseUrl: 'http://127.0.0.1:5179',
+    stunUrls: options.stunUrls || ['stun:stun.example.test:3478'],
+    getAccessToken: async () => 'access-token',
+    SignalingWebSocketImpl: FakeSignalSocket,
+    LocalWebSocketImpl: FakeLocalSocket,
+    createPeerConnection: (name, config) => new FakePeerConnection(name, config),
+    retryDelaysMs: options.retryDelaysMs || [60_000],
+    ...(options.iceConnectTimeoutMs ? { iceConnectTimeoutMs: options.iceConnectTimeoutMs } : {}),
+    ...(options.peerDisconnectedTimeoutMs
+      ? { peerDisconnectedTimeoutMs: options.peerDisconnectedTimeoutMs }
+      : {}),
+    ...(options.mediaAssemblyTimeoutMs ? { mediaAssemblyTimeoutMs: options.mediaAssemblyTimeoutMs } : {}),
+    fetchImpl: options.fetchImpl || (async () => new Response('{}', {
+      status: 200,
+      headers: { 'Content-Type': 'application/json' }
+    }))
+  });
+  direct.start();
+  await settle();
+  const signal = FakeSignalSocket.instances[0];
+  assert.ok(signal);
+  assert.equal(new URL(signal.url).pathname, '/v2/rtc/hub');
+  assert.equal(new URL(signal.url).searchParams.get('deviceId'), 'hub-device');
+  assert.equal(new URL(signal.url).searchParams.get('hubInstanceId'), options.hubInstanceId || HUB_EPOCH);
+  signal.open();
+  signal.receive(JSON.stringify({
+    type: 'signal-ready',
+    role: 'hub',
+    deviceId: 'hub-device',
+    hubEpoch: HUB_EPOCH
+  }), false);
+  return { direct, signal };
+}
+
+function offer(signal, connectionId = CONNECTION_ONE, sdp = 'v=0\r\na=fake-offer\r\n') {
+  signal.receive(JSON.stringify({
+    type: 'rtc-offer',
+    consoleId: CONSOLE_ID,
+    connectionId,
+    hubEpoch: HUB_EPOCH,
+    description: { type: 'offer', sdp }
+  }), false);
+  return FakePeerConnection.instances.at(-1);
+}
+
+test('STUN-only peer answers and rejects stale owner callbacks after replacement', async () => {
+  const { direct, signal } = await connectedDirect();
+  const firstPeer = offer(signal, CONNECTION_ONE);
+  assert.deepEqual(firstPeer.config.iceServers, ['stun:stun.example.test:3478']);
+  assert.equal(firstPeer.config.iceTransportPolicy, 'all');
+  assert.equal(firstPeer.config.disableFingerprintVerification, false);
+  assert.equal(signalingMessages(signal).some(message => (
+    message.type === 'rtc-answer' && message.connectionId === CONNECTION_ONE
+  )), true);
+
+  const secondPeer = offer(signal, CONNECTION_TWO);
+  assert.equal(firstPeer.closed, true);
+  const messagesBeforeStaleCandidate = signal.sent.length;
+  firstPeer.emitLocalCandidate('candidate:1 1 udp 1 192.0.2.1 5000 typ host');
+  assert.equal(signal.sent.length, messagesBeforeStaleCandidate);
+  assert.equal(direct.inspect().peerConnections, 1);
+
+  const staleControl = new FakeDataChannel('livedesk-control-v1');
+  firstPeer.emitDataChannel(staleControl);
+  assert.equal(staleControl.closed, true);
+  assert.equal(secondPeer.closed, false);
+  direct.close();
+});
+
+test('a signaling reconnect preserves a healthy direct peer until the Hub epoch actually changes', async () => {
+  const { direct, signal } = await connectedDirect({ retryDelaysMs: [0] });
+  const peer = offer(signal);
+  const control = new FakeDataChannel('livedesk-control-v1');
+  peer.emitDataChannel(control);
+  control.open();
+  signal.close(1012, 'transient-signal-loss');
+  assert.equal(peer.closed, false);
+  assert.equal(direct.inspect().peerConnections, 1);
+  assert.equal(direct.inspect().hubEpoch, HUB_EPOCH);
+
+  await new Promise(resolve => setTimeout(resolve, 10));
+  await settle();
+  const replacementSignal = FakeSignalSocket.instances.at(-1);
+  assert.notEqual(replacementSignal, signal);
+  assert.equal(
+    new URL(replacementSignal.url).searchParams.get('hubInstanceId'),
+    new URL(signal.url).searchParams.get('hubInstanceId')
+  );
+  replacementSignal.open();
+  replacementSignal.receive(JSON.stringify({
+    type: 'signal-ready',
+    role: 'hub',
+    deviceId: 'hub-device',
+    hubEpoch: HUB_EPOCH
+  }), false);
+  assert.equal(peer.closed, false);
+  assert.equal(direct.inspect().peerConnections, 1);
+
+  replacementSignal.receive(JSON.stringify({
+    type: 'signal-ready',
+    role: 'hub',
+    deviceId: 'hub-device',
+    hubEpoch: HUB_EPOCH_TWO
+  }), false);
+  assert.equal(peer.closed, true);
+  assert.equal(direct.inspect().peerConnections, 0);
+  direct.close();
+});
+
+test('a same-account token refresh reconnects signaling without dropping a healthy direct peer', async () => {
+  const { direct, signal } = await connectedDirect();
+  const peer = offer(signal);
+  const control = new FakeDataChannel('livedesk-control-v1');
+  peer.emitDataChannel(control);
+  control.open();
+  direct.refresh();
+  assert.equal(peer.closed, false);
+  assert.equal(direct.inspect().hubEpoch, HUB_EPOCH);
+  await settle();
+  const replacementSignal = FakeSignalSocket.instances.at(-1);
+  assert.notEqual(replacementSignal, signal);
+  assert.equal(
+    new URL(replacementSignal.url).searchParams.get('hubInstanceId'),
+    new URL(signal.url).searchParams.get('hubInstanceId')
+  );
+  replacementSignal.open();
+  replacementSignal.receive(JSON.stringify({
+    type: 'signal-ready',
+    role: 'hub',
+    deviceId: 'hub-device',
+    hubEpoch: HUB_EPOCH
+  }), false);
+  assert.equal(peer.closed, false);
+  assert.equal(direct.inspect().peerConnections, 1);
+  direct.close();
+});
+
+test('close revokes every direct owner and refresh can start signaling again after logout', async () => {
+  const { direct, signal } = await connectedDirect();
+  const peer = offer(signal);
+  const control = new FakeDataChannel('livedesk-control-v1');
+  peer.emitDataChannel(control);
+  control.open();
+  direct.close();
+  assert.equal(peer.closed, true);
+  assert.equal(direct.inspect().peerConnections, 0);
+  assert.equal(direct.inspect().resourceTimers, 0);
+  direct.refresh();
+  await settle();
+  const restartedSignal = FakeSignalSocket.instances.at(-1);
+  assert.notEqual(restartedSignal, signal);
+  assert.equal(
+    new URL(restartedSignal.url).searchParams.get('hubInstanceId'),
+    new URL(signal.url).searchParams.get('hubInstanceId')
+  );
+  direct.close();
+});
+
+test('a signaling loss retires only a peer that has not opened its control channel', async () => {
+  const { direct, signal } = await connectedDirect();
+  const peer = offer(signal);
+  signal.close(1012, 'signal-lost-during-negotiation');
+  assert.equal(peer.closed, true);
+  assert.equal(direct.inspect().peerConnections, 0);
+  assert.equal(direct.inspect().hubEpoch, HUB_EPOCH);
+  direct.close();
+});
+
+test('an access-token owner has one bounded deadline and late stale completion cannot reconnect', async () => {
+  resetFakes();
+  const tokenResolvers = [];
+  let tokenCalls = 0;
+  const direct = createHubConsoleDirect({
+    url: 'https://signal.example.test',
+    deviceId: 'hub-device',
+    hubInstanceId: HUB_EPOCH,
+    httpBaseUrl: 'http://127.0.0.1:5179',
+    getAccessToken: () => {
+      tokenCalls += 1;
+      return new Promise(resolve => tokenResolvers.push(resolve));
+    },
+    accessTokenTimeoutMs: 5,
+    retryDelaysMs: [1],
+    SignalingWebSocketImpl: FakeSignalSocket,
+    LocalWebSocketImpl: FakeLocalSocket,
+    createPeerConnection: (name, config) => new FakePeerConnection(name, config)
+  });
+  direct.start();
+  await waitFor(() => tokenCalls >= 2);
+  assert.equal(FakeSignalSocket.instances.length, 0);
+  assert.equal(direct.inspect().lastError, 'console-direct-access-token-timeout');
+  assert.ok(direct.inspect().resourceTimers <= 1);
+  direct.close();
+  for (const resolve of tokenResolvers) resolve('late-access-token');
+  await settle();
+  assert.equal(FakeSignalSocket.instances.length, 0);
+  assert.equal(direct.inspect().accessTokenDeadlineActive, false);
+  assert.equal(direct.inspect().signalReadyDeadlineActive, false);
+  assert.equal(direct.inspect().resourceTimers, 0);
+});
+
+test('one exact WebSocket deadline bounds both handshake and signal-ready before a healthy retry', async () => {
+  resetFakes();
+  const direct = createHubConsoleDirect({
+    url: 'https://signal.example.test',
+    deviceId: 'hub-device',
+    hubInstanceId: HUB_EPOCH,
+    httpBaseUrl: 'http://127.0.0.1:5179',
+    getAccessToken: async () => 'access-token',
+    accessTokenTimeoutMs: 20,
+    signalReadyTimeoutMs: 15,
+    retryDelaysMs: [0],
+    SignalingWebSocketImpl: FakeSignalSocket,
+    LocalWebSocketImpl: FakeLocalSocket,
+    createPeerConnection: (name, config) => new FakePeerConnection(name, config)
+  });
+  direct.start();
+  await waitFor(() => FakeSignalSocket.instances.length === 1);
+  const connectingSocket = FakeSignalSocket.instances[0];
+  assert.equal(direct.inspect().state, 'connecting');
+  assert.equal(direct.inspect().signalReadyDeadlineActive, true);
+
+  await waitFor(() => FakeSignalSocket.instances.length === 2);
+  assert.equal(connectingSocket.readyState, FakeSignalSocket.CLOSED);
+  const authenticatingSocket = FakeSignalSocket.instances[1];
+  authenticatingSocket.open();
+  assert.equal(direct.inspect().state, 'authenticating');
+
+  await waitFor(() => FakeSignalSocket.instances.length === 3);
+  assert.equal(authenticatingSocket.readyState, FakeSignalSocket.CLOSED);
+  const healthySocket = FakeSignalSocket.instances[2];
+  healthySocket.open();
+  healthySocket.receive(JSON.stringify({
+    type: 'signal-ready',
+    role: 'hub',
+    deviceId: 'hub-device',
+    hubEpoch: HUB_EPOCH
+  }), false);
+  assert.equal(direct.inspect().state, 'connected');
+  assert.equal(direct.inspect().signalReadyDeadlineActive, false);
+  await new Promise(resolve => setTimeout(resolve, 25));
+  assert.equal(FakeSignalSocket.instances.length, 3);
+  direct.close();
+  assert.equal(direct.inspect().resourceTimers, 0);
+});
+
+test('reliable control channel bridges bounded HTTP over fragmented wire messages', async () => {
+  let fetchCalls = 0;
+  const { direct, signal } = await connectedDirect({
+    fetchImpl: async (url, init) => {
+      fetchCalls += 1;
+      assert.equal(url, 'http://127.0.0.1:5179/api/update/apply');
+      assert.equal(init.method, 'POST');
+      assert.equal(init.headers['content-type'], 'application/json');
+      assert.equal(init.headers['x-livedesk-csrf'], 'csrf-proof');
+      assert.equal(Buffer.from(init.body).toString('utf8'), '{"apply":true}');
+      return new Response('{"ok":true}', {
+        status: 200,
+        statusText: 'OK',
+        headers: { 'Content-Type': 'application/json' }
+      });
+    }
+  });
+  const peer = offer(signal);
+  const control = new FakeDataChannel('livedesk-control-v1');
+  peer.emitDataChannel(control);
+  control.open();
+  let messages = decodeWireMessages(control.sent);
+  assert.deepEqual(JSON.parse(messages[0].data), {
+    type: 'direct-ready',
+    connectionId: CONNECTION_ONE,
+    hubEpoch: HUB_EPOCH
+  });
+
+  sendWire(control, {
+    type: 'http-request',
+    requestId: REQUEST_ID,
+    method: 'POST',
+    path: '/api/update/apply',
+    headers: {
+      accept: 'application/json',
+      'content-type': 'application/json',
+      'x-livedesk-csrf': 'csrf-proof'
+    },
+    bodyBase64: Buffer.from('{"apply":true}').toString('base64')
+  });
+  await settle();
+  messages = decodeWireMessages(control.sent);
+  const response = messages.map(message => JSON.parse(message.data))
+    .find(message => message.type === 'http-response');
+  assert.equal(fetchCalls, 1);
+  assert.equal(response.requestId, REQUEST_ID);
+  assert.equal(response.status, 200);
+  assert.equal(Buffer.from(response.bodyBase64, 'base64').toString('utf8'), '{"ok":true}');
+  assert.equal(direct.inspect().pendingHttpRequests, 0);
+  direct.close();
+});
+
+test('canonical HTTP routing rejects encoded, backslash, duplicate-slash, and external-origin bypasses', async () => {
+  const fetchedUrls = [];
+  const { direct, signal } = await connectedDirect({
+    fetchImpl: async url => {
+      fetchedUrls.push(String(url));
+      return new Response('{"ok":true}', {
+        status: 200,
+        headers: { 'Content-Type': 'application/json' }
+      });
+    }
+  });
+  const peer = offer(signal);
+  const control = new FakeDataChannel('livedesk-control-v1');
+  peer.emitDataChannel(control);
+  control.open();
+
+  const bypasses = [
+    ['/api/settings/%2e%2e/remote/registry-credentials', 'aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaa1'],
+    ['/api/settings/%252e%252e/remote/registry-credentials', 'aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaa2'],
+    ['/api/settings\\..\\remote\\registry-credentials', 'aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaa3'],
+    ['/api/settings//profile', 'aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaa4'],
+    ['//attacker.example.test/api/settings/profile', 'aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaa5'],
+    ['https://attacker.example.test/api/settings/profile', 'aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaa6'],
+    ['/api/settings/%2f..%2fremote/registry-credentials', 'aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaa7']
+  ];
+  for (const [path, requestId] of bypasses) {
+    sendWire(control, {
+      type: 'http-request',
+      requestId,
+      method: 'GET',
+      path
+    }, { messageId: Number(requestId.at(-1)) + 10 });
+  }
+  await settle();
+  assert.deepEqual(fetchedUrls, []);
+  const rejected = decodeWireMessages(control.sent)
+    .map(message => JSON.parse(message.data))
+    .filter(message => bypasses.some(([, requestId]) => requestId === message.requestId));
+  assert.equal(rejected.length, bypasses.length);
+  assert.ok(rejected.every(message => message.error === 'console-route-not-allowed'));
+
+  sendWire(control, {
+    type: 'http-request',
+    requestId: 'aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaa8',
+    method: 'GET',
+    path: '/api/settings/profile?section=general%20settings'
+  }, { messageId: 18 });
+  await settle();
+  assert.deepEqual(fetchedUrls, [
+    'http://127.0.0.1:5179/api/settings/profile?section=general%20settings'
+  ]);
+  direct.close();
+});
+
+test('reliable lifecycle control survives logical lane registration reordering and the lane carries payload only', async () => {
+  const { direct, signal } = await connectedDirect();
+  const peer = offer(signal);
+  const control = new FakeDataChannel('livedesk-control-v1');
+  peer.emitDataChannel(control);
+  control.open();
+
+  // Model external SCTP scheduling: reliable ws-open arrives before the
+  // separately negotiated logical lane is surfaced to the Hub callback.
+  sendWire(control, {
+    type: 'ws-open',
+    connectionId: CONNECTION_ONE,
+    hubEpoch: HUB_EPOCH,
+    channelId: CHANNEL_ID,
+    purpose: 'frame',
+    path: '/api/remote/frames/ws?devices=device-a'
+  });
+  assert.equal(FakeLocalSocket.instances.length, 0);
+  assert.equal(direct.inspect().pendingLogicalControlRequests, 1);
+
+  const lane = new FakeDataChannel(`livedesk-ws-v1:${CHANNEL_ID}:frame`);
+  peer.emitDataChannel(lane);
+  lane.open();
+  const local = FakeLocalSocket.instances[0];
+  assert.ok(local);
+  assert.equal(new URL(local.url).pathname, '/api/remote/frames/ws');
+  assert.equal(direct.inspect().pendingLogicalControlRequests, 0);
+  local.open();
+
+  const controlMessages = decodeWireMessages(control.sent)
+    .filter(message => message.kind === 'control')
+    .map(message => JSON.parse(message.data));
+  assert.deepEqual(controlMessages.find(message => message.type === 'ws-opened'), {
+    type: 'ws-opened',
+    channelId: CHANNEL_ID,
+    connectionId: CONNECTION_ONE,
+    hubEpoch: HUB_EPOCH
+  });
+  assert.equal(lane.sent.length, 0);
+
+  local.receive(Buffer.from([1, 2, 3, 4]), true);
+  const laneMessages = decodeWireMessages(lane.sent);
+  const binary = laneMessages.find(message => message.kind === 'binary');
+  assert.deepEqual([...binary.data], [1, 2, 3, 4]);
+  assert.equal(laneMessages.some(message => message.kind === 'control'), false);
+
+  sendWire(lane, 'browser-text-message', { messageId: 2, kind: 'text' });
+  sendWire(lane, new Uint8Array([5, 6, 7]), { messageId: 3, kind: 'binary' });
+  assert.equal(local.sent[0], 'browser-text-message');
+  assert.deepEqual([...local.sent[1]], [5, 6, 7]);
+  assert.equal(direct.inspect().logicalWebSocketChannels, 1);
+
+  sendWire(control, {
+    type: 'ws-close',
+    connectionId: CONNECTION_ONE,
+    hubEpoch: HUB_EPOCH,
+    channelId: CHANNEL_ID,
+    code: 1000,
+    reason: 'test-complete'
+  }, { messageId: 4 });
+  assert.equal(lane.closed, true);
+  assert.equal(local.readyState, FakeLocalSocket.CLOSED);
+  assert.equal(direct.inspect().logicalWebSocketChannels, 0);
+  direct.close();
+});
+
+test('logical lifecycle cannot bind a different channel id or stale connection owner', async () => {
+  {
+    const { direct, signal } = await connectedDirect();
+    const peer = offer(signal);
+    const control = new FakeDataChannel('livedesk-control-v1');
+    peer.emitDataChannel(control);
+    control.open();
+    const lane = new FakeDataChannel(`livedesk-ws-v1:${CHANNEL_ID}:input`);
+    peer.emitDataChannel(lane);
+    lane.open();
+    sendWire(control, {
+      type: 'ws-open',
+      connectionId: CONNECTION_ONE,
+      hubEpoch: HUB_EPOCH,
+      channelId: REQUEST_ID,
+      purpose: 'input',
+      path: '/api/remote/input/ws'
+    });
+    assert.equal(FakeLocalSocket.instances.length, 0);
+    assert.equal(direct.inspect().pendingLogicalControlRequests, 1);
+    assert.equal(lane.closed, false);
+    direct.close();
+    assert.equal(direct.inspect().resourceTimers, 0);
+  }
+
+  {
+    const { direct, signal } = await connectedDirect();
+    const peer = offer(signal);
+    const control = new FakeDataChannel('livedesk-control-v1');
+    peer.emitDataChannel(control);
+    control.open();
+    const lane = new FakeDataChannel(`livedesk-ws-v1:${CHANNEL_ID}:input`);
+    peer.emitDataChannel(lane);
+    lane.open();
+    sendWire(control, {
+      type: 'ws-open',
+      connectionId: CONNECTION_TWO,
+      hubEpoch: HUB_EPOCH,
+      channelId: CHANNEL_ID,
+      purpose: 'input',
+      path: '/api/remote/input/ws'
+    });
+    assert.equal(peer.closed, true);
+    assert.equal(direct.inspect().peerConnections, 0);
+    assert.equal(FakeLocalSocket.instances.length, 0);
+    direct.close();
+  }
+});
+
+test('relay ICE candidate fails closed and exact owner returns to terminal zero', async () => {
+  const { direct, signal } = await connectedDirect();
+  const peer = offer(signal);
+  signal.receive(JSON.stringify({
+    type: 'rtc-ice',
+    consoleId: CONSOLE_ID,
+    connectionId: CONNECTION_ONE,
+    hubEpoch: HUB_EPOCH,
+    candidate: 'candidate:1 1 udp 1 203.0.113.10 5000 typ relay raddr 0.0.0.0 rport 0',
+    sdpMid: '0'
+  }), false);
+  assert.equal(peer.closed, true);
+  assert.equal(direct.inspect().peerConnections, 0);
+  assert.equal(direct.inspect().rejectedRelayCandidates, 1);
+  assert.equal(signalingMessages(signal).some(message => (
+    message.type === 'rtc-close'
+      && message.connectionId === CONNECTION_ONE
+      && message.reason === 'console-direct-relay-candidate-rejected'
+  )), true);
+  direct.close();
+  assert.deepEqual({
+    peers: direct.inspect().peerConnections,
+    channels: direct.inspect().logicalWebSocketChannels,
+    requests: direct.inspect().pendingHttpRequests,
+    retained: direct.inspect().retainedAssemblyBytes
+  }, { peers: 0, channels: 0, requests: 0, retained: 0 });
+});
+
+test('a relay candidate embedded in the offer SDP is rejected before peer allocation', async () => {
+  const { direct, signal } = await connectedDirect();
+  offer(signal, CONNECTION_ONE, 'v=0\r\na=candidate:1 1 udp 1 203.0.113.10 5000 typ relay\r\n');
+  assert.equal(direct.inspect().peerConnections, 0);
+  assert.equal(direct.inspect().rejectedRelayCandidates, 1);
+  assert.equal(signalingMessages(signal).some(message => (
+    message.type === 'rtc-close'
+      && message.connectionId === CONNECTION_ONE
+      && message.reason === 'console-direct-relay-candidate-rejected'
+  )), true);
+  direct.close();
+});
+
+test('the peer-wide DataChannel buffer cap closes only the overflowing logical lane', async () => {
+  const { direct, signal } = await connectedDirect();
+  const peer = offer(signal);
+  const control = new FakeDataChannel('livedesk-control-v1');
+  peer.emitDataChannel(control);
+  control.open();
+  const lane = new FakeDataChannel(`livedesk-ws-v1:${CHANNEL_ID}:frame`);
+  peer.emitDataChannel(lane);
+  lane.open();
+  sendWire(control, {
+    type: 'ws-open',
+    connectionId: CONNECTION_ONE,
+    hubEpoch: HUB_EPOCH,
+    channelId: CHANNEL_ID,
+    purpose: 'frame',
+    path: '/api/remote/frames/ws'
+  });
+  const local = FakeLocalSocket.instances[0];
+  local.open();
+  control.buffered = consoleDirectContract.maxBufferedBytes / 2;
+  lane.buffered = consoleDirectContract.maxBufferedBytes / 2;
+  local.receive('latest-frame');
+  assert.equal(lane.sent.length, 0);
+  assert.equal(lane.closed, true);
+  assert.equal(control.closed, false);
+  assert.equal(peer.closed, false);
+  assert.equal(direct.inspect().dataChannelBackpressureCloses, 1);
+  direct.close();
+});
+
+test('a reliable control response drops stale media backlog without retiring the peer', async () => {
+  const { direct, signal } = await connectedDirect({
+    fetchImpl: async () => new Response('{"online":true}', {
+      status: 200,
+      headers: { 'Content-Type': 'application/json' }
+    })
+  });
+  const peer = offer(signal);
+  const control = new FakeDataChannel('livedesk-control-v1');
+  peer.emitDataChannel(control);
+  control.open();
+  const lane = new FakeDataChannel(`livedesk-ws-v1:${CHANNEL_ID}:frame`);
+  peer.emitDataChannel(lane);
+  lane.open();
+  sendWire(control, {
+    type: 'ws-open',
+    connectionId: CONNECTION_ONE,
+    hubEpoch: HUB_EPOCH,
+    channelId: CHANNEL_ID,
+    purpose: 'frame',
+    path: '/api/remote/frames/ws'
+  });
+  FakeLocalSocket.instances[0].open();
+  lane.buffered = consoleDirectContract.maxBufferedBytes;
+
+  sendWire(control, {
+    type: 'http-request',
+    requestId: REQUEST_ID,
+    method: 'GET',
+    path: '/api/remote/status'
+  }, { messageId: 11 });
+  await settle();
+
+  const response = decodeWireMessages(control.sent)
+    .map(message => JSON.parse(message.data))
+    .find(message => message.type === 'http-response' && message.requestId === REQUEST_ID);
+  assert.equal(response.status, 200);
+  assert.equal(Buffer.from(response.bodyBase64, 'base64').toString('utf8'), '{"online":true}');
+  assert.equal(lane.closed, true);
+  assert.equal(control.closed, false);
+  assert.equal(peer.closed, false);
+  assert.equal(direct.inspect().peerConnections, 1);
+  assert.equal(direct.inspect().dataChannelBackpressureCloses, 1);
+  direct.close();
+});
+
+test('a transient disconnected state recovers or retires the exact peer on one bounded deadline', async () => {
+  const { direct, signal } = await connectedDirect({ peerDisconnectedTimeoutMs: 5 });
+  const peer = offer(signal);
+  const control = new FakeDataChannel('livedesk-control-v1');
+  peer.emitDataChannel(control);
+  control.open();
+
+  peer.emitState('disconnected');
+  assert.equal(direct.inspect().peerDisconnectTimers, 1);
+  peer.emitState('connected');
+  assert.equal(direct.inspect().peerDisconnectTimers, 0);
+  assert.equal(peer.closed, false);
+
+  peer.emitState('disconnected');
+  await new Promise(resolve => setTimeout(resolve, 15));
+  assert.equal(peer.closed, true);
+  assert.equal(direct.inspect().peerConnections, 0);
+  assert.equal(direct.inspect().peerDisconnectTimers, 0);
+  assert.equal(direct.inspect().resourceTimers, 0);
+  direct.close();
+});
+
+test('an oversized local frame closes only its logical media lane', async () => {
+  const { direct, signal } = await connectedDirect();
+  const peer = offer(signal);
+  const control = new FakeDataChannel('livedesk-control-v1');
+  peer.emitDataChannel(control);
+  control.open();
+  const lane = new FakeDataChannel(`livedesk-ws-v1:${CHANNEL_ID}:frame`);
+  peer.emitDataChannel(lane);
+  lane.open();
+  sendWire(control, {
+    type: 'ws-open',
+    connectionId: CONNECTION_ONE,
+    hubEpoch: HUB_EPOCH,
+    channelId: CHANNEL_ID,
+    purpose: 'frame',
+    path: '/api/remote/frames/ws'
+  });
+  const local = FakeLocalSocket.instances[0];
+  local.open();
+  local.receive(Buffer.alloc(consoleDirectContract.maxFrameMessageBytes + 1), true);
+  assert.equal(lane.closed, true);
+  assert.equal(control.closed, false);
+  assert.equal(peer.closed, false);
+  direct.close();
+});
+
+test('an unopened control channel cannot suppress the bounded ICE owner timeout', async () => {
+  const { direct, signal } = await connectedDirect({ iceConnectTimeoutMs: 5 });
+  const peer = offer(signal);
+  const control = new FakeDataChannel('livedesk-control-v1');
+  peer.emitDataChannel(control);
+  assert.equal(direct.inspect().iceConnectTimers, 1);
+  await new Promise(resolve => setTimeout(resolve, 15));
+  assert.equal(peer.closed, true);
+  assert.equal(direct.inspect().peerConnections, 0);
+  assert.equal(direct.inspect().resourceTimers, 0);
+  direct.close();
+});
+
+test('an incomplete partial-reliable media message owns one deadline and close returns terminal zero', async () => {
+  const { direct, signal } = await connectedDirect({ mediaAssemblyTimeoutMs: 5 });
+  const peer = offer(signal);
+  const control = new FakeDataChannel('livedesk-control-v1');
+  peer.emitDataChannel(control);
+  control.open();
+  const lane = new FakeDataChannel(`livedesk-ws-v1:${CHANNEL_ID}:frame`);
+  peer.emitDataChannel(lane);
+  lane.open();
+  const chunks = encodeDirectConsoleWireMessage(new Uint8Array(40 * 1024), {
+    messageId: 9,
+    kind: 'binary',
+    maxMessageBytes: 12 * 1024 * 1024
+  });
+  assert.ok(chunks.length > 1);
+  lane.receive(chunks[0]);
+  assert.equal(direct.inspect().assemblyDeadlineTimers, 1);
+  assert.ok(direct.inspect().retainedAssemblyBytes > 0);
+  await new Promise(resolve => setTimeout(resolve, 15));
+  assert.equal(lane.closed, true);
+  assert.equal(peer.closed, false);
+  assert.equal(direct.inspect().assemblyDeadlineTimers, 0);
+  assert.equal(direct.inspect().retainedAssemblyBytes, 0);
+  direct.close();
+  assert.deepEqual({
+    peers: direct.inspect().peerConnections,
+    channels: direct.inspect().logicalWebSocketChannels,
+    localSockets: direct.inspect().localWebSocketChannels,
+    retained: direct.inspect().retainedAssemblyBytes,
+    timers: direct.inspect().resourceTimers
+  }, { peers: 0, channels: 0, localSockets: 0, retained: 0, timers: 0 });
+});
+
+test('TURN and credential-like override values are filtered before peer configuration', async () => {
+  const { direct, signal } = await connectedDirect({
+    stunUrls: [
+      'turn:turn.example.test:3478',
+      'stun:user@example.test:3478',
+      'stun:approved.example.test:3478'
+    ]
+  });
+  const peer = offer(signal);
+  assert.deepEqual(peer.config.iceServers, ['stun:approved.example.test:3478']);
+  direct.close();
+});
+
+test('server session refresh preserves peers while logout uses the revoking close path', () => {
+  const source = readFileSync(new URL('./server.js', import.meta.url), 'utf8');
+  const sessionStart = source.indexOf("app.post('/api/auth/session'");
+  const logoutStart = source.indexOf("app.delete('/api/auth/session'");
+  const hubStatusStart = source.indexOf("app.get('/api/hub/status'", logoutStart);
+  assert.ok(sessionStart >= 0 && logoutStart > sessionStart && hubStatusStart > logoutStart);
+  const sessionBlock = source.slice(sessionStart, logoutStart);
+  const logoutBlock = source.slice(logoutStart, hubStatusStart);
+  assert.match(sessionBlock, /hubConsoleDirect\?\.refresh\(\)/);
+  assert.match(logoutBlock, /hubConsoleDirect\?\.close\(\)/);
+  assert.doesNotMatch(logoutBlock, /hubConsoleDirect\?\.refresh\(\)/);
+});
+
+test('native node-datachannel peers carry the fragmented control wire over loopback', { timeout: 8_000 }, async () => {
+  let offerer = null;
+  let answerer = null;
+  let offerChannel = null;
+  let answerChannel = null;
+  const assembler = createDirectConsoleWireAssembler();
+  let openTimer = null;
+  let messageTimer = null;
+  try {
+    offerer = new nodeDataChannel.PeerConnection('console-direct-native-offerer', { iceServers: [] });
+    answerer = new nodeDataChannel.PeerConnection('console-direct-native-answerer', { iceServers: [] });
+    offerer.onLocalDescription((sdp, type) => {
+      answerer.setRemoteDescription(sdp, type);
+    });
+    answerer.onLocalDescription((sdp, type) => offerer.setRemoteDescription(sdp, type));
+    offerer.onLocalCandidate((candidate, sdpMid) => {
+      if (candidate) answerer.addRemoteCandidate(candidate, sdpMid);
+    });
+    answerer.onLocalCandidate((candidate, sdpMid) => {
+      if (candidate) offerer.addRemoteCandidate(candidate, sdpMid);
+    });
+
+    let resolveOpened;
+    const opened = new Promise((resolve, reject) => {
+      resolveOpened = resolve;
+      openTimer = setTimeout(() => reject(new Error('native-datachannel-open-timeout')), 4_000);
+    });
+    let resolveReceived;
+    const received = new Promise((resolve, reject) => {
+      resolveReceived = resolve;
+      messageTimer = setTimeout(() => reject(new Error('native-datachannel-message-timeout')), 4_000);
+    });
+    answerer.onDataChannel(channel => {
+      answerChannel = channel;
+      channel.onOpen(resolveOpened);
+      channel.onMessage(raw => {
+        const message = assembler.push(raw);
+        if (message) resolveReceived(message);
+      });
+    });
+    offerChannel = offerer.createDataChannel('livedesk-control-v1');
+    await opened;
+    clearTimeout(openTimer);
+    openTimer = null;
+    const payload = JSON.stringify({ type: 'direct-ready', connectionId: CONNECTION_ONE, hubEpoch: HUB_EPOCH });
+    const chunks = encodeDirectConsoleWireMessage(payload.repeat(400), {
+      messageId: 77,
+      kind: 'control'
+    });
+    assert.ok(chunks.length > 1);
+    for (const chunk of chunks) assert.equal(offerChannel.sendMessageBinary(chunk), true);
+    const message = await received;
+    clearTimeout(messageTimer);
+    messageTimer = null;
+    assert.equal(message.kind, 'control');
+    assert.equal(message.data, payload.repeat(400));
+  } finally {
+    if (openTimer) clearTimeout(openTimer);
+    if (messageTimer) clearTimeout(messageTimer);
+    assembler.dispose();
+    try { offerChannel?.close(); } catch {}
+    try { answerChannel?.close(); } catch {}
+    try { offerer?.close(); } catch {}
+    try { answerer?.close(); } catch {}
+    await new Promise(resolve => setTimeout(resolve, 100));
+    nodeDataChannel.cleanup();
+  }
+});