Skip to content

feat(spec): independent JavaScript verifier for korg-ledger@v1#5

Merged
New1Direction merged 1 commit into
mainfrom
feat/js-verifier
Jun 6, 2026
Merged

feat(spec): independent JavaScript verifier for korg-ledger@v1#5
New1Direction merged 1 commit into
mainfrom
feat/js-verifier

Conversation

@New1Direction

Copy link
Copy Markdown
Owner

Makes the "three genuinely independent implementations" claim true rather than aspirational.

What

Adds spec/korg-ledger-v1/js/ — a dependency-free, isomorphic (Node ≥18 + browser, via the Web Crypto standard) verifier for korg-ledger@v1, plus a conformance harness mirroring conformance.py.

File Role
verify.mjs the verifier — canonicalize / chain-hash (SHA-256 + HMAC) / verify_chain / verify_dag / Ed25519 tip-signature / receipt+journal autodetect + CLI
conformance.mjs executable oracle: reproduces every frozen tip_entry_hash, flags every tampered vector
bin.mjs shebang shim so verify.mjs stays browser-importable while npx still works
package.json npm-ready as @korgg/ledger-verify (npx korg-verify-js <receipt>)
README.md usage + library API

Why it matters

Before this PR there were two genuinely independent, conformance-tested implementations (Python conformance.py, Rust korg-verify) and an ad-hoc in-browser JS snippet on the launch site. The spec README claimed four implementations, two of which were stale (thumper, since folded) or untested (the launch-site JS). This replaces that with three rigorous, reproducible implementations — Python, JavaScript, Rust — each a one-command conformance check.

Verification

  • node spec/korg-ledger-v1/js/conformance.mjsPASS — reproduces 7418b910… (basic) and 1b371102… (HMAC) byte-for-byte, plus non-ASCII (éé) and astral surrogate-pair (𝄞𝄞) canonicalization edge cases.
  • Cross-implementation proof: verify.mjs and korg-verify (Rust) return the same VALID verdict and same signer on the real signed korg-proof/deliverable.korgreceipt.json (6 events) — Python minted the Ed25519 signature, Rust and JS both re-verify it.
  • Tamper one byte → rejected; wrong --pubkey pin → rejected; HMAC journal without key → rejected.
  • Rust baseline cargo test -p korg-verify unchanged and green.

Notes

  • Docs-only changes to spec/korg-ledger-v1/{README,SPEC}.md; no Rust/Python code touched.
  • verify.mjs has zero dependencies (Web Crypto only). Ed25519 in crypto.subtle needs a recent runtime (Node ≥18.4 / current browsers); chain + DAG checks work everywhere.
  • npm publish of @korgg/ledger-verify is left as a separate step (needs registry auth).

Add spec/korg-ledger-v1/js/ — a dependency-free, isomorphic (Node + browser via
Web Crypto) verifier plus a conformance harness mirroring conformance.py. It
reproduces every frozen tip hash byte-for-byte (including the non-ASCII and
astral surrogate-pair canonicalization edge cases) and cross-validates against
the Rust korg-verify crate on a real Ed25519-signed receipt: Python mints the
signature, Rust and JavaScript both re-verify it.

This makes the 'three genuinely independent implementations' claim TRUE rather
than aspirational — Python (conformance.py) + JavaScript (js/verify.mjs) + Rust
(korg-verify): three languages, three codepaths, one shared frozen oracle.

Update the spec README/SPEC to state that honestly: drop the folded 'thumper'
impl and the ad-hoc launch-site JS, list the three tested/reproducible
implementations with their one-command conformance checks.

npm-ready as @korgg/ledger-verify (npx korg-verify-js <receipt>).
@New1Direction New1Direction merged commit 46b6b3b into main Jun 6, 2026
2 checks passed
@New1Direction New1Direction deleted the feat/js-verifier branch June 6, 2026 00:07
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