matrixscroll 0.6.4__tar.gz → 0.9.0__tar.gz

{matrixscroll-0.6.4 → matrixscroll-0.9.0}/.gitignore

@@ -18,6 +18,7 @@ htmlcov/
 .tox/
 .mypy_cache/
 .ruff_cache/
+onboarding-smoke-summary*.json
 
 # Virtual envs
 .venv/
@@ -45,9 +46,15 @@ credentials/
 .cursor/
 .playwright-cli/
 
+# Local operational data (workbench / envelopes)
+data/
+
 # Matrix Scroll local store (never commit a private key)
 .matrixscroll/
 device.json
+session.secret
+credentials.once.txt
+workbench.sqlite3
 
 # TLA+ tools (download locally or in CI)
 tla2tools.jar
@@ -65,3 +72,6 @@ site/
 .vale/styles/write-good/
 .vale/styles/ai-tells/
 .vale/styles/ai-tells-commits/
+
+.mcp-resign-home/
+

{matrixscroll-0.6.4 → matrixscroll-0.9.0}/CHANGELOG.md

@@ -6,6 +6,178 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+## [0.9.0] - 2026-09-13
+
+Device-agnostic custody and CNSA 2.0 Category 5 sealed evidence packs. The USB/SE050
+signing path is removed from the public SDK; historical `signature.mode=hardware`
+envelopes still verify.
+
+### Removed
+- **`matrixscroll[hardware]`**, `HardwareProvider`, USB CDC SE050 transport, MCP
+  `connect_card`, SE050 acceptance vectors, and USB-first documentation. Setting
+  `MATRIXSCROLL_MODE=hardware` raises `IdentityError` with migration guidance.
+- Product visualizations and protocol docs that described a single USB signer as the
+  custody path.
+
+### Added
+- **Sealed evidence packs** (`matrixscroll.sealed`, schema
+  `matrixscroll.sealed-evidence-pack.v1`): hybrid X25519 + ML-KEM-1024 key agreement,
+  AES-256-GCM body, Ed25519 + ML-DSA-87 signatures. Requires `matrixscroll[pqc]`.
+  Parameter-set readiness through liboqs; not a CNSA certification or FIPS validation.
+- Device-agnostic custody documentation: implement `IdentityProvider` for any device
+  or HSM; default remains the file-backed `emulated` provider.
+
+### Changed
+- MCP stdio server is **13 tools** (was 14). Version pins, action default, and
+  public docs target **0.9.0**.
+- CRYPTO_ROADMAP sealed-pack step marked shipping for 0.9.0.
+
+## [0.8.0] - 2026-09-12
+
+Default post-quantum signature set moves to the CNSA 2.0 parameter set. No
+wire-format change; Ed25519 remains the default signature scheme and the
+post-quantum overlay remains opt-in through `MATRIXSCROLL_PQC`.
+
+### Changed
+- **Default PQC algorithm is now `ml-dsa-87`.** When you run
+  `matrixscroll pqc-keygen` without `--algorithm`, and when a library caller
+  invokes `load_pqc_keypair` or `attach_pqc_overlay` without an algorithm while
+  `MATRIXSCROLL_PQC` is unset, the SDK selects ML-DSA-87 (FIPS 204 Category 5).
+  That matches the CNSA 2.0 signature parameter set. Git commit envelopes and
+  `sign_manifest_with_pqc` attach the overlay only when you enable it:
+  `MATRIXSCROLL_PQC` names the set (`MATRIXSCROLL_PQC=ml-dsa-87`) or the caller
+  passes `pqc_algorithm`; `0`, `false`, `off` and `no` disable it, and an unset
+  variable leaves the manifest Ed25519-only. `matrixscroll sign`, the MCP
+  `sign_action` tool and `sign_mcp_manifest` remain Ed25519-only, as in 0.7.0;
+  the MCP `create_envelope` tool signs Git envelopes through
+  `sign_manifest_with_pqc`. It is parameter-set readiness through liboqs, not
+  CNSA certification, FIPS CMVP validation, or NSA approval.
+  Callers can still pass `ml-dsa-44` or `ml-dsa-65` explicitly. Existing key
+  files under `~/.matrixscroll/pqc/` are unchanged; a new default only affects
+  newly generated keys. `0.7.0` and earlier default to `ml-dsa-65`. Status of
+  each algorithm (shipping now, in progress, not planned) is the table in
+  `docs/CRYPTO_ROADMAP.md`.
+- The public README and documentation now lead with the offline verification
+  outcome, use explicit verification-boundary sections, and reserve signer
+  implementation detail for qualified setup.
+- **Documentation refreshed against the standards status of 12 September 2026.**
+  `docs/CRYPTO_ROADMAP.md` gains a policy-dates table (CNSSP-15 and the CNSA 2.0
+  FAQ v2.1, Executive Order 14412 and OMB M-26-15, the Department of War PQC
+  strategy, the NIST IR 8547 draft) and rows for FIPS 206, ML-KEM, LMS/XMSS and
+  the ACVP tests; `docs/COMPARISON.md` gains a dated landscape section (Sigstore,
+  GitHub attestations, gittuf, forge commit signing, MCP scanners, 2025-2026
+  agent-receipt projects) and a list of claims Matrix Scroll does not make. The
+  README and the documentation home open with the SSX360 USB signer render
+  (`docs/images/ssx360-usb-signer.jpg`, replaced) and the signer section shows
+  the sign round-trip sequence.
+
+### Added
+- **`slh-dsa-sha2-256s` and `slh-dsa-sha2-256f`** in the allowed PQC algorithm
+  list (FIPS 205 Category 5 hash-based options), schema, and CLI choices.
+- **NIST ACVP vectors** for the overlay: `vectors/acvp-sigver-fips204-fips205.json`
+  carries a subset of the ACVP-Server sample vectors for ML-DSA-87,
+  SLH-DSA-SHA2-256s and SLH-DSA-SHA2-256f (external interface, pure variant):
+  sigVer cases with the NIST tcIds, verdicts and reason strings, and sigGen
+  expected signatures over an empty context restated as positive cases. The
+  provenance block records the URL and SHA-256 of each source file. This is an
+  evidence mapping to NIST sample vectors, not a certification claim
+  (`docs/CRYPTO_ROADMAP.md`).
+- **`tests/test_acvp_sigver.py`** verifies the NIST-valid empty-context
+  signatures through `pqc_verify`, verifies and rejects the context-string
+  cases through liboqs's `verify_with_ctx_str` on the same mechanism the
+  overlay uses, and treats a wrong-length signature as invalid without calling
+  the verifier; the provenance check runs without liboqs.
+- **`tests/test_pqc.py`** signs, verifies and rejects a tampered signature for
+  every identifier in `PQC_ALGORITHMS`, and checks that a key file naming a set
+  the build does not enable fails through `IdentityError`.
+- **`tools/independent_verify.py`**, a second implementation of the verifier
+  written from SPEC.md alone: its own canonical serializer, a pure-Python
+  RFC 8032 Ed25519, the device-id derivation and the section 6 procedure, with
+  no import from the SDK (the section 11 overlay is checked when liboqs is
+  present). `tests/test_independent_verifier.py` holds it against the SDK on
+  every committed vector, on 500 random documents and on fresh signatures; the
+  README's "Ten-minute check for reviewers" names the commands.
+- **`matrixscroll.kem`** (CNSA 2.0 full-suite track, in progress): ML-KEM-1024
+  and ML-KEM-768 key generation, encapsulation and decapsulation through liboqs,
+  with deterministic key generation from the FIPS 203 seed. No envelope or
+  export format uses the module yet; `docs/CRYPTO_ROADMAP.md` names the sealed
+  evidence-pack design that will. `vectors/acvp-mlkem-fips203.json` and
+  `tests/test_acvp_mlkem.py` check it against the NIST ACVP sample vectors
+  (keyGen, decapsulation of NIST ciphertexts, implicit rejection of modified
+  ciphertexts); evidence mapping, not a certification claim.
+- **`CNSA_PREFERRED_PQC_ALGORITHM`** constant (`ml-dsa-87`) for policy and docs
+  that need a named CNSA 2.0 signature target without hard-coding the string.
+- **`docs/CRYPTO_ROADMAP.md`** CNSA 2.0 shipping / in progress / not table.
+
+### Fixed
+- **SLH-DSA identifiers now resolve against liboqs.** The overlay mapped the
+  `slh-dsa-*` identifiers to mechanism names liboqs does not expose
+  (`SLH-DSA-SHA2-256s`), so every SLH-DSA key generation, signature and
+  verification raised `MechanismNotSupportedError` on liboqs 0.16. The backend
+  now resolves each identifier against `oqs.get_enabled_sig_mechanisms()`
+  (`SLH_DSA_PURE_SHA2_256S` on liboqs 0.13 and later, the hyphenated spelling as
+  a fallback) and reports an unsupported set as `IdentityError` with the liboqs
+  version. ML-DSA was unaffected.
+- **`pqc_available()` no longer flips to true on the second call.** The probe
+  cached its negative result as an empty string and returned it unchanged on
+  later calls, so any second query reported the backend as present without
+  liboqs installed and the next signing call failed with a raw import error
+  instead of `IdentityError`. Found by the new tests, which query the probe
+  from two modules.
+
+## [0.7.0] - 2026-08-11
+
+Fail-closed verification, package completeness, and public positioning. No
+wire-format change.
+
+### Added
+- Range verification results now report agent-scope details and the formal model
+  includes the default-path invariant `Inv_EmptyRangeFailsClosed`.
+- Added `schemas/ssx360.evidence-pack.v1.json` for the document written by the
+  evidence-pack exporter.
+- Added a hardware-signed SE050 acceptance vector with CLI and CI verification.
+- You can explicitly set the composite action's `allow-empty-range` input. It
+  remains disabled by default and cannot satisfy a signature-mode requirement.
+
+### Changed
+- Empty commit ranges now return `ok: false` by default. CLI and Python callers
+  that intentionally accept an empty range must opt in explicitly. MCP callers
+  use the same explicit opt-in and fail closed by default.
+- Documentation now describes the shipped 14-tool MCP server and completed USB
+  signer directly, without retired pricing tiers or level-based product gates.
+- Development, documentation, and GitHub Action dependencies were refreshed.
+- Public package metadata now describes signed machine-action records instead
+  of leading with AI terminology. Exact schema terms such as `actor_type: agent`
+  remain unchanged.
+
+### Fixed
+- **The verify action could hand a caller a blank `ok` when the verifier
+  crashed.** It now writes all eight outputs on every path, masks captured
+  verifier output in the job summary, and distinguishes tool failures from
+  legitimate verification failures. Parser and action-step tests cover crashes,
+  silent output, malformed JSON, and signature failures.
+- Unhandled CLI exceptions now return structured JSON with exit status 1 instead
+  of leaking a traceback into automation output.
+- Evidence-pack annotations no longer mutate signed hosted response bodies.
+- JSON schemas now ship in wheels and MCP schema resources resolve the installed
+  copies.
+- The MCP extra now requires the verified 1.28+ SDK line; earlier 1.x releases
+  cannot register the server's annotated tools, and MCP 2.0 removed the
+  `mcp.server.fastmcp` API entirely.
+- You receive an explicit rejection when a hosted MCP Git range is empty, before
+  any API call. Non-empty ranges send the resolved commit SHAs.
+- Hosted CLI checks now write `--summary-output` on successful and empty-range
+  responses, matching local checks.
+- Local evidence-pack documents without a `bundle` now fail schema validation,
+  and CI verifies all eight schemas from an isolated wheel installation.
+
+### Removed
+- **Breaking:** removed `matrixscroll claim`, `matrixscroll identity`, the
+  `--identity` verification flag, and their private paid-enrollment client. The
+  retired service no longer issues identity certificates; device identity
+  remains the local Ed25519 key pair reported by `matrixscroll status`.
+- Removed the retired platform-pricing and signup guide.
+
 ## [0.6.4] - 2026-08-11
 
 Documentation and release metadata. No wire-format change.
@@ -334,6 +506,9 @@ Initial public release. Extracted from the SSX360 reference implementation.
 - Device id format: `MS-XXXX-XXXX` (SHA-256 of the raw public key, first 8 hex
   chars, uppercase).
 
+[0.9.0]: https://github.com/SSX360/matrixscroll/releases/tag/v0.9.0
+[0.8.0]: https://github.com/SSX360/matrixscroll/releases/tag/v0.8.0
+[0.7.0]: https://github.com/SSX360/matrixscroll/releases/tag/v0.7.0
 [0.6.4]: https://github.com/SSX360/matrixscroll/releases/tag/v0.6.4
 [0.6.3]: https://github.com/SSX360/matrixscroll/releases/tag/v0.6.3
 [0.6.2]: https://github.com/SSX360/matrixscroll/releases/tag/v0.6.2
@@ -341,6 +516,12 @@ Initial public release. Extracted from the SSX360 reference implementation.
 [0.6.0]: https://github.com/SSX360/matrixscroll/releases/tag/v0.6.0
 [0.5.1]: https://github.com/SSX360/matrixscroll/releases/tag/v0.5.1
 [0.5.0]: https://github.com/SSX360/matrixscroll/releases/tag/v0.5.0
+[0.4.2]: https://github.com/SSX360/matrixscroll/releases/tag/v0.4.2
+[0.4.1]: https://github.com/SSX360/matrixscroll/releases/tag/v0.4.1
+[0.3.0]: https://github.com/SSX360/matrixscroll/releases/tag/v0.3.0
+[0.2.6]: https://github.com/SSX360/matrixscroll/releases/tag/v0.2.6
+[0.2.5]: https://github.com/SSX360/matrixscroll/releases/tag/v0.2.5
+[0.2.4]: https://github.com/SSX360/matrixscroll/releases/tag/v0.2.4
 [0.2.2]: https://github.com/SSX360/matrixscroll/releases/tag/v0.2.2
 [0.2.1]: https://github.com/SSX360/matrixscroll/releases/tag/v0.2.1
 [0.2.0]: https://github.com/SSX360/matrixscroll/releases/tag/v0.2.0

matrixscroll-0.9.0/PKG-INFO

@@ -0,0 +1,267 @@
+Metadata-Version: 2.5
+Name: matrixscroll
+Version: 0.9.0
+Summary: MCP server for signed machine-action records, offline tool-surface checks, with device-agnostic custody and CNSA 2.0 Category 5 crypto (ML-DSA-87, ML-KEM-1024).
+Project-URL: Homepage, https://matrixscroll.com
+Project-URL: Documentation, https://github.com/SSX360/matrixscroll/tree/main/docs
+Project-URL: Specification, https://github.com/SSX360/matrixscroll/blob/main/SPEC.md
+Project-URL: Verifier, https://matrixscroll.com/#verify-offline
+Project-URL: Repository, https://github.com/SSX360/matrixscroll
+Project-URL: Source, https://github.com/SSX360/matrixscroll
+Project-URL: Issues, https://github.com/SSX360/matrixscroll/issues
+Project-URL: Whitepaper, https://github.com/SSX360/matrixscroll/blob/main/docs/WHITEPAPER.md
+Project-URL: Changelog, https://github.com/SSX360/matrixscroll/blob/main/CHANGELOG.md
+Project-URL: Discussions, https://github.com/SSX360/matrixscroll/discussions
+Project-URL: Security, https://github.com/SSX360/matrixscroll/blob/main/SECURITY.md
+Project-URL: GitHub Action, https://github.com/SSX360/matrixscroll/tree/main/.github/actions/verify
+Project-URL: Tests, https://github.com/SSX360/matrixscroll/tree/main/tests
+Project-URL: Public Roadmap, https://github.com/SSX360/matrixscroll/blob/main/docs/ROADMAP_2026-07.md
+Project-URL: Crypto Roadmap, https://github.com/SSX360/matrixscroll/blob/main/docs/CRYPTO_ROADMAP.md
+Project-URL: Maintainer, https://ssx360.com/about
+Author-email: SSX360 <security@matrixscroll.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: authorization,ed25519,fips-204,fips-205,machine-action,matrixscroll,ml-dsa,ml-kem,post-quantum,provenance,root-of-trust,signing,slh-dsa,ssx360,supply-chain
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: cryptography>=43.0
+Provides-Extra: dev
+Requires-Dist: build>=1.5.0; extra == 'dev'
+Requires-Dist: hypothesis>=6.165.2; extra == 'dev'
+Requires-Dist: jsonschema>=4.23.0; extra == 'dev'
+Requires-Dist: pytest-cov>=7.1.0; extra == 'dev'
+Requires-Dist: pytest>=9.1.1; extra == 'dev'
+Requires-Dist: pyyaml>=6.0.3; extra == 'dev'
+Provides-Extra: git
+Provides-Extra: mcp
+Requires-Dist: mcp<2.0.0,>=1.28.0; extra == 'mcp'
+Provides-Extra: pqc
+Requires-Dist: liboqs-python>=0.16.0; extra == 'pqc'
+Provides-Extra: tpm
+Provides-Extra: yubikey
+Requires-Dist: python-pkcs11>=0.9.5; extra == 'yubikey'
+Description-Content-Type: text/markdown
+
+# Matrix Scroll
+
+Signed machine-action records with offline verification for MCP, Git, and CI.
+
+[![ci-unit](https://github.com/SSX360/matrixscroll/actions/workflows/ci-unit.yml/badge.svg)](https://github.com/SSX360/matrixscroll/actions/workflows/ci-unit.yml)
+[![PyPI](https://img.shields.io/pypi/v/matrixscroll)](https://pypi.org/project/matrixscroll/)
+[![Python](https://img.shields.io/pypi/pyversions/matrixscroll)](https://pypi.org/project/matrixscroll/)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/SSX360/matrixscroll/blob/main/LICENSE)
+
+An MCP server can change its tool descriptions or input schemas after installation. A Git commit can also declare an actor or tool without carrying a signed authorization record. Matrix Scroll records both surfaces as Ed25519-signed evidence that reviewers can verify offline, with an optional ML-DSA-87 post-quantum overlay and ML-KEM-1024 sealed evidence packs on the CNSA 2.0 Category 5 track.
+
+The `matrixscroll-mcp` stdio server exposes 13 tools for commit envelopes, action records, pull-request checks, Git notes, MCP surface manifests, and agent traces. Custody is device-agnostic: the default is a file-backed software provider, and any device or HSM plugs in through the `IdentityProvider` seam. Local signing and verification need no cloud account.
+
+Matrix Scroll is an open protocol. The Python SDK is Apache-2.0 software, and the specification and vectors are CC0 1.0.
+
+## Contents
+
+- [Install the MCP server](#install-the-mcp-server)
+- [MCP tools](#mcp-tools)
+- [Detect MCP tool-surface changes](#detect-mcp-tool-surface-changes)
+- [Device-agnostic custody](#device-agnostic-custody)
+- [Sign and verify from the CLI](#sign-and-verify-from-the-cli)
+- [Verification boundaries](#verification-boundaries)
+- [Verify the release](#verify-the-release)
+- [Ten-minute check for reviewers](#ten-minute-check-for-reviewers)
+- [Security and license](#security-and-license)
+
+## Install the MCP server
+
+Install the current release from PyPI:
+
+```bash
+pip install "matrixscroll[mcp]==0.9.0"
+```
+
+Register the stdio server in your MCP client:
+
+```json
+{
+  "mcpServers": {
+    "matrixscroll": {
+      "command": "matrixscroll-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+On Windows, use the full path to `matrixscroll-mcp.exe` inside the active virtual environment if the command is not on `PATH`.
+
+Start the executable directly when you want to inspect the server over stdio:
+
+```bash
+matrixscroll-mcp
+```
+
+After your client connects, call `status`. The server reports the local identity, hook state, and envelope count.
+
+## MCP tools
+
+The `0.9.0` server exposes these tools:
+
+| Tool | What it does | Network or write behavior |
+| --- | --- | --- |
+| `status` | Reports local identity, hook state, and envelope count | Read-only and local |
+| `create_envelope` | Creates an Ed25519-signed Git commit envelope | Writes a local envelope by default |
+| `verify_envelope` | Verifies one signed envelope and its policy fields | Read-only and local |
+| `sign_action` | Signs provenance for CI, infrastructure changes, migrations, API calls, or other actions | Writes only when `save_path` is set |
+| `verify_pr_range` | Checks every commit in a Git range | Local for `local`, `notes`, or `bundle`. Hosted mode requires an API key |
+| `publish_notes` | Publishes local envelopes to `refs/notes/matrixscroll` | Writes local Git notes |
+| `audit_export` | Exports evidence for review | Writes a local bundle or uses the hosted API when configured |
+| `list_envelopes` | Lists organization envelopes | Requires `SSX360_API_KEY` and the hosted API |
+| `scan_mcp_server` | Fingerprints MCP tool names, descriptions, and input schemas | Read-only when tools are supplied |
+| `sign_mcp_manifest` | Signs an MCP tool-surface manifest | Writes only when `save_path` is set |
+| `verify_mcp_manifest` | Verifies a manifest and compares it with a signed baseline | Read-only and local |
+| `sign_agent_trace` | Signs a browser-agent JSONL trace | Writes a signed envelope |
+| `verify_agent_trace` | Verifies a signed trace and optionally checks the source bytes | Read-only and local |
+
+An API key is optional. Local signing, offline verification, and MCP manifest checks do not require one. Hosted organization history and hosted range verification use `SSX360_API_KEY`.
+
+## Detect MCP tool-surface changes
+
+Matrix Scroll records an MCP server's tool names, descriptions, and input schemas in a signed manifest. Re-scan the server after an update and compare it with the install-time baseline.
+
+```bash
+pip install "matrixscroll[mcp]==0.9.0"
+
+matrixscroll mcp scan \
+  --connect stdio \
+  --server-command "npx -y some-mcp-server" \
+  --output manifest.json \
+  --pretty
+
+matrixscroll mcp sign manifest.json \
+  --output baseline.signed.json
+
+matrixscroll mcp scan \
+  --connect stdio \
+  --server-command "npx -y some-mcp-server" \
+  --output current.json
+
+matrixscroll mcp sign current.json \
+  --output current.signed.json
+
+matrixscroll mcp verify current.signed.json \
+  --baseline baseline.signed.json \
+  --pretty
+```
+
+The verify command exits with code `2` when the signature is invalid or the current tool surface differs from the signed baseline. You can also scan an exported `tools/list` response without starting a server:
+
+```bash
+matrixscroll mcp scan --tools tools.json --output manifest.json --pretty
+```
+
+## Device-agnostic custody
+
+Signing goes through an `IdentityProvider` (`public_key_bytes`, `sign`, `mode`). The default `emulated` provider stores an Ed25519 key under `~/.matrixscroll`. To adapt Matrix Scroll to any device or HSM, implement that interface and select it with `MATRIXSCROLL_MODE` (or pass a provider instance to the library APIs). Experimental `tpm` and `yubikey` previews remain available; they are not the Category 5 story and do not claim hardware ML-DSA.
+
+Historical envelopes with `signature.mode` equal to `"hardware"` still verify. The USB/SE050 signing path was removed in 0.9.0; `MATRIXSCROLL_MODE=hardware` raises instead of opening a serial port.
+
+Sealed evidence packs (`matrixscroll.sealed`) encrypt a payload to a recipient's ML-KEM-1024 key with a hybrid X25519 + ML-KEM-1024 agreement, AES-256-GCM for the body, and Ed25519 plus ML-DSA-87 signatures over the pack. Install `matrixscroll[pqc]`. This is parameter-set readiness through liboqs, not a CNSA certification or FIPS validation.
+
+## Sign and verify from the CLI
+
+The Python package includes a CLI and Git hooks for workflows that do not use MCP.
+
+```bash
+pip install "matrixscroll==0.9.0"
+matrixscroll hook-install
+
+export MATRIXSCROLL_ACTOR_TYPE=ci
+export MATRIXSCROLL_TOOL=release-runner
+git commit -m "feat: automate release"
+
+matrixscroll envelope-verify "$(git rev-parse HEAD)"
+```
+
+Sign a JSON manifest directly:
+
+```bash
+matrixscroll sign release.json > release.signed.json
+matrixscroll verify release.signed.json
+```
+
+`matrixscroll verify` exits with code `0` for a valid signature and code `2` for invalid input, a failed signature, a mismatched device identity, or an unsupported schema or algorithm.
+
+## Verification boundaries
+
+<!-- vale ai-tells.ShipOveruse = NO -->
+
+- Release: PyPI `matrixscroll==0.9.0` installs the 13-tool stdio MCP server and Git hooks, the MCP Trust Scanner, offline verification, sealed evidence packs, and device-agnostic custody.
+- Hosted tools: `list_envelopes` and the hosted modes of `verify_pr_range` and `audit_export` require `SSX360_API_KEY` and a deployed SSX360 API. Local signing and verification remain available without a key.
+- Post-quantum evaluation path: the optional `matrixscroll[pqc]` extra provides ML-DSA and SLH-DSA through liboqs, including Category 5 sets (`ml-dsa-87`, `slh-dsa-sha2-256s`/`256f`). Release `0.9.0` defaults new software keys to `ml-dsa-87` for CNSA 2.0 signature-parameter alignment (`0.7.0` and earlier default to `ml-dsa-65`; pass `--algorithm` or `MATRIXSCROLL_PQC` to choose a set explicitly). That is parameter-set readiness, not CNSA certification, FIPS CMVP validation, or NSA approval. This module has no CMVP validation. liboqs states that applications should not rely on it to protect sensitive data in production.
+- CNSA 2.0 full-suite track: `matrixscroll.kem` provides ML-KEM-1024 primitives (ACVP-checked). Sealed evidence packs in `matrixscroll.sealed` use hybrid X25519 + ML-KEM-1024 with Ed25519 + ML-DSA-87. Same boundary as the signature overlay: evidence mapping against NIST vectors, not a validation. See `docs/CRYPTO_ROADMAP.md`.
+- Verification scope: an Ed25519 signature proves that the signed bytes match and correspond to the included public key. A trusted-key and authorization policy establishes whether the declared `actor_type` can perform the action.
+- Adjacent controls: identity and access management, sandboxing, prompt filtering, and agent runtime policy remain separate controls.
+
+<!-- vale ai-tells.ShipOveruse = YES -->
+
+## Verify the release
+
+GitHub Actions publishes each Matrix Scroll release through PyPI Trusted Publishing. PyPI records a PEP 740 attestation for the wheel and source distribution.
+
+Ask PyPI for the `0.9.0` wheel provenance:
+
+```bash
+curl -H "Accept: application/vnd.pypi.integrity.v1+json" \
+  https://pypi.org/integrity/matrixscroll/0.9.0/matrixscroll-0.9.0-py3-none-any.whl/provenance
+```
+
+The response names the GitHub publisher:
+
+```json
+{
+  "kind": "GitHub",
+  "repository": "SSX360/matrixscroll",
+  "workflow": "publish.yml",
+  "environment": "pypi"
+}
+```
+
+Compare the attested `subject[].digest.sha256` value with the SHA-256 digest of the file you downloaded. Stop if the repository, workflow, or digest differs.
+
+## Ten-minute check for reviewers
+
+Five questions a programme manager or auditor asks first, each with the command that answers it. Everything below runs offline from a clone of this repository with `pip install "matrixscroll[pqc]==0.9.0"` (the `pqc` extra is needed only for the last two lines of question 3).
+
+1. **Does it run in one command, offline?** `matrixscroll verify vectors/valid_simple.json` prints `"ok": true` and exits `0`; `matrixscroll verify vectors/tampered_field.json` prints `"ok": false` and exits `2`. Neither command opens a network connection. Exit codes are fixed in [docs/reference/exit-codes.md](https://github.com/SSX360/matrixscroll/blob/main/docs/reference/exit-codes.md).
+2. **Is there a second implementation of the verifier?** `python tools/independent_verify.py vectors/` re-implements SPEC.md sections 3 to 6 from the text, with its own canonical serializer and a pure-Python RFC 8032 Ed25519, and imports nothing from the SDK. It must reach the same verdict as the SDK on every committed vector and on 500 randomly generated documents; `tests/test_independent_verifier.py` enforces that in CI on every change.
+3. **Are the vectors committed?** `vectors/valid_*.json`, `tampered_*.json` and `unsigned_*.json` are the conformance set (CC0 1.0); `vectors/acvp-sigver-fips204-fips205.json` and `vectors/acvp-mlkem-fips203.json` are NIST ACVP sample vectors with source URLs and SHA-256 digests. `python -m pytest tests/test_vectors.py tests/test_independent_verifier.py -q` runs the conformance set; `python -m pytest tests/test_acvp_sigver.py tests/test_acvp_mlkem.py -q` runs the NIST vectors through liboqs.
+4. **Is the boundary stated?** [Verification boundaries](#verification-boundaries) above, [docs/CRYPTO_ROADMAP.md](https://github.com/SSX360/matrixscroll/blob/main/docs/CRYPTO_ROADMAP.md) (Shipping now / In progress / Not, with policy dates) and [docs/COMPARISON.md](https://github.com/SSX360/matrixscroll/blob/main/docs/COMPARISON.md) (a dated landscape and the claims Matrix Scroll does not make). Compliance language everywhere is evidence mapping, not a certification claim.
+5. **Are the design rules checked by a model checker?** `formal/tla/` holds TLA+ models of the canonical bytes, the dual signature and the Scroll Gate range rules; `.github/workflows/formal-verify.yml` runs TLC on all seven configurations on every change to them. The models check the design, not the Python implementation; the tests above check the implementation. [docs/WHITEPAPER.md](https://github.com/SSX360/matrixscroll/blob/main/docs/WHITEPAPER.md) is the written account of the protocol.
+
+## Security and license
+
+Read the [security policy](https://github.com/SSX360/matrixscroll/blob/main/SECURITY.md) and [security properties](https://github.com/SSX360/matrixscroll/blob/main/docs/SECURITY_PROPERTIES.md). Report vulnerabilities privately to `security@matrixscroll.com` or through a GitHub Security Advisory.
+
+Matrix Scroll code is licensed under Apache-2.0. [`SPEC.md`](https://github.com/SSX360/matrixscroll/blob/main/SPEC.md) and [`vectors/`](https://github.com/SSX360/matrixscroll/tree/main/vectors/) are released under CC0 1.0.
+
+| Resource | Link |
+| --- | --- |
+| Tombstone / schemas | [matrixscroll.com](https://matrixscroll.com/) |
+| Documentation | [GitHub docs](https://github.com/SSX360/matrixscroll/tree/main/docs) |
+| Where Matrix Scroll fits (dated comparison) | [docs/COMPARISON.md](https://github.com/SSX360/matrixscroll/blob/main/docs/COMPARISON.md) |
+| Cryptographic roadmap (Ed25519, ML-DSA-87 overlay, policy dates) | [docs/CRYPTO_ROADMAP.md](https://github.com/SSX360/matrixscroll/blob/main/docs/CRYPTO_ROADMAP.md) |
+| Offline verification | [CLI guide](https://github.com/SSX360/matrixscroll#sign-and-verify-from-the-cli) |
+| Protocol specification | [SPEC.md](https://github.com/SSX360/matrixscroll/blob/main/SPEC.md) |
+| Source repository | [github.com/SSX360/matrixscroll](https://github.com/SSX360/matrixscroll) |
+| SSX360 contact | [Contact SSX360](https://ssx360.com/contact) |