sanning-proof 0.4.0__tar.gz

sanning_proof-0.4.0/.github/workflows/ci.yml

@@ -0,0 +1,73 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: pip install -e .[dev]
+      - name: Format check
+        run: black --check src tests
+      - name: Conformance + unit tests
+        run: pytest -q
+
+  ts:
+    # The TypeScript kernel (ts/) — same conformance gate as the Python kernel,
+    # against the one authoritative test-vectors/ corpus. SHA-pinned actions
+    # per this repo's supply-chain discipline.
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: ts
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: "24"
+      - run: npm ci
+      - name: Build (dist ESM + declarations — the publishable shape)
+        run: npm run build
+      - name: Typecheck
+        run: npm run typecheck
+      - name: Conformance + verifier tests (vectors byte-for-byte)
+        run: npm test
+
+  cross-kernel:
+    # Python ⇄ TS ⇄ Go agreement gate over the corpus + adversarial cases
+    # (cross-kernel/). The three kernels must return identical verdicts on
+    # identical bytes. Python+TS always run; the Go leg builds sanning-io/agent
+    # pkg/proof at cross-kernel/PIN when the agent source is fetchable, and
+    # SKIPS loudly otherwise (public PRs without private-repo access).
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        with:
+          python-version: "3.13"
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: "24"
+      - uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6.4.0
+        with:
+          go-version: "1.25.0"
+      - name: Install Python kernel + node deps
+        run: |
+          pip install -e .[dev]
+          (cd ts && npm ci)
+      - name: Cross-kernel agreement (Python + TS + Go)
+        # Go leg builds the VENDORED sanning-io/agent pkg/proof (cross-kernel/
+        # vendor-agent, pinned in cross-kernel/PIN) — no private-repo access,
+        # so all three legs run on public and fork PRs.
+        run: bash cross-kernel/run.sh

sanning_proof-0.4.0/.github/workflows/release-ts.yml

@@ -0,0 +1,71 @@
+# Publishes ts/ (@sanning/proof) to npm via OIDC trusted publishing — no
+# long-lived npm tokens anywhere (the npm mirror of this repo's PyPI
+# Trusted-Publishing flow in release.yml). This repo is PUBLIC, so npm
+# provenance works from day one: --provenance is ON.
+#
+# npmjs.com side (one-time, package settings for @sanning/proof →
+# "Trusted Publisher" → GitHub Actions):
+#   organization: sanning-io
+#   repository:   proof
+#   workflow:     release-ts.yml         (filename must match exactly)
+#   environment:  (leave blank)
+#
+# Real publish: push a `ts-vX.Y.Z` tag whose version matches ts/package.json
+# (the guard step enforces it).
+# Dry-run: workflow_dispatch — runs the ENTIRE path including
+# `npm publish --dry-run`. Lesson from the v1.2.0 cosign failure: a dry-run
+# that skips the publish step validates nothing.
+#
+# Tag namespace: ts-v* (TS). Does not overlap v* (Python, release.yml) or
+# test-vectors-v* (corpus).
+
+name: release-ts
+
+on:
+  push:
+    tags: ['ts-v*.*.*']
+  workflow_dispatch: # full dry-run: build, test, pack — publishes nothing
+
+permissions:
+  contents: read
+  id-token: write # npm OIDC trusted publishing
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: ts
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: '24'
+          registry-url: 'https://registry.npmjs.org'
+      - name: Pin npm to a trusted-publishing-capable version
+        # OIDC trusted publishing needs npm >= 11.5.1; Node images float their
+        # bundled npm. Floor it explicitly (a floating tool default broke the
+        # first v1.2.0 release cut — don't repeat that with npm).
+        run: |
+          npm install -g npm@^11.5.1
+          npm --version
+      - run: npm ci
+      - name: Build (exports point at dist/)
+        run: npm run build
+      - run: npm run typecheck
+      - name: Conformance + verifier tests (vectors byte-for-byte)
+        run: npm test
+      - name: Tag ↔ package version guard
+        if: github.event_name == 'push'
+        run: |
+          PKG="$(node -p "require('./package.json').version")"
+          TAG="${GITHUB_REF_NAME#ts-v}"
+          if [ "$PKG" != "$TAG" ]; then
+            echo "::error::tag ts-v${TAG} does not match ts/package.json version ${PKG}"
+            exit 1
+          fi
+      - name: Publish to npm (dry-run on dispatch)
+        # --provenance ON: this repo is public, so npm provenance attests the
+        # build from source. On workflow_dispatch this runs --dry-run (packs +
+        # validates, publishes nothing); on a ts-v* tag push it publishes.
+        run: npm publish --provenance --access public ${{ github.event_name == 'workflow_dispatch' && '--dry-run' || '' }}

sanning_proof-0.4.0/.github/workflows/release.yml

@@ -0,0 +1,45 @@
+name: release
+
+# Publishes to PyPI via Trusted Publishing (OIDC) — no token secrets.
+# Trigger: a maintainer pushes a v* tag (e.g. `git tag v0.1.0 && git push origin v0.1.0`).
+# One-time setup on pypi.org: add a "pending publisher" for project sanning-proof
+# with owner=sanning-io, repo=proof, workflow=release.yml, environment=pypi.
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        with:
+          python-version: "3.12"
+      - name: Run the conformance gate before anything ships
+        run: |
+          pip install -e .[dev]
+          black --check src tests
+          pytest -q
+      - name: Build sdist + wheel
+        run: |
+          pip install build
+          python -m build
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2

sanning_proof-0.4.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+dist/
+build/
+.pytest_cache/
+
+# TS kernel (ts/)
+node_modules/
+*.tsbuildinfo

sanning_proof-0.4.0/CHANGELOG.md

@@ -0,0 +1,108 @@
+# Changelog — `sanning-proof` (Python kernel)
+
+All notable changes to the Python verification kernel. Format loosely follows
+[Keep a Changelog](https://keepachangelog.com/); this project is pre-1.0, so
+minor versions may include behavior changes.
+
+## [Unreleased]
+
+### Added
+
+- **Cross-kernel accept-set agreement.** The tri-kernel gate now probes the
+  accepted-`spec_version` registry itself: `cross-kernel/accept-set.json`
+  transcribes the ratified accept-set (envelope-spec §4 registry + §5
+  accepted-majors discipline) and `cross-kernel/generate_cases.py` builds one
+  correctly signed probe per identifier, in the profile's registered binding
+  mode, plus the profile-conditional signed-scope dialects (32 → 48 cases).
+  Until now every case in the set carried `sanning.agent/v1` or
+  `sanning.events/v1`, so three kernels could hold three different registries
+  and the gate stayed green. Each of the three registries is additionally held
+  to the declaration by **set equality**, because a verdict probe can only
+  disagree about identifiers someone declared — a kernel admitting a profile
+  nobody wrote down has no probe to fail: `tests/test_accept_set.py` for the
+  Python `ACCEPTED_SPEC_VERSIONS`, `ts/test/accept-set.test.ts` for the TS
+  `ACCEPTED_SPEC_MAJORS`, and `cross-kernel/go-verifier/accept_set.go` for Go's
+  `SupportedSpecMajor` (inside the gate, since Go has no unit-test leg here).
+  No kernel behavior changes: the registry's contents are untouched.
+
+### Known gaps
+
+- **`sanning.mlflow/v1` admission is divergent and escalated, not fixed.** The
+  ratified accept-set is `{ sanning.agent/v1, sanning.mlflow/v1,
+  sanning.events/v1 }` (§5, amendment A5 — "in all three kernels"); the Python
+  kernel carries all three, while TS `ACCEPTED_SPEC_MAJORS` and Go
+  `SupportedSpecMajor` carry two. A second divergence sits behind it: TS and Go
+  do not implement the mlflow profile's underscore-annotation signed-scope
+  strip, so an `_tx_id`-carrying envelope would split the verdict even once the
+  identifier is admitted. Both are quarantined in `accept-set.json` and asserted
+  in both directions (the divergence must persist unchanged; resolving it fails
+  the gate until the row is deleted). Widening a kernel's accept-set changes
+  which envelopes are admitted — a founder decision, not a kernel edit.
+
+## [0.4.0] — 2026-08-05
+
+First release of the Python verification kernel under this name, carrying the
+July 2026 security fixes.
+
+### Security
+
+Merged to `main` during the July 2026 adversarial pass; **this is the first
+release that publishes them.** Both are normative cross-kernel invariants — the
+TypeScript kernel carries the identical guards.
+
+- **RSA public-exponent guard (`sanning_proof.rsa_pss`).** `verify_rsa_pss_sha256`
+  now rejects any operator key whose public exponent is not `65537`
+  (`RSA_PUBLIC_EXPONENT`), returning `False` — a **FAILED** attestation, exit 1 —
+  rather than delegating the decision to the crypto library. The operator-address
+  binding is `base64url(SHA-256(n))`, which commits to the **modulus alone**; with
+  `e = 1`, RSA verification degenerates to the identity function, so anyone holding
+  a public modulus could forge an attestation that binds to the legitimate
+  operator's address without ever holding the private key. A malformed `e`
+  (unparseable or empty) still routes to `MalformedRsaError` → exit 2, so
+  "forged" and "garbage" stay distinguishable.
+- **Canonicalization depth bound (`sanning_proof.canonicalize`).**
+  `MAX_CANONICAL_DEPTH = 128`, enforced by an **iterative** (never recursive)
+  `exceeds_depth` walk that runs *before* canonicalization on already-parsed,
+  possibly hostile input. Container nesting past the bound raises
+  `CanonicalDepthError`, bucketed as **malformed** (exit 2), not as a failed
+  verification. Without it, an attacker-chosen nesting depth splits the verdict
+  across kernels — bytes one kernel canonicalizes on a large native stack and
+  another rejects with `RecursionError` — which is a verdict-integrity break, not
+  merely a crash.
+
+### Changed
+
+- **Family namespace.** Every family
+  wire string moves namespace with the MAJOR unchanged at `v1` (a new namespace,
+  not a new revision): `sanning.agent/v1`, `sanning.mlflow/v1`, `sanning.events/v1`
+  (`ACCEPTED_SPEC_VERSIONS`), `sanning.evidence/v1` (`ACCEPTED_EVIDENCE_MAJORS`),
+  `sanning.anchor.trace/v1` and `sanning.evidence.export/v1` (`body_type`),
+  `sanning.evidence.verdict/v1` (`VERDICT_SCHEMA_VERSION`), and
+  `sanning.agent.proof/v1` (`BUNDLE_SPEC_VERSION`). Envelopes and bundles emitted
+  outside the accept-set do not verify.
+- **BREAKING — conformance corpus re-cut to `test-vectors-v2.0`.** Every vector was
+  regenerated under the migrated namespace, so all signatures, Merkle leaves, roots
+  and audit paths were re-derived; the manifest moved `CORPUS-v1.md` → `CORPUS-v2.md`
+  and the profile directory is `sanning.events-v1/`. A byte change
+  to existing vectors is a **major** cut per `specs/governance.md` §4; the 30-day RFC
+  was waived by founder call (recorded in §7). **41 manifest rows, up from 39** — the
+  two `evidence-export/negatives/` files (the RSA `e=1` exponent forgery and the
+  canonicalization-depth bundle) were never pinned in any manifest and are now listed.
+  A `v1.x` pin cannot be upgraded in place; downstreams re-pin deliberately.
+- The `e=1` attestation-forgery negative gained a generator
+  (`tools/gen-vectors/gen_exponent_forgery_vector.py`), closing the CORP1 violation it
+  carried since the July security pass. It asserts on every run that raw `e=1` RSA
+  verification *accepts* the forged signature, so the vector cannot decay into one that
+  fails for an unrelated reason while the exponent guard stops being exercised.
+
+### Known gaps
+
+- The vendored Go leg (`cross-kernel/vendor-agent/` @ `cross-kernel/PIN`) still carries
+  the pre-migration accept-set, so `cross-kernel/run.sh`'s Go leg is expected-red until
+  the `agent` repo migrates. The Python⇄TS legs (including the byte-identical export
+  verdict gate) are green.
+- Both gaps clear **after** this release, not before it: `sanning-io/anchor` can only
+  re-cut the golden bundle once it depends on a published `@sanning/proof`, and the Go
+  leg needs the `agent` migration. Neither blocks 0.4.0 — re-cutting the fixture locally
+  to make the skips green would destroy the cross-repo emit↔verify guarantee the fixture
+  exists to hold.

sanning_proof-0.4.0/CLAUDE.md

@@ -0,0 +1,116 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this is
+
+`sanning-io/proof` — the **polyglot verification home** of the Sanning evidence plane: the family
+specs (`specs/`), the one authoritative conformance corpus (`test-vectors/`), and two conformant
+kernels that reproduce it byte-for-byte:
+
+- **Python** (`sanning_proof`, repo root) — extracted from the MLflow plugin's proof engine; this is
+  the kernel most of this CLAUDE.md is about.
+- **TypeScript** (`@sanning/proof`, [`ts/`](ts/)) — moved here 2026-06-11 from the browser verifier
+  app (an app never owns a kernel — same principle that extracted the Python kernel from mlflow).
+
+Both implement exactly the five kernel primitives from
+[`specs/architecture.md`](specs/architecture.md) §3: RFC 8785 (JCS) canonicalization, SHA-256, Ed25519
+sign/verify, RFC 9162 binary Merkle (incl. inclusion-proof bundles), and the
+accepted-`spec_version` registry. **No I/O, no networking, no key lifecycle** — those belong to
+producers (`agent`, `mlflow`), not the kernel. The Go reference stays MIT-carved in
+`agent/pkg/proof` (sanning-io).
+
+### Working in the TS kernel (`ts/`)
+
+Standalone npm package, separate from the Python tooling:
+
+```bash
+cd ts && npm ci
+npm run build        # tsc -p tsconfig.build.json → dist/ (ESM + .d.ts; the published shape)
+npm run typecheck    # tsc --noEmit
+npm test             # vitest — conformance vs ../test-vectors (the same corpus), byte-for-byte
+```
+
+CI runs a dedicated `ts` job (`ci.yml`). Releases go through `release-ts.yml` (npm OIDC trusted
+publishing, provenance on, tags `ts-v*` — distinct from Python's `v*` / `release.yml`). Source
+relative imports MUST carry explicit `.js` extensions (Node-ESM requirement; `moduleResolution:
+bundler` won't add them — this bit `0.1.1`, fixed in `0.1.2`). Kernel changes are spec-layer
+changes: byte-for-byte conformance is the gate, and the Python and Go kernels must stay in
+lockstep (escalate divergences per `specs/governance.md` §6).
+
+**Bundle verify + the CLI live HERE, not in `@ar.io/anchor`** (the kernel is the producer-neutral
+verifier — an auditor must not need the write SDK). `src/evidence.ts` = `verifyEvidenceBundle`
+(signed `sanning.evidence/v1` / `sanning.anchor.trace/v1` bundles); `src/agent-proof.ts` =
+`verifyAgentProofBundle` (`sanning.agent.proof/v1`); `src/cli.ts` = the `bin: proof` →
+`npx @sanning/proof verify <bundle> [gateways]` (sniffs `spec_version`, so one verb covers anchor +
+agent; pinned exit codes `0/1/2/3`). Bundle *emit* (`toEvidenceBundle`) lives in `@ar.io/anchor`.
+Implemented on `main`; the `bin` ships on the next `ts-v*` tag. Cross-repo round-trip is pinned by
+`ts/test/fixtures/anchor-trace-bundle.golden.json` (a real @ar.io/anchor bundle, frozen).
+
+## Commands
+
+```bash
+python3 -m venv .venv && .venv/bin/pip install -e .[dev]   # one-time setup
+.venv/bin/pytest -q                                        # all tests (conformance is the contract)
+.venv/bin/pytest tests/test_conformance.py -q              # corpus gate only
+.venv/bin/black src tests                                  # format (CI runs black --check)
+```
+
+## The conformance contract
+
+`test-vectors/` is the authoritative home of the family conformance corpus (the current
+cut is the DL-22 `sanning.*` re-cut declared in `CORPUS-v2.md` — a MAJOR cut per
+`specs/governance.md` §4, tagged **`test-vectors-v2.0`** → commit `3a9ccf5`.
+Regeneration is an ordered ceremony: see `test-vectors/README.md`. Provenance:
+`test-vectors/VENDORING.md`; downstreams like `agent` (sanning-io) vendor byte-for-byte
+from here). `tests/test_conformance.py`
+asserts, for every vector: SHA-256 corpus integrity against the CORPUS-v2.md table, JCS-canonical
+payload bytes, `payload_hash`, envelope-for-signature bytes, deterministic Ed25519 signatures, and
+Merkle roots / audit paths. **If the kernel disagrees with a vector, the kernel is wrong — never
+the vector.** Never edit vector files; re-sync only at a published corpus tag per
+`VENDORING.md`.
+
+## Spec pins (do not drift)
+
+- `envelope-spec.md` **v1.3 (ratified v1.0 2026-06-10, amended through 2026-06-15 — additive,
+  no wire change)** — the family contract. Ratified accept-set (§4 registry + §5): `sanning.agent/v1`
+  (inline payload), `sanning.mlflow/v1` (external commitment), `sanning.events/v1` (external
+  commitment, Minimal disclosure). Fail-closed on unknown majors. **The kernels do not all
+  implement that set today:** `sanning.mlflow/v1` is carried by the Python kernel only — the TS
+  (`ACCEPTED_SPEC_MAJORS`) and Go (`SupportedSpecMajor`) registries omit it, as does their
+  signed-scope handling of the mlflow `_*` annotation dialect. That gap is an **escalated
+  divergence**, pinned by the cross-kernel gate and awaiting a founder admission decision — see
+  [`cross-kernel/README.md`](cross-kernel/README.md) § Known divergences and
+  [`cross-kernel/accept-set.json`](cross-kernel/accept-set.json). Do not close it with a one-line
+  registry edit: widening an accept-set changes which envelopes verify.
+- Signed scope = the envelope minus **`signature`**, minus the reserved **`co_signatures`**
+  (envelope-spec §7.1), and — **profile-conditional** — minus underscore-prefixed annotation
+  keys for `sanning.mlflow/v1` + legacy envelopes ONLY (mlflow convention, e.g. `_tx_id`). The
+  `sanning.agent/v1` and `sanning.events/v1` scopes are minus-signature/co_signatures only, matching
+  Go: an injected `_*` key on an agent or events envelope MUST fail verification. The corpus can
+  catch neither the co_signatures strip nor the profile-conditionality — unit tests in
+  `tests/test_envelope.py`
+  are the only guard; do not remove them because conformance still passes without them.
+- Merkle: RFC 9162 §2.1 domain separation (`0x00` leaf / `0x01` node), empty-tree root =
+  `SHA-256("")`. Never the Bitcoin duplicate-last-leaf variant.
+- Ed25519 is strict RFC 8032 (libsodium via PyNaCl) — matches Go `crypto/ed25519` and the JS
+  sibling's `zip215: false`.
+
+## Working rules
+
+- Verifiers must never raise on adversarial input — malformed envelopes return a failed
+  `VerificationResult`, they don't throw.
+- Each commit lands one primitive, CI-green, with tests in the same commit.
+- Dependencies are pinned to two load-bearing packages: `PyNaCl` and `jcs`. Adding a dependency
+  is a design decision, not a convenience.
+- Source siblings for cross-checks (read-only): Go reference `agent/pkg/{proof,merkle}` (sanning-io),
+  origin kernel `mlflow` (sanning-io).
+
+## Release
+
+`release.yml` publishes to PyPI via Trusted Publishing (OIDC) on a `v*` tag pushed by a
+maintainer. Version lives in `pyproject.toml` + `src/sanning_proof/__init__.py`; bump both together.
+The TS kernel is a **third** version site — `ts/package.json`, released separately by a `ts-v*`
+tag through `release-ts.yml`. All three move in lockstep; a bump in one and not the others is the
+classic release-day failure, and neither Python workflow guards it (`release.yml` has no
+tag↔version check — PyPI publishes whatever `pyproject.toml` says).

sanning_proof-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sanning Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sanning_proof-0.4.0/PKG-INFO

@@ -0,0 +1,202 @@
+Metadata-Version: 2.5
+Name: sanning-proof
+Version: 0.4.0
+Summary: Verification kernel for the Sanning verification stack: RFC 8785 canonicalization, SHA-256, Ed25519 envelope sign/verify, RFC 9162 Merkle inclusion proofs, and RSA-PSS attested-evidence-export verification.
+Project-URL: Repository, https://github.com/sanning-io/proof
+Project-URL: Issues, https://github.com/sanning-io/proof/issues
+Author: Sanning Inc.
+License: MIT License
+        
+        Copyright (c) 2026 Sanning Inc.
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: arweave,ed25519,jcs,merkle,provenance,rfc8785,rfc9162,sanning,verification
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: >=3.10
+Requires-Dist: cryptography>=41.0.0
+Requires-Dist: jcs>=0.2.1
+Requires-Dist: pynacl>=1.5.0
+Provides-Extra: dev
+Requires-Dist: black>=24.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Sanning Proof
+
+Offline verification for the [Sanning](https://console.sanning.io) evidence plane: standalone, dependency-light verification kernels in **Python** and **TypeScript**, plus the ratified specs and the conformance corpus both kernels are gated against, byte for byte. No network, no accounts, no vendor code in the trust path — anyone can check a piece of anchored evidence with nothing but this package.
+
+- **Python** — `sanning_proof` (PyPI: [`sanning-proof`](https://pypi.org/project/sanning-proof/)), at the repo root.
+- **TypeScript** — [`@sanning/proof`](https://www.npmjs.com/package/@sanning/proof) (npm), in [`ts/`](ts/) — browser + Node ≥ 20, ESM.
+
+Verify a signed envelope fetched from any Arweave gateway:
+
+```python
+import json
+import urllib.request
+
+from sanning_proof import verify_envelope
+
+raw = urllib.request.urlopen("https://arweave.net/raw/<tx_id>").read()
+result = verify_envelope(json.loads(raw))
+
+assert result.ok            # spec_version + payload binding + Ed25519 signature
+```
+
+```ts
+import { verifyEnvelope } from "@sanning/proof";
+
+const env = await (await fetch("https://arweave.net/raw/<tx_id>")).json();
+const result = await verifyEnvelope(env);
+result.ok; // spec_version + payload binding + Ed25519 signature
+```
+
+> [!NOTE]
+> Verification never needs an account or a server. If you are *producing* evidence — anchoring agent steps, running a fleet under continuous tamper-evidence — the hosted plane is [console.sanning.io](https://console.sanning.io) and the write SDK is [`@sanning/anchor`](https://github.com/sanning-io/anchor).
+
+## Install
+
+```bash
+pip install sanning-proof        # Python
+npm install @sanning/proof       # TypeScript
+```
+
+## What a verdict proves — and what it doesn't
+
+`result.ok` proves exactly this: *the holder of the private key matching the envelope's `public_key` signed exactly these bytes, and the payload binding holds.*
+
+It deliberately does **not** prove:
+
+- **Whose key that is.** The key ↔ identity binding comes from out of band — for example an enrollment roster. The kernel checks cryptography, not identity.
+- **That the envelope is on-chain.** Fetch the transaction from a gateway yourself and re-verify — which is exactly what the example above does.
+- **When it happened.** `signed_at` is the signer's claim; witnessed time comes from the Arweave block the envelope landed in.
+- **What the raw data was.** Envelopes are content-blind: they commit to hashes. Raw bytes never pass through this kernel unless the producer explicitly disclosed them alongside the proof.
+
+For a verification tool, the guarantee boundary is the product — a verifier that overclaims is worse than no verifier at all.
+
+## Verify more things
+
+**Bind an artifact you hold** to the provenance an envelope commits to (reverse lookup):
+
+```python
+import hashlib
+
+artifact_hash = hashlib.sha256(open("model.pkl", "rb").read()).hexdigest()
+result = verify_envelope(envelope, expected_content_hash=artifact_hash)
+print(result.content_hash_ok, result.content_role)   # True, "asset"
+```
+
+**Verify an external-commitment envelope** (`sanning.mlflow/v1`) against the committed bytes:
+
+```python
+result = verify_envelope(envelope, payload_bytes=canonical_bytes)
+```
+
+**Verify an inclusion-proof bundle** — proves a leaf event was in a signed checkpoint:
+
+```python
+from sanning_proof import verify_proof_bundle
+
+bundle = json.load(open("proof-bundle.json"))
+result = verify_proof_bundle(bundle)
+assert result.ok and result.inclusion_ok
+```
+
+The TypeScript kernel has full parity, including the RFC 9162 Merkle primitives (`leafHash` / `merkleRoot` / `auditPath` / `verifyInclusion`) — see [`ts/README.md`](ts/README.md).
+
+## The CLI
+
+The TypeScript package ships a turnkey CLI. Pinned exit codes — `0` verified · `1` failed · `2` malformed · `3` gateway-unavailable — safe to gate CI on.
+
+**Verify** any evidence or agent-proof bundle, fully offline; optionally re-fetch checkpoints on-chain by passing gateways:
+
+```bash
+npx @sanning/proof verify <bundle.json> [gateway1,gateway2,...] [--logs <logs.json>]
+```
+
+`--logs` binds disclosed raw logs to their committed hashes (evidence bundles only).
+
+**Compose an attested export** — turn a source trace bundle plus operator attestation records into one signed, offline-verifiable `sanning.evidence/v1` bundle that verifies like any other:
+
+```bash
+npx @sanning/proof export <source-bundle.json> --attestations <att.json> --key <exporter.hex> -o export.json
+npx @sanning/proof verify export.json
+```
+
+Programmatic equivalent: `composeExport(sourceBundle, attestations, { privateKey })`. Full format: [`specs/evidence-export.md`](specs/evidence-export.md).
+
+## Signing (producers)
+
+Most producers never call the kernel directly — the write SDK ([`@sanning/anchor`](https://github.com/sanning-io/anchor)), the agent daemon, and the MLflow plugin all sign through it. For a custom producer:
+
+```python
+from sanning_proof import sign_envelope, signing_key_from_seed_hex
+
+key = signing_key_from_seed_hex("<32-byte seed hex>")
+envelope = sign_envelope({...}, key)   # the envelope minus `signature`, per the spec
+```
+
+## The standard
+
+This repo is the authoritative home of the evidence plane's **standards layer** — the contract is public alongside the reference verifiers:
+
+- [`specs/envelope-spec.md`](specs/envelope-spec.md) — the producer-neutral **Verifiable Event Envelope** family contract (ratified v1.0, amended through **v1.4**, 2026-07-15).
+- [`specs/evidence-bundle.md`](specs/evidence-bundle.md) — the `sanning.evidence/v1` report wrapper.
+- [`specs/evidence-export.md`](specs/evidence-export.md) — the attested-export format behind `proof export`.
+- [`specs/architecture.md`](specs/architecture.md) — the kernel / producer / connector / transport factoring standard.
+- [`specs/governance.md`](specs/governance.md) — who decides, and how.
+- [`test-vectors/`](test-vectors/) — the conformance corpus (current cut: tag **`test-vectors-v2.0`**, per-file SHA-256 in [`CORPUS-v2.md`](test-vectors/CORPUS-v2.md)); generated by [`tools/gen-vectors/`](tools/gen-vectors/), never hand-edited.
+
+Three envelope **profiles** are registered against the family contract: `sanning.agent/v1` (the agent daemon's inline-payload profile), `sanning.mlflow/v1` (the MLflow plugin's external-commitment profile), and `sanning.events/v1` (the anchor SDK's minimal-disclosure profile). The Python kernel accepts all three; the TypeScript kernel accepts `sanning.agent/v1` and `sanning.events/v1` (the mlflow dialect is Python-only). Additive minors are accepted within a major; unknown majors and malformed versions fail closed.
+
+**Conformance discipline:** both kernels reproduce the corpus byte for byte — JCS-canonical bytes, payload hashes, envelope-for-signature bytes, deterministic signatures, Merkle roots, audit paths. If this package disagrees with a vector, the package is wrong — never the vector.
+
+## Kernel scope
+
+The kernel is deliberately small: canonicalization (RFC 8785), SHA-256 hashing, Ed25519 sign/verify, RFC 9162 binary Merkle inclusion proofs, and the profile registry — **no I/O, no networking, no key lifecycle**. Gateway fetching, attestation polling, and key storage belong to the products that import it. Dependencies are deliberately minimal: Python has exactly two ([`PyNaCl`](https://pypi.org/project/PyNaCl/), [`jcs`](https://pypi.org/project/jcs/)); TypeScript has exactly two ([`@noble/ed25519`](https://www.npmjs.com/package/@noble/ed25519), [`canonicalize`](https://www.npmjs.com/package/canonicalize)).
+
+## Development
+
+```bash
+python3 -m venv .venv && .venv/bin/pip install -e .[dev]
+.venv/bin/pytest -q          # the conformance gate is the contract
+.venv/bin/black src tests
+```
+
+The TypeScript kernel lives in [`ts/`](ts/) and is conformance-gated in CI against the same `test-vectors/` directory.
+
+## Contributing
+
+Issues and pull requests are welcome. If you believe a kernel disagrees with a spec or a corpus vector, open an issue titled `contract conflict: <spec> §<section>` with the smallest reproduction — see [`specs/governance.md`](specs/governance.md) §6.
+
+## Security
+
+Please report vulnerabilities privately via GitHub Security Advisories ("Report a vulnerability" under this repo's Security tab) and do **not** open a public issue.
+
+## License
+
+[MIT](LICENSE). The verifier is deliberately open-licensed so anyone can audit it and verify evidence independently of Sanning.