feat(security): #498 — pin SHA-256 of perry.nativeLibrary prebuilt archives in perry.lock

[proggeramlug]

Closes #498.

Summary

A swapped or tampered prebuilt static archive (.a / .lib / .dylib) was undetectable before this change — perry resolved the path and handed it to the linker without inspection. A malicious dep update could swap in arbitrary native code and the host got no signal.

This adds a small SHA-256-based lockfile at the project root, analogous to package-lock.json's integrity field but scoped to the linker-visible archives perry consumes through perry.nativeLibrary.targets.<key>.prebuilt.

Zero runtime cost — the check is a compile-time hash + lookup; the resulting binary is the same size/shape as a build without the gate.

Cross-platform — runs in the platform-agnostic compile_command driver, so every backend (LLVM / WASM / ArkTS / HarmonyOS / Glance / SwiftUI / JS) inherits the protection from one choke point. Per-target-arch key (macos-arm64, linux-x86_64, …) matches what perry.nativeLibrary.targets uses in package.json.

File shape (<project_root>/perry.lock)

{
  "version": 1,
  "native_libraries": {
    "@bloomengine/engine": {
      "macos-arm64": "sha256:abcd..."
    },
    "lodash-native": {
      "linux-x86_64": "sha256:..."
    }
  }
}

BTreeMap-sorted on both levels → on-disk JSON is byte-deterministic across builds. git diff perry.lock is a meaningful supply-chain review signal.

Verification semantics

Lockfile state	Outcome
No perry.lock	Fresh lockfile written with current hashes.
Matching entry	Build proceeds.
Missing entry for (pkg, tgt)	Added to the lockfile (grows over time).
Mismatching entry	Build fails with verbose reviewer-actionable diagnostic.

Diagnostic example

Error: archive for `@bloomengine/engine` (target `macos-arm64`)
changed since last accepted:

  expected: sha256:abcd1234...
  found:    sha256:ef015678...
  path:     /repo/node_modules/@bloomengine/engine-darwin-arm64/lib/libbloom.a

Review the package — a swapped or tampered prebuilt static
archive is exactly the supply-chain attack class this lock
was added to catch (#498).

If the change is intentional (dep upgrade, vendored archive
rebuild), rerun the build with `PERRY_LOCK_REFRESH=1` to
rewrite the lockfile entry, or delete `perry.lock` to
regenerate it from scratch.

Env-var knobs

• PERRY_LOCK_REFRESH=1 — one-time. Rewrites mismatched entries instead of failing. Logged so it's obvious in build output. Use after a deliberate dep upgrade.
• PERRY_LOCK_FROZEN=1 — CI verification mode. Missing AND mismatching entries both fail. Ensures developers must commit perry.lock updates themselves; CI won't silently extend the lock.

Test coverage

9 unit tests in commands::perry_lock::tests:

• round_trip_empty_lock — serialize/deserialize stable
• missing_file_reads_empty — first-time semantics
• sha256_of_file_matches_known_vector — pins SHA-256 of "hello\n"
• first_build_adds_entries — adds entry, marks modified
• matching_hash_verifies — pass-through, no modification
• mismatching_hash_fails — checks diagnostic content (security: pinned checksums for perry.nativeLibrary archives #498 cite, refresh hint, both hashes, package name)
• refresh_env_var_rewrites_mismatch — PERRY_LOCK_REFRESH=1 path
• frozen_env_var_refuses_new_entries — PERRY_LOCK_FROZEN=1 path
• lockfile_is_deterministic_across_writes — BTreeMap order invariant

cargo test --release -p perry — 256 tests pass (247 pre-existing + 9 new).

Out of scope (deferred)

• Crate-source builds (crate_path field, built via cargo): multi-file builds need a different hash mechanism (Cargo.lock + workspace tree hash). The MVP covers single-file prebuilt archives only.
• Cross-target pre-hashing: hashing all targets a package declares at once instead of one-per-build.
• perry lock CLI subcommand: env-var refresh + lockfile deletion cover the same workflow without a new subcommand.

Acceptance

• First-time resolution writes hash to perry.lock
• Subsequent builds verify against locked hash
• Mismatch fails with actionable error
• [partial] perry lock --update <pkg> CLI subcommand deferred — PERRY_LOCK_REFRESH=1 covers the use case
• Hash covers every per-target archive declared by the package, not just host arch (multi-target builds accumulate hashes one target at a time)
• CI-friendly: --frozen mode via PERRY_LOCK_FROZEN=1

Notes

No Cargo.toml version bump, no CLAUDE.md version line touch, no CHANGELOG.md entry — maintainer folds those in at merge time.