Skip to content

Add image-trust signal to the verify verdict, backed by a stub allowlist (STE-54)#5

Merged
yvesfracari merged 1 commit into
mainfrom
pedro/ste-54-add-image-trust-signal-to-the-verify-verdict-backed-by-a
Jun 12, 2026
Merged

Add image-trust signal to the verify verdict, backed by a stub allowlist (STE-54)#5
yvesfracari merged 1 commit into
mainfrom
pedro/ste-54-add-image-trust-signal-to-the-verify-verdict-backed-by-a

Conversation

@yvesfracari

Copy link
Copy Markdown
Contributor

Closes STE-54

What

Adds a second, orthogonal trust dimension to the verification verdict: every verify result now carries an imageTrust tier describing how trustworthy the declared build image is. Rationale (from the RFP): reproducibility alone is not faithfulness to source — a hostile build image can deterministically rewrite bytes and still pass byte-comparison, so image trust must be a graded signal, not a binary.

Tier Meaning
sdf-trusted image digest is on the SDF-trusted allowlist
publicly-auditable allowlisted as a publicly-auditable third-party image
arbitrary a bldimg was declared but is not allowlisted
unknown no bldimg metadata available

How

  • docker/allowlist.json (new): checked-in allowlist mapping image references/digests to a tier, seeded with this repo's pinned toolchain image from docker/toolchain-manifest.json (publicly-auditable, digest null while the image is only built locally) and a documented placeholder entry shape for future SDF stellar-cli-docker digests (sdf-trusted). Doc header records the eviction semantics: removing an entry downgrades the tier reported for past verifications; it never deletes verification records.
  • reader/src/image-trust.ts (new): ImageTrustTier, AllowlistEntry, pure deriveImageTrust(bldimg, allowlist) (digest match or exact-reference match, first hit wins), and loadAllowlist() (missing file → empty allowlist; malformed file or an entry granting a non-allowlistable tier throws).
  • reader/src/verify.ts: VerificationResult gains imageTrust + bldimg; trust is judged on the on-chain WASM's SEP-58 bldimg (exposed by STE-53). verifyById loads the default allowlist (overridable via options); the ERROR path reports unknown (no on-chain bytes → no metadata to judge).
  • CLI: verify prints a trust: line with the tier and the bldimg value; --json includes the new fields automatically. Exit-code semantics unchanged (0 only on FULL_MATCH).
  • Exported from the package index; README documents the tier table.

Testing

  • 15 new unit tests cover all four tiers via deriveImageTrust, allowlist loading/validation, and compareWasm carrying the tier through every verdict (including: trust judged on on-chain metadata, not the rebuilt WASM's).
  • Full reader suite passes: 57 passed, 3 skipped (opt-in live).
  • Live testnet integration (SOROSCAN_INTEGRATION=1): fixture still reads/verifies; a new test derives its tier from on-chain metadata — unknown, correct since the fixture predates bldimg stamping.
  • End-to-end CLI against the live fixture:
[OK]  FULL_MATCH
    contract:  CDVSGPL3HFBGJ6ZEYQUAVE3OH3XE2ZE5ZT2GWPA3LKOYVD4UBPQJ2VHB
    network:   testnet
    trust:     unknown (no bldimg metadata)
    on-chain:  6fe7bd58e5a33dc27daefc74acfae6eb70f101fdbde860475cf18fde87288e4b
    rebuilt:   6fe7bd58e5a33dc27daefc74acfae6eb70f101fdbde860475cf18fde87288e4b

…ist (STE-54)

Every verify result now carries an imageTrust tier orthogonal to the
match verdict: sdf-trusted / publicly-auditable / arbitrary / unknown.
Reproducibility alone is not faithfulness to source — a hostile build
image can deterministically rewrite bytes and still pass
byte-comparison — so image trust is a graded signal, not a binary.

The tier is derived by looking up the on-chain WASM's SEP-58 bldimg in
the checked-in docker/allowlist.json, seeded with this repo's pinned
toolchain image (publicly-auditable) and a documented placeholder shape
for future SDF stellar-cli-docker digests (sdf-trusted). Eviction from
the allowlist downgrades the tier reported for past verifications; it
never deletes verification records.
@linear-code

linear-code Bot commented Jun 12, 2026

Copy link
Copy Markdown

STE-54

@yvesfracari yvesfracari merged commit 64da3c5 into main Jun 12, 2026
5 of 6 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant