livedesk 0.1.457 → 0.1.459

package/diagnostics/livedesk-transport-physical-core.mjs

@@ -0,0 +1,503 @@
+import { isIP } from 'node:net';
+
+const REQUIRED_PHASES = Object.freeze([
+  'direct',
+  'p2p',
+  'relay',
+  'recover-direct'
+]);
+
+const MAX_PHASE_LATENCY_MS = 15_000;
+const MAX_AGENT_QUEUE_DEPTH = 8;
+const MAX_AGENT_QUEUE_DROPPED_DELTA = 8;
+const MAX_HUB_INGRESS_DROPPED_DELTA = 8;
+const MAX_UDP_INCOMPLETE_DELTA = 2;
+const MAX_HUB_ADDRESS_OBSERVATION_SKEW_MS = 60_000;
+
+const SECRET_KEYS = new Set([
+  'authorization',
+  'bearer',
+  'token',
+  'secret',
+  'password',
+  'apikey',
+  'pairtoken'
+]);
+const SAFE_NETWORK_KEYS = new Set([
+  'clientaddresshash',
+  'hubaddresshash',
+  'clientaddresspublic',
+  'hubaddresspublic',
+  'hubaddressobservedat',
+  'endpointauthenticated',
+  'differentpublicegress',
+  'evidence',
+  'observedat',
+  'udpready'
+]);
+const IDENTIFIER_KEYS = new Set([
+  'leaseid',
+  'deviceid',
+  'selecteddeviceid',
+  'streamid',
+  'streamcommandid',
+  'commandid',
+  'sessionid',
+  'requestid',
+  'connectionid',
+  'hubconnectionid',
+  'inputeventid',
+  'clientid',
+  'ownerid'
+]);
+const SECRET_TEXT = /\b(?:authorization|bearer|token|secret|password|api[-_ ]?key|pair[-_ ]?token)(?:\s+|\s*[:=]\s*)\S+/i;
+const IPV4_TEXT = /(^|[^\d])(?:\d{1,3}\.){3}\d{1,3}(?::\d{1,5})?($|[^\d])/;
+const IPV6_CANDIDATE_TEXT = /\[[0-9a-f:.%]+\](?::\d{1,5})?|[0-9a-f:%]*:[0-9a-f:.%:]*/gi;
+const URL_TEXT = /\b[a-z][a-z0-9+.-]*:\/\/[^\s]+/i;
+const HOST_TEXT = /\b(?:localhost|(?:[a-z0-9-]+\.)+[a-z]{2,63})(?::\d{1,5})?\b/i;
+const UUID_TEXT = /\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b/i;
+
+function normalizedKey(key) {
+  return String(key || '').replace(/[-_]/g, '').toLowerCase();
+}
+
+function isIdentifierKey(key) {
+  return IDENTIFIER_KEYS.has(normalizedKey(key));
+}
+
+function isSecretKey(key) {
+  const normalized = normalizedKey(key);
+  return SECRET_KEYS.has(normalized)
+    || normalized.endsWith('token')
+    || normalized.endsWith('secret')
+    || normalized.endsWith('password')
+    || normalized.endsWith('apikey');
+}
+
+function isRawNetworkKey(key) {
+  const rawKey = String(key || '');
+  const normalized = normalizedKey(key);
+  if (SAFE_NETWORK_KEYS.has(normalized) || normalized.endsWith('hash')) return false;
+  return normalized === 'address'
+    || normalized.endsWith('address')
+    || normalized === 'endpoint'
+    || normalized.endsWith('endpoint')
+    || normalized === 'host'
+    || normalized.endsWith('host')
+    || normalized === 'port'
+    || /(?:^|[-_])port$/i.test(rawKey)
+    || /[A-Z]Port$/.test(rawKey)
+    || normalized === 'url'
+    || normalized.endsWith('url')
+    || normalized === 'uri'
+    || normalized.endsWith('uri')
+    || normalized === 'origin'
+    || normalized.endsWith('origin');
+}
+
+function containsIpv6Text(value) {
+  const candidates = String(value || '').match(IPV6_CANDIDATE_TEXT) || [];
+  return candidates.some(candidate => {
+    const bracketed = candidate.match(/^\[([^\]]+)\](?::\d{1,5})?$/);
+    const address = String(bracketed?.[1] || candidate)
+      .replace(/%[a-z0-9_.-]+$/i, '')
+      .replace(/[.,;]+$/g, '');
+    return isIP(address) === 6;
+  });
+}
+
+function containsRawNetworkText(value) {
+  const text = String(value || '');
+  return IPV4_TEXT.test(text)
+    || containsIpv6Text(text)
+    || URL_TEXT.test(text)
+    || HOST_TEXT.test(text);
+}
+
+function identifierMarker(value) {
+  if (value === null || value === undefined || String(value) === '') return '';
+  return '[redacted-id]';
+}
+
+export function genericTransportPhysicalError(value, fallback = 'transport-diagnostic-error') {
+  const text = String(value instanceof Error ? value.message : value || '').trim();
+  if (!text
+    || containsRawNetworkText(text)
+    || SECRET_TEXT.test(text)
+    || UUID_TEXT.test(text)) return fallback;
+  if (!/^[a-z0-9][a-z0-9 _.,:;()[\]/'"+=-]{0,239}$/i.test(text)) return fallback;
+  return text;
+}
+
+export function redactTransportPhysicalReport(value, key = '') {
+  if (isSecretKey(key)) return '[redacted]';
+  if (isIdentifierKey(key)) return identifierMarker(value);
+  if (isRawNetworkKey(key)) return '[redacted-network]';
+  if (Array.isArray(value)) {
+    return value.map(item => redactTransportPhysicalReport(item));
+  }
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(Object.entries(value)
+      .filter(([childKey]) => !isSecretKey(childKey))
+      .map(([childKey, childValue]) => [
+        childKey,
+        redactTransportPhysicalReport(childValue, childKey)
+      ]));
+  }
+  if (typeof value === 'string'
+    && (containsRawNetworkText(value)
+      || SECRET_TEXT.test(value)
+      || UUID_TEXT.test(value))) {
+    return /error|reason|detail|summary/i.test(key)
+      ? '[redacted-sensitive-error]'
+      : '[redacted-sensitive]';
+  }
+  return value;
+}
+
+export function findTransportPhysicalReportLeaks(value, path = '$', leaks = []) {
+  if (Array.isArray(value)) {
+    value.forEach((item, index) => findTransportPhysicalReportLeaks(item, `${path}[${index}]`, leaks));
+    return leaks;
+  }
+  if (value && typeof value === 'object') {
+    for (const [key, child] of Object.entries(value)) {
+      if (isSecretKey(key)
+        || (isRawNetworkKey(key) && child !== '[redacted-network]')) {
+        leaks.push(`${path}.${key}`);
+      }
+      if (isIdentifierKey(key)
+        && child !== ''
+        && child !== '[redacted-id]') {
+        leaks.push(`${path}.${key}`);
+      }
+      findTransportPhysicalReportLeaks(child, `${path}.${key}`, leaks);
+    }
+    return leaks;
+  }
+  if (typeof value === 'string'
+    && (containsRawNetworkText(value)
+      || SECRET_TEXT.test(value)
+      || UUID_TEXT.test(value))) {
+    leaks.push(path);
+  }
+  return leaks;
+}
+
+function optionalFinite(value) {
+  if (value === null || value === undefined || value === '') return null;
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+function phaseFrame(snapshot, phase) {
+  return Array.isArray(snapshot?.frames)
+    ? snapshot.frames.find(frame => frame?.phase === phase && frame?.accepted === true)
+    : null;
+}
+
+function expectedPathForPhase(phase) {
+  if (phase === 'p2p') return 'p2p';
+  if (phase === 'relay') return 'relay';
+  return 'direct';
+}
+
+export function hubObservedTransport(frame) {
+  const transport = String(frame?.transport || '').trim().toLowerCase();
+  if (transport === 'udp-p2p') return { path: 'p2p', label: 'udp-p2p' };
+  if (transport === 'relay-binary') return { path: 'relay', label: 'relay-binary' };
+  if (transport === 'binary' || transport === 'tcp-binary') {
+    return { path: 'direct', label: 'direct-tcp' };
+  }
+  if (transport === 'ws-binary') return { path: 'direct', label: 'direct-ws' };
+  return { path: '', label: 'unknown' };
+}
+
+export function isTransportPhysicalPhaseEvidence(frame, phase) {
+  const expectedPath = expectedPathForPhase(phase);
+  const observed = hubObservedTransport(frame);
+  const phaseLatencyMs = optionalFinite(frame?.phaseLatencyMs);
+  return frame?.accepted === true
+    && frame?.phase === phase
+    && frame?.actualPath === expectedPath
+    && observed.path === expectedPath
+    && frame?.isKeyFrame === true
+    && frame?.annexB === true
+    && frame?.hasIdr === true
+    && frame?.hasSps === true
+    && frame?.hasPps === true
+    && frame?.nalOrderValid === true
+    && optionalFinite(frame?.byteLength) > 0
+    && phaseLatencyMs !== null
+    && phaseLatencyMs >= 0
+    && phaseLatencyMs <= MAX_PHASE_LATENCY_MS;
+}
+
+function cumulativeDelta(values) {
+  if (!Array.isArray(values) || values.length < 2) {
+    return { valid: false, delta: null };
+  }
+  const normalized = values.map(optionalFinite);
+  const valid = normalized.every(value => value !== null && value >= 0)
+    && normalized.every((value, index) => index === 0 || value >= normalized[index - 1]);
+  return {
+    valid,
+    delta: valid ? normalized.at(-1) - normalized[0] : null
+  };
+}
+
+function scopedCounterDelta(baselines, samples) {
+  const scopes = new Map();
+  for (const baseline of baselines || []) {
+    const scope = String(baseline?.scope || '');
+    const value = optionalFinite(baseline?.value);
+    if (!scope || value === null || value < 0 || scopes.has(scope)) {
+      return { valid: false, delta: null };
+    }
+    scopes.set(scope, { initial: value, last: value });
+  }
+  let total = 0;
+  for (const sample of samples || []) {
+    const scope = String(sample?.scope || '');
+    const value = optionalFinite(sample?.value);
+    if (!scope || value === null || value < 0) {
+      return { valid: false, delta: null };
+    }
+    const state = scopes.get(scope) || { initial: 0, last: 0 };
+    if (value < state.last) {
+      return { valid: false, delta: null };
+    }
+    state.last = value;
+    scopes.set(scope, state);
+  }
+  for (const state of scopes.values()) {
+    total += state.last - state.initial;
+  }
+  return { valid: true, delta: total };
+}
+
+function timestampWithin(value, reference, maximumSkewMs) {
+  const observedAt = Date.parse(String(value || ''));
+  const referenceAt = Date.parse(String(reference || ''));
+  return Number.isFinite(observedAt)
+    && Number.isFinite(referenceAt)
+    && Math.abs(observedAt - referenceAt) <= maximumSkewMs;
+}
+
+export function classifyTransportPhysicalSnapshot(snapshot) {
+  const checks = [];
+  const add = (id, ok, detail) => checks.push({ id, ok: ok === true, detail });
+  const owner = snapshot?.owner || {};
+
+  add(
+    'same-current-owner',
+    !!owner.streamId
+      && !!owner.streamCommandId
+      && Number(owner.captureGeneration || 0) > 0
+      && Number(owner.monitorIndex) >= 0,
+    'One immutable stream, command, generation, and monitor must own the complete run.');
+
+  const observedFrames = REQUIRED_PHASES.map(phase => phaseFrame(snapshot, phase));
+  for (let index = 0; index < REQUIRED_PHASES.length; index += 1) {
+    const phase = REQUIRED_PHASES[index];
+    const frame = observedFrames[index];
+    const expectedPath = expectedPathForPhase(phase);
+    const observed = hubObservedTransport(frame);
+    add(
+      `received-h264-${phase}`,
+      !!frame
+        && frame.actualPath === expectedPath
+        && frame.isKeyFrame === true
+        && frame.annexB === true
+        && frame.hasIdr === true
+        && frame.hasSps === true
+        && frame.hasPps === true
+        && frame.nalOrderValid === true
+        && optionalFinite(frame.byteLength) > 0,
+      `A received Annex-B H.264 SPS -> PPS -> IDR access unit must prove ${phase}.`);
+    add(
+      `hub-observed-transport-${phase}`,
+      !!frame && observed.path === expectedPath,
+      `Hub ingress must observe ${phase} as ${observed.label}.`);
+    const phaseLatencyMs = optionalFinite(frame?.phaseLatencyMs);
+    add(
+      `phase-latency-${phase}`,
+      phaseLatencyMs !== null
+        && phaseLatencyMs >= 0
+        && phaseLatencyMs <= MAX_PHASE_LATENCY_MS,
+      `${phaseLatencyMs === null ? 'unknown' : Math.round(phaseLatencyMs)}ms/15000ms`);
+  }
+
+  const receivedTimes = observedFrames.map(frame => Date.parse(frame?.receivedAt || ''));
+  add(
+    'ordered-path-transition',
+    observedFrames.every(Boolean)
+      && receivedTimes.every(Number.isFinite)
+      && receivedTimes.every((time, index) => index === 0 || time > receivedTimes[index - 1]),
+    'Frames must arrive in strict Direct, UDP P2P, encrypted relay, Direct order.');
+
+  const frameSequences = observedFrames.map(frame => optionalFinite(frame?.frameSeq));
+  add(
+    'strict-frame-sequence',
+    frameSequences.every(value => Number.isSafeInteger(value) && value > 0)
+      && frameSequences.every((value, index) => index === 0 || value > frameSequences[index - 1]),
+    frameSequences.map(value => value ?? '?').join(' -> '));
+
+  const switchCounts = observedFrames.map(frame => optionalFinite(frame?.switchCount));
+  add(
+    'transport-switch-count',
+    switchCounts.every(value => Number.isSafeInteger(value) && value >= 0)
+      && switchCounts.every((value, index) => index === 0 || value > switchCounts[index - 1]),
+    switchCounts.map(value => value ?? '?').join(' -> '));
+
+  const network = snapshot?.network || {};
+  add(
+    'distinct-public-ipv4-egress',
+    network.evidence === 'authenticated-udp-endpoint-rendezvous-observed'
+      && network.endpointAuthenticated === true
+      && network.clientAddressPublic === true
+      && network.hubAddressPublic === true
+      && network.differentPublicEgress === true
+      && network.hubEndpointSource === 'trusted-rendezvous-observation',
+    'Authenticated UDP and trusted-rendezvous-observed distinct public IPv4 egress values are required; this does not prove distinct NAT devices.');
+  add(
+    'fresh-hub-public-ipv4-observation',
+    timestampWithin(
+      network.hubAddressObservedAt,
+      snapshot?.startedAt,
+      MAX_HUB_ADDRESS_OBSERVATION_SKEW_MS),
+    'The Hub public IPv4 value must be freshly observed within 60 seconds of diagnostic start.');
+  add(
+    'fresh-client-udp-observation',
+    timestampWithin(
+      network.observedAt,
+      snapshot?.startedAt,
+      MAX_HUB_ADDRESS_OBSERVATION_SKEW_MS),
+    'The authenticated Client UDP endpoint must be observed within 60 seconds of diagnostic start.');
+
+  const cleanup = Array.isArray(snapshot?.cleanup) ? snapshot.cleanup : [];
+  add(
+    'lease-cleaned',
+    snapshot?.state === 'completed'
+      && cleanup.some(entry => entry?.state === 'agent-released'),
+    'The exact-owner diagnostic lease must be released by the Agent.');
+
+  const baseline = snapshot?.baseline || {};
+  const agentTelemetryAvailable = baseline.agentQueueTelemetryAvailable === true
+    && optionalFinite(baseline.agentQueueDropped) !== null
+    && observedFrames.every(frame =>
+      frame?.agentQueueTelemetryAvailable === true
+      && optionalFinite(frame.agentQueueDepth) !== null
+      && optionalFinite(frame.agentQueueDropped) !== null);
+  const hubTelemetryAvailable = baseline.hubIngressTelemetryAvailable === true
+    && optionalFinite(baseline.hubIngressDropped) !== null
+    && !!baseline.hubIngressCounterEpochHash
+    && !!baseline.udpCounterEpochHash
+    && observedFrames.every(frame =>
+      frame?.hubIngressTelemetryAvailable === true
+      && optionalFinite(frame.hubIngressDropped) !== null
+      && !!frame.hubIngressCounterEpochHash);
+  const p2pFrame = observedFrames[REQUIRED_PHASES.indexOf('p2p')];
+  const udpTelemetryAvailable = baseline.udpTelemetryAvailable === true
+    && optionalFinite(baseline.udpIncompleteFrames) !== null
+    && p2pFrame?.udpTelemetryAvailable === true
+    && optionalFinite(p2pFrame?.udpIncompleteFrames) !== null
+    && p2pFrame?.hubIngressCounterEpochHash === baseline.udpCounterEpochHash;
+  add(
+    'agent-queue-telemetry',
+    agentTelemetryAvailable,
+    agentTelemetryAvailable ? 'baseline and all four phases' : 'unknown or incomplete');
+  add(
+    'hub-ingress-telemetry',
+    hubTelemetryAvailable,
+    hubTelemetryAvailable ? 'baseline and all four phases' : 'unknown or incomplete');
+  add(
+    'udp-reassembly-telemetry',
+    udpTelemetryAvailable,
+    udpTelemetryAvailable ? 'baseline and P2P phase' : 'unknown or incomplete');
+
+  const agentDropped = cumulativeDelta([
+    baseline.agentQueueDropped,
+    ...observedFrames.map(frame => frame?.agentQueueDropped)
+  ]);
+  const hubDropped = scopedCounterDelta([
+    {
+      scope: baseline.hubIngressCounterEpochHash,
+      value: baseline.hubIngressDropped
+    },
+    {
+      scope: baseline.udpCounterEpochHash,
+      value: baseline.udpIncompleteFrames
+    }
+  ], observedFrames.map(frame => ({
+    scope: frame?.hubIngressCounterEpochHash,
+    value: frame?.hubIngressDropped
+  })));
+  const udpIncomplete = cumulativeDelta([
+    baseline.udpIncompleteFrames,
+    p2pFrame?.udpIncompleteFrames
+  ]);
+  const maxAgentQueueDepth = agentTelemetryAvailable
+    ? Math.max(...observedFrames.map(frame => Number(frame.agentQueueDepth)))
+    : null;
+  const boundedQueues = agentTelemetryAvailable
+    && hubTelemetryAvailable
+    && udpTelemetryAvailable
+    && agentDropped.valid
+    && hubDropped.valid
+    && udpIncomplete.valid
+    && maxAgentQueueDepth <= MAX_AGENT_QUEUE_DEPTH
+    && agentDropped.delta <= MAX_AGENT_QUEUE_DROPPED_DELTA
+    && hubDropped.delta <= MAX_HUB_INGRESS_DROPPED_DELTA
+    && udpIncomplete.delta <= MAX_UDP_INCOMPLETE_DELTA;
+  add(
+    'bounded-frame-queues',
+    boundedQueues,
+    `queueDepth=${maxAgentQueueDepth ?? 'unknown'}, `
+      + `agentDroppedDelta=${agentDropped.delta ?? 'unknown'}, `
+      + `hubDroppedDelta=${hubDropped.delta ?? 'unknown'}, `
+      + `udpIncompleteDelta=${udpIncomplete.delta ?? 'unknown'}`);
+
+  const failed = checks.filter(check => !check.ok);
+  const phaseLatencies = observedFrames.map(frame => optionalFinite(frame?.phaseLatencyMs));
+  return {
+    status: failed.length === 0 ? 'passed' : 'blocked',
+    summary: failed.length === 0
+      ? 'Direct, UDP P2P, encrypted relay, and Direct recovery were proven by independent received H.264 access units.'
+      : `Physical transport proof is incomplete (${failed.map(check => check.id).join(', ')}).`,
+    checks,
+    metrics: {
+      maxPhaseLatencyMs: phaseLatencies.every(value => value !== null)
+        ? Math.max(...phaseLatencies)
+        : null,
+      maxAgentQueueDepth,
+      agentQueueDroppedDelta: agentDropped.delta,
+      hubIngressDroppedDelta: hubDropped.delta,
+      udpIncompleteFramesDelta: udpIncomplete.delta,
+      observedTransports: observedFrames.map(frame => hubObservedTransport(frame).label)
+    }
+  };
+}
+
+export function buildTransportPhysicalReport(snapshot, context = {}) {
+  const classified = classifyTransportPhysicalSnapshot(snapshot);
+  const report = redactTransportPhysicalReport({
+    schema: 'livedesk.transport-physical.v1',
+    generatedAt: new Date().toISOString(),
+    hubUrl: context.hubUrl,
+    selectedDeviceId: context.deviceId,
+    result: classified,
+    transport: snapshot
+  });
+  const leaks = findTransportPhysicalReportLeaks(report);
+  if (leaks.length > 0) {
+    throw new Error(`transport-physical-report-redaction-failed:${leaks.join(',')}`);
+  }
+  return report;
+}
+
+export {
+  MAX_HUB_ADDRESS_OBSERVATION_SKEW_MS,
+  MAX_PHASE_LATENCY_MS,
+  REQUIRED_PHASES
+};