@esp-vision/device-core 0.1.0 → 0.2.0

package/tests/test-device-v4-alignment.mjs

@@ -0,0 +1,189 @@
+// SPDX-License-Identifier: Apache-2.0
+import assert from 'node:assert/strict'
+import test from 'node:test'
+import { Buffer } from 'node:buffer'
+import { DeviceSession } from '../src/device_session.js'
+import { EvMuxParser, makeEvMuxFrame } from '../src/evmux.js'
+import { EvRepl, evReplExecInputBytes } from '../src/evrepl.js'
+
+function fixture(options = {}) {
+  return new DeviceSession({ transport: { async writeBytes() {} }, EvMuxParser, makeEvMuxFrame, EvRepl, ...options })
+}
+
+test('Unicode Python is ASCII on the wire and length preflight includes escapes', async () => {
+  let command
+  const repl = new EvRepl({ writeEvmux() {} })
+  repl._execLine = async line => { command = line; return '' }
+  const source = "print('你好😀', '\\u4f60')\n\tpass"
+  await repl.execPy(source)
+  assert.match(command, /\\u4f60\\u597d\\U0001f600/)
+  assert.match(command, /\\\\u4f60/)
+  assert.ok([...command].every(char => char.charCodeAt(0) < 128))
+  assert.equal(evReplExecInputBytes(source), Buffer.byteLength(command + '\r\n'))
+})
+
+test('64 KiB reads use bounded output and serialize with other REPL work', async () => {
+  const data = Uint8Array.from({ length: 65536 }, (_, i) => i % 256)
+  const repl = new EvRepl({ writeEvmux() {} })
+  const counts = []
+  repl._execPy = async source => {
+    const offset = Number(/f.seek\((\d+)\)/.exec(source)[1])
+    const count = Number(/f.read\((\d+)\)/.exec(source)[1])
+    counts.push(count)
+    await Promise.resolve()
+    const chunk = data.slice(offset, offset + count)
+    return `__EVREAD_OK__${data.length}:${chunk.length}:` + Buffer.from(chunk).toString('hex') + '\n'
+  }
+  const reading = repl.readFile('/data.bin', { maxBytes: data.length })
+  const after = repl.enqueue(() => { assert.equal(counts.length, 64) })
+  assert.deepEqual(await reading, data)
+  await after
+  assert.ok(counts.every(count => count <= 1024))
+  await assert.rejects(repl.readFile('/data.bin', { maxBytes: 1023 }), error => error.code === 'DEVICE_FILE_TOO_LARGE')
+})
+
+test('file errors, cancellation and a total deadline stop chunk reads', async () => {
+  const repl = new EvRepl({ writeEvmux() {} })
+  repl._execPy = async () => '__EVREAD_ERROR__OSError(2)\n'
+  await assert.rejects(repl.readFile('/missing'), /OSError\(2\)/)
+  await assert.rejects(repl.readFile('/file', { timeout: 0 }), /read timeout/)
+  const controller = new AbortController()
+  let chunks = 0
+  repl._execPy = async () => {
+    chunks += 1
+    controller.abort(new Error('cancelled'))
+    return '__EVREAD_OK__2048:1024:' + '00'.repeat(1024) + '\n'
+  }
+  await assert.rejects(repl.readFile('/file', { signal: controller.signal }), /cancelled/)
+  assert.equal(chunks, 1)
+})
+
+test('startup drain parses split frames without adopting old sessions', async () => {
+  let session
+  const frame = makeEvMuxFrame({ channel: 'user.rpc', type: 'event', method: 'hello', payload: '{}' })
+  session = fixture({ sleep: async () => {
+    session.feedBytes(frame.slice(0, 20))
+    session.feedBytes(frame.slice(20))
+  } })
+  session.rpc = async () => { throw new Error('first request reached') }
+  await assert.rejects(session.negotiate({ drainMs: 300 }), /first request reached/)
+  assert.equal(session.parser.getDiagnostics().droppedFrames, 1)
+  assert.equal(session.parser.getDiagnostics().bufferedBytes, 0)
+  assert.equal(session.sessionId, null)
+  session.close()
+})
+
+test('unfinished startup frames close the transport before any request', async () => {
+  let session, writes = 0, disconnects = 0
+  session = fixture({
+    transport: { async writeBytes() { writes += 1 }, async disconnect() { disconnects += 1 } },
+    sleep: async () => { session.feedBytes(new TextEncoder().encode('\x1eEVMUX/1 h=100 p=0 c=00000000\r\n{')) },
+  })
+  await assert.rejects(session.negotiate({ drainMs: 300 }), error => error.code === 'SERIAL_STARTUP_INCOMPLETE_FRAME')
+  assert.equal(writes, 0)
+  assert.equal(disconnects, 1)
+  assert.equal(session.state, 'disconnected')
+})
+
+test('plain console tails do not fail drain and TCP does not wait for drain', async () => {
+  for (const role of ['usj', 'tcp']) {
+    let sleeps = 0, session
+    session = fixture({ sleep: async () => {
+      sleeps += 1
+      session.feedBytes(new TextEncoder().encode('console\x1eordinary text'))
+    } })
+    if (role === 'tcp') session.feedBytes(new TextEncoder().encode('\x1eEVMUX/1 h='))
+    session.rpc = async () => { throw new Error('first request reached') }
+    await assert.rejects(session.negotiate({ role }), /first request reached/)
+    assert.equal(sleeps, role === 'tcp' ? 0 : 1)
+    session.close()
+    session.parser.reset()
+  }
+})
+
+test('unscoped authorization errors resolve only the matching RPC without adopting state', async () => {
+  const session = fixture()
+  session.sessionId = 'a'.repeat(32)
+  session.vmEpoch = 3
+  const pending = { channel: 'debug.rpc', method: 'debug.info', sessionId: session.sessionId, vmEpoch: 3, vmRequest: true }
+  session.pendingRpc.set(7, pending)
+  const metadata = { seq: 7, channel: 'debug.rpc', method: 'debug.info', type: 'rsp' }
+  for (const code of ['NOT_OWNER', 'SESSION_EXPIRED', 'SESSION_REQUIRED']) {
+    assert.equal(session._matchesPendingResponse(metadata, { ok: false, error: { code } }), true)
+  }
+  assert.equal(session._matchesPendingResponse(metadata, { ok: true }), false)
+  assert.equal(session._matchesPendingResponse(metadata, { ok: false, error: { code: 'WRITE_FAILED' } }), false)
+  assert.equal(session._matchesPendingResponse({ ...metadata, seq: 8 }, { ok: false, error: { code: 'NOT_OWNER' } }), false)
+  assert.equal(session.sessionId, 'a'.repeat(32))
+  assert.equal(session.vmEpoch, 3)
+  session.pendingRpc.clear()
+  session.close()
+})
+
+test('dropped stdout cannot masquerade as EOF, and changing files fail explicitly', async () => {
+  const repl = new EvRepl({ writeEvmux() {} })
+  repl._execPy = async () => '__EVREAD_OK__2048:1024:' + '00'.repeat(768) + '\n'
+  await assert.rejects(repl.readFile('/file'), error => error.code === 'DEVICE_FILE_READ_INCOMPLETE')
+  repl._execPy = async () => '__EVREAD_OK__2048:0:\n'
+  await assert.rejects(repl.readFile('/file'), error => error.code === 'DEVICE_FILE_READ_INCOMPLETE')
+  let index = 0
+  repl._execPy = async () => `__EVREAD_OK__${++index === 1 ? 2048 : 2049}:1024:` + '00'.repeat(1024) + '\n'
+  await assert.rejects(repl.readFile('/file'), error => error.code === 'DEVICE_FILE_CHANGED')
+})
+
+
+test('post-acquisition capabilities accepts a response beyond the old four-second deadline', async t => {
+  t.mock.timers.enable({ apis: ['setTimeout'] })
+  let session, waitingForCapabilities = false
+  const id = 'a'.repeat(32)
+  const caps = {
+    ok: true, protocol: { evMuxVersion: 4 },
+    features: ['capabilities', 'route.changed', 'framed.repl', 'session.firstCome', 'session.keepalive'],
+    channels: ['user.rpc', 'debug.rpc', 'repl.stdin', 'repl.stdout', 'repl.stderr', 'repl.signal', 'log.idf', 'preview.frame'],
+    limits: { metadataMax: 384, rxPayloadMax: 2048, replInputMax: 511, vmPendingMax: 1, txLargePayloadMax: 262144, txFrameTimeoutMs: 1500, txQueueTimeoutMs: 2000 },
+    session: { policy: 'firstCome', leaseMs: 15000, keepaliveMs: 5000 },
+  }
+  const reader = new EvMuxParser({ filterFrame: (m, p) => {
+    const request = JSON.parse(new TextDecoder().decode(p))
+    const acquire = m.method === 'hello' && request.acquire
+    const response = m.method === 'capabilities' ? caps : acquire
+      ? { ok: true, evMuxVersion: 4, session: { id, vmEpoch: 0, leaseMs: 15000, keepaliveMs: 5000 }, vmReady: false }
+      : { ok: true, evMuxVersion: 4, session: null }
+    const reply = () => session.feedBytes(makeEvMuxFrame({
+      channel: m.channel, type: 'rsp', method: m.method, seq: m.seq,
+      ...(acquire ? { sessionId: id, vmEpoch: 0 } : {}), payload: JSON.stringify(response),
+    }))
+    if (m.method === 'capabilities') {
+      waitingForCapabilities = true
+      setTimeout(reply, 4500)
+    } else reply()
+    return false
+  } })
+  session = fixture({ transport: { async writeBytes(bytes) { reader.feedBytes(bytes) } } })
+  t.after(() => session.close())
+  const negotiated = session.negotiate({ role: 'tcp', probeRepl: false })
+  for (let i = 0; i < 50 && !waitingForCapabilities; i++) await Promise.resolve()
+  assert.equal(waitingForCapabilities, true)
+  for (let i = 0; i < 10; i++) await Promise.resolve()
+  t.mock.timers.tick(4500)
+  assert.equal((await negotiated).capabilities.protocol.evMuxVersion, 4)
+  assert.equal(session.sessionId, id)
+})
+
+
+test('a TCP frame survives a three-second receive gap and incomplete frames still expire', t => {
+  t.mock.timers.enable({ apis: ['setTimeout', 'Date'] })
+  let response
+  const parser = new EvMuxParser({ rpc: (metadata, payload) => { response = payload } })
+  const frame = makeEvMuxFrame({ sid: 'user', channel: 'user.rpc', type: 'rsp', method: 'hello', seq: 1, payload: '{"ok":true}' })
+  parser.feedBytes(frame.slice(0, 80))
+  t.mock.timers.tick(3500)
+  assert.equal(parser.getDiagnostics().droppedFrames, 0)
+  parser.feedBytes(frame.slice(80))
+  assert.equal(response.ok, true)
+  parser.feedBytes(frame.slice(0, 80))
+  t.mock.timers.tick(12000)
+  assert.equal(parser.getDiagnostics().droppedFrames, 1)
+  assert.equal(parser.getDiagnostics().bufferedBytes, 0)
+  parser.reset()
+})

package/tests/test-file-binary.mjs

@@ -0,0 +1,112 @@
+// SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+// SPDX-License-Identifier: Apache-2.0
+import assert from 'node:assert/strict'
+import { test } from 'node:test'
+import { DeviceSession } from '../src/device_session.js'
+import { EvMuxParser, makeEvMuxFrame } from '../src/evmux.js'
+import { EvRepl } from '../src/evrepl.js'
+
+function fixture(options = {}) {
+  const requests = [], chunks = []; let session, began, finished
+  let token
+  const peer = new EvMuxParser({ filterFrame(metadata, bytes) {
+    const payload = metadata.encoding === 'binary' ? bytes.slice() : JSON.parse(new TextDecoder().decode(bytes))
+    requests.push({ metadata, payload })
+    let reply = { ok: true }
+    if (payload instanceof Uint8Array) {
+      assert.equal(metadata.method, 'file.write'); assert.equal(metadata.encoding, 'binary')
+      assert.equal(metadata.vmEpoch, 7); assert.equal(metadata.sessionId, 'a'.repeat(32))
+      assert.equal(Buffer.from(payload.slice(0, 16)).toString('hex'), token)
+      const offset = new DataView(payload.buffer).getUint32(16, true)
+      assert.equal(offset, chunks.reduce((sum, chunk) => sum + chunk.length, 0))
+      chunks.push(payload.slice(20)); reply.writtenBytes = offset + payload.length - 20
+      if (options.badAck) reply.writtenBytes--
+      if (options.abort) options.abort.abort()
+    } else if (payload.action === 'begin') {
+      began = payload; token = payload.uploadId; reply.uploadId = token; reply.chunkBytes = 16384
+      if (options.abortBegin) options.abortBegin.abort()
+      if (options.failBegin) { options.failBegin = false; throw new Error('begin response lost') }
+    } else if (payload.action === 'commit') {
+      finished = true; reply.bytes = chunks.reduce((sum, chunk) => sum + chunk.length, 0); reply.complete = true
+      if (options.badCommit) reply.bytes++
+      if (options.failCommit) reply = { ok: false, error: { code: 'HASH_MISMATCH' } }
+    }
+    session.feedBytes(makeEvMuxFrame({ channel: 'user.rpc', type: 'rsp', method: metadata.method, seq: metadata.seq,
+      sessionId: 'a'.repeat(32), vmEpoch: 7, payload: JSON.stringify(reply) }))
+    return false
+  } })
+  session = new DeviceSession({ transport: { async writeBytes(bytes) { peer.feedBytes(bytes) } }, EvMuxParser, makeEvMuxFrame, EvRepl })
+  Object.assign(session, { state: 'ready', sessionId: 'a'.repeat(32), vmEpoch: 7, vmReady: true,
+    capabilities: { features: ['file.write.binary', 'script.run'] } })
+  session.limits.fileWriteChunkMax = 16384
+  return { session, requests, chunks, get began() { return began }, get finished() { return finished } }
+}
+for (const size of [0, 1, 4096, 16384, 16385, 2 * 1024 * 1024]) {
+  test(`binary upload ${size} bytes is bounded, exact, hashed and committed`, async () => {
+    const f = fixture(), data = Uint8Array.from({ length: size }, (_, i) => i & 255), progress = []
+    try {
+      const result = await f.session.writeFile('/model.bin', data, { encoding: 'binary', onProgress: value => progress.push(value.writtenBytes) })
+      assert.equal(result.complete, true); assert.equal(result.bytes, size)
+      assert.deepEqual(Buffer.concat(f.chunks), Buffer.from(data)); assert.equal(f.finished, true)
+      assert.equal(f.began.sha256, Buffer.from(await crypto.subtle.digest('SHA-256', data)).toString('hex'))
+      assert.ok(f.chunks.every(chunk => chunk.length <= 16384)); assert.equal(f.chunks.length, Math.ceil(size / 16384))
+      assert.equal(progress.at(-1), size)
+      assert.ok(!f.requests.some(request => request.metadata.method === 'script.write'))
+    } finally { f.session.close() }
+  })
+}
+test('Python upload uses the same byte engine and requests execution only after commit', async () => {
+  const f = fixture()
+  try {
+    await f.session.writeScript('/script.py', "print('中文')", { runAfterWrite: true })
+    assert.deepEqual(Buffer.concat(f.chunks), Buffer.from("print('中文')"))
+    assert.equal(f.requests.at(-1).metadata.method, 'script.run')
+    assert.equal(f.requests.at(-2).payload.action, 'commit')
+  } finally { f.session.close() }
+})
+for (const setting of ['badAck', 'badCommit', 'failCommit']) {
+  test(`${setting} triggers abort cleanup without publishing success`, async () => {
+    const f = fixture({ [setting]: true })
+    try {
+      await assert.rejects(f.session.writeFile('/x.bin', new Uint8Array(100)))
+      assert.equal(f.requests.at(-1).payload.action, 'abort')
+    } finally { f.session.close() }
+  })
+}
+test('cancellation after begin still sends an independent abort', async () => {
+  const controller = new AbortController(), f = fixture({ abort: controller })
+  try {
+    await assert.rejects(f.session.writeFile('/x.bin', new Uint8Array(32768), { signal: controller.signal }), { name: 'AbortError' })
+    assert.equal(f.requests.at(-1).payload.action, 'abort')
+  } finally { f.session.close() }
+})
+test('missing binary capability rejects without falling back to script.write', async () => {
+  const f = fixture(); f.session.capabilities.features = ['script.write']
+  try { await assert.rejects(f.session.writeFile('/x.bin', new Uint8Array(10)), { code: 'UNSUPPORTED_OPERATION' }); assert.equal(f.requests.length, 0) }
+  finally { f.session.close() }
+})
+test('corrupted binary frames fail CRC before dispatch', () => {
+  let calls = 0
+  const parser = new EvMuxParser({ filterFrame() { calls++; return false } })
+  const bytes = makeEvMuxFrame({ channel: 'user.rpc', type: 'req', method: 'file.write', encoding: 'binary', payload: new Uint8Array([0, 1, 0x1e, 0x1f, 255]) })
+  parser.feedBytes(bytes); assert.equal(calls, 1)
+  bytes[bytes.length - 2] ^= 1; parser.feedBytes(bytes); assert.equal(calls, 1)
+})
+
+test('cancellation during begin still aborts the client-known upload ID', async () => {
+  const controller = new AbortController(), f = fixture({ abortBegin: controller })
+  try {
+    await assert.rejects(f.session.writeFile('/x.bin', new Uint8Array(100), { signal: controller.signal }), { name: 'AbortError' })
+    assert.equal(f.requests.at(-1).payload.action, 'abort')
+    assert.equal(f.requests.at(-1).payload.uploadId, f.began.uploadId)
+    assert.equal(f.chunks.length, 0)
+  } finally { f.session.close() }
+})
+test('a lost begin response still allows abort without knowing a server-generated ID', async () => {
+  const f = fixture({ failBegin: true })
+  try {
+    await assert.rejects(f.session.writeFile('/x.bin', new Uint8Array(100)), /begin response lost/)
+    assert.equal(f.requests.at(-1).payload.action, 'abort')
+    assert.equal(f.requests.at(-1).payload.uploadId, f.began.uploadId)
+  } finally { f.session.close() }
+})

package/tests/test-firmware-flash.mjs

@@ -0,0 +1,89 @@
+import assert from 'node:assert/strict'
+import { test } from 'node:test'
+import { FirmwareFlashSession, firmwareSha256, validateFirmwareImage } from '../src/firmware_flash.js'
+async function fixture() {
+  const bytes = new Uint8Array([0xe9, 1, 2, 3]), table = new Uint8Array([4, 5, 6]), calls = []
+  const image = { evMuxVersion: 4, chipFamily: 0x3280, chipRevision: 302, offset: 0x10000, bytes: 4, partitionSize: 0x700000, sha256: await firmwareSha256(bytes), partitionTable: { offset: 0x8000, bytes: 3, sha256: await firmwareSha256(table) } }
+  const stub = { async readFlash(offset) { calls.push(['read', offset]); return offset === 0x8000 ? table : bytes }, async readRegister() { return 0x1dfbc7f8 }, async writeRegister() { throw new Error('unexpected register write') }, async flashData(_data, progress, offset, compress) { calls.push(['write', offset, compress]); progress(4, 4) } }
+  const loader = { chipFamily: image.chipFamily, chipRevision: image.chipRevision, async initialize() { calls.push(['initialize']) }, async getSecurityInfo() { return { flags: 0, flashCryptCnt: 0 } }, async runStub(skip) { calls.push(['stub', skip]); return stub }, async readRegister() { return 0x1dfbc7f8 }, async writeRegister() { throw new Error('unexpected register write') }, async hardReset() { calls.push(['reset']) }, async disconnect() { calls.push(['close']) } }
+  return { bytes, table, image, calls, loader, stub, session: new FirmwareFlashSession(loader, image) }
+}
+test('only exact approved v4 images pass before touching the ROM loader', async () => {
+  const f = await fixture()
+  await assert.rejects(validateFirmwareImage({ ...f.image, evMuxVersion: 3 }, f.bytes), /v4/)
+  await assert.rejects(f.session.connect(new Uint8Array([0xe9, 1, 2, 0])), /SHA-256/)
+  assert.deepEqual(f.calls, [['close']])
+})
+test('wrong chip/revision and partition layout fail before any flash write', async () => {
+  for (const change of ['revision', 'partition']) {
+    const f = await fixture()
+    if (change === 'revision') f.loader.chipRevision = 301
+    else f.image.partitionTable.sha256 = '0'.repeat(64)
+    await assert.rejects(f.session.connect(f.bytes), change === 'revision' ? /revision/ : /Partition layout/)
+    assert.ok(!f.calls.some(([operation]) => operation === 'write'))
+    assert.equal(f.calls.at(-1)[0], 'close')
+  }
+})
+test('application-only write is read back in full before reset, with port cleanup', async () => {
+  const f = await fixture()
+  await f.session.connect(f.bytes)
+  await f.session.flash(f.bytes)
+  assert.deepEqual(f.calls, [['initialize'], ['stub', true], ['read', 0x8000], ['write', 0x10000, false], ['read', 0x10000], ['reset'], ['close']])
+})
+test('corrupt readback never reports success or resets into unverified firmware', async () => {
+  const f = await fixture()
+  await f.session.connect(f.bytes)
+  f.stub.readFlash = async () => new Uint8Array([9, 9, 9, 9])
+  await assert.rejects(f.session.flash(f.bytes), /verification failed/)
+  assert.ok(!f.calls.some(([operation]) => operation === 'reset'))
+  assert.equal(f.calls.at(-1)[0], 'close')
+})
+test('reset failure preserves verified result and asks for manual reset', async () => {
+  const f = await fixture(), messages = []
+  await f.session.connect(f.bytes)
+  f.loader.hardReset = async () => { throw new Error('reset unavailable') }
+  await f.session.flash(f.bytes, { onPhase: message => messages.push(message) })
+  assert.match(messages.at(-1), /verified.*RESET/)
+})
+test('full verification uses bounded 1 KiB packets and a single outstanding packet', async () => {
+  const f = await fixture(), bytes = new Uint8Array(65537), reads = []
+  f.image.bytes = bytes.length; f.image.sha256 = await firmwareSha256(bytes)
+  f.stub.readFlash = async (offset, count, _progress, options) => {
+    if (offset === 0x8000) return f.table
+    reads.push({ offset, count, options })
+    return bytes.slice(offset - f.image.offset, offset - f.image.offset + count)
+  }
+  await f.session.connect(bytes)
+  await f.session.flash(bytes)
+  assert.deepEqual(reads.map(item => item.count), [65536, 1])
+  for (const read of reads) assert.deepEqual(read.options, { chunkSize: 65536, blockSize: 1024, maxInFlight: 1 })
+})
+
+test('unsigned application updates refuse secure boot and flash encryption before loading a stub', async () => {
+  for (const security of [{ flags: 1, flashCryptCnt: 0 }, { flags: 0, flashCryptCnt: 1 }]) {
+    const f = await fixture()
+    f.loader.getSecurityInfo = async () => security
+    await assert.rejects(f.session.connect(f.bytes), /signed flashing workflow/)
+    assert.deepEqual(f.calls, [['initialize'], ['close']])
+  }
+})
+
+
+test('P4 software download latch is cleared with a mask and verified before reset', async () => {
+  const f = await fixture(), registers = []; let register = 0x1dfbc7fc
+  f.stub.readRegister = async address => { registers.push(['read', address]); return register }
+  f.stub.writeRegister = async (address, value, mask) => { registers.push(['write', address, value, mask]); register &= ~mask }
+  f.loader.hardReset = async () => { assert.equal(register, 0x1dfbc7f8); f.calls.push(['reset']) }
+  await f.session.connect(f.bytes); await f.session.flash(f.bytes)
+  assert.equal(register, 0x1dfbc7f8)
+  assert.deepEqual(registers, [['read', 0x50110008], ['write', 0x50110008, 0, 4], ['read', 0x50110008]])
+  assert.ok(f.calls.some(([operation]) => operation === 'reset'))
+})
+test('P4 latch clear failure does not reset and retains manual recovery guidance', async () => {
+  const f = await fixture(), messages = []
+  f.stub.readRegister = async () => 0x1dfbc7fc
+  f.stub.writeRegister = async () => {}
+  await f.session.connect(f.bytes); await f.session.flash(f.bytes, { onPhase: message => messages.push(message) })
+  assert.ok(!f.calls.some(([operation]) => operation === 'reset'))
+  assert.match(messages.at(-1), /verified.*RESET/)
+})

package/tests/test-network-discovery.mjs

@@ -0,0 +1,153 @@
+// SPDX-FileCopyrightText: 2026 ESP-VISION-IDE
+// SPDX-License-Identifier: Apache-2.0
+import assert from 'node:assert/strict'
+import { EventEmitter } from 'node:events'
+import { test } from 'node:test'
+import { createNodeDiscovery } from '../src/network_discovery_node.js'
+import { NetworkDiscovery, createBridgeDiscovery } from '../src/network_discovery.js'
+import { EvMuxParser, makeEvMuxFrame } from '../src/evmux.js'
+import { EvRepl } from '../src/evrepl.js'
+import { DeviceSession } from '../src/device_session.js'
+const hostname = 'esp-vision-esp32-s3-eye-a1b2c3-0-9-1'
+const instance = hostname + '._esp-vision._tcp.local'
+const device = { deviceId: 'aabbcca1b2c3', hostname, board: 'ESP32_S3_EYE', firmwareVersion: '0.9.1', evMuxVersion: 4, port: 3232, addresses: ['192.168.2.3'] }
+const records = [
+  { name: '_esp-vision._tcp.local', type: 'PTR', ttl: 60, data: instance },
+  { name: instance, type: 'SRV', ttl: 60, data: { target: hostname + '.local', port: 3232 } },
+  { name: instance, type: 'TXT', ttl: 60, data: Object.entries({ txtvers: '1', id: device.deviceId, hostname, board: device.board, fw: device.firmwareVersion, evmux: '4' }).map(([k, v]) => Buffer.from(`${k}=${v}`)) },
+  { name: hostname + '.local', type: 'A', ttl: 60, data: '192.168.2.3' },
+]
+function provider(t, emit) {
+  const mdns = new EventEmitter()
+  mdns.query = () => { if (!mdns.sent) { mdns.sent = true; emit(mdns) } }
+  mdns.destroy = () => { mdns.closed = true }
+  t.after(() => assert.equal(mdns.closed, true))
+  return createNodeDiscovery({ createMdns: () => mdns })
+}
+
+test('split PTR/SRV/TXT/A records resolve, duplicate packets deduplicate and v4 metadata stays intact', async t => {
+  const discovery = provider(t, mdns => queueMicrotask(() => {
+    mdns.emit('response', { answers: records.slice(0, 2) })
+    mdns.emit('response', { additionals: records.slice(2) })
+    mdns.emit('response', { answers: records })
+  }))
+  const results = await discovery.list({ timeout: 50 })
+  assert.equal(results.length, 1)
+  assert.deepEqual({ ...results[0], expiresAt: undefined, compatible: undefined }, { ...device, expiresAt: undefined, compatible: undefined })
+})
+
+test('goodbye removes a device, and an expired address cannot appear online', async t => {
+  let now = 1000
+  t.mock.method(Date, 'now', () => now)
+  const discovery = provider(t, mdns => queueMicrotask(() => {
+    mdns.emit('response', { answers: records })
+    mdns.emit('response', { answers: [{ ...records[0], ttl: 0 }] })
+    now += 1001
+  }))
+  assert.deepEqual(await discovery.list({ timeout: 50 }), [])
+})
+
+test('cache flush preserves addresses split across a burst of packets', async t => {
+  let now = 1000
+  t.mock.method(Date, 'now', () => now)
+  const discovery = provider(t, mdns => queueMicrotask(() => {
+    mdns.emit('response', { answers: records })
+    now += 500
+    mdns.emit('response', { answers: [{ ...records[3], flush: true, data: '192.168.2.4' }] })
+  }))
+  assert.deepEqual((await discovery.list({ timeout: 50 }))[0].addresses.sort(), ['192.168.2.3', '192.168.2.4'])
+})
+
+test('old addresses expire after the cache-flush grace period', async t => {
+  let now = 1000
+  t.mock.method(Date, 'now', () => now)
+  const discovery = provider(t, mdns => queueMicrotask(() => {
+    mdns.emit('response', { answers: records })
+    now += 2000
+    mdns.emit('response', { answers: [{ ...records[3], flush: true, data: '192.168.2.4' }] })
+    now += 1001
+  }))
+  assert.deepEqual((await discovery.list({ timeout: 50 }))[0].addresses, ['192.168.2.4'])
+})
+
+test('re-announcement rescues a record during the goodbye grace period', async t => {
+  let now = 1000
+  t.mock.method(Date, 'now', () => now)
+  const discovery = provider(t, mdns => queueMicrotask(() => {
+    mdns.emit('response', { answers: records })
+    mdns.emit('response', { answers: [{ ...records[0], ttl: 0 }] })
+    now += 500
+    mdns.emit('response', { answers: [records[0]] })
+    now += 1001
+  }))
+  assert.equal((await discovery.list({ timeout: 50 })).length, 1)
+})
+
+test('expired cache entries cannot block discovery at the record limit', async t => {
+  let now = 1000
+  t.mock.method(Date, 'now', () => now)
+  const discovery = provider(t, mdns => queueMicrotask(() => {
+    for (let start = 0; start < 2048; start += 256) mdns.emit('response', { answers: Array.from({ length: 256 }, (_, i) => ({
+      name: `unrelated-${start + i}.local`, type: 'A', ttl: 1, data: '192.168.2.10',
+    })) })
+    now += 2000
+    mdns.emit('response', { answers: records })
+  }))
+  assert.equal((await discovery.list({ timeout: 50 })).length, 1)
+})
+
+test('cancellation during adapter creation still closes the socket', async () => {
+  const controller = new AbortController()
+  const mdns = new EventEmitter()
+  let closed = false
+  mdns.destroy = () => { closed = true }
+  mdns.query = () => assert.fail('aborted discovery must not query')
+  const discovery = createNodeDiscovery({ createMdns() {
+    controller.abort(new Error('cancel during setup'))
+    return mdns
+  } })
+  await assert.rejects(discovery.list({ signal: controller.signal }), /cancel during setup/)
+  assert.equal(closed, true)
+})
+
+test('SRV targets inconsistent with the advertised hostname are ignored', async t => {
+  const discovery = provider(t, mdns => queueMicrotask(() => mdns.emit('response', { answers: [
+    records[0], { ...records[1], data: { ...records[1].data, target: 'other.local' } }, records[2],
+    { ...records[3], name: 'other.local' },
+  ] })))
+  assert.deepEqual(await discovery.list({ timeout: 50 }), [])
+})
+
+test('cancellation releases mDNS resources and does not resolve a partial device', async t => {
+  const controller = new AbortController()
+  const discovery = provider(t, () => queueMicrotask(() => controller.abort(new Error('cancel discovery'))))
+  await assert.rejects(discovery.list({ timeout: 3000, signal: controller.signal }), /cancel discovery/)
+})
+
+test('unrelated/malformed advertisements and public destinations are ignored', async t => {
+  const discovery = provider(t, mdns => queueMicrotask(() => mdns.emit('response', { answers: [
+    ...records.slice(0, 3), { ...records[3], data: '8.8.8.8' },
+  ] })))
+  assert.deepEqual(await discovery.list({ timeout: 50 }), [])
+})
+
+test('browser bridge URLs stay on the configured origin and reject arbitrary forwarding URLs', async () => {
+  const bridge = 'ws://127.0.0.1:8766/device'
+  const handle = '/device/' + 'a'.repeat(32)
+  const valid = createBridgeDiscovery(bridge, { fetch: async () => ({ ok: true, json: async () => ({ devices: [{ ...device, connectionUrl: handle }] }) }) })
+  assert.equal((await valid.list({ timeout: 50 }))[0].connectionUrl, 'ws://127.0.0.1:8766' + handle)
+  const invalid = createBridgeDiscovery(bridge, { fetch: async () => ({ ok: true, json: async () => ({ devices: [{ ...device, connectionUrl: 'ws://attacker.example' + handle }] }) }) })
+  await assert.rejects(invalid.list({ timeout: 50 }), /Invalid discovered connection URL/)
+  const controller = new AbortController(); controller.abort(new Error('already cancelled'))
+  await assert.rejects(new NetworkDiscovery({ list() { assert.fail('must not browse') } }).list({ signal: controller.signal }), /already cancelled/)
+})
+
+test('a changed IP leading to the wrong device fails before any acquire RPC', async () => {
+  const session = new DeviceSession({ transport: { writeBytes() {} }, EvMuxParser, makeEvMuxFrame, EvRepl })
+  const requests = []
+  session.rpc = async (method, payload) => { requests.push({ method, payload }); return { ...device, deviceId: '000000000000', evMuxVersion: 4 } }
+  await assert.rejects(session.negotiate({ role: 'tcp', expectedDevice: device }), error => error.code === 'DEVICE_IDENTITY_MISMATCH')
+  assert.deepEqual(requests, [{ method: 'hello', payload: {} }])
+  assert.equal(session.sessionId, null)
+  session.close()
+})

package/tests/test-release-verification.mjs

@@ -0,0 +1,58 @@
+// SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+// SPDX-License-Identifier: Apache-2.0
+import assert from 'node:assert/strict'
+import { test } from 'node:test'
+import { verifyPublishedIntegrity } from '../scripts/verify-registry.mjs'
+
+const integrity = 'sha512-test-content'
+const url = 'https://registry.npmjs.org/%40esp-vision%2Fdevice-core/0.2.0'
+const published = value => new Response(JSON.stringify({ dist: { integrity: value } }))
+function fixture(replies) {
+  const calls = [], waits = [], reports = []
+  return { calls, waits, reports, options: {
+    async fetcher(address, options) {
+      calls.push({ address, options })
+      const reply = replies.shift()
+      if (reply instanceof Error) throw reply
+      assert(reply, 'Unexpected verification request')
+      return reply
+    },
+    wait: async milliseconds => { waits.push(milliseconds) },
+    report: message => reports.push(message),
+  } }
+}
+test('new npm version becomes visible after stale 404 metadata; only uncached reads repeat', async () => {
+  const f = fixture([new Response('', { status: 404 }), published(integrity)])
+  await verifyPublishedIntegrity(url, integrity, f.options)
+  assert.equal(f.calls.length, 2); assert.deepEqual(f.waits, [1000])
+  for (const call of f.calls) {
+    assert.equal(call.address, url); assert.equal(call.options.cache, 'no-store')
+    assert.equal(call.options.headers['Cache-Control'], 'no-cache')
+    assert.equal(call.options.method ?? 'GET', 'GET')
+  }
+})
+test('verification retries rate limits, temporary registry errors and network failures', async () => {
+  const f = fixture([new Response('', { status: 429 }), new Response('', { status: 503 }), new TypeError('network unavailable'), published(integrity)])
+  await verifyPublishedIntegrity(url, integrity, f.options)
+  assert.deepEqual(f.waits, [1000, 2000, 4000])
+})
+for (const status of [400, 401, 403]) test(`registry HTTP ${status} fails without retries`, async () => {
+  const f = fixture([new Response('', { status })])
+  await assert.rejects(verifyPublishedIntegrity(url, integrity, f.options), new RegExp(`HTTP ${status}`))
+  assert.equal(f.calls.length, 1); assert.deepEqual(f.waits, [])
+})
+test('published integrity mismatch fails immediately', async () => {
+  const f = fixture([published('sha512-other-content')])
+  await assert.rejects(verifyPublishedIntegrity(url, integrity, f.options), /integrity mismatch/)
+  assert.equal(f.calls.length, 1); assert.deepEqual(f.waits, [])
+})
+test('missing published integrity is not accepted', async () => {
+  const f = fixture([new Response('{}')])
+  await assert.rejects(verifyPublishedIntegrity(url, integrity, f.options), /integrity mismatch/)
+  assert.deepEqual(f.waits, [])
+})
+test('persistent propagation failures stop after six reads with bounded backoff', async () => {
+  const f = fixture(Array.from({ length: 6 }, () => new Response('', { status: 404 })))
+  await assert.rejects(verifyPublishedIntegrity(url, integrity, f.options), /after 6 reads/)
+  assert.equal(f.calls.length, 6); assert.deepEqual(f.waits, [1000, 2000, 4000, 8000, 16000])
+})