Tarball input mode for verify (content-addressed source submission) (STE-55)

[yvesfracari]

Closes STE-55.

What

Adds the SEP-58 content-addressed source mode to verify: supply a source tarball plus its expected SHA-256 instead of a checked-out directory.

soroscan-verify verify --id <CONTRACT_ID> --tarball src.tar.gz --tarball-sha256 <hex> [--docker]
scripts/verify.sh <CONTRACT_ID> --tarball src.tar.gz --tarball-sha256 <hex> [--docker]

How it works

1. Digest gate first: the tarball's SHA-256 must equal the supplied digest, or verification returns ERROR (non-zero exit) before any unpacking — never build from an unverified tarball.
2. On match, the archive's entry names are validated (absolute paths and .. components rejected) before extraction into a fresh temp dir, which is cleaned up afterwards.
3. The unpacked source is rebuilt — local pinned toolchain by default, or the pinned network-isolated Docker image with --docker — and byte-compared against the on-chain WASM exactly as the existing verify does.
4. The result carries sourceMode: "tarball" and the verified tarballSha256, tying wasm hash ↔ source artifact digest.

Tests

TDD, 6 new tests in reader/test/verify-tarball.test.ts: digest mismatch (no unpack/build), happy path with a fixture tarball of the sample contract, ..-component rejection, absolute-path rejection, malformed archive, and build-failure → ERROR verdict (not a crash). Hostile archives are hand-rolled ustar blocks since tar CLIs refuse to create them. Full suite: 63 passed + 3 live testnet integration tests passed; typecheck clean.

Verified end-to-end against the deployed testnet fixture: tarball of contracts/ → digest gate → rebuild → FULL_MATCH (exit 0); digest mismatch → ERROR (exit 1); existing directory-based scripts/verify.sh flow still reports FULL_MATCH.

Notes

• VerificationResult.rebuiltSha256/rebuiltByteLength are now optional: tarball-mode failures can error before any WASM exists. verifyById always sets them, as before.
• Local (non-Docker) builds use the ambient toolchain, same as the existing directory mode; version managers that resolve per-directory (e.g. asdf) won't see the repo's .tool-versions from the temp dir. --docker is the pinned, environment-independent path.

[linear-code]

STE-55

[yvesfracari]

Applied the review's cheap fixes in a36cac7:

1. Link entries rejected by our own check — a header walk over the verified bytes rejects symlink/hardlink entries before extraction (typeflags 1/2), instead of relying on host-tar defaults. Notably, the new symlink/hardlink tests passed before the fix on macOS because bsdtar happens to refuse link extraction — i.e. the protection was real but platform-dependent. Assertions are now pinned to our error messages (symlink entries are not allowed) so host-tar stderr can't satisfy them.
2. TOCTOU closed — unpackTarball now takes the in-memory bytes the digest gate hashed and feeds them to tar -xf - via stdin; the tarball file is never re-read after hashing.
3. Compression auto-detect — gzip magic check + in-process gunzipSync, plain .tar fallback. This also removes the bsdtar-vs-GNU -z-on-read divergence (the uncompressed-tar test would have failed on Linux with the old tar -tzf approach).

Suite: 66 passed, typecheck clean, real testnet E2E re-run from the tarball → FULL_MATCH.

Not addressed (tracked as follow-ups, per review): Docker Desktop tmpdir mount note, multi-contract workspace selector for the default builder.