@esp-vision/device-core 0.2.0 → 0.4.0

package/tests/test-firmware-install.mjs

@@ -0,0 +1,126 @@
+// SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+// SPDX-License-Identifier: Apache-2.0
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { createDevice } from '../src/index.js'
+import { firmwareSha256 } from '../src/firmware_flash.js'
+import { parseCli, runCli } from '../src/cli.js'
+
+async function fixture() {
+  const data = new Uint8Array(0x11000).fill(0xff), calls = []
+  data.set([0xe9, 1, 2, 3], 0x2000)
+  data.set([0xaa, 0x50, 4, 5], 0x8000)
+  data.set([0xe9, 6, 7, 8], 0x10000)
+  const part = async offset => ({ offset, bytes: 4, sha256: await firmwareSha256(data.subarray(offset, offset + 4)) })
+  const release = { board: 'BOARD', version: 'new', image: {
+    evMuxVersion: 4, chipFamily: 0x3280, chipRevision: 302, ...(await part(0x10000)),
+    partitionSize: 4096, partitionTable: await part(0x8000), url: 'https://example.test/app.bin',
+  }, install: { offset: 0, bytes: data.length, flashSize: 0x1000000, chipRevisionMin: 302, chipRevisionMax: 302,
+    sha256: await firmwareSha256(data), bootloader: await part(0x2000), url: 'https://example.test/full.bin' } }
+  const flash = new Uint8Array(data.length).fill(0xff)
+  const loader = {
+    chipFamily: 0x3280, chipRevision: 302,
+    async initialize() { calls.push('initialize') },
+    async getSecurityInfo() { return { flags: 0, flashCryptCnt: 0 } },
+    async runStub() { calls.push('stub'); return loader },
+    async flashId() { calls.push('capacity'); return 0x1840ef },
+    async flashData(buffer, progress, offset) { calls.push(['write', offset]); flash.set(new Uint8Array(buffer), offset); progress(buffer.byteLength, buffer.byteLength) },
+    async readFlash(offset, count) { calls.push(['read', offset]); return flash.slice(offset, offset + count) },
+    async readRegister() { return 0 },
+    async hardReset() { calls.push('reset') },
+    async disconnect() { calls.push('close') },
+  }
+  const device = createDevice(), request = { mode: 'install', release, board: 'BOARD', data, async openLoader() { calls.push('open'); return loader } }
+  return { data, calls, release, loader, device, request, flash }
+}
+
+test('blank device installs through ROM without an EV-MUX transport or existing partition table', async () => {
+  const f = await fixture(), progress = []
+  const result = await f.device.firmware.update({ ...f.request, onProgress: value => progress.push(value) })
+  assert.equal(result.verified, true); assert.equal(result.reconnected, false)
+  assert.deepEqual(f.flash, f.data)
+  assert.deepEqual(f.calls, ['open', 'initialize', 'stub', 'capacity', ['write', 0], ['read', 0], ['read', 65536], 'reset', 'close'])
+  assert.equal(progress.at(-1), 100)
+})
+
+test('default application update refuses blank layout and never falls back to installing', async () => {
+  const f = await fixture()
+  await assert.rejects(f.device.firmware.update({ ...f.request, mode: undefined, data: f.data.slice(65536, 65540) }), /Partition layout/)
+  assert.ok(!f.calls.some(call => Array.isArray(call) && call[0] === 'write'))
+  assert.ok(!f.calls.includes('capacity'))
+})
+
+test('complete image is downloaded from install URL with the requested cancellation signal', async () => {
+  const f = await fixture(), controller = new AbortController()
+  await f.device.firmware.update({ ...f.request, data: undefined, signal: controller.signal,
+    async fetch(url, options) { assert.equal(url, f.release.install.url); assert.equal(options.signal, controller.signal); return { ok: true, arrayBuffer: async () => f.data.buffer } },
+  })
+  assert.deepEqual(f.flash, f.data)
+})
+
+test('install selection skips app-only releases and rejects explicit unqualified versions', async () => {
+  const f = await fixture(), appOnly = { ...f.release, version: 'app-only', install: undefined }
+  const request = { mode: 'install', identity: { board: 'BOARD', firmwareVersion: 'unknown' }, catalog: { schemaVersion: 1, releases: [appOnly, f.release] } }
+  const result = await f.device.firmware.check(request)
+  assert.equal(result.release.version, 'new'); assert.equal(result.releases.length, 2)
+  await assert.rejects(f.device.firmware.check({ ...request, version: 'app-only' }), { code: 'FIRMWARE_INSTALL_UNAVAILABLE' })
+  const updates = await f.device.firmware.check({ ...request, mode: 'update' })
+  assert.equal(updates.release.version, 'app-only')
+  assert.deepEqual(f.calls, [])
+})
+
+for (const change of ['hash', 'bootloader', 'table', 'application', 'overlap', 'bounds', 'revision-range', 'missing-metadata', 'mode', 'board']) {
+  test(`invalid ${change} rejects installation before opening or releasing a port`, async () => {
+    const f = await fixture()
+    if (change === 'hash') f.data[1] = 0
+    if (change === 'bootloader') f.release.install.bootloader.sha256 = '0'.repeat(64)
+    if (change === 'table') f.release.image.partitionTable.sha256 = '0'.repeat(64)
+    if (change === 'application') f.release.image.sha256 = '0'.repeat(64)
+    if (change === 'overlap') f.release.install.bootloader.bytes = 0x8000
+    if (change === 'bounds') f.release.install.offset = 0x1000
+    if (change === 'revision-range') f.release.install.chipRevisionMin = 301
+    if (change === 'missing-metadata') delete f.release.install
+    if (change === 'mode') f.request.mode = 'auto'
+    if (change === 'board') f.request.board = 'WRONG'
+    await assert.rejects(f.device.firmware.update(f.request))
+    assert.deepEqual(f.calls, [])
+  })
+}
+
+for (const change of ['wrong-chip', 'wrong-revision', 'secure-boot', 'encryption', 'small-flash', 'unknown-flash', 'missing-capacity']) {
+  test(`physical ${change} refuses installation before any write`, async () => {
+    const f = await fixture()
+    if (change === 'wrong-chip') f.loader.chipFamily = 0x3253
+    if (change === 'wrong-revision') f.loader.chipRevision = 301
+    if (change === 'secure-boot') f.loader.getSecurityInfo = async () => ({ flags: 1, flashCryptCnt: 0 })
+    if (change === 'encryption') f.loader.getSecurityInfo = async () => ({ flags: 0, flashCryptCnt: 1 })
+    if (change === 'small-flash') f.loader.flashId = async () => 0x1740ef
+    if (change === 'unknown-flash') f.loader.flashId = async () => 0xffffff
+    if (change === 'missing-capacity') delete f.loader.flashId
+    await assert.rejects(f.device.firmware.update(f.request))
+    assert.ok(!f.calls.some(call => Array.isArray(call) && call[0] === 'write'))
+    assert.equal(f.calls.at(-1), 'close')
+  })
+}
+
+test('installation with damaged readback does not reset or report success', async () => {
+  const f = await fixture(); f.loader.readFlash = async (_offset, count) => new Uint8Array(count)
+  await assert.rejects(f.device.firmware.update(f.request), /verification failed/)
+  assert.ok(!f.calls.includes('reset')); assert.equal(f.calls.at(-1), 'close')
+})
+
+test('CLI install uses ROM directly and passes mode through both check and update', async () => {
+  const f = await fixture(), checked = []
+  const options = parseCli(['firmware', 'update', '--mode', 'install', '--board', 'BOARD', '--port', '/dev/ttyACM0', '--version', 'new'])
+  const result = await runCli(options, {
+    transportFor: () => { throw new Error('No application transport should be acquired') },
+    async readFile() { throw new Error('No user catalog required') },
+    createDevice: () => ({ firmware: {
+      async check(request) { checked.push(request.mode); return { release: f.release } },
+      async update(request) { assert.equal(request.mode, 'install'); return { verified: true } },
+    }, async disconnect() {} }),
+  })
+  assert.equal(result.verified, true); assert.deepEqual(checked, ['install'])
+  assert.throws(() => parseCli(['firmware', 'update', '--mode', 'install', '--port', 'COM3', '--version', 'new']), /explicit --board/)
+  assert.throws(() => parseCli(['firmware', 'update', '--mode', 'install', '--tcp', 'host', '--board', 'BOARD', '--version', 'new']), /local --port/)
+})

package/tests/test-firmware-source.mjs

@@ -0,0 +1,143 @@
+// SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+// SPDX-License-Identifier: Apache-2.0
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { createDevice } from '../src/index.js'
+import { firmwareSha256 } from '../src/firmware.js'
+
+async function fixture() {
+  const full = new Uint8Array(0x11000).fill(0xff), appOffset = 0x10000, appLength = 4, calls = []
+  full.set([0xe9, 1, 2, 3], 0x2000); full.set([0xaa, 0x50, 4, 5], 0x8000); full.set([0xe9, 6, 7, 8], appOffset)
+  const segment = async offset => ({ offset, bytes: 4, sha256: await firmwareSha256(full.subarray(offset, offset + 4)) })
+  const source = { url: 'https://example.test/full.bin', bytes: full.length, sha256: await firmwareSha256(full), offset: appOffset }
+  const release = { board: 'BOARD', version: 'new', image: {
+    evMuxVersion: 4, chipFamily: 0x3280, chipRevision: 302, ...(await segment(appOffset)), partitionSize: 4096,
+    partitionTable: await segment(0x8000), url: source.url, source,
+  }, install: { url: source.url, offset: 0, bytes: full.length, sha256: source.sha256, flashSize: 0x1000000,
+    chipRevisionMin: 302, chipRevisionMax: 302, bootloader: await segment(0x2000) } }
+  const flash = new Uint8Array(full.length).fill(0x5a)
+  flash.set(full.subarray(0x8000, 0x8004), 0x8000)
+  const before = flash.slice()
+  const loader = {
+    chipFamily: 0x3280, chipRevision: 302,
+    async initialize() { calls.push('initialize') },
+    async getSecurityInfo() { return { flags: 0, flashCryptCnt: 0 } },
+    async runStub() { calls.push('stub'); return loader },
+    async flashId() { return 0x1840ef },
+    async flashData(buffer, progress, offset) { calls.push(['write', offset, buffer.byteLength]); flash.set(new Uint8Array(buffer), offset); progress(buffer.byteLength, buffer.byteLength) },
+    async readFlash(offset, bytes) { return flash.slice(offset, offset + bytes) },
+    async readRegister() { return 0 },
+    async hardReset() { calls.push('reset') },
+    async disconnect() { calls.push('close') },
+  }
+  const request = { release, board: 'BOARD', openLoader: async () => { calls.push('open'); return loader }, fetch: async (url, options) => {
+    calls.push(['download', url]); assert.equal(options.redirect, 'error'); assert.equal(options.headers, undefined)
+    return new Response(full)
+  } }
+  return { device: createDevice(), release, request, full, flash, before, loader, calls, appOffset, appLength }
+}
+test('single BIN update verifies the container then writes only the application, preserving all other bytes', async () => {
+  const f = await fixture()
+  const result = await f.device.firmware.update(f.request)
+  assert.equal(result.verified, true)
+  assert.deepEqual(f.calls.filter(call => Array.isArray(call)), [['download', f.release.image.source.url], ['write', f.appOffset, f.appLength]])
+  assert.deepEqual(f.flash.slice(0, f.appOffset), f.before.slice(0, f.appOffset))
+  assert.deepEqual(f.flash.slice(f.appOffset + f.appLength), f.before.slice(f.appOffset + f.appLength))
+  assert.deepEqual(f.flash.slice(f.appOffset, f.appOffset + f.appLength), f.full.slice(f.appOffset, f.appOffset + f.appLength))
+})
+test('provided data means the complete BIN when image.source exists; application bytes alone are rejected', async () => {
+  const f = await fixture()
+  await assert.rejects(f.device.firmware.update({ ...f.request, data: f.full.slice(f.appOffset, f.appOffset + f.appLength) }), /source size/)
+  assert.deepEqual(f.calls, [])
+  assert.equal((await f.device.firmware.update({ ...f.request, data: f.full })).verified, true)
+  assert.ok(!f.calls.some(call => Array.isArray(call) && call[0] === 'download'))
+})
+test('old application-only descriptors still download and verify a raw application BIN', async () => {
+  const f = await fixture(); delete f.release.image.source; f.release.image.url = 'https://example.test/app.bin'
+  let downloads = 0
+  const result = await f.device.firmware.update({ ...f.request, fetch: async url => {
+    downloads++; assert.equal(url, f.release.image.url); return new Response(f.full.slice(f.appOffset, f.appOffset + f.appLength))
+  } })
+  assert.equal(result.verified, true); assert.equal(downloads, 1)
+})
+for (const mutation of ['outside-app-corruption', 'source-truncated', 'source-long', 'app-hash', 'source-offset', 'source-bounds', 'source-size-limit', 'source-install-hash', 'source-install-url', 'image-source-url', 'source-http', 'bootloader-descriptor', 'table-descriptor']) {
+  test(`invalid source ${mutation} rejects before any ROM acquisition`, async () => {
+    const f = await fixture(), source = f.release.image.source
+    let bytes = f.full
+    if (mutation === 'outside-app-corruption') bytes[1] ^= 1
+    if (mutation === 'source-truncated') bytes = bytes.slice(0, -1)
+    if (mutation === 'source-long') bytes = new Uint8Array(bytes.length + 1)
+    if (mutation === 'app-hash') f.release.image.sha256 = '0'.repeat(64)
+    if (mutation === 'source-offset') source.offset++
+    if (mutation === 'source-bounds') source.bytes = 1
+    if (mutation === 'source-size-limit') source.bytes = 257 * 1024 * 1024
+    if (mutation === 'source-install-hash') source.sha256 = '0'.repeat(64)
+    if (mutation === 'source-install-url') f.release.install.url = 'https://example.test/other.bin'
+    if (mutation === 'image-source-url') f.release.image.url = 'https://example.test/app.bin'
+    if (mutation === 'bootloader-descriptor') f.release.install.bootloader.sha256 = '0'.repeat(64)
+    if (mutation === 'table-descriptor') f.release.image.partitionTable.sha256 = '0'.repeat(64)
+    if (mutation === 'source-http') source.url = f.release.image.url = f.release.install.url = 'http://example.test/full.bin'
+    await assert.rejects(f.device.firmware.update({ ...f.request, data: bytes }))
+    assert.deepEqual(f.calls, [])
+  })
+}
+test('downloaded full BIN enforces approved length during streaming before opening ROM', async () => {
+  const f = await fixture()
+  await assert.rejects(f.device.firmware.update({ ...f.request, fetch: async () => new Response(new Uint8Array(f.full.length + 1)) }), /byte limit/)
+  assert.deepEqual(f.calls, [])
+})
+test('single BIN explicit install writes the complete container without slicing it', async () => {
+  const f = await fixture()
+  assert.equal((await f.device.firmware.update({ ...f.request, data: f.full, mode: 'install' })).verified, true)
+  assert.deepEqual(f.flash, f.full)
+  assert.deepEqual(f.calls.find(call => Array.isArray(call) && call[0] === 'write'), ['write', 0, f.full.length])
+})
+test('single BIN application update still refuses changed partition layouts with no install fallback', async () => {
+  const f = await fixture(); f.flash[0x8000] ^= 1
+  await assert.rejects(f.device.firmware.update({ ...f.request, data: f.full }), /Partition layout/)
+  assert.ok(!f.calls.some(call => Array.isArray(call) && call[0] === 'write'))
+  assert.equal(f.calls.at(-1), 'close')
+})
+test('source extraction retains complete application readback verification and does not reset on corruption', async () => {
+  const f = await fixture(), read = f.loader.readFlash
+  f.loader.readFlash = async (offset, count) => offset === 0x8000 ? read(offset, count) : new Uint8Array(count)
+  await assert.rejects(f.device.firmware.update({ ...f.request, data: f.full }), /verification failed/)
+  assert.ok(!f.calls.includes('reset')); assert.equal(f.calls.at(-1), 'close')
+})
+
+test('single BIN update and explicit installation reuse hash-pinned browser-cache responses', async () => {
+  for (const mode of ['update', 'install']) {
+    const f = await fixture(), caches = []
+    const result = await f.device.firmware.update({ ...f.request, mode, fetch: async (_url, options) => {
+      caches.push(options.cache)
+      return new Response(f.full)
+    } })
+    assert.equal(result.verified, true)
+    assert.deepEqual(caches, ['default'])
+  }
+})
+test('single BIN cached CORS failure retries once and retains application-only verification', async () => {
+  const f = await fixture(), caches = []
+  const result = await f.device.firmware.update({ ...f.request, fetch: async (_url, options) => {
+    caches.push(options.cache)
+    if (caches.length === 1) throw new TypeError('Cached response lacks CORS permission')
+    return new Response(f.full)
+  } })
+  assert.equal(result.verified, true)
+  assert.deepEqual(caches, ['default', 'no-store'])
+  assert.deepEqual(f.calls.find(call => Array.isArray(call) && call[0] === 'write'), ['write', f.appOffset, f.appLength])
+})
+test('single BIN hash mismatch never retries cache or opens ROM; legacy app BIN stays no-store', async () => {
+  const f = await fixture(), caches = []
+  f.full[0] ^= 1
+  await assert.rejects(f.device.firmware.update({ ...f.request, fetch: async (_url, options) => {
+    caches.push(options.cache); return new Response(f.full)
+  } }), /SHA-256/)
+  assert.deepEqual(caches, ['default']); assert.deepEqual(f.calls, [])
+  delete f.release.image.source
+  caches.length = 0
+  await assert.rejects(f.device.firmware.update({ ...f.request, fetch: async (_url, options) => {
+    caches.push(options.cache); throw new TypeError('Network failure')
+  } }), /Network failure/)
+  assert.deepEqual(caches, ['no-store']); assert.deepEqual(f.calls, [])
+})

package/tests/test-release-manifest.mjs

@@ -0,0 +1,214 @@
+// SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+// SPDX-License-Identifier: Apache-2.0
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { createDevice } from '../src/index.js'
+import { loadOfficialFirmware, loadReleaseManifest, firmwareSha256 } from '../src/firmware.js'
+
+const base = 'https://dl.espressif.com/AE/esp-vision/'
+const commit = 'a'.repeat(40)
+async function fixture(version = 'new', sourceCommit = commit) {
+  const bytes = new Uint8Array(0x11000).fill(0xff)
+  bytes.set([0xe9, 1, 2, 3], 0x2000); bytes.set([0xaa, 0x50, 4, 5], 0x8000); bytes.set([0xe9, 6, 7, 8], 0x10000)
+  const segment = async offset => ({ offset, bytes: 4, sha256: await firmwareSha256(bytes.subarray(offset, offset + 4)) })
+  const source = { url: `${base}bin/esp-vision-BOARD-${version}.bin`, bytes: bytes.byteLength, sha256: await firmwareSha256(bytes), offset: 0x10000 }
+  const release = { board: 'BOARD', version, image: {
+    evMuxVersion: 4, chipFamily: 0x3280, chipRevision: 302, ...(await segment(0x10000)),
+    partitionSize: 4096, partitionTable: await segment(0x8000), url: source.url, source,
+  }, install: { url: source.url, offset: 0, bytes: source.bytes, sha256: source.sha256, flashSize: 0x1000000,
+    chipRevisionMin: 302, chipRevisionMax: 302, bootloader: await segment(0x2000) } }
+  const manifest = { schemaVersion: 1, version, sourceCommit, pipelineId: 123, layout: 'single-bin', releases: [release], website: {
+    schemaVersion: '1.0.0', release: version, releases: [version], binaryNameTemplate: 'esp-vision-{board}-{tag}.bin',
+    boards: [{ slug: 'board', board: 'BOARD', name: 'Board', flashable: true }],
+    models: [{ slug: 'model', sizeBytes: 4, path: 'models/a/model.espdl', downloadUrl: `https://raw.githubusercontent.com/espressif/esp-vision/${sourceCommit}/models/a/model.espdl` }],
+  }, mcp: { url: `${base}bin/mcp/mcp-pack-${version}.json`, bytes: 1234, sha256: 'c'.repeat(64), version, sourceCommit } }
+  const reference = async () => {
+    const raw = new TextEncoder().encode(JSON.stringify(manifest))
+    return { url: `${base}releases/${version}/manifest.json`, sha256: await firmwareSha256(raw), version, sourceCommit, boards: ['BOARD'], fetch: async () => new Response(raw) }
+  }
+  return { bytes, manifest, release, reference }
+}
+function config(current, history = [current]) {
+  return `[publication]\nschemaVersion = 1\nversion = "${current.version}"\nsourceCommit = "${current.sourceCommit}"\nmanifestUrl = "${current.url}"\nmanifestSha256 = "${current.sha256}"\npipelineId = 123\npreviousConfigSha256 = "${'e'.repeat(64)}"\nreleases = [${history.map(item => `{version = "${item.version}", manifestUrl = "${item.url}", manifestSha256 = "${item.sha256}", boards = ["BOARD"]}`).join(',')}]\n`
+}
+
+test('public manifest reader verifies the raw snapshot and preserves website, MCP and source metadata', async () => {
+  const f = await fixture(), request = await f.reference()
+  const result = await loadReleaseManifest(request)
+  assert.deepEqual(result, f.manifest)
+  assert.equal(result.releases[0].image.bytes, 4)
+  assert.equal(result.releases[0].image.source.bytes, f.bytes.length)
+})
+test('raw manifest hash is checked before parsing or returning any metadata', async () => {
+  const f = await fixture(), request = await f.reference()
+  await assert.rejects(loadReleaseManifest({ ...request, fetch: async () => new Response(JSON.stringify(f.manifest) + '\n') }), /manifest SHA-256/)
+  await assert.rejects(loadReleaseManifest({ ...request, sha256: 'invalid', fetch: () => { throw new Error('must not fetch') } }), /qualified SHA-256/)
+})
+for (const mutation of ['schema', 'version', 'commit', 'pipeline', 'layout', 'layout-source', 'duplicate-board', 'entry-version', 'entry-commit', 'app-hash', 'source-size', 'firmware-host', 'website-version', 'website-board', 'model-master', 'model-traversal', 'mcp-url', 'mcp-latest', 'mcp-version', 'mcp-commit', 'mcp-size']) {
+  test(`invalid manifest ${mutation} never yields an approved release`, async () => {
+    const f = await fixture(), m = f.manifest
+    if (mutation === 'schema') m.schemaVersion = 2
+    if (mutation === 'version') m.version = 'other'
+    if (mutation === 'commit') m.sourceCommit = 'master'
+    if (mutation === 'pipeline') m.pipelineId = 0
+    if (mutation === 'layout') m.layout = 'unknown'
+    if (mutation === 'layout-source') m.layout = 'legacy'
+    if (mutation === 'duplicate-board') m.releases.push(structuredClone(f.release))
+    if (mutation === 'entry-version') f.release.version = 'other'
+    if (mutation === 'entry-commit') f.release.sourceCommit = 'b'.repeat(40)
+    if (mutation === 'app-hash') f.release.image.sha256 = 'invalid'
+    if (mutation === 'source-size') f.release.image.source.bytes++
+    if (mutation === 'firmware-host') {
+      const url = 'https://untrusted.test/app.bin'
+      f.release.image.url = url; f.release.image.source.url = url; f.release.install.url = url
+    }
+    if (mutation === 'website-version') m.website.release = 'other'
+    if (mutation === 'website-board') m.website.boards[0].board = 'UNQUALIFIED'
+    if (mutation === 'model-master') m.website.models[0].downloadUrl = m.website.models[0].downloadUrl.replace(commit, 'master')
+    if (mutation === 'model-traversal') {
+      const model = m.website.models[0]
+      model.path = 'models/%2e%2e/%2e%2e/master/models/evil.espdl'
+      model.downloadUrl = `https://raw.githubusercontent.com/espressif/esp-vision/${commit}/${model.path}`
+    }
+    if (mutation === 'mcp-url') m.mcp.url = 'https://untrusted.test/pack.json'
+    if (mutation === 'mcp-latest') m.mcp.url = `${base}bin/mcp/mcp-pack-latest.json`
+    if (mutation === 'mcp-version') m.mcp.version = 'other'
+    if (mutation === 'mcp-commit') m.mcp.sourceCommit = 'b'.repeat(40)
+    if (mutation === 'mcp-size') m.mcp.bytes = 17 * 1024 * 1024
+    const reference = await f.reference()
+    reference.version = 'new'; reference.sourceCommit = commit
+    await assert.rejects(loadReleaseManifest(reference))
+  })
+}
+test('multi-file model groups may share a slug while each model path remains unique', async () => {
+  const f = await fixture(), model = f.manifest.website.models[0]
+  const otherPath = 'models/a/other.espdl'
+  f.manifest.website.models.push({ ...model, path: otherPath, downloadUrl: model.downloadUrl.replace(model.path, otherPath) })
+  assert.equal((await loadReleaseManifest(await f.reference())).website.models.length, 2)
+  f.manifest.website.models.push(structuredClone(model))
+  await assert.rejects(loadReleaseManifest(await f.reference()), /Invalid manifest model/)
+})
+test('manifest board set is checked against its immutable publication reference', async () => {
+  const f = await fixture()
+  await assert.rejects(loadReleaseManifest({ ...await f.reference(), boards: ['OTHER'] }), /board set/)
+})
+test('legacy manifest layout accepts qualified application-only artifacts and explicitly missing MCP', async () => {
+  const f = await fixture(); f.manifest.layout = 'legacy'; f.manifest.mcp = null
+  delete f.release.image.source
+  f.release.image.url = `${base}bin/app.bin`
+  assert.equal((await loadReleaseManifest(await f.reference())).layout, 'legacy')
+})
+test('official check loads only the requested version snapshot and never traverses old board/version metadata', async () => {
+  const current = await fixture(), old = await fixture('old', 'b'.repeat(40)), refs = [await current.reference(), await old.reference()], calls = []
+  const fetch = async (url, options) => {
+    calls.push(url)
+    assert.equal(options.cache, url.endsWith('config.toml') ? 'no-store' : 'default')
+    if (url.endsWith('config.toml')) return new Response(config(refs[0], refs))
+    assert.equal(url, refs[1].url)
+    assert.equal(options.redirect, 'error')
+    return refs[1].fetch()
+  }
+  const checked = await createDevice().firmware.check({ identity: { board: 'BOARD', firmwareVersion: 'older' }, version: 'old', fetch })
+  assert.equal(checked.release.version, 'old')
+  assert.deepEqual(calls, [base + 'config.toml', refs[1].url])
+  assert.equal(checked.releases.length, 1)
+})
+test('default official reader returns one current snapshot and its version references', async () => {
+  const f = await fixture(), reference = await f.reference(), calls = []
+  const result = await loadOfficialFirmware({ fetch: async url => {
+    calls.push(url)
+    return url.endsWith('config.toml') ? new Response(config(reference)) : reference.fetch()
+  } })
+  assert.equal(result.sourceCommit, commit); assert.equal(result.publication.releases[0].version, 'new')
+  assert.deepEqual(result.website, f.manifest.website)
+  assert.equal(calls.length, 2)
+})
+for (const mutation of ['manifest-404', 'manifest-corrupt', 'publication-invalid', 'missing-version', 'wrong-board']) {
+  test(`explicit publication ${mutation} never falls back to legacy per-board metadata`, async () => {
+    const f = await fixture(), reference = await f.reference(), calls = []
+    const request = { version: mutation === 'missing-version' ? 'missing' : 'new', board: mutation === 'wrong-board' ? 'OTHER' : 'BOARD', fetch: async url => {
+      calls.push(url)
+      if (url.endsWith('config.toml')) return new Response(mutation === 'publication-invalid' ? '[publication]\nschemaVersion = 7' : config(reference))
+      return mutation === 'manifest-corrupt' ? new Response('{}') : new Response('', { status: 404 })
+    } }
+    await assert.rejects(loadOfficialFirmware(request))
+    assert.ok(!calls.some(url => url.includes('/firmware/')))
+    assert.equal(calls.length, ['manifest-404', 'manifest-corrupt'].includes(mutation) ? 2 : 1)
+  })
+}
+test('old official configs retain compatibility but explicit version avoids historical requests', async () => {
+  const f = await fixture('old'), calls = []
+  delete f.release.image.source
+  const text = `firmware_images_url = "${base}bin/"\n[esp-vision.image]\nBOARD = "latest.bin"\n[website]\nrelease = "new"\nreleases = ["new", "old"]\nbinaryNameTemplate = "esp-vision-{board}-{tag}.bin"\n`
+  const result = await loadOfficialFirmware({ version: 'old', fetch: async url => {
+    calls.push(url)
+    return url.endsWith('config.toml') ? new Response(text) : new Response(JSON.stringify(f.release))
+  } })
+  assert.equal(result.releases[0].version, 'old')
+  assert.deepEqual(calls, [base + 'config.toml', base + 'firmware/BOARD/old.json'])
+})
+test('manifest responses enforce a byte limit before allocation and during streaming', async () => {
+  const f = await fixture(), reference = await f.reference()
+  await assert.rejects(loadReleaseManifest({ ...reference, fetch: async () => ({ ok: true, headers: new Headers({ 'content-length': String(5 * 1024 * 1024) }), arrayBuffer() { throw new Error('must not allocate') } }) }), /byte limit/)
+  let cancelled = false
+  const response = new Response(new ReadableStream({ start(controller) { controller.enqueue(new Uint8Array(4 * 1024 * 1024 + 1)) }, cancel() { cancelled = true } }))
+  await assert.rejects(loadReleaseManifest({ ...reference, fetch: async () => response }), /byte limit/)
+  assert.equal(cancelled, true)
+})
+test('a cancelled pending manifest stream closes its reader and rejects', async () => {
+  const f = await fixture(), controller = new AbortController()
+  let cancelled = false
+  const response = new Response(new ReadableStream({ cancel() { cancelled = true } }))
+  const pending = loadReleaseManifest({ ...await f.reference(), signal: controller.signal, fetch: async () => response })
+  await new Promise(resolve => setTimeout(resolve, 5))
+  controller.abort()
+  await assert.rejects(pending, { name: 'AbortError' })
+  assert.equal(cancelled, true)
+})
+test('official manifest URLs reject HTTP, credentials, redirects and outside-root origins', async () => {
+  const f = await fixture(), reference = await f.reference()
+  for (const url of ['http://dl.espressif.com/AE/esp-vision/release.json', 'https://user:pass@dl.espressif.com/AE/esp-vision/release.json', 'https://dl.espressif.com/other/release.json', 'https://example.test/release.json']) {
+    await assert.rejects(loadReleaseManifest({ ...reference, url }))
+  }
+  await assert.rejects(loadReleaseManifest({ ...reference, fetch: async () => ({ ok: true, url: 'https://untrusted.test/redirect', arrayBuffer() { throw new Error('must not read') } }) }), /official source/)
+})
+
+test('hash-pinned manifest uses browser cache and retries a fetch-stage CORS TypeError once without cache', async () => {
+  const f = await fixture(), reference = await f.reference(), caches = []
+  const result = await loadReleaseManifest({ ...reference, fetch: async (_url, options) => {
+    caches.push(options.cache)
+    if (caches.length === 1) throw new TypeError('Cached navigation response has no CORS headers')
+    return reference.fetch()
+  } })
+  assert.equal(result.version, 'new')
+  assert.deepEqual(caches, ['default', 'no-store'])
+})
+test('manifest cache recovery never retries HTTP, hash or metadata failures', async () => {
+  const f = await fixture(), reference = await f.reference()
+  for (const failure of ['http', 'body', 'hash', 'metadata']) {
+    const caches = []
+    let bytes
+    if (failure === 'metadata') {
+      f.manifest.pipelineId = 0
+      bytes = new TextEncoder().encode(JSON.stringify(f.manifest))
+    }
+    await assert.rejects(loadReleaseManifest({ ...reference, sha256: bytes ? await firmwareSha256(bytes) : reference.sha256, fetch: async (_url, options) => {
+      caches.push(options.cache)
+      if (failure === 'body') return new Response(new ReadableStream({ start(controller) { controller.error(new TypeError('body read failed')) } }))
+      return failure === 'http' ? new Response('', { status: 503 }) : new Response(bytes ?? '{}')
+    } }))
+    assert.deepEqual(caches, ['default'])
+  }
+})
+test('manifest fetch TypeError recovery stops after one retry and does not retry after cancellation', async () => {
+  const f = await fixture(), reference = await f.reference(), caches = []
+  await assert.rejects(loadReleaseManifest({ ...reference, fetch: async (_url, options) => {
+    caches.push(options.cache); throw new TypeError('CORS still unavailable')
+  } }), /CORS still unavailable/)
+  assert.deepEqual(caches, ['default', 'no-store'])
+  const controller = new AbortController(), cancelledCalls = []
+  await assert.rejects(loadReleaseManifest({ ...reference, signal: controller.signal, fetch: async (_url, options) => {
+    cancelledCalls.push(options.cache); controller.abort(); throw new TypeError('request cancelled')
+  } }))
+  assert.deepEqual(cancelledCalls, ['default'])
+})

package/tests/test-release-verification.mjs

@@ -51,8 +51,16 @@ test('missing published integrity is not accepted', async () => {
   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])
+test('persistent propagation failures stop after ten reads with bounded backoff', async () => {
+  const f = fixture(Array.from({ length: 10 }, () => new Response('', { status: 404 })))
+  await assert.rejects(verifyPublishedIntegrity(url, integrity, f.options), /after 10 reads/)
+  assert.equal(f.calls.length, 10); assert.deepEqual(f.waits, [1000, 2000, 4000, 8000, 16000, 30000, 30000, 30000, 30000])
+})
+
+test('registry visibility delayed beyond the original 31-second window is verified without another publish', async () => {
+  const f = fixture([...Array.from({ length: 7 }, () => new Response('', { status: 404 })), published(integrity)])
+  await verifyPublishedIntegrity(url, integrity, f.options)
+  assert.equal(f.calls.length, 8)
+  assert.ok(f.waits.reduce((total, delay) => total + delay, 0) > 31000)
+  assert.ok(f.waits.every(delay => delay <= 30000))
 })