Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
75f1bf97e1 | ||
|
|
0bc422d7be | ||
|
|
2895a18ca9 | ||
|
|
7a6defab18 | ||
|
|
a4dd4e8128 | ||
|
|
346275525e | ||
|
|
8fef2aa64e | ||
|
|
ebaaa79ca0 | ||
|
|
1d5f95dc4a | ||
|
|
f652709cac | ||
|
|
c8ef1f916c | ||
|
|
f1045001f0 | ||
|
|
69bd81f7f2 | ||
|
|
781827b7b4 | ||
|
|
dc8a3e6078 | ||
|
|
1b6c899b03 | ||
|
|
0434be924e | ||
|
|
93e29d242a | ||
|
|
c6631814e0 | ||
|
|
62c8b3da1b | ||
|
|
0c9ee56c2f | ||
|
|
501c5d45fe | ||
|
|
df3d96da80 | ||
|
|
7e3a198638 | ||
|
|
502266b3f7 | ||
|
|
72b9ab4af1 | ||
|
|
d4f0c5e664 | ||
|
|
3f80b75708 | ||
|
|
1aaaf06928 | ||
|
|
ee4a11df81 | ||
|
|
480a467dac | ||
|
|
2904bdb4f8 | ||
|
|
00f31692b5 | ||
|
|
de2ab343f1 | ||
|
|
717b5a215e | ||
|
|
5e7fcdcdc3 | ||
|
|
89914a04cd | ||
|
|
96608517ba | ||
|
|
577d6c3e9b | ||
|
|
f6748a511e | ||
|
|
faa6f89566 | ||
|
|
c530a37813 | ||
|
|
75c2741912 | ||
|
|
0d018d5a77 | ||
|
|
9d4c517b84 | ||
|
|
6d0a6b5d51 | ||
|
|
baadb8114c | ||
|
|
6c93ebabb0 | ||
|
|
2d1d8c45ea | ||
|
|
d4530488c3 | ||
|
|
3590893742 | ||
|
|
72b78e41b9 | ||
|
|
a74a599fce | ||
|
|
d3e315cf33 | ||
|
|
54c2e4e81c | ||
|
|
c17cb017fa | ||
|
|
2b29105bf9 | ||
|
|
681f34879e | ||
|
|
a60d60dc6b | ||
|
|
1c6217258a | ||
|
|
e47b667670 | ||
|
|
78820dd69a | ||
|
|
db24a47c15 | ||
|
|
071f632e92 | ||
|
|
7cba3acaa4 | ||
|
|
ca646b6cb9 | ||
|
|
2f0e4d79ea | ||
|
|
9b8916152b | ||
|
|
e6d4d7fb84 | ||
|
|
5ba8b2f6bf | ||
|
|
574f6bb3bd | ||
|
|
414307c9d5 |
@@ -213,6 +213,16 @@ REA. Symlinks and encrypted entries are inventory facts, not extractable files.
|
||||
The result reports the materialized directory; callers do not choose the
|
||||
destination. No separate permission grant is needed.
|
||||
|
||||
For classic iNES cartridges, `open_binary` recognizes the byte signature without
|
||||
an executable architecture. `inspect_artifact` retains header facts and each
|
||||
PRG/CHR file unit's offset, length and SHA-256; its nested inventory's
|
||||
`ines.reconstruction` verifies the actual ordered region bytes against the
|
||||
whole-file digest. Extraction includes the original header, optional trainer
|
||||
and uninterpreted trailing bytes. These file units are not mapper/CPU bank
|
||||
maps. NES 2.0, UNIF, dirty legacy headers and truncated payloads are explicitly
|
||||
refused. No emulator or 6502 analysis is performed. See the
|
||||
[iNES guide](https://github.com/morluto/rea/blob/main/docs/ines-containers.md).
|
||||
|
||||
Native DMG traversal automatically uses a read-only mount on supported macOS
|
||||
hosts, with an owned temporary mount directory and cleanup. It needs no approval
|
||||
flag. Unsupported hosts or mount failures remain explicit limitations; do not
|
||||
|
||||
@@ -33,7 +33,7 @@ env:
|
||||
jobs:
|
||||
changes:
|
||||
name: Classify changes
|
||||
runs-on: ubuntu-latest
|
||||
runs-on: ubuntu-24.04
|
||||
timeout-minutes: 5
|
||||
permissions:
|
||||
contents: read
|
||||
@@ -290,14 +290,19 @@ jobs:
|
||||
- if: needs.changes.outputs.code == 'true' && success()
|
||||
run: npm ci
|
||||
- uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
|
||||
if: needs.changes.outputs.code == 'true' && success()
|
||||
if: >-
|
||||
!cancelled() && needs.changes.outputs.code == 'true' &&
|
||||
(needs.test-shard.result == 'success' || needs.test-shard.result == 'failure')
|
||||
with:
|
||||
path: .vitest/blob
|
||||
pattern: vitest-report-*
|
||||
merge-multiple: true
|
||||
- name: Merge coverage, JUnit, and timing reports
|
||||
id: merge
|
||||
if: needs.changes.outputs.code == 'true' && needs.changes.outputs.tier == 'full' && success()
|
||||
if: >-
|
||||
!cancelled() && needs.changes.outputs.code == 'true' &&
|
||||
needs.changes.outputs.tier == 'full' &&
|
||||
(needs.test-shard.result == 'success' || needs.test-shard.result == 'failure')
|
||||
run: >-
|
||||
npm run test:ci:merge --
|
||||
--coverage.reportsDirectory=coverage
|
||||
@@ -312,7 +317,10 @@ jobs:
|
||||
--outputFile.json=test-results.json
|
||||
- name: Merge fast-suite JUnit and timing reports
|
||||
id: merge-fast
|
||||
if: needs.changes.outputs.code == 'true' && needs.changes.outputs.tier == 'fast' && success()
|
||||
if: >-
|
||||
!cancelled() && needs.changes.outputs.code == 'true' &&
|
||||
needs.changes.outputs.tier == 'fast' &&
|
||||
(needs.test-shard.result == 'success' || needs.test-shard.result == 'failure')
|
||||
run: >-
|
||||
npm exec -- vitest --merge-reports
|
||||
--reporter=default
|
||||
@@ -514,6 +522,12 @@ jobs:
|
||||
npm run verify:legacy-simulator
|
||||
npm run verify:apple-dispatch
|
||||
npm run verify:interface-builder
|
||||
- name: Verify portable iNES CLI, MCP and source boundaries
|
||||
run: >-
|
||||
npm run test:focused --
|
||||
tests/acceptance/inesContainer.test.ts
|
||||
tests/boundary/filesystem/inesArtifact.test.ts
|
||||
tests/boundary/filesystem/inesCancellation.test.ts
|
||||
- name: Run native Apple and process boundary regressions
|
||||
run: >-
|
||||
npm run test:focused --
|
||||
@@ -525,6 +539,7 @@ jobs:
|
||||
tests/boundary/cli/nativePlistSelectionFailureCli.test.ts
|
||||
tests/boundary/cli/nativeDemangleCli.test.ts
|
||||
tests/boundary/mcp/nativeDemangleMcp.test.ts
|
||||
tests/boundary/mcp/nativeMachoSummaryMcp.test.ts
|
||||
tests/boundary/providers/native/nativeSignatureTargetBinding.test.ts
|
||||
tests/boundary/cli/nativeSignatureCli.test.ts
|
||||
tests/boundary/mcp/nativeSignatureTargetBindingMcp.test.ts
|
||||
@@ -777,7 +792,8 @@ jobs:
|
||||
|
||||
required:
|
||||
name: CI required
|
||||
if: ${{ always() }}
|
||||
# Report failed dependencies, but release superseded PR concurrency slots.
|
||||
if: ${{ !cancelled() }}
|
||||
needs:
|
||||
[
|
||||
changes,
|
||||
@@ -804,7 +820,7 @@ jobs:
|
||||
nativeaot,
|
||||
website,
|
||||
]
|
||||
runs-on: ubuntu-latest
|
||||
runs-on: ubuntu-24.04
|
||||
timeout-minutes: 5
|
||||
steps:
|
||||
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
|
||||
|
||||
@@ -14,7 +14,7 @@ concurrency:
|
||||
jobs:
|
||||
pr-title:
|
||||
name: Conventional PR title
|
||||
runs-on: ubuntu-latest
|
||||
runs-on: ubuntu-24.04
|
||||
timeout-minutes: 2
|
||||
steps:
|
||||
- name: Validate title for Release Please
|
||||
|
||||
@@ -181,6 +181,10 @@ The separate GitHub Pages host uses only the manual
|
||||
|
||||
## Development feedback and PR verification
|
||||
|
||||
For routine merges, wait for the required checks to pass for the current PR
|
||||
revision. Administrators retain an override for deliberate maintainer recovery.
|
||||
If `main` is broken, prioritize a focused repair before updating affected PRs.
|
||||
|
||||
Select checks for the behavior changed. For a source edit:
|
||||
|
||||
```bash
|
||||
|
||||
@@ -48,6 +48,7 @@ export default defineConfig({
|
||||
{ text: "Android applications", link: "/android-analysis" },
|
||||
{ text: "Apple applications", link: "/apple-application-analysis" },
|
||||
{ text: "Firmware", link: "/firmware-analysis" },
|
||||
{ text: "iNES containers", link: "/ines-containers" },
|
||||
{ text: "SQLite databases", link: "/sqlite-databases" },
|
||||
{ text: "Packet captures", link: "/packet-captures" },
|
||||
{ text: "Signal recordings", link: "/signal-recordings" },
|
||||
|
||||
@@ -107,6 +107,47 @@ first navigation. For a dedicated investigation profile, add
|
||||
then describe an unloaded page; REA continues to require an allowed, committed
|
||||
URL. See [the startup investigation](https://github.com/morluto/rea/issues/1384#issuecomment-6093781686).
|
||||
|
||||
### Browsers without HTTP discovery
|
||||
|
||||
Some browsers expose a loopback browser WebSocket but no `/json/version` or
|
||||
`/json/list`. Chrome 144 and later can enable remote debugging on a running
|
||||
browser from `chrome://inspect/#remote-debugging`; this mode is reported to
|
||||
serve only the browser socket. Since Chrome 136, `--remote-debugging-port` is
|
||||
ignored for the default profile, so this is the remaining way to inspect a page
|
||||
in an existing profile.
|
||||
|
||||
For such a browser, pass the browser socket instead of the HTTP endpoint:
|
||||
|
||||
```bash
|
||||
rea list-browser-targets ws://127.0.0.1:9222/devtools/browser/<id>
|
||||
```
|
||||
|
||||
Chrome writes the port and the `/devtools/browser/<id>` path to the
|
||||
`DevToolsActivePort` file in its user data directory. REA does not read that
|
||||
file for you.
|
||||
|
||||
- Only `list_browser_targets`, `inspect_web_page`, `analyze_web_bundle`,
|
||||
`observe_web_session`, `discover_webmcp_tools`, and `capture_web_screenshot`
|
||||
accept a browser socket. Website runtime attribution, Electron inspection,
|
||||
and scenario attach mode still require HTTP discovery.
|
||||
- Each call opens one WebSocket and uses it for discovery
|
||||
(`Browser.getVersion`, `Target.getTargets`) and for the selected page.
|
||||
Discovery must finish within the same 10-second deadline as HTTP discovery.
|
||||
Chrome may ask you to approve each connection.
|
||||
- The browser identifier controls access to the socket. Evidence records the
|
||||
endpoint as `ws://127.0.0.1:9222/devtools/browser/[REDACTED]`.
|
||||
- `browser.revision` is the socket's `Browser.getVersion` value, such as
|
||||
`@e533e98…`. HTTP discovery reports `WebKit-Version`, such as
|
||||
`537.36 (@e533e98…)`.
|
||||
- `Target.getTargets` reports whether each target is attached. Chrome's
|
||||
`/json/list` can omit it, so HTTP discovery may report `attached` as `null`.
|
||||
- An existing profile can hold many unrelated pages. Target listing returns
|
||||
each eligible page's URL and title, so pass `--allowed-origins` to list only
|
||||
the origins you are investigating.
|
||||
|
||||
A browser driven only through `--remote-debugging-pipe` or a vendor's private
|
||||
automation channel has neither endpoint, and REA cannot attach to it.
|
||||
|
||||
## Request boundary
|
||||
|
||||
CDP connections enforce the shared 64 MiB limit per WebSocket message. A larger
|
||||
@@ -116,9 +157,13 @@ decoded strings or JSON objects.
|
||||
|
||||
Discovery supplies a literal loopback CDP endpoint and returns all eligible
|
||||
page targets unless an exact HTTP(S) origin filter narrows the result. Follow-up
|
||||
inspection requests select one target; their default scope is its current origin. `localhost`, private-LAN
|
||||
addresses, HTTPS CDP endpoints, credentials, paths, queries, fragments, and
|
||||
implicit ports are not valid CDP endpoints. Origin filters contain only scheme,
|
||||
inspection requests select one target; their default scope is its current origin.
|
||||
The endpoint is either `http://127.0.0.1:PORT` or a
|
||||
[browser socket](#browsers-without-http-discovery),
|
||||
`ws://127.0.0.1:PORT/devtools/browser/ID`; `[::1]` may replace `127.0.0.1`.
|
||||
`localhost`, private-LAN addresses, HTTPS and `wss:` endpoints, credentials,
|
||||
queries, fragments, implicit ports, and any other path are not valid CDP
|
||||
endpoints. Origin filters contain only scheme,
|
||||
host, and port; paths, credentials, queries, fragments, and wildcards are not
|
||||
valid origins.
|
||||
|
||||
|
||||
+28
@@ -214,8 +214,36 @@ Import an older source tree to compare with the current artifact:
|
||||
|
||||
```bash
|
||||
rea import-reference-source /absolute/path/to/source
|
||||
rea import-reference-source /absolute/path/to/source --detail summary --outline-depth 2 --json
|
||||
```
|
||||
|
||||
The default (`--detail full`) returns the complete `HistoricalSourceGraph`.
|
||||
Choose `--detail summary` for a `HistoricalSourceSummary` of that same committed
|
||||
inventory: its `HistoricalSourceManifest` contains the full graph and root
|
||||
digests, with provenance, VCS facts, languages, manifest paths, entry and
|
||||
relationship counts, parse-failure counts, file/directory states, exclusions
|
||||
and limitations. The summary is a presentation view, not a graph accepted by
|
||||
source-to-bundle comparison; keep the full output for that workflow.
|
||||
|
||||
`--outline-depth` requires `--detail summary` and accepts a nonnegative safe
|
||||
integer. Depth 1 shows root children, depth 2 (the default) also shows their
|
||||
children, and depth 0 omits all outline entries. Paths retain canonical Unicode
|
||||
code-point order. `outline.omitted_entry_count` counts only inventoried entries
|
||||
hidden by the chosen depth; it does not count unexamined children of excluded or
|
||||
unreadable directories, or change `inventory_state`. Exclusions and source
|
||||
limitations remain separate from this presentation omission.
|
||||
|
||||
`file_sizes.known_bytes` is the exact sum of known inventoried file sizes as
|
||||
decimal text, so large sums cannot lose integer precision. Unknown sizes count
|
||||
in `file_sizes.unknown_file_count`; excluded or unexamined paths are not included
|
||||
in that total. A zero known-byte sum therefore does not establish an empty source
|
||||
tree. Full output retains individual file hashes, relationships and parse-failure
|
||||
diagnostics. Summary mode performs the same import and cleanup, then projects
|
||||
the committed result without rereading source files. It reduces the selected
|
||||
output, not the amount of source examined. A shallow tree or many exclusions can
|
||||
still produce a large summary; depth 0 removes the outline but preserves the
|
||||
other facts. No fixed output-size or runtime improvement is promised.
|
||||
|
||||
The import records hashes and metadata for the supplied files, separately
|
||||
from observations of the current app. For a directory inside a Git checkout,
|
||||
it records the HEAD of the nearest enclosing repository; whether the working
|
||||
|
||||
@@ -0,0 +1,183 @@
|
||||
# Verify real HTTP/3 MITM captures
|
||||
|
||||
This optional Linux laboratory checks native mitmproxy captures through REA's
|
||||
public CLI and MCP. It changes no runtime contracts or adapters and establishes
|
||||
only the specific producer, mode and clients exercised here.
|
||||
|
||||
## Prepare a disposable guest
|
||||
|
||||
The exercised image is [Omarchy 4.0.4, build 440](https://nightly.omarchy.org/stable/4.0.4/440/omarchy-4.0.4.qcow2),
|
||||
SHA-256 `43412b896fe3d730e373a51a8acf99343d7c3e6dee78aa9f9bd7fca181127264`.
|
||||
Download it without installing guest packages on the host, check its digest,
|
||||
and use a **new qcow2 overlay** with that file as a read-only backing image.
|
||||
The matching [boot artifacts](https://nightly.omarchy.org/stable/4.0.4/440/unpacked/)
|
||||
include the kernel, initrd, cmdline and upstream vm-boot recipe. Use a fresh SSH
|
||||
key, loopback forwarding and guest disk; do not reuse another investigation's
|
||||
writable overlay or host trust configuration. Shut the guest down before
|
||||
switching overlays. Preserve the image and boot artifact hashes with evidence.
|
||||
|
||||
This sealed guest already supplies cURL 8.22.0 with OpenSSL 3.6.4, ngtcp2 1.25.0,
|
||||
nghttp3 1.18.0 and nghttp2 1.70.0. **No guest rolling package upgrade is needed.**
|
||||
Run `curl --version` and verify HTTP2 and HTTP3 features before starting. A stock
|
||||
cURL from another distribution may omit HTTP/3. For a different guest, building
|
||||
cURL requires a compatible TLS library, ngtcp2 and nghttp3; follow the
|
||||
[official build instructions](https://curl.se/docs/http3.html), install to a guest
|
||||
private prefix, and record exact source revisions and build inputs. That alternative
|
||||
has not been exercised by this laboratory; it is not the pinned reproduction path.
|
||||
|
||||
Use a fresh VM overlay over a sealed Linux image. Use user-mode networking with
|
||||
SSH forwarding bound to host loopback; keep host directories unmounted. Install
|
||||
and build dependencies inside the guest, then remove its default route before
|
||||
generating traffic. Host trust, routes and installed packages stay unchanged.
|
||||
|
||||
Record the image digest, REA source revision and these dependency versions:
|
||||
|
||||
- REA's `.nvmrc`, `package.json#packageManager` and locked npm dependencies.
|
||||
- Official Linux x86_64 mitmproxy **12.2.3** standalone archive. SHA-256:
|
||||
`2e95286b618fa6fd33e5e62a78c2e5112571d85f42ec2bac29b97ee242bdb5c5`.
|
||||
- A private Python virtual environment using the complete pinned graph in
|
||||
`scripts/fixtures/http3-lab-requirements.txt`. Save `pip freeze` and build/download logs.
|
||||
- OpenSSL and cURL advertising HTTP3 and HTTP2 in `curl --version`.
|
||||
|
||||
The verified guest used Python 3.14.7, cURL 8.22.0, ngtcp2 1.25.0 and nghttp3
|
||||
1.18.0. Other dependency profiles need verification. Back up the guest's
|
||||
`/etc/hosts` before adding `127.0.0.1 lab.test`. Reserve guest TCP/UDP loopback
|
||||
ports 18443 and 19443. These changes belong only to the disposable guest.
|
||||
|
||||
From the guest REA checkout, use its pinned Node/npm toolchain:
|
||||
|
||||
```sh
|
||||
npm ci
|
||||
npm run build:cached
|
||||
python3 -m venv /absolute/lab/venv
|
||||
/absolute/lab/venv/bin/pip install --no-deps -r scripts/fixtures/http3-lab-requirements.txt
|
||||
/absolute/lab/venv/bin/pip check
|
||||
/absolute/lab/venv/bin/pip freeze > /absolute/lab/python-requirements.txt
|
||||
```
|
||||
|
||||
Before removing the guest default route, download the official mitmproxy archive
|
||||
and verify it, then extract to the guest's private tools directory:
|
||||
|
||||
```sh
|
||||
mkdir -p /absolute/lab/tools
|
||||
curl --fail --location https://downloads.mitmproxy.org/12.2.3/mitmproxy-12.2.3-linux-x86_64.tar.gz \
|
||||
--output /absolute/lab/mitmproxy.tar.gz
|
||||
printf '%s %s\n' 2e95286b618fa6fd33e5e62a78c2e5112571d85f42ec2bac29b97ee242bdb5c5 \
|
||||
/absolute/lab/mitmproxy.tar.gz | sha256sum --check --strict
|
||||
tar -xzf /absolute/lab/mitmproxy.tar.gz -C /absolute/lab/tools
|
||||
/absolute/lab/tools/mitmdump --version
|
||||
```
|
||||
|
||||
Pin the REA revision with `git rev-parse HEAD` or archive SHA-256. Build using
|
||||
the exact `.nvmrc` and npm version; do not copy a different checkout's `dist`.
|
||||
For stronger offline dependency reproduction, preserve downloaded Python
|
||||
archives, their digests and built wheels along with the image and toolchain.
|
||||
The requirement versions pin the runtime graph, not every transient build tool;
|
||||
source builds and alternate interpreters are not guaranteed byte-identical.
|
||||
|
||||
## Run the narrow profile
|
||||
|
||||
Select absolute executables and a new evidence directory. The producer refuses
|
||||
to reuse a directory. No certificates are installed in a system trust store;
|
||||
clients and proxy receive explicit paths to freshly generated test CAs.
|
||||
|
||||
```sh
|
||||
REA_MITMDUMP_COMMAND=/absolute/lab/tools/mitmdump \
|
||||
REA_HTTP3_PYTHON_COMMAND=/absolute/lab/venv/bin/python \
|
||||
npm run verify:web:http3 -- /absolute/evidence/run-1
|
||||
```
|
||||
|
||||
The producer sends three concurrent binary POSTs on one HTTP/3 connection to the
|
||||
same URL through mitmproxy reverse mode to an aioquic HTTP/3 origin. The origin
|
||||
waits for all complete requests, then dispatches responses in reverse order of
|
||||
completion at the origin. QUIC stream send/receive orders need not coincide. A cURL HTTP/3-only
|
||||
request checks a second client implementation. Mitmproxy's real save addon
|
||||
writes `normal.mitm`; no native flows are synthesized.
|
||||
|
||||
A second proxy run disables HTTP/3. cURL `--http3` falls back to HTTP/2, reaching
|
||||
an HTTP/1.1 TLS test origin. `fallback.mitm` must retain those lower protocols,
|
||||
so a successful HTTP request cannot masquerade as an HTTP/3 success.
|
||||
|
||||
## Acceptance and evidence
|
||||
|
||||
Each execution creates `verifications/<run-UUID>/` with its own diagnostics.
|
||||
`verification-latest.json` belongs to the most recently registered attempt and
|
||||
changes atomically from `running` to `passed` or `failed`. Registration and
|
||||
the ownership check/replacement use the same SQLite transaction lock. An older
|
||||
attempt finishing later keeps its own reports without replacing the marker.
|
||||
The `.verification-lock.sqlite` pathname must remain in place while attempts
|
||||
may run; SQLite releases the lock on connection close or process death.
|
||||
Lock acquisition waits for the current owner without a timeout or lease
|
||||
stealing. The verifier has per-command deadlines, but no overall run deadline;
|
||||
a live stalled lock owner can therefore delay publication until it exits.
|
||||
Only a successful attempt writes its own `verification.json`, after
|
||||
all cleanup and input-integrity checks. `result.json` also records failures and
|
||||
the original error separately from cleanup errors. Older successes remain in
|
||||
identified history; a legacy root `verification.json` is archived before a rerun.
|
||||
A killed verifier may leave `running`, which must never be interpreted as success.
|
||||
|
||||
Capture inputs live in `captures/`. To inspect them again without new traffic:
|
||||
|
||||
```sh
|
||||
REA_MITMDUMP_COMMAND=/absolute/lab/tools/mitmdump \
|
||||
npm run verify:web:http3 -- /absolute/evidence/run-1 --inspect-existing
|
||||
```
|
||||
|
||||
Acceptance for the current run:
|
||||
|
||||
- Every positive native record reports HTTP/3, UDP, ALPN h3 and successful TLS
|
||||
timestamps on both legs. Connection IDs, producer TLS labels, exact TLS setup
|
||||
timestamps and connection errors match the UUID-matched producer observation
|
||||
on each leg. Endpoint handshakes independently observe QUIC v1.
|
||||
- Native flow UUIDs remain distinct. Three endpoint streams share a connection
|
||||
on each leg. Origin dispatch reverses completed receipt. Client and capture
|
||||
ordering is observed, while association is verified independent of their order.
|
||||
- CLI and MCP agree. Request/response bytes, lengths, SHA-256, ordered duplicate
|
||||
headers, method, scheme, authority and path match independent observations.
|
||||
Readable header names and values, request URL fields and ALPN also match;
|
||||
non-UTF-8 header bytes retain a null display value rather than replacement text.
|
||||
- Actual MCP advertised schemas validate, Evidence preserves source digests and
|
||||
provider provenance, and the complete returned Evidence matches the retained MCP session records.
|
||||
- The fallback capture reports client HTTP/2 over TCP and origin HTTP/1.1, with
|
||||
cURL independently reporting version 2. Input files remain unchanged.
|
||||
- Every cleanup action is attempted on success and failure, and final lineage
|
||||
contains no live descendants. Recorded producer groups are inspected separately
|
||||
after token-verified cleanup, including after their launcher has exited.
|
||||
|
||||
Retain captures, endpoint/producer JSONL, proxy diagnostics, cURL output, manifest,
|
||||
CLI/MCP output, advertised schema and session bundle. Export public certificates
|
||||
and dependency/source provenance separately. Do not commit evidence, private
|
||||
keys, dependencies or VM disks. Shut down the guest after exporting evidence.
|
||||
|
||||
The reverse proxy can preserve authority `lab.test:18443` while recording origin
|
||||
port 19443. Mitmproxy's serialized flow/connection UUIDs are not stream IDs.
|
||||
Endpoint stream IDs are scoped observations; this test invents no cross-leg
|
||||
mapping. Mitmproxy 12.2.3's `QUICv1` label alone does not prove negotiation: the
|
||||
fixture checks the negotiated `_quic._version` in pinned aioquic 1.2.0.
|
||||
|
||||
Coverage is native capture, Linux reverse mode, QUIC v1 and these clients.
|
||||
Empty/absent/incomplete/redacted body semantics, cancellations, resets,
|
||||
certificate failures, malformed captures, HAR and qlog are separate increments.
|
||||
Local/WireGuard, browsers, QUIC v2, migration, 0-RTT, mTLS, replay, sustained load
|
||||
and loss tolerance remain unverified by this profile. Passing it does not
|
||||
establish general HTTP/3 support in REA.
|
||||
|
||||
Official references: [mitmproxy protocol support](https://github.com/mitmproxy/mitmproxy/blob/v12.2.3/docs/src/content/concepts/protocols.md),
|
||||
[HTTP/3 implementation](https://github.com/mitmproxy/mitmproxy/blob/v12.2.3/mitmproxy/proxy/layers/http/_http3.py),
|
||||
[serialized HTTP state](https://github.com/mitmproxy/mitmproxy/blob/v12.2.3/mitmproxy/http.py),
|
||||
[aioquic configuration](https://github.com/aiortc/aioquic/blob/1.2.0/src/aioquic/quic/configuration.py).
|
||||
|
||||
## Verifier regressions
|
||||
|
||||
After building REA, run these inside the same isolated guest:
|
||||
|
||||
```sh
|
||||
node --test scripts/lib/http3-verifier-lifecycle.test.mjs scripts/lib/http3-capture-assertions.test.mjs
|
||||
/absolute/lab/venv/bin/python scripts/fixtures/http3-lab.test.py
|
||||
```
|
||||
|
||||
These cover different QUIC stream completion orders, stale success reports,
|
||||
multiple failed closes, separately owned process groups and partially acquired
|
||||
resources, plus producer TLS fact mismatches on both legs and altered readable
|
||||
fields with unchanged binary evidence. They test verifier
|
||||
semantics; they do not add HTTP/3 provider coverage.
|
||||
@@ -0,0 +1,72 @@
|
||||
# Classic iNES container inspection
|
||||
|
||||
REA recognizes classic iNES from the `NES` + `0x1a` byte signature, independently
|
||||
of the file extension. This read-only container inspection uses portable
|
||||
Node.js file reads; it needs neither Ghidra nor an emulator.
|
||||
|
||||
```bash
|
||||
rea inspect-artifact ./cartridge.nes --json
|
||||
rea extract-artifact ./cartridge.nes --json
|
||||
```
|
||||
|
||||
Through MCP, call `open_binary` with the local path, then `inspect_artifact`.
|
||||
Use `extract_artifact` to materialize the regions in the fresh directory named
|
||||
by its result. The caller owns that successful extraction directory.
|
||||
|
||||
## Header and file regions
|
||||
|
||||
Inspection returns `container-header` and `reconstruction` observations inline.
|
||||
The single inventory Evidence under `substeps[].evidence.normalized_result`
|
||||
contains the complete graph and an `ines` object:
|
||||
|
||||
- `ines.header`: original 16-byte `header_hex`, PRG/CHR file-unit counts, mapper,
|
||||
raw flags 6/7, trainer and battery flags, and the declared mirroring mode.
|
||||
- `occurrences[]`: each region's path, `source_location.offset` and
|
||||
`source_location.length` in the original container. Follow `artifact_id` to
|
||||
the node's observed SHA-256 and byte count.
|
||||
- `ines.reconstruction`: ordered region paths, concatenated byte count,
|
||||
SHA-256 and `verified: true`. REA accumulates the concatenation digest during
|
||||
the same physical-order region scan that produces node hashes, then compares
|
||||
it with the original whole-file digest. Final source freshness is also checked.
|
||||
No reconstructed file is written during inspection.
|
||||
|
||||
Regions are `header.bin`, optional `trainer.bin` (512 bytes),
|
||||
`prg/000.bin` onward (16 KiB each), `chr/000.bin` onward (8 KiB each), and
|
||||
optional `trailing.bin`. Every input byte is retained, including unused header
|
||||
fields and uninterpreted trailing data. Zero CHR-ROM units create no CHR region;
|
||||
REA does not fabricate CHR-RAM contents.
|
||||
|
||||
After extraction, concatenate the materialized files in
|
||||
`ines.reconstruction.region_order` from the inspection inventory. Their bytes
|
||||
reproduce the input exactly. Graph path order is lexical and is not physical
|
||||
file order; use the explicit region order or source offsets.
|
||||
|
||||
## Supported boundary
|
||||
|
||||
This increment supports classic iNES with a complete 16-byte header, nonzero
|
||||
PRG count, complete declared trainer/PRG/CHR payload, and zero reserved bytes
|
||||
12–15. Dirty legacy headers are refused because their upper mapper bits are
|
||||
ambiguous; REA does not silently repair them. NES 2.0 and UNIF signatures,
|
||||
unsupported header variants and truncated payloads are explicitly refused.
|
||||
An arbitrary file named `.nes` is not admitted as iNES.
|
||||
|
||||
The PRG/CHR units describe file storage, not mapper bank sizes or CPU windows.
|
||||
The mapper number and flags are header declarations, not proof of cartridge
|
||||
hardware or runtime behavior. Bank switching, 6502/65816 disassembly, emulator
|
||||
sessions and interpretation of console-specific trailing data remain outside
|
||||
this lane. Raw-binary Ghidra analysis is a separate workflow. This container
|
||||
increment addresses the first milestone of [#2072](https://github.com/morluto/rea/issues/2072);
|
||||
the related [#1641](https://github.com/morluto/rea/issues/1641) tracks 6502/65816
|
||||
native analysis with explicit load addresses and provider limitations. Extracted
|
||||
PRG units still need caller-selected CPU windows before static code analysis;
|
||||
their physical file offsets do not establish those addresses.
|
||||
|
||||
Source-owned byte fixtures verify original offsets and hashes, extraction and
|
||||
byte-exact reconstruction, CLI/stdio MCP parity, malformed/unsupported inputs,
|
||||
failed target-switch recovery, cancellation and source identity. These checks
|
||||
do not establish emulator behavior or compatibility with every historical ROM.
|
||||
The portable CLI/stdio MCP acceptance and source-identity checks run in Linux
|
||||
and macOS CI. The same workflows have also been executed on native Windows x64.
|
||||
|
||||
Format references: [iNES](https://www.nesdev.org/wiki/INES) and
|
||||
[NES 2.0](https://www.nesdev.org/wiki/NES_2.0).
|
||||
+26
-19
@@ -51,7 +51,7 @@ Bir uygulamada kendi ürününüze eklemek istediğiniz bir özellik mi gördün
|
||||
|
||||
REA, ajanınızı yerel makine kodu içeren ikili dosyaları, JavaScript ve Electron uygulamalarını, .NET derlemelerini ve web sitelerini inceleyen araçlara bağlar. Aynı araçları terminalden de kullanabilirsiniz. Analiz yerel olarak çalışır; sonuçlar her çıkarımın dayandığı kanıtları ve sınırlamaları içerir.
|
||||
|
||||
Kurulum, REA'yı ajanınıza kaydeder ve uyumlu iş akışı talimatlarını yükler. Yerel makine kodu analizi mevcut bir Hopper veya Ghidra kurulumunu kullanabilir; kurulum işlemi, onayınızla isteğe bağlı olarak Hopper da yükleyebilir. Statik JavaScript analizi bu iki motora da ihtiyaç duymaz.
|
||||
Kurulum, REA'yı ajanınıza kaydeder ve uyumlu iş akışı talimatlarını yükler. Yerel makine kodu analizi mevcut bir Hopper, Ghidra veya IDA kurulumunu kullanabilir; kurulum işlemi, onayınızla isteğe bağlı olarak Hopper da yükleyebilir. Statik JavaScript analizi bu yerel analiz motorlarından hiçbirine ihtiyaç duymaz.
|
||||
|
||||
> Kurulum talimatları, görselli rehberler ve gerçek örnek çalışmalar için **[REA web sitesini ziyaret edin](https://rea.tools/tr/)**.
|
||||
|
||||
@@ -100,12 +100,14 @@ Yerel makine kodu analizi için önce bir sağlayıcı yapılandırın. Yerel an
|
||||
|
||||
REA hızla değişir ve yeni sürümler sık sık hata düzeltmeleri içerir. Kurulumunuzu güncel tutun.
|
||||
|
||||
npm ile yüklenen CLI için:
|
||||
`npm install --global` veya `bun add --global` ile yüklenen CLI için:
|
||||
|
||||
```bash
|
||||
rea update
|
||||
```
|
||||
|
||||
Bun ile yapılan global güncellemeler için Bun 1.2.17 veya üzeri gerekir. Daha eski bir Bun sürümünü kullanıyorsanız `rea update` komutunu çalıştırmadan önce Bun'u manuel olarak yükseltin.
|
||||
|
||||
Ajan kayıtlarını ve skill'i güncellemek için güncellemenin çıktısında gösterilen kurulum komutunu çalıştırın.
|
||||
|
||||
`npx` kullanıyorsanız ajan kurulumunu şu komutla güncelleyin:
|
||||
@@ -114,7 +116,7 @@ Ajan kayıtlarını ve skill'i güncellemek için güncellemenin çıktısında
|
||||
npx rea-agents@latest setup
|
||||
```
|
||||
|
||||
Kurulum değişikliklerini inceleyin ve ajanınızı yeniden başlatın. Tek seferlik CLI işlemleri için `npx rea-agents@latest` komutunun ardından istediğiniz komutu yazın.
|
||||
Kurulum değişikliklerini inceleyin ve ajanınızı yeniden başlatın. Tek seferlik CLI işlemleri için `npx rea-agents@latest` komutunun ardından istediğiniz komutu yazın. Bun kullanıyorsanız `npx rea-agents@latest` yerine `bunx rea-agents@latest` kullanın.
|
||||
|
||||
## REA nasıl çalışır
|
||||
|
||||
@@ -134,12 +136,14 @@ REA; Node.js 22.x (>=22.19), 24.x (>=24.11) veya 26+ ve npm gerektirir. Ek araç
|
||||
| --------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Yerel makine kodu içeren ikili dosyalar | Sözde kod, assembly kodu, dizeler, semboller, çağrılar ve referanslar | Hopper, Ghidra veya IDA; [yerel kod analizi](https://rea.tools/tr/guides/native/) |
|
||||
| Çevrimdışı ELF yapısı | Bölümler, segmentler, özgün semboller/yeniden konumlandırmalar ve statik analizden olası güvenlik önlemleri | Linux x64 üzerinde çağıranın sağladığı pwntools; [ikili dosya tanılama](../binary-diagnostics.md) |
|
||||
| Go ikili dosyaları | Gömülü compiler sürümü, modüller, replacement'lar ve build ayarları | Yerleşik statik ELF/PE/thin Mach-O incelemesi; Go kurulumu gerekmez |
|
||||
| WASM artefaktı | Doğrulama, bölümler, tam import/export WAT biçimleri ve decode edilmiş WAT | Çağıranın sağladığı WABT 1.0.42; `inspect_wasm_artifact` |
|
||||
| EVM bayt kodu | Yönlendirme seçicileri, bayt ofsetleri, çıkarımla belirlenen argümanlar ve durum değiştirilebilirliği | Linux x64 üzerinde yerel ham bayt/onaltılık girdi; [çevrimdışı EVM rehberi](../evm-bytecode.md) |
|
||||
| SQLite veritabanları | Tablolar, sütunlar, index'ler, view'lar, trigger'lar ve seçilen sıradan tablo satırları | Yerel database/WAL snapshot'ı; native SQLite sınırlarıyla Node.js 24.x >=24.15 veya 26+ |
|
||||
| Kaydedilmiş Linux çökmeleri | Ham note kayıtları, kaydedilen her iş parçacığının yazmaçları/sinyalleri ve isteğe bağlı eşleme adayları | Linux x64 üzerinde çağıranın sağladığı pwntools; isteğe bağlı GDB/pwndbg; [kaydedilmiş çökmeler](../recorded-crashes.md) |
|
||||
| JavaScript / Electron | Modüller, içe aktarmalar, kaynak haritaları, rotalar, IPC ve yerel eklenti ilişkileri | Node.js ve npm; [uygulama analizi](https://rea.tools/tr/guides/javascript/) |
|
||||
| Web siteleri | Sayfa yapısı, betikler, ağ gözlemleri ve istenen ekran görüntüleri | Chrome ailesinden bir tarayıcı; [tarayıcı analizi](https://rea.tools/tr/guides/browser/) |
|
||||
| Kaydedilmiş ağ yakalamaları | İstekler, yanıtlar, erişilebilir yük içerikleri ve kaynak konumları | HAR; mitmproxy'nin kendi biçimindeki yakalamalar için Linux üzerinde mitmdump; [ağ yakalama rehberi](../web-network-captures.md) |
|
||||
| Paket yakalamaları | Uç noktalar, DNS, TLS SNI, protokol dağılımı ve HTTP istekleri | Çağıranın sağladığı tshark ve capinfos; [pcap rehberi](../pcap-analysis.md) |
|
||||
| Kaydedilmiş ağ yakalamaları | İstekler, yanıtlar, erişilebilir yük içerikleri ve kaynak konumları | HAR veya Fiddler Everywhere SAZ; Linux'ta native mitmproxy için mitmdump; [ağ yakalama rehberi](../web-network-captures.md) |
|
||||
| .NET derlemeleri | Meta veriler, CIL talimatları, bildirilmiş yerel bağımlılıklar ve derleme karşılaştırmaları | Statik inceleme; [yönetilen kod rehberi](../managed-code-analysis.md) |
|
||||
| Android APK'leri | Manifest bildirimleri, sınıflar, tersine derlenmiş metotlar ve referanslar | Linux/macOS/Windows x64 üzerinde arayüzsüz JADX ve tam bir JDK; [Android rehberi](../android-analysis.md) |
|
||||
| Android cihazları | Cihazlar, paketler, süreçler, günlükler, dökümler, ekran görüntüleri ve APK/dosya aktarımları | Çağıranın sağladığı adb (emülatör veya cihaz); [ADB rehberi](../adb-device-analysis.md) |
|
||||
@@ -148,6 +152,7 @@ REA; Node.js 22.x (>=22.19), 24.x (>=24.11) veya 26+ ve npm gerektirir. Ek araç
|
||||
| Flutter uygulamaları | Dart anlık görüntü karması, ABI başına kitaplık özetleri ve motor derleme kökeni | Yok (statik APK çözümleme); [Flutter rehberi](../flutter-analysis.md) |
|
||||
| Donanım yazılımı | Bölgeler, çıkarma sonuçları ve yerel kod analizine devirler | Linux üzerinde Binwalk / Unblob; [donanım yazılımı rehberi](../firmware-analysis.md) |
|
||||
| Kaydedilmiş paketler | Seçilen alanlar, yinelenen değerler, filtreler ve çözümleme kuralları | Linux: TShark 4.x + prlimit; [yakalama kılavuzu](../packet-captures.md) |
|
||||
| Paket özetleri | Uç noktalar, DNS, TLS SNI, protokol dağılımı ve HTTP istekleri | Çağıranın sağladığı tshark ve capinfos (Linux üzerinde doğrulandı); [pcap rehberi](../pcap-analysis.md) |
|
||||
| Kaydedilmiş mantık sinyalleri | Kod çözücü açıklamaları, örnek aralıkları ve tanılama | Linux: sigrok-cli 0.7.2 + prlimit; [sinyal kılavuzu](../signal-recordings.md) |
|
||||
| Paketler ve kaynaklar | Dosya envanterleri, özet değerleri, plist'ler, Apple paket yapısı ve çıkarılmış kaynaklar | [Artefakt ve JavaScript rehberi](../javascript-artifact-reconstruction.md), [Apple uygulamaları](../apple-application-analysis.md) |
|
||||
| Süreç davranışı | Terminal çıktısı, etkileşimler, sonlanma ve dosya sistemi gözlemleri, çalıştırma karşılaştırmaları | Yerel PTY ile Linux/macOS; [süreç yakalama](../process-capture.md) |
|
||||
@@ -156,7 +161,7 @@ Statik JavaScript ve .NET incelemesi, uygulamayı çalıştırmadan sağlanan do
|
||||
|
||||
<a id="choosing-a-deep-analysis-provider"></a>
|
||||
|
||||
Yerel makine kodu içeren ikili dosya biçimleri ve ana bilgisayar desteği sağlayıcıya göre değişir. [Hopper ve Ghidra kurulumu](../installation.md#hopper), [IDA rehberi](../ida-provider.md) ve [Windows için deneysel Ghidra desteği](../windows-ghidra-p0.md) belgelerine bakın. Ghidra ayrıca [16 bit DOS analizini](../ghidra-dos.md) destekler. Sağlayıcı seçimi için [CLI rehberine](../cli.md#choose-a-provider) bakın. En son npm sürümünden sonra eklenen özellikler için [sürümlerde kullanılabilirliği](../installation.md#released-package-and-main) kontrol edin.
|
||||
Yerel makine kodu içeren ikili dosya biçimleri ve ana bilgisayar desteği sağlayıcıya göre değişir. [Hopper ve Ghidra kurulumu](../installation.md#hopper), isteğe bağlı native MCP bridge'i de açıklayan [IDA rehberi](../ida-provider.md) ve [Windows için deneysel Ghidra desteği](../windows-ghidra-p0.md) belgelerine bakın. Ghidra ayrıca [16 bit DOS analizini](../ghidra-dos.md) destekler. Büyük ikili dosyalar için sağlayıcının başlatma zaman aşımını `REA_GHIDRA_STARTUP_TIMEOUT_MS` veya `REA_HOPPER_STARTUP_TIMEOUT_MS` ile artırın. Sağlayıcı seçimi için [CLI rehberine](../cli.md#choose-a-provider) bakın. En son npm sürümünden sonra eklenen özellikler için [sürümlerde kullanılabilirliği](../installation.md#released-package-and-main) kontrol edin.
|
||||
|
||||
## Örnek çalışmalar
|
||||
|
||||
@@ -280,9 +285,9 @@ Sorumlu kullanım yönergeleri için [DISCLAIMER.md](../../DISCLAIMER.md) dosyas
|
||||
|
||||
REA; yasal araştırma, eğitim, birlikte çalışabilirlik, yazılımın korunması ve sahibi olduğunuz ya da inceleme yetkiniz bulunan yazılımların analizi için tasarlanmıştır.
|
||||
|
||||
The project's position on illegal or unauthorized use covers all REA
|
||||
versions, distribution channels, and platforms; each copy retains its
|
||||
applicable licenses.
|
||||
Projenin yasa dışı veya yetkisiz kullanıma ilişkin tutumu tüm REA sürümleri,
|
||||
dağıtım kanalları ve platformlar için geçerlidir; her kopya geçerli lisanslarını
|
||||
korur.
|
||||
|
||||
## Katkıda bulunma
|
||||
|
||||
@@ -294,14 +299,16 @@ Geliştirme ortamı ve kontroller için [CONTRIBUTING.md](../../CONTRIBUTING.md)
|
||||
|
||||
[MIT](../../LICENSE)
|
||||
|
||||
REA-authored code is licensed under MIT. Third-party material retains its own
|
||||
licenses and copyright notices; see [Third-party notices](../../THIRD_PARTY_NOTICES.md)
|
||||
for the dependency inventory, preserved license texts, and external-tool terms.
|
||||
REA tarafından yazılan kod MIT lisansı altında lisanslanır. Üçüncü taraf
|
||||
materyaller kendi lisanslarını ve telif hakkı bildirimlerini korur; bağımlılık
|
||||
envanteri, korunan lisans metinleri ve harici araç koşulları için [Üçüncü taraf
|
||||
bildirimleri](../../THIRD_PARTY_NOTICES.md) dosyasına bakın.
|
||||
|
||||
**You must legally obtain and be authorized to use commercial tools**, including
|
||||
IDA Pro / Hex-Rays decompilers, Hopper, and JEB, under their applicable licenses.
|
||||
REA grants no tool license, key, or activation entitlement. Trials and demos
|
||||
remain subject to vendor terms, including user, feature, automation, and output
|
||||
sharing restrictions. Cracked copies, stolen keys, unauthorized key sharing,
|
||||
and bypassing license restrictions are not authorized. This guidance does not
|
||||
amend MIT or third-party licenses.
|
||||
**IDA Pro / Hex-Rays decompiler'ları, Hopper ve JEB dahil olmak üzere ticari
|
||||
araçları yasal olarak edinmeli ve ilgili lisanslar kapsamında kullanma
|
||||
yetkiniz olmalıdır.** REA hiçbir araç lisansı, anahtarı veya etkinleştirme hakkı
|
||||
vermez. Deneme sürümleri ve demolar; kullanıcı, özellik, otomasyon ve çıktı
|
||||
paylaşımı kısıtlamaları dahil olmak üzere satıcı koşullarına tabidir. Kırılmış
|
||||
kopyalar, çalınmış anahtarlar, yetkisiz anahtar paylaşımı ve lisans
|
||||
kısıtlamalarını aşma yetkili kullanım kapsamında değildir. Bu yönlendirme MIT
|
||||
veya üçüncü taraf lisanslarını değiştirmez.
|
||||
|
||||
@@ -51,7 +51,7 @@
|
||||
|
||||
REA 將 AI 代理連接到分析工具,用於檢查原生二進位檔案、JavaScript 和 Electron 應用、.NET 程式集以及網站。你也可以在終端中使用同樣的工具。分析在本機執行,結果包含支撐各項結論的證據和相關限制。
|
||||
|
||||
設定流程會向 AI 代理註冊 REA,並安裝對應的工作流程指引。原生分析可以使用已有的 Hopper 或 Ghidra;設定流程也可以在你核准後安裝 Hopper。靜態 JavaScript 分析不需要這兩個引擎。
|
||||
設定流程會向 AI 代理註冊 REA,並安裝對應的工作流程指引。原生分析可以使用已有的 Hopper、Ghidra 或 IDA;設定流程也可以在你核准後安裝 Hopper。靜態 JavaScript 分析不需要原生分析引擎。
|
||||
|
||||
> **[訪問 REA 網站](https://rea.tools/zh-TW/)**,查看設定說明、圖解指南和真實案例。
|
||||
|
||||
@@ -100,12 +100,14 @@ rea --help
|
||||
|
||||
REA 更新較快,新版本經常包含錯誤修復。請將安裝的版本保持最新。
|
||||
|
||||
通過 npm 安裝的 CLI 使用:
|
||||
通過 `npm install --global` 或 `bun add --global` 安裝的 CLI 使用:
|
||||
|
||||
```bash
|
||||
rea update
|
||||
```
|
||||
|
||||
Bun 全域更新需要 Bun 1.2.17 或更新版本。如果使用較舊的 Bun 版本,請先手動升級 Bun,再執行 `rea update`。
|
||||
|
||||
要更新 AI 代理註冊和 skill,請執行更新命令輸出的設定命令。
|
||||
|
||||
如果使用 `npx`,通過以下命令更新 AI 代理設定:
|
||||
@@ -114,7 +116,7 @@ rea update
|
||||
npx rea-agents@latest setup
|
||||
```
|
||||
|
||||
檢查設定變更並重新啟動 AI 代理。單次 CLI 操作可使用 `npx rea-agents@latest`,後接所需命令。
|
||||
檢查設定變更並重新啟動 AI 代理。單次 CLI 操作可使用 `npx rea-agents@latest`,後接所需命令。使用 Bun 時,用 `bunx rea-agents@latest` 代替 `npx rea-agents@latest`。
|
||||
|
||||
## REA 的工作原理
|
||||
|
||||
@@ -134,6 +136,8 @@ REA 需要 Node.js 22.x(>=22.19)、24.x(>=24.11)或 26+,以及 npm。
|
||||
| --------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
|
||||
| 原生二進位檔案 | 偽程式碼、組合語言、字串、符號、呼叫和引用 | Hopper、Ghidra 或 IDA;[原生分析](https://rea.tools/zh-TW/guides/native/) |
|
||||
| 離線 ELF 佈局 | 節、段、原始符號/重定位資訊及靜態防護機制候選項 | Linux x64 上由呼叫方提供的 pwntools;[二進位診斷](../binary-diagnostics.md) |
|
||||
| Go 二進位檔案 | 內嵌編譯器版本、模組、替換項和建置設定 | 內建靜態 ELF/PE/thin Mach-O 檢查;無需安裝 Go |
|
||||
| WASM 工件 | 驗證、節、精確的匯入/匯出 WAT 形式及解碼後的 WAT | 呼叫方提供的 WABT 1.0.42;`inspect_wasm_artifact` |
|
||||
| EVM 位元組碼 | 分派選擇器、位元組偏移、推斷的參數和狀態可變性 | Linux x64 上的本地原始位元組/十六進位輸入載體;[離線 EVM 指南](../evm-bytecode.md) |
|
||||
| 已記錄的 Linux 崩潰 | 原始 note 記錄、每個已記錄執行緒的暫存器/訊號及可選的對映候選項 | Linux x64 上由呼叫方提供的 pwntools;可選的 GDB/pwndbg;[已記錄崩潰](../recorded-crashes.md) |
|
||||
| JavaScript / Electron | 模組、匯入、source map、路由、IPC 和原生附加元件關係 | Node.js 和 npm;[應用分析](https://rea.tools/zh-TW/guides/javascript/) |
|
||||
|
||||
@@ -51,7 +51,7 @@
|
||||
|
||||
REA 将智能体连接到分析工具,用于检查原生二进制文件、JavaScript 和 Electron 应用、.NET 程序集以及网站。你也可以在终端中使用同样的工具。分析在本机运行,结果包含支撑各项结论的证据和相关限制。
|
||||
|
||||
设置流程会向智能体注册 REA,并安装匹配的工作流指引。原生分析可以使用已有的 Hopper 或 Ghidra;设置流程也可以在你批准后安装 Hopper。静态 JavaScript 分析不需要这两个引擎。
|
||||
设置流程会向智能体注册 REA,并安装匹配的工作流指引。原生分析可以使用已有的 Hopper、Ghidra 或 IDA;设置流程也可以在你批准后安装 Hopper。静态 JavaScript 分析不需要原生分析引擎。
|
||||
|
||||
> **[访问 REA 网站](https://rea.tools/zh-CN/)**,查看设置说明、图解指南和真实案例。
|
||||
|
||||
@@ -100,12 +100,14 @@ rea --help
|
||||
|
||||
REA 更新较快,新版本经常包含错误修复。请保持安装的版本为最新。
|
||||
|
||||
通过 npm 安装的 CLI 使用:
|
||||
通过 `npm install --global` 或 `bun add --global` 安装的 CLI 使用:
|
||||
|
||||
```bash
|
||||
rea update
|
||||
```
|
||||
|
||||
Bun 全局更新需要 Bun 1.2.17 或更高版本。如果使用较旧的 Bun 版本,请先手动升级 Bun,再运行 `rea update`。
|
||||
|
||||
要更新智能体注册和 skill,请运行更新命令输出的设置命令。
|
||||
|
||||
如果使用 `npx`,通过以下命令更新智能体设置:
|
||||
@@ -114,7 +116,7 @@ rea update
|
||||
npx rea-agents@latest setup
|
||||
```
|
||||
|
||||
检查设置变更并重启智能体。单次 CLI 操作可使用 `npx rea-agents@latest`,后接所需命令。
|
||||
检查设置变更并重启智能体。单次 CLI 操作可使用 `npx rea-agents@latest`,后接所需命令。使用 Bun 时,用 `bunx rea-agents@latest` 代替 `npx rea-agents@latest`。
|
||||
|
||||
## REA 的工作原理
|
||||
|
||||
@@ -134,6 +136,8 @@ REA 需要 Node.js 22.x(>=22.19)、24.x(>=24.11)或 26+,以及 npm。
|
||||
| --------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
|
||||
| 原生二进制文件 | 伪代码、汇编、字符串、符号、调用和引用 | Hopper、Ghidra 或 IDA;[原生分析](https://rea.tools/zh-CN/guides/native/) |
|
||||
| 离线 ELF 布局 | 节、段、原始符号/重定位信息及静态防护机制候选项 | Linux x64 上由调用方提供的 pwntools;[二进制诊断](../binary-diagnostics.md) |
|
||||
| Go 二进制文件 | 内嵌编译器版本、模块、替换项和构建设置 | 内置静态 ELF/PE/thin Mach-O 检查;无需安装 Go |
|
||||
| WASM 工件 | 验证、节、精确的导入/导出 WAT 形式及解码后的 WAT | 调用方提供的 WABT 1.0.42;`inspect_wasm_artifact` |
|
||||
| EVM 字节码 | 分派选择器、字节偏移、推断的参数和状态可变性 | Linux x64 上的本地原始字节/十六进制输入载体;[离线 EVM 指南](../evm-bytecode.md) |
|
||||
| 已记录的 Linux 崩溃 | 原始 note 记录、每个已记录线程的寄存器/信号及可选的映射候选项 | Linux x64 上由调用方提供的 pwntools;可选的 GDB/pwndbg;[已记录崩溃](../recorded-crashes.md) |
|
||||
| JavaScript / Electron | 模块、导入、source map、路由、IPC 和原生扩展关系 | Node.js 和 npm;[应用分析](https://rea.tools/zh-CN/guides/javascript/) |
|
||||
|
||||
@@ -266,6 +266,7 @@
|
||||
"verify:browser:source-maps": "npm run build:cached && node scripts/verify-browser-source-maps.mjs",
|
||||
"verify:browser:runtime": "npm run build:cached && node scripts/verify-browser-runtime.mjs",
|
||||
"verify:web:network-captures": "npm run build:cached && node scripts/verify-web-network-captures.mjs",
|
||||
"verify:web:http3": "npm run build:cached && node scripts/verify-http3-network-captures.mjs",
|
||||
"verify:binary:layout": "npm run build:cached && node scripts/verify-binary-layout.mjs",
|
||||
"verify:go:binary": "npm run build:cached && node scripts/verify-go-binary.mjs",
|
||||
"verify:wasm:package": "npm run build:cached && node scripts/verify-packaged-wasm-artifact.mjs",
|
||||
|
||||
@@ -4,6 +4,12 @@
|
||||
export const SCOPES = {
|
||||
// Apple artifact CLI/MCP lane on macOS, including its focused regressions.
|
||||
apple: [
|
||||
"src/artifacts/InesArtifactReader.ts",
|
||||
"src/domain/inesContainer.ts",
|
||||
"tests/fixtures/ines.ts",
|
||||
"tests/acceptance/inesContainer.test.ts",
|
||||
"tests/boundary/filesystem/inesArtifact.test.ts",
|
||||
"tests/boundary/filesystem/inesCancellation.test.ts",
|
||||
"src/native/Apple*",
|
||||
"src/native/NativeMacOS*",
|
||||
"src/native/NativeUi*",
|
||||
@@ -19,6 +25,7 @@ export const SCOPES = {
|
||||
"tests/boundary/cli/nativePlistSelectionFailureCli.test.ts",
|
||||
"tests/boundary/cli/nativeDemangleCli.test.ts",
|
||||
"tests/boundary/mcp/nativeDemangleMcp.test.ts",
|
||||
"tests/boundary/mcp/nativeMachoSummaryMcp.test.ts",
|
||||
"tests/boundary/providers/native/nativeSignatureTargetBinding.test.ts",
|
||||
"tests/boundary/cli/nativeSignatureCli.test.ts",
|
||||
"tests/boundary/mcp/nativeSignatureTargetBindingMcp.test.ts",
|
||||
|
||||
@@ -0,0 +1,10 @@
|
||||
# Exercised runtime graph: CPython 3.14.7, Linux x86_64 guest.
|
||||
aioquic==1.2.0
|
||||
attrs==26.1.0
|
||||
certifi==2026.7.22
|
||||
cffi==2.1.1
|
||||
cryptography==50.0.2
|
||||
pycparser==3.11
|
||||
pylsqpack==0.3.24
|
||||
pyOpenSSL==26.4.0
|
||||
service-identity==26.1.0
|
||||
@@ -0,0 +1,416 @@
|
||||
"""Real loopback HTTP/3 laboratory using aioquic and caller-supplied mitmdump.
|
||||
|
||||
Run inside a disposable Linux guest. All native records are written by
|
||||
mitmproxy's real save addon, not constructed fixtures. Endpoint stream IDs are
|
||||
observations scoped to that endpoint; no MITM stream mapping is claimed.
|
||||
"""
|
||||
|
||||
import argparse
|
||||
import asyncio
|
||||
import base64
|
||||
import hashlib
|
||||
import json
|
||||
import os
|
||||
import signal
|
||||
import ssl
|
||||
import subprocess
|
||||
import time
|
||||
from pathlib import Path
|
||||
|
||||
import aioquic
|
||||
from aioquic.asyncio import QuicConnectionProtocol, connect, serve
|
||||
from aioquic.h3.connection import H3Connection
|
||||
from aioquic.h3.events import DataReceived, HeadersReceived
|
||||
from aioquic.quic.configuration import QuicConfiguration
|
||||
from aioquic.quic.events import ConnectionTerminated, HandshakeCompleted, StreamReset
|
||||
from aioquic.quic.packet import QuicProtocolVersion
|
||||
|
||||
|
||||
def binary(value):
|
||||
return {"base64": base64.b64encode(value).decode("ascii"), "bytes": len(value),
|
||||
"sha256": hashlib.sha256(value).hexdigest()}
|
||||
|
||||
|
||||
def pairs(headers):
|
||||
return [[binary(name), binary(value)] for name, value in headers]
|
||||
|
||||
|
||||
class Journal:
|
||||
def __init__(self, root):
|
||||
self.root = root
|
||||
self.events = []
|
||||
self.requests = {}
|
||||
self.responses = {}
|
||||
self.tasks = set()
|
||||
self.children = []
|
||||
self.writers = []
|
||||
|
||||
def emit(self, event, **data):
|
||||
value = {"event": event, "monotonic": time.monotonic(), **data}
|
||||
self.events.append(value)
|
||||
with (self.root / "endpoints.jsonl").open("a") as handle:
|
||||
handle.write(json.dumps(value) + "\n")
|
||||
|
||||
def task(self, coroutine):
|
||||
task = asyncio.create_task(coroutine)
|
||||
self.tasks.add(task)
|
||||
return task
|
||||
|
||||
|
||||
|
||||
class Endpoint(QuicConnectionProtocol):
|
||||
def __init__(self, *args, journal, endpoint, **kwargs):
|
||||
super().__init__(*args, **kwargs)
|
||||
self.journal, self.endpoint = journal, endpoint
|
||||
self.http = H3Connection(self._quic)
|
||||
self.messages = {}
|
||||
self.waiters = {}
|
||||
self.concurrent = []
|
||||
self.identity = f"{endpoint}-{len(journal.events)}"
|
||||
|
||||
def quic_event_received(self, event):
|
||||
if isinstance(event, HandshakeCompleted):
|
||||
# This is the negotiated runtime value in pinned aioquic 1.2.0,
|
||||
# not configuration.supported_versions or mitmproxy's QUICv1 label.
|
||||
self.journal.emit("handshake", endpoint=self.endpoint, connection=self.identity,
|
||||
alpn=event.alpn_protocol, quic_version=int(self._quic._version))
|
||||
if isinstance(event, (StreamReset, ConnectionTerminated)):
|
||||
self.journal.emit(type(event).__name__, endpoint=self.endpoint,
|
||||
connection=self.identity, error_code=event.error_code,
|
||||
stream_id=getattr(event, "stream_id", None),
|
||||
reason=getattr(event, "reason_phrase", None))
|
||||
targets = self.waiters.values() if isinstance(event, ConnectionTerminated) else [self.waiters.get(event.stream_id)]
|
||||
for waiter in targets:
|
||||
if waiter is not None and not waiter.done():
|
||||
waiter.set_exception(ConnectionError(type(event).__name__))
|
||||
for item in self.http.handle_event(event):
|
||||
if isinstance(item, (HeadersReceived, DataReceived)):
|
||||
message = self.messages.setdefault(item.stream_id, {"headers": [], "body": bytearray()})
|
||||
if isinstance(item, HeadersReceived):
|
||||
message["headers"].extend(item.headers)
|
||||
else:
|
||||
message["body"].extend(item.data)
|
||||
if item.stream_ended:
|
||||
self.completed(item.stream_id, message)
|
||||
|
||||
def completed(self, stream_id, message):
|
||||
body = bytes(message["body"])
|
||||
if self.endpoint == "client":
|
||||
self.journal.emit("response-received", endpoint="client", connection=self.identity,
|
||||
stream_id=stream_id, headers=pairs(message["headers"]), body=binary(body))
|
||||
self.waiters[stream_id].set_result(message)
|
||||
return
|
||||
headers = dict(message["headers"])
|
||||
case = headers.get(b"x-lab-case", b"curl").decode("ascii")
|
||||
self.journal.requests[case] = {"headers": pairs(message["headers"]), "body": binary(body)}
|
||||
self.journal.emit("request-received", endpoint="origin", connection=self.identity,
|
||||
stream_id=stream_id, case=case, **self.journal.requests[case])
|
||||
if case.startswith("parallel-"):
|
||||
self.concurrent.append((case, stream_id, body))
|
||||
if len(self.concurrent) == 3:
|
||||
self.journal.task(self.answer_parallel())
|
||||
else:
|
||||
self.answer(case, stream_id, b"\x00\xfeanswer:" + case.encode() + b":" + body[::-1])
|
||||
|
||||
async def answer_parallel(self):
|
||||
for case, stream_id, body in reversed(self.concurrent):
|
||||
self.answer(case, stream_id, b"\x00\xfeanswer:" + case.encode() + b":" + body[::-1])
|
||||
await asyncio.sleep(0.15)
|
||||
|
||||
def answer(self, case, stream_id, body):
|
||||
headers = [(b":status", b"200"), (b"content-type", b"application/octet-stream"),
|
||||
(b"content-length", str(len(body)).encode()),
|
||||
(b"x-lab-case", case.encode()), (b"x-duplicate", b"one"), (b"x-duplicate", b"two")]
|
||||
self.journal.responses[case] = {"headers": pairs(headers), "body": binary(body), "finished": True}
|
||||
self.journal.emit("response-sent", endpoint="origin", connection=self.identity,
|
||||
stream_id=stream_id, case=case, **self.journal.responses[case])
|
||||
self.http.send_headers(stream_id, headers)
|
||||
self.http.send_data(stream_id, body, end_stream=True)
|
||||
self.transmit()
|
||||
|
||||
def request(self, case, body):
|
||||
stream_id = self._quic.get_next_available_stream_id()
|
||||
headers = [(b":method", b"POST"), (b":scheme", b"https"),
|
||||
(b":authority", b"lab.test:18443"), (b":path", b"/same?token=ordinary&x=%2F"),
|
||||
(b"x-lab-case", case.encode()), (b"content-type", b"application/octet-stream"),
|
||||
(b"content-length", str(len(body)).encode()),
|
||||
(b"x-duplicate", b"first"), (b"x-duplicate", b"second")]
|
||||
self.waiters[stream_id] = asyncio.get_running_loop().create_future()
|
||||
self.journal.emit("request-sent", endpoint="client", connection=self.identity,
|
||||
stream_id=stream_id, case=case, headers=pairs(headers), body=binary(body), finished=True)
|
||||
self.http.send_headers(stream_id, headers)
|
||||
self.http.send_data(stream_id, body, end_stream=True)
|
||||
self.transmit()
|
||||
return stream_id, self.waiters[stream_id]
|
||||
|
||||
|
||||
|
||||
class Proxy:
|
||||
def __init__(self, args, root, name, http3=True):
|
||||
self.args, self.root, self.name, self.http3 = args, root, name, http3
|
||||
self.process = None
|
||||
self.log = None
|
||||
|
||||
async def start(self):
|
||||
self.log = (self.root / f"{self.name}.proxy.log").open("wb")
|
||||
command = [self.args.mitmdump, "--mode", "reverse:https://lab.test:19443@127.0.0.1:18443",
|
||||
"--set", f"confdir={self.root / 'proxy-config'}", "--set", "connection_strategy=lazy",
|
||||
"--set", "keep_host_header=true", "--set", "store_streamed_bodies=false",
|
||||
"--set", f"rea_lab_log={self.root / (self.name + '.producer.jsonl')}",
|
||||
"-w", str(self.root / (self.name + '.mitm')),
|
||||
"-s", str(Path(__file__).with_name("observe-mitmproxy-http3.py"))]
|
||||
command.extend(["--set", f"ssl_verify_upstream_trusted_ca={self.root / 'origin-ca.pem'}"])
|
||||
if not self.http3:
|
||||
command.extend(["--set", "http3=false"])
|
||||
self.process = subprocess.Popen(command, stdout=self.log, stderr=subprocess.STDOUT,
|
||||
start_new_session=True)
|
||||
lease = {"runId": os.environ["REA_PROCESS_RUN_ID"], "leaderPid": self.process.pid,
|
||||
"processGroupId": self.process.pid}
|
||||
with (self.root / "process-groups.jsonl").open("a") as handle:
|
||||
handle.write(json.dumps(lease) + "\n")
|
||||
deadline = time.monotonic() + 15
|
||||
journal = self.root / f"{self.name}.producer.jsonl"
|
||||
while time.monotonic() < deadline:
|
||||
if self.process.poll() is not None:
|
||||
raise RuntimeError(f"Proxy exited: {self.log.name}")
|
||||
if journal.exists() and '"event": "ready"' in journal.read_text():
|
||||
return self
|
||||
await asyncio.sleep(0.05)
|
||||
raise TimeoutError(f"Proxy readiness: {self.log.name}")
|
||||
|
||||
async def stop(self):
|
||||
if self.process is not None and self.process.poll() is None:
|
||||
# The standalone mitmdump distribution has a bootloader parent.
|
||||
# Signal its owned session together, including the interpreter child.
|
||||
os.killpg(self.process.pid, signal.SIGINT)
|
||||
try:
|
||||
await asyncio.wait_for(asyncio.to_thread(self.process.wait), 10)
|
||||
except TimeoutError:
|
||||
os.killpg(self.process.pid, signal.SIGKILL)
|
||||
await asyncio.to_thread(self.process.wait)
|
||||
raise
|
||||
if self.process is not None:
|
||||
for _ in range(40):
|
||||
if group_is_empty(self.process.pid):
|
||||
return
|
||||
await asyncio.sleep(0.05)
|
||||
raise RuntimeError(f"Owned proxy group still live: {self.process.pid}")
|
||||
|
||||
async def close_log(self):
|
||||
if self.log is not None:
|
||||
self.log.close()
|
||||
|
||||
|
||||
def certificates(root):
|
||||
for name in ["origin"]:
|
||||
subprocess.run(["openssl", "req", "-x509", "-newkey", "rsa:2048", "-nodes",
|
||||
"-keyout", str(root / f"{name}-key.pem"), "-out", str(root / f"{name}-ca.pem"),
|
||||
"-days", "2", "-subj", "/CN=lab.test", "-addext", "subjectAltName=DNS:lab.test",
|
||||
"-addext", "basicConstraints=critical,CA:TRUE"], check=True,
|
||||
stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
|
||||
|
||||
|
||||
def client_config(root):
|
||||
config = QuicConfiguration(is_client=True, alpn_protocols=["h3"], supported_versions=[QuicProtocolVersion.VERSION_1],
|
||||
server_name="lab.test", idle_timeout=3)
|
||||
config.load_verify_locations(cafile=str(root / "proxy-config/mitmproxy-ca-cert.pem"))
|
||||
return config
|
||||
|
||||
|
||||
def connection(root, journal):
|
||||
return connect("127.0.0.1", 18443, configuration=client_config(root),
|
||||
create_protocol=lambda *a, **kw: Endpoint(*a, journal=journal, endpoint="client", **kw))
|
||||
|
||||
|
||||
async def curl_request(root, journal, name, version, path="/curl", maximum=8):
|
||||
child = await asyncio.create_subprocess_exec("curl", version, "--silent", "--show-error",
|
||||
"--max-time", str(maximum), "--cacert", str(root / "proxy-config/mitmproxy-ca-cert.pem"),
|
||||
"--resolve", "lab.test:18443:127.0.0.1", "--noproxy", "*", "-H", f"x-lab-case: {name}",
|
||||
"--output", str(root / (name + ".body")), "--dump-header", str(root / (name + ".headers")),
|
||||
"--write-out", "%{json}", "https://lab.test:18443" + path,
|
||||
stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE)
|
||||
journal.children.append(child)
|
||||
out, err = await child.communicate()
|
||||
(root / (name + ".json")).write_bytes(out)
|
||||
(root / (name + ".stderr")).write_bytes(err)
|
||||
return child.returncode, json.loads(out)
|
||||
|
||||
|
||||
async def tcp_origin(reader, writer, journal):
|
||||
journal.writers.append(writer)
|
||||
try:
|
||||
head = await asyncio.wait_for(reader.readuntil(b"\r\n\r\n"), 5)
|
||||
case = "tcp"
|
||||
for line in head.split(b"\r\n")[1:]:
|
||||
if line.lower().startswith(b"x-lab-case:"):
|
||||
case = line.split(b":", 1)[1].strip().decode("ascii")
|
||||
body = b"\x00\xfftcp-origin"
|
||||
journal.emit("tcp-request", case=case, alpn=writer.get_extra_info("ssl_object").selected_alpn_protocol(),
|
||||
headers=binary(head), body=binary(body))
|
||||
writer.write(b"HTTP/1.1 200 OK\r\ncontent-type: application/octet-stream\r\ncontent-length: " +
|
||||
str(len(body)).encode() + b"\r\nconnection: close\r\n\r\n" + body)
|
||||
await writer.drain()
|
||||
finally:
|
||||
writer.close()
|
||||
await writer.wait_closed()
|
||||
|
||||
|
||||
def group_is_empty(group):
|
||||
for entry in Path("/proc").iterdir():
|
||||
if not entry.name.isdigit():
|
||||
continue
|
||||
try:
|
||||
fields = (entry / "stat").read_text().rsplit(")", 1)[1].split()
|
||||
except FileNotFoundError:
|
||||
continue
|
||||
if fields[0] != "Z" and int(fields[2]) == group:
|
||||
return False
|
||||
return True
|
||||
|
||||
|
||||
async def attempt_all(actions):
|
||||
failures = []
|
||||
for name, action in actions:
|
||||
try:
|
||||
await asyncio.wait_for(action(), 12)
|
||||
except BaseException as error:
|
||||
failures.append((name, error))
|
||||
return failures
|
||||
|
||||
|
||||
async def close_resource(resource):
|
||||
resource.close()
|
||||
|
||||
|
||||
async def finish_child(child):
|
||||
if child.returncode is None:
|
||||
child.terminate()
|
||||
try:
|
||||
await asyncio.wait_for(child.wait(), 3)
|
||||
except TimeoutError:
|
||||
child.kill()
|
||||
await child.wait()
|
||||
|
||||
|
||||
async def finish_tasks(journal):
|
||||
for task in journal.tasks:
|
||||
if not task.done():
|
||||
task.cancel()
|
||||
results = await asyncio.gather(*journal.tasks, return_exceptions=True)
|
||||
failures = [error for error in results if isinstance(error, BaseException)
|
||||
and not isinstance(error, asyncio.CancelledError)]
|
||||
if failures:
|
||||
raise BaseExceptionGroup("Endpoint tasks failed", failures)
|
||||
|
||||
|
||||
async def run(args):
|
||||
if aioquic.__version__ != "1.2.0":
|
||||
raise RuntimeError("This laboratory requires aioquic 1.2.0")
|
||||
root = Path(args.output).resolve()
|
||||
root.mkdir(mode=0o700)
|
||||
os.umask(0o077)
|
||||
journal = Journal(root)
|
||||
loop = asyncio.get_running_loop()
|
||||
asynchronous_errors = []
|
||||
def unexpected_exception(active_loop, context):
|
||||
asynchronous_errors.append(context.get("message", "Unexpected asynchronous error"))
|
||||
active_loop.default_exception_handler(context)
|
||||
loop.set_exception_handler(unexpected_exception)
|
||||
certificates(root)
|
||||
server = tcp_server = None
|
||||
proxies = []
|
||||
scenarios = []
|
||||
primary_error = None
|
||||
cleanup_errors = []
|
||||
try:
|
||||
config = QuicConfiguration(is_client=False, alpn_protocols=["h3"],
|
||||
supported_versions=[QuicProtocolVersion.VERSION_1], idle_timeout=3)
|
||||
config.load_cert_chain(str(root / "origin-ca.pem"), str(root / "origin-key.pem"))
|
||||
server = await serve("127.0.0.1", 19443, configuration=config,
|
||||
create_protocol=lambda *a, **kw: Endpoint(*a, journal=journal, endpoint="origin", **kw))
|
||||
tls_context = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
|
||||
tls_context.load_cert_chain(str(root / "origin-ca.pem"), str(root / "origin-key.pem"))
|
||||
tls_context.set_alpn_protocols(["http/1.1"])
|
||||
tcp_server = await asyncio.start_server(lambda r, w: journal.task(tcp_origin(r, w, journal)),
|
||||
"127.0.0.1", 19443, ssl=tls_context)
|
||||
proxy = Proxy(args, root, "normal")
|
||||
proxies.append(proxy)
|
||||
await proxy.start()
|
||||
async with connection(root, journal) as client:
|
||||
requests = [client.request(f"parallel-{i}", bytes([0, 255, i]) + bytes(range(256))) for i in range(3)]
|
||||
await asyncio.wait_for(asyncio.gather(*(future for _, future in requests)), 10)
|
||||
# cURL supplies an independently implemented HTTP/3 smoke case.
|
||||
code, result = await curl_request(root, journal, "curl", "--http3-only")
|
||||
if code != 0:
|
||||
raise RuntimeError("HTTP/3 cURL failed; inspect curl.stderr")
|
||||
if result["http_version"] != "3":
|
||||
raise AssertionError("cURL silently downgraded")
|
||||
await proxy.stop()
|
||||
scenarios.append({"name": "normal", "capture": "normal.mitm"})
|
||||
|
||||
proxy = Proxy(args, root, "fallback", http3=False)
|
||||
proxies.append(proxy)
|
||||
await proxy.start()
|
||||
code, result = await curl_request(root, journal, "fallback", "--http3", path="/fallback")
|
||||
if code != 0 or result["http_version"] != "2":
|
||||
raise AssertionError(f"Fallback control: {result}")
|
||||
await proxy.stop()
|
||||
scenarios.append({"name": "fallback", "capture": "fallback.mitm"})
|
||||
|
||||
except BaseException as error:
|
||||
primary_error = error
|
||||
finally:
|
||||
actions = []
|
||||
for proxy in proxies:
|
||||
actions.extend([(f"proxy-{proxy.name}", proxy.stop),
|
||||
(f"proxy-log-{proxy.name}", proxy.close_log)])
|
||||
if server is not None:
|
||||
actions.append(("quic-server", lambda: close_resource(server)))
|
||||
if tcp_server is not None:
|
||||
actions.extend([("tcp-listener-close", lambda: close_resource(tcp_server)),
|
||||
("tcp-listener-wait", tcp_server.wait_closed)])
|
||||
for index, writer in enumerate(journal.writers):
|
||||
actions.extend([(f"tcp-writer-close-{index}", lambda w=writer: close_resource(w)),
|
||||
(f"tcp-writer-wait-{index}", writer.wait_closed)])
|
||||
actions.append(("endpoint-tasks", lambda: finish_tasks(journal)))
|
||||
for index, child in enumerate(journal.children):
|
||||
actions.append((f"curl-child-{index}", lambda c=child: finish_child(c)))
|
||||
cleanup_errors = await attempt_all(actions)
|
||||
# This runs after every close attempt, including failed setup.
|
||||
groups = []
|
||||
async def audit_groups():
|
||||
for proxy in proxies:
|
||||
if proxy.process is not None:
|
||||
groups.append({"group": proxy.process.pid, "empty": group_is_empty(proxy.process.pid)})
|
||||
if any(not item["empty"] for item in groups):
|
||||
raise RuntimeError("Proxy groups remain live")
|
||||
cleanup_errors.extend(await attempt_all([("process-groups", audit_groups)]))
|
||||
try:
|
||||
(root / "producer-cleanup.json").write_text(json.dumps({
|
||||
"primary_error": None if primary_error is None else str(primary_error),
|
||||
"cleanup_errors": [{"action": name, "type": type(error).__name__, "message": str(error)}
|
||||
for name, error in cleanup_errors], "groups": groups,
|
||||
"asynchronous_errors": asynchronous_errors}, indent=2))
|
||||
except BaseException as error:
|
||||
cleanup_errors.append(("cleanup-report", error))
|
||||
if primary_error is not None:
|
||||
for name, error in cleanup_errors:
|
||||
primary_error.add_note(f"Cleanup {name}: {error}")
|
||||
raise primary_error
|
||||
if cleanup_errors:
|
||||
raise BaseExceptionGroup("HTTP/3 producer cleanup failed", [error for _, error in cleanup_errors])
|
||||
if asynchronous_errors:
|
||||
raise RuntimeError(f"Unexpected asynchronous errors: {asynchronous_errors}")
|
||||
(root / "manifest.json").write_text(json.dumps({"profile": "http3-minimal-v1", "aioquic": aioquic.__version__,
|
||||
"scenarios": scenarios, "requests": journal.requests, "responses": journal.responses,
|
||||
"events": journal.events, "limitations": [
|
||||
"Endpoint stream IDs are scoped observations, not mitmproxy serialized IDs or mappings.",
|
||||
"The fixture reads negotiated _version from pinned aioquic 1.2.0.",
|
||||
"Only QUIC v1, Linux reverse proxy and the selected endpoints are exercised."]}, indent=2))
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
parser = argparse.ArgumentParser()
|
||||
parser.add_argument("--mitmdump", required=True)
|
||||
parser.add_argument("--output", required=True)
|
||||
asyncio.run(run(parser.parse_args()))
|
||||
@@ -0,0 +1,56 @@
|
||||
"""Lifecycle regressions; these tests do not establish HTTP/3 provider support."""
|
||||
import importlib.util
|
||||
import json
|
||||
import tempfile
|
||||
import unittest
|
||||
from pathlib import Path
|
||||
from types import SimpleNamespace
|
||||
from unittest.mock import patch
|
||||
|
||||
spec = importlib.util.spec_from_file_location("http3_lab", Path(__file__).with_name("http3-lab.py"))
|
||||
lab = importlib.util.module_from_spec(spec)
|
||||
spec.loader.exec_module(lab)
|
||||
|
||||
|
||||
class CleanupTests(unittest.IsolatedAsyncioTestCase):
|
||||
async def test_all_actions_run_after_multiple_close_failures(self):
|
||||
attempted = []
|
||||
async def fail():
|
||||
attempted.append("failed-close")
|
||||
raise RuntimeError("close failed")
|
||||
async def audit():
|
||||
attempted.append("audit")
|
||||
failures = await lab.attempt_all([("one", fail), ("two", fail), ("audit", audit)])
|
||||
self.assertEqual(attempted, ["failed-close", "failed-close", "audit"])
|
||||
self.assertEqual([name for name, _ in failures], ["one", "two"])
|
||||
|
||||
async def test_partial_setup_keeps_primary_error_and_audits_after_close_failure(self):
|
||||
original_serve = lab.serve
|
||||
closed = []
|
||||
class ClosingServer:
|
||||
def __init__(self, server):
|
||||
self.server = server
|
||||
def close(self):
|
||||
self.server.close()
|
||||
closed.append(True)
|
||||
raise RuntimeError("injected close failure")
|
||||
async def serve(*args, **kwargs):
|
||||
return ClosingServer(await original_serve(*args, **kwargs))
|
||||
async def fail_tcp(*args, **kwargs):
|
||||
raise RuntimeError("injected primary setup failure")
|
||||
with tempfile.TemporaryDirectory() as directory:
|
||||
root = Path(directory) / "capture"
|
||||
with patch.object(lab, "serve", serve), patch.object(lab.asyncio, "start_server", fail_tcp):
|
||||
with self.assertRaisesRegex(RuntimeError, "injected primary setup failure") as caught:
|
||||
await lab.run(SimpleNamespace(output=str(root), mitmdump="unused"))
|
||||
self.assertEqual(closed, [True])
|
||||
self.assertIn("injected close failure", " ".join(caught.exception.__notes__))
|
||||
report = json.loads((root / "producer-cleanup.json").read_text())
|
||||
self.assertEqual(report["primary_error"], "injected primary setup failure")
|
||||
self.assertEqual(report["cleanup_errors"][0]["action"], "quic-server")
|
||||
self.assertEqual(report["groups"], [])
|
||||
self.assertFalse((root / "manifest.json").exists())
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
@@ -0,0 +1,64 @@
|
||||
"""Test-only observation of real flows; never synthesizes flow or stream IDs."""
|
||||
|
||||
import base64
|
||||
import hashlib
|
||||
import json
|
||||
from pathlib import Path
|
||||
|
||||
from mitmproxy import ctx
|
||||
|
||||
|
||||
def bytes_view(value):
|
||||
if value is None:
|
||||
return None
|
||||
return {"base64": base64.b64encode(value).decode("ascii"),
|
||||
"bytes": len(value), "sha256": hashlib.sha256(value).hexdigest()}
|
||||
|
||||
|
||||
class Observer:
|
||||
def load(self, loader):
|
||||
loader.add_option("rea_lab_log", str, "", "HTTP/3 verifier observations")
|
||||
|
||||
def emit(self, event, **data):
|
||||
with Path(ctx.options.rea_lab_log).open("a", encoding="utf-8") as handle:
|
||||
handle.write(json.dumps({"event": event, **data}) + "\n")
|
||||
|
||||
def running(self):
|
||||
self.emit("ready")
|
||||
|
||||
def connection(self, conn):
|
||||
return {"id": conn.id, "transport_protocol": conn.transport_protocol,
|
||||
"alpn": bytes_view(conn.alpn), "tls_version": conn.tls_version,
|
||||
"timestamp_tls_setup": conn.timestamp_tls_setup,
|
||||
"error": conn.error}
|
||||
|
||||
def tls_established_client(self, data):
|
||||
self.emit("tls-established-client", connection=self.connection(data.conn))
|
||||
|
||||
def tls_established_server(self, data):
|
||||
self.emit("tls-established-server", connection=self.connection(data.conn))
|
||||
|
||||
def flow(self, event, flow):
|
||||
def message(message):
|
||||
if message is None:
|
||||
return None
|
||||
return {"http_version": message.http_version,
|
||||
"content": bytes_view(message.raw_content),
|
||||
"timestamp_end": message.timestamp_end}
|
||||
self.emit(event, id=flow.id, case=flow.request.headers.get("x-lab-case", "curl"),
|
||||
request=message(flow.request), response=message(flow.response),
|
||||
error=None if flow.error is None else flow.error.msg,
|
||||
client_conn=self.connection(flow.client_conn),
|
||||
server_conn=self.connection(flow.server_conn))
|
||||
|
||||
def request(self, flow):
|
||||
self.flow("request", flow)
|
||||
|
||||
def response(self, flow):
|
||||
self.flow("response", flow)
|
||||
|
||||
def error(self, flow):
|
||||
self.flow("error", flow)
|
||||
|
||||
|
||||
addons = [Observer()]
|
||||
@@ -16,17 +16,28 @@ import { compareBrowserScenarios } from "../../dist/domain/browserScenarioDiff.j
|
||||
import { browserScenarioCaptureSchema } from "../../dist/domain/browserScenarioCapture.js";
|
||||
import { parseEvidence } from "../../dist/domain/evidence.js";
|
||||
|
||||
// Readiness includes descendant document loads, so complete network capture
|
||||
// does not depend on whether an inline script runs before an iframe finishes.
|
||||
const document = (path) => {
|
||||
const icon = '<link rel="icon" href="data:,">';
|
||||
if (path.startsWith("/nested"))
|
||||
return `<script>throw new Error("nested popup failure")</script>
|
||||
<script>opener.postMessage("nested-ready", "*")</script>`;
|
||||
return `${icon}<script>throw new Error("nested popup failure")</script>
|
||||
<script>addEventListener("load", () => opener.postMessage("nested-ready", "*"))</script>`;
|
||||
if (path.startsWith("/popup"))
|
||||
return `<script>throw new Error("popup failure")</script>
|
||||
<script>onmessage = e => {
|
||||
if (e.data === "nested-ready") opener.postMessage("popup-ready", "*");
|
||||
}; window.open("/nested");</script><iframe src="/child"></iframe>`;
|
||||
if (path.startsWith("/child")) return "child frame";
|
||||
return `<script>onmessage = e => {
|
||||
return `${icon}<script>throw new Error("popup failure")</script>
|
||||
<script>
|
||||
let loaded = false, nested = false;
|
||||
const ready = () => {
|
||||
if (loaded && nested) opener.postMessage("popup-ready", "*");
|
||||
};
|
||||
addEventListener("load", () => { loaded = true; ready(); });
|
||||
onmessage = e => {
|
||||
if (e.data === "nested-ready") { nested = true; ready(); }
|
||||
};
|
||||
window.open("/nested");
|
||||
</script><iframe src="/child"></iframe>`;
|
||||
if (path.startsWith("/child")) return `${icon}child frame`;
|
||||
return `${icon}<script>onmessage = e => {
|
||||
if (e.data === "popup-ready") document.body.dataset.ready = "true";
|
||||
}</script><button onclick="window.open('/redirect')">Open popup</button>`;
|
||||
};
|
||||
@@ -74,7 +85,25 @@ const assertNetwork = (result, origin) => {
|
||||
1,
|
||||
`${kind} ${path} must be captured exactly once`,
|
||||
);
|
||||
assert.equal(result.completeness.equality_eligible, true);
|
||||
assert.equal(
|
||||
result.completeness.equality_eligible,
|
||||
true,
|
||||
JSON.stringify({
|
||||
limitations: result.limitations,
|
||||
unfinished: result.events.items.filter(
|
||||
(event) => event.kind === "request-unfinished",
|
||||
),
|
||||
}),
|
||||
);
|
||||
assert.equal(
|
||||
result.events.items.filter(
|
||||
(event) =>
|
||||
event.kind === "request-finished" &&
|
||||
event.url?.url === origin + "/child",
|
||||
).length,
|
||||
1,
|
||||
"child document must finish before network capture ends",
|
||||
);
|
||||
assert.equal(compareWithSelf(result).overall_status, "unchanged");
|
||||
};
|
||||
|
||||
@@ -179,13 +208,27 @@ const verifyTransports = async (executable, origin) => {
|
||||
|
||||
/** Verify popup timing, selection, coverage, and shared-context isolation on Chromium. */
|
||||
export async function verifyPopupEventCoverage(executable) {
|
||||
let slowChild = true;
|
||||
let childTimer;
|
||||
const childStarted = Promise.withResolvers();
|
||||
const server = createServer((request, response) => {
|
||||
if (request.url === "/redirect") {
|
||||
response.writeHead(302, { Location: "/popup" });
|
||||
response.end();
|
||||
} else {
|
||||
response.setHeader("Content-Type", "text/html");
|
||||
response.end(document(request.url ?? "/"));
|
||||
if (slowChild && request.url === "/child") {
|
||||
// Keep one response open while the nested page can announce readiness.
|
||||
// This exposes premature capture cutoff even on fast local browsers.
|
||||
response.writeHead(200);
|
||||
response.write(document("/child"));
|
||||
childStarted.resolve();
|
||||
childTimer = setTimeout(() => response.end(), 1500);
|
||||
} else if (slowChild && request.url === "/nested") {
|
||||
void childStarted.promise.then(() => response.end(document("/nested")));
|
||||
} else {
|
||||
response.end(document(request.url ?? "/"));
|
||||
}
|
||||
}
|
||||
});
|
||||
server.listen(0, "127.0.0.1");
|
||||
@@ -198,6 +241,7 @@ export async function verifyPopupEventCoverage(executable) {
|
||||
await capture(scenarioFor(executable, origin, ["network"])),
|
||||
origin,
|
||||
);
|
||||
slowChild = false;
|
||||
const errors = await capture(
|
||||
scenarioFor(executable, origin, ["page-errors"]),
|
||||
);
|
||||
@@ -239,6 +283,7 @@ export async function verifyPopupEventCoverage(executable) {
|
||||
stdio_mcp: true,
|
||||
};
|
||||
} finally {
|
||||
clearTimeout(childTimer);
|
||||
server.closeAllConnections();
|
||||
await new Promise((resolve, reject) =>
|
||||
server.close((error) =>
|
||||
|
||||
@@ -12,10 +12,13 @@ import {
|
||||
BROWSER_DEVTOOLS_STARTUP_TIMEOUT_MS,
|
||||
waitForBrowserDevtoolsPort,
|
||||
} from "../../dist/browser/BrowserProcessStartup.js";
|
||||
import { discoverCdpEndpoint } from "../../dist/browser/CdpEndpoint.js";
|
||||
import { BrowserObservationError } from "../../dist/domain/browserObservationError.js";
|
||||
|
||||
/** Launch the synthetic fixture browser and await CDP in its own verified process group. */
|
||||
/** Admit the owned fixture only after CDP serves its requested page. */
|
||||
export async function startRuntimeFixtureBrowser(executable, origin) {
|
||||
const profile = await mkdtemp(join(tmpdir(), "rea-real-web-runtime-"));
|
||||
const deadline = performance.now() + BROWSER_DEVTOOLS_STARTUP_TIMEOUT_MS;
|
||||
let owned;
|
||||
try {
|
||||
owned = await spawnOwnedProviderProcess({
|
||||
@@ -53,7 +56,16 @@ export async function startRuntimeFixtureBrowser(executable, origin) {
|
||||
stderr: () => stderr,
|
||||
// Match the broader real-browser verifier's allowance for cold Chrome
|
||||
// startup on shared runners; early process failures still reject at once.
|
||||
timeoutMs: BROWSER_DEVTOOLS_STARTUP_TIMEOUT_MS,
|
||||
timeoutMs: Math.max(1, deadline - performance.now()),
|
||||
});
|
||||
// Port publication can precede a responsive discovery service and renderer.
|
||||
// Both phases share the owned fixture's startup budget; public CDP calls
|
||||
// retain their normal per-response deadlines and failure semantics.
|
||||
await waitForRuntimeFixturePage({
|
||||
child: owned.process,
|
||||
port,
|
||||
origin,
|
||||
deadline,
|
||||
});
|
||||
return {
|
||||
port,
|
||||
@@ -68,17 +80,86 @@ export async function startRuntimeFixtureBrowser(executable, origin) {
|
||||
},
|
||||
};
|
||||
} catch (cause) {
|
||||
if (owned !== undefined) await stopOwnedBrowser(owned, profile);
|
||||
await rm(profile, {
|
||||
recursive: true,
|
||||
force: true,
|
||||
maxRetries: 5,
|
||||
retryDelay: 100,
|
||||
});
|
||||
await closeRuntimeFixtureResources(
|
||||
[
|
||||
async () => {
|
||||
// Keep the profile when stopping its browser cannot be confirmed.
|
||||
if (owned !== undefined) await stopOwnedBrowser(owned, profile);
|
||||
await rm(profile, {
|
||||
recursive: true,
|
||||
force: true,
|
||||
maxRetries: 5,
|
||||
retryDelay: 100,
|
||||
});
|
||||
},
|
||||
],
|
||||
cause,
|
||||
);
|
||||
throw cause;
|
||||
}
|
||||
}
|
||||
|
||||
async function waitForRuntimeFixturePage({ child, port, origin, deadline }) {
|
||||
const controller = new AbortController();
|
||||
let lastFailure;
|
||||
const onExit = () =>
|
||||
controller.abort(
|
||||
new Error(
|
||||
"Owned runtime fixture exited before CDP discovery became ready",
|
||||
{ cause: lastFailure },
|
||||
),
|
||||
);
|
||||
const onError = (cause) => controller.abort(cause);
|
||||
const timer = setTimeout(
|
||||
() =>
|
||||
controller.abort(
|
||||
new Error(
|
||||
"Owned runtime fixture page was not discoverable within its startup budget",
|
||||
{ cause: lastFailure },
|
||||
),
|
||||
),
|
||||
Math.max(1, deadline - performance.now()),
|
||||
);
|
||||
child.once("exit", onExit);
|
||||
child.once("error", onError);
|
||||
try {
|
||||
for (;;) {
|
||||
if (child.exitCode !== null || child.signalCode !== null) onExit();
|
||||
controller.signal.throwIfAborted();
|
||||
try {
|
||||
const discovery = await discoverCdpEndpoint(
|
||||
`http://127.0.0.1:${port}`,
|
||||
"list_browser_targets",
|
||||
controller.signal,
|
||||
);
|
||||
if (
|
||||
discovery.targets.some(
|
||||
(target) =>
|
||||
target.type === "page" &&
|
||||
(target.url === origin || target.url.startsWith(`${origin}/`)),
|
||||
)
|
||||
)
|
||||
return;
|
||||
} catch (cause) {
|
||||
controller.signal.throwIfAborted();
|
||||
// Only transient startup failures are retryable. Invalid protocol
|
||||
// responses and payload-limit failures must remain visible immediately.
|
||||
if (
|
||||
!(cause instanceof BrowserObservationError) ||
|
||||
!["timeout", "endpoint_unreachable"].includes(cause.reason)
|
||||
)
|
||||
throw cause;
|
||||
lastFailure = cause;
|
||||
}
|
||||
await new Promise((resolve) => setTimeout(resolve, 25));
|
||||
}
|
||||
} finally {
|
||||
clearTimeout(timer);
|
||||
child.removeListener("exit", onExit);
|
||||
child.removeListener("error", onError);
|
||||
}
|
||||
}
|
||||
|
||||
async function stopOwnedBrowser(owned, profile) {
|
||||
const child = owned.process;
|
||||
const exited =
|
||||
|
||||
@@ -0,0 +1,100 @@
|
||||
import assert from "node:assert/strict";
|
||||
import { readFile } from "node:fs/promises";
|
||||
import { join } from "node:path";
|
||||
|
||||
import {
|
||||
inspectWebPageInputSchema,
|
||||
listBrowserTargetsInputSchema,
|
||||
} from "../../dist/domain/browserObservation.js";
|
||||
import { compareWebCapturesInputSchema } from "../../dist/domain/webCaptureDiffSchemas.js";
|
||||
import { artifactCliEvidence } from "./artifact-e2e.mjs";
|
||||
|
||||
/** Verify browser-socket discovery and inspection against HTTP discovery. */
|
||||
export async function verifyBrowserSocketTransport({
|
||||
provider,
|
||||
profile,
|
||||
endpoint,
|
||||
target,
|
||||
origin,
|
||||
}) {
|
||||
const [port, path] = (
|
||||
await readFile(join(profile, "DevToolsActivePort"), "utf8")
|
||||
).split("\n");
|
||||
const socket = `ws://127.0.0.1:${port}${path}`;
|
||||
const version = await (await fetch(`${endpoint}/json/version`)).json();
|
||||
assert.equal(
|
||||
new URL(version.webSocketDebuggerUrl).pathname,
|
||||
path,
|
||||
"DevToolsActivePort and /json/version named different browser sockets",
|
||||
);
|
||||
const list = async (cdpEndpoint) => {
|
||||
const listed = await provider.listTargets(
|
||||
listBrowserTargetsInputSchema.parse({
|
||||
cdp_endpoint: cdpEndpoint,
|
||||
allowed_origins: [origin],
|
||||
}),
|
||||
);
|
||||
if (!listed.ok) throw listed.error;
|
||||
return listed.value;
|
||||
};
|
||||
const throughHttp = await list(endpoint);
|
||||
const throughSocket = await list(socket);
|
||||
// Target.getTargets reports attachment state that /json/list may omit.
|
||||
const withoutAttachment = (targets) =>
|
||||
targets.map(({ attached: _attached, ...rest }) => rest);
|
||||
assert.ok(throughSocket.targets.length > 0, "Browser socket listed no page");
|
||||
assert.deepEqual(
|
||||
withoutAttachment(throughSocket.targets),
|
||||
withoutAttachment(throughHttp.targets),
|
||||
);
|
||||
assert.ok(
|
||||
throughSocket.targets.every(
|
||||
({ attached }) => typeof attached === "boolean",
|
||||
),
|
||||
"Browser socket omitted target attachment state",
|
||||
);
|
||||
assert.equal(throughSocket.browser.product, throughHttp.browser.product);
|
||||
|
||||
const evidence = await artifactCliEvidence("inspect-web-page", socket, [
|
||||
target,
|
||||
"--allowed-origins",
|
||||
origin,
|
||||
"--observation-ms",
|
||||
"100",
|
||||
]);
|
||||
assert.equal(evidence.normalized_result.target.target_id, target);
|
||||
assert.ok(
|
||||
evidence.normalized_result.dom.nodes.length > 0,
|
||||
"Browser-socket inspection returned no DOM nodes",
|
||||
);
|
||||
assert.equal(
|
||||
evidence.parameters.cdp_endpoint,
|
||||
`ws://127.0.0.1:${port}/devtools/browser/[REDACTED]`,
|
||||
);
|
||||
assert.ok(
|
||||
!JSON.stringify(evidence).includes(path),
|
||||
"Browser-socket Evidence retained the socket identifier",
|
||||
);
|
||||
const throughHttpInspection = await provider.inspectPage(
|
||||
inspectWebPageInputSchema.parse({
|
||||
cdp_endpoint: endpoint,
|
||||
allowed_origins: [origin],
|
||||
target_id: target,
|
||||
observation_ms: 100,
|
||||
}),
|
||||
);
|
||||
if (!throughHttpInspection.ok) throw throughHttpInspection.error;
|
||||
const compared = await provider.compareCaptures(
|
||||
compareWebCapturesInputSchema.parse({
|
||||
before: { inspection: throughHttpInspection.value },
|
||||
after: { inspection: evidence.normalized_result },
|
||||
}),
|
||||
);
|
||||
if (!compared.ok) throw compared.error;
|
||||
assert.equal(compared.value.dimensions.dom_structure.status, "unchanged");
|
||||
assert.equal(compared.value.dimensions.scripts.status, "unchanged");
|
||||
return {
|
||||
targets: throughSocket.targets.length,
|
||||
revision: throughSocket.browser.revision,
|
||||
};
|
||||
}
|
||||
@@ -1,3 +1,4 @@
|
||||
export function assertCleanLinuxHopperRuntime(
|
||||
launcherPaths?: readonly string[],
|
||||
procRoot?: string,
|
||||
): Promise<void>;
|
||||
|
||||
@@ -16,6 +16,7 @@ export const assertCleanLinuxHopperRuntime = async (
|
||||
? []
|
||||
: [process.env.HOPPER_LAUNCHER_PATH]),
|
||||
],
|
||||
procRoot = "/proc",
|
||||
) => {
|
||||
const { stdout } = await execFileAsync("ps", ["-ax", "-o", "command="]);
|
||||
if (/\/opt\/hopper\/bin\/Hopper|\bXvfb\b|hopper-demo-x11\.py/u.test(stdout))
|
||||
@@ -32,17 +33,19 @@ export const assertCleanLinuxHopperRuntime = async (
|
||||
// /proc exposes the executed file even when argv[0] names a removed symlink.
|
||||
// Compare file identity, not a display path or a process name.
|
||||
let inspectionError;
|
||||
for (const entry of await readdir("/proc", { withFileTypes: true })) {
|
||||
for (const entry of await readdir(procRoot, { withFileTypes: true })) {
|
||||
if (!entry.isDirectory() || !/^\d+$/u.test(entry.name)) continue;
|
||||
let executable;
|
||||
try {
|
||||
executable = await stat(`/proc/${entry.name}/exe`, { bigint: true });
|
||||
executable = await stat(`${procRoot}/${entry.name}/exe`, {
|
||||
bigint: true,
|
||||
});
|
||||
} catch (error) {
|
||||
if (error?.code === "ENOENT" || error?.code === "ESRCH") continue;
|
||||
// Other users' executables may be unreadable. The setup lane launches
|
||||
// providers as the caller; unreadable caller-owned processes fail closed.
|
||||
if (error?.code === "EACCES") {
|
||||
const owner = await stat(`/proc/${entry.name}`).catch((cause) => {
|
||||
const owner = await stat(`${procRoot}/${entry.name}`).catch((cause) => {
|
||||
if (cause?.code === "ENOENT") return undefined;
|
||||
throw cause;
|
||||
});
|
||||
|
||||
@@ -0,0 +1,243 @@
|
||||
import assert from "node:assert/strict";
|
||||
import { createHash } from "node:crypto";
|
||||
import { isUtf8 } from "node:buffer";
|
||||
const digest = (bytes) => createHash("sha256").update(bytes).digest("hex");
|
||||
// The native decoder displays strict UTF-8 and retains invalid bytes as null text.
|
||||
const textOf = (expected) => {
|
||||
const value = Buffer.from(expected.base64, "base64");
|
||||
return isUtf8(value) ? value.toString("utf8") : null;
|
||||
};
|
||||
const field = (record, pointer) =>
|
||||
record.binary_fields.find((item) => item.pointer === pointer);
|
||||
const bytes = (record, pointer) => {
|
||||
const value = field(record, pointer);
|
||||
assert.equal(
|
||||
value?.state,
|
||||
"retained",
|
||||
`Missing retained bytes at ${pointer}`,
|
||||
);
|
||||
const decoded = Buffer.from(value.content_base64, "base64");
|
||||
assert.equal(value.bytes, decoded.length);
|
||||
assert.equal(value.sha256, digest(decoded));
|
||||
return decoded;
|
||||
};
|
||||
const binaryEqual = (record, pointer, expected) => {
|
||||
const decoded = bytes(record, pointer);
|
||||
assert.deepEqual(decoded, Buffer.from(expected.base64, "base64"), pointer);
|
||||
assert.equal(field(record, pointer).sha256, expected.sha256);
|
||||
assert.equal(field(record, pointer).bytes, expected.bytes);
|
||||
};
|
||||
const caseOf = (record) =>
|
||||
record.reported.request.headers.find(
|
||||
([name]) => name === "x-lab-case",
|
||||
)?.[1] ?? "curl";
|
||||
const byCase = (value, name) => {
|
||||
const selected = value.records.filter((record) => caseOf(record) === name);
|
||||
assert.equal(
|
||||
selected.length,
|
||||
1,
|
||||
`Expected exactly one producer record for ${name}`,
|
||||
);
|
||||
return selected[0];
|
||||
};
|
||||
const connectionH3 = (record, side) => {
|
||||
const conn = record.reported[side];
|
||||
assert.equal(conn.transport_protocol, "udp");
|
||||
assert.equal(bytes(record, `/${side}/alpn`).toString(), "h3");
|
||||
assert.equal(conn.alpn, "h3", `${side}.alpn readable value`);
|
||||
assert.equal(typeof conn.timestamp_tls_setup, "number");
|
||||
};
|
||||
|
||||
function assertHeaders(record, side, headers) {
|
||||
const regular = headers.filter(
|
||||
([name]) => !Buffer.from(name.base64, "base64").toString().startsWith(":"),
|
||||
);
|
||||
assert.equal(record.reported[side].headers.length, regular.length);
|
||||
for (const [index, pair] of regular.entries()) {
|
||||
binaryEqual(record, `/${side}/headers/${index}/0`, pair[0]);
|
||||
binaryEqual(record, `/${side}/headers/${index}/1`, pair[1]);
|
||||
assert.deepEqual(
|
||||
record.reported[side].headers[index],
|
||||
pair.map(textOf),
|
||||
`${side}.headers[${index}] readable values`,
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
export function assertEndpointHeaders(actual, expected) {
|
||||
// The proxy rebuilds pseudo fields from its HTTP state. Compare their values
|
||||
// by name while retaining the exact order and duplicates of regular headers.
|
||||
const partition = (headers) => {
|
||||
const pseudo = new Map();
|
||||
const regular = [];
|
||||
for (const pair of headers) {
|
||||
const name = Buffer.from(pair[0].base64, "base64").toString();
|
||||
if (name.startsWith(":")) {
|
||||
assert.equal(pseudo.has(name), false);
|
||||
pseudo.set(name, pair);
|
||||
} else regular.push(pair);
|
||||
}
|
||||
return { pseudo, regular };
|
||||
};
|
||||
assert.deepEqual(partition(actual), partition(expected));
|
||||
}
|
||||
|
||||
export function requireHttp3(record) {
|
||||
for (const side of ["request", "response"])
|
||||
assert.equal(record.reported[side].http_version, "HTTP/3");
|
||||
connectionH3(record, "client_conn");
|
||||
connectionH3(record, "server_conn");
|
||||
}
|
||||
|
||||
export function verifyNormalRecords(normal, manifest, finalProducer) {
|
||||
for (const record of normal.records) {
|
||||
const name = caseOf(record);
|
||||
const producer = finalProducer.find(
|
||||
(event) => event.id === record.reported.id,
|
||||
);
|
||||
assert.ok(producer, `No actual producer observation for ${name}`);
|
||||
assert.equal(record.reported.error, null);
|
||||
assert.equal(producer.error, null);
|
||||
assert.equal(record.reported.response.status_code, 200);
|
||||
requireHttp3(record);
|
||||
for (const side of ["request", "response"]) {
|
||||
assert.equal(
|
||||
record.reported[side].http_version,
|
||||
producer[side].http_version,
|
||||
);
|
||||
binaryEqual(record, `/${side}/content`, producer[side].content);
|
||||
assertHeaders(
|
||||
record,
|
||||
side,
|
||||
manifest[side === "request" ? "requests" : "responses"][name].headers,
|
||||
);
|
||||
}
|
||||
// Native UUIDs must be retained as UUIDs; the producer exports no stream mapping.
|
||||
for (const side of ["client_conn", "server_conn"])
|
||||
for (const key of ["id", "tls_version", "timestamp_tls_setup", "error"])
|
||||
assert.equal(
|
||||
record.reported[side][key],
|
||||
producer[side][key],
|
||||
`${side}.${key} differs from producer observation ${producer.id}`,
|
||||
);
|
||||
binaryEqual(record, "/request/content", manifest.requests[name].body);
|
||||
binaryEqual(record, "/response/content", manifest.responses[name].body);
|
||||
const pseudo = {
|
||||
":method": "method",
|
||||
":scheme": "scheme",
|
||||
":authority": "authority",
|
||||
":path": "path",
|
||||
};
|
||||
for (const [headerName, headerValue] of manifest.requests[name].headers) {
|
||||
const decodedName = Buffer.from(headerName.base64, "base64").toString();
|
||||
if (pseudo[decodedName]) {
|
||||
binaryEqual(record, `/request/${pseudo[decodedName]}`, headerValue);
|
||||
assert.equal(
|
||||
record.reported.request[pseudo[decodedName]],
|
||||
textOf(headerValue),
|
||||
`request.${pseudo[decodedName]} readable value`,
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
export { bytes, caseOf, byCase };
|
||||
|
||||
export function verifyConcurrency(normal, manifest) {
|
||||
const parallelNames = ["parallel-0", "parallel-1", "parallel-2"];
|
||||
const sent = manifest.events.filter(
|
||||
(event) =>
|
||||
event.event === "request-sent" && parallelNames.includes(event.case),
|
||||
);
|
||||
const received = manifest.events.filter(
|
||||
(event) =>
|
||||
event.event === "request-received" && parallelNames.includes(event.case),
|
||||
);
|
||||
const responses = manifest.events.filter(
|
||||
(event) =>
|
||||
event.event === "response-sent" && parallelNames.includes(event.case),
|
||||
);
|
||||
assert.equal(new Set(sent.map((event) => event.connection)).size, 1);
|
||||
assert.equal(new Set(received.map((event) => event.connection)).size, 1);
|
||||
assert.equal(new Set(sent.map((event) => event.stream_id)).size, 3);
|
||||
assert.equal(new Set(received.map((event) => event.stream_id)).size, 3);
|
||||
assert.ok(
|
||||
Math.max(...received.map((event) => event.monotonic)) <
|
||||
responses[0].monotonic,
|
||||
);
|
||||
assert.deepEqual(
|
||||
responses.map((event) => event.case),
|
||||
received.map((event) => event.case).reverse(),
|
||||
);
|
||||
for (const side of ["client_conn", "server_conn"])
|
||||
assert.equal(
|
||||
new Set(
|
||||
parallelNames.map((name) => byCase(normal, name).reported[side].id),
|
||||
).size,
|
||||
1,
|
||||
);
|
||||
const normalConnections = new Set(
|
||||
[...sent, ...received].map((event) => event.connection),
|
||||
);
|
||||
for (const connection of normalConnections) {
|
||||
const handshakes = manifest.events.filter(
|
||||
(event) => event.event === "handshake" && event.connection === connection,
|
||||
);
|
||||
assert.equal(handshakes.length, 1);
|
||||
assert.equal(handshakes[0].alpn, "h3");
|
||||
assert.equal(handshakes[0].quic_version, 1);
|
||||
}
|
||||
assert.equal(
|
||||
new Set(normal.records.map((record) => record.reported.id)).size,
|
||||
4,
|
||||
);
|
||||
assert.equal(sent.length, 3);
|
||||
const receivedByClient = manifest.events.filter(
|
||||
(event) =>
|
||||
event.event === "response-received" &&
|
||||
sent.some(
|
||||
(request) =>
|
||||
request.connection === event.connection &&
|
||||
request.stream_id === event.stream_id,
|
||||
),
|
||||
);
|
||||
assert.equal(receivedByClient.length, 3);
|
||||
for (const request of sent) {
|
||||
const response = receivedByClient.find(
|
||||
(event) =>
|
||||
event.connection === request.connection &&
|
||||
event.stream_id === request.stream_id,
|
||||
);
|
||||
assert.ok(
|
||||
response,
|
||||
"Each sent request needs an independently observed client response",
|
||||
);
|
||||
assert.deepEqual(response.body, manifest.responses[request.case].body);
|
||||
assert.deepEqual(request.body, manifest.requests[request.case].body);
|
||||
assertEndpointHeaders(
|
||||
request.headers,
|
||||
manifest.requests[request.case].headers,
|
||||
);
|
||||
assertEndpointHeaders(
|
||||
response.headers,
|
||||
manifest.responses[request.case].headers,
|
||||
);
|
||||
}
|
||||
return {
|
||||
sent: sent.map((event) => event.case),
|
||||
completed_at_origin: received.map((event) => event.case),
|
||||
dispatched_at_origin: responses.map((event) => event.case),
|
||||
completed_at_client: receivedByClient.map(
|
||||
(event) =>
|
||||
sent.find(
|
||||
(request) =>
|
||||
request.connection === event.connection &&
|
||||
request.stream_id === event.stream_id,
|
||||
).case,
|
||||
),
|
||||
saved_in_capture: normal.records
|
||||
.filter((record) => parallelNames.includes(caseOf(record)))
|
||||
.map(caseOf),
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,163 @@
|
||||
import assert from "node:assert/strict";
|
||||
import { createHash } from "node:crypto";
|
||||
import { test } from "node:test";
|
||||
import { verifyNormalRecords } from "./http3-capture-assertions.mjs";
|
||||
|
||||
function connectionFactsFixture() {
|
||||
const body = Buffer.from([0, 255, 128, 1]);
|
||||
const view = (bytes) => ({
|
||||
base64: bytes.toString("base64"),
|
||||
bytes: bytes.length,
|
||||
sha256: createHash("sha256").update(bytes).digest("hex"),
|
||||
});
|
||||
const producer = {
|
||||
id: "flow-id",
|
||||
error: null,
|
||||
request: { http_version: "HTTP/3", content: view(body) },
|
||||
response: { http_version: "HTTP/3", content: view(body) },
|
||||
client_conn: {
|
||||
id: "client-id",
|
||||
transport_protocol: "udp",
|
||||
tls_version: "QUICv1",
|
||||
timestamp_tls_setup: 1_700_000_000.125678,
|
||||
error: null,
|
||||
},
|
||||
server_conn: {
|
||||
id: "server-id",
|
||||
transport_protocol: "udp",
|
||||
tls_version: "QUICv1",
|
||||
timestamp_tls_setup: 1_700_000_000.987654,
|
||||
error: null,
|
||||
},
|
||||
};
|
||||
const reported = structuredClone(producer);
|
||||
const requestFields = {
|
||||
method: "POST",
|
||||
scheme: "https",
|
||||
authority: "lab.test:18443",
|
||||
path: "/echo?case=readable",
|
||||
};
|
||||
Object.assign(reported.request, requestFields);
|
||||
const headers = [
|
||||
[Buffer.from("x-repeat"), Buffer.from("first-α")],
|
||||
[Buffer.from("x-repeat"), Buffer.from("second-β")],
|
||||
[Buffer.from("x-binary"), Buffer.from([255])],
|
||||
];
|
||||
for (const side of ["request", "response"])
|
||||
reported[side].headers = [
|
||||
["x-repeat", "first-α"],
|
||||
["x-repeat", "second-β"],
|
||||
["x-binary", null],
|
||||
];
|
||||
reported.client_conn.alpn = "h3";
|
||||
reported.server_conn.alpn = "h3";
|
||||
reported.response.status_code = 200;
|
||||
const binary_fields = [
|
||||
["/request/content", body],
|
||||
["/response/content", body],
|
||||
["/client_conn/alpn", Buffer.from("h3")],
|
||||
["/server_conn/alpn", Buffer.from("h3")],
|
||||
...Object.entries(requestFields).map(([name, value]) => [
|
||||
`/request/${name}`,
|
||||
Buffer.from(value),
|
||||
]),
|
||||
...["request", "response"].flatMap((side) =>
|
||||
headers.flatMap((pair, index) =>
|
||||
pair.map((value, part) => [`/${side}/headers/${index}/${part}`, value]),
|
||||
),
|
||||
),
|
||||
].map(([pointer, bytes]) => {
|
||||
const { base64, ...facts } = view(bytes);
|
||||
return {
|
||||
pointer,
|
||||
representation: "producer-bytes",
|
||||
state: "retained",
|
||||
content_base64: base64,
|
||||
...facts,
|
||||
};
|
||||
});
|
||||
return {
|
||||
normal: { records: [{ reported, binary_fields }] },
|
||||
manifest: {
|
||||
requests: {
|
||||
curl: {
|
||||
headers: [
|
||||
...Object.entries(requestFields).map(([name, value]) => [
|
||||
view(Buffer.from(`:${name}`)),
|
||||
view(Buffer.from(value)),
|
||||
]),
|
||||
...headers.map((pair) => pair.map(view)),
|
||||
],
|
||||
body: view(body),
|
||||
},
|
||||
},
|
||||
responses: {
|
||||
curl: {
|
||||
headers: headers.map((pair) => pair.map(view)),
|
||||
body: view(body),
|
||||
},
|
||||
},
|
||||
},
|
||||
producer: [producer],
|
||||
};
|
||||
}
|
||||
|
||||
test("positive assertions retain exact producer connection facts on both legs", () => {
|
||||
const { normal, manifest, producer } = connectionFactsFixture();
|
||||
verifyNormalRecords(normal, manifest, producer);
|
||||
});
|
||||
|
||||
for (const [field, value] of [
|
||||
["method", "GET"],
|
||||
["scheme", "http"],
|
||||
["authority", "other.test:18443"],
|
||||
["path", "/different"],
|
||||
])
|
||||
test(`positive assertions reject changed readable request ${field}`, () => {
|
||||
const { normal, manifest, producer } = connectionFactsFixture();
|
||||
normal.records[0].reported.request[field] = value;
|
||||
assert.throws(() => verifyNormalRecords(normal, manifest, producer), {
|
||||
code: "ERR_ASSERTION",
|
||||
});
|
||||
});
|
||||
|
||||
for (const side of ["client_conn", "server_conn"])
|
||||
test(`positive assertions reject null readable ${side} ALPN`, () => {
|
||||
const { normal, manifest, producer } = connectionFactsFixture();
|
||||
normal.records[0].reported[side].alpn = null;
|
||||
assert.throws(() => verifyNormalRecords(normal, manifest, producer), {
|
||||
code: "ERR_ASSERTION",
|
||||
});
|
||||
});
|
||||
|
||||
for (const side of ["request", "response"])
|
||||
for (const [index, part, value] of [
|
||||
[0, 0, "x-changed"],
|
||||
[0, 1, "changed-first"],
|
||||
[1, 1, "changed-second"],
|
||||
[2, 1, "�"],
|
||||
])
|
||||
test(`positive assertions reject changed readable ${side} header ${index}/${part}`, () => {
|
||||
const { normal, manifest, producer } = connectionFactsFixture();
|
||||
normal.records[0].reported[side].headers[index][part] = value;
|
||||
assert.throws(() => verifyNormalRecords(normal, manifest, producer), {
|
||||
code: "ERR_ASSERTION",
|
||||
});
|
||||
});
|
||||
|
||||
for (const side of ["client_conn", "server_conn"])
|
||||
for (const [field, value] of [
|
||||
["tls_version", null],
|
||||
["tls_version", "changed-producer-label"],
|
||||
["error", "changed-connection-error"],
|
||||
["error", undefined],
|
||||
["timestamp_tls_setup", 0],
|
||||
["timestamp_tls_setup", 1_700_000_000],
|
||||
])
|
||||
test(`positive assertions reject ${side}.${field} changed to ${String(value)}`, () => {
|
||||
const { normal, manifest, producer } = connectionFactsFixture();
|
||||
normal.records[0].reported[side][field] = value;
|
||||
assert.throws(() => verifyNormalRecords(normal, manifest, producer), {
|
||||
code: "ERR_ASSERTION",
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,143 @@
|
||||
import assert from "node:assert/strict";
|
||||
import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
|
||||
import { join } from "node:path";
|
||||
import { DatabaseSync } from "node:sqlite";
|
||||
import { setTimeout } from "node:timers/promises";
|
||||
import { cleanupOwnedProcessGroup } from "../../dist/process/ProcessOwnership.js";
|
||||
import { observeOwnedProcessGroups } from "../../dist/process/ProcessOwnershipObservation.js";
|
||||
|
||||
export const describeError = (error) => ({
|
||||
name: error?.name ?? "Error",
|
||||
message: error?.message ?? String(error),
|
||||
...(error?.stack ? { stack: error.stack } : {}),
|
||||
});
|
||||
|
||||
export async function attemptAll(actions) {
|
||||
const failures = [];
|
||||
for (const [name, action] of actions) {
|
||||
try {
|
||||
await action();
|
||||
} catch (error) {
|
||||
failures.push({ action: name, ...describeError(error) });
|
||||
}
|
||||
}
|
||||
return failures;
|
||||
}
|
||||
|
||||
async function latest(root, report) {
|
||||
const temporary = join(root, `.verification-${report.run_id}.tmp`);
|
||||
await writeFile(temporary, JSON.stringify(report, null, 2), { flag: "wx" });
|
||||
await rename(temporary, join(root, "verification-latest.json"));
|
||||
}
|
||||
|
||||
async function withLatestLock(root, action) {
|
||||
// Keep this pathname stable: removing it could split concurrent lock owners.
|
||||
// SQLite releases its OS-backed lock when the connection/process closes.
|
||||
const database = new DatabaseSync(join(root, ".verification-lock.sqlite"));
|
||||
try {
|
||||
for (;;) {
|
||||
try {
|
||||
database.exec("BEGIN EXCLUSIVE");
|
||||
break;
|
||||
} catch (error) {
|
||||
if (
|
||||
error.code !== "ERR_SQLITE_ERROR" ||
|
||||
(error.errcode !== 5 && error.errcode !== 6)
|
||||
)
|
||||
throw error;
|
||||
// Yield while another process (or async operation here) owns the lock.
|
||||
// A synchronous busy timeout would block that operation's fs callbacks.
|
||||
await setTimeout(10);
|
||||
}
|
||||
}
|
||||
return await action();
|
||||
} finally {
|
||||
database.close();
|
||||
}
|
||||
}
|
||||
|
||||
export async function prepareAttempt(root, inspectExisting, run) {
|
||||
if (!inspectExisting) await mkdir(root, { mode: 0o700 });
|
||||
const directory = join(root, "verifications", run.run_id);
|
||||
await mkdir(directory, { recursive: true, mode: 0o700 });
|
||||
await withLatestLock(root, async () => {
|
||||
// Preserve older reports as history, without leaving an ambiguous success
|
||||
// at the capture root. Registration is the shared marker's ordering point.
|
||||
try {
|
||||
await rename(
|
||||
join(root, "verification.json"),
|
||||
join(directory, "legacy-verification.json"),
|
||||
);
|
||||
} catch (error) {
|
||||
if (error.code !== "ENOENT") throw error;
|
||||
}
|
||||
await latest(root, {
|
||||
run_id: run.run_id,
|
||||
status: "running",
|
||||
started_at: new Date().toISOString(),
|
||||
directory,
|
||||
});
|
||||
});
|
||||
return { directory, captureRoot: join(root, "captures") };
|
||||
}
|
||||
|
||||
export async function publishAttempt(root, directory, report) {
|
||||
await writeFile(
|
||||
join(directory, "result.json"),
|
||||
JSON.stringify(report, null, 2),
|
||||
{ flag: "wx" },
|
||||
);
|
||||
if (report.status === "passed")
|
||||
await writeFile(
|
||||
join(directory, "verification.json"),
|
||||
JSON.stringify(report, null, 2),
|
||||
{ flag: "wx" },
|
||||
);
|
||||
await withLatestLock(root, async () => {
|
||||
const current = JSON.parse(
|
||||
await readFile(join(root, "verification-latest.json"), "utf8"),
|
||||
);
|
||||
if (current.run_id !== report.run_id) return;
|
||||
// Ownership check and replacement share one lock with attempt registration.
|
||||
// An older attempt still keeps its reports, but cannot replace this marker.
|
||||
await latest(root, {
|
||||
run_id: report.run_id,
|
||||
status: report.status,
|
||||
directory,
|
||||
finished_at: report.finished_at,
|
||||
});
|
||||
});
|
||||
}
|
||||
|
||||
export async function finishProducerGroups(captureRoot, runId) {
|
||||
let leases;
|
||||
try {
|
||||
leases = (await readFile(join(captureRoot, "process-groups.jsonl"), "utf8"))
|
||||
.trim()
|
||||
.split("\n")
|
||||
.filter(Boolean)
|
||||
.map(JSON.parse);
|
||||
} catch (error) {
|
||||
if (error.code === "ENOENT") return { groups: [], observation: [] };
|
||||
throw error;
|
||||
}
|
||||
for (const lease of leases) assert.equal(lease.runId, runId);
|
||||
const failures = await attemptAll(
|
||||
leases.map((lease) => [
|
||||
`producer-group-${lease.processGroupId}`,
|
||||
async () => {
|
||||
const result = await cleanupOwnedProcessGroup(lease);
|
||||
assert.equal(result.cleaned, true, JSON.stringify(result));
|
||||
},
|
||||
]),
|
||||
);
|
||||
// Inspect even when one close failed; the groups can outlive their bootloader
|
||||
// parent and disappear from a plain descendant-only observation.
|
||||
const observation = [
|
||||
...(await observeOwnedProcessGroups(
|
||||
runId,
|
||||
leases.map((lease) => lease.processGroupId),
|
||||
)),
|
||||
];
|
||||
return { groups: leases, failures, observation };
|
||||
}
|
||||
@@ -0,0 +1,433 @@
|
||||
import assert from "node:assert/strict";
|
||||
import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
|
||||
import { tmpdir } from "node:os";
|
||||
import { join } from "node:path";
|
||||
import { test } from "node:test";
|
||||
import { spawn } from "node:child_process";
|
||||
import { randomUUID } from "node:crypto";
|
||||
import { once } from "node:events";
|
||||
import { setTimeout } from "node:timers/promises";
|
||||
import { DatabaseSync } from "node:sqlite";
|
||||
import {
|
||||
attemptAll,
|
||||
prepareAttempt,
|
||||
publishAttempt,
|
||||
finishProducerGroups,
|
||||
} from "./http3-verifier-lifecycle.mjs";
|
||||
import { cleanupOwnedProcessGroup } from "../../dist/process/ProcessOwnership.js";
|
||||
import { runOwnedCommand } from "../../dist/process/OwnedCommand.js";
|
||||
import { verifyConcurrency } from "./http3-capture-assertions.mjs";
|
||||
|
||||
async function waitForFile(path) {
|
||||
const signal = AbortSignal.timeout(5_000);
|
||||
for (;;) {
|
||||
try {
|
||||
await readFile(path);
|
||||
return;
|
||||
} catch (error) {
|
||||
if (error.code !== "ENOENT") throw error;
|
||||
}
|
||||
await setTimeout(10, undefined, { signal });
|
||||
}
|
||||
}
|
||||
|
||||
function startAttemptWorker(root, report) {
|
||||
const worker = `
|
||||
import { readFile, writeFile } from "node:fs/promises";
|
||||
import { join } from "node:path";
|
||||
import { setTimeout } from "node:timers/promises";
|
||||
import { prepareAttempt, publishAttempt } from ${JSON.stringify(
|
||||
new URL("./http3-verifier-lifecycle.mjs", import.meta.url).href,
|
||||
)};
|
||||
const [root, serialized] = process.argv.slice(1);
|
||||
const report = JSON.parse(serialized);
|
||||
const attempt = await prepareAttempt(root, true, report);
|
||||
await writeFile(join(root, report.run_id + ".ready"), "");
|
||||
for (;;) {
|
||||
try { await readFile(join(root, report.run_id + ".finish")); break; }
|
||||
catch (error) { if (error.code !== "ENOENT") throw error; }
|
||||
await setTimeout(10);
|
||||
}
|
||||
await publishAttempt(root, attempt.directory, report);
|
||||
`;
|
||||
return runOwnedCommand(
|
||||
{
|
||||
command: process.execPath,
|
||||
arguments: [
|
||||
"--input-type=module",
|
||||
"--eval",
|
||||
worker,
|
||||
root,
|
||||
JSON.stringify(report),
|
||||
],
|
||||
cwd: root,
|
||||
hostEnvironment: process.env,
|
||||
runId: randomUUID(),
|
||||
},
|
||||
{ timeoutMs: 10_000, diagnosticBytes: 4096 },
|
||||
).then(
|
||||
(result) => ({ result }),
|
||||
(error) => ({ error }),
|
||||
);
|
||||
}
|
||||
|
||||
test("cleanup continues through failed closes and reaches its audit", async () => {
|
||||
const attempted = [];
|
||||
const failures = await attemptAll(
|
||||
["client", "transport", "audit"].map((name) => [
|
||||
name,
|
||||
async () => {
|
||||
attempted.push(name);
|
||||
if (name !== "audit") throw new Error(`${name} failed`);
|
||||
},
|
||||
]),
|
||||
);
|
||||
assert.deepEqual(attempted, ["client", "transport", "audit"]);
|
||||
assert.deepEqual(
|
||||
failures.map((failure) => failure.action),
|
||||
["client", "transport"],
|
||||
);
|
||||
});
|
||||
|
||||
test("a failed reinspection cannot leave the earlier success as the current result", async () => {
|
||||
const root = await mkdtemp(join(tmpdir(), "rea-http3-results-"));
|
||||
try {
|
||||
await writeFile(
|
||||
join(root, "verification.json"),
|
||||
'{"status":"passed","run_id":"legacy"}',
|
||||
);
|
||||
const first = await prepareAttempt(root, true, { run_id: "first" });
|
||||
await publishAttempt(root, first.directory, {
|
||||
run_id: "first",
|
||||
status: "passed",
|
||||
});
|
||||
const next = await prepareAttempt(root, true, { run_id: "next" });
|
||||
assert.equal(
|
||||
JSON.parse(await readFile(join(root, "verification-latest.json"))).status,
|
||||
"running",
|
||||
);
|
||||
await publishAttempt(root, next.directory, {
|
||||
run_id: "next",
|
||||
status: "failed",
|
||||
error: { message: "new failure" },
|
||||
});
|
||||
assert.equal(
|
||||
JSON.parse(await readFile(join(root, "verification-latest.json"))).run_id,
|
||||
"next",
|
||||
);
|
||||
assert.equal(
|
||||
JSON.parse(await readFile(join(root, "verification-latest.json"))).status,
|
||||
"failed",
|
||||
);
|
||||
await assert.rejects(readFile(join(next.directory, "verification.json")), {
|
||||
code: "ENOENT",
|
||||
});
|
||||
await assert.rejects(readFile(join(root, "verification.json")), {
|
||||
code: "ENOENT",
|
||||
});
|
||||
assert.equal(
|
||||
JSON.parse(await readFile(join(first.directory, "verification.json")))
|
||||
.status,
|
||||
"passed",
|
||||
);
|
||||
assert.equal(
|
||||
JSON.parse(
|
||||
await readFile(join(first.directory, "legacy-verification.json")),
|
||||
).run_id,
|
||||
"legacy",
|
||||
);
|
||||
} finally {
|
||||
await rm(root, { recursive: true, force: true });
|
||||
}
|
||||
});
|
||||
|
||||
test("separate overlapping attempts finishing in reverse order retain the newer failure", async () => {
|
||||
const root = await mkdtemp(join(tmpdir(), "rea-http3-overlap-"));
|
||||
const commands = [];
|
||||
const failed = {
|
||||
run_id: "newer",
|
||||
status: "failed",
|
||||
error: { message: "newer inspection failed" },
|
||||
cleanup_failures: [{ action: "transport-close", message: "close failed" }],
|
||||
};
|
||||
let primaryError;
|
||||
const start = (report) => {
|
||||
const command = startAttemptWorker(root, report);
|
||||
commands.push(command);
|
||||
return command;
|
||||
};
|
||||
try {
|
||||
const older = start({ run_id: "older", status: "passed" });
|
||||
await waitForFile(join(root, "older.ready"));
|
||||
const newer = start(failed);
|
||||
await waitForFile(join(root, "newer.ready"));
|
||||
await writeFile(join(root, "newer.finish"), "");
|
||||
const newerResult = await newer;
|
||||
if (newerResult.error) throw newerResult.error;
|
||||
assert.equal(newerResult.result.exitCode, 0);
|
||||
assert.equal(newerResult.result.signal, null);
|
||||
const marker = await readFile(join(root, "verification-latest.json"));
|
||||
await writeFile(join(root, "older.finish"), "");
|
||||
const olderResult = await older;
|
||||
if (olderResult.error) throw olderResult.error;
|
||||
assert.equal(olderResult.result.exitCode, 0);
|
||||
assert.equal(olderResult.result.signal, null);
|
||||
assert.deepEqual(
|
||||
await readFile(join(root, "verification-latest.json")),
|
||||
marker,
|
||||
);
|
||||
assert.deepEqual(
|
||||
JSON.parse(await readFile(join(root, "verifications/newer/result.json"))),
|
||||
failed,
|
||||
);
|
||||
await assert.rejects(
|
||||
readFile(join(root, "verifications/newer/verification.json")),
|
||||
{
|
||||
code: "ENOENT",
|
||||
},
|
||||
);
|
||||
assert.equal(
|
||||
JSON.parse(
|
||||
await readFile(join(root, "verifications/older/verification.json")),
|
||||
).status,
|
||||
"passed",
|
||||
);
|
||||
} catch (error) {
|
||||
primaryError = error;
|
||||
} finally {
|
||||
// Release both barriers even after an assertion/setup failure. Each command
|
||||
// retains native supervision through termination before the root is removed.
|
||||
const failures = await attemptAll(
|
||||
["older", "newer"].map((name) => [
|
||||
name,
|
||||
() => writeFile(join(root, name + ".finish"), ""),
|
||||
]),
|
||||
);
|
||||
const outcomes = await Promise.all(commands);
|
||||
const retained = outcomes.filter(
|
||||
({ error }) => error?.cleanupFailure || error?.cleanupResult,
|
||||
);
|
||||
if (retained.length)
|
||||
primaryError = new AggregateError(
|
||||
[primaryError, ...retained.map(({ error }) => error)].filter(Boolean),
|
||||
`Worker cleanup failed; retained test evidence at ${root}`,
|
||||
{ cause: primaryError },
|
||||
);
|
||||
else
|
||||
failures.push(
|
||||
...(await attemptAll([
|
||||
["root", () => rm(root, { recursive: true, force: true })],
|
||||
])),
|
||||
);
|
||||
if (failures.length)
|
||||
primaryError = new AggregateError(
|
||||
[primaryError, ...failures].filter(Boolean),
|
||||
"Test cleanup failed",
|
||||
{ cause: primaryError },
|
||||
);
|
||||
}
|
||||
if (primaryError) throw primaryError;
|
||||
});
|
||||
|
||||
test("publication waits for the lock before reading the current owner", async () => {
|
||||
const root = await mkdtemp(join(tmpdir(), "rea-http3-lock-"));
|
||||
let database;
|
||||
let publication;
|
||||
let primaryError;
|
||||
try {
|
||||
const older = await prepareAttempt(root, true, { run_id: "older" });
|
||||
database = new DatabaseSync(join(root, ".verification-lock.sqlite"));
|
||||
database.exec("BEGIN EXCLUSIVE");
|
||||
publication = publishAttempt(root, older.directory, {
|
||||
run_id: "older",
|
||||
status: "passed",
|
||||
});
|
||||
await waitForFile(join(older.directory, "verification.json"));
|
||||
const marker = join(root, "verification-latest.json");
|
||||
assert.equal(JSON.parse(await readFile(marker)).status, "running");
|
||||
// This connection represents another marker writer. Its replacement must
|
||||
// be observed only after the blocked publisher acquires the same lock.
|
||||
const newer = { run_id: "newer", status: "failed" };
|
||||
await writeFile(marker, JSON.stringify(newer));
|
||||
database.close();
|
||||
database = undefined;
|
||||
await publication;
|
||||
assert.deepEqual(JSON.parse(await readFile(marker)), newer);
|
||||
} catch (error) {
|
||||
primaryError = error;
|
||||
} finally {
|
||||
const failures = await attemptAll([
|
||||
["lock", () => database?.close()],
|
||||
[
|
||||
"publication",
|
||||
async () => {
|
||||
if (publication) await publication;
|
||||
},
|
||||
],
|
||||
["root", () => rm(root, { recursive: true, force: true })],
|
||||
]);
|
||||
if (failures.length)
|
||||
primaryError = new AggregateError(
|
||||
[primaryError, ...failures].filter(Boolean),
|
||||
"Test cleanup failed",
|
||||
{ cause: primaryError },
|
||||
);
|
||||
}
|
||||
if (primaryError) throw primaryError;
|
||||
});
|
||||
|
||||
test("a failed marker read releases the lock and preserves the attempt report", async () => {
|
||||
const root = await mkdtemp(join(tmpdir(), "rea-http3-lock-failure-"));
|
||||
try {
|
||||
const older = await prepareAttempt(root, true, { run_id: "older" });
|
||||
await writeFile(join(root, "verification-latest.json"), "{");
|
||||
const report = {
|
||||
run_id: "older",
|
||||
status: "failed",
|
||||
error: { message: "inspection failed" },
|
||||
};
|
||||
await assert.rejects(
|
||||
publishAttempt(root, older.directory, report),
|
||||
SyntaxError,
|
||||
);
|
||||
assert.deepEqual(
|
||||
JSON.parse(await readFile(join(older.directory, "result.json"))),
|
||||
report,
|
||||
);
|
||||
const next = await prepareAttempt(root, true, { run_id: "next" });
|
||||
await publishAttempt(root, next.directory, {
|
||||
run_id: "next",
|
||||
status: "passed",
|
||||
});
|
||||
assert.equal(
|
||||
JSON.parse(await readFile(join(root, "verification-latest.json"))).run_id,
|
||||
"next",
|
||||
);
|
||||
} finally {
|
||||
await rm(root, { recursive: true, force: true });
|
||||
}
|
||||
});
|
||||
|
||||
test("dispatch reverses origin completion; client and capture may arrive in other orders", () => {
|
||||
const names = ["parallel-0", "parallel-1", "parallel-2"];
|
||||
const header = (text) => ({ base64: Buffer.from(text).toString("base64") });
|
||||
const messages = Object.fromEntries(
|
||||
names.map((name) => [
|
||||
name,
|
||||
{
|
||||
headers: [[header("x-lab-case"), header(name)]],
|
||||
body: { base64: header(name).base64 },
|
||||
},
|
||||
]),
|
||||
);
|
||||
const event = (kind, index, connection, monotonic) => ({
|
||||
event: kind,
|
||||
case: names[index],
|
||||
stream_id: index * 4,
|
||||
connection,
|
||||
monotonic,
|
||||
...messages[names[index]],
|
||||
});
|
||||
const manifest = {
|
||||
requests: messages,
|
||||
responses: messages,
|
||||
events: [
|
||||
...[0, 1, 2].map((i) => event("request-sent", i, "client", i)),
|
||||
...[1, 2, 0].map((i) => event("request-received", i, "origin", 10)),
|
||||
...[0, 2, 1].map((i) => event("response-sent", i, "origin", 20)),
|
||||
...[2, 0, 1].map((i) => event("response-received", i, "client", 30)),
|
||||
...["client", "origin"].map((connection) => ({
|
||||
event: "handshake",
|
||||
connection,
|
||||
alpn: "h3",
|
||||
quic_version: 1,
|
||||
})),
|
||||
],
|
||||
};
|
||||
const record = (name) => ({
|
||||
reported: {
|
||||
id: name,
|
||||
request: { headers: [["x-lab-case", name]] },
|
||||
client_conn: { id: "client-uuid" },
|
||||
server_conn: { id: "origin-uuid" },
|
||||
},
|
||||
});
|
||||
const normal = {
|
||||
records: [...[1, 0, 2].map((i) => record(names[i])), record("curl")],
|
||||
};
|
||||
const orders = verifyConcurrency(normal, manifest);
|
||||
assert.deepEqual(orders.dispatched_at_origin, [
|
||||
"parallel-0",
|
||||
"parallel-2",
|
||||
"parallel-1",
|
||||
]);
|
||||
manifest.events = manifest.events.filter(
|
||||
(item) => item.event !== "response-sent",
|
||||
);
|
||||
manifest.events.push(
|
||||
...[2, 1, 0].map((i) => event("response-sent", i, "origin", 20)),
|
||||
);
|
||||
assert.throws(() => verifyConcurrency(normal, manifest), {
|
||||
code: "ERR_ASSERTION",
|
||||
});
|
||||
});
|
||||
|
||||
test("cleanup verifies and retires a separately owned producer group", async () => {
|
||||
const root = await mkdtemp(join(tmpdir(), "rea-http3-group-"));
|
||||
const runId = randomUUID();
|
||||
const child = spawn("/usr/bin/sleep", ["60"], {
|
||||
detached: true,
|
||||
env: { ...process.env, REA_PROCESS_RUN_ID: runId },
|
||||
stdio: "ignore",
|
||||
});
|
||||
let primaryError;
|
||||
let cleaned = false;
|
||||
try {
|
||||
await once(child, "spawn");
|
||||
await writeFile(
|
||||
join(root, "process-groups.jsonl"),
|
||||
JSON.stringify({
|
||||
runId,
|
||||
leaderPid: child.pid,
|
||||
processGroupId: child.pid,
|
||||
}) + "\n",
|
||||
);
|
||||
const result = await finishProducerGroups(root, runId);
|
||||
assert.deepEqual(result.failures, []);
|
||||
assert.equal(result.observation[0][1].state, "empty");
|
||||
} catch (error) {
|
||||
primaryError = error;
|
||||
} finally {
|
||||
const failures = await attemptAll([
|
||||
[
|
||||
"process",
|
||||
async () => {
|
||||
const result = await cleanupOwnedProcessGroup({
|
||||
runId,
|
||||
leaderPid: child.pid,
|
||||
processGroupId: child.pid,
|
||||
});
|
||||
assert.equal(
|
||||
result.cleaned,
|
||||
true,
|
||||
`Retained ownership evidence at ${root}: ${JSON.stringify(result)}`,
|
||||
);
|
||||
cleaned = true;
|
||||
},
|
||||
],
|
||||
[
|
||||
"root",
|
||||
async () => {
|
||||
if (cleaned) await rm(root, { recursive: true, force: true });
|
||||
},
|
||||
],
|
||||
]);
|
||||
if (failures.length)
|
||||
primaryError = new AggregateError(
|
||||
[primaryError, ...failures].filter(Boolean),
|
||||
"Test cleanup failed",
|
||||
{ cause: primaryError },
|
||||
);
|
||||
}
|
||||
if (primaryError) throw primaryError;
|
||||
});
|
||||
@@ -0,0 +1,408 @@
|
||||
#!/usr/bin/env node
|
||||
import assert from "node:assert/strict";
|
||||
import { createHash } from "node:crypto";
|
||||
import { readFile, writeFile } from "node:fs/promises";
|
||||
import { isAbsolute, join } from "node:path";
|
||||
import { fileURLToPath } from "node:url";
|
||||
import { Client } from "@modelcontextprotocol/client";
|
||||
import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";
|
||||
import { Ajv2020 } from "ajv/dist/2020.js";
|
||||
import { runOwnedCommand } from "../dist/process/OwnedCommand.js";
|
||||
import { toolContract } from "../dist/contracts/toolContracts.js";
|
||||
import { createVerifierRun, completeVerifierRun } from "./lib/verifier-run.mjs";
|
||||
import {
|
||||
bytes,
|
||||
byCase,
|
||||
verifyNormalRecords,
|
||||
requireHttp3,
|
||||
verifyConcurrency,
|
||||
} from "./lib/http3-capture-assertions.mjs";
|
||||
import {
|
||||
attemptAll,
|
||||
describeError,
|
||||
prepareAttempt,
|
||||
publishAttempt,
|
||||
finishProducerGroups,
|
||||
} from "./lib/http3-verifier-lifecycle.mjs";
|
||||
import { mcpTextValue } from "./lib/mcp-verifier-results.mjs";
|
||||
|
||||
const root = process.argv[2];
|
||||
const inspectExisting = process.argv[3] === "--inspect-existing";
|
||||
const mitmdump = process.env.REA_MITMDUMP_COMMAND;
|
||||
const python = process.env.REA_HTTP3_PYTHON_COMMAND;
|
||||
assert.equal(
|
||||
process.platform,
|
||||
"linux",
|
||||
"HTTP/3 native verification requires Linux",
|
||||
);
|
||||
assert.ok(
|
||||
root && isAbsolute(root),
|
||||
"Select an absolute, new evidence directory",
|
||||
);
|
||||
assert.ok(
|
||||
mitmdump && isAbsolute(mitmdump),
|
||||
"Select caller-supplied mitmdump 12.2.3",
|
||||
);
|
||||
if (!inspectExisting)
|
||||
assert.ok(
|
||||
python && isAbsolute(python),
|
||||
"Select a Python environment with aioquic 1.2.0",
|
||||
);
|
||||
const run = createVerifierRun();
|
||||
const cwd = fileURLToPath(new URL("..", import.meta.url));
|
||||
const entrypoint = fileURLToPath(new URL("./rea.mjs", import.meta.url));
|
||||
const environment = Object.fromEntries(
|
||||
Object.entries(process.env).filter(([, value]) => typeof value === "string"),
|
||||
);
|
||||
const client = new Client({
|
||||
name: "real-http3-capture-verifier",
|
||||
version: "1",
|
||||
});
|
||||
const transport = new StdioClientTransport({
|
||||
command: process.execPath,
|
||||
args: [entrypoint, "mcp"],
|
||||
env: environment,
|
||||
stderr: "pipe",
|
||||
});
|
||||
const contract = toolContract("inspect_web_network_capture");
|
||||
const maxMcpStderrBytes = 64 * 1024;
|
||||
let mcpStderr = Buffer.alloc(0);
|
||||
transport.stderr?.on("data", (chunk) => {
|
||||
mcpStderr = Buffer.concat([mcpStderr, chunk]);
|
||||
if (mcpStderr.length > maxMcpStderrBytes)
|
||||
mcpStderr = mcpStderr.subarray(-maxMcpStderrBytes);
|
||||
});
|
||||
const checks = [];
|
||||
const retainedEvidence = [];
|
||||
const originals = new Map();
|
||||
let directory;
|
||||
let captureRoot = join(root, "captures");
|
||||
let primaryError;
|
||||
let verifier;
|
||||
let producerAudit;
|
||||
let cleanupFailures = [];
|
||||
let validateOutput;
|
||||
|
||||
const digest = (bytes) => createHash("sha256").update(bytes).digest("hex");
|
||||
const readJson = async (path) => JSON.parse(await readFile(path, "utf8"));
|
||||
const readLines = async (path) =>
|
||||
(await readFile(path, "utf8"))
|
||||
.trim()
|
||||
.split("\n")
|
||||
.filter(Boolean)
|
||||
.map(JSON.parse);
|
||||
|
||||
async function cli(input, name) {
|
||||
const command = await runOwnedCommand(
|
||||
{
|
||||
command: process.execPath,
|
||||
arguments: [
|
||||
entrypoint,
|
||||
"inspect-web-network-capture",
|
||||
input.capture_path,
|
||||
input.format,
|
||||
"--json",
|
||||
],
|
||||
cwd,
|
||||
hostEnvironment: environment,
|
||||
runId: run.run_id,
|
||||
},
|
||||
{
|
||||
timeoutMs: 40_000,
|
||||
diagnosticBytes: 8 * 1024 * 1024,
|
||||
},
|
||||
);
|
||||
assert.notEqual(command.diagnosticTruncated, true);
|
||||
await writeFile(
|
||||
join(directory, `${name}.cli.stdout.json`),
|
||||
command.stdout.text,
|
||||
);
|
||||
await writeFile(
|
||||
join(directory, `${name}.cli.stderr.log`),
|
||||
command.stderr.text,
|
||||
);
|
||||
const value = JSON.parse(command.stdout.text);
|
||||
return contract.outputSchema.parse(value);
|
||||
}
|
||||
|
||||
async function mcp(input, name) {
|
||||
const reply = await client.callTool({
|
||||
name: contract.name,
|
||||
arguments: input,
|
||||
});
|
||||
await writeFile(
|
||||
join(directory, `${name}.mcp.reply.json`),
|
||||
JSON.stringify(reply, null, 2),
|
||||
);
|
||||
const value = JSON.parse(mcpTextValue(reply));
|
||||
assert.notEqual(reply.isError, true, mcpTextValue(reply));
|
||||
assert.ok(
|
||||
validateOutput(reply.structuredContent),
|
||||
JSON.stringify(validateOutput.errors),
|
||||
);
|
||||
const evidence = contract.outputSchema.parse(value);
|
||||
assert.deepEqual(reply.structuredContent, value);
|
||||
retainedEvidence.push(evidence);
|
||||
return evidence;
|
||||
}
|
||||
|
||||
async function inspect(name) {
|
||||
const input = {
|
||||
capture_path: join(captureRoot, `${name}.mitm`),
|
||||
format: "mitmproxy",
|
||||
};
|
||||
const cliResult = await cli(input, name);
|
||||
const mcpResult = await mcp(input, name);
|
||||
assert.deepEqual(cliResult.normalized_result, mcpResult.normalized_result);
|
||||
for (const evidence of [cliResult, mcpResult]) {
|
||||
assert.equal(evidence.authority, "historical-reference");
|
||||
assert.equal(evidence.confidence, "observed");
|
||||
assert.equal(evidence.provider.version, "12.2.3");
|
||||
assert.equal(evidence.normalized_result.runtime_attribution, "unknown");
|
||||
assert.deepEqual(evidence.provider, evidence.normalized_result.decoder);
|
||||
assert.equal(
|
||||
evidence.subject.digest.sha256,
|
||||
digest(await readFile(input.capture_path)),
|
||||
);
|
||||
}
|
||||
checks.push({
|
||||
case: name,
|
||||
outcome: "passed",
|
||||
records: mcpResult.normalized_result.records.length,
|
||||
});
|
||||
return mcpResult.normalized_result;
|
||||
}
|
||||
|
||||
try {
|
||||
({ directory, captureRoot } = await prepareAttempt(
|
||||
root,
|
||||
inspectExisting,
|
||||
run,
|
||||
));
|
||||
if (!inspectExisting) {
|
||||
const produced = await runOwnedCommand(
|
||||
{
|
||||
command: python,
|
||||
arguments: [
|
||||
fileURLToPath(new URL("./fixtures/http3-lab.py", import.meta.url)),
|
||||
"--mitmdump",
|
||||
mitmdump,
|
||||
"--output",
|
||||
captureRoot,
|
||||
],
|
||||
cwd,
|
||||
hostEnvironment: environment,
|
||||
runId: run.run_id,
|
||||
},
|
||||
{ timeoutMs: 120_000, diagnosticBytes: 1024 * 1024 },
|
||||
);
|
||||
await writeFile(
|
||||
join(directory, "producer.stdout.log"),
|
||||
produced.stdout.text,
|
||||
);
|
||||
await writeFile(
|
||||
join(directory, "producer.stderr.log"),
|
||||
produced.stderr.text,
|
||||
);
|
||||
}
|
||||
const manifest = await readJson(join(captureRoot, "manifest.json"));
|
||||
assert.equal(manifest.aioquic, "1.2.0");
|
||||
assert.equal(manifest.profile, "http3-minimal-v1");
|
||||
await client.connect(transport);
|
||||
const advertised = (await client.listTools()).tools.find(
|
||||
(tool) => tool.name === contract.name,
|
||||
);
|
||||
assert.ok(advertised?.outputSchema, "Missing named advertised schema");
|
||||
const ajv = new Ajv2020({ strict: false, validateFormats: false });
|
||||
assert.ok(ajv.validateSchema(advertised.inputSchema));
|
||||
assert.ok(ajv.validateSchema(advertised.outputSchema));
|
||||
validateOutput = ajv.compile(advertised.outputSchema);
|
||||
const inputValidator = ajv.compile(advertised.inputSchema);
|
||||
assert.ok(
|
||||
inputValidator({
|
||||
capture_path: join(captureRoot, "normal.mitm"),
|
||||
format: "mitmproxy",
|
||||
}),
|
||||
);
|
||||
assert.equal(
|
||||
inputValidator({
|
||||
capture_path: join(captureRoot, "normal.mitm"),
|
||||
format: "mitmproxy",
|
||||
stream_id: 0,
|
||||
}),
|
||||
false,
|
||||
);
|
||||
await writeFile(
|
||||
join(directory, "advertised-tool.json"),
|
||||
JSON.stringify(advertised, null, 2),
|
||||
);
|
||||
|
||||
for (const name of ["normal", "fallback"])
|
||||
originals.set(name, await readFile(join(captureRoot, `${name}.mitm`)));
|
||||
const normal = await inspect("normal");
|
||||
assert.equal(normal.total_records, 4);
|
||||
const finalProducer = (
|
||||
await readLines(join(captureRoot, "normal.producer.jsonl"))
|
||||
).filter((event) => ["response", "error"].includes(event.event));
|
||||
verifyNormalRecords(normal, manifest, finalProducer);
|
||||
const orders = verifyConcurrency(normal, manifest);
|
||||
assert.equal(
|
||||
(await readJson(join(captureRoot, "curl.json"))).http_version,
|
||||
"3",
|
||||
);
|
||||
assert.deepEqual(
|
||||
await readFile(join(captureRoot, "curl.body")),
|
||||
bytes(byCase(normal, "curl"), "/response/content"),
|
||||
);
|
||||
checks.push({
|
||||
case: "concurrency-bytes",
|
||||
outcome: "passed",
|
||||
parallel_streams: 3,
|
||||
orders,
|
||||
});
|
||||
const fallback = await inspect("fallback");
|
||||
assert.equal(fallback.total_records, 1);
|
||||
const record = byCase(fallback, "fallback");
|
||||
assert.throws(
|
||||
() => requireHttp3(record),
|
||||
{ code: "ERR_ASSERTION" },
|
||||
"The same positive HTTP/3 check must reject the fallback record",
|
||||
);
|
||||
assert.equal(record.reported.client_conn.transport_protocol, "tcp");
|
||||
assert.equal(record.reported.server_conn.transport_protocol, "tcp");
|
||||
assert.equal(record.reported.request.http_version, "HTTP/2.0");
|
||||
assert.equal(record.reported.response.http_version, "HTTP/1.1");
|
||||
assert.equal(record.reported.server_conn.alpn, "http/1.1");
|
||||
assert.equal(
|
||||
(await readJson(join(captureRoot, "fallback.json"))).http_version,
|
||||
"2",
|
||||
);
|
||||
checks.push({
|
||||
case: "fallback-detected",
|
||||
outcome: "passed",
|
||||
client_http: "2",
|
||||
origin_http: "1.1",
|
||||
});
|
||||
|
||||
const bundleReply = await client.callTool({
|
||||
name: "get_evidence_bundle",
|
||||
arguments: {},
|
||||
});
|
||||
assert.notEqual(bundleReply.isError, true, mcpTextValue(bundleReply));
|
||||
const bundle = JSON.parse(mcpTextValue(bundleReply)).result;
|
||||
const records = bundle.records;
|
||||
assert.ok(Array.isArray(records), "Evidence bundle omitted its records");
|
||||
for (const evidence of retainedEvidence) {
|
||||
const retained = records.find(
|
||||
(record) => record.evidence_id === evidence.evidence_id,
|
||||
);
|
||||
assert.deepEqual(
|
||||
retained,
|
||||
evidence,
|
||||
`MCP must retain the complete Evidence for ${evidence.evidence_id}`,
|
||||
);
|
||||
}
|
||||
await writeFile(
|
||||
join(directory, "session-bundle.reply.json"),
|
||||
JSON.stringify(bundleReply, null, 2),
|
||||
);
|
||||
checks.push({
|
||||
case: "mcp-session-retention",
|
||||
outcome: "passed",
|
||||
records: retainedEvidence.length,
|
||||
});
|
||||
} catch (error) {
|
||||
primaryError = error;
|
||||
} finally {
|
||||
cleanupFailures = await attemptAll([
|
||||
["client-close", () => client.close()],
|
||||
["transport-close", () => transport.close()],
|
||||
[
|
||||
"producer-groups",
|
||||
async () => {
|
||||
if (!inspectExisting) {
|
||||
producerAudit = await finishProducerGroups(captureRoot, run.run_id);
|
||||
assert.deepEqual(producerAudit.failures ?? [], []);
|
||||
for (const [, observation] of producerAudit.observation)
|
||||
assert.equal(
|
||||
observation.state,
|
||||
"empty",
|
||||
JSON.stringify(observation),
|
||||
);
|
||||
}
|
||||
},
|
||||
],
|
||||
...[...originals].map(([name, original]) => [
|
||||
`input-immutability-${name}`,
|
||||
async () => {
|
||||
assert.deepEqual(
|
||||
await readFile(join(captureRoot, `${name}.mitm`)),
|
||||
original,
|
||||
);
|
||||
},
|
||||
]),
|
||||
[
|
||||
"mcp-stderr-diagnostics",
|
||||
async () => {
|
||||
if (directory)
|
||||
await writeFile(join(directory, "mcp.stderr.log"), mcpStderr);
|
||||
},
|
||||
],
|
||||
[
|
||||
"failed-command-diagnostics",
|
||||
async () => {
|
||||
if (directory && primaryError?.snapshot) {
|
||||
await writeFile(
|
||||
join(directory, "failed-command.stdout.log"),
|
||||
primaryError.snapshot.stdout.text,
|
||||
);
|
||||
await writeFile(
|
||||
join(directory, "failed-command.stderr.log"),
|
||||
primaryError.snapshot.stderr.text,
|
||||
);
|
||||
}
|
||||
},
|
||||
],
|
||||
[
|
||||
"final-lineage",
|
||||
async () => {
|
||||
verifier = await completeVerifierRun(run);
|
||||
assert.equal(verifier.process_lineage.status, "verified");
|
||||
assert.deepEqual(verifier.process_lineage.descendants, []);
|
||||
},
|
||||
],
|
||||
]);
|
||||
}
|
||||
const report = {
|
||||
run_id: run.run_id,
|
||||
status: primaryError || cleanupFailures.length ? "failed" : "passed",
|
||||
finished_at: new Date().toISOString(),
|
||||
...(primaryError
|
||||
? {
|
||||
error: describeError(primaryError),
|
||||
mcp_stderr_log: "mcp.stderr.log",
|
||||
}
|
||||
: {}),
|
||||
cleanup_failures: cleanupFailures,
|
||||
checks,
|
||||
verifier,
|
||||
producer_audit: producerAudit,
|
||||
scope:
|
||||
"Real Linux reverse HTTP/3, mitmproxy 12.2.3, aioquic 1.2.0 and guest cURL",
|
||||
limitations: [
|
||||
"No local/WireGuard, browser, QUIC v2, migration, 0-RTT, mTLS or replay claim.",
|
||||
"No HAR, interruption, certificate-failure or body-completeness coverage in this profile.",
|
||||
],
|
||||
};
|
||||
if (directory) {
|
||||
try {
|
||||
await publishAttempt(root, directory, report);
|
||||
} catch (error) {
|
||||
console.error("Could not publish this attempt's result:", error);
|
||||
primaryError ??= error;
|
||||
}
|
||||
}
|
||||
if (primaryError) throw primaryError;
|
||||
if (cleanupFailures.length)
|
||||
throw new AggregateError(cleanupFailures, "HTTP/3 verifier cleanup failed");
|
||||
console.log(JSON.stringify(report, null, 2));
|
||||
@@ -45,6 +45,7 @@ import { verifyBrowserNetworkEvidence } from "./lib/browser-network-e2e.mjs";
|
||||
import { verifyBrowserScriptExport } from "./lib/browser-script-export-e2e.mjs";
|
||||
import { verifyBrowserModules } from "./lib/browser-module-e2e.mjs";
|
||||
import { verifyBrowserDomDestinations } from "./lib/browser-dom-destinations-e2e.mjs";
|
||||
import { verifyBrowserSocketTransport } from "./lib/browser-socket-e2e.mjs";
|
||||
import { verifyBrowserCaptureMetadataBudget } from "./lib/browser-capture-metadata-budget-e2e.mjs";
|
||||
import { artifactCliEvidence, artifactMcpResult } from "./lib/artifact-e2e.mjs";
|
||||
import { verifyScenarioEnvironment } from "./lib/browser-scenario-environment-e2e.mjs";
|
||||
@@ -234,6 +235,13 @@ try {
|
||||
|
||||
pageProxy = await startPageCdpProxy(endpoint);
|
||||
await verifyPageScopedTransport(provider, pageProxy, site.origin);
|
||||
const browserSocketTransport = await verifyBrowserSocketTransport({
|
||||
provider,
|
||||
profile,
|
||||
endpoint,
|
||||
target,
|
||||
origin: site.origin,
|
||||
});
|
||||
const attachedScenarioInput = browserScenario(
|
||||
{
|
||||
mode: "connect",
|
||||
@@ -377,6 +385,7 @@ try {
|
||||
bundle_cli_and_stdio_mcp: true,
|
||||
sessionEvents: session.value.timeline.length,
|
||||
pageScopedTransport: true,
|
||||
browserSocketTransport,
|
||||
screenshotBytes: screenshot.value.artifact.bytes,
|
||||
largeScreenshot,
|
||||
popupEvents,
|
||||
|
||||
@@ -1,18 +1,17 @@
|
||||
import { readFileHandlePrefix } from "../filesystem/readFileHandlePrefix.js";
|
||||
import { constants, type Stats } from "node:fs";
|
||||
import { createHash } from "node:crypto";
|
||||
import {
|
||||
access,
|
||||
lstat,
|
||||
realpath,
|
||||
stat,
|
||||
type FileHandle,
|
||||
} from "node:fs/promises";
|
||||
nesContainerFormat,
|
||||
parseInesLayout,
|
||||
} from "../domain/inesContainer.js";
|
||||
import { access, realpath, stat, type FileHandle } from "node:fs/promises";
|
||||
import { extname, isAbsolute, resolve } from "node:path";
|
||||
|
||||
import { BinaryTargetError } from "../domain/configurationErrors.js";
|
||||
import {
|
||||
openRegularFile,
|
||||
sameRegularFileState,
|
||||
verifyRegularFileState,
|
||||
} from "../filesystem/RegularFile.js";
|
||||
import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";
|
||||
import type { BinaryTarget } from "../domain/binaryTargetTypes.js";
|
||||
@@ -162,15 +161,17 @@ export const parseBinaryTarget = async (
|
||||
availableArchitectures: ["x86"],
|
||||
});
|
||||
}
|
||||
// Probe WASM content before suffix-only database routing; an explicit
|
||||
// Probe content before suffix-only database routing; an explicit
|
||||
// database selection keeps the caller's chosen interpretation.
|
||||
const artifactFormat =
|
||||
targetKind === "database"
|
||||
? undefined
|
||||
: await detectArtifactFormat(path, handle, signal);
|
||||
: await detectArtifactFormat(path, handle, metadata, signal);
|
||||
if (
|
||||
targetKind === "database" ||
|
||||
(targetKind === undefined && path.toLowerCase().endsWith(".hop"))
|
||||
(targetKind === undefined &&
|
||||
artifactFormat === undefined &&
|
||||
path.toLowerCase().endsWith(".hop"))
|
||||
)
|
||||
return ok({
|
||||
path,
|
||||
@@ -212,6 +213,13 @@ export const parseBinaryTarget = async (
|
||||
await handle.close();
|
||||
}
|
||||
} catch (cause: unknown) {
|
||||
// The filesystem admission helper throws the caller's abort reason after
|
||||
// confirming descriptor release. Cleanup failures carry a different owner
|
||||
// error and must remain visible rather than being reduced to cancellation.
|
||||
if (signal?.aborted === true && cause === signal.reason)
|
||||
return err(
|
||||
new AnalysisCancelledError("resolve_binary_target", { cause }),
|
||||
);
|
||||
if (cause instanceof AnalysisCancelledError) return err(cause);
|
||||
if (cause instanceof BinaryTargetError) return err(cause);
|
||||
if (!(cause instanceof Error)) throw cause;
|
||||
@@ -264,9 +272,26 @@ const throwIfTargetResolutionCancelled = (signal?: AbortSignal): void => {
|
||||
throw new AnalysisCancelledError("resolve_binary_target");
|
||||
};
|
||||
|
||||
/** Preserve cancellation when an asynchronous identity check succeeds or rejects. */
|
||||
const verifyTargetState = async (
|
||||
path: string,
|
||||
handle: FileHandle,
|
||||
initial: Stats,
|
||||
signal?: AbortSignal,
|
||||
): Promise<void> => {
|
||||
try {
|
||||
await verifyRegularFileState(path, { handle, initial });
|
||||
} catch (cause: unknown) {
|
||||
throwIfTargetResolutionCancelled(signal);
|
||||
throw cause;
|
||||
}
|
||||
throwIfTargetResolutionCancelled(signal);
|
||||
};
|
||||
|
||||
const detectArtifactFormat = async (
|
||||
path: string,
|
||||
handle: FileHandle,
|
||||
initial: Stats,
|
||||
signal?: AbortSignal,
|
||||
): Promise<
|
||||
| Exclude<
|
||||
@@ -284,32 +309,44 @@ const detectArtifactFormat = async (
|
||||
> => {
|
||||
throwIfTargetResolutionCancelled(signal);
|
||||
const lower = path.toLowerCase();
|
||||
const magic = Buffer.alloc(8);
|
||||
const observed = await handle.read(magic, 0, magic.length, 0);
|
||||
const magic = await readFileHandlePrefix(handle, 16, () =>
|
||||
throwIfTargetResolutionCancelled(signal),
|
||||
);
|
||||
throwIfTargetResolutionCancelled(signal);
|
||||
await verifyTargetState(path, handle, initial, signal);
|
||||
if (
|
||||
observed.bytesRead === 8 &&
|
||||
magic.equals(Buffer.from([0, 0x61, 0x73, 0x6d, 1, 0, 0, 0]))
|
||||
magic.length >= 8 &&
|
||||
magic.subarray(0, 8).equals(Buffer.from([0, 0x61, 0x73, 0x6d, 1, 0, 0, 0]))
|
||||
)
|
||||
throw new BinaryTargetError(
|
||||
path,
|
||||
"WebAssembly v1 artifacts are not supported by the native opening route",
|
||||
{ constraint: "wasm_requires_static_inspection" },
|
||||
);
|
||||
if (hasZipSignature(magic.subarray(0, observed.bytesRead))) {
|
||||
const prefix = magic;
|
||||
const nesFormat = nesContainerFormat(prefix);
|
||||
if (nesFormat !== undefined) {
|
||||
const parsed = parseInesLayout(prefix, initial.size);
|
||||
throwIfTargetResolutionCancelled(signal);
|
||||
if (!parsed.ok)
|
||||
throw new BinaryTargetError(path, parsed.error, {
|
||||
constraint: "file_format_rejected",
|
||||
});
|
||||
return "ines";
|
||||
}
|
||||
if (hasZipSignature(prefix)) {
|
||||
// The HarmonyOS App Pack suffix `.app` is a root-input concept; a nested
|
||||
// ZIP member ending in `.app` keeps the generic zip classification.
|
||||
if (lower.endsWith(".app")) return "app-pack";
|
||||
return zipPackageFormatForPath(lower) ?? "zip";
|
||||
}
|
||||
// Binary plists, including keyed archives, often use other extensions.
|
||||
if (hasBinaryPlistSignature(magic.subarray(0, observed.bytesRead)))
|
||||
return "plist";
|
||||
if (hasBinaryPlistSignature(magic)) return "plist";
|
||||
const named = namedArtifactFormat(lower);
|
||||
if (named !== undefined) return named;
|
||||
if (
|
||||
lower.endsWith(".pkg") &&
|
||||
observed.bytesRead >= 4 &&
|
||||
magic.length >= 4 &&
|
||||
magic.subarray(0, 4).equals(Buffer.from("xar!"))
|
||||
)
|
||||
return "pkg";
|
||||
@@ -350,7 +387,7 @@ const isArchiveFormat = (
|
||||
| "raw-binary"
|
||||
>,
|
||||
): format is Extract<BinaryTarget, { kind: "archive" }>["format"] =>
|
||||
isZipPackageFormat(format) || ["asar", "dmg", "pkg"].includes(format);
|
||||
isZipPackageFormat(format) || ["asar", "ines", "dmg", "pkg"].includes(format);
|
||||
|
||||
const sha256Handle = async (
|
||||
handle: FileHandle,
|
||||
@@ -377,12 +414,8 @@ const sha256Handle = async (
|
||||
throw new BinaryTargetError(path, "target grew while being read");
|
||||
}
|
||||
throwIfTargetResolutionCancelled(signal);
|
||||
const [opened, currentPath] = await Promise.all([handle.stat(), lstat(path)]);
|
||||
if (
|
||||
!sameRegularFileState(initial, opened) ||
|
||||
!sameRegularFileState(initial, currentPath) ||
|
||||
position !== initial.size
|
||||
)
|
||||
await verifyTargetState(path, handle, initial, signal);
|
||||
if (position !== initial.size)
|
||||
throw new BinaryTargetError(path, "target changed while being read");
|
||||
return hash.digest("hex");
|
||||
};
|
||||
|
||||
@@ -131,7 +131,7 @@ const browserParameters = (
|
||||
}
|
||||
const observedOrigin = browserResultTargetOrigin(result);
|
||||
const scope = {
|
||||
cdp_endpoint: input.cdp_endpoint,
|
||||
cdp_endpoint: input.cdp_endpoint.recorded,
|
||||
allowed_origins:
|
||||
input.allowed_origins.length > 0
|
||||
? input.allowed_origins
|
||||
|
||||
@@ -539,7 +539,7 @@ export const SUPPORTED_CLIENT_DEFINITIONS = [
|
||||
configPath: ({ home, platform, env }: ClientPathContext) =>
|
||||
join(devinDirectory({ home, platform, env }), "mcp_config.json"),
|
||||
markerPath: devinDirectory,
|
||||
format: "devin",
|
||||
format: "json",
|
||||
},
|
||||
{
|
||||
name: "opencode",
|
||||
|
||||
@@ -553,10 +553,10 @@ const collectSourceMapOriginals = (
|
||||
if (!Array.isArray(names))
|
||||
return invalidSourceMap(file, "Source map has no sources array.");
|
||||
const contents = map.sourcesContent;
|
||||
if (!hasValidSourceMapContents(names.length, contents))
|
||||
if (!hasValidSourceMapContents(contents))
|
||||
return invalidSourceMap(
|
||||
file,
|
||||
"Source map sourcesContent must contain one string or null entry per source.",
|
||||
"Source map sourcesContent must be an array of strings or null entries.",
|
||||
);
|
||||
if (map.sourceRoot != null && typeof map.sourceRoot !== "string")
|
||||
return invalidSourceMap(
|
||||
|
||||
@@ -23,6 +23,20 @@ import type { Result } from "../../domain/result.js";
|
||||
|
||||
const target = "a".repeat(64);
|
||||
const provider = { id: "fixture", name: "Fixture", version: "1" };
|
||||
const methodName = "-[BuildViewController buildTapped:]";
|
||||
const methodSymbol = {
|
||||
primary: true,
|
||||
dynamic: false,
|
||||
external: false,
|
||||
type: "function",
|
||||
source: "user_defined",
|
||||
};
|
||||
const methodInventoryEntry = {
|
||||
address: "0x1000",
|
||||
value: methodName,
|
||||
symbol: methodSymbol,
|
||||
};
|
||||
|
||||
const evidence = [
|
||||
{
|
||||
kind: "interface_builder_resource" as const,
|
||||
@@ -258,8 +272,12 @@ describe("native UI action trace", () => {
|
||||
},
|
||||
});
|
||||
});
|
||||
it("builds the evidence path from the active app and native provider", async () => {
|
||||
const tools = new EnhancedTools(testAnalysis());
|
||||
it("builds the evidence path from provider names with declared symbol facts", async () => {
|
||||
const tools = new EnhancedTools(
|
||||
testAnalysis({
|
||||
list_names: () => execution("list_names", [methodInventoryEntry]),
|
||||
}),
|
||||
);
|
||||
const result = await tools.execute("trace_native_ui_action", {
|
||||
action: "buildTapped:",
|
||||
});
|
||||
@@ -392,18 +410,117 @@ describe("bounded native UI tracing", () => {
|
||||
error: { _tag: "AnalysisInputError" },
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
it("binds dispatch metadata to the active target digest", async () => {
|
||||
const result = await new EnhancedTools(testAnalysis()).execute(
|
||||
"inspect_native_dispatch_metadata",
|
||||
{ max_records: 10 },
|
||||
);
|
||||
describe("native dispatch inventory", () => {
|
||||
it.each([
|
||||
{ label: "plain value", entry: { address: "0x1000", value: methodName } },
|
||||
{ label: "value with symbol facts", entry: methodInventoryEntry },
|
||||
{
|
||||
label: "legacy name with symbol facts",
|
||||
entry: { address: "0x1000", name: methodName, symbol: methodSymbol },
|
||||
},
|
||||
])(
|
||||
"binds $label inventory to the target without overstating dispatch coverage",
|
||||
async ({ entry }) => {
|
||||
const result = await new EnhancedTools(
|
||||
testAnalysis({
|
||||
list_names: () => execution("list_names", [entry]),
|
||||
}),
|
||||
).execute("inspect_native_dispatch_metadata", { max_records: 10 });
|
||||
|
||||
expect(result).toMatchObject({
|
||||
ok: true,
|
||||
value: { target_sha256: target },
|
||||
});
|
||||
});
|
||||
expect(result).toMatchObject({
|
||||
ok: true,
|
||||
value: {
|
||||
target_sha256: target,
|
||||
provider,
|
||||
result: {
|
||||
objc_dispatch_implementations: [
|
||||
{
|
||||
class_name: "BuildViewController",
|
||||
selector: "buildTapped:",
|
||||
implementation_address: "0x1000",
|
||||
decode: { status: "partial", reason: "symbol_name_only" },
|
||||
},
|
||||
],
|
||||
coverage: expect.arrayContaining([
|
||||
expect.objectContaining({
|
||||
facet: "objc_dispatch_implementations",
|
||||
status: "partial",
|
||||
}),
|
||||
expect.objectContaining({
|
||||
facet: "swift_dispatch_tables",
|
||||
status: "unsupported",
|
||||
}),
|
||||
expect.objectContaining({
|
||||
facet: "relative_pointers",
|
||||
status: "unsupported",
|
||||
}),
|
||||
]),
|
||||
},
|
||||
},
|
||||
});
|
||||
},
|
||||
);
|
||||
|
||||
it.each([
|
||||
{
|
||||
label: "malformed symbol flag",
|
||||
entry: {
|
||||
...methodInventoryEntry,
|
||||
symbol: { ...methodSymbol, primary: "true" },
|
||||
},
|
||||
},
|
||||
{
|
||||
label: "unknown symbol source",
|
||||
entry: {
|
||||
...methodInventoryEntry,
|
||||
symbol: { ...methodSymbol, source: "unknown" },
|
||||
},
|
||||
},
|
||||
{
|
||||
label: "incomplete symbol",
|
||||
entry: { ...methodInventoryEntry, symbol: { primary: true } },
|
||||
},
|
||||
{
|
||||
label: "malformed legacy symbol",
|
||||
entry: { address: "0x1000", name: methodName, symbol: null },
|
||||
},
|
||||
{
|
||||
label: "malformed address",
|
||||
entry: { ...methodInventoryEntry, address: 4096 },
|
||||
},
|
||||
{
|
||||
label: "malformed value with a legacy name",
|
||||
entry: { ...methodInventoryEntry, value: 42, name: methodName },
|
||||
},
|
||||
{
|
||||
label: "undeclared field",
|
||||
entry: { address: "0x1000", value: methodName, unexpected: true },
|
||||
},
|
||||
])(
|
||||
"rejects $label inventory in both dispatch consumers",
|
||||
async ({ entry }) => {
|
||||
const tools = new EnhancedTools(
|
||||
testAnalysis({
|
||||
list_names: () => execution("list_names", [entry]),
|
||||
}),
|
||||
);
|
||||
for (const [operation, parameters] of [
|
||||
["inspect_native_dispatch_metadata", { max_records: 10 }],
|
||||
["trace_native_ui_action", { action: "buildTapped:" }],
|
||||
] as const) {
|
||||
expect(await tools.execute(operation, parameters)).toMatchObject({
|
||||
ok: false,
|
||||
error: {
|
||||
_tag: "AnalysisOutputError",
|
||||
operation: "list_names",
|
||||
reason: "provider returned an invalid inventory",
|
||||
},
|
||||
});
|
||||
}
|
||||
},
|
||||
);
|
||||
});
|
||||
|
||||
describe("native UI query outcomes", () => {
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
import { z } from "zod";
|
||||
import { addressedValue } from "../../contracts/toolOutputSchemaPrimitives.js";
|
||||
import {
|
||||
nativeDispatchMetadataResultSchema,
|
||||
inspectNativeDispatchMetadata,
|
||||
@@ -36,8 +37,11 @@ export const inspectNativeDispatch = async (
|
||||
const names = z
|
||||
.array(
|
||||
z.union([
|
||||
z.strictObject({ address: z.string(), value: z.string() }),
|
||||
z.strictObject({ address: z.string(), name: z.string() }),
|
||||
addressedValue.strict(),
|
||||
addressedValue
|
||||
.omit({ value: true })
|
||||
.extend({ name: z.string() })
|
||||
.strict(),
|
||||
]),
|
||||
)
|
||||
.safeParse(execution.value.result);
|
||||
|
||||
@@ -6,6 +6,7 @@ import {
|
||||
AnalysisCancelledError,
|
||||
AnalysisInputError,
|
||||
AnalysisOutputError,
|
||||
type AnalysisInputIssue,
|
||||
} from "../../domain/analysisErrorCore.js";
|
||||
import { createEvidence, type Evidence } from "../../domain/evidence.js";
|
||||
import {
|
||||
@@ -41,22 +42,29 @@ export class WasmArtifactService {
|
||||
cause: input.error,
|
||||
}),
|
||||
);
|
||||
if (
|
||||
![
|
||||
input.data.path,
|
||||
...input.data.glue_paths,
|
||||
...input.data.candidate_paths,
|
||||
].every(isAbsolute)
|
||||
)
|
||||
return err(
|
||||
new AnalysisInputError(OPERATION, undefined, [
|
||||
{
|
||||
path: ["path"],
|
||||
reason: "invalid_format",
|
||||
message: "Expected an absolute filesystem path on this host.",
|
||||
},
|
||||
]),
|
||||
);
|
||||
const pathIssues = [
|
||||
{ value: input.data.path, path: ["path"] },
|
||||
...input.data.glue_paths.map((value, index) => ({
|
||||
value,
|
||||
path: ["glue_paths", index],
|
||||
})),
|
||||
...input.data.candidate_paths.map((value, index) => ({
|
||||
value,
|
||||
path: ["candidate_paths", index],
|
||||
})),
|
||||
].flatMap<AnalysisInputIssue>(({ value, path }) =>
|
||||
isAbsolute(value)
|
||||
? []
|
||||
: [
|
||||
{
|
||||
path,
|
||||
reason: "invalid_format",
|
||||
message: "Expected an absolute filesystem path on this host.",
|
||||
},
|
||||
],
|
||||
);
|
||||
if (pathIssues.length > 0)
|
||||
return err(new AnalysisInputError(OPERATION, undefined, pathIssues));
|
||||
const inspected = await this.provider.inspect(input.data, options);
|
||||
if (!inspected.ok) return inspected;
|
||||
if (options?.signal?.aborted)
|
||||
|
||||
@@ -23,10 +23,11 @@ export const abortIfNeeded = (signal?: AbortSignal): void => {
|
||||
);
|
||||
};
|
||||
|
||||
/** Hash every stream byte and retain its bounded classification prefix. */
|
||||
/** Hash every stream byte, optionally feeding the same bytes to a scan aggregate. */
|
||||
export const hashReadable = async (
|
||||
stream: Readable,
|
||||
signal?: AbortSignal,
|
||||
observeChunk?: (chunk: Buffer) => void,
|
||||
): Promise<HashResult> => {
|
||||
const hash = createHash("sha256");
|
||||
const prefixes: Buffer[] = [];
|
||||
@@ -37,6 +38,7 @@ export const hashReadable = async (
|
||||
const chunk = streamChunkToBuffer(raw);
|
||||
bytes += chunk.length;
|
||||
hash.update(chunk);
|
||||
observeChunk?.(chunk);
|
||||
if (prefixBytes < ARTIFACT_CLASSIFICATION_PREFIX_BYTES) {
|
||||
const selected = chunk.subarray(
|
||||
0,
|
||||
|
||||
@@ -188,7 +188,10 @@ class ArtifactClient implements AnalysisClient {
|
||||
const result = await extractArtifact(
|
||||
{
|
||||
inputPath: this.target.sourcePath ?? this.target.path,
|
||||
inputFormat: this.target.format,
|
||||
...(this.target.sourcePath === undefined ||
|
||||
this.target.sourcePath === this.target.path
|
||||
? { expectedRootSha256: this.target.sha256 }
|
||||
: {}),
|
||||
outputRoot: parsed.output_root,
|
||||
environment: this.environment,
|
||||
integrityPolicy: parsed.integrity_policy,
|
||||
@@ -391,6 +394,9 @@ class ArtifactClient implements AnalysisClient {
|
||||
environment: this.environment,
|
||||
...(options?.signal === undefined ? {} : { signal: options.signal }),
|
||||
integrity: { mode: parsed.integrity_policy },
|
||||
...(this.target.kind === "archive" && this.target.format === "ines"
|
||||
? { expectedRootSha256: this.target.sha256 }
|
||||
: {}),
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
@@ -92,7 +92,7 @@ export const sameArtifactEntry = (
|
||||
|
||||
/** Read-only adapter over one directory, archive, or virtual container. */
|
||||
export interface ArtifactReader {
|
||||
readonly format: "directory" | ZipPackageFormat | "asar" | "file";
|
||||
readonly format: "directory" | ZipPackageFormat | "asar" | "ines" | "file";
|
||||
entries(signal?: AbortSignal): AsyncIterable<ArtifactEntry>;
|
||||
open(entry: ArtifactEntry, signal?: AbortSignal): Promise<Readable>;
|
||||
provenance(): readonly ArtifactCommand[];
|
||||
|
||||
@@ -0,0 +1,187 @@
|
||||
import { readFileHandlePrefix } from "../filesystem/readFileHandlePrefix.js";
|
||||
import { Readable } from "node:stream";
|
||||
import {
|
||||
parseInesLayout,
|
||||
type InesInventory,
|
||||
type InesLayout,
|
||||
} from "../domain/inesContainer.js";
|
||||
import type { ArtifactCommand } from "../domain/artifactGraph.js";
|
||||
import {
|
||||
RegularFileChangedError,
|
||||
verifyRegularFileState,
|
||||
type StableRegularFileDescriptor,
|
||||
} from "../filesystem/RegularFile.js";
|
||||
import { readFileHandleChunks } from "../filesystem/readFileHandleChunks.js";
|
||||
import type { OwnedFileHandle } from "../filesystem/OwnedFileHandle.js";
|
||||
import {
|
||||
ArtifactReaderFailure,
|
||||
copyArtifactEntry,
|
||||
sameArtifactEntry,
|
||||
type ArtifactEntry,
|
||||
type ArtifactReader,
|
||||
} from "./ArtifactReader.js";
|
||||
import { abortIfNeeded } from "./ArtifactHash.js";
|
||||
import { streamChunkToBuffer } from "./StreamBytes.js";
|
||||
|
||||
export const INES_LIMITATION =
|
||||
"Classic iNES file regions are observed; mapper execution, CPU bank mappings, CHR-RAM contents, 6502 analysis and emulator behavior are not observed. Trailing bytes are retained without interpretation. NES 2.0 and UNIF are unsupported.";
|
||||
|
||||
/** Actual concatenated bytes observed by the inventory's ordered region scan. */
|
||||
export type InesRegionScan = Omit<InesInventory["reconstruction"], "verified">;
|
||||
|
||||
/** Read positional regions from a descriptor retained by the artifact resource scope. */
|
||||
export class InesArtifactReader implements ArtifactReader {
|
||||
readonly format = "ines" as const;
|
||||
readonly #entries = new Map<string, ArtifactEntry>();
|
||||
#layout: InesLayout | undefined;
|
||||
#closed = false;
|
||||
|
||||
constructor(
|
||||
private readonly path: string,
|
||||
private readonly source: StableRegularFileDescriptor,
|
||||
private readonly ownedSource?: OwnedFileHandle,
|
||||
) {}
|
||||
|
||||
async *entries(signal?: AbortSignal): AsyncIterable<ArtifactEntry> {
|
||||
abortIfNeeded(signal);
|
||||
await this.#verifySource(signal);
|
||||
const prefix = await readFileHandlePrefix(this.source.handle, 16, () =>
|
||||
abortIfNeeded(signal),
|
||||
);
|
||||
abortIfNeeded(signal);
|
||||
// Concurrent source changes take precedence over malformed header diagnostics.
|
||||
await this.#verifySource(signal);
|
||||
const parsed = parseInesLayout(prefix, this.source.initial.size);
|
||||
if (!parsed.ok) throw new ArtifactReaderFailure("format", parsed.error);
|
||||
this.#layout = parsed.value;
|
||||
this.#entries.clear();
|
||||
for (const region of parsed.value.regions) {
|
||||
abortIfNeeded(signal);
|
||||
const entry: ArtifactEntry = {
|
||||
path: region.path,
|
||||
kind: "file",
|
||||
declaredSize: region.length,
|
||||
compressedSize: null,
|
||||
executable: false,
|
||||
encrypted: false,
|
||||
byteOffset: region.offset,
|
||||
declaredSha256: null,
|
||||
unpacked: false,
|
||||
limitations: [],
|
||||
adapterKey: region.path,
|
||||
};
|
||||
this.#entries.set(entry.adapterKey, copyArtifactEntry(entry));
|
||||
yield entry;
|
||||
}
|
||||
}
|
||||
|
||||
async open(entry: ArtifactEntry, signal?: AbortSignal): Promise<Readable> {
|
||||
abortIfNeeded(signal);
|
||||
const produced = this.#entries.get(entry.adapterKey);
|
||||
if (produced === undefined || !sameArtifactEntry(entry, produced))
|
||||
throw new ArtifactReaderFailure(
|
||||
"integrity",
|
||||
"iNES region does not match this reader's inventory",
|
||||
);
|
||||
await this.#verifySource(signal);
|
||||
const offset = produced.byteOffset;
|
||||
const size = produced.declaredSize;
|
||||
if (offset === null || size === null || size <= 0)
|
||||
throw new ArtifactReaderFailure("integrity", "Invalid iNES region range");
|
||||
const stream = readFileHandleChunks(this.source.handle, {
|
||||
start: offset,
|
||||
end: offset + size - 1,
|
||||
signal,
|
||||
});
|
||||
const verify = () => this.#verifySource(signal);
|
||||
return Readable.from(
|
||||
(async function* () {
|
||||
let bytes = 0;
|
||||
try {
|
||||
for await (const raw of stream) {
|
||||
abortIfNeeded(signal);
|
||||
const chunk = streamChunkToBuffer(raw);
|
||||
bytes += chunk.length;
|
||||
yield chunk;
|
||||
}
|
||||
if (bytes !== size)
|
||||
throw new ArtifactReaderFailure(
|
||||
"integrity",
|
||||
"Truncated iNES region",
|
||||
);
|
||||
await verify();
|
||||
} catch (cause: unknown) {
|
||||
abortIfNeeded(signal);
|
||||
if (cause instanceof ArtifactReaderFailure) throw cause;
|
||||
throw new ArtifactReaderFailure("io", "Could not read iNES region", {
|
||||
cause,
|
||||
});
|
||||
}
|
||||
})(),
|
||||
{ objectMode: false },
|
||||
);
|
||||
}
|
||||
|
||||
/** Validate the completed region scan without rereading its payload. */
|
||||
async verifyReconstruction(
|
||||
expectedSha256: string,
|
||||
observed: InesRegionScan,
|
||||
signal?: AbortSignal,
|
||||
): Promise<InesInventory> {
|
||||
abortIfNeeded(signal);
|
||||
const layout = this.#layout;
|
||||
if (layout === undefined || this.#entries.size !== layout.regions.length)
|
||||
throw new ArtifactReaderFailure("integrity", "Incomplete iNES inventory");
|
||||
await this.#verifySource(signal);
|
||||
if (
|
||||
observed.region_order.length !== layout.regions.length ||
|
||||
layout.regions.some(
|
||||
(region, index) => observed.region_order[index] !== region.path,
|
||||
) ||
|
||||
observed.bytes !== this.source.initial.size ||
|
||||
observed.sha256 !== expectedSha256
|
||||
)
|
||||
throw new ArtifactReaderFailure(
|
||||
"integrity",
|
||||
"iNES reconstruction differs from the source",
|
||||
);
|
||||
return {
|
||||
header: layout.header,
|
||||
reconstruction: {
|
||||
...observed,
|
||||
verified: true,
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
provenance(): readonly ArtifactCommand[] {
|
||||
return [];
|
||||
}
|
||||
|
||||
close(): Promise<void> {
|
||||
// Inventory borrows its admitting scope's descriptor. Extraction owns its
|
||||
// separately opened descriptor and retains this reader if close fails.
|
||||
this.#closed = true;
|
||||
return this.ownedSource?.close() ?? Promise.resolve();
|
||||
}
|
||||
|
||||
async #verifySource(signal?: AbortSignal): Promise<void> {
|
||||
abortIfNeeded(signal);
|
||||
if (this.#closed)
|
||||
throw new ArtifactReaderFailure("unavailable", "iNES reader is closed");
|
||||
try {
|
||||
await verifyRegularFileState(this.path, this.source);
|
||||
} catch (cause: unknown) {
|
||||
abortIfNeeded(signal);
|
||||
if (cause instanceof RegularFileChangedError)
|
||||
throw new ArtifactReaderFailure(
|
||||
"integrity",
|
||||
"iNES source changed during reading",
|
||||
{ cause: cause.cause ?? cause },
|
||||
);
|
||||
throw cause;
|
||||
}
|
||||
// State validation is asynchronous even after the final byte was consumed.
|
||||
abortIfNeeded(signal);
|
||||
}
|
||||
}
|
||||
@@ -1,8 +1,13 @@
|
||||
import { lstat, realpath } from "node:fs/promises";
|
||||
import { realpath } from "node:fs/promises";
|
||||
|
||||
import { compareUnicodeCodePoints } from "../../domain/unicodeCodePointOrder.js";
|
||||
import { digestCanonicalValue } from "../../domain/canonicalDigest.js";
|
||||
import { AsarArtifactReader } from "../AsarArtifactReader.js";
|
||||
import { InesArtifactReader } from "../InesArtifactReader.js";
|
||||
import {
|
||||
openRootArtifact,
|
||||
hashStableRootArtifactHandle,
|
||||
} from "../inventory/hashStableRootArtifact.js";
|
||||
import {
|
||||
ArtifactPathRegistry,
|
||||
normalizeArtifactPath,
|
||||
@@ -32,10 +37,7 @@ import type {
|
||||
ArtifactResourceOwner,
|
||||
ArtifactResourceScope,
|
||||
} from "../ArtifactResourceScope.js";
|
||||
import {
|
||||
isMachOFormat,
|
||||
type BinaryTarget,
|
||||
} from "../../domain/binaryTargetTypes.js";
|
||||
import { isMachOFormat } from "../../domain/binaryTargetTypes.js";
|
||||
import type { ArtifactInventorySnapshot } from "../../domain/artifactInventorySnapshot.js";
|
||||
import { scanArtifactInventoryInScope } from "../inventory/ArtifactInventory.js";
|
||||
import type { ArtifactIntegrityPolicyName } from "../../domain/artifactIntegrityPolicy.js";
|
||||
@@ -43,7 +45,8 @@ import type { ArtifactIntegrityPolicyName } from "../../domain/artifactIntegrity
|
||||
/** Local extraction input with the output root chosen by the adapter. */
|
||||
export interface ArtifactExtractionInput {
|
||||
readonly inputPath: string;
|
||||
readonly inputFormat: BinaryTarget["format"];
|
||||
/** Digest of the active session target, when extraction is session-bound. */
|
||||
readonly expectedRootSha256?: string;
|
||||
readonly outputRoot: string;
|
||||
readonly environment: Readonly<NodeJS.ProcessEnv>;
|
||||
readonly integrityPolicy: ArtifactIntegrityPolicyName;
|
||||
@@ -64,13 +67,22 @@ const extractArtifactInScope = async (
|
||||
// Cancellation wins over every later refusal, including unsupported formats.
|
||||
abortIfNeeded(signal);
|
||||
const sourcePath = await realpath(input.inputPath);
|
||||
await requireExtractableFormat(sourcePath, input);
|
||||
const snapshot = await scanArtifactInventoryInScope(sourcePath, {
|
||||
resourceScope: input.resourceScope,
|
||||
signal,
|
||||
environment: input.environment,
|
||||
integrity: { mode: input.integrityPolicy },
|
||||
admitRootFormat: (format) =>
|
||||
requireExtractableFormat(format, input.inputPath),
|
||||
});
|
||||
if (
|
||||
input.expectedRootSha256 !== undefined &&
|
||||
snapshot.manifest.root_sha256 !== input.expectedRootSha256
|
||||
)
|
||||
throw new ArtifactReaderFailure(
|
||||
"integrity",
|
||||
`Active artifact digest changed: expected ${input.expectedRootSha256}, observed ${snapshot.manifest.root_sha256}`,
|
||||
);
|
||||
return materializeArtifactInventoryInScope(
|
||||
input,
|
||||
sourcePath,
|
||||
@@ -217,7 +229,12 @@ const materializeSelection = async ({
|
||||
const byPath = new Map(
|
||||
selected.map((item) => [item.occurrence.logical_path, item]),
|
||||
);
|
||||
const reader = await createReader(sourcePath, input);
|
||||
const reader = await createReader(
|
||||
sourcePath,
|
||||
input,
|
||||
inventory.manifest,
|
||||
signal,
|
||||
);
|
||||
const readerOwner: ArtifactResourceOwner = {
|
||||
kind: "reader" as const,
|
||||
reader,
|
||||
@@ -402,43 +419,89 @@ interface ExtractionInventory {
|
||||
}
|
||||
|
||||
/**
|
||||
* Refuse a format without an extraction reader before inventory work starts.
|
||||
* The target kind, not the host, is unsupported by extraction. The error keeps
|
||||
* the caller's spelling of the path; I/O uses the canonical path.
|
||||
* Admit the scanner's format, preserving the caller's path in a refusal.
|
||||
*/
|
||||
const requireExtractableFormat = async (
|
||||
path: string,
|
||||
input: Pick<ArtifactExtractionInput, "inputPath" | "inputFormat">,
|
||||
): Promise<boolean> => {
|
||||
const format = input.inputFormat;
|
||||
const directory = (await lstat(path)).isDirectory();
|
||||
const requireExtractableFormat = (
|
||||
format: ArtifactGraphManifest["root_format"],
|
||||
inputPath: string,
|
||||
): void => {
|
||||
if (
|
||||
!directory &&
|
||||
format !== "directory" &&
|
||||
format !== "asar" &&
|
||||
format !== "ines" &&
|
||||
!isMachOFormat(format) &&
|
||||
!isZipPackageFormat(format)
|
||||
)
|
||||
throw new AnalysisUnsupportedTargetError(
|
||||
"extract_artifact",
|
||||
input.inputPath,
|
||||
inputPath,
|
||||
`Artifact format has no extraction reader: ${format}`,
|
||||
);
|
||||
return directory;
|
||||
};
|
||||
|
||||
const createReader = async (
|
||||
path: string,
|
||||
input: Pick<
|
||||
ArtifactExtractionInput,
|
||||
"inputPath" | "inputFormat" | "environment"
|
||||
"inputPath" | "environment" | "resourceScope"
|
||||
>,
|
||||
manifest: ArtifactGraphManifest,
|
||||
signal?: AbortSignal,
|
||||
): Promise<ArtifactReader> => {
|
||||
const format = input.inputFormat;
|
||||
if (await requireExtractableFormat(path, input))
|
||||
return new DirectoryArtifactReader(path);
|
||||
// The current scan owns format selection; the opened target may be stale.
|
||||
const format = manifest.root_format;
|
||||
if (format === "ines") {
|
||||
const owner = await openRootArtifact(
|
||||
path,
|
||||
input.resourceScope,
|
||||
signal,
|
||||
"inventoried",
|
||||
);
|
||||
try {
|
||||
const initial = await owner.handle.stat();
|
||||
const digest = await hashStableRootArtifactHandle(
|
||||
path,
|
||||
owner.handle,
|
||||
initial,
|
||||
signal,
|
||||
);
|
||||
if (digest.sha256 !== manifest.root_sha256)
|
||||
throw new ArtifactReaderFailure(
|
||||
"integrity",
|
||||
`Inventoried iNES source bytes changed: ${path}`,
|
||||
);
|
||||
return new InesArtifactReader(
|
||||
path,
|
||||
{
|
||||
handle: owner.handle,
|
||||
initial,
|
||||
},
|
||||
owner,
|
||||
);
|
||||
} catch (cause: unknown) {
|
||||
const attempt = await input.resourceScope.release({
|
||||
kind: "file-handle",
|
||||
handle: owner,
|
||||
resource: `iNES source ${path}`,
|
||||
});
|
||||
if (attempt.kind === "failed")
|
||||
throw ArtifactReaderFailure.withCleanup(
|
||||
cause,
|
||||
ArtifactReaderFailure.cleanupObservation(attempt.cause, path),
|
||||
);
|
||||
throw cause;
|
||||
}
|
||||
}
|
||||
if (format === "directory") return new DirectoryArtifactReader(path);
|
||||
if (format === "asar") return new AsarArtifactReader(path);
|
||||
if (isZipPackageFormat(format)) return new ZipArtifactReader(path, format);
|
||||
return new MachOSliceArtifactReader(path, input.environment);
|
||||
if (format === "mach-o" || format === "mach-o-universal")
|
||||
return new MachOSliceArtifactReader(path, input.environment);
|
||||
throw new AnalysisUnsupportedTargetError(
|
||||
"extract_artifact",
|
||||
input.inputPath,
|
||||
`Artifact format has no extraction reader: ${format}`,
|
||||
);
|
||||
};
|
||||
|
||||
const preflight = (entry: ArtifactEntry): void => {
|
||||
|
||||
@@ -27,6 +27,10 @@ import {
|
||||
classifyFatContainerIdentity,
|
||||
readFatContainerHeader,
|
||||
} from "../../domain/apple/machoContainer.js";
|
||||
import {
|
||||
nesContainerFormat,
|
||||
parseInesLayout,
|
||||
} from "../../domain/inesContainer.js";
|
||||
|
||||
/** Mutable internal occurrence used until root-bound IDs are known. */
|
||||
export interface MutableOccurrence {
|
||||
@@ -227,7 +231,7 @@ export const rootOccurrenceFor = (
|
||||
artifact_kind:
|
||||
metadata.format === "directory" ||
|
||||
isZipPackageFormat(metadata.format) ||
|
||||
["asar", "dmg", "pkg"].includes(metadata.format)
|
||||
["asar", "ines", "dmg", "pkg"].includes(metadata.format)
|
||||
? "container"
|
||||
: artifactRoleForFormat(metadata.path, metadata.format).kind,
|
||||
artifact_format: metadata.format,
|
||||
@@ -427,6 +431,7 @@ const artifactRoleForFormat = (
|
||||
format: zipPackageFormatForPath(path) ?? format,
|
||||
};
|
||||
if (format === "plist") return { kind: "plist", format };
|
||||
if (format === "ines") return { kind: "container", format };
|
||||
return {
|
||||
kind: ["native-addon", "dynamic-library"].includes(byPath.kind)
|
||||
? byPath.kind
|
||||
@@ -440,6 +445,13 @@ export const classifyArtifactBytes = (
|
||||
prefix: Buffer,
|
||||
fileSize = prefix.length,
|
||||
): ArtifactNode["format"] => {
|
||||
// A header-only region has the signature but not the declared cartridge
|
||||
// extent. Keep it as a file instead of inventing another container.
|
||||
if (
|
||||
nesContainerFormat(prefix) === "ines" &&
|
||||
parseInesLayout(prefix, fileSize).ok
|
||||
)
|
||||
return "ines";
|
||||
if (hasZipSignature(prefix)) return "zip";
|
||||
if (hasBinaryPlistSignature(prefix)) return "plist";
|
||||
const fatFormat = classifyFatArtifact(prefix, fileSize);
|
||||
|
||||
@@ -5,6 +5,7 @@ import {
|
||||
type ArtifactInventoryOutput,
|
||||
} from "../../domain/artifactGraph.js";
|
||||
import { abortIfNeeded } from "../ArtifactHash.js";
|
||||
import { ArtifactReaderFailure } from "../ArtifactReader.js";
|
||||
import { scanCanonicalArtifactInventoryInScope } from "./scanCanonical.js";
|
||||
import type { ArtifactInventoryOptions } from "./types.js";
|
||||
import type { ArtifactInventorySnapshot } from "../../domain/artifactInventorySnapshot.js";
|
||||
@@ -33,5 +34,14 @@ export const scanArtifactInventoryInScope = async (
|
||||
): Promise<ArtifactInventorySnapshot> => {
|
||||
abortIfNeeded(options.signal);
|
||||
const path = await realpath(inputPath);
|
||||
return scanCanonicalArtifactInventoryInScope(path, options);
|
||||
const snapshot = await scanCanonicalArtifactInventoryInScope(path, options);
|
||||
if (
|
||||
options.expectedRootSha256 !== undefined &&
|
||||
snapshot.manifest.root_sha256 !== options.expectedRootSha256
|
||||
)
|
||||
throw new ArtifactReaderFailure(
|
||||
"integrity",
|
||||
`Active artifact digest changed: expected ${options.expectedRootSha256}, observed ${snapshot.manifest.root_sha256}`,
|
||||
);
|
||||
return snapshot;
|
||||
};
|
||||
|
||||
@@ -1,11 +1,23 @@
|
||||
import { sameRegularFileState } from "../../filesystem/RegularFile.js";
|
||||
import { readFileHandlePrefix } from "../../filesystem/readFileHandlePrefix.js";
|
||||
import {
|
||||
sameRegularFileState,
|
||||
verifyRegularFileState,
|
||||
RegularFileChangedError,
|
||||
} from "../../filesystem/RegularFile.js";
|
||||
import type { FileHandle } from "node:fs/promises";
|
||||
import type { Stats } from "node:fs";
|
||||
import type { StableRegularFileDescriptor } from "../../filesystem/RegularFile.js";
|
||||
import type { OwnedFileHandle } from "../../filesystem/OwnedFileHandle.js";
|
||||
|
||||
import { classifyArtifactContent } from "./ArtifactGraphConstruction.js";
|
||||
import { ARTIFACT_CLASSIFICATION_PREFIX_BYTES } from "../ArtifactHash.js";
|
||||
import {
|
||||
nesContainerFormat,
|
||||
parseInesLayout,
|
||||
} from "../../domain/inesContainer.js";
|
||||
import {
|
||||
abortIfNeeded,
|
||||
ARTIFACT_CLASSIFICATION_PREFIX_BYTES,
|
||||
} from "../ArtifactHash.js";
|
||||
import type { ArtifactOccurrence } from "../../domain/artifactGraph.js";
|
||||
import {
|
||||
hasZipSignature,
|
||||
@@ -41,7 +53,10 @@ export const classifyAndHashRoot = async (
|
||||
path: string,
|
||||
directory: boolean,
|
||||
expectedMetadata: Stats,
|
||||
options: Pick<ArtifactInventoryOptions, "resourceScope" | "signal">,
|
||||
options: Pick<
|
||||
ArtifactInventoryOptions,
|
||||
"resourceScope" | "signal" | "admitRootFormat"
|
||||
>,
|
||||
): Promise<RootClassification> => {
|
||||
return options.resourceScope.run(async () => {
|
||||
const result = await classifyAndHashRootForInventory(
|
||||
@@ -71,15 +86,21 @@ export const classifyAndHashRoot = async (
|
||||
});
|
||||
};
|
||||
|
||||
/** Classify a root and retain its admitted ZIP descriptor for child inventory. */
|
||||
/** Classify a root and retain its admitted container descriptor for child inventory. */
|
||||
export const classifyAndHashRootForInventory = async (
|
||||
path: string,
|
||||
directory: boolean,
|
||||
expectedMetadata: Stats,
|
||||
options: Pick<ArtifactInventoryOptions, "resourceScope" | "signal">,
|
||||
options: Pick<
|
||||
ArtifactInventoryOptions,
|
||||
"resourceScope" | "signal" | "admitRootFormat"
|
||||
>,
|
||||
): Promise<RootInventoryClassification> => {
|
||||
if (directory)
|
||||
abortIfNeeded(options.signal);
|
||||
if (directory) {
|
||||
options.admitRootFormat?.("directory");
|
||||
return { format: "directory", digest: null, rootSource: undefined };
|
||||
}
|
||||
const ownedHandle = await openRootArtifact(
|
||||
path,
|
||||
options.resourceScope,
|
||||
@@ -99,12 +120,20 @@ export const classifyAndHashRootForInventory = async (
|
||||
| { readonly kind: "failed"; readonly cause: unknown };
|
||||
try {
|
||||
const initial = await handle.stat();
|
||||
abortIfNeeded(options.signal);
|
||||
if (!sameRegularFileState(expectedMetadata, initial))
|
||||
throw new ArtifactReaderFailure(
|
||||
"integrity",
|
||||
`Root artifact changed before inventory: ${path}`,
|
||||
);
|
||||
const format = await classifyRootFormat(path, handle);
|
||||
const format = await classifyRootFormat(
|
||||
path,
|
||||
handle,
|
||||
initial,
|
||||
options.signal,
|
||||
);
|
||||
abortIfNeeded(options.signal);
|
||||
options.admitRootFormat?.(format);
|
||||
const digest = await hashStableRootArtifactHandle(
|
||||
path,
|
||||
handle,
|
||||
@@ -112,7 +141,9 @@ export const classifyAndHashRootForInventory = async (
|
||||
options.signal,
|
||||
);
|
||||
const retainSource =
|
||||
isZipPackageFormat(format) || format === "mach-o-universal";
|
||||
isZipPackageFormat(format) ||
|
||||
format === "mach-o-universal" ||
|
||||
format === "ines";
|
||||
outcome = {
|
||||
kind: "completed",
|
||||
value: {
|
||||
@@ -124,7 +155,23 @@ export const classifyAndHashRootForInventory = async (
|
||||
},
|
||||
};
|
||||
} catch (cause: unknown) {
|
||||
outcome = { kind: "failed", cause };
|
||||
outcome = {
|
||||
kind: "failed",
|
||||
cause:
|
||||
options.signal?.aborted === true
|
||||
? new ArtifactReaderFailure(
|
||||
"cancelled",
|
||||
"Artifact inventory cancelled",
|
||||
{ cause },
|
||||
)
|
||||
: cause instanceof RegularFileChangedError
|
||||
? new ArtifactReaderFailure(
|
||||
"integrity",
|
||||
`Root artifact changed during inventory: ${path}`,
|
||||
{ cause: cause.cause ?? cause },
|
||||
)
|
||||
: cause,
|
||||
};
|
||||
}
|
||||
if (outcome.kind === "failed" || outcome.value.rootSource === undefined) {
|
||||
const cleanupAttempt = await options.resourceScope.release(owner);
|
||||
@@ -144,10 +191,23 @@ export const classifyAndHashRootForInventory = async (
|
||||
const classifyRootFormat = async (
|
||||
path: string,
|
||||
handle: FileHandle,
|
||||
initial: Stats,
|
||||
signal?: AbortSignal,
|
||||
): Promise<ArtifactOccurrence["artifact_format"]> => {
|
||||
const magic = Buffer.alloc(ARTIFACT_CLASSIFICATION_PREFIX_BYTES);
|
||||
const observed = await handle.read(magic, 0, magic.length, 0);
|
||||
const prefix = magic.subarray(0, observed.bytesRead);
|
||||
abortIfNeeded(signal);
|
||||
const prefix = await readFileHandlePrefix(
|
||||
handle,
|
||||
ARTIFACT_CLASSIFICATION_PREFIX_BYTES,
|
||||
() => abortIfNeeded(signal),
|
||||
);
|
||||
abortIfNeeded(signal);
|
||||
await verifyRegularFileState(path, { handle, initial });
|
||||
abortIfNeeded(signal);
|
||||
if (nesContainerFormat(prefix) !== undefined) {
|
||||
const parsed = parseInesLayout(prefix, initial.size);
|
||||
if (!parsed.ok) throw new ArtifactReaderFailure("format", parsed.error);
|
||||
return "ines";
|
||||
}
|
||||
const lower = path.toLowerCase();
|
||||
if (hasZipSignature(prefix)) return zipRootPackageFormat(lower);
|
||||
if (
|
||||
|
||||
@@ -1,4 +1,3 @@
|
||||
import { lstat } from "node:fs/promises";
|
||||
import type { Stats } from "node:fs";
|
||||
import type { FileHandle } from "node:fs/promises";
|
||||
import { readFileHandleChunks } from "../../filesystem/readFileHandleChunks.js";
|
||||
@@ -9,7 +8,8 @@ import {
|
||||
NonRegularFileReadError,
|
||||
RegularFileAdmissionFailure,
|
||||
openRegularFile,
|
||||
sameRegularFileState,
|
||||
RegularFileChangedError,
|
||||
verifyRegularFileState,
|
||||
} from "../../filesystem/RegularFile.js";
|
||||
import {
|
||||
abortIfNeeded,
|
||||
@@ -23,6 +23,7 @@ export const openRootArtifact = async (
|
||||
path: string,
|
||||
resourceScope: ArtifactResourceScope,
|
||||
signal?: AbortSignal,
|
||||
admission: "initial" | "inventoried" = "initial",
|
||||
): Promise<OwnedFileHandle> => {
|
||||
try {
|
||||
return new OwnedFileHandle(
|
||||
@@ -31,14 +32,41 @@ export const openRootArtifact = async (
|
||||
} catch (cause: unknown) {
|
||||
const primary =
|
||||
cause instanceof RegularFileAdmissionFailure ? cause.cause : cause;
|
||||
const changed =
|
||||
admission === "inventoried" &&
|
||||
(primary instanceof NonRegularFileReadError ||
|
||||
primary instanceof RegularFileChangedError ||
|
||||
(primary instanceof Error &&
|
||||
"code" in primary &&
|
||||
[
|
||||
"ENOENT",
|
||||
"ENOTDIR",
|
||||
"ELOOP",
|
||||
"EISDIR",
|
||||
"ENOTFILE",
|
||||
"ESTALE",
|
||||
].includes(String(primary.code))));
|
||||
// Normalize the primary failure before cleanup so failed closes keep both facts.
|
||||
const failure =
|
||||
primary instanceof NonRegularFileReadError
|
||||
signal?.aborted === true
|
||||
? new ArtifactReaderFailure(
|
||||
"format",
|
||||
`Artifact root is not a regular file: ${path}`,
|
||||
"cancelled",
|
||||
"Artifact admission cancelled",
|
||||
{ cause: primary },
|
||||
)
|
||||
: primary;
|
||||
: changed
|
||||
? new ArtifactReaderFailure(
|
||||
"integrity",
|
||||
`Inventoried artifact source changed: ${path}`,
|
||||
{ cause: primary },
|
||||
)
|
||||
: primary instanceof NonRegularFileReadError
|
||||
? new ArtifactReaderFailure(
|
||||
"format",
|
||||
`Artifact root is not a regular file: ${path}`,
|
||||
{ cause: primary },
|
||||
)
|
||||
: primary;
|
||||
if (cause instanceof RegularFileAdmissionFailure) {
|
||||
const resource = `root artifact descriptor for ${path}`;
|
||||
const cleanup = await resourceScope.release({
|
||||
@@ -105,12 +133,20 @@ export const hashStableRootArtifactHandle = async (
|
||||
signal,
|
||||
);
|
||||
abortIfNeeded(signal);
|
||||
const [opened, currentPath] = await Promise.all([handle.stat(), lstat(path)]);
|
||||
if (
|
||||
!sameRegularFileState(initial, opened) ||
|
||||
!sameRegularFileState(initial, currentPath) ||
|
||||
digest.bytes !== initial.size
|
||||
)
|
||||
try {
|
||||
await verifyRegularFileState(path, { handle, initial });
|
||||
} catch (cause: unknown) {
|
||||
abortIfNeeded(signal);
|
||||
if (cause instanceof RegularFileChangedError)
|
||||
throw new ArtifactReaderFailure(
|
||||
"integrity",
|
||||
`Root artifact changed during inventory: ${path}`,
|
||||
{ cause: cause.cause ?? cause },
|
||||
);
|
||||
throw cause;
|
||||
}
|
||||
abortIfNeeded(signal);
|
||||
if (digest.bytes !== initial.size)
|
||||
throw new ArtifactReaderFailure(
|
||||
"integrity",
|
||||
`Root artifact changed during inventory: ${path}`,
|
||||
|
||||
@@ -1,4 +1,6 @@
|
||||
import { AsarArtifactReader } from "../AsarArtifactReader.js";
|
||||
import { InesArtifactReader, INES_LIMITATION } from "../InesArtifactReader.js";
|
||||
import { ArtifactReaderFailure } from "../ArtifactReader.js";
|
||||
import type { ArtifactReader } from "../ArtifactReader.js";
|
||||
import { DirectoryArtifactReader } from "../DirectoryArtifactReader.js";
|
||||
import { MachOSliceArtifactReader } from "../MachOSliceArtifactReader.js";
|
||||
@@ -24,6 +26,13 @@ export const createReader = (
|
||||
if (isZipPackageFormat(format))
|
||||
return new ZipArtifactReader(path, format, undefined, rootSource);
|
||||
switch (format) {
|
||||
case "ines":
|
||||
if (rootSource === undefined)
|
||||
throw new ArtifactReaderFailure(
|
||||
"integrity",
|
||||
"iNES inventory requires its admitted source descriptor",
|
||||
);
|
||||
return new InesArtifactReader(path, rootSource);
|
||||
case "directory":
|
||||
return new DirectoryArtifactReader(path);
|
||||
case "asar":
|
||||
@@ -52,6 +61,7 @@ export const inventoryAssessment = (
|
||||
} => {
|
||||
let coverageStatus: ArtifactInventoryCoverage = "complete";
|
||||
const limitations: string[] = [];
|
||||
if (format === "ines") limitations.push(INES_LIMITATION);
|
||||
if (reader !== undefined) {
|
||||
if (isZipPackageFormat(reader.format))
|
||||
limitations.push(ZIP_NON_ENTRY_TAIL_LIMITATION);
|
||||
|
||||
@@ -1,7 +1,12 @@
|
||||
import type { ArtifactInventorySnapshot } from "../../domain/artifactInventorySnapshot.js";
|
||||
import type { InesInventory } from "../../domain/inesContainer.js";
|
||||
import { compareUnicodeCodePoints } from "../../domain/unicodeCodePointOrder.js";
|
||||
|
||||
import { AsarArtifactReader } from "../AsarArtifactReader.js";
|
||||
import {
|
||||
InesArtifactReader,
|
||||
type InesRegionScan,
|
||||
} from "../InesArtifactReader.js";
|
||||
|
||||
import { lstat } from "node:fs/promises";
|
||||
import type { Stats } from "node:fs";
|
||||
@@ -99,6 +104,7 @@ export const scanCanonicalArtifactInventoryInScope = async (
|
||||
occurrences,
|
||||
pendingContradictions,
|
||||
caseCollisionLimitation,
|
||||
inesRegionScan,
|
||||
} = await scanReader(reader, ownedReaders, options.signal, integrity);
|
||||
outcome = {
|
||||
kind: "completed",
|
||||
@@ -115,6 +121,7 @@ export const scanCanonicalArtifactInventoryInScope = async (
|
||||
occurrences,
|
||||
pendingContradictions,
|
||||
caseCollisionLimitation,
|
||||
inesRegionScan,
|
||||
}),
|
||||
};
|
||||
} catch (cause: unknown) {
|
||||
@@ -196,6 +203,7 @@ interface SnapshotBuildInput {
|
||||
readonly occurrences: MutableOccurrence[];
|
||||
readonly pendingContradictions: PendingIntegrityContradiction[];
|
||||
readonly caseCollisionLimitation: string | undefined;
|
||||
readonly inesRegionScan: InesRegionScan | undefined;
|
||||
}
|
||||
|
||||
const buildInventorySnapshot = async (
|
||||
@@ -274,8 +282,22 @@ const buildInventorySnapshot = async (
|
||||
integrityContradictions,
|
||||
input.caseCollisionLimitation,
|
||||
);
|
||||
let ines: InesInventory | undefined;
|
||||
if (reader instanceof InesArtifactReader) {
|
||||
if (rootDigest === null || input.inesRegionScan === undefined)
|
||||
throw new ArtifactReaderFailure(
|
||||
"integrity",
|
||||
"Missing iNES reconstruction scan",
|
||||
);
|
||||
ines = await reader.verifyReconstruction(
|
||||
rootDigest.sha256,
|
||||
input.inesRegionScan,
|
||||
signal,
|
||||
);
|
||||
}
|
||||
return {
|
||||
manifest,
|
||||
...(ines === undefined ? {} : { ines }),
|
||||
nodes: orderedNodes,
|
||||
occurrences: orderedOccurrences,
|
||||
edges: orderedEdges,
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
import { isAbsolute } from "node:path";
|
||||
import { createHash, type Hash } from "node:crypto";
|
||||
|
||||
import {
|
||||
annotateEnglishUnicodeCaseCollisions,
|
||||
@@ -11,6 +12,10 @@ import {
|
||||
type ArtifactReader,
|
||||
} from "../ArtifactReader.js";
|
||||
import { AsarArtifactReader } from "../AsarArtifactReader.js";
|
||||
import {
|
||||
InesArtifactReader,
|
||||
type InesRegionScan,
|
||||
} from "../InesArtifactReader.js";
|
||||
import type { ArtifactNode } from "../../domain/artifactGraph.js";
|
||||
import {
|
||||
classifyArtifactContent,
|
||||
@@ -55,6 +60,13 @@ interface ScanContext {
|
||||
readonly registry: ArtifactPathRegistry;
|
||||
readonly expandedContainerIds: Set<string>;
|
||||
readonly ownedReaders: ArtifactReader[];
|
||||
readonly reconstruction:
|
||||
| {
|
||||
readonly hash: Hash;
|
||||
readonly regionOrder: string[];
|
||||
bytes: number;
|
||||
}
|
||||
| undefined;
|
||||
}
|
||||
|
||||
export const scanReader = async (
|
||||
@@ -67,6 +79,7 @@ export const scanReader = async (
|
||||
readonly occurrences: MutableOccurrence[];
|
||||
readonly pendingContradictions: PendingIntegrityContradiction[];
|
||||
readonly caseCollisionLimitation: string | undefined;
|
||||
readonly inesRegionScan: InesRegionScan | undefined;
|
||||
}> => {
|
||||
const { nodes, occurrences, pendingContradictions } = emptyScan();
|
||||
if (reader === undefined)
|
||||
@@ -75,6 +88,7 @@ export const scanReader = async (
|
||||
occurrences,
|
||||
pendingContradictions,
|
||||
caseCollisionLimitation: undefined,
|
||||
inesRegionScan: undefined,
|
||||
};
|
||||
const context: ScanContext = {
|
||||
reader,
|
||||
@@ -87,6 +101,10 @@ export const scanReader = async (
|
||||
registry: new ArtifactPathRegistry(),
|
||||
expandedContainerIds: new Set<string>(),
|
||||
ownedReaders,
|
||||
reconstruction:
|
||||
reader instanceof InesArtifactReader
|
||||
? { hash: createHash("sha256"), regionOrder: [], bytes: 0 }
|
||||
: undefined,
|
||||
};
|
||||
await visitArtifactEntries(context, reader, "");
|
||||
// Archive directories may appear after their children. Resolve containment
|
||||
@@ -101,6 +119,14 @@ export const scanReader = async (
|
||||
occurrences,
|
||||
pendingContradictions,
|
||||
caseCollisionLimitation: annotateEnglishUnicodeCaseCollisions(occurrences),
|
||||
inesRegionScan:
|
||||
context.reconstruction === undefined
|
||||
? undefined
|
||||
: {
|
||||
region_order: context.reconstruction.regionOrder,
|
||||
bytes: context.reconstruction.bytes,
|
||||
sha256: context.reconstruction.hash.digest("hex"),
|
||||
},
|
||||
};
|
||||
};
|
||||
|
||||
@@ -233,10 +259,22 @@ const digestArtifactEntry = async (
|
||||
> => {
|
||||
if ((entry.kind !== "file" && entry.kind !== "slice") || entry.encrypted)
|
||||
return undefined;
|
||||
const reconstruction =
|
||||
currentReader === context.reader ? context.reconstruction : undefined;
|
||||
if (reconstruction !== undefined && entry.byteOffset !== reconstruction.bytes)
|
||||
throw new ArtifactReaderFailure("integrity", "Noncontiguous iNES regions");
|
||||
const digest = await hashReadable(
|
||||
await currentReader.open(entry, context.signal),
|
||||
context.signal,
|
||||
reconstruction === undefined
|
||||
? undefined
|
||||
: (chunk) => {
|
||||
// Hash the same bytes used for each node, in physical region order.
|
||||
reconstruction.hash.update(chunk);
|
||||
reconstruction.bytes += chunk.length;
|
||||
},
|
||||
);
|
||||
reconstruction?.regionOrder.push(entry.path);
|
||||
const mismatched =
|
||||
entry.declaredSha256 !== null && entry.declaredSha256 !== digest.sha256;
|
||||
if (mismatched && entry.declaredSha256 !== null) {
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
import type { ArtifactResourceScope } from "../ArtifactResourceScope.js";
|
||||
import type { ArtifactOccurrence } from "../../domain/artifactGraph.js";
|
||||
|
||||
/** Resolved integrity behavior admitted to the artifact scanner. */
|
||||
export type ArtifactIntegrityPolicy =
|
||||
@@ -12,7 +13,13 @@ export const STRICT_INTEGRITY_POLICY: ArtifactIntegrityPolicy = {
|
||||
/** Options shared by artifact inventory scans. */
|
||||
export interface ArtifactInventoryOptions {
|
||||
readonly resourceScope: ArtifactResourceScope;
|
||||
/** Bind a session-owned leaf inventory to the admitted root digest. */
|
||||
readonly expectedRootSha256?: string | undefined;
|
||||
readonly signal?: AbortSignal | undefined;
|
||||
readonly integrity?: ArtifactIntegrityPolicy | undefined;
|
||||
readonly environment?: Readonly<NodeJS.ProcessEnv> | undefined;
|
||||
/** Admit the current root before payload hashing or native child inventory. */
|
||||
readonly admitRootFormat?: (
|
||||
format: ArtifactOccurrence["artifact_format"],
|
||||
) => void;
|
||||
}
|
||||
|
||||
@@ -49,13 +49,14 @@ import { ProviderAdapterError } from "../domain/providerAdapterError.js";
|
||||
import type { BrowserObservationOperation } from "../domain/browserObservationErrors.js";
|
||||
import { err, ok, type Result } from "../domain/result.js";
|
||||
import {
|
||||
discoverCdpEndpoint,
|
||||
hasCdpTargetWebSocket,
|
||||
type CdpEndpointDiscovery,
|
||||
type CdpEndpointTarget,
|
||||
} from "./CdpEndpoint.js";
|
||||
import {
|
||||
attachCdpTargetSession,
|
||||
closeCdpTargetSession,
|
||||
openCdpEndpoint,
|
||||
openCdpTargetSession,
|
||||
type CdpTargetSession,
|
||||
} from "./CdpTargetSession.js";
|
||||
@@ -82,11 +83,13 @@ export class CdpBrowserProvider implements BrowserObservationPort {
|
||||
options: ExecutionOptions = {},
|
||||
): Promise<Result<BrowserTargetList, AnalysisError>> {
|
||||
try {
|
||||
const discovery = await discoverCdpEndpoint(
|
||||
const endpoint = await openCdpEndpoint(
|
||||
input.cdp_endpoint,
|
||||
"list_browser_targets",
|
||||
options.signal,
|
||||
);
|
||||
await endpoint.connection?.close();
|
||||
const { discovery } = endpoint;
|
||||
const selected = selectTargets(
|
||||
discovery,
|
||||
input.allowed_origins.length === 0
|
||||
@@ -169,45 +172,19 @@ export class CdpBrowserProvider implements BrowserObservationPort {
|
||||
input: ObserveWebSessionInput,
|
||||
options: ExecutionOptions = {},
|
||||
): Promise<Result<WebObservationSession, AnalysisError>> {
|
||||
let targetSession: CdpTargetSession | undefined;
|
||||
try {
|
||||
const discovery = await discoverCdpEndpoint(
|
||||
input.cdp_endpoint,
|
||||
"observe_web_session",
|
||||
options.signal,
|
||||
);
|
||||
const target = authorizeTarget(discovery, input);
|
||||
const scopedInput = scopeToTargetOrigin(input, target);
|
||||
targetSession = await openCdpTargetSession(
|
||||
discovery,
|
||||
target,
|
||||
"observe_web_session",
|
||||
options.signal,
|
||||
);
|
||||
return ok(
|
||||
webObservationSessionSchema.parse(
|
||||
await observeCdpSession({
|
||||
connection: targetSession.connection,
|
||||
sessionId: targetSession.sessionId,
|
||||
discovery,
|
||||
target,
|
||||
input: scopedInput,
|
||||
...(options.signal === undefined ? {} : { signal: options.signal }),
|
||||
...(options.progress === undefined
|
||||
? {}
|
||||
: { progress: options.progress }),
|
||||
}),
|
||||
await withTargetSession(
|
||||
input,
|
||||
"observe_web_session",
|
||||
options,
|
||||
observeCdpSession,
|
||||
),
|
||||
),
|
||||
);
|
||||
} catch (cause: unknown) {
|
||||
return err(providerError(cause, "observe_web_session"));
|
||||
} finally {
|
||||
if (targetSession !== undefined)
|
||||
await closeCdpTargetSession(
|
||||
targetSession,
|
||||
CLEANUP_DOMAINS,
|
||||
options.signal,
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
@@ -215,45 +192,19 @@ export class CdpBrowserProvider implements BrowserObservationPort {
|
||||
input: DiscoverWebMcpToolsInput,
|
||||
options: ExecutionOptions = {},
|
||||
): Promise<Result<WebMcpDiscovery, AnalysisError>> {
|
||||
let targetSession: CdpTargetSession | undefined;
|
||||
try {
|
||||
const discovery = await discoverCdpEndpoint(
|
||||
input.cdp_endpoint,
|
||||
"discover_webmcp_tools",
|
||||
options.signal,
|
||||
);
|
||||
const target = authorizeTarget(discovery, input);
|
||||
const scopedInput = scopeToTargetOrigin(input, target);
|
||||
targetSession = await openCdpTargetSession(
|
||||
discovery,
|
||||
target,
|
||||
"discover_webmcp_tools",
|
||||
options.signal,
|
||||
);
|
||||
return ok(
|
||||
webMcpDiscoverySchema.parse(
|
||||
await discoverWebMcp({
|
||||
connection: targetSession.connection,
|
||||
sessionId: targetSession.sessionId,
|
||||
discovery,
|
||||
target,
|
||||
input: scopedInput,
|
||||
...(options.signal === undefined ? {} : { signal: options.signal }),
|
||||
...(options.progress === undefined
|
||||
? {}
|
||||
: { progress: options.progress }),
|
||||
}),
|
||||
await withTargetSession(
|
||||
input,
|
||||
"discover_webmcp_tools",
|
||||
options,
|
||||
discoverWebMcp,
|
||||
),
|
||||
),
|
||||
);
|
||||
} catch (cause: unknown) {
|
||||
return err(providerError(cause, "discover_webmcp_tools"));
|
||||
} finally {
|
||||
if (targetSession !== undefined)
|
||||
await closeCdpTargetSession(
|
||||
targetSession,
|
||||
CLEANUP_DOMAINS,
|
||||
options.signal,
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
@@ -273,45 +224,19 @@ export class CdpBrowserProvider implements BrowserObservationPort {
|
||||
input: CaptureWebScreenshotInput,
|
||||
options: ExecutionOptions = {},
|
||||
): Promise<Result<WebScreenshot, AnalysisError>> {
|
||||
let targetSession: CdpTargetSession | undefined;
|
||||
try {
|
||||
const discovery = await discoverCdpEndpoint(
|
||||
input.cdp_endpoint,
|
||||
"capture_web_screenshot",
|
||||
options.signal,
|
||||
);
|
||||
const target = authorizeTarget(discovery, input);
|
||||
const scopedInput = scopeToTargetOrigin(input, target);
|
||||
targetSession = await openCdpTargetSession(
|
||||
discovery,
|
||||
target,
|
||||
"capture_web_screenshot",
|
||||
options.signal,
|
||||
);
|
||||
return ok(
|
||||
webScreenshotSchema.parse(
|
||||
await captureCdpScreenshot({
|
||||
connection: targetSession.connection,
|
||||
sessionId: targetSession.sessionId,
|
||||
discovery,
|
||||
target,
|
||||
input: scopedInput,
|
||||
...(options.signal === undefined ? {} : { signal: options.signal }),
|
||||
...(options.progress === undefined
|
||||
? {}
|
||||
: { progress: options.progress }),
|
||||
}),
|
||||
await withTargetSession(
|
||||
input,
|
||||
"capture_web_screenshot",
|
||||
options,
|
||||
captureCdpScreenshot,
|
||||
),
|
||||
),
|
||||
);
|
||||
} catch (cause: unknown) {
|
||||
return err(providerError(cause, "capture_web_screenshot"));
|
||||
} finally {
|
||||
if (targetSession !== undefined)
|
||||
await closeCdpTargetSession(
|
||||
targetSession,
|
||||
CLEANUP_DOMAINS,
|
||||
options.signal,
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
@@ -336,44 +261,83 @@ export class CdpBrowserProvider implements BrowserObservationPort {
|
||||
options: ExecutionOptions,
|
||||
operation: "inspect_web_page" | "analyze_web_bundle",
|
||||
): Promise<CapturedPage> {
|
||||
let targetSession: CdpTargetSession | undefined;
|
||||
try {
|
||||
const discovery = await discoverCdpEndpoint(
|
||||
input.cdp_endpoint,
|
||||
operation,
|
||||
options.signal,
|
||||
);
|
||||
const target = authorizeTarget(discovery, input);
|
||||
const scopedInput = scopeToTargetOrigin(input, target);
|
||||
targetSession = await openCdpTargetSession(
|
||||
discovery,
|
||||
target,
|
||||
operation,
|
||||
options.signal,
|
||||
);
|
||||
return await capturePage({
|
||||
connection: targetSession.connection,
|
||||
sessionId: targetSession.sessionId,
|
||||
operation,
|
||||
discovery,
|
||||
target,
|
||||
input: scopedInput,
|
||||
...(options.signal === undefined ? {} : { signal: options.signal }),
|
||||
...(options.progress === undefined
|
||||
? {}
|
||||
: { progress: options.progress }),
|
||||
});
|
||||
} finally {
|
||||
if (targetSession !== undefined)
|
||||
await closeCdpTargetSession(
|
||||
targetSession,
|
||||
CLEANUP_DOMAINS,
|
||||
options.signal,
|
||||
);
|
||||
}
|
||||
return await withTargetSession(
|
||||
input,
|
||||
operation,
|
||||
options,
|
||||
async (session) => await capturePage({ ...session, operation }),
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
/** Facts and transport handed to one target operation. */
|
||||
interface CdpTargetOperationSession<Input> {
|
||||
readonly connection: CdpTargetSession["connection"];
|
||||
readonly sessionId: CdpTargetSession["sessionId"];
|
||||
readonly discovery: CdpEndpointDiscovery;
|
||||
readonly target: CdpEndpointTarget;
|
||||
readonly input: Input;
|
||||
readonly signal?: AbortSignal;
|
||||
readonly progress?: NonNullable<ExecutionOptions["progress"]>;
|
||||
}
|
||||
|
||||
/** Authorize one discovered target, run work in its session, and close REA's socket. */
|
||||
const withTargetSession = async <
|
||||
Input extends Pick<
|
||||
InspectWebPageInput,
|
||||
"cdp_endpoint" | "target_id" | "allowed_origins"
|
||||
>,
|
||||
Output,
|
||||
>(
|
||||
input: Input,
|
||||
operation: BrowserObservationOperation,
|
||||
options: ExecutionOptions,
|
||||
work: (session: CdpTargetOperationSession<Input>) => Promise<Output>,
|
||||
): Promise<Output> => {
|
||||
const endpoint = await openCdpEndpoint(
|
||||
input.cdp_endpoint,
|
||||
operation,
|
||||
options.signal,
|
||||
);
|
||||
let targetSession: CdpTargetSession | undefined;
|
||||
try {
|
||||
const target = authorizeTarget(endpoint.discovery, input);
|
||||
const scopedInput = scopeToTargetOrigin(input, target);
|
||||
targetSession =
|
||||
endpoint.connection === undefined
|
||||
? await openCdpTargetSession(
|
||||
endpoint.discovery,
|
||||
target,
|
||||
operation,
|
||||
options.signal,
|
||||
)
|
||||
: await attachCdpTargetSession(
|
||||
endpoint.connection,
|
||||
target,
|
||||
operation,
|
||||
options.signal,
|
||||
);
|
||||
return await work({
|
||||
connection: targetSession.connection,
|
||||
sessionId: targetSession.sessionId,
|
||||
discovery: endpoint.discovery,
|
||||
target,
|
||||
input: scopedInput,
|
||||
...(options.signal === undefined ? {} : { signal: options.signal }),
|
||||
...(options.progress === undefined ? {} : { progress: options.progress }),
|
||||
});
|
||||
} finally {
|
||||
if (targetSession !== undefined)
|
||||
await closeCdpTargetSession(
|
||||
targetSession,
|
||||
CLEANUP_DOMAINS,
|
||||
options.signal,
|
||||
);
|
||||
// An unadopted browser socket is closed here; closing is idempotent.
|
||||
await endpoint.connection?.close();
|
||||
}
|
||||
};
|
||||
|
||||
const selectTargets = (
|
||||
discovery: CdpEndpointDiscovery,
|
||||
allowedOrigins: ReadonlySet<string> | undefined,
|
||||
|
||||
@@ -9,6 +9,7 @@ import type { BrowserObservationOperation } from "../domain/browserObservationEr
|
||||
import { sanitizeBrowserUrl } from "../domain/browserObservation.js";
|
||||
import { urlDeclaresQueryOrFragment } from "../domain/urlComponents.js";
|
||||
import { safeParseJson } from "../domain/safeJson.js";
|
||||
import type { CdpConnection } from "./CdpConnection.js";
|
||||
|
||||
const endpointVersionSchema = z.object({
|
||||
Browser: z.string().min(1),
|
||||
@@ -40,6 +41,26 @@ interface CdpDiscoveryResponseLimits {
|
||||
readonly timeoutMs: number;
|
||||
}
|
||||
|
||||
const browserSocketVersionSchema = z.object({
|
||||
protocolVersion: z.string().min(1),
|
||||
product: z.string().min(1),
|
||||
revision: z.string(),
|
||||
userAgent: z.string(),
|
||||
jsVersion: z.string(),
|
||||
});
|
||||
|
||||
const browserSocketTargetsSchema = z.object({
|
||||
targetInfos: z.array(
|
||||
z.object({
|
||||
targetId: z.string().min(1),
|
||||
type: z.string().min(1),
|
||||
title: z.string().default(""),
|
||||
url: z.string(),
|
||||
attached: z.boolean().optional(),
|
||||
}),
|
||||
),
|
||||
});
|
||||
|
||||
/** Validated direct CDP WebSocket bound to one discovered page target. */
|
||||
interface CdpPageWebSocketEndpoint {
|
||||
readonly scope: "page";
|
||||
@@ -124,6 +145,88 @@ export const discoverCdpEndpoint = async (
|
||||
};
|
||||
};
|
||||
|
||||
/**
|
||||
* Run browser-socket discovery work, including its WebSocket handshake, under
|
||||
* the HTTP discovery deadline. Reaching the deadline is a timeout, not a
|
||||
* caller cancellation, so the internal abort is not carried as its cause.
|
||||
*/
|
||||
export const withCdpDiscoveryDeadline = async <T>(
|
||||
operation: BrowserObservationOperation,
|
||||
signal: AbortSignal | undefined,
|
||||
work: (deadlineSignal: AbortSignal) => Promise<T>,
|
||||
timeoutMs: number = CDP_DISCOVERY_RESPONSE_LIMITS.timeoutMs,
|
||||
): Promise<T> => {
|
||||
const deadline = new AbortController();
|
||||
const timer = setTimeout(() => deadline.abort(), timeoutMs);
|
||||
try {
|
||||
return await work(
|
||||
signal === undefined
|
||||
? deadline.signal
|
||||
: AbortSignal.any([signal, deadline.signal]),
|
||||
);
|
||||
} catch (cause: unknown) {
|
||||
if (deadline.signal.aborted && signal?.aborted !== true)
|
||||
throw new BrowserObservationError(operation, "timeout", {
|
||||
detail: `CDP browser-socket discovery exceeded its ${String(timeoutMs)} ms deadline.`,
|
||||
});
|
||||
throw cause;
|
||||
} finally {
|
||||
clearTimeout(timer);
|
||||
}
|
||||
};
|
||||
|
||||
/**
|
||||
* Read discovery facts over a browser socket that has no HTTP discovery.
|
||||
* Each reply is bounded by the connection's protocol message limit; callers
|
||||
* apply the discovery deadline through `signal`.
|
||||
*/
|
||||
export const discoverCdpBrowserSocket = async (
|
||||
connection: CdpConnection,
|
||||
url: string,
|
||||
operation: BrowserObservationOperation,
|
||||
signal?: AbortSignal,
|
||||
): Promise<CdpEndpointDiscovery> => {
|
||||
const versionInput = await connection.send(
|
||||
"Browser.getVersion",
|
||||
{},
|
||||
undefined,
|
||||
signal,
|
||||
);
|
||||
const targetsInput = await connection.send(
|
||||
"Target.getTargets",
|
||||
{},
|
||||
undefined,
|
||||
signal,
|
||||
);
|
||||
const version = parseCdpEndpointValue(
|
||||
browserSocketVersionSchema,
|
||||
versionInput,
|
||||
operation,
|
||||
);
|
||||
const targets = parseCdpEndpointValue(
|
||||
browserSocketTargetsSchema,
|
||||
targetsInput,
|
||||
operation,
|
||||
);
|
||||
return {
|
||||
webSocket: { scope: "browser", url },
|
||||
version: {
|
||||
product: version.product,
|
||||
protocol_version: version.protocolVersion,
|
||||
revision: version.revision,
|
||||
user_agent: version.userAgent,
|
||||
js_version: version.jsVersion,
|
||||
},
|
||||
targets: targets.targetInfos.map((target) => ({
|
||||
id: target.targetId,
|
||||
type: target.type,
|
||||
title: sanitizeTargetTitle(target.title, target.url),
|
||||
url: target.url,
|
||||
attached: target.attached ?? null,
|
||||
})),
|
||||
};
|
||||
};
|
||||
|
||||
const sanitizeTargetTitle = (value: string, targetUrl: string): string => {
|
||||
let url: URL;
|
||||
try {
|
||||
|
||||
@@ -1,8 +1,12 @@
|
||||
import type { BrowserObservationEndpoint } from "../domain/browserObservation.js";
|
||||
import { BrowserObservationError } from "../domain/browserObservationError.js";
|
||||
import type { BrowserObservationOperation } from "../domain/browserObservationErrors.js";
|
||||
import { CdpConnection } from "./CdpConnection.js";
|
||||
import {
|
||||
cdpTargetWebSocket,
|
||||
discoverCdpBrowserSocket,
|
||||
discoverCdpEndpoint,
|
||||
withCdpDiscoveryDeadline,
|
||||
type CdpEndpointDiscovery,
|
||||
type CdpEndpointTarget,
|
||||
} from "./CdpEndpoint.js";
|
||||
@@ -13,6 +17,59 @@ export interface CdpTargetSession {
|
||||
readonly sessionId: string | undefined;
|
||||
}
|
||||
|
||||
/** Discovery for one caller-selected endpoint and the browser socket that read it. */
|
||||
export interface CdpOpenedEndpoint {
|
||||
readonly discovery: CdpEndpointDiscovery;
|
||||
/**
|
||||
* Browser socket kept for the target session, because a browser may ask
|
||||
* the user to approve each socket. HTTP discovery opens no socket.
|
||||
*/
|
||||
readonly connection: CdpConnection | undefined;
|
||||
}
|
||||
|
||||
/**
|
||||
* Discover one passive browser endpoint through its selected transport. A
|
||||
* browser socket's handshake and discovery share one discovery deadline.
|
||||
*/
|
||||
export const openCdpEndpoint = async (
|
||||
endpoint: BrowserObservationEndpoint,
|
||||
operation: BrowserObservationOperation,
|
||||
signal?: AbortSignal,
|
||||
timeoutMs?: number,
|
||||
): Promise<CdpOpenedEndpoint> => {
|
||||
if (endpoint.transport === "http_discovery")
|
||||
return {
|
||||
discovery: await discoverCdpEndpoint(endpoint.url, operation, signal),
|
||||
connection: undefined,
|
||||
};
|
||||
return await withCdpDiscoveryDeadline(
|
||||
operation,
|
||||
signal,
|
||||
async (deadlineSignal) => {
|
||||
const connection = await CdpConnection.connect(
|
||||
endpoint.url,
|
||||
operation,
|
||||
deadlineSignal,
|
||||
);
|
||||
try {
|
||||
return {
|
||||
discovery: await discoverCdpBrowserSocket(
|
||||
connection,
|
||||
endpoint.url,
|
||||
operation,
|
||||
deadlineSignal,
|
||||
),
|
||||
connection,
|
||||
};
|
||||
} catch (cause: unknown) {
|
||||
await connection.close();
|
||||
throw cause;
|
||||
}
|
||||
},
|
||||
timeoutMs,
|
||||
);
|
||||
};
|
||||
|
||||
/** Open one authorized target through its supported browser or page transport. */
|
||||
export const openCdpTargetSession = async (
|
||||
discovery: CdpEndpointDiscovery,
|
||||
@@ -29,6 +86,16 @@ export const openCdpTargetSession = async (
|
||||
limits,
|
||||
);
|
||||
if (webSocket.scope === "page") return { connection, sessionId: undefined };
|
||||
return await attachCdpTargetSession(connection, target, operation, signal);
|
||||
};
|
||||
|
||||
/** Attach one target through an open browser socket, which the session then owns. */
|
||||
export const attachCdpTargetSession = async (
|
||||
connection: CdpConnection,
|
||||
target: CdpEndpointTarget,
|
||||
operation: BrowserObservationOperation,
|
||||
signal?: AbortSignal,
|
||||
): Promise<CdpTargetSession> => {
|
||||
try {
|
||||
const attached = await connection.send(
|
||||
"Target.attachToTarget",
|
||||
|
||||
@@ -2,6 +2,17 @@ import {
|
||||
AnalysisCancelledError,
|
||||
AnalysisTimeoutError,
|
||||
} from "../domain/analysisErrorCore.js";
|
||||
import { WEB_RUNTIME_LIMITS } from "../domain/webRuntime.js";
|
||||
|
||||
export const PLAYWRIGHT_NETWORK_READ_TIMEOUT_MS = 5_000;
|
||||
|
||||
// Cleanup drains bounded content reads before closing Chrome and removing its
|
||||
// profile. Cover those stages and retain the observed 30-second allowance for
|
||||
// slow persistent-context close on shared runners.
|
||||
export const PLAYWRIGHT_SCENARIO_CLEANUP_TIMEOUT_MS = Math.max(
|
||||
30_000,
|
||||
PLAYWRIGHT_NETWORK_READ_TIMEOUT_MS + WEB_RUNTIME_LIMITS.cleanupTimeoutMs,
|
||||
);
|
||||
|
||||
const OPERATION = "capture_browser_scenario" as const;
|
||||
|
||||
|
||||
@@ -2,6 +2,7 @@ import { afterEach, expect, it, vi } from "vitest";
|
||||
import type { Browser } from "playwright-core";
|
||||
|
||||
import { browserScenarioSchema } from "../domain/browserScenario.js";
|
||||
import { PLAYWRIGHT_SCENARIO_CLEANUP_TIMEOUT_MS } from "./PlaywrightExecutionBoundary.js";
|
||||
import {
|
||||
attachedScenarioLeaseKey,
|
||||
openPlaywrightScenarioBrowser,
|
||||
@@ -144,6 +145,35 @@ it("keeps attached-target ownership until cancelled cleanup actually settles", a
|
||||
expect(settled).toEqual([true]);
|
||||
});
|
||||
|
||||
it("waits for bounded event finalization and owned browser teardown", async () => {
|
||||
vi.useFakeTimers();
|
||||
try {
|
||||
const closeBrowser = vi.fn(
|
||||
() => new Promise<void>((resolve) => setTimeout(resolve, 1_500)),
|
||||
);
|
||||
const removeProfile = vi.fn(async () => undefined);
|
||||
const cleanup = new PlaywrightScenarioBrowserCleanupOwner({
|
||||
closeBrowser,
|
||||
removeProfile,
|
||||
});
|
||||
const finished = cleanup
|
||||
.close(() => new Promise<void>((resolve) => setTimeout(resolve, 4_500)))
|
||||
.then(
|
||||
() => ({ ok: true }),
|
||||
(cause: unknown) => ({ ok: false, cause }),
|
||||
);
|
||||
await vi.advanceTimersByTimeAsync(4_500);
|
||||
expect(removeProfile).not.toHaveBeenCalled();
|
||||
await vi.advanceTimersByTimeAsync(1_500);
|
||||
expect(await finished).toEqual({ ok: true });
|
||||
expect(cleanup.browserClosed).toBe(true);
|
||||
expect(closeBrowser).toHaveBeenCalledOnce();
|
||||
expect(removeProfile).toHaveBeenCalledOnce();
|
||||
} finally {
|
||||
vi.useRealTimers();
|
||||
}
|
||||
});
|
||||
|
||||
it("keeps attached-target ownership after the cleanup response timeout", async () => {
|
||||
vi.useFakeTimers();
|
||||
try {
|
||||
@@ -170,7 +200,9 @@ it("keeps attached-target ownership after the cleanup response timeout", async (
|
||||
responseSettled = true;
|
||||
})
|
||||
.catch(() => {});
|
||||
await vi.advanceTimersByTimeAsync(29_999);
|
||||
await vi.advanceTimersByTimeAsync(
|
||||
PLAYWRIGHT_SCENARIO_CLEANUP_TIMEOUT_MS - 1,
|
||||
);
|
||||
expect(responseSettled).toBe(false);
|
||||
await vi.advanceTimersByTimeAsync(1);
|
||||
await timeoutExpectation;
|
||||
|
||||
@@ -8,13 +8,12 @@ import type { BrowserScenario } from "../domain/browserScenario.js";
|
||||
import { AnalysisError } from "../domain/analysisErrorBase.js";
|
||||
import { isLiteralLoopbackHostname } from "../domain/browserObservation.js";
|
||||
import { BrowserObservationError } from "../domain/browserObservationError.js";
|
||||
import { withPlaywrightExecutionBoundary } from "./PlaywrightExecutionBoundary.js";
|
||||
import {
|
||||
PLAYWRIGHT_SCENARIO_CLEANUP_TIMEOUT_MS,
|
||||
withPlaywrightExecutionBoundary,
|
||||
} from "./PlaywrightExecutionBoundary.js";
|
||||
|
||||
const OPERATION = "capture_browser_scenario" as const;
|
||||
// Closing a real Chrome persistent context can take several seconds even when
|
||||
// it succeeds. The shorter operation deadline must not misreport cleanup.
|
||||
const CLEANUP_CONFIRMATION_TIMEOUT_MS = 30_000;
|
||||
|
||||
const throwIfScenarioCancelled = (signal: AbortSignal | undefined): void => {
|
||||
if (signal?.aborted === true)
|
||||
throw new BrowserObservationError(OPERATION, "cancelled");
|
||||
@@ -76,7 +75,7 @@ export class PlaywrightScenarioBrowserCleanupOwner {
|
||||
try {
|
||||
await withPlaywrightExecutionBoundary(
|
||||
() => cleanup,
|
||||
CLEANUP_CONFIRMATION_TIMEOUT_MS,
|
||||
PLAYWRIGHT_SCENARIO_CLEANUP_TIMEOUT_MS,
|
||||
signal,
|
||||
);
|
||||
} catch (cause: unknown) {
|
||||
|
||||
@@ -14,19 +14,9 @@ const mocks = vi.hoisted(() => ({
|
||||
finishEvents: vi.fn(),
|
||||
}));
|
||||
|
||||
vi.mock("./PlaywrightScenarioBrowser.js", () => ({
|
||||
vi.mock("./PlaywrightScenarioBrowser.js", async (importOriginal) => ({
|
||||
...(await importOriginal<typeof import("./PlaywrightScenarioBrowser.js")>()),
|
||||
openPlaywrightScenarioBrowser: mocks.openBrowser,
|
||||
failBrowserScenarioOperation: async (
|
||||
cleanup: () => Promise<void>,
|
||||
cause: unknown,
|
||||
) => {
|
||||
try {
|
||||
await cleanup();
|
||||
} catch (cleanupCause: unknown) {
|
||||
throw new AggregateError([cause, cleanupCause]);
|
||||
}
|
||||
throw cause;
|
||||
},
|
||||
}));
|
||||
|
||||
vi.mock("./PlaywrightScenarioStorage.js", () => ({
|
||||
@@ -63,6 +53,7 @@ vi.mock("./PlaywrightScenarioEvents.js", () => ({
|
||||
|
||||
import { browserScenarioSchema } from "../domain/browserScenario.js";
|
||||
import { PlaywrightScenarioSession } from "./PlaywrightScenarioSession.js";
|
||||
import { PlaywrightScenarioBrowserCleanupOwner } from "./PlaywrightScenarioBrowser.js";
|
||||
|
||||
const scenario = browserScenarioSchema.parse({
|
||||
browser: { mode: "launch", executable_path: process.execPath },
|
||||
@@ -106,25 +97,100 @@ const fixture = () => {
|
||||
return browserClosed;
|
||||
},
|
||||
};
|
||||
mocks.openBrowser.mockResolvedValue({
|
||||
const opened = {
|
||||
page,
|
||||
context,
|
||||
browser,
|
||||
cleanup,
|
||||
profilePath: "/tmp/profile",
|
||||
});
|
||||
};
|
||||
mocks.openBrowser.mockResolvedValue(opened);
|
||||
mocks.storage = {
|
||||
initialize: vi.fn(async () => undefined),
|
||||
settle: vi.fn(async () => undefined),
|
||||
close: vi.fn(async () => undefined),
|
||||
};
|
||||
return { cleanup, page, storage: mocks.storage };
|
||||
return { cleanup, page, context, storage: mocks.storage, opened };
|
||||
};
|
||||
|
||||
beforeEach(() => {
|
||||
vi.clearAllMocks();
|
||||
});
|
||||
|
||||
it("finishes initialization cleanup independently of request cancellation", async () => {
|
||||
const { context, opened } = fixture();
|
||||
const controller = new AbortController();
|
||||
const closeBrowser = vi.fn(async () => undefined);
|
||||
const removeProfile = vi.fn(async () => undefined);
|
||||
mocks.openBrowser.mockResolvedValue({
|
||||
...opened,
|
||||
cleanup: new PlaywrightScenarioBrowserCleanupOwner({
|
||||
closeBrowser,
|
||||
removeProfile,
|
||||
}),
|
||||
});
|
||||
context.addCookies.mockImplementationOnce(async () => {
|
||||
controller.abort();
|
||||
});
|
||||
const retainCleanup = vi.fn();
|
||||
|
||||
await expect(
|
||||
PlaywrightScenarioSession.open(
|
||||
scenario,
|
||||
{},
|
||||
{
|
||||
signal: controller.signal,
|
||||
retainCleanup,
|
||||
},
|
||||
),
|
||||
).rejects.toMatchObject({ _tag: "AnalysisCancelledError" });
|
||||
expect(closeBrowser).toHaveBeenCalledTimes(1);
|
||||
expect(removeProfile).toHaveBeenCalledTimes(1);
|
||||
expect(retainCleanup).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it("can retry cleanup of a browser that opened after request cancellation", async () => {
|
||||
const { opened } = fixture();
|
||||
const closeBrowser = vi
|
||||
.fn()
|
||||
.mockRejectedValueOnce(new Error("transport close failed"))
|
||||
.mockResolvedValueOnce(undefined);
|
||||
const removeProfile = vi.fn(async () => undefined);
|
||||
const lateOpened = {
|
||||
...opened,
|
||||
cleanup: new PlaywrightScenarioBrowserCleanupOwner({
|
||||
closeBrowser,
|
||||
removeProfile,
|
||||
}),
|
||||
};
|
||||
let resolveOpening: ((value: typeof lateOpened) => void) | undefined;
|
||||
const opening = new Promise<typeof lateOpened>((resolve) => {
|
||||
resolveOpening = resolve;
|
||||
});
|
||||
mocks.openBrowser.mockReturnValueOnce(opening);
|
||||
const controller = new AbortController();
|
||||
const retained: (() => Promise<unknown>)[] = [];
|
||||
const result = PlaywrightScenarioSession.open(
|
||||
scenario,
|
||||
{},
|
||||
{
|
||||
signal: controller.signal,
|
||||
retainCleanup: (close) => retained.push(close),
|
||||
},
|
||||
);
|
||||
const cancelled = expect(result).rejects.toMatchObject({
|
||||
_tag: "AnalysisCancelledError",
|
||||
});
|
||||
controller.abort();
|
||||
await cancelled;
|
||||
resolveOpening?.(lateOpened);
|
||||
await vi.waitFor(() => expect(closeBrowser).toHaveBeenCalledTimes(1));
|
||||
expect(retained).toHaveLength(1);
|
||||
await expect(retained[0]?.()).resolves.toBeUndefined();
|
||||
expect(closeBrowser).toHaveBeenCalledTimes(2);
|
||||
expect(removeProfile).toHaveBeenCalledTimes(1);
|
||||
});
|
||||
|
||||
it("uses browser disconnect as terminal storage release after detach failure", async () => {
|
||||
const { cleanup, storage } = fixture();
|
||||
const detachFailure = new Error("CDP detach rejected");
|
||||
|
||||
@@ -14,7 +14,10 @@ import { performPlaywrightScenarioAction } from "./PlaywrightScenarioActions.js"
|
||||
import { capturePlaywrightStepArtifacts } from "./PlaywrightScenarioArtifacts.js";
|
||||
import { PlaywrightScenarioEvents } from "./PlaywrightScenarioEvents.js";
|
||||
import { PlaywrightScenarioStorage } from "./PlaywrightScenarioStorage.js";
|
||||
import { withPlaywrightExecutionBoundary } from "./PlaywrightExecutionBoundary.js";
|
||||
import {
|
||||
PLAYWRIGHT_SCENARIO_CLEANUP_TIMEOUT_MS,
|
||||
withPlaywrightExecutionBoundary,
|
||||
} from "./PlaywrightExecutionBoundary.js";
|
||||
import {
|
||||
browserScenarioCaptureData,
|
||||
browserScenarioOperationFailure,
|
||||
@@ -148,13 +151,17 @@ export class PlaywrightScenarioSession implements BrowserScenarioSessionPort {
|
||||
options.signal,
|
||||
);
|
||||
} catch (cause: unknown) {
|
||||
// Resource release outlives the cancelled request, including retained retries.
|
||||
const lateCleanup = () =>
|
||||
opening.then(
|
||||
(lateOpened) => lateOpened.cleanup.close(undefined, options.signal),
|
||||
(lateOpened) => lateOpened.cleanup.close(),
|
||||
() => undefined,
|
||||
);
|
||||
options.retainCleanup?.(() =>
|
||||
withPlaywrightExecutionBoundary(lateCleanup, 1_000),
|
||||
withPlaywrightExecutionBoundary(
|
||||
lateCleanup,
|
||||
PLAYWRIGHT_SCENARIO_CLEANUP_TIMEOUT_MS,
|
||||
),
|
||||
);
|
||||
void lateCleanup().catch((cleanupCause: unknown) => {
|
||||
// best-effort cleanup: retainCleanup keeps the retry capability.
|
||||
@@ -280,7 +287,6 @@ export class PlaywrightScenarioSession implements BrowserScenarioSessionPort {
|
||||
events === undefined
|
||||
? undefined
|
||||
: () => events?.finish() ?? Promise.resolve(),
|
||||
options.signal,
|
||||
);
|
||||
} catch (failure: unknown) {
|
||||
browserFailure = { cause: failure };
|
||||
|
||||
@@ -743,8 +743,8 @@ const originalModuleEdges = (
|
||||
check();
|
||||
const dependency = originalDependency(node);
|
||||
if (dependency === null) return;
|
||||
const { kind, specifier } = dependency;
|
||||
if (kind === "require" && t.isCallExpression(node)) {
|
||||
const { kind, specifier, requireCallee } = dependency;
|
||||
if (requireCallee !== undefined) {
|
||||
unboundRequires ??= new Set(
|
||||
analyzeParsedJavaScriptReferences(parsed, "require")
|
||||
.filter(
|
||||
@@ -756,7 +756,7 @@ const originalModuleEdges = (
|
||||
`${String(location.start.line)}:${String(location.start.column)}`,
|
||||
),
|
||||
);
|
||||
const location = node.callee.loc?.start;
|
||||
const location = requireCallee.loc?.start;
|
||||
if (
|
||||
location === undefined ||
|
||||
!unboundRequires.has(
|
||||
@@ -1039,6 +1039,7 @@ const originalDependency = (
|
||||
): {
|
||||
readonly kind: ParsedSourceMapItem["original_module_edges"][number]["kind"];
|
||||
readonly specifier: string;
|
||||
readonly requireCallee?: t.Identifier;
|
||||
} | null => {
|
||||
if (
|
||||
t.isImportDeclaration(node) ||
|
||||
@@ -1051,11 +1052,15 @@ const originalDependency = (
|
||||
if (t.isImportExpression(node) && t.isStringLiteral(node.source))
|
||||
return { kind: "dynamic_import", specifier: node.source.value };
|
||||
if (
|
||||
t.isCallExpression(node) &&
|
||||
(t.isCallExpression(node) || t.isOptionalCallExpression(node)) &&
|
||||
t.isIdentifier(node.callee, { name: "require" }) &&
|
||||
t.isStringLiteral(node.arguments[0])
|
||||
)
|
||||
return { kind: "require", specifier: node.arguments[0].value };
|
||||
return {
|
||||
kind: "require",
|
||||
specifier: node.arguments[0].value,
|
||||
requireCallee: node.callee,
|
||||
};
|
||||
// `import x = require("m")` is only legal at module top level and always
|
||||
// refers to the host loader, so it needs no unbound-`require` check. The
|
||||
// `moduleReference` is an entity name for a local alias instead, which
|
||||
|
||||
@@ -4,6 +4,7 @@ import type {
|
||||
} from "../../domain/browserNetworkEvidence.js";
|
||||
import type { BrowserScenarioEvent } from "../../domain/browserScenarioCaptureValues.js";
|
||||
import type { BrowserScenarioSecrets } from "../BrowserScenarioSecrets.js";
|
||||
import { PLAYWRIGHT_NETWORK_READ_TIMEOUT_MS } from "../PlaywrightExecutionBoundary.js";
|
||||
import {
|
||||
captureNetworkBody,
|
||||
captureNetworkHeaders,
|
||||
@@ -76,7 +77,7 @@ export class PlaywrightScenarioNetwork {
|
||||
|
||||
constructor(private readonly options: NetworkCaptureOptions) {
|
||||
this.readOptions = {
|
||||
timeoutMs: options.readTimeoutMs ?? 5_000,
|
||||
timeoutMs: options.readTimeoutMs ?? PLAYWRIGHT_NETWORK_READ_TIMEOUT_MS,
|
||||
...(options.signal === undefined ? {} : { signal: options.signal }),
|
||||
};
|
||||
}
|
||||
|
||||
@@ -46,7 +46,9 @@ const registerWebMcp = (
|
||||
cli.command(CLI_COMMANDS.discoverWebMcpTools, {
|
||||
description: "Passively discover page-declared WebMCP tools",
|
||||
args: z.object({
|
||||
endpoint: z.string().describe("Configured loopback CDP HTTP endpoint"),
|
||||
endpoint: z
|
||||
.string()
|
||||
.describe("Loopback CDP HTTP endpoint or browser WebSocket URL"),
|
||||
targetId: z.string().describe("Target ID from list-browser-targets"),
|
||||
}),
|
||||
options: z.object({
|
||||
@@ -150,7 +152,9 @@ const registerScreenshot = (
|
||||
description:
|
||||
"Capture one visible page viewport within the supplied origin scope",
|
||||
args: z.object({
|
||||
endpoint: z.string().describe("Configured loopback CDP HTTP endpoint"),
|
||||
endpoint: z
|
||||
.string()
|
||||
.describe("Loopback CDP HTTP endpoint or browser WebSocket URL"),
|
||||
targetId: z.string().describe("Target ID from list-browser-targets"),
|
||||
}),
|
||||
options: z.object({
|
||||
|
||||
@@ -42,7 +42,9 @@ const registerTargetList = (
|
||||
description:
|
||||
"List page targets from a selected loopback CDP browser, optionally filtered by origin",
|
||||
args: z.object({
|
||||
endpoint: z.string().describe("Configured loopback CDP HTTP endpoint"),
|
||||
endpoint: z
|
||||
.string()
|
||||
.describe("Loopback CDP HTTP endpoint or browser WebSocket URL"),
|
||||
}),
|
||||
options: z.object({ ...browserScopeOptions }),
|
||||
run: ({ args, options }) =>
|
||||
@@ -75,7 +77,9 @@ const registerPageInspection = (
|
||||
description:
|
||||
"Passively inspect one page through CDP, defaulting to its current origin",
|
||||
args: z.object({
|
||||
endpoint: z.string().describe("Configured loopback CDP HTTP endpoint"),
|
||||
endpoint: z
|
||||
.string()
|
||||
.describe("Loopback CDP HTTP endpoint or browser WebSocket URL"),
|
||||
targetId: z.string().describe("Target ID from list-browser-targets"),
|
||||
}),
|
||||
options: browserPageInspectionOptions,
|
||||
@@ -118,7 +122,9 @@ const registerBundleAnalysis = (
|
||||
description:
|
||||
"Capture and statically analyze a page bundle, defaulting to the selected target origin",
|
||||
args: z.object({
|
||||
endpoint: z.string().describe("Configured loopback CDP HTTP endpoint"),
|
||||
endpoint: z
|
||||
.string()
|
||||
.describe("Loopback CDP HTTP endpoint or browser WebSocket URL"),
|
||||
targetId: z.string().describe("Target ID from list-browser-targets"),
|
||||
}),
|
||||
options: z.object({
|
||||
@@ -162,7 +168,9 @@ const registerObservationSession = (
|
||||
cli.command(CLI_COMMANDS.observeWebSession, {
|
||||
description: "Observe user-driven page navigation during a chosen window",
|
||||
args: z.object({
|
||||
endpoint: z.string().describe("Configured loopback CDP HTTP endpoint"),
|
||||
endpoint: z
|
||||
.string()
|
||||
.describe("Loopback CDP HTTP endpoint or browser WebSocket URL"),
|
||||
targetId: z.string().describe("Target ID from list-browser-targets"),
|
||||
}),
|
||||
options: z.object({
|
||||
|
||||
@@ -2,6 +2,7 @@ import { z } from "incur";
|
||||
|
||||
import type { DirectAnalysis } from "../composition/directAnalysis.js";
|
||||
import type { ReferenceSourcePolicy } from "../domain/referenceSourcePolicy.js";
|
||||
import { createHistoricalSourceSummary } from "../domain/referenceSourceSummary.js";
|
||||
import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";
|
||||
import { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js";
|
||||
import { importReferenceSource } from "../application/ReferenceSourceImport.js";
|
||||
@@ -241,11 +242,48 @@ const registerReferenceSourceCommand = (
|
||||
.string()
|
||||
.describe("Local source directory to import as historical reference"),
|
||||
}),
|
||||
run: ({ args }) =>
|
||||
options: z.object({
|
||||
detail: z
|
||||
.enum(["full", "summary"])
|
||||
.default("full")
|
||||
.describe(
|
||||
"Complete committed graph or compact historical-source summary",
|
||||
),
|
||||
outlineDepth: z
|
||||
.number()
|
||||
.int()
|
||||
.nonnegative()
|
||||
.safe()
|
||||
.optional()
|
||||
.describe(
|
||||
"Summary outline path depth (default: 2; 0 omits entries); requires --detail summary",
|
||||
),
|
||||
}),
|
||||
run: ({ args, options }) =>
|
||||
logCliCommand(
|
||||
logger,
|
||||
"import-reference-source",
|
||||
async () => {
|
||||
if (
|
||||
options.outlineDepth !== undefined &&
|
||||
options.detail !== "summary"
|
||||
)
|
||||
return {
|
||||
error: "Import failed",
|
||||
...projectAnalysisError(
|
||||
new AnalysisInputError(
|
||||
"import-reference-source",
|
||||
{ userMessage: "--outline-depth requires --detail summary" },
|
||||
[
|
||||
{
|
||||
path: ["outlineDepth"],
|
||||
reason: "invalid_value",
|
||||
message: "--outline-depth requires --detail summary",
|
||||
},
|
||||
],
|
||||
),
|
||||
),
|
||||
};
|
||||
const config = parseConfig(environment);
|
||||
if (!config.ok)
|
||||
return {
|
||||
@@ -255,6 +293,9 @@ const registerReferenceSourceCommand = (
|
||||
return runReferenceSourceImport(
|
||||
args.root,
|
||||
config.value.referenceSourcePolicy,
|
||||
options.detail === "summary"
|
||||
? (options.outlineDepth ?? 2)
|
||||
: undefined,
|
||||
);
|
||||
},
|
||||
isReferenceSourceImportCliFailure,
|
||||
@@ -265,6 +306,7 @@ const registerReferenceSourceCommand = (
|
||||
const runReferenceSourceImport = async (
|
||||
root: string,
|
||||
policy: ReferenceSourcePolicy,
|
||||
outlineDepth: number | undefined,
|
||||
): Promise<unknown> => {
|
||||
const resources = new ArtifactResourceScope();
|
||||
let outcome:
|
||||
@@ -346,7 +388,9 @@ const runReferenceSourceImport = async (
|
||||
cause: closeOutcome.cause,
|
||||
}),
|
||||
};
|
||||
return imported.value;
|
||||
return outlineDepth === undefined
|
||||
? imported.value
|
||||
: createHistoricalSourceSummary(imported.value, outlineDepth);
|
||||
};
|
||||
|
||||
const mergeReferenceSourceCleanup = (
|
||||
|
||||
+13
-4
@@ -65,12 +65,19 @@ const accessDeniedSystemCode = (
|
||||
: undefined;
|
||||
};
|
||||
|
||||
/**
|
||||
* A `file:` URL or `scheme://` URL is not an operator-relative filesystem path.
|
||||
* One-letter prefixes stay paths so Windows drive paths resolve normally.
|
||||
*/
|
||||
const URL_REFERENCE = /^(?:file:|[A-Za-z][A-Za-z0-9+.-]+:\/\/)/iu;
|
||||
|
||||
/**
|
||||
* Resolve named string fields of CLI-supplied JSON against the operator
|
||||
* working directory. Each entry is a key path from the document root; only
|
||||
* fields holding nonblank strings are resolved, everything else passes through
|
||||
* untouched so shared schemas can reject blank paths. Shared MCP contracts reject
|
||||
* relative paths, so CLI workflows resolve operator-relative values before validation.
|
||||
* fields holding nonblank, non-URL strings are resolved, everything else passes
|
||||
* through untouched so shared schemas can reject blank paths and URLs. Shared MCP
|
||||
* contracts reject relative paths, so CLI workflows resolve operator-relative
|
||||
* values before validation.
|
||||
*/
|
||||
export const resolveCliJsonPaths = (
|
||||
value: unknown,
|
||||
@@ -94,7 +101,9 @@ const resolveJsonPath = (
|
||||
if (tail.length === 0)
|
||||
return [
|
||||
key,
|
||||
typeof entry === "string" && entry.trim().length > 0
|
||||
typeof entry === "string" &&
|
||||
entry.trim().length > 0 &&
|
||||
!URL_REFERENCE.test(entry)
|
||||
? resolve(entry)
|
||||
: entry,
|
||||
];
|
||||
|
||||
@@ -56,4 +56,38 @@ describe("CLI JSON path normalization", () => {
|
||||
});
|
||||
expect(input.browser.executable_path).toBe(" browser ");
|
||||
});
|
||||
|
||||
it.each([
|
||||
"file:///opt/electron",
|
||||
"FILE:electron",
|
||||
"https://example.test/app",
|
||||
])("keeps URL %j distinguishable from a local path", (value) => {
|
||||
const input = {
|
||||
executable_path: value,
|
||||
application_path: resolve("/synthetic/app"),
|
||||
};
|
||||
const normalized = resolveCliJsonPaths(input, paths);
|
||||
expect(normalized).toEqual(input);
|
||||
const parsed = electronActiveObservationInputSchema.safeParse(normalized);
|
||||
expect(parsed.success).toBe(false);
|
||||
if (parsed.success) throw new Error("Expected URL path rejection");
|
||||
expect(parsed.error.issues).toEqual([
|
||||
expect.objectContaining({
|
||||
path: ["executable_path"],
|
||||
message: expect.stringContaining(
|
||||
"must be absolute local filesystem paths",
|
||||
),
|
||||
}),
|
||||
]);
|
||||
});
|
||||
|
||||
it.each([
|
||||
"bin/electron",
|
||||
"release:v1/electron",
|
||||
"C:\\Electron\\electron.exe",
|
||||
])("keeps resolving local path %j", (value) => {
|
||||
expect(resolveCliJsonPaths({ executable_path: value }, paths)).toEqual({
|
||||
executable_path: resolve(value),
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
@@ -79,7 +79,7 @@ const artifact = <
|
||||
export const ARTIFACT_TOOL_CONTRACTS = [
|
||||
artifact(
|
||||
"inspect_artifact",
|
||||
"Inspect an active archive or application package in one call. By default returns the complete content-addressed artifact graph once, as the typed nested inventory Evidence, with root and integrity observations, integrity contradictions, hypotheses, unexplored branches, limitations, and next probes inline. Optional detail summary retains the complete inspection and returns its derived summary view; read exact paths or inventory pages with inspect_analysis_view using parent_evidence_id. This changes delivery, not inventory coverage. Read-only DMG mounting is used automatically on supported macOS hosts. Integrity mismatches fail by default; record-and-continue keeps mismatches explicitly untrusted. It does not extract files; use extract_artifact to materialize its regular contents.",
|
||||
"Inspect an active archive or application package in one call. By default returns the complete content-addressed artifact graph once, as the typed nested inventory Evidence, with root and integrity observations, integrity contradictions, hypotheses, unexplored branches, limitations, and next probes inline. Optional detail summary retains the complete inspection and returns its derived summary view; read exact paths or inventory pages with inspect_analysis_view using parent_evidence_id. This changes delivery, not inventory coverage. Classic iNES includes header facts, PRG/CHR file-region hashes and byte-exact reconstruction evidence; mapper execution and CPU bank mappings remain unobserved. Read-only DMG mounting is used automatically on supported macOS hosts. Integrity mismatches fail by default; record-and-continue keeps mismatches explicitly untrusted. It does not extract files; use extract_artifact to materialize its regular contents.",
|
||||
artifactInspectionInputSchema,
|
||||
),
|
||||
artifact(
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
import { z } from "zod";
|
||||
import { evidenceSchema } from "../../domain/evidence.js";
|
||||
import { managedNativeVerificationInputSchema } from "../../domain/managed/managedNativeVerificationSchemas.js";
|
||||
|
||||
import { managedReconstructionImportInputSchema } from "../../domain/managed/managedReconstruction.js";
|
||||
import type { ToolContract } from "../toolContractTypes.js";
|
||||
@@ -34,35 +35,6 @@ export const managedReconstructionReferenceInputSchema =
|
||||
static_members: evidenceSchema,
|
||||
});
|
||||
|
||||
/** Inline Evidence inputs for managed/native verification. */
|
||||
export const managedNativeVerificationReferenceInputSchema = z
|
||||
.strictObject({
|
||||
managed_boundaries: evidenceSchema,
|
||||
native_observations: z
|
||||
.array(evidenceSchema)
|
||||
.min(1)
|
||||
.describe("Native function or export Evidence records"),
|
||||
})
|
||||
.superRefine((input, context) => {
|
||||
const ids = new Set<string>([input.managed_boundaries.evidence_id]);
|
||||
for (const [index, evidence] of input.native_observations.entries()) {
|
||||
if (evidence.evidence_id === input.managed_boundaries.evidence_id)
|
||||
context.addIssue({
|
||||
code: "custom",
|
||||
path: ["native_observations", index],
|
||||
message:
|
||||
"Native observation Evidence must be distinct from managed boundary Evidence",
|
||||
});
|
||||
if (ids.has(evidence.evidence_id))
|
||||
context.addIssue({
|
||||
code: "custom",
|
||||
path: ["native_observations", index],
|
||||
message: "Native observation Evidence IDs must be unique",
|
||||
});
|
||||
ids.add(evidence.evidence_id);
|
||||
}
|
||||
});
|
||||
|
||||
const managedApplicationGraphReferenceFacts = {} as const;
|
||||
|
||||
const managedApplicationGraphReferenceShape = z.strictObject({
|
||||
@@ -146,7 +118,7 @@ export const MANAGED_WORKFLOW_TOOL_CONTRACTS = [
|
||||
description:
|
||||
"Verify managed P/Invoke/native-boundary declarations against authenticated native export or function Evidence without executing managed code or translating managed metadata tokens into native addresses. The workflow preserves declaration-only, verified, inferred, contradicted, and unresolved states.",
|
||||
kind: "application",
|
||||
inputSchema: managedNativeVerificationReferenceInputSchema,
|
||||
inputSchema: managedNativeVerificationInputSchema,
|
||||
outputSchema: nativeVerificationOutputSchema,
|
||||
examples: [
|
||||
{
|
||||
|
||||
@@ -13,6 +13,7 @@ const EXECUTION_WORDING =
|
||||
/\b(?:run|runs|running|launch|launches|launching|execute|executes|executing|execution|start|starts|install|installs|uninstall|uninstalls)\b/iu;
|
||||
|
||||
const EXECUTION_WORDING_EXCEPTIONS: Readonly<Record<string, string>> = {
|
||||
inspect_artifact: "states that mapper execution remains unobserved",
|
||||
start_frida_session:
|
||||
"spawned targets remain suspended until resume_frida_session",
|
||||
inspect_native_load_image: "states that it does not execute the target",
|
||||
|
||||
@@ -62,6 +62,7 @@ export const targetFormatSchema = z.enum([
|
||||
"raw-binary",
|
||||
...ZIP_PACKAGE_FORMATS,
|
||||
"asar",
|
||||
"ines",
|
||||
"dmg",
|
||||
"pkg",
|
||||
"plist",
|
||||
|
||||
@@ -1,5 +1,9 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
|
||||
import { managedNativeVerificationInputSchema } from "../domain/managed/managedNativeVerificationSchemas.js";
|
||||
import { toolContract } from "./toolContracts.js";
|
||||
import { toolInputSchemaWithMetadata } from "./toolSchemaMetadata.js";
|
||||
|
||||
import { traceJavaScriptSemanticsRequestSchema } from "./javascript/applicationWorkflowInputContracts.js";
|
||||
import { JAVASCRIPT_FEATURE_TRACE_EXAMPLE } from "./javascript/javascriptApplicationWorkflowExamples.js";
|
||||
import {
|
||||
@@ -10,7 +14,6 @@ import {
|
||||
import {
|
||||
compareManagedMembersReferenceInputSchema,
|
||||
managedApplicationGraphReferenceInputSchema,
|
||||
managedNativeVerificationReferenceInputSchema,
|
||||
} from "./managed/managedWorkflowToolContracts.js";
|
||||
|
||||
describe("workflow input contracts", () => {
|
||||
@@ -41,17 +44,6 @@ describe("workflow input contracts", () => {
|
||||
}).success,
|
||||
).toBe(false);
|
||||
|
||||
expect(
|
||||
managedNativeVerificationReferenceInputSchema.safeParse({
|
||||
managed_boundaries:
|
||||
MANAGED_NATIVE_VERIFICATION_EXAMPLE.managed_boundaries,
|
||||
native_observations: [
|
||||
MANAGED_NATIVE_VERIFICATION_EXAMPLE.native_observations[0],
|
||||
MANAGED_NATIVE_VERIFICATION_EXAMPLE.native_observations[0],
|
||||
],
|
||||
}).success,
|
||||
).toBe(false);
|
||||
|
||||
expect(
|
||||
managedApplicationGraphReferenceInputSchema.safeParse({
|
||||
managed_artifact: MANAGED_APPLICATION_GRAPH_EXAMPLE.managed_members,
|
||||
@@ -62,4 +54,80 @@ describe("workflow input contracts", () => {
|
||||
managedApplicationGraphReferenceInputSchema.safeParse({}).success,
|
||||
).toBe(false);
|
||||
});
|
||||
|
||||
it.each([
|
||||
{
|
||||
name: "one observation reusing the boundary",
|
||||
observations: [MANAGED_NATIVE_VERIFICATION_EXAMPLE.managed_boundaries],
|
||||
issues: [
|
||||
{
|
||||
path: ["native_observations", 0],
|
||||
message:
|
||||
"Native observation Evidence must be distinct from managed boundary Evidence",
|
||||
},
|
||||
],
|
||||
},
|
||||
{
|
||||
name: "repeated native observations",
|
||||
observations: [
|
||||
MANAGED_NATIVE_VERIFICATION_EXAMPLE.native_observations[0],
|
||||
MANAGED_NATIVE_VERIFICATION_EXAMPLE.native_observations[0],
|
||||
],
|
||||
issues: [
|
||||
{
|
||||
path: ["native_observations", 1],
|
||||
message: "Native observation Evidence IDs must be unique",
|
||||
},
|
||||
],
|
||||
},
|
||||
{
|
||||
name: "repeated observations reusing the boundary",
|
||||
observations: [
|
||||
MANAGED_NATIVE_VERIFICATION_EXAMPLE.managed_boundaries,
|
||||
MANAGED_NATIVE_VERIFICATION_EXAMPLE.managed_boundaries,
|
||||
],
|
||||
issues: [
|
||||
{
|
||||
path: ["native_observations", 0],
|
||||
message:
|
||||
"Native observation Evidence must be distinct from managed boundary Evidence",
|
||||
},
|
||||
{
|
||||
path: ["native_observations", 1],
|
||||
message:
|
||||
"Native observation Evidence must be distinct from managed boundary Evidence",
|
||||
},
|
||||
{
|
||||
path: ["native_observations", 1],
|
||||
message: "Native observation Evidence IDs must be unique",
|
||||
},
|
||||
],
|
||||
},
|
||||
{
|
||||
name: "distinct native observations",
|
||||
observations: MANAGED_NATIVE_VERIFICATION_EXAMPLE.native_observations,
|
||||
issues: [],
|
||||
},
|
||||
])(
|
||||
"preserves managed/native diagnostics for $name",
|
||||
async ({ observations, issues }) => {
|
||||
const input = {
|
||||
managed_boundaries:
|
||||
MANAGED_NATIVE_VERIFICATION_EXAMPLE.managed_boundaries,
|
||||
native_observations: observations,
|
||||
};
|
||||
const contract = toolContract("verify_managed_native_boundaries");
|
||||
for (const schema of [
|
||||
managedNativeVerificationInputSchema,
|
||||
contract.inputSchema,
|
||||
toolInputSchemaWithMetadata(contract),
|
||||
]) {
|
||||
const result = await schema["~standard"].validate(input);
|
||||
expect(
|
||||
result.issues?.map(({ path, message }) => ({ path, message })) ?? [],
|
||||
).toEqual(issues);
|
||||
if (issues.length === 0) expect(result).toEqual({ value: input });
|
||||
}
|
||||
},
|
||||
);
|
||||
});
|
||||
|
||||
@@ -69,6 +69,7 @@ const formatSchema = z.enum([
|
||||
"hsp",
|
||||
"app-pack",
|
||||
"asar",
|
||||
"ines",
|
||||
"dmg",
|
||||
"pkg",
|
||||
"plist",
|
||||
|
||||
@@ -102,7 +102,7 @@ const textCoverage = z.strictObject({
|
||||
export const dexDescriptorSchema = z
|
||||
.string()
|
||||
.regex(
|
||||
/^\((?:\[*(?:[ZBSCIJFD]|L[^;()]+;))*\)(?:V|\[*(?:[ZBSCIJFD]|L[^;()]+;))$/u,
|
||||
/^\((?:\[*(?:[ZBSCIJFD]|L[^;\x28\x29]+;))*\)(?:V|\[*(?:[ZBSCIJFD]|L[^;\x28\x29]+;))$/u,
|
||||
);
|
||||
|
||||
const method = z.strictObject({
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
import { z } from "zod";
|
||||
import { prefixedDigestSchema } from "./../domain/digests.js";
|
||||
import { inesInventorySchema } from "./inesContainer.js";
|
||||
|
||||
const sha256Schema = z.string().regex(/^[a-f0-9]{64}$/u);
|
||||
const artifactIdSchema = prefixedDigestSchema("art");
|
||||
@@ -42,6 +43,7 @@ const artifactFormatSchema = z.enum([
|
||||
"zip",
|
||||
"pkg",
|
||||
"asar",
|
||||
"ines",
|
||||
"javascript-bundle",
|
||||
"source-map",
|
||||
"mach-o-universal",
|
||||
@@ -69,6 +71,7 @@ const artifactFormatSchema = z.enum([
|
||||
|
||||
/** Formats established from bytes or a virtual directory tree, independent of path roles. */
|
||||
const artifactContentFormatSchema = artifactFormatSchema.extract([
|
||||
"ines",
|
||||
"zip",
|
||||
"mach-o-universal",
|
||||
"mach-o",
|
||||
@@ -202,6 +205,7 @@ export const artifactInventoryResultSchema = z.object({
|
||||
edges: z.array(artifactEdgeSchema),
|
||||
provenance: z.array(artifactCommandSchema),
|
||||
integrity_contradictions: z.array(integrityContradictionSchema).default([]),
|
||||
ines: inesInventorySchema.optional(),
|
||||
limitations: z.array(z.string()),
|
||||
/** Optional only for persisted inventory Evidence written before this field. */
|
||||
coverage_status: artifactInventoryCoverageSchema.optional(),
|
||||
@@ -211,6 +215,8 @@ export const artifactInventoryResultSchema = z.object({
|
||||
export const artifactInventoryOutputSchema =
|
||||
artifactInventoryResultSchema.extend({
|
||||
coverage_status: artifactInventoryCoverageSchema,
|
||||
// JSON output may omit container facts, but cannot carry an undefined member.
|
||||
ines: inesInventorySchema.exactOptional(),
|
||||
});
|
||||
export type ArtifactInventoryOutput = z.infer<
|
||||
typeof artifactInventoryOutputSchema
|
||||
|
||||
@@ -17,7 +17,12 @@ const artifactIdSchema = prefixedDigestSchema("art");
|
||||
|
||||
const inspectionObservationSchema = z.strictObject({
|
||||
observation_id: prefixedDigestSchema("aio"),
|
||||
kind: z.enum(["root-manifest", "integrity"]),
|
||||
kind: z.enum([
|
||||
"root-manifest",
|
||||
"integrity",
|
||||
"container-header",
|
||||
"reconstruction",
|
||||
]),
|
||||
subject: textSchema,
|
||||
value: jsonValueSchema,
|
||||
evidence_id: evidenceIdSchema,
|
||||
@@ -228,6 +233,22 @@ const allObservations = (
|
||||
...inventory.integrity_contradictions.map((value) =>
|
||||
observation("integrity", value.contradiction_id, value, evidenceId),
|
||||
),
|
||||
...(inventory.ines === undefined
|
||||
? []
|
||||
: [
|
||||
observation(
|
||||
"container-header",
|
||||
inventory.manifest.root_artifact_id,
|
||||
inventory.ines.header,
|
||||
evidenceId,
|
||||
),
|
||||
observation(
|
||||
"reconstruction",
|
||||
inventory.manifest.root_artifact_id,
|
||||
inventory.ines.reconstruction,
|
||||
evidenceId,
|
||||
),
|
||||
]),
|
||||
];
|
||||
|
||||
const observation = (
|
||||
|
||||
@@ -0,0 +1,74 @@
|
||||
import { expect, it } from "vitest";
|
||||
import {
|
||||
artifactInventoryOutputSchema,
|
||||
artifactInventoryResultSchema,
|
||||
} from "./artifactGraph.js";
|
||||
import { jsonValueSchema } from "./jsonValue.js";
|
||||
|
||||
const digest = "a".repeat(64);
|
||||
const inventory = {
|
||||
manifest: {
|
||||
manifest_id: `agm_${digest}`,
|
||||
root_artifact_id: `art_${digest}`,
|
||||
root_sha256: digest,
|
||||
root_format: "zip",
|
||||
graph_sha256: digest,
|
||||
node_count: 1,
|
||||
occurrence_count: 1,
|
||||
edge_count: 0,
|
||||
},
|
||||
nodes: [
|
||||
{
|
||||
artifact_id: `art_${digest}`,
|
||||
format: "zip",
|
||||
sha256: digest,
|
||||
size: 22,
|
||||
media_type: null,
|
||||
architecture: null,
|
||||
content_state: "materialized",
|
||||
limitations: [],
|
||||
},
|
||||
],
|
||||
occurrences: [
|
||||
{
|
||||
occurrence_id: `occ_${digest}`,
|
||||
artifact_id: `art_${digest}`,
|
||||
parent_occurrence_id: null,
|
||||
logical_path: ".",
|
||||
entry_kind: "file",
|
||||
artifact_kind: "container",
|
||||
artifact_format: "zip",
|
||||
declared_size: 22,
|
||||
compressed_size: null,
|
||||
executable: false,
|
||||
encrypted: false,
|
||||
hash_status: "verified",
|
||||
source_location: null,
|
||||
limitations: [],
|
||||
},
|
||||
],
|
||||
edges: [],
|
||||
provenance: [],
|
||||
integrity_contradictions: [],
|
||||
limitations: [],
|
||||
coverage_status: "complete",
|
||||
};
|
||||
|
||||
it("keeps absent container facts absent in JSON-safe inventory output", () => {
|
||||
const output = artifactInventoryOutputSchema.parse(inventory);
|
||||
expect(Object.hasOwn(output, "ines")).toBe(false);
|
||||
expect(jsonValueSchema.safeParse(output).success).toBe(true);
|
||||
expect(
|
||||
artifactInventoryOutputSchema.safeParse({ ...inventory, ines: undefined })
|
||||
.success,
|
||||
).toBe(false);
|
||||
});
|
||||
|
||||
it("keeps historical coverage omission separate from current output requirements", () => {
|
||||
const { coverage_status: _coverage, ...historical } = inventory;
|
||||
const imported = artifactInventoryResultSchema.parse(historical);
|
||||
expect(Object.hasOwn(imported, "coverage_status")).toBe(false);
|
||||
expect(artifactInventoryOutputSchema.safeParse(historical).success).toBe(
|
||||
false,
|
||||
);
|
||||
});
|
||||
@@ -16,5 +16,6 @@ export interface ArtifactInventorySnapshot {
|
||||
ArtifactInventoryResult["provenance"][number]
|
||||
>;
|
||||
readonly integrity_contradictions: readonly IntegrityContradiction[];
|
||||
readonly ines?: ArtifactInventoryResult["ines"];
|
||||
readonly limitations: readonly string[];
|
||||
}
|
||||
|
||||
@@ -179,7 +179,7 @@ export type BinaryTarget =
|
||||
| (BinaryTargetIdentity &
|
||||
NonExecutableMetadata & {
|
||||
readonly kind: "archive";
|
||||
readonly format: ZipPackageFormat | "asar" | "dmg" | "pkg";
|
||||
readonly format: ZipPackageFormat | "asar" | "ines" | "dmg" | "pkg";
|
||||
})
|
||||
| (BinaryTargetIdentity &
|
||||
NonExecutableMetadata & {
|
||||
|
||||
@@ -2,7 +2,9 @@ import { describe, expect, it } from "vitest";
|
||||
|
||||
import {
|
||||
browserEndpointSchema,
|
||||
browserObservationEndpointSchema,
|
||||
browserOriginSchema,
|
||||
recordedBrowserObservationEndpointSchema,
|
||||
sanitizeEndpointCandidate,
|
||||
sanitizeBrowserUrl,
|
||||
} from "./browserObservation.js";
|
||||
@@ -45,6 +47,58 @@ describe("browser observation contracts", () => {
|
||||
])
|
||||
expect(browserEndpointSchema.safeParse(value).success, value).toBe(false);
|
||||
});
|
||||
|
||||
it("accepts a loopback browser socket and records it without its identifier", () => {
|
||||
expect(
|
||||
browserObservationEndpointSchema.parse("http://127.0.0.1:9222/"),
|
||||
).toEqual({
|
||||
transport: "http_discovery",
|
||||
url: "http://127.0.0.1:9222",
|
||||
recorded: "http://127.0.0.1:9222",
|
||||
});
|
||||
expect(
|
||||
browserObservationEndpointSchema.parse(
|
||||
"ws://[::1]:9222/devtools/browser/0b1c-socket-id",
|
||||
),
|
||||
).toEqual({
|
||||
transport: "browser_websocket",
|
||||
url: "ws://[::1]:9222/devtools/browser/0b1c-socket-id",
|
||||
recorded: "ws://[::1]:9222/devtools/browser/[REDACTED]",
|
||||
});
|
||||
for (const value of [
|
||||
"ws://127.0.0.1/devtools/browser/id",
|
||||
"ws://localhost:9222/devtools/browser/id",
|
||||
"wss://127.0.0.1:9222/devtools/browser/id",
|
||||
"ws://user:pass@127.0.0.1:9222/devtools/browser/id",
|
||||
"ws://127.0.0.1:9222/devtools/browser/id?token=x",
|
||||
"ws://127.0.0.1:9222/devtools/browser/id#fragment",
|
||||
"ws://127.0.0.1:9222/devtools/browser/id?",
|
||||
"ws://127.0.0.1:9222/devtools/browser/id#",
|
||||
"ws://127.0.0.1:9222/devtools/browser/",
|
||||
"ws://127.0.0.1:9222/devtools/browser/id/extra",
|
||||
"ws://127.0.0.1:9222/devtools/page/id",
|
||||
])
|
||||
expect(
|
||||
browserObservationEndpointSchema.safeParse(value).success,
|
||||
value,
|
||||
).toBe(false);
|
||||
});
|
||||
|
||||
it("accepts recorded browser sockets only in their redacted form", () => {
|
||||
for (const value of [
|
||||
"http://127.0.0.1:9222",
|
||||
"ws://127.0.0.1:9222/devtools/browser/[REDACTED]",
|
||||
])
|
||||
expect(
|
||||
recordedBrowserObservationEndpointSchema.safeParse(value).success,
|
||||
value,
|
||||
).toBe(true);
|
||||
expect(
|
||||
recordedBrowserObservationEndpointSchema.safeParse(
|
||||
"ws://127.0.0.1:9222/devtools/browser/0b1c-socket-id",
|
||||
).success,
|
||||
).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
describe("browser observation sensitive surfaces and retention", () => {
|
||||
|
||||
@@ -43,46 +43,125 @@ export const browserOriginSchema = z
|
||||
export const isLiteralLoopbackHostname = (hostname: string): boolean =>
|
||||
hostname === "127.0.0.1" || hostname === "[::1]" || hostname === "::1";
|
||||
|
||||
const HTTP_ENDPOINT_MESSAGE =
|
||||
"CDP endpoint must be an explicit-port HTTP URL on 127.0.0.1 or ::1";
|
||||
const BROWSER_SOCKET_PATH = "/devtools/browser/";
|
||||
const REDACTED_BROWSER_SOCKET_PATH = `${BROWSER_SOCKET_PATH}[REDACTED]`;
|
||||
|
||||
/** Normalized origin of an accepted loopback CDP HTTP discovery endpoint. */
|
||||
const httpDiscoveryOrigin = (url: URL): string | undefined =>
|
||||
url.protocol === "http:" &&
|
||||
isLiteralLoopbackHostname(url.hostname) &&
|
||||
url.port !== "" &&
|
||||
url.username === "" &&
|
||||
url.password === "" &&
|
||||
url.pathname === "/" &&
|
||||
!urlDeclaresQueryOrFragment(url)
|
||||
? url.origin
|
||||
: undefined;
|
||||
|
||||
/** Scheme and authority of an accepted loopback CDP browser WebSocket. */
|
||||
const browserSocketAuthority = (url: URL): string | undefined => {
|
||||
const id = url.pathname.slice(BROWSER_SOCKET_PATH.length);
|
||||
return url.protocol === "ws:" &&
|
||||
isLiteralLoopbackHostname(url.hostname) &&
|
||||
url.port !== "" &&
|
||||
url.username === "" &&
|
||||
url.password === "" &&
|
||||
!urlDeclaresQueryOrFragment(url) &&
|
||||
url.pathname.startsWith(BROWSER_SOCKET_PATH) &&
|
||||
id.length > 0 &&
|
||||
!id.includes("/")
|
||||
? `${url.protocol}//${url.host}`
|
||||
: undefined;
|
||||
};
|
||||
|
||||
/** Loopback-only HTTP endpoint accepted for a user-owned CDP browser. */
|
||||
export const browserEndpointSchema = z
|
||||
.string()
|
||||
.min(1)
|
||||
.transform((value, context) => {
|
||||
let url: URL;
|
||||
try {
|
||||
url = new URL(value);
|
||||
} catch (cause: unknown) {
|
||||
// Invalid input is reported through the zod issue.
|
||||
void cause;
|
||||
const url = URL.parse(value);
|
||||
const origin = url === null ? undefined : httpDiscoveryOrigin(url);
|
||||
if (origin !== undefined) return origin;
|
||||
context.addIssue({
|
||||
code: "custom",
|
||||
message:
|
||||
url === null ? "Invalid CDP endpoint URL" : HTTP_ENDPOINT_MESSAGE,
|
||||
});
|
||||
return z.NEVER;
|
||||
});
|
||||
|
||||
/**
|
||||
* Caller-selected endpoint for passive browser observation. A browser socket
|
||||
* skips HTTP discovery; its identifier gates access, so `recorded` omits it.
|
||||
*/
|
||||
export interface BrowserObservationEndpoint {
|
||||
readonly transport: "http_discovery" | "browser_websocket";
|
||||
readonly url: string;
|
||||
readonly recorded: string;
|
||||
}
|
||||
|
||||
/** Loopback CDP HTTP discovery origin or browser WebSocket URL. */
|
||||
export const browserObservationEndpointSchema = z
|
||||
.string()
|
||||
.min(1)
|
||||
.describe(
|
||||
"Literal loopback CDP endpoint: http://127.0.0.1:PORT, or ws://127.0.0.1:PORT/devtools/browser/ID.",
|
||||
)
|
||||
.transform((value, context): BrowserObservationEndpoint => {
|
||||
const url = URL.parse(value);
|
||||
if (url === null) {
|
||||
context.addIssue({ code: "custom", message: "Invalid CDP endpoint URL" });
|
||||
return z.NEVER;
|
||||
}
|
||||
if (
|
||||
url.protocol !== "http:" ||
|
||||
!isLiteralLoopbackHostname(url.hostname) ||
|
||||
url.port === "" ||
|
||||
url.username !== "" ||
|
||||
url.password !== "" ||
|
||||
url.pathname !== "/" ||
|
||||
urlDeclaresQueryOrFragment(url)
|
||||
) {
|
||||
context.addIssue({
|
||||
code: "custom",
|
||||
message:
|
||||
"CDP endpoint must be an explicit-port HTTP URL on 127.0.0.1 or ::1",
|
||||
});
|
||||
return z.NEVER;
|
||||
}
|
||||
return url.origin;
|
||||
const origin = httpDiscoveryOrigin(url);
|
||||
if (origin !== undefined)
|
||||
return { transport: "http_discovery", url: origin, recorded: origin };
|
||||
const authority = browserSocketAuthority(url);
|
||||
if (authority !== undefined)
|
||||
return {
|
||||
transport: "browser_websocket",
|
||||
url: url.href,
|
||||
recorded: `${authority}${REDACTED_BROWSER_SOCKET_PATH}`,
|
||||
};
|
||||
context.addIssue({
|
||||
code: "custom",
|
||||
message:
|
||||
url.protocol === "ws:"
|
||||
? "CDP browser WebSocket must be ws://127.0.0.1:PORT/devtools/browser/ID or ws://[::1]:PORT/devtools/browser/ID"
|
||||
: HTTP_ENDPOINT_MESSAGE,
|
||||
});
|
||||
return z.NEVER;
|
||||
});
|
||||
|
||||
/** Evidence form of a passive browser endpoint, with any socket identifier redacted. */
|
||||
export const recordedBrowserObservationEndpointSchema = z
|
||||
.string()
|
||||
.min(1)
|
||||
.refine(
|
||||
(value) => {
|
||||
const url = URL.parse(value);
|
||||
return (
|
||||
url !== null &&
|
||||
(httpDiscoveryOrigin(url) !== undefined ||
|
||||
(browserSocketAuthority(url) !== undefined &&
|
||||
url.pathname === REDACTED_BROWSER_SOCKET_PATH))
|
||||
);
|
||||
},
|
||||
{
|
||||
message:
|
||||
"Recorded CDP endpoint must be a loopback HTTP origin or a redacted browser WebSocket URL",
|
||||
},
|
||||
);
|
||||
|
||||
export const browserAllowedOriginsSchema = z
|
||||
.array(browserOriginSchema)
|
||||
.transform((origins) => Array.from(new Set(origins)).sort())
|
||||
.default([]);
|
||||
|
||||
const browserInput = {
|
||||
cdp_endpoint: browserEndpointSchema,
|
||||
cdp_endpoint: browserObservationEndpointSchema,
|
||||
allowed_origins: browserAllowedOriginsSchema,
|
||||
};
|
||||
|
||||
|
||||
@@ -2,14 +2,14 @@ import { z } from "zod";
|
||||
|
||||
import {
|
||||
browserAllowedOriginsSchema,
|
||||
browserEndpointSchema,
|
||||
browserObservationEndpointSchema,
|
||||
} from "./browserObservation.js";
|
||||
import { browserCompletenessSchema } from "./browserCompleteness.js";
|
||||
import { browserVersionSchema } from "./browserObservationSchemas.js";
|
||||
|
||||
/** Input for a navigation-aware browser observation window. */
|
||||
export const observeWebSessionInputSchema = z.strictObject({
|
||||
cdp_endpoint: browserEndpointSchema,
|
||||
cdp_endpoint: browserObservationEndpointSchema,
|
||||
allowed_origins: browserAllowedOriginsSchema,
|
||||
target_id: z.string().trim().min(1),
|
||||
observation_ms: z.number().int().min(1).default(10_000),
|
||||
|
||||
+21
-12
@@ -19,7 +19,7 @@ const TARGET: BinaryTarget = {
|
||||
const PROVIDER = { id: "fixture", name: "Fixture provider", version: "1" };
|
||||
const PROFILE = createAnalysisProfile(PROVIDER, { loader: "default" });
|
||||
|
||||
it("rejects a detected Evidence subject with the raw-only 6502 architecture", () => {
|
||||
it("keeps 6502 confined to explicit raw Evidence subjects alongside iNES", () => {
|
||||
const selected = {
|
||||
path: TARGET.path,
|
||||
sha256: TARGET.sha256,
|
||||
@@ -33,17 +33,26 @@ it("rejects a detected Evidence subject with the raw-only 6502 architecture", ()
|
||||
result: null,
|
||||
}).subject,
|
||||
).toMatchObject({ format: "raw-binary", architecture: "6502" });
|
||||
const malformed = {
|
||||
...selected,
|
||||
format: "pe" as const,
|
||||
};
|
||||
expect(() =>
|
||||
createEvidence(malformed, PROVIDER, {
|
||||
operation: "inspect",
|
||||
parameters: {},
|
||||
result: null,
|
||||
}),
|
||||
).toThrow();
|
||||
expect(
|
||||
createEvidence(
|
||||
{
|
||||
path: selected.path,
|
||||
sha256: selected.sha256,
|
||||
format: "ines",
|
||||
},
|
||||
PROVIDER,
|
||||
{ operation: "inspect", parameters: {}, result: null },
|
||||
).subject,
|
||||
).toMatchObject({ format: "ines", architecture: null });
|
||||
for (const format of ["pe", "ines"] as const) {
|
||||
expect(() =>
|
||||
createEvidence({ ...selected, format }, PROVIDER, {
|
||||
operation: "inspect",
|
||||
parameters: {},
|
||||
result: null,
|
||||
}),
|
||||
).toThrow();
|
||||
}
|
||||
});
|
||||
|
||||
it("preserves omitted relationship diagnostics and authenticates reported diagnostics", () => {
|
||||
|
||||
@@ -56,6 +56,7 @@ const subjectFormatSchema = z.enum([
|
||||
"hsp",
|
||||
"app-pack",
|
||||
"asar",
|
||||
"ines",
|
||||
"dmg",
|
||||
"pkg",
|
||||
"plist",
|
||||
|
||||
@@ -175,7 +175,9 @@ describe("function comparison normalized identity", () => {
|
||||
it("retains unresolved call details alongside missing facet coverage", () => {
|
||||
const value: Record<string, unknown> = {
|
||||
...dossier("return 0;", "0x1000"),
|
||||
unresolved_calls: [{ address: "0x1010", reason: "Unknown indirect target" }],
|
||||
unresolved_calls: [
|
||||
{ address: "0x1010", reason: "Unknown indirect target" },
|
||||
],
|
||||
};
|
||||
delete value.facet_availability;
|
||||
const legacy = observe("a", functionDossierSchema.parse(value), "ida");
|
||||
|
||||
@@ -0,0 +1,92 @@
|
||||
import { expect, it } from "vitest";
|
||||
import { parseInesLayout } from "./inesContainer.js";
|
||||
|
||||
const header = (): Buffer => {
|
||||
const bytes = Buffer.alloc(16);
|
||||
bytes.write("NES\x1a", "latin1");
|
||||
bytes[4] = 1;
|
||||
return bytes;
|
||||
};
|
||||
|
||||
it("bounds the complete classic header count without inventing RAM regions", () => {
|
||||
const bytes = header();
|
||||
bytes[4] = 255;
|
||||
bytes[5] = 255;
|
||||
bytes[6] = 0xfe;
|
||||
bytes[7] = 0xf3;
|
||||
const parsed = parseInesLayout(bytes, 16 + 512 + 255 * (16_384 + 8_192));
|
||||
if (!parsed.ok) throw new Error(parsed.error);
|
||||
expect(parsed.value.header).toMatchObject({
|
||||
mapper: 255,
|
||||
trainer_present: true,
|
||||
battery_flag: true,
|
||||
mirroring: "four-screen",
|
||||
});
|
||||
expect(parsed.value.regions).toHaveLength(512);
|
||||
expect(parsed.value.regions.at(-1)).toMatchObject({
|
||||
path: "chr/254.bin",
|
||||
length: 8_192,
|
||||
});
|
||||
});
|
||||
|
||||
it.each([
|
||||
{
|
||||
label: "short header",
|
||||
modify: (bytes: Buffer) => bytes.subarray(0, 8),
|
||||
size: 8,
|
||||
reason: "truncated iNES header",
|
||||
},
|
||||
{
|
||||
label: "short payload",
|
||||
modify: (bytes: Buffer) => bytes,
|
||||
size: 16,
|
||||
reason: "truncated iNES payload",
|
||||
},
|
||||
{
|
||||
label: "NES 2.0",
|
||||
modify: (bytes: Buffer) => {
|
||||
bytes[7] = 8;
|
||||
return bytes;
|
||||
},
|
||||
size: 16_400,
|
||||
reason: "nes-2.0",
|
||||
},
|
||||
{
|
||||
label: "dirty legacy header",
|
||||
modify: (bytes: Buffer) => {
|
||||
bytes[12] = 1;
|
||||
return bytes;
|
||||
},
|
||||
size: 16_400,
|
||||
reason: "ambiguous iNES mapper",
|
||||
},
|
||||
{
|
||||
label: "empty PRG",
|
||||
modify: (bytes: Buffer) => {
|
||||
bytes[4] = 0;
|
||||
return bytes;
|
||||
},
|
||||
size: 16,
|
||||
reason: "at least one PRG",
|
||||
},
|
||||
{
|
||||
label: "unsupported variant",
|
||||
modify: (bytes: Buffer) => {
|
||||
bytes[7] = 4;
|
||||
return bytes;
|
||||
},
|
||||
size: 16_400,
|
||||
reason: "unsupported iNES header variant",
|
||||
},
|
||||
{
|
||||
label: "unsafe extent",
|
||||
modify: (bytes: Buffer) => bytes,
|
||||
size: Number.MAX_SAFE_INTEGER + 1,
|
||||
reason: "invalid iNES file extent",
|
||||
},
|
||||
])("refuses $label before producing regions", ({ modify, size, reason }) => {
|
||||
expect(parseInesLayout(modify(header()), size)).toMatchObject({
|
||||
ok: false,
|
||||
error: expect.stringContaining(reason),
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,131 @@
|
||||
import { z } from "zod";
|
||||
import { err, ok, type Result } from "./result.js";
|
||||
|
||||
/** Byte signatures select a container family, never an executable architecture. */
|
||||
export const nesContainerFormat = (
|
||||
prefix: Buffer,
|
||||
): "ines" | "nes-2.0" | "unif" | undefined => {
|
||||
if (prefix.subarray(0, 4).equals(Buffer.from("UNIF"))) return "unif";
|
||||
if (!prefix.subarray(0, 4).equals(Buffer.from([0x4e, 0x45, 0x53, 0x1a])))
|
||||
return undefined;
|
||||
return prefix.length >= 8 && (prefix.readUInt8(7) & 0x0c) === 0x08
|
||||
? "nes-2.0"
|
||||
: "ines";
|
||||
};
|
||||
|
||||
const inesHeaderSchema = z.strictObject({
|
||||
format: z.literal("ines"),
|
||||
header_hex: z.string().regex(/^[a-f0-9]{32}$/u),
|
||||
prg_rom_units_16k: z.number().int().min(1).max(255),
|
||||
chr_rom_units_8k: z.number().int().min(0).max(255),
|
||||
mapper: z.number().int().min(0).max(255),
|
||||
flags_6: z.number().int().min(0).max(255),
|
||||
flags_7: z.number().int().min(0).max(255),
|
||||
trainer_present: z.boolean(),
|
||||
battery_flag: z.boolean(),
|
||||
mirroring: z.enum(["horizontal", "vertical", "four-screen"]),
|
||||
});
|
||||
|
||||
/** Verified concatenation is a byte identity claim, not an emulator claim. */
|
||||
export const inesInventorySchema = z.strictObject({
|
||||
header: inesHeaderSchema,
|
||||
reconstruction: z.strictObject({
|
||||
region_order: z.array(z.string().min(1)).min(2),
|
||||
bytes: z.number().int().min(16).max(Number.MAX_SAFE_INTEGER),
|
||||
sha256: z.string().regex(/^[a-f0-9]{64}$/u),
|
||||
verified: z.literal(true),
|
||||
}),
|
||||
});
|
||||
|
||||
export type InesInventory = z.infer<typeof inesInventorySchema>;
|
||||
|
||||
export interface InesRegion {
|
||||
readonly path: string;
|
||||
readonly offset: number;
|
||||
readonly length: number;
|
||||
}
|
||||
|
||||
export interface InesLayout {
|
||||
readonly header: InesInventory["header"];
|
||||
readonly regions: readonly InesRegion[];
|
||||
}
|
||||
|
||||
/**
|
||||
* Classic iNES counts 16 KiB PRG and 8 KiB CHR file units. Those units do not
|
||||
* establish the mapper's runtime windows. Preserve all other bytes verbatim.
|
||||
*/
|
||||
export const parseInesLayout = (
|
||||
prefix: Buffer,
|
||||
fileSize: number,
|
||||
): Result<InesLayout, string> => {
|
||||
const format = nesContainerFormat(prefix);
|
||||
if (format !== "ines")
|
||||
return err(
|
||||
format === undefined
|
||||
? "missing iNES byte signature"
|
||||
: `${format} containers are not supported by the classic iNES lane`,
|
||||
);
|
||||
if (!Number.isSafeInteger(fileSize) || fileSize < 0)
|
||||
return err("invalid iNES file extent: expected a nonnegative safe integer");
|
||||
if (fileSize < 16 || prefix.length < 16)
|
||||
return err("truncated iNES header: expected 16 bytes");
|
||||
const prgUnits = prefix.readUInt8(4);
|
||||
const chrUnits = prefix.readUInt8(5);
|
||||
const flags6 = prefix.readUInt8(6);
|
||||
const flags7 = prefix.readUInt8(7);
|
||||
if ((flags7 & 0x0c) !== 0) return err("unsupported iNES header variant");
|
||||
// Dirty legacy headers make the upper mapper bits ambiguous. Do not repair
|
||||
// them or claim a mapper that the observed header cannot establish.
|
||||
if (prefix.subarray(12, 16).some((byte) => byte !== 0))
|
||||
return err(
|
||||
"ambiguous iNES mapper: reserved header bytes 12..15 are nonzero",
|
||||
);
|
||||
if (prgUnits === 0) return err("iNES requires at least one PRG-ROM unit");
|
||||
const trainer = (flags6 & 4) !== 0;
|
||||
const declaredEnd =
|
||||
16 + (trainer ? 512 : 0) + prgUnits * 16_384 + chrUnits * 8_192;
|
||||
if (declaredEnd > fileSize)
|
||||
return err(
|
||||
`truncated iNES payload: header declares ${declaredEnd} bytes; file has ${fileSize}`,
|
||||
);
|
||||
const regions: InesRegion[] = [{ path: "header.bin", offset: 0, length: 16 }];
|
||||
let offset = 16;
|
||||
if (trainer) {
|
||||
regions.push({ path: "trainer.bin", offset, length: 512 });
|
||||
offset += 512;
|
||||
}
|
||||
for (const [kind, count, length] of [
|
||||
["prg", prgUnits, 16_384],
|
||||
["chr", chrUnits, 8_192],
|
||||
] as const)
|
||||
for (let index = 0; index < count; index += 1) {
|
||||
regions.push({
|
||||
path: `${kind}/${String(index).padStart(3, "0")}.bin`,
|
||||
offset,
|
||||
length,
|
||||
});
|
||||
offset += length;
|
||||
}
|
||||
if (offset < fileSize)
|
||||
regions.push({ path: "trailing.bin", offset, length: fileSize - offset });
|
||||
return ok({
|
||||
header: {
|
||||
format: "ines",
|
||||
header_hex: prefix.subarray(0, 16).toString("hex"),
|
||||
prg_rom_units_16k: prgUnits,
|
||||
chr_rom_units_8k: chrUnits,
|
||||
mapper: (flags6 >>> 4) | (flags7 & 0xf0),
|
||||
flags_6: flags6,
|
||||
flags_7: flags7,
|
||||
trainer_present: trainer,
|
||||
battery_flag: (flags6 & 2) !== 0,
|
||||
mirroring:
|
||||
(flags6 & 8) !== 0
|
||||
? "four-screen"
|
||||
: (flags6 & 1) !== 0
|
||||
? "vertical"
|
||||
: "horizontal",
|
||||
},
|
||||
regions,
|
||||
});
|
||||
};
|
||||
@@ -3,6 +3,7 @@ import { z } from "zod";
|
||||
import {
|
||||
browserAllowedOriginsSchema,
|
||||
browserEndpointSchema,
|
||||
recordedBrowserObservationEndpointSchema,
|
||||
} from "../browserObservation.js";
|
||||
import {
|
||||
webPageInspectionSchema,
|
||||
@@ -424,14 +425,17 @@ const assertRuntimeParameters = (
|
||||
): void => {
|
||||
const common = {
|
||||
target_id: z.string().trim().min(1),
|
||||
cdp_endpoint: browserEndpointSchema,
|
||||
include_script_sources: z.boolean(),
|
||||
};
|
||||
if (expected.kind === "browser") {
|
||||
const parameters = parseAtPath(
|
||||
(value) =>
|
||||
z
|
||||
.object({ ...common, allowed_origins: browserAllowedOriginsSchema })
|
||||
.object({
|
||||
...common,
|
||||
cdp_endpoint: recordedBrowserObservationEndpointSchema,
|
||||
allowed_origins: browserAllowedOriginsSchema,
|
||||
})
|
||||
.passthrough()
|
||||
.parse(value),
|
||||
evidence.parameters,
|
||||
@@ -455,7 +459,11 @@ const assertRuntimeParameters = (
|
||||
return;
|
||||
}
|
||||
const parameters = parseAtPath(
|
||||
(value) => z.object(common).passthrough().parse(value),
|
||||
(value) =>
|
||||
z
|
||||
.object({ ...common, cdp_endpoint: browserEndpointSchema })
|
||||
.passthrough()
|
||||
.parse(value),
|
||||
evidence.parameters,
|
||||
[...path, "parameters"],
|
||||
);
|
||||
|
||||
@@ -0,0 +1,96 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
import { analyzeJavaScriptSemantics } from "./javascriptSemanticAnalysis.js";
|
||||
|
||||
const observe = (source: string) => {
|
||||
const ir = analyzeJavaScriptSemantics(source);
|
||||
return {
|
||||
binding: ir.bindings.find((item) => item.name === "x")?.value,
|
||||
returned: ir.callables.find((item) => item.name === "read")?.returnSites[0]
|
||||
?.value,
|
||||
};
|
||||
};
|
||||
|
||||
describe("JavaScript semantic analysis: logical assignment", () => {
|
||||
it.each(["||=", "??=", "&&="])(
|
||||
"keeps a parameter uncertain after %s",
|
||||
(operator) => {
|
||||
const { binding, returned } = observe(
|
||||
`function read(x) { x ${operator} 2; return x; }`,
|
||||
);
|
||||
expect(binding?.status).toBe("unknown");
|
||||
expect(returned?.status).toBe("unknown");
|
||||
},
|
||||
);
|
||||
|
||||
it.each(["||=", "??=", "&&="])(
|
||||
"keeps a destructured parameter uncertain after %s",
|
||||
(operator) => {
|
||||
const { binding, returned } = observe(
|
||||
`function read({ x }) { x ${operator} 2; return x; }`,
|
||||
);
|
||||
expect(binding?.status).toBe("unknown");
|
||||
expect(returned?.status).toBe("unknown");
|
||||
},
|
||||
);
|
||||
|
||||
it.each(["||=", "??=", "&&="])(
|
||||
"keeps a catch binding uncertain after %s",
|
||||
(operator) => {
|
||||
const { binding, returned } = observe(
|
||||
`function read() { try { run(); } catch (x) { x ${operator} 2; return x; } }`,
|
||||
);
|
||||
expect(binding?.status).toBe("unknown");
|
||||
expect(returned?.status).toBe("unknown");
|
||||
},
|
||||
);
|
||||
|
||||
it.each([
|
||||
["let", "||="],
|
||||
["let", "??="],
|
||||
["var", "||="],
|
||||
["var", "??="],
|
||||
])(
|
||||
"keeps an uninitialized %s local exact after %s",
|
||||
(declaration, operator) => {
|
||||
const { binding, returned } = observe(
|
||||
`function read() { ${declaration} x; x ${operator} 2; return x; }`,
|
||||
);
|
||||
expect(binding).toEqual({ status: "literal", value: 2 });
|
||||
expect(returned).toEqual({ status: "literal", value: 2 });
|
||||
},
|
||||
);
|
||||
|
||||
it("keeps an unconditional parameter assignment exact", () => {
|
||||
const { binding, returned } = observe(
|
||||
"function read(x) { x = 2; return x; }",
|
||||
);
|
||||
expect(binding).toEqual({ status: "literal", value: 2 });
|
||||
expect(returned).toEqual({ status: "literal", value: 2 });
|
||||
});
|
||||
|
||||
it("keeps an unchanged parameter unknown", () => {
|
||||
expect(observe("function read(x) { return x; }").returned?.status).toBe(
|
||||
"unknown",
|
||||
);
|
||||
});
|
||||
|
||||
it("reproduces the issue #2646 inputs without an exact literal", () => {
|
||||
for (const operator of ["||=", "??="]) {
|
||||
const { binding, returned } = observe(
|
||||
`function read(x) { x ${operator} 2; return x; }`,
|
||||
);
|
||||
expect(binding).not.toEqual({ status: "literal", value: 2 });
|
||||
expect(returned).not.toEqual({ status: "literal", value: 2 });
|
||||
}
|
||||
const readOr = (x: number) => {
|
||||
x ||= 2;
|
||||
return x;
|
||||
};
|
||||
const readNullish = (x: number) => {
|
||||
x ??= 2;
|
||||
return x;
|
||||
};
|
||||
expect(readOr(5)).toBe(5);
|
||||
expect(readNullish(5)).toBe(5);
|
||||
});
|
||||
});
|
||||
@@ -919,6 +919,21 @@ const bindImportEquals = (
|
||||
});
|
||||
};
|
||||
|
||||
// A parameter or catch binding starts with a caller-supplied value that a
|
||||
// conditional logical assignment can retain, so its RHS is not exact.
|
||||
const hasIncomingValue = (
|
||||
identifier: t.Identifier,
|
||||
scope: JavaScriptSemanticScopeState,
|
||||
state: JavaScriptSemanticAnalysisState,
|
||||
): boolean => {
|
||||
const kind = resolveSemanticBindingFromScope(
|
||||
scope,
|
||||
identifier.name,
|
||||
state,
|
||||
)?.kind;
|
||||
return kind === "parameter" || kind === "catch";
|
||||
};
|
||||
|
||||
const bindAssignment = (
|
||||
node: t.Node,
|
||||
scope: JavaScriptSemanticScopeState,
|
||||
@@ -929,8 +944,8 @@ const bindAssignment = (
|
||||
addAssignment(
|
||||
node.left,
|
||||
node.operator === "=" ||
|
||||
node.operator === "||=" ||
|
||||
node.operator === "??="
|
||||
((node.operator === "||=" || node.operator === "??=") &&
|
||||
!hasIncomingValue(node.left, scope, state))
|
||||
? node.right
|
||||
: node,
|
||||
scope,
|
||||
|
||||
@@ -275,12 +275,3 @@ export const dataEffectMemberCallee = (
|
||||
t.isMemberExpression(node.callee) || t.isOptionalMemberExpression(node.callee)
|
||||
? node.callee
|
||||
: null;
|
||||
|
||||
/** Read a parent member's object when present. */
|
||||
export const dataEffectMemberObject = (
|
||||
node: t.Node | null,
|
||||
): t.Expression | t.Super | null =>
|
||||
node !== null &&
|
||||
(t.isMemberExpression(node) || t.isOptionalMemberExpression(node))
|
||||
? node.object
|
||||
: null;
|
||||
|
||||
@@ -24,7 +24,6 @@ import {
|
||||
dataEffectArgumentBindingId as argumentBindingId,
|
||||
dataEffectLiteralString as literalString,
|
||||
dataEffectMemberCallee as memberCallee,
|
||||
dataEffectMemberObject as memberObject,
|
||||
dataEffectPrimitive as primitiveValue,
|
||||
isSemanticProcessObject as isProcessObject,
|
||||
outerDataEffectBinding as outerAssignedBinding,
|
||||
@@ -83,8 +82,8 @@ const collectConfigurations = (
|
||||
context: TraversalContext,
|
||||
): ConfigurationCandidate[] => {
|
||||
const output: ConfigurationCandidate[] = [];
|
||||
traverseWithContext(program, context, (node, parent) => {
|
||||
const details = configurationDetails(node, parent, context);
|
||||
traverseWithContext(program, context, (node) => {
|
||||
const details = configurationDetails(node, context);
|
||||
if (details === null) return;
|
||||
const operation: JavaScriptSemanticConfigurationOperation = {
|
||||
configId: `config:${details.kind}:${String(node.start ?? -1)}:${String(node.end ?? -1)}`,
|
||||
@@ -104,17 +103,13 @@ const collectConfigurations = (
|
||||
|
||||
const configurationDetails = (
|
||||
node: t.Node,
|
||||
parent: t.Node | null,
|
||||
context: TraversalContext,
|
||||
): {
|
||||
readonly kind: "environment" | "argv" | "file";
|
||||
readonly key: string | null;
|
||||
readonly resolution: "complete" | "partial";
|
||||
} | null => {
|
||||
if (
|
||||
(t.isMemberExpression(node) || t.isOptionalMemberExpression(node)) &&
|
||||
!(memberObject(parent) === node)
|
||||
) {
|
||||
if (t.isMemberExpression(node) || t.isOptionalMemberExpression(node)) {
|
||||
const processMember = processConfigurationMember(node, context.state);
|
||||
if (processMember !== null) return processMember;
|
||||
}
|
||||
|
||||
@@ -92,7 +92,10 @@ export type PinvokeVerification = z.infer<typeof pinvokeVerificationSchema>;
|
||||
export const managedNativeVerificationInputSchema = z
|
||||
.strictObject({
|
||||
managed_boundaries: evidenceSchema,
|
||||
native_observations: z.array(evidenceSchema).min(1),
|
||||
native_observations: z
|
||||
.array(evidenceSchema)
|
||||
.min(1)
|
||||
.describe("Native function or export Evidence records"),
|
||||
})
|
||||
.superRefine((input, context) => {
|
||||
const ids = new Set<string>();
|
||||
|
||||
@@ -44,6 +44,16 @@ const dossier = jsonValueSchema.parse(
|
||||
referenced_names: [],
|
||||
native_api: null,
|
||||
native_value_flow: null,
|
||||
facet_availability: {
|
||||
pseudocode: { available: true },
|
||||
assembly: { available: true },
|
||||
comments: { available: true },
|
||||
callers: { available: true },
|
||||
callees: { available: true },
|
||||
references: { available: true },
|
||||
strings_names: { available: true },
|
||||
cfg: { available: true },
|
||||
},
|
||||
basic_blocks: [{ start: "0x1000", end: "0x1001", successors: [] }],
|
||||
limitations: [],
|
||||
}),
|
||||
|
||||
@@ -0,0 +1,104 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
|
||||
import {
|
||||
createHistoricalSourceGraph,
|
||||
createHistoricalSourceManifest,
|
||||
type HistoricalSourceGraphInput,
|
||||
} from "./referenceSourceGraph.js";
|
||||
import { createHistoricalSourceSummary } from "./referenceSourceSummary.js";
|
||||
|
||||
const input = (
|
||||
entries: HistoricalSourceGraphInput["entries"],
|
||||
): HistoricalSourceGraphInput => ({
|
||||
schema: "HistoricalSourceGraph",
|
||||
authority: "historical-reference",
|
||||
root_alias: "$REFERENCE_ROOT",
|
||||
inventory_state: "unknown",
|
||||
entries,
|
||||
relationships: [],
|
||||
parse_failures: [],
|
||||
exclusions: [],
|
||||
languages: [],
|
||||
manifests: [],
|
||||
vcs: null,
|
||||
provenance: { importer: "fixture", importer_version: null, caller: "test" },
|
||||
limitations: ["Inventory coverage is unknown"],
|
||||
});
|
||||
|
||||
describe("committed historical-source summaries", () => {
|
||||
it("preserves unknown coverage, sizes, directories and missing symlinks without mutating the graph", () => {
|
||||
const graph = createHistoricalSourceGraph(
|
||||
input([
|
||||
{
|
||||
path: "a",
|
||||
kind: "directory",
|
||||
tree_state: "unknown",
|
||||
classifications: ["unknown"],
|
||||
limitations: ["Not enumerated"],
|
||||
},
|
||||
{
|
||||
path: "b",
|
||||
kind: "file",
|
||||
sha256: null,
|
||||
size: null,
|
||||
content_state: "unreadable",
|
||||
language: null,
|
||||
classifications: ["unknown"],
|
||||
limitations: ["Not readable"],
|
||||
},
|
||||
{
|
||||
path: "c",
|
||||
kind: "symlink",
|
||||
target: "missing",
|
||||
target_state: "missing",
|
||||
classifications: ["unknown"],
|
||||
limitations: [],
|
||||
},
|
||||
]),
|
||||
);
|
||||
const original = structuredClone(graph);
|
||||
const summary = createHistoricalSourceSummary(graph, 1);
|
||||
expect(summary).toMatchObject({
|
||||
manifest: createHistoricalSourceManifest(original),
|
||||
inventory_state: "unknown",
|
||||
vcs: null,
|
||||
provenance: original.provenance,
|
||||
file_sizes: { known_bytes: "0", unknown_file_count: 1 },
|
||||
counts: { entries: 3, files: 1, directories: 1, symlinks: 1 },
|
||||
directory_tree_states: { unknown: 1, enumerated: 0 },
|
||||
file_content_states: { unreadable: 1, hashed: 0 },
|
||||
limitations: original.limitations,
|
||||
outline: {
|
||||
entries: [
|
||||
original.entries[0],
|
||||
expect.objectContaining({ size: null, content_state: "unreadable" }),
|
||||
original.entries[2],
|
||||
],
|
||||
omitted_entry_count: 0,
|
||||
},
|
||||
});
|
||||
expect(summary.outline.entries[1]).not.toHaveProperty("sha256");
|
||||
expect(graph).toEqual(original);
|
||||
});
|
||||
|
||||
it("sums known bytes losslessly beyond the JSON safe integer range", () => {
|
||||
const graph = createHistoricalSourceGraph(
|
||||
input(
|
||||
["a", "b"].map((path) => ({
|
||||
path,
|
||||
kind: "file",
|
||||
sha256: "a".repeat(64),
|
||||
size: Number.MAX_SAFE_INTEGER,
|
||||
content_state: "hashed",
|
||||
language: null,
|
||||
classifications: ["unknown"],
|
||||
limitations: [],
|
||||
})),
|
||||
),
|
||||
);
|
||||
expect(createHistoricalSourceSummary(graph, 0)).toMatchObject({
|
||||
file_sizes: { known_bytes: "18014398509481982", unknown_file_count: 0 },
|
||||
outline: { entries: [], omitted_entry_count: 2 },
|
||||
});
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,93 @@
|
||||
import {
|
||||
createHistoricalSourceManifest,
|
||||
type HistoricalSourceGraph,
|
||||
} from "./referenceSourceGraph.js";
|
||||
|
||||
type Entry = HistoricalSourceGraph["entries"][number];
|
||||
|
||||
const outlineEntry = (entry: Entry) => {
|
||||
if (entry.kind !== "file") return entry;
|
||||
return {
|
||||
path: entry.path,
|
||||
kind: entry.kind,
|
||||
language: entry.language,
|
||||
size: entry.size,
|
||||
content_state: entry.content_state,
|
||||
classifications: entry.classifications,
|
||||
limitations: entry.limitations,
|
||||
};
|
||||
};
|
||||
|
||||
/** Project one committed inventory without rereading or reinterpreting source. */
|
||||
export const createHistoricalSourceSummary = (
|
||||
graph: HistoricalSourceGraph,
|
||||
outlineDepth: number,
|
||||
) => {
|
||||
const manifest = createHistoricalSourceManifest(graph);
|
||||
const counts = {
|
||||
entries: graph.entries.length,
|
||||
files: 0,
|
||||
directories: 0,
|
||||
symlinks: 0,
|
||||
relationships: graph.relationships.length,
|
||||
parse_failures: graph.parse_failures.length,
|
||||
exclusions: graph.exclusions.length,
|
||||
};
|
||||
const contentStates = {
|
||||
hashed: 0,
|
||||
"redacted-secret": 0,
|
||||
excluded: 0,
|
||||
unreadable: 0,
|
||||
unknown: 0,
|
||||
};
|
||||
const treeStates = {
|
||||
enumerated: 0,
|
||||
partial: 0,
|
||||
excluded: 0,
|
||||
unreadable: 0,
|
||||
unknown: 0,
|
||||
};
|
||||
let knownBytes = 0n;
|
||||
let unknownSizeFiles = 0;
|
||||
const outline: ReturnType<typeof outlineEntry>[] = [];
|
||||
for (const entry of graph.entries) {
|
||||
if (entry.kind === "file") {
|
||||
counts.files += 1;
|
||||
contentStates[entry.content_state] += 1;
|
||||
if (entry.size === null) unknownSizeFiles += 1;
|
||||
else knownBytes += BigInt(entry.size);
|
||||
} else if (entry.kind === "directory") {
|
||||
counts.directories += 1;
|
||||
treeStates[entry.tree_state] += 1;
|
||||
} else counts.symlinks += 1;
|
||||
// Canonical entries already use Unicode code-point order; filtering preserves it.
|
||||
if (entry.path.split("/").length <= outlineDepth)
|
||||
outline.push(outlineEntry(entry));
|
||||
}
|
||||
return {
|
||||
schema: "HistoricalSourceSummary" as const,
|
||||
authority: graph.authority,
|
||||
root_alias: graph.root_alias,
|
||||
manifest,
|
||||
inventory_state: graph.inventory_state,
|
||||
provenance: graph.provenance,
|
||||
vcs: graph.vcs,
|
||||
languages: graph.languages,
|
||||
manifests: graph.manifests,
|
||||
counts,
|
||||
file_content_states: contentStates,
|
||||
directory_tree_states: treeStates,
|
||||
file_sizes: {
|
||||
// Decimal text keeps large totals exact; this covers only known inventoried sizes.
|
||||
known_bytes: knownBytes.toString(),
|
||||
unknown_file_count: unknownSizeFiles,
|
||||
},
|
||||
exclusions: graph.exclusions,
|
||||
limitations: graph.limitations,
|
||||
outline: {
|
||||
depth: outlineDepth,
|
||||
entries: outline,
|
||||
omitted_entry_count: graph.entries.length - outline.length,
|
||||
},
|
||||
};
|
||||
};
|
||||
@@ -2,10 +2,18 @@ import { expect, it } from "vitest";
|
||||
|
||||
import { hasValidSourceMapContents } from "./sourceMapContents.js";
|
||||
|
||||
it("accepts absent map-level source contents and aligned nullable slots", () => {
|
||||
expect(hasValidSourceMapContents(2, undefined)).toBe(true);
|
||||
expect(hasValidSourceMapContents(2, null)).toBe(true);
|
||||
expect(hasValidSourceMapContents(2, [null, "retained source"])).toBe(true);
|
||||
expect(hasValidSourceMapContents(2, ["retained source"])).toBe(false);
|
||||
expect(hasValidSourceMapContents(2, [null, 42])).toBe(false);
|
||||
it("accepts absent map-level source contents and nullable string slots", () => {
|
||||
expect(hasValidSourceMapContents(undefined)).toBe(true);
|
||||
expect(hasValidSourceMapContents(null)).toBe(true);
|
||||
expect(hasValidSourceMapContents([null, "retained source"])).toBe(true);
|
||||
expect(hasValidSourceMapContents([null, 42])).toBe(false);
|
||||
expect(hasValidSourceMapContents("retained source")).toBe(false);
|
||||
});
|
||||
|
||||
it("leaves sourcesContent length to source decoding (ECMA-426 DecodeSourceMapSources)", () => {
|
||||
expect(hasValidSourceMapContents([])).toBe(true);
|
||||
expect(hasValidSourceMapContents(["retained source"])).toBe(true);
|
||||
expect(
|
||||
hasValidSourceMapContents(["a", null, "unused trailing content"]),
|
||||
).toBe(true);
|
||||
});
|
||||
|
||||
@@ -1,12 +1,15 @@
|
||||
/** Validate optional source-map content against its source inventory. */
|
||||
export const hasValidSourceMapContents = (
|
||||
sourceCount: number,
|
||||
contents: unknown,
|
||||
): boolean =>
|
||||
/**
|
||||
* Validate optional source-map content against its source inventory.
|
||||
*
|
||||
* ECMA-426 DecodeSourceMapSources reads a content slot only while its index is
|
||||
* within `sourcesContent`, so a shorter array leaves trailing sources without
|
||||
* content and a longer array contributes no extra sources. Only the entry types
|
||||
* are checked here.
|
||||
*/
|
||||
export const hasValidSourceMapContents = (contents: unknown): boolean =>
|
||||
contents === undefined ||
|
||||
contents === null ||
|
||||
(Array.isArray(contents) &&
|
||||
contents.length === sourceCount &&
|
||||
contents.every(
|
||||
(content: unknown) => content === null || typeof content === "string",
|
||||
));
|
||||
|
||||
@@ -3,7 +3,7 @@ import { z } from "zod";
|
||||
import { browserCompletenessSchema } from "./browserCompleteness.js";
|
||||
import {
|
||||
browserAllowedOriginsSchema,
|
||||
browserEndpointSchema,
|
||||
browserObservationEndpointSchema,
|
||||
} from "./browserObservation.js";
|
||||
import { browserVersionSchema } from "./browserObservationSchemas.js";
|
||||
import { jsonValueSchema } from "./jsonValue.js";
|
||||
@@ -11,7 +11,7 @@ import { digestSchema, prefixedDigestSchema } from "./../domain/digests.js";
|
||||
|
||||
/** Input for passive discovery of page-registered WebMCP tools. */
|
||||
export const discoverWebMcpToolsInputSchema = z.strictObject({
|
||||
cdp_endpoint: browserEndpointSchema,
|
||||
cdp_endpoint: browserObservationEndpointSchema,
|
||||
allowed_origins: browserAllowedOriginsSchema,
|
||||
target_id: z.string().trim().min(1),
|
||||
observation_ms: z.number().int().min(0).default(100),
|
||||
|
||||
@@ -5,7 +5,7 @@ import { z } from "zod";
|
||||
import { browserCompletenessSchema } from "./browserCompleteness.js";
|
||||
import {
|
||||
browserAllowedOriginsSchema,
|
||||
browserEndpointSchema,
|
||||
browserObservationEndpointSchema,
|
||||
} from "./browserObservation.js";
|
||||
import { browserVersionSchema } from "./browserObservationSchemas.js";
|
||||
|
||||
@@ -34,7 +34,7 @@ export type WebScreenshotArtifact = z.infer<typeof webScreenshotArtifactSchema>;
|
||||
|
||||
/** Input for one read-only visible-viewport screenshot. */
|
||||
export const captureWebScreenshotInputSchema = z.strictObject({
|
||||
cdp_endpoint: browserEndpointSchema,
|
||||
cdp_endpoint: browserObservationEndpointSchema,
|
||||
allowed_origins: browserAllowedOriginsSchema,
|
||||
target_id: z.string().trim().min(1),
|
||||
});
|
||||
|
||||
@@ -40,8 +40,11 @@ export class RegularFileAdmissionFailure extends Error {
|
||||
/** A regular input no longer matches the extent or identity admitted for reading. */
|
||||
export class RegularFileChangedError extends Error {
|
||||
readonly code = "ESTALE";
|
||||
constructor(readonly path: string) {
|
||||
super(`Selected input changed while being read: ${path}`);
|
||||
constructor(
|
||||
readonly path: string,
|
||||
options?: ErrorOptions,
|
||||
) {
|
||||
super(`Selected input changed while being read: ${path}`, options);
|
||||
this.name = "RegularFileChangedError";
|
||||
}
|
||||
}
|
||||
@@ -52,6 +55,30 @@ export interface StableRegularFileDescriptor {
|
||||
readonly initial: Stats;
|
||||
}
|
||||
|
||||
/** Revalidate admitted bytes before interpreting them, including lost path identity. */
|
||||
export const verifyRegularFileState = async (
|
||||
path: string,
|
||||
source: StableRegularFileDescriptor,
|
||||
): Promise<void> => {
|
||||
const [opened, selected] = await Promise.all([
|
||||
source.handle.stat(),
|
||||
lstat(path).catch((cause: unknown) => {
|
||||
if (
|
||||
cause instanceof Error &&
|
||||
"code" in cause &&
|
||||
["ENOENT", "ENOTDIR", "ELOOP"].includes(String(cause.code))
|
||||
)
|
||||
throw new RegularFileChangedError(path, { cause });
|
||||
throw cause;
|
||||
}),
|
||||
]);
|
||||
if (
|
||||
!sameRegularFileState(source.initial, opened) ||
|
||||
!sameRegularFileState(source.initial, selected)
|
||||
)
|
||||
throw new RegularFileChangedError(path);
|
||||
};
|
||||
|
||||
/** Open and verify the selected file descriptor without blocking on pipes. */
|
||||
export const openRegularFile = async (
|
||||
path: string,
|
||||
|
||||
@@ -0,0 +1,30 @@
|
||||
import type { FileHandle } from "node:fs/promises";
|
||||
|
||||
/** Fill a positional prefix until its bound or true EOF, preserving caller cancellation errors. */
|
||||
export const readFileHandlePrefix = async (
|
||||
handle: Pick<FileHandle, "read">,
|
||||
length: number,
|
||||
checkCancellation: () => void,
|
||||
): Promise<Buffer> => {
|
||||
const prefix = Buffer.alloc(length);
|
||||
let offset = 0;
|
||||
while (offset < length) {
|
||||
checkCancellation();
|
||||
let bytesRead: number;
|
||||
try {
|
||||
({ bytesRead } = await handle.read(
|
||||
prefix,
|
||||
offset,
|
||||
length - offset,
|
||||
offset,
|
||||
));
|
||||
} catch (cause: unknown) {
|
||||
checkCancellation();
|
||||
throw cause;
|
||||
}
|
||||
checkCancellation();
|
||||
if (bytesRead === 0) break;
|
||||
offset += bytesRead;
|
||||
}
|
||||
return prefix.subarray(0, offset);
|
||||
};
|
||||
@@ -503,7 +503,8 @@ export class IdaOperationRunner {
|
||||
items: [],
|
||||
availability: {
|
||||
available: false,
|
||||
reason: "Upstream xrefs do not establish direct caller relationships.",
|
||||
reason:
|
||||
"Upstream xrefs do not establish direct caller relationships.",
|
||||
},
|
||||
coverage: {
|
||||
status: "unknown",
|
||||
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user