Docs · Public ledger

Public ledger.

Available · Runs locally

Ledgerful publishes its own development change ledger as a redacted, signed, browser-verifiable bundle at /ledger.

What it is

Ledgerful's own development change ledger, published as a redacted, cryptographically verifiable static bundle at /ledger. Every entry carries a real Ed25519 signature from the engine's commit hook. Offline browser re-verify works for legacy v1 payloads; v2 provenance fields may be redacted, so the offline verifier fences full re-verify and points to local ledgerful verify --signatures.

What it proves

For v1 (or missing sig_version) rows: Ed25519 over the published five-field basis via WebCrypto — no backend call. For v2 rows: signature presence and an honest fence when free-text provenance is redacted from the public allowlist.

What it does not prove

Chain continuity as a full walk, signer identity without an out-of-band key pin, or full v2 free-text provenance when those fields are redacted.

Honest ceiling: the public ledger proves v1 entry signatures offline and publishes signed material for inspection. It does not prove order/set alone, key identity without a pin, or offline re-verify of redacted v2 provenance — use local CLI for that.

The allowlist

Only these fields are published:

tx_id
category
summary
reason
committed_at
author_pseudonym
verification_result
verification_duration_ms
risk_level
signature
public_key
entry_hash
prev_hash
sig_version

Author identity is a pseudonym. The author_pseudonym field is computed as HMAC-SHA256 over the author identity using a local secret key. The same author always produces the same pseudonym, so attribution patterns are correlatable, but the real identity is not recoverable from the bundle.

Redactions: file paths, entity names, author email, author name, commit messages beyond the published summary and reason, argv, environment variables, hostnames, machine identifiers, and internal ticket or PR numbers are removed. Email addresses and sign-off lines inside summary or reason are kept byte-exact in the bundle (editing them would break Ed25519 signatures) and masked at display time in the web UI. Entries with third-party PII in signed text are excluded from the bundle entirely.

How to verify

You can verify entries without installing Ledgerful.

Open the on-site verifier at /ledger and click Verify all signatures.
Open the offline verifier at /ledger/verifier.html (opens in new tab) — it works from file:// with no network.
Or use the CLI fallback: run ledgerful verify --signatures against a local repo that has the ledger bundle.

Thin signed chain head

A stable thin head artifact is published alongside the full bundle.

URL: /ledger/chain_head.json (canonical production: https://www.ledgerful.dev/ledger/chain_head.json; same shape as ledgerful export head /manifest.chainHead: latest_entry_hash, genesis, length, signature fields when signed).

Checkpoint semantics: download the public head, then compare your local workspace ledger against it. The local chain must extend or equal the published checkpoint (same genesis; hash at public length matches). That detects local rollback/rewrite relative to the published head — not “the public site proves your private product history.” Customer repos still need their own off-machine retention (operator path: export head + retain + verify --against-export).

curl -fsSL -o head.json https://www.ledgerful.dev/ledger/chain_head.json
ledgerful verify --signatures --against-export .\head.json

There is no verify --against-url (path-only by design). Compose curl + --against-export as above. No Rekor / multi-party transparency log is claimed.

Export-then-commit (no data sent anywhere)

The public ledger is generated locally with ledgerful ledger export-public, then committed into this web repository. No data is sent to a Ledgerful server. GitHub-hosted CI validates committed artifacts; it does not invent ledger history.

Publish path: on a machine that holds the engine .ledgerful state (and bot key for --sign), run ledgerful ledger export-public --output <dir> --sign or enable the helper scripts/publish-public-ledger.mjs with LEDGERFUL_PUBLISH_LEDGER_ENABLED=1. Copy artifacts into public/ledger/ (entries, manifest, README, manifest.sig/manifest.pub, chain_head.json) and open a PR. There is no engine publish-public command.

CSP dual-file verifier: production verifier.html + verifier.js are never overwritten by the publish helper (track 0075).

Publishing helper

The web publish helper ships disabled. It is opt-in only, default off.

The web helper script scripts/publish-public-ledger.mjs ships disabled. Enable it with LEDGERFUL_PUBLISH_LEDGER_ENABLED=1. It runs in your own environment (portable LEDGERFUL_ENGINE_REPO, default ../ledgerful), prefers --sign, writes chain_head.json, and by default only copies artifacts (set LEDGERFUL_PUBLISH_LEDGER_COMMIT=1 for optional auto-commit). Manifest and chain-head signatures are real when the bot key is available.

Trust model warning

Treat the public ledger as a signed sample, not a trust anchor.

manifest.pub originated from the same machine. The verifying key in this bundle came from the same environment that generated the ledger. A compromised machine could replace both the ledger data and the signing key, producing a convincing but fraudulent bundle.

Out-of-band verification required: to close that gap, the receiver must verify the public key against a trusted out-of-band copy of the Ed25519 fingerprint — for example, a key fingerprint shared over a separate secure channel, or a copy stored in a location independent of the machine that generated the bundle. Without this step, the signature proves internal consistency but not the authenticity of the signing key itself.