@hcu-lab.me/mcp-device 1.0.9 → 1.0.12

package/control-plane/scripts/device-pairing-store.mjs

@@ -0,0 +1,245 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { DatabaseSync } from 'node:sqlite';
+
+import { normalizeEd25519PublicKey } from './device-store.mjs';
+
+const DEVICE_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+const USER_CODE_ALPHABET = 'ABCDEFGHJKLMNPQRSTUVWXYZ23456789';
+
+function requiredText(value, label, max = 512) {
+  const text = String(value ?? '').trim();
+  if (!text || text.length > max) throw new Error(`${label} is required and must be at most ${max} characters.`);
+  return text;
+}
+
+function normalizeDeviceId(value) {
+  const deviceId = requiredText(value, 'device_id', 64);
+  if (!DEVICE_ID_PATTERN.test(deviceId)) throw new Error('Invalid device_id.');
+  return deviceId;
+}
+
+function normalizeCodeChallenge(value) {
+  const challenge = requiredText(value, 'code_challenge', 128);
+  if (!/^[A-Za-z0-9_-]{43,128}$/.test(challenge)) throw new Error('Invalid PKCE code_challenge.');
+  return challenge;
+}
+
+function sha256(value) {
+  return crypto.createHash('sha256').update(String(value), 'utf8').digest('base64url');
+}
+
+function publicKeyFingerprint(publicKeyPem) {
+  return sha256(normalizeEd25519PublicKey(publicKeyPem));
+}
+
+function generateUserCode() {
+  const bytes = crypto.randomBytes(8);
+  let code = '';
+  for (let i = 0; i < 8; i += 1) code += USER_CODE_ALPHABET[bytes[i] % USER_CODE_ALPHABET.length];
+  return `${code.slice(0, 4)}-${code.slice(4)}`;
+}
+
+function statusFromRow(row, nowMs) {
+  if (!row) return null;
+  const expired = Number(row.expires_at) < nowMs;
+  let status = 'pending';
+  if (expired) status = 'expired';
+  else if (row.grant_consumed_at) status = 'consumed';
+  else if (row.approved_at) status = 'approved';
+  return {
+    userCode: row.user_code,
+    deviceId: row.device_id,
+    deviceName: row.device_name,
+    status,
+    expiresAt: Number(row.expires_at),
+    approvedAt: row.approved_at ? Number(row.approved_at) : null,
+    accountId: row.owner_account_id || null,
+    accountLabel: row.account_label || null
+  };
+}
+
+export function createDevicePairingStore({
+  dbPath,
+  now = () => Date.now(),
+  ttlMs = 10 * 60_000,
+  pollIntervalSec = 2
+} = {}) {
+  if (!dbPath) throw new Error('dbPath is required for device pairing store.');
+  if (!Number.isInteger(ttlMs) || ttlMs < 60_000 || ttlMs > 60 * 60_000) throw new Error('Pairing ttlMs must be between 60000 and 3600000.');
+  if (!Number.isInteger(pollIntervalSec) || pollIntervalSec < 1 || pollIntervalSec > 30) throw new Error('Pairing pollIntervalSec must be between 1 and 30.');
+
+  const resolved = path.resolve(dbPath);
+  fs.mkdirSync(path.dirname(resolved), { recursive: true });
+  const db = new DatabaseSync(resolved);
+  db.exec(`
+    PRAGMA journal_mode = WAL;
+    PRAGMA synchronous = NORMAL;
+    PRAGMA busy_timeout = 5000;
+    CREATE TABLE IF NOT EXISTS device_pairings (
+      device_code TEXT PRIMARY KEY,
+      user_code TEXT NOT NULL UNIQUE,
+      client_id TEXT NOT NULL,
+      device_id TEXT NOT NULL,
+      device_name TEXT NOT NULL,
+      public_key_fingerprint TEXT NOT NULL,
+      code_challenge TEXT NOT NULL,
+      created_at INTEGER NOT NULL,
+      expires_at INTEGER NOT NULL,
+      approved_at INTEGER,
+      owner_account_id TEXT,
+      account_label TEXT,
+      grant_hash TEXT UNIQUE,
+      grant_issued_at INTEGER,
+      grant_consumed_at INTEGER
+    );
+    CREATE INDEX IF NOT EXISTS device_pairings_user_code_idx ON device_pairings(user_code);
+    CREATE INDEX IF NOT EXISTS device_pairings_grant_hash_idx ON device_pairings(grant_hash);
+  `);
+
+  const columns = db.prepare('PRAGMA table_info(device_pairings)').all();
+  if (!columns.some(column => column.name === 'owner_account_id')) {
+    db.exec('ALTER TABLE device_pairings ADD COLUMN owner_account_id TEXT');
+  }
+
+  const getByUserCodeStatement = db.prepare('SELECT * FROM device_pairings WHERE user_code = ?');
+  const getByDeviceCodeStatement = db.prepare('SELECT * FROM device_pairings WHERE device_code = ?');
+  const getByGrantHashStatement = db.prepare('SELECT * FROM device_pairings WHERE grant_hash = ?');
+  const insertStatement = db.prepare(`
+    INSERT INTO device_pairings (
+      device_code, user_code, client_id, device_id, device_name,
+      public_key_fingerprint, code_challenge, created_at, expires_at
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `);
+  const approveStatement = db.prepare(`
+    UPDATE device_pairings
+    SET approved_at = ?, owner_account_id = ?, account_label = ?
+    WHERE user_code = ? AND approved_at IS NULL
+  `);
+  const grantStatement = db.prepare(`
+    UPDATE device_pairings
+    SET grant_hash = ?, grant_issued_at = ?
+    WHERE device_code = ? AND grant_hash IS NULL
+  `);
+  const consumeStatement = db.prepare(`
+    UPDATE device_pairings
+    SET grant_consumed_at = ?
+    WHERE grant_hash = ? AND grant_consumed_at IS NULL
+  `);
+
+  function start({ clientId, deviceId, deviceName, publicKeyPem, codeChallenge }) {
+    const normalizedClientId = requiredText(clientId, 'client_id', 128);
+    const normalizedDeviceId = normalizeDeviceId(deviceId);
+    const normalizedDeviceName = requiredText(deviceName, 'device_name', 128);
+    const fingerprint = publicKeyFingerprint(publicKeyPem);
+    const normalizedChallenge = normalizeCodeChallenge(codeChallenge);
+    const createdAt = Number(now());
+    const expiresAt = createdAt + ttlMs;
+    const deviceCode = crypto.randomBytes(32).toString('base64url');
+
+    let userCode;
+    for (let attempt = 0; attempt < 8; attempt += 1) {
+      const candidate = generateUserCode();
+      try {
+        insertStatement.run(
+          deviceCode,
+          candidate,
+          normalizedClientId,
+          normalizedDeviceId,
+          normalizedDeviceName,
+          fingerprint,
+          normalizedChallenge,
+          createdAt,
+          expiresAt
+        );
+        userCode = candidate;
+        break;
+      } catch (error) {
+        if (!String(error?.message || '').toLowerCase().includes('unique')) throw error;
+      }
+    }
+    if (!userCode) throw new Error('Unable to allocate a unique device pairing code.');
+
+    return {
+      deviceCode,
+      userCode,
+      expiresIn: Math.floor(ttlMs / 1000),
+      interval: pollIntervalSec
+    };
+  }
+
+  function getStatusByUserCode(userCode) {
+    const normalized = requiredText(userCode, 'user_code', 16).toUpperCase();
+    const row = getByUserCodeStatement.get(normalized);
+    if (!row) throw new Error('Unknown pairing code.');
+    return statusFromRow(row, Number(now()));
+  }
+
+  function approve({ userCode, accountId, accountLabel }) {
+    const normalized = requiredText(userCode, 'user_code', 16).toUpperCase();
+    const owner = requiredText(accountId, 'account_id', 64);
+    const label = requiredText(accountLabel, 'account_label', 128);
+    const row = getByUserCodeStatement.get(normalized);
+    if (!row) throw new Error('Unknown pairing code.');
+    const nowMs = Number(now());
+    if (Number(row.expires_at) < nowMs) throw new Error('Pairing code expired.');
+    if (row.grant_consumed_at) throw new Error('Pairing code was already consumed.');
+    if (!row.approved_at) approveStatement.run(nowMs, owner, label, normalized);
+    const updated = getByUserCodeStatement.get(normalized);
+    return statusFromRow(updated, nowMs);
+  }
+
+  function poll({ deviceCode, clientId, codeVerifier }) {
+    const normalizedDeviceCode = requiredText(deviceCode, 'device_code', 128);
+    const normalizedClientId = requiredText(clientId, 'client_id', 128);
+    const verifier = requiredText(codeVerifier, 'code_verifier', 256);
+    const row = getByDeviceCodeStatement.get(normalizedDeviceCode);
+    if (!row) throw new Error('Unknown device code.');
+    const nowMs = Number(now());
+    if (Number(row.expires_at) < nowMs) throw new Error('Device pairing code expired.');
+    if (row.client_id !== normalizedClientId) throw new Error('Device code was not issued to this client.');
+    if (sha256(verifier) !== row.code_challenge) throw new Error('PKCE verifier does not match device pairing request.');
+    if (!row.approved_at) return { status: 'authorization_pending' };
+    if (row.grant_consumed_at) throw new Error('Pairing enrollment grant was already consumed.');
+    if (row.grant_hash) throw new Error('Pairing enrollment grant was already issued.');
+
+    const enrollmentGrant = crypto.randomBytes(32).toString('base64url');
+    const grantHash = sha256(enrollmentGrant);
+    const changed = grantStatement.run(grantHash, nowMs, normalizedDeviceCode);
+    if (Number(changed.changes) !== 1) throw new Error('Pairing enrollment grant was already issued.');
+    return {
+      status: 'approved',
+      enrollmentGrant,
+      deviceId: row.device_id,
+      account: { connected: true, account_id: row.owner_account_id, label: row.account_label }
+    };
+  }
+
+  function consumeGrant({ enrollmentGrant, deviceId, publicKeyPem }) {
+    const grant = requiredText(enrollmentGrant, 'enrollment_grant', 256);
+    const normalizedDeviceId = normalizeDeviceId(deviceId);
+    const fingerprint = publicKeyFingerprint(publicKeyPem);
+    const grantHash = sha256(grant);
+    const row = getByGrantHashStatement.get(grantHash);
+    if (!row) throw new Error('Invalid enrollment grant.');
+    const nowMs = Number(now());
+    if (Number(row.expires_at) < nowMs) throw new Error('Enrollment grant expired.');
+    if (row.grant_consumed_at) throw new Error('Enrollment grant was already consumed.');
+    if (row.device_id !== normalizedDeviceId) throw new Error('Enrollment grant is bound to a different device.');
+    if (row.public_key_fingerprint !== fingerprint) throw new Error('Enrollment grant is bound to a different device key.');
+    const changed = consumeStatement.run(nowMs, grantHash);
+    if (Number(changed.changes) !== 1) throw new Error('Enrollment grant was already consumed.');
+    return {
+      deviceId: row.device_id,
+      deviceName: row.device_name,
+      account: { connected: true, account_id: row.owner_account_id, label: row.account_label }
+    };
+  }
+
+  function close() {
+    db.close();
+  }
+
+  return { start, getStatusByUserCode, approve, poll, consumeGrant, close };
+}

package/control-plane/scripts/device-public-contract.mjs

@@ -0,0 +1,165 @@
+import { DEVICE_PUBLIC_TOOL_NAMES, listStaticDevicePublicTools } from './device-execution-tool-definitions.mjs';
+
+function clone(value) {
+  return value === undefined ? undefined : JSON.parse(JSON.stringify(value));
+}
+
+function toolContract(tool) {
+  return {
+    name: tool.name,
+    description: tool.description,
+    inputSchema: clone(tool.inputSchema),
+    ...(tool.outputSchema ? { outputSchema: clone(tool.outputSchema) } : {}),
+    ...(tool.annotations ? { annotations: clone(tool.annotations) } : {}),
+    ...(tool._meta ? { _meta: clone(tool._meta) } : {})
+  };
+}
+
+export function buildDevicePublicContract() {
+  const tools = listStaticDevicePublicTools();
+  if (tools.length !== DEVICE_PUBLIC_TOOL_NAMES.length) {
+    throw new Error('Device public contract tool count drifted from the fixed device surface.');
+  }
+  return {
+    schemaVersion: 1,
+    scope: 'gateway-device-public-tools',
+    mcpSpecificationRevision: '2026-07-28',
+    resultEnvelope: {
+      success: {
+        content: 'MCP CallToolResult content array',
+        structuredContent: 'JSON object when the gateway normalizes a structured device result'
+      }
+    },
+    errorEnvelope: {
+      publicProtocolError: {
+        type: 'JSON-RPC request error',
+        code: -32603,
+        message: 'Gateway/device error message',
+        customInternalCodeExposed: false
+      },
+      internalRoutingCodes: [
+        'DEVICE_ID_REQUIRED',
+        'DEVICE_NOT_READY',
+        'DEVICE_OFFLINE',
+        'DEVICE_RUNTIME_CHANGED',
+        'PROCESS_SESSION_STALE',
+        'DEVICE_ACCESS_DENIED',
+        'DEVICE_PATH_DENIED',
+        'DEVICE_RATE_LIMIT',
+        'DEVICE_INPUT_TOO_LARGE',
+        'DEVICE_OUTPUT_TOO_LARGE',
+        'DEVICE_NOT_FOUND',
+        'DEVICE_SELECTION_AMBIGUOUS',
+        'PATH_HINT_REQUIRED',
+        'PATH_HINT_UNSUPPORTED',
+        'REMOTE_DEVICE_ERROR'
+      ]
+    },
+    tools: tools.map(toolContract)
+  };
+}
+
+function jsonEqual(left, right) {
+  return JSON.stringify(left) === JSON.stringify(right);
+}
+
+function addChange(changes, classification, path, before, after) {
+  changes.push({ classification, path, before, after });
+}
+
+function classifyInputSchema(toolName, before = {}, after = {}, changes) {
+  const beforeRequired = new Set(before.required || []);
+  const afterRequired = new Set(after.required || []);
+  for (const name of afterRequired) {
+    if (!beforeRequired.has(name)) addChange(changes, 'breaking', `tools.${toolName}.inputSchema.required+${name}`, false, true);
+  }
+  for (const name of beforeRequired) {
+    if (!afterRequired.has(name)) addChange(changes, 'additive', `tools.${toolName}.inputSchema.required-${name}`, true, false);
+  }
+
+  const beforeProps = before.properties || {};
+  const afterProps = after.properties || {};
+  for (const name of Object.keys(beforeProps)) {
+    if (!(name in afterProps)) {
+      addChange(changes, 'breaking', `tools.${toolName}.inputSchema.properties.${name}`, beforeProps[name], undefined);
+      continue;
+    }
+    if (!jsonEqual(beforeProps[name], afterProps[name])) {
+      addChange(changes, 'breaking', `tools.${toolName}.inputSchema.properties.${name}`, beforeProps[name], afterProps[name]);
+    }
+  }
+  for (const name of Object.keys(afterProps)) {
+    if (name in beforeProps) continue;
+    addChange(
+      changes,
+      afterRequired.has(name) ? 'breaking' : 'additive',
+      `tools.${toolName}.inputSchema.properties.${name}`,
+      undefined,
+      afterProps[name]
+    );
+  }
+
+  const beforeAdditional = before.additionalProperties;
+  const afterAdditional = after.additionalProperties;
+  if (!jsonEqual(beforeAdditional, afterAdditional)) {
+    const classification = beforeAdditional === false && afterAdditional !== false ? 'additive' : 'breaking';
+    addChange(changes, classification, `tools.${toolName}.inputSchema.additionalProperties`, beforeAdditional, afterAdditional);
+  }
+
+  const handled = new Set(['required', 'properties', 'additionalProperties']);
+  const beforeRest = Object.fromEntries(Object.entries(before).filter(([key]) => !handled.has(key)));
+  const afterRest = Object.fromEntries(Object.entries(after).filter(([key]) => !handled.has(key)));
+  if (!jsonEqual(beforeRest, afterRest)) {
+    addChange(changes, 'breaking', `tools.${toolName}.inputSchema`, beforeRest, afterRest);
+  }
+}
+
+export function classifyDevicePublicContractChanges(baseline, current) {
+  const changes = [];
+  const baselineTools = new Map((baseline?.tools || []).map(tool => [tool.name, tool]));
+  const currentTools = new Map((current?.tools || []).map(tool => [tool.name, tool]));
+
+  for (const [name, before] of baselineTools) {
+    const after = currentTools.get(name);
+    if (!after) {
+      addChange(changes, 'breaking', `tools.${name}`, before, undefined);
+      continue;
+    }
+
+    const beforeDeprecated = before?._meta?.deprecated === true;
+    const afterDeprecated = after?._meta?.deprecated === true;
+    if (!beforeDeprecated && afterDeprecated) {
+      addChange(changes, 'deprecated', `tools.${name}._meta.deprecated`, false, true);
+    }
+
+    classifyInputSchema(name, before.inputSchema, after.inputSchema, changes);
+
+    for (const key of ['description', 'outputSchema', 'annotations']) {
+      if (!jsonEqual(before[key], after[key])) {
+        addChange(changes, 'breaking', `tools.${name}.${key}`, before[key], after[key]);
+      }
+    }
+
+    const beforeMeta = { ...(before._meta || {}) };
+    const afterMeta = { ...(after._meta || {}) };
+    delete beforeMeta.deprecated;
+    delete afterMeta.deprecated;
+    if (!jsonEqual(beforeMeta, afterMeta)) {
+      addChange(changes, 'breaking', `tools.${name}._meta`, beforeMeta, afterMeta);
+    }
+  }
+
+  for (const [name, after] of currentTools) {
+    if (!baselineTools.has(name)) addChange(changes, 'additive', `tools.${name}`, undefined, after);
+  }
+
+  for (const key of ['schemaVersion', 'scope', 'mcpSpecificationRevision', 'resultEnvelope', 'errorEnvelope']) {
+    if (!jsonEqual(baseline?.[key], current?.[key])) {
+      addChange(changes, 'breaking', key, baseline?.[key], current?.[key]);
+    }
+  }
+
+  const counts = { unchanged: changes.length === 0 ? 1 : 0, additive: 0, deprecated: 0, breaking: 0 };
+  for (const change of changes) counts[change.classification] += 1;
+  return { counts, changes };
+}

package/control-plane/scripts/device-release.mjs

@@ -0,0 +1,95 @@
+const DEFAULT_PACKAGE = '@hcu-lab.me/mcp-device';
+const DEFAULT_REGISTRY = 'https://registry.npmjs.org';
+
+export function normalizeStableVersion(value) {
+  const version = String(value || '').trim();
+  if (!/^\d+\.\d+\.\d+$/.test(version)) throw new Error('Expected an exact stable semantic version.');
+  return version;
+}
+
+export function compareStableVersions(left, right) {
+  const a = normalizeStableVersion(left).split('.').map(Number);
+  const b = normalizeStableVersion(right).split('.').map(Number);
+  for (let index = 0; index < 3; index += 1) {
+    if (a[index] !== b[index]) return a[index] < b[index] ? -1 : 1;
+  }
+  return 0;
+}
+
+export function isNewerStableVersion(current, latest) {
+  try { return compareStableVersions(current, latest) < 0; }
+  catch { return false; }
+}
+
+export function minimumSelfUpdateVersion(platform) {
+  const normalized = String(platform || '').trim().toLowerCase();
+  if (normalized === 'win32') return '1.0.6';
+  if (normalized === 'linux') return '1.0.8';
+  return '1.0.5';
+}
+
+export function supportsDeviceSelfUpdate(packageVersion, platform) {
+  try {
+    return Boolean(packageVersion) && compareStableVersions(packageVersion, minimumSelfUpdateVersion(platform)) >= 0;
+  } catch {
+    return false;
+  }
+}
+
+export function createDeviceReleaseProvider(options = {}) {
+  const packageName = String(options.packageName || DEFAULT_PACKAGE).trim();
+  const registryUrl = String(options.registryUrl || DEFAULT_REGISTRY).replace(/\/+$/, '');
+  const fetchFn = options.fetchFn || globalThis.fetch;
+  const enabled = options.enabled !== false;
+  const ttlMs = Math.max(1_000, Number(options.ttlMs || 60_000));
+  const timeoutMs = Math.max(500, Number(options.timeoutMs || 4_000));
+  let fallbackVersion = null;
+  try { fallbackVersion = options.fallbackVersion ? normalizeStableVersion(options.fallbackVersion) : null; } catch {}
+  let cachedVersion = fallbackVersion;
+  let cachedAt = fallbackVersion ? Date.now() : 0;
+  let inFlight = null;
+
+  async function fetchLatest() {
+    if (typeof fetchFn !== 'function') throw new Error('fetch is unavailable');
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    timer.unref?.();
+    try {
+      const response = await fetchFn(`${registryUrl}/${encodeURIComponent(packageName)}/latest`, {
+        headers: { accept: 'application/json' },
+        signal: controller.signal
+      });
+      if (!response?.ok) throw new Error(`npm registry returned HTTP ${response?.status || 'unknown'}`);
+      const body = await response.json();
+      return normalizeStableVersion(body?.version);
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  async function latestVersion() {
+    if (!enabled) return cachedVersion || fallbackVersion || null;
+    const now = Date.now();
+    if (cachedVersion && now - cachedAt < ttlMs) return cachedVersion;
+    if (inFlight) return await inFlight;
+    inFlight = (async () => {
+      try {
+        const latest = await fetchLatest();
+        cachedVersion = latest;
+        cachedAt = Date.now();
+        return latest;
+      } catch {
+        return cachedVersion || fallbackVersion || null;
+      } finally {
+        inFlight = null;
+      }
+    })();
+    return await inFlight;
+  }
+
+  return {
+    latestVersion,
+    peek: () => cachedVersion,
+    packageName
+  };
+}

package/control-plane/scripts/device-secure-transport.mjs

@@ -0,0 +1,128 @@
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import tls from 'node:tls';
+import { Duplex } from 'node:stream';
+import { WebSocket } from 'ws';
+
+export const DEVICE_INNER_TLS_SUBPROTOCOL = 'hcu-device-v2-inner-tls';
+export const DEVICE_MAX_MESSAGE_BYTES = 64 * 1024;
+
+export function loadDeviceInnerTlsConfig(env = process.env, readFile = readFileSync) {
+  const certPath = String(env.MCP_DEVICE_INNER_TLS_CERT_PATH || '').trim();
+  const keyPath = String(env.MCP_DEVICE_INNER_TLS_KEY_PATH || '').trim();
+  if (!certPath && !keyPath) return null;
+  if (!certPath || !keyPath) throw new Error('MCP_DEVICE_INNER_TLS_CERT_PATH and MCP_DEVICE_INNER_TLS_KEY_PATH must be configured together.');
+  return { cert: readFile(certPath), key: readFile(keyPath) };
+}
+
+export class WebSocketDuplex extends Duplex {
+  constructor(ws) {
+    super();
+    this.ws = ws;
+    ws.on('message', (data, isBinary) => {
+      if (!isBinary) {
+        this.destroy(new Error('Inner TLS transport requires binary WebSocket messages.'));
+        return;
+      }
+      const chunk = Buffer.isBuffer(data) ? data : Buffer.from(data);
+      this.push(chunk);
+    });
+    ws.once('close', () => this.push(null));
+    ws.once('error', error => this.destroy(error));
+  }
+
+  _read() {}
+
+  _write(chunk, _encoding, callback) {
+    if (this.ws.readyState !== WebSocket.OPEN) {
+      callback(new Error('WebSocket is not open.'));
+      return;
+    }
+    this.ws.send(Buffer.from(chunk), { binary: true }, callback);
+  }
+
+  _destroy(error, callback) {
+    try {
+      if (this.ws.readyState === WebSocket.OPEN) this.ws.close(1000, 'inner transport closed');
+      else if (this.ws.readyState === WebSocket.CONNECTING) this.ws.terminate();
+    } catch {}
+    callback(error);
+  }
+}
+
+export function createWebSocketDuplex(ws) {
+  return new WebSocketDuplex(ws);
+}
+
+export function createServerInnerTls(ws, { cert, key, secureContext } = {}) {
+  const context = secureContext || tls.createSecureContext({ cert, key, minVersion: 'TLSv1.3' });
+  return new tls.TLSSocket(createWebSocketDuplex(ws), {
+    isServer: true,
+    secureContext: context
+  });
+}
+
+export function exportDeviceAuthKeyingMaterial(socket, deviceId, mode) {
+  const context = createHash('sha256')
+    .update(`hcu-mcp-device-auth-v2\n${String(deviceId)}\n${String(mode)}`, 'utf8')
+    .digest();
+  return socket.exportKeyingMaterial(32, 'EXPERIMENTAL-HCU-MCP-DEVICE-AUTH-V2', context);
+}
+
+export function encodeJsonFrame(message, maxMessageBytes = DEVICE_MAX_MESSAGE_BYTES) {
+  const payload = Buffer.from(JSON.stringify(message), 'utf8');
+  if (payload.length < 1 || payload.length > maxMessageBytes) {
+    throw new Error('Device JSON frame exceeds maximum size.');
+  }
+  const frame = Buffer.allocUnsafe(4 + payload.length);
+  frame.writeUInt32BE(payload.length, 0);
+  payload.copy(frame, 4);
+  return frame;
+}
+
+export function createJsonFrameParser({ maxMessageBytes = DEVICE_MAX_MESSAGE_BYTES, onMessage }) {
+  if (typeof onMessage !== 'function') throw new Error('onMessage callback is required.');
+  const header = Buffer.allocUnsafe(4);
+  let headerBytes = 0;
+  let expectedLength = null;
+  let bodyBytes = 0;
+  let bodyParts = [];
+
+  return {
+    push(value) {
+      const chunk = Buffer.isBuffer(value) ? value : Buffer.from(value);
+      let offset = 0;
+      while (offset < chunk.length) {
+        if (expectedLength === null) {
+          const take = Math.min(4 - headerBytes, chunk.length - offset);
+          chunk.copy(header, headerBytes, offset, offset + take);
+          headerBytes += take;
+          offset += take;
+          if (headerBytes < 4) continue;
+          const length = header.readUInt32BE(0);
+          headerBytes = 0;
+          if (length < 1 || length > maxMessageBytes) throw new Error('Invalid device JSON frame length.');
+          expectedLength = length;
+          bodyBytes = 0;
+          bodyParts = [];
+          continue;
+        }
+
+        const remaining = expectedLength - bodyBytes;
+        const take = Math.min(remaining, chunk.length - offset);
+        bodyParts.push(chunk.subarray(offset, offset + take));
+        bodyBytes += take;
+        offset += take;
+        if (bodyBytes !== expectedLength) continue;
+
+        const text = Buffer.concat(bodyParts, expectedLength).toString('utf8');
+        expectedLength = null;
+        bodyBytes = 0;
+        bodyParts = [];
+        const message = JSON.parse(text);
+        if (!message || typeof message !== 'object') throw new Error('Device JSON frame must contain an object.');
+        onMessage(message);
+      }
+    }
+  };
+}