[{"data":1,"prerenderedAt":4},["ShallowReactive",2],{"xVBUeAlmvd":3},"# LeanSha256\n\n> [!IMPORTANT]\n> **Issues and pull requests belong in the\n> [`etheorem` monorepo](https://github.com/etheorem/etheorem), not\n> here.** `LeanSha256` is developed inside the umbrella repo under\n> `packages/LeanSha256/`; this repository is a **read-only\n> subtree mirror** regenerated on every push to the umbrella's\n> `main`. Issues filed here, and pull requests opened against this\n> repo's branches, will not be acted on. Please redirect them to\n> the umbrella. Any direct pushes to this repo's `main` are\n> overwritten by the next mirror run.\n>\n> The mirror exists so the package is independently discoverable\n> on [Reservoir](https://reservoir.lean-lang.org) (which indexes\n> repository roots, not monorepo subdirectories). The umbrella\n> remains the single source of truth.\n\n## Where to file issues / contribute\n\n→ **[github.com/etheorem/etheorem](https://github.com/etheorem/etheorem)**\n(the monorepo). Look under `packages/LeanSha256/` for this\nlibrary's source; the umbrella's `CLAUDE.md` documents the\nproject-wide conventions.\n\n---\n\nA pure-Lean SHA-256 reference implementation. Two functions in the\npublic surface (`hash` and `combine`); NIST CAVP-validated against\nthe FIPS 180-4 published vectors; kernel-reducible (no FFI, no\nopaque calls, no SSZ coupling) so kernel `decide` closes goals about\nit without trusting the compiler.\n\n## Status\n\nStable. NIST CAVP byte-oriented short-message and long-message\ntest suites pass via build-time `native_decide` gates inside\n`LeanSha256Tests/Nist.lean`. At version `0.1.0`, the two-function\npublic API is intended to remain stable; internal modules under\n`LeanSha256.Core` (round functions, message schedule, helper\nlemmas) may evolve.\n\n## Dependencies\n\nNone. Pure Lean 4 + the standard library. No `mathlib`, no\n`batteries`, no native shims.\n\n## Modules\n\n* `LeanSha256.Core`: the SHA-256 algorithm (initial state, message\n  schedule, compression function, padding, multi-block driver).\n  Kernel-reducible.\n* `LeanSha256Tests.Nist`: NIST CAVP byte-oriented test vectors as\n  `native_decide` gates over `LeanSha256.Core`. Lives in the\n  separate `LeanSha256Tests` library so the ~108 s build cost is\n  opt-in.\n\n## Public API\n\n```lean\nnamespace LeanSha256\n\n/-- Single SHA-256 digest. Equivalent to FIPS 180-4 §6.2. -/\ndef hash    : ByteArray → ByteArray\n\n/-- Sibling combine: `hash (a ++ b)`. Exported separately because\n    Merkle-tree consumers (e.g. SSZ `hash_tree_root`) call it on the\n    hot path and want a direct, allocation-free entry point. -/\ndef combine : ByteArray → ByteArray → ByteArray\n\nend LeanSha256\n```\n\nBoth functions are total, structurally terminating, and return a\n32-byte `ByteArray`. The `Core` module also exposes a handful of\nstructural conformance lemmas (e.g. that `hash` agrees with a\nsingle-block compression on inputs ≤ 55 bytes). See its module\ndocstring for the full list.\n\n## Trust assumptions\n\n* Kernel-reducible: every definition reduces in Lean's trusted\n  kernel. Closing a goal with `decide` against `LeanSha256.hash`\n  adds **no** compiler-trust axiom, only Lean's core kernel is\n  trusted.\n* For speed, consumers normally close hash-equality goals with\n  `native_decide`, which trusts the Lean compiler via\n  `Lean.ofReduceBool`. The full `LeanSha256Tests` library\n  (`LeanSha256Tests.Nist`) does this. See its `#axioms` output.\n* No `sorry`, no `axiom` declarations, no FFI calls anywhere in\n  the library.\n\n## Build / test\n\n```bash\n# From the umbrella repo root:\nlake build LeanSha256\n# (3 anchor FIPS 180-4 §B gates fire at build time via\n# native_decide inside LeanSha256.Core; if any case regresses,\n# the build fails.)\n\n# Full NIST CAVP byte-oriented suite — 129 short-message +\n# long-message cases via native_decide, ~108 s. The `Justfile`\n# at the umbrella root wraps this:\njust leansha256-test\n# …which is exactly `lake build LeanSha256Tests`.\n\n# Or from this subpackage's directory:\ncd packages/LeanSha256 && lake build\n```\n\nThe CAVP vector files (`SHA256ShortMsg.rsp`, `SHA256LongMsg.rsp`,\n`SHA256Monte.rsp`) live under `cavp/` in this subpackage and are\nthe upstream NIST artefacts unmodified. A stranger can verify\nthe byte-for-byte match against the\n[NIST CSRC CAVP archive](https://csrc.nist.gov/projects/cryptographic-algorithm-validation-program/secure-hashing).\n\nTo regenerate `LeanSha256Tests/Nist.lean` after refreshing the\n`.rsp` files, run the in-package script (or its umbrella wrapper):\n\n```bash\npython3 packages/LeanSha256/scripts/gen_sha256_cavp.py\n# or, from the umbrella root:\njust leansha256-gen-cavp\n```\n\n## Requiring this package\n\n`LeanSha256` is published as a standalone Lake package at\n[`etheorem/LeanSha256`](https://github.com/etheorem/LeanSha256) (a\nsubtree mirror of `packages/LeanSha256/` from the\n[`etheorem` umbrella repo](https://github.com/etheorem/etheorem)).\nDownstream Lake projects can require it directly:\n\n```toml\n[[require]]\nname = \"LeanSha256\"\ngit = \"https://github.com/etheorem/LeanSha256\"\nrev = \"v0.1.0\"  # pin to a release tag or a specific commit sha\n```\n\nThe mirror exposes `vX.Y.Z` tags for each release. The umbrella's\nown release tags use a `leansha256-vX.Y.Z` prefix; the mirror\nworkflow strips the prefix.\n\nEither form (mirror or umbrella) can also be required by `subDir`\nif you want the package directly from the monorepo source, useful\nduring development. For general consumption the mirror is the\ncanonical address:\n\n```toml\n# Source the package from the monorepo (for development / debugging):\n[[require]]\nname = \"LeanSha256\"\ngit = \"https://github.com/etheorem/etheorem\"\nsubDir = \"packages/LeanSha256\"\nrev = \"\u003Ccommit-sha>\"\n```\n\n**From a local copy, via path** (vendoring or `git submodule`):\n\n```toml\n[[require]]\nname = \"LeanSha256\"\npath = \"vendor/LeanSha256\"\n```\n\nThen run `lake update` to refresh `lake-manifest.json`. Per the\numbrella's [`CLAUDE.md`](../../CLAUDE.md) dependency policy,\nprefer pinning `rev` to a specific commit hash or release tag over\ntracking a branch.\n\n## Licence\n\nLGPL-3.0-only. The package ships a local copy of the licence text\nat `LICENSE`, pinned from the umbrella repo's root `LICENSE`. The\nmirror workflow refreshes the local copy on every push to keep it\nin sync.\n",1784670031369]