mirror of
https://github.com/morluto/rea.git
synced 2026-11-20 05:32:44 +00:00
* fix(v8): read the code cache header size from the container
V8 sizes the header with `kHeaderSize = POINTER_SIZE_ALIGN(kUnalignedHeaderSize)` and
`kUnalignedHeaderSize` is 28, so the header is padded *after* its words: a 64-bit producer writes
32 header bytes and a 32-bit one writes 28. The reader pinned 32 and required the declared payload
to equal `bytes.length - 32`, so every container from a 32-bit producer failed as "truncated or
corrupt".
Measured here on Node 24.22.1 (V8 in x64): take a real cache and drop the four alignment bytes at
offset 28. V8 loads it unchanged — `cachedDataRejected === false` — while the reader refused it:
before: Header declares a 392-byte payload but 388 bytes follow the 32-byte header
after: ACCEPT header_bytes=28 words=7 payload.offset=28
The payload-length word sits at byte 20 in both layouts, so the declared length already states how
much trailing padding the container carries. The header size is derived from it now: `28` and `32`
are admitted, the reported word table covers exactly the header the container holds (7 or 8 words),
and the schema requires that table to agree with `header_bytes`.
Nothing is loosened. A header that is neither 28 nor 32 bytes is still `malformed`, and the
16 existing cases pass unchanged — dropping only the derivation back to the constant fails exactly
the new narrow-header case.
`src/v8` — 26 passing. `npm run lint` and `tsc --noEmit` clean.
* fix(v8): refuse a wide cache that is only four bytes short
A review finding on the previous commit, and a real one: deriving the header size from the declared
payload length makes a 32-byte-header container truncated by four bytes resolve to 28, because
`bytes.length - declaredPayload` loses exactly those four bytes. The reader then accepted a
truncated cache and read its payload one word long.
The wide header's last word is `POINTER_SIZE_ALIGN` padding that V8 leaves zero, and a narrow
container has payload where that word sits. Measured on Node 24.22.1 across six different sources:
the padding word is always `0x00000000` and the first payload word is always non-zero. So the zero
word is the only evidence that separates the two, and it is now required to be non-zero for the
28-byte layout:
| container | before this commit | after |
| --- | --- | --- |
| real 32-byte header | accept | accept, `header_bytes=32` |
| real 28-byte header | accept | accept, `header_bytes=28` |
| 32-byte header truncated by 4 | **accept** | refused as `malformed` |
The guide also described one pinned 32-byte header; it now describes both layouts, how the size is
resolved, and why an ambiguous container is refused.
`src/v8` — 27 passing. Removing the guard accepts the truncated container again.
* fix(v8): read the padding word through the header accessor
A Static checks finding: `verify/architecture-guards.mjs` counts raw Buffer reads in parser folders
and allows only a shrinking baseline, and the previous commit added one:
```
raw Buffer or DataView numeric read (use BinaryReader ...); new copies are not allowed:
src/v8/V8CodeCacheParser.ts: 2 (baseline 1)
```
The read is the narrow-header discriminator — the alignment word a 64-bit producer leaves zero at
offset 28. It now goes through the file's existing `field(index)` accessor instead of calling
`bytes.readUInt32LE` directly, so the count returns to the baseline while the check itself is
unchanged: `field(7)` is byte 28, and `V8_CODE_CACHE_NARROW_HEADER_BYTES / 4` spells that index.
`node scripts/verify/architecture-guards.mjs` — passed across 2 843 source files.
`src/v8` + `tests/boundary/rust` — 68 passing. `tsc --noEmit` 0 errors.
Setting the condition to `false` fails "refuses a wide container that is only four bytes short",
so the check is still load-bearing.
* fix(v8): ground the narrow-header rule in the producer, and test the word table
Two review findings.
**The rule was stated as measurement, not as format.** The previous comment justified the zero-word
discriminator with "measured on Node 24.22.1 every real payload begins with a non-zero word", which
makes support for other producers depend on one host. The producer zeroes that padding rather than
copying payload over it: `SerializedData::AllocateWithPayload` in `src/snapshot/snapshot-data.cc`
runs `std::fill_n(data_, header_size, 0)` before writing any header word, and
`kHeaderSize = POINTER_SIZE_ALIGN(kUnalignedHeaderSize)` in `src/snapshot/code-serializer.h` puts the
four padding bytes inside `header_size`. So a zero word at byte 28 is a fact about the producer, not
about one Node build.
The refusal is now worded as the reservation it is: a narrow container whose payload happened to
begin with four zero bytes would match the same test, and no reading of the header alone separates
the two cases. The message says both readings instead of asserting corruption.
**The word-table rule had no test that could fail.** `header.fields.length * 4 === header.header_bytes`
cannot disagree on a parsed container — the parser derives both from `payloadOffset` — so it is only
reachable through the schema, which is what a stored or projected report also goes through. The new
case builds four reports directly: seven words with 32 bytes and eight words with 28 are refused on
`header.fields`, while the two consistent pairs are accepted. Setting the rule to `false` fails it
with `7 words / 32 bytes: expected true to be false`.
`node scripts/verify/architecture-guards.mjs` — passed across 2 843 source files.
`src/v8` + `tests/boundary/rust` — 69 passing. `tsc --noEmit` 0 errors, `npm run lint` 0 errors.
* refactor(v8): share decoded code cache header words
* fix(v8): validate narrow header evidence without assuming runtime compatibility
---------
Co-authored-by: morluto <76467478+morluto@users.noreply.github.com>
128 lines
6.8 KiB
Markdown
128 lines
6.8 KiB
Markdown
# V8 code cache inspection
|
|
|
|
`inspect_v8_code_cache` reads one explicitly selected V8 code cache container as static
|
|
bytes: a bytenode `.jsc`, the bytes `vm.Script.createCachedData()` writes, or a cache
|
|
carried inside a Node single-executable application or an Electron app. It never executes
|
|
the file, never starts a V8 runtime, never installs bytenode, and never invokes a
|
|
decompiler.
|
|
|
|
```bash
|
|
rea inspect-v8-code-cache /absolute/path/to/module.jsc --json
|
|
rea inspect-v8-code-cache /absolute/path/to/module.jsc --minStringBytes 8 --json
|
|
```
|
|
|
|
The MCP tool is `inspect_v8_code_cache` with the same inputs and the same retained
|
|
Evidence.
|
|
|
|
## What is read
|
|
|
|
A V8 code cache is a version-dependent container. This reader recognizes a pinned
|
|
layout with both supported header extents and reports observed header values and
|
|
payload bytes.
|
|
|
|
The [Node v24.22.1 V8 serializer](https://github.com/nodejs/node/blob/v24.22.1/deps/v8/src/snapshot/code-serializer.h#L106-L119)
|
|
defines seven little-endian 32-bit words followed by pointer-alignment padding.
|
|
Four-byte alignment produces a 28-byte header. Eight-byte alignment produces a
|
|
32-byte header with a zero padding word. The reader derives the candidate header
|
|
extent from the container length and declared payload length. Each observed word
|
|
appears in `header.fields` with its byte offset, value, role, and confidence.
|
|
|
|
| Offset | Role | Status |
|
|
| -------------- | -------------- | ----------- |
|
|
| `0x00` | magic | confirmed |
|
|
| `0x04` | version hash | inferred |
|
|
| `0x08` | source length | confirmed |
|
|
| `0x0c` | flag hash | inferred |
|
|
| `0x10` | build constant | inferred |
|
|
| `0x14` | payload length | confirmed |
|
|
| `0x18`, `0x1c` | reserved | unconfirmed |
|
|
|
|
`confirmed` means the role is demonstrated by the reader's own tests against the producer.
|
|
`inferred` means the word's behaviour is consistent with the role but a different producer
|
|
could plausibly differ. `unconfirmed` means the word is reported and nothing more is
|
|
claimed.
|
|
|
|
Admission requires the V8 magic high half `0xc0de` and a declared payload
|
|
that reaches the end of the file from a 28- or 32-byte header.
|
|
`ExternalReferenceTable::kSize` accounts for the varying low half of the magic word.
|
|
A candidate 28-byte header followed by a zero word is ambiguous. A 32-byte header
|
|
with a four-byte-truncated payload leaves its zero padding at the same offset as a
|
|
28-byte header whose payload begins with that word. The reader refuses that case.
|
|
|
|
Header extent describes the retained bytes. The synthetic narrow fixture tests
|
|
reader admission. Runtime compatibility remains unverified for a 32-bit producer.
|
|
|
|
`header.source_length` is the producer's recorded source length in UTF-16 code units.
|
|
V8's serializer calls this field the source hash; on the producers measured here its value
|
|
equals the source length exactly, including sources whose UTF-8 byte length differs, so the
|
|
reader reports it under the name the measurement supports. Treat that name as an
|
|
observation, not as a claim about what any other build stores there.
|
|
`header.producer` names the producer family from the flag bits in that word. Bit 29
|
|
marks `vm.compileFunction` (`compile_function`); bit 30 marks `vm.SourceTextModule`
|
|
(`module`). V8 before 13.4, including Node 22, marks a module with bit 31 instead,
|
|
which is also reported as `module`. When no flag is present, the producer remains `unknown`:
|
|
`vm.Script`, bytenode output and older unflagged function caches cannot be
|
|
separated by those bits alone. The source-length mask is `0x1fffffff`, so both
|
|
flags sit outside the reported length. This describes the admitted header
|
|
profile rather than a version-independent V8 ABI.
|
|
|
|
## Failed inspection and provenance
|
|
|
|
After a stable read completes, format and observation-budget refusals retain a
|
|
`file-snapshot-hash` partial observation with the selected path, exact SHA-256 and
|
|
byte count. This proves which bytes were read; it does not claim the format was
|
|
successfully decoded. A refusal before read completion does not invent an identity.
|
|
Descriptor cleanup remains owned for retry if finalization fails.
|
|
|
|
## Embedded byte patterns
|
|
|
|
`embedded_strings` lists printable runs found in the payload, each with its absolute byte
|
|
offset in the selected file and its observed byte length. `min_string_bytes` (default 4)
|
|
sets the shortest reported run; `max_strings` caps how many may be reported, and exceeding
|
|
it fails without partial success.
|
|
|
|
These are **byte-pattern observations inside serialized V8 heap data, not parsed heap
|
|
objects**. A reported run is not proof V8 retained it as a string. A literal that is absent
|
|
from the payload is not proof it is absent from the program: V8 may encode a string in a
|
|
form the run scan does not surface, and a string can be produced at runtime rather than
|
|
retained.
|
|
|
|
A run longer than 4096 bytes is reported with `truncated: true` and a `retained_bytes`
|
|
prefix.
|
|
|
|
## Limitations
|
|
|
|
Every result states these, and they are part of the contract:
|
|
|
|
- the payload is serialized V8 heap data, not source; no logic is recovered and no
|
|
bytecode is decompiled;
|
|
- recovering logic needs a version-pinned V8 decompiler (View8-style) that this tool
|
|
neither provides nor depends on;
|
|
- header roles beyond magic, source length, and payload length are version-dependent
|
|
observations;
|
|
- the tool never executes the selected file and never claims recovered source.
|
|
|
|
## Failure behaviour
|
|
|
|
An unknown magic is a typed `unsupported_target` failure, because the file is not a V8
|
|
code cache. A short header, a payload-length disagreement, or bytes past the declared
|
|
payload is a typed `invalid_request` failure. Neither produces completed inspection
|
|
Evidence; the stable-read partial observation described above is retained when available.
|
|
|
|
`max_file_bytes` (default 32 MiB, ceiling 64 MiB) is the caller-selected read budget. The
|
|
payload SHA-256 is computed over the declared payload, so two containers with the same
|
|
payload length and content but different version hashes have different whole-file digests
|
|
and identical payload digests.
|
|
|
|
## Relationship to other tools
|
|
|
|
- `inspect_binary_layout` reads the surrounding ELF/PE container of a single-executable
|
|
application; it does not decode the embedded code cache.
|
|
- A cache embedded in a Node single-executable application or an Electron app must be
|
|
**extracted first**: this reader admits a container whose magic is at byte zero, so
|
|
passing the surrounding ELF/PE executable here returns `unsupported_target`. Run
|
|
`extract_artifact` on the application, then pass the extracted `.jsc` path to this tool.
|
|
- `inspect_artifact` inventories the file without decoding V8 structures.
|
|
- This tool is in the same family as `inspect_python_pyc`, `inspect_erlang_beam`, and
|
|
`inspect_kernel_module`: one explicit local file, bounded parsing, no execution.
|