@livedesk/hub 0.1.47 → 0.1.48

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livedesk/hub",
-  "version": "0.1.47",
+  "version": "0.1.48",
   "description": "LiveDesk local Hub API and browser frame bridge",
   "type": "module",
   "main": "src/server.js",
@@ -11,7 +11,7 @@
   "scripts": {
     "dev": "node src/server.js",
     "start": "node src/server.js",
-    "check": "node --check src/server.js && node --check src/remote-hub.js && node --check src/console-relay.js",
+    "check": "node --check src/server.js && node --check src/remote-hub.js && node --check src/remote-clipboard-contract.mjs && node --check src/console-relay.js",
     "prepublishOnly": "node ../../scripts/livedesk-release-git-gate.mjs"
   },
   "dependencies": {

package/src/filesystem/roots.js

@@ -98,8 +98,26 @@ async function mountedRoots() {
   return roots;
 }
 
-export async function discoverFilesystemRoots() {
-  const roots = process.platform === 'win32' ? await windowsRoots() : await mountedRoots();
+export async function discoverFilesystemRoots() {
+  const isolatedTestRoot = process.env.LIVEDESK_TEST_MODE === '1'
+    ? normalizeRootPath(process.env.LIVEDESK_TEST_FILESYSTEM_ROOT)
+    : '';
+  if (isolatedTestRoot) {
+    const rootStat = await fs.stat(isolatedTestRoot);
+    if (!rootStat.isDirectory()) {
+      throw new Error('LIVEDESK_TEST_FILESYSTEM_ROOT must be a directory.');
+    }
+    return [{
+      path: isolatedTestRoot,
+      name: 'Test drive',
+      displayPath: isolatedTestRoot,
+      type: 'drive',
+      driveType: 'fixed',
+      ...await statfsCapacity(isolatedTestRoot),
+      hasChildren: true
+    }];
+  }
+  const roots = process.platform === 'win32' ? await windowsRoots() : await mountedRoots();
   if (roots.length > 0) return roots;
   const fallback = process.platform === 'win32' ? `${process.env.SystemDrive || 'C:'}\\` : os.homedir();
   return [{

package/src/remote-clipboard-contract.mjs

@@ -0,0 +1,482 @@
+const MIB = 1024 * 1024;
+
+export const REMOTE_CLIPBOARD_PROTOCOL = 'livedesk.clipboard.v1';
+
+export const REMOTE_CLIPBOARD_LIMITS = Object.freeze({
+  maxTextBytes: 1 * MIB,
+  maxImageBytes: 24 * MIB,
+  maxTotalBytes: 256 * MIB,
+  maxFiles: 24,
+  // 384,000 raw bytes encode to 512,000 base64 characters, leaving bounded
+  // room for the command envelope below Relay's 512 KiB JSON-message limit.
+  maxChunkBytes: 384_000,
+  maxOperationsPerDevice: 2,
+  operationIdleTimeoutMs: 2 * 60 * 1000,
+  commandTimeoutMs: 15 * 1000
+});
+
+export const REMOTE_CLIPBOARD_INPUT_ACTIONS = Object.freeze(new Set([
+  'clipboard.prepare',
+  'clipboard.copy',
+  'clipboard.paste'
+]));
+
+export const REMOTE_CLIPBOARD_FILE_ACTIONS = Object.freeze(new Set([
+  'clipboard.copy.begin',
+  'clipboard.copy.chunk',
+  'clipboard.copy.end',
+  'clipboard.paste.begin',
+  'clipboard.paste.chunk',
+  'clipboard.paste.cancel',
+  'clipboard.operation.status'
+]));
+
+const ACTION_ALIASES = new Map([
+  ['prepare', 'clipboard.prepare'],
+  ['copy', 'clipboard.copy'],
+  ['paste', 'clipboard.paste'],
+  ['copy.begin', 'clipboard.copy.begin'],
+  ['copy.chunk', 'clipboard.copy.chunk'],
+  ['copy.end', 'clipboard.copy.end'],
+  ['paste.begin', 'clipboard.paste.begin'],
+  ['paste.chunk', 'clipboard.paste.chunk'],
+  ['paste.cancel', 'clipboard.paste.cancel'],
+  ['operation.status', 'clipboard.operation.status']
+]);
+
+const SAFE_STATUS_VALUES = new Set([
+  'preparing',
+  'copying',
+  'receiving',
+  'ready',
+  'completed',
+  'cancelled',
+  'cleaned',
+  'failed',
+  'expired',
+  'not-found',
+  'already-ended',
+  'complete',
+  'applied',
+  'pasted'
+]);
+
+export class RemoteClipboardContractError extends Error {
+  constructor(code, status = 400) {
+    super(code);
+    this.name = 'RemoteClipboardContractError';
+    this.code = code;
+    this.status = status;
+  }
+}
+
+function fail(code, status = 400) {
+  throw new RemoteClipboardContractError(code, status);
+}
+
+function boundedString(value, maxLength, code, { required = false } = {}) {
+  const text = String(value ?? '').trim();
+  if ((required && !text) || text.length > maxLength) {
+    fail(code);
+  }
+  return text;
+}
+
+function exactInteger(value, { min = 0, max = Number.MAX_SAFE_INTEGER, code }) {
+  const number = Number(value);
+  if (!Number.isSafeInteger(number) || number < min || number > max) {
+    fail(code);
+  }
+  return number;
+}
+
+function optionalInteger(value, options) {
+  if (value === undefined || value === null || value === '') {
+    return undefined;
+  }
+  return exactInteger(value, options);
+}
+
+function normalizeContentKind(value) {
+  const kind = String(value || '').trim().toLowerCase();
+  if (!['text', 'image', 'files'].includes(kind)) {
+    fail('clipboard-manifest-kind-invalid');
+  }
+  return kind;
+}
+
+function normalizeItemKind(value) {
+  const kind = String(value || '').trim().toLowerCase();
+  if (!['text', 'image', 'file'].includes(kind)) {
+    fail('clipboard-manifest-item-kind-invalid');
+  }
+  return kind;
+}
+
+function normalizeMimeType(value, itemKind) {
+  const fallback = itemKind === 'text'
+    ? 'text/plain;charset=utf-8'
+    : itemKind === 'image'
+      ? 'image/png'
+      : 'application/octet-stream';
+  const mimeType = boundedString(value || fallback, 160, 'clipboard-manifest-mime-invalid');
+  if (itemKind === 'text' && !mimeType.toLowerCase().startsWith('text/plain')) {
+    fail('clipboard-text-mime-required');
+  }
+  if (itemKind === 'image' && mimeType.toLowerCase() !== 'image/png') {
+    fail('clipboard-image-png-required');
+  }
+  return mimeType;
+}
+
+export function normalizeRemoteClipboardOperationId(value) {
+  const operationId = boundedString(value, 128, 'clipboard-operation-id-invalid', { required: true });
+  if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(operationId)) {
+    fail('clipboard-operation-id-invalid');
+  }
+  return operationId;
+}
+
+export function normalizeRemoteClipboardAction(value) {
+  const requested = String(value || '').trim().toLowerCase();
+  const action = ACTION_ALIASES.get(requested) || requested;
+  if (!REMOTE_CLIPBOARD_INPUT_ACTIONS.has(action) && !REMOTE_CLIPBOARD_FILE_ACTIONS.has(action)) {
+    fail('clipboard-action-invalid');
+  }
+  return action;
+}
+
+export function normalizeRemoteClipboardManifest(value, expectedOperationId = '') {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    fail('clipboard-manifest-required');
+  }
+  const operationId = normalizeRemoteClipboardOperationId(
+    value.operationId || value.clipboardOperationId || expectedOperationId);
+  if (expectedOperationId && operationId !== expectedOperationId) {
+    fail('clipboard-operation-id-mismatch');
+  }
+  const contentKind = normalizeContentKind(value.contentKind || value.kind);
+  const rawItems = Array.isArray(value.items) ? value.items : [];
+  if (rawItems.length === 0 || rawItems.length > REMOTE_CLIPBOARD_LIMITS.maxFiles) {
+    fail('clipboard-manifest-item-count-invalid');
+  }
+  const expectedItemKind = contentKind === 'files' ? 'file' : contentKind;
+  if (contentKind !== 'files' && rawItems.length !== 1) {
+    fail('clipboard-single-item-required');
+  }
+
+  let totalBytes = 0;
+  const items = rawItems.map((rawItem, itemIndex) => {
+    const item = rawItem && typeof rawItem === 'object' && !Array.isArray(rawItem) ? rawItem : {};
+    const normalizedIndex = exactInteger(item.itemIndex, {
+      min: 0,
+      max: REMOTE_CLIPBOARD_LIMITS.maxFiles - 1,
+      code: 'clipboard-manifest-item-index-invalid'
+    });
+    if (normalizedIndex !== itemIndex) {
+      fail('clipboard-manifest-item-index-invalid');
+    }
+    const kind = normalizeItemKind(item.kind);
+    if (kind !== expectedItemKind) {
+      fail('clipboard-manifest-item-kind-mismatch');
+    }
+    const size = exactInteger(item.size, {
+      min: 0,
+      max: REMOTE_CLIPBOARD_LIMITS.maxTotalBytes,
+      code: 'clipboard-manifest-item-size-invalid'
+    });
+    if (kind !== 'file' && size === 0) {
+      fail('clipboard-manifest-item-size-invalid');
+    }
+    if (kind === 'text' && size > REMOTE_CLIPBOARD_LIMITS.maxTextBytes) {
+      fail('clipboard-text-too-large', 413);
+    }
+    if (kind === 'image' && size > REMOTE_CLIPBOARD_LIMITS.maxImageBytes) {
+      fail('clipboard-image-too-large', 413);
+    }
+    totalBytes += size;
+    if (totalBytes > REMOTE_CLIPBOARD_LIMITS.maxTotalBytes) {
+      fail('clipboard-total-too-large', 413);
+    }
+    const storageName = boundedString(
+      item.storageName,
+      64,
+      'clipboard-manifest-storage-name-invalid',
+      { required: true });
+    if (storageName !== `item-${itemIndex}.bin`) {
+      fail('clipboard-manifest-storage-name-invalid');
+    }
+    const sha256 = boundedString(item.sha256, 64, 'clipboard-manifest-sha256-invalid', { required: true }).toLowerCase();
+    if (!/^[a-f0-9]{64}$/.test(sha256)) {
+      fail('clipboard-manifest-sha256-invalid');
+    }
+    const name = boundedString(
+      item.name || (kind === 'text' ? 'clipboard.txt' : kind === 'image' ? 'clipboard.png' : ''),
+      240,
+      'clipboard-manifest-name-invalid',
+      { required: true });
+    if (/[/\\\u0000-\u001f]/.test(name) || name === '.' || name === '..') {
+      fail('clipboard-manifest-name-invalid');
+    }
+    return {
+      itemIndex,
+      kind,
+      name,
+      mimeType: normalizeMimeType(item.mimeType, kind),
+      size,
+      lastModified: optionalInteger(item.lastModified, {
+        min: 0,
+        max: 8_640_000_000_000_000,
+        code: 'clipboard-manifest-last-modified-invalid'
+      }) || 0,
+      sha256,
+      storageName
+    };
+  });
+
+  const declaredTotalBytes = optionalInteger(value.totalBytes, {
+    min: 0,
+    max: REMOTE_CLIPBOARD_LIMITS.maxTotalBytes,
+    code: 'clipboard-manifest-total-invalid'
+  });
+  if (declaredTotalBytes !== undefined && declaredTotalBytes !== totalBytes) {
+    fail('clipboard-manifest-total-mismatch');
+  }
+  return { operationId, contentKind, totalBytes, items };
+}
+
+export function normalizeRemoteClipboardBase64(value, maxBytes = REMOTE_CLIPBOARD_LIMITS.maxChunkBytes) {
+  const encoded = String(value || '').trim();
+  if (encoded.length > Math.ceil(maxBytes / 3) * 4 + 4 || !/^[A-Za-z0-9+/]*={0,2}$/.test(encoded)) {
+    fail('clipboard-chunk-base64-invalid');
+  }
+  const bytes = Buffer.from(encoded, 'base64');
+  if (bytes.length > maxBytes) {
+    fail('clipboard-chunk-too-large', 413);
+  }
+  if (bytes.toString('base64') !== encoded) {
+    fail('clipboard-chunk-base64-invalid');
+  }
+  return { dataBase64: encoded, byteLength: bytes.length };
+}
+
+function normalizeBinding(body) {
+  const binding = body?.binding && typeof body.binding === 'object' && !Array.isArray(body.binding)
+    ? body.binding
+    : {};
+  return {
+    controlSessionId: boundedString(
+      binding.sessionId || binding.controlSessionId || body.controlSessionId || body.sessionId,
+      160,
+      'clipboard-control-session-required',
+      { required: true }),
+    controlCommandId: boundedString(
+      binding.commandId || binding.controlCommandId || body.controlCommandId || body.commandId,
+      128,
+      'clipboard-control-command-required',
+      { required: true }),
+    captureGeneration: exactInteger(
+      binding.captureGeneration ?? body.captureGeneration,
+      { min: 1, max: Number.MAX_SAFE_INTEGER, code: 'clipboard-capture-generation-required' }),
+    monitorIndex: exactInteger(
+      binding.monitorIndex ?? body.monitorIndex,
+      { min: 0, max: 63, code: 'clipboard-monitor-index-required' })
+  };
+}
+
+function normalizeClipboardPayload(action, rawPayload, operationId) {
+  const payload = rawPayload && typeof rawPayload === 'object' && !Array.isArray(rawPayload)
+    ? rawPayload
+    : {};
+  if (action === 'clipboard.paste.begin') {
+    return { manifest: normalizeRemoteClipboardManifest(payload.manifest || payload, operationId) };
+  }
+  if (action === 'clipboard.copy.chunk') {
+    return {
+      itemIndex: exactInteger(payload.itemIndex, {
+        min: 0,
+        max: REMOTE_CLIPBOARD_LIMITS.maxFiles - 1,
+        code: 'clipboard-item-index-invalid'
+      }),
+      offset: exactInteger(payload.offset, {
+        min: 0,
+        max: REMOTE_CLIPBOARD_LIMITS.maxTotalBytes,
+        code: 'clipboard-chunk-offset-invalid'
+      }),
+      maxBytes: exactInteger(payload.maxBytes ?? REMOTE_CLIPBOARD_LIMITS.maxChunkBytes, {
+        min: 1,
+        max: REMOTE_CLIPBOARD_LIMITS.maxChunkBytes,
+        code: 'clipboard-chunk-max-bytes-invalid'
+      })
+    };
+  }
+  if (action === 'clipboard.paste.chunk') {
+    const chunk = normalizeRemoteClipboardBase64(payload.dataBase64);
+    return {
+      itemIndex: exactInteger(payload.itemIndex, {
+        min: 0,
+        max: REMOTE_CLIPBOARD_LIMITS.maxFiles - 1,
+        code: 'clipboard-item-index-invalid'
+      }),
+      offset: exactInteger(payload.offset, {
+        min: 0,
+        max: REMOTE_CLIPBOARD_LIMITS.maxTotalBytes,
+        code: 'clipboard-chunk-offset-invalid'
+      }),
+      dataBase64: chunk.dataBase64,
+      final: payload.final === true
+    };
+  }
+  const normalized = {};
+  const manifestValue = payload.manifest;
+  if (manifestValue) {
+    normalized.manifest = normalizeRemoteClipboardManifest(manifestValue, operationId);
+  }
+  const requestedKind = payload.contentKind || payload.kind;
+  if (requestedKind) {
+    normalized.contentKind = normalizeContentKind(requestedKind);
+  }
+  return normalized;
+}
+
+export function normalizeRemoteClipboardRequest(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    fail('clipboard-request-invalid');
+  }
+  const action = normalizeRemoteClipboardAction(value.action || value.type);
+  const operationId = normalizeRemoteClipboardOperationId(
+    value.operationId || value.clipboardOperationId || value.op?.operationId || value.op);
+  const hubConnectionId = boundedString(
+    value.hubConnectionId || value.binding?.hubConnectionId,
+    128,
+    'clipboard-input-owner-required',
+    { required: true });
+  const clipboardDirection = action.includes('.paste')
+    ? 'paste'
+    : action.includes('.copy')
+      ? 'copy'
+      : String(value.clipboardDirection || value.payload?.clipboardDirection || '').trim().toLowerCase();
+  if (action === 'clipboard.prepare' && !['copy', 'paste'].includes(clipboardDirection)) {
+    fail('clipboard-direction-required');
+  }
+  return {
+    action,
+    operationId,
+    hubConnectionId,
+    clipboardDirection,
+    binding: normalizeBinding(value),
+    payload: normalizeClipboardPayload(action, value.payload, operationId)
+  };
+}
+
+export function remoteClipboardContentNeedsFileTransfer(contentKind) {
+  return contentKind === 'image' || contentKind === 'files';
+}
+
+function safeStatus(value) {
+  const status = String(value || '').trim().toLowerCase();
+  return SAFE_STATUS_VALUES.has(status) ? status : '';
+}
+
+export function normalizeRemoteClipboardCommandResult(action, operationId, value) {
+  const result = value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+  const returnedOperationId = result.operationId || result.clipboardOperationId;
+  if (returnedOperationId && normalizeRemoteClipboardOperationId(returnedOperationId) !== operationId) {
+    fail('clipboard-operation-id-mismatch', 409);
+  }
+  const response = {
+    ok: result.ok !== false,
+    action,
+    operationId,
+    status: safeStatus(result.status) || (result.ok === false ? 'failed' : '')
+  };
+  if (action === 'clipboard.copy.begin') {
+    response.manifest = normalizeRemoteClipboardManifest(result.manifest, operationId);
+    response.kind = response.manifest.contentKind;
+    response.status ||= 'ready';
+    return response;
+  }
+  if (action === 'clipboard.copy.chunk') {
+    const chunk = normalizeRemoteClipboardBase64(result.dataBase64);
+    const itemIndex = exactInteger(result.itemIndex, {
+      min: 0,
+      max: REMOTE_CLIPBOARD_LIMITS.maxFiles - 1,
+      code: 'clipboard-item-index-invalid'
+    });
+    const offset = exactInteger(result.offset, {
+      min: 0,
+      max: REMOTE_CLIPBOARD_LIMITS.maxTotalBytes,
+      code: 'clipboard-chunk-offset-invalid'
+    });
+    const bytes = exactInteger(result.bytes ?? chunk.byteLength, {
+      min: 0,
+      max: REMOTE_CLIPBOARD_LIMITS.maxChunkBytes,
+      code: 'clipboard-chunk-byte-count-invalid'
+    });
+    if (bytes !== chunk.byteLength) {
+      fail('clipboard-chunk-byte-count-mismatch');
+    }
+    return {
+      ok: result.ok !== false,
+      action,
+      operationId,
+      itemIndex,
+      offset,
+      bytes,
+      totalBytes: exactInteger(result.totalBytes, {
+        min: 0,
+        max: REMOTE_CLIPBOARD_LIMITS.maxTotalBytes,
+        code: 'clipboard-chunk-total-invalid'
+      }),
+      final: result.final === true,
+      dataBase64: chunk.dataBase64
+    };
+  }
+  if (action === 'clipboard.paste.chunk') {
+    return {
+      ok: result.ok !== false,
+      action,
+      operationId,
+      status: safeStatus(result.status) || '',
+      itemIndex: exactInteger(result.itemIndex, {
+        min: 0,
+        max: REMOTE_CLIPBOARD_LIMITS.maxFiles - 1,
+        code: 'clipboard-item-index-invalid'
+      }),
+      offset: exactInteger(result.offset, {
+        min: 0,
+        max: REMOTE_CLIPBOARD_LIMITS.maxTotalBytes,
+        code: 'clipboard-chunk-offset-invalid'
+      }),
+      bytes: exactInteger(result.bytes, {
+        min: 0,
+        max: REMOTE_CLIPBOARD_LIMITS.maxChunkBytes,
+        code: 'clipboard-chunk-byte-count-invalid'
+      }),
+      totalBytes: exactInteger(result.totalBytes, {
+        min: 0,
+        max: REMOTE_CLIPBOARD_LIMITS.maxTotalBytes,
+        code: 'clipboard-chunk-total-invalid'
+      }),
+      final: result.final === true
+    };
+  }
+  if (result.manifest) {
+    response.manifest = normalizeRemoteClipboardManifest(result.manifest, operationId);
+    response.kind = response.manifest.contentKind;
+  } else {
+    const kind = result.contentKind || result.kind;
+    if (kind) response.kind = normalizeContentKind(kind);
+  }
+  for (const key of ['receivedBytes', 'totalBytes']) {
+    if (result[key] !== undefined) {
+      response[key] = exactInteger(result[key], {
+        min: 0,
+        max: REMOTE_CLIPBOARD_LIMITS.maxTotalBytes,
+        code: `clipboard-${key}-invalid`
+      });
+    }
+  }
+  if (result.ready !== undefined) response.ready = result.ready === true;
+  return response;
+}