Entrpiandmorluto
b43c329df7
* feat(artifacts): inventory and extract UF2 and DfuSe regions open_binary refused UF2 and DfuSe firmware containers as an unsupported format, so inspect_artifact and extract_artifact could not show which bytes a drag-and-drop or DFU update writes at which addresses. UF2 is recognized by a complete first block with all three magic numbers. Valid main-flash payloads are joined into address-contiguous regions per familyID, named family-0x<id>/0x<start>-0x<end>.bin, and known IDs are named from a small table copied from Microsoft's uf2families.json at a pinned commit. Numbering is counted per familyID and block count: absent, repeated, out-of-order and out-of-range block numbers are reported, and absent blocks leave coverage unknown. Not-main-flash blocks are excluded and reported; file-container blocks are reported and leave coverage unknown; invalid blocks and a partial final block are excluded with their position. A rewrite of one address with different bytes fails closed, naming both block spans. DfuSe is recognized only by its prefix together with a DFU 1.1a suffix. Each element becomes one region at its file range with its target's alternate setting and name. Structural faults fail closed with a byte offset; overlapping elements stay separate and are reported. A suffix CRC mismatch follows integrity_policy: fail refuses with a dfu-crc32 integrity error, and record-and-continue records a root contradiction that extraction also carries. HEX, UF2 and DfuSe share one retained-region reader and one run merger, so the HEX decoder and reader lose their private copies. * docs(artifacts): document UF2 and DfuSe images and their esptool lane Describe recognition, region names, metadata, numbering, failures, the DfuSe suffix CRC under integrity_policy, and limits, and link the page from the CLI and firmware guides and the agent skill reference. npm run verify:uf2 runs esptool merge-bin --format uf2 on generated inputs at known addresses, with and without MD5, with 256-byte payloads, and on a concatenation of two chips' outputs. Inspection and extraction through the built CLI must return every input at its address under the familyID esptool itself reports. * fix(artifacts): accept both DfuSe image size conventions UM0391 calls DFUImageSize the file length, and dfu-util's dfuse-pack.py writes that value, while ST's DfuFileMgr, MicroPython's dfu.py and pydfu leave the 16-byte suffix out. The decoder accepted only the second form, so it refused dfuse-pack.py output as malformed. Accept either value and keep the declared one in image_size; any other value still fails with the suffix offset and the file length. The tests pin both producers' output for one image, CRC included, from their build() functions transcribed and run under Python 3. * fix(artifacts): keep reused UF2 block numbers from hiding missing blocks esptool numbers every merged input from 0, so two inputs with the same block count share one numbering group. A block lost from one input left its number present in the other, and the file reported complete coverage. Each block number now records the target addresses it was seen at: equal address counts are complete copies, a resend to the same address is one block, and unequal counts make coverage unknown with a limitation and ambiguous_numbering_group_count. sequence_count becomes numbering_group_count, and region block positions become first_file_block and last_file_block. Review follow-ups in the same change: - compare_artifacts compares a DfuSe element's alternate setting and target name, so bytes moved to another device memory are changed; - the shared reader keeps no region bytes outside its map after close; - one domain type replaces four identical decoder failure types; - the UF2 decoder returns a typed limit instead of throwing on bytes beyond its admitted size, and caps retained regions, not runs; - DfuSe caps elements with bytes only, names empty elements and element-less targets, drops the constant bVersion and bcdDFU fields, and says whether the CRC matches when DFUImageSize fits neither convention; - classification evidence carries a suffix only when the probe saw the end, and root classification reads the tail only for a DfuSe prefix; - the UF2 domain region owns family_name, and the root records the family registry revision; the table's MIT notice is preserved; - docs pin the producer revisions (dfu-util ee6b393d and f9a537c9, MicroPython cb99ca98), give the MD5 structure's real meaning, and describe container contradictions in the MCP contract guide; - tests and the esptool lane add the equal-count inputs and a block lost from one of them, accepted boundaries beside each refusal, a DfuSe root larger than the classification prefix, and CLI refusals. * feat(artifacts): name the UF2 families that LibreTiny builds for LibreTiny writes UF2 for Realtek, Beken and Bouffalo Lab modules. The Microsoft registry revision REA already cites (cf3bd7f9) lists eight of those families: RTL8710A, RTL8710B, RTL8720C, RTL8720D, BK7231U, BK7231N, BK7251 and BL602. Their regions now carry those names. LN882H, which that revision omits, keeps its familyID with no name. * fix(artifacts): count DfuSe declarations without bytes instead of listing them Empty DfuSe elements have no entry, so DFUSE_MAX_ELEMENTS does not cap them, and the target walk kept a description string for each one. At 8 bytes per element, a file under the 128 MiB ceiling can declare about 16.7 million of them. The walk now counts every declaration without bytes and builds only the first NAMED_ELEMENTS descriptions, which is all that the limitation shows. The limitation text and empty_element_count do not change. The guide now says that both DfuSe limitations name the first four. On this host, decoding 4,000,000 empty elements (a 32 MB file) ran out of memory under a 128 MB V8 heap before this change, and it peaked at 1.59 GB RSS with the default heap. It now decodes in 114 ms with a 220 MB peak. --------- Co-authored-by: morluto <76467478+morluto@users.noreply.github.com>
Preserved licenses and attribution
Start with THIRD_PARTY_NOTICES.md for the distinction between distributed material and separately obtained tools. These files retain upstream texts; they do not change REA's MIT license.
| Files | Provenance and scope |
|---|---|
npm-dependencies.txt |
Every package path in the root lockfile, with its exact version, declared license, scope, download URL, and integrity. Includes development and optional platform entries. |
npm-runtime-notices.txt |
Original license, copyright, and NOTICE texts collected from integrity-verified locked runtime npm archives across all platforms; also the license of Rolldown's generated runtime helpers. The archive manifest's name and version are checked. |
protobuf-es-v2.16.0-LICENSE.txt |
Original Apache license omitted from the protobuf-es npm archive, preserved from its v2.16.0 source commit. Its embedded Google BSD notice is retained in npm-runtime-notices.txt. |
microsoft-uf2-MIT.txt |
Unchanged LICENSE.txt from microsoft/uf2 revision cf3bd7f9c274b949528f8cd6a19eef2502a687d2, for the UF2 family names copied from its utils/uf2families.json. |
nativeaot-parser-MIT.txt |
Original Washi notice for derived NativeAOT parser code; source revision is recorded in the parser and the root notices. |
dotnet-runtime-MIT.txt |
Original .NET Foundation MIT text from the NativeAOT reference revision a3b2d40328be0be3f8dd43f0e5cc925b8827b044. |
ghidra-12.1.4-{LICENSE,NOTICE,DISCLAIMER}.txt |
Unchanged top-level documents from Ghidra_12.1.4_build. Ghidra is not bundled; these reference copies do not replace its component and GPL support-program notices. The US-government-specific disclaimer applies to Ghidra, not to REA. |
cfworker-MIT.txt, xterm-MIT.txt |
Original notices missing from their published runtime npm archives, recovered from the releases' upstream Git revisions. They are included in the corresponding runtime entries. |
Apache-2.0.txt, MIT-template.txt |
Standard license texts for explicitly documented upstream notice gaps. The MIT placeholders are not an attribution to an inferred author or year. |
frida-17.23.2-COPYING.txt, LGPL-2.0.txt |
Unchanged licensing supplements for the optional Frida dependency: tagged Frida wxWindows notice and GNU Library GPL v2 text. The npm archive and tagged Node binding omit a standalone license/copyright document; these texts do not recover binding or prebuild-component attribution. |
MinGW-w64-runtime.txt |
Upstream's combined runtime copyright and license notices, snapshot from v12.0.0, for the statically linked Windows addon. This is a notice snapshot, not a pin of the compiler used in release CI. |
GPL-3.0.txt, GCC-Runtime-Library-Exception-3.1.txt |
Unchanged GPLv3 and GCC runtime exception texts from GCC 14.2.0. The exception permits eligible compiled combinations under its conditions; the runtime keeps its own license. This snapshot does not assert that every release uses GCC 14.2.0. |
Node-22.19.0-LICENSE.txt |
The original Node 22.19.0 license and third-party notices. The Windows addon uses Node-API headers from that release; the complete Node runtime and all components listed in this reference document are not bundled. |
upstream-sources.json |
Source URLs and SHA-256 digests for the new unchanged reference and supplemental texts. These digests identify the preserved local texts. |
Additional preserved originals live at evmole/LICENSE, pwndbg/LICENSE.md, and the website dinosaur notice.
Collection scope and maintenance
The inventory and runtime texts were prepared from the root lockfile. The collection downloaded the locked npm archives, checked their lockfile integrity and package identity, and read license/NOTICE/copyright documents without installing packages or executing lifecycle scripts. It includes optional platform packages that may not be present in one local installation. Temporary archives were removed after collection.
For releases that omit original documents, the collection uses pinned upstream
texts, embedded source/README license sections, or the same release's parent
notice for the @lydell/node-pty prebuilt family. evmole@0.9.3 uses the existing
preserved upstream license. clean-git-ref@2.0.1 and minimisted@2.0.1 provide
only license and author metadata: their missing original copyright documents
remain explicitly identified in the runtime texts. Do not describe those
entries as complete recovered attribution.
frida@17.23.2 also lacks an original standalone notice in its npm archive and
tagged Node source. Its declared license and the preserved licensing supplements
are recorded explicitly without inferring a copyright holder or year.
These records do not establish the legal accuracy of upstream metadata or
prove that every upstream source-file attribution has been supplied in an
archive. Review and refresh them when dependencies change; compare reference
texts with the sources and SHA-256 digests in upstream-sources.json.
When updating engines, copied code, website assets, or the Windows release toolchain, review their actual upstream notices as well. The Linux MinGW-w64 compiler in release CI is not version-pinned by REA: compare its installed runtime/component notices with the retained snapshots and update them if they differ. Do not assume that a compiler change leaves redistribution requirements unchanged. Preserve applicable originals with any additionally bundled engine; top-level reference copies alone may not cover its entire distribution.
Generate the exact locked inventory with npm run licenses:generate. After
refreshing verified runtime notices, update their header fingerprint to the
generator's reported runtime_dependency_fingerprint, then run
npm run licenses:check; docs:check also runs this check. It compares the
inventory, runtime package identities,
license declarations, archive URLs/integrity, runtime dependency fingerprint,
and preserved reference digests. It does not verify legal completeness or
replace inspection of original upstream notices.