matrixscroll 0.4.2__tar.gz → 0.5.0__tar.gz

{matrixscroll-0.4.2 → matrixscroll-0.5.0}/CHANGELOG.md

@@ -4,6 +4,22 @@ All notable changes to the Matrix Scroll Python SDK are documented here. The
 format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
 this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.0] - 2026-07-02
+
+Post-quantum overlay (v1.1 additive extension).
+
+### Added
+- **SPEC.md §11** — optional `pqc_signatures` array (ML-DSA FIPS 204, SLH-DSA FIPS 205).
+- **`matrixscroll.pqc`** — software-only PQC overlay; Ed25519 `signature` block unchanged.
+- **`matrixscroll pqc-keygen`** — generate/load PQC keys under `~/.matrixscroll/pqc/`.
+- **`MATRIXSCROLL_PQC`** env — attach overlay on sign (e.g. `ml-dsa-65`); hardware mode exempt.
+- **Policy `require_pqc`** — `false` (default), `emulated_only`, or `true` (hardware exempt).
+- **Optional extra `[pqc]`** — `liboqs-python` backend for ML-DSA / SLH-DSA.
+
+### Unchanged
+- USB/NFC/SE050 device signing remains **Ed25519-only** (no firmware change).
+- All v1 vectors and Ed25519 verification behavior.
+
 ## [0.4.2] - 2026-06-29
 
 Crypto backend consolidation (middle path).
@@ -189,6 +205,7 @@ 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.5.0]: https://github.com/SSX360/matrixscroll/releases/tag/v0.5.0
 [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.4.2 → matrixscroll-0.5.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: matrixscroll
-Version: 0.4.2
-Summary: Signed provenance for agent-assisted Git commits with offline verification; emulated Ed25519 ships today and the SE050 hardware path remains an optional preview.
+Version: 0.5.0
+Summary: Signed provenance for agent-assisted Git commits with offline Ed25519 verification; optional ML-DSA/SLH-DSA software overlay (FIPS 204/205). USB/NFC/SE050 hardware remains Ed25519.
 Project-URL: Homepage, https://ssx360.com
 Project-URL: Documentation, https://ssx360.com/docs
 Project-URL: Repository, https://github.com/SSX360/matrixscroll
@@ -22,7 +22,7 @@ Project-URL: Public Roadmap, https://github.com/SSX360/matrixscroll/blob/main/do
 Author-email: SSX360 <security@matrixscroll.com>
 License-Expression: Apache-2.0
 License-File: LICENSE
-Keywords: ai,ed25519,matrixscroll,provenance,root-of-trust,secure-element,signing,ssx360,supply-chain
+Keywords: ai,ed25519,fips-204,fips-205,matrixscroll,ml-dsa,post-quantum,provenance,root-of-trust,secure-element,signing,slh-dsa,ssx360,supply-chain
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Information Technology
@@ -38,7 +38,7 @@ Classifier: Topic :: Security :: Cryptography
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
 Requires-Python: >=3.10
-Requires-Dist: cryptography>=42.0
+Requires-Dist: cryptography>=43.0
 Provides-Extra: dev
 Requires-Dist: build>=1.0; extra == 'dev'
 Requires-Dist: hypothesis>=6.100; extra == 'dev'
@@ -49,6 +49,8 @@ Provides-Extra: hardware
 Requires-Dist: pyserial>=3.5; extra == 'hardware'
 Provides-Extra: mcp
 Requires-Dist: mcp<2.0.0,>=1.0.0; extra == 'mcp'
+Provides-Extra: pqc
+Requires-Dist: liboqs-python>=0.12.0; extra == 'pqc'
 Provides-Extra: tpm
 Provides-Extra: yubikey
 Requires-Dist: python-pkcs11>=0.7; extra == 'yubikey'
@@ -62,19 +64,16 @@ Description-Content-Type: text/markdown
 
 **123 tests** · Hypothesis-verified security properties · [Security properties](docs/SECURITY_PROPERTIES.md)
 
-**Signed proof of who — or what — wrote every commit.** Matrix Scroll is the
-**universal provenance SDK** — open Ed25519 envelopes for Git commits, CI steps,
-IaC changes, DB migrations, API calls, and smart-contract deploys — verified
-offline in CLI, browser, and CI. Hardware (SE050) is an optional preview trust
-upgrade; emulated mode ships today.
+**Signed proof of who — or what — wrote every AI-assisted commit.** Matrix Scroll is an
+**open protocol for cryptographically signed, AI-assisted code provenance** — Ed25519 commit
+envelopes for Git (and universal action envelopes for CI, IaC, and migrations),
+verified offline in CLI, browser, and CI. Software emulated keys ship today; NXP SE050
+secure-element signing is on the roadmap with the same verifier contract.
 
-**TAM wedge (honest):** Layer 2 universal provenance SDK ($50–200M) · Layer 3 SSX360 Scroll
-governance on Git ($200M–1B) · Scroll Gate CI ($50–150M) · Python-first ML/agent
-ecosystem via `pip install matrixscroll`.
-
-**Hosted control plane:** identity, billing, and device confirmation live at
-[ssx360.com](https://ssx360.com/). Teams evaluating protected-branch enforcement should
-[book a provenance pilot](https://ssx360.com/contact?intent=pilot);
+**Hosted control plane:** identity, billing, audit ledger, and Scroll Gate live at
+[ssx360.com](https://ssx360.com/). Enterprise teams evaluating protected-branch enforcement should
+[book a provenance pilot](https://ssx360.com/contact?intent=pilot) or visit
+[ssx360.com/enterprise](https://ssx360.com/enterprise).
 Provisioned pilot and team accounts sign in at [ssx360.com/signup](https://ssx360.com/signup).
 
 ## Compliance evidence mapping
@@ -104,18 +103,18 @@ Agents sign commits in-loop via the **provenance-only** MCP server:
 ```
 
 ```bash
-pip install "matrixscroll[mcp]==0.4.2"
+pip install "matrixscroll[mcp]==0.5.0"
 matrixscroll-mcp   # stdio — register in Cursor / Claude Desktop / VS Code
 ```
 
 **MCP tools (provenance verbs only):** `create_envelope`, `sign_action`, `verify_envelope`,
 `verify_pr_range` (Scroll Gate), `publish_notes`, `status`, `audit_export`, `list_envelopes`,
-`connect_card` (SE050 preview).
+`connect_card` (SE050 hardware preview, roadmap).
 
 ## Also available — CLI & hooks
 
 ```bash
-pip install "matrixscroll==0.4.2"
+pip install "matrixscroll==0.5.0"
 matrixscroll hook-install
 export MATRIXSCROLL_ACTOR_TYPE=agent
 export MATRIXSCROLL_TOOL=agent-runner
@@ -179,12 +178,12 @@ canonical UTF-8 JSON bytes (see [`SPEC.md`](SPEC.md) §4). Verifiers reject any
 
 ## Honest limits
 
-- Shipping now: PyPI `matrixscroll==0.4.2`, Git post-commit hooks,
+- Shipping now: PyPI `matrixscroll==0.5.0`, Git post-commit hooks,
   `matrixscroll sign-action`, `matrixscroll scroll commit` (thin wrapper),
   `matrixscroll envelope-verify`, Scroll Gate PR verification (partial SLSA L1–2),
   verifier, the GitHub Action, and a USB CDC host transport preview for the
   SE050 rollout path. Emulated mode is the default evaluation path.
-- In progress: nRF52840 + SE050 firmware validation (AP2 Vault Card PoC), external Ed25519-capable
+- In progress: nRF52840 + SE050 firmware validation for hardware-backed signing, external Ed25519-capable
   hardware key backends, and transparency-log integrations.
 - Not: IAM, sandboxing, prompt filtering, or an agent runtime.
 
@@ -194,8 +193,10 @@ canonical UTF-8 JSON bytes (see [`SPEC.md`](SPEC.md) §4). Verifiers reject any
   records who or what signed the change before push.
 - Hardware keys and build attestations remain complementary roots and downstream
   proofs; Matrix Scroll covers commit-time provenance.
-- The public contract stays pure Ed25519 over canonical manifest bytes,
-  whether the signer is emulated today or hardware-backed later.
+- The public contract stays pure Ed25519 over canonical manifest bytes for the
+  required `signature` block — whether the signer is emulated today or
+  hardware-backed later. Software signers may optionally attach ML-DSA/SLH-DSA
+  overlays (FIPS 204/205) via `matrixscroll[pqc]` without changing hardware firmware.
 
 ## Common questions
 
@@ -225,7 +226,7 @@ alongside your existing scanners, branch protection, and build attestations.
 ## Quickstart (CLI)
 
 ```bash
-pip install "matrixscroll==0.4.2"
+pip install "matrixscroll==0.5.0"
 matrixscroll hook-install
 matrixscroll hook-status
 
@@ -252,7 +253,7 @@ See [`docs/quickstart-git.md`](docs/quickstart-git.md) and run
     head-ref: ${{ github.event.pull_request.head.sha }}
     base-ref: ${{ github.event.pull_request.base.sha }}
     source: notes
-    matrixscroll-version: "0.4.2"
+    matrixscroll-version: "0.5.0"
     require-mode: emulated
 ```
 
@@ -272,7 +273,7 @@ git push origin refs/notes/matrixscroll
     head-ref: ${{ github.event.pull_request.head.sha }}
     base-ref: ${{ github.event.pull_request.base.sha }}
     source: notes
-    matrixscroll-version: "0.4.2"
+    matrixscroll-version: "0.5.0"
     summary-output: provenance-summary.json
 ```
 
@@ -280,7 +281,7 @@ See [`docs/quickstart-git.md`](docs/quickstart-git.md) and
 [`examples/ci/protected-branch.yml`](examples/ci/protected-branch.yml).
 
 The `--require-mode`, `--trusted-keys`, and actor or delegation policy checks
-ship in the current release line; examples in this README pin `0.4.2`.
+ship in the current release line; examples in this README pin `0.5.0`.
 
 ## Security: Ed25519 via cryptography
 
@@ -312,13 +313,14 @@ when they preserve the same pure Ed25519 byte contract.
 - Conformance vectors: [`vectors/`](vectors/)
 - GitHub Action: <https://github.com/SSX360/matrixscroll-verify-action>
 - Agentic AI controls: [`docs/AGENTIC_AI_SECURITY.md`](docs/AGENTIC_AI_SECURITY.md)
-- Site: <https://ssx360.com/docs> (matrixscroll.com redirects here)
-- Reference device path: [AP2 Vault Card hardware](https://ssx360.com/hardware)
+- Site: <https://matrixscroll.com> · Enterprise: <https://ssx360.com/enterprise>
+- [AP2 Vault Card hardware](https://ssx360.com/hardware)
+- SE050 hardware signing: <https://ssx360.com/enterprise#roadmap>
 
 ## Python API
 
 ```bash
-pip install "matrixscroll==0.4.2"
+pip install "matrixscroll==0.5.0"
 ```
 
 ```python
@@ -428,7 +430,7 @@ The MCP server exposes **provenance verbs only**: `create_envelope`, `verify_env
 Install and register in Cursor / Claude Desktop / VS Code:
 
 ```bash
-pip install "matrixscroll[mcp]==0.4.2"
+pip install "matrixscroll[mcp]==0.5.0"
 matrixscroll-mcp   # stdio
 ```
 

{matrixscroll-0.4.2 → matrixscroll-0.5.0}/README.md

@@ -6,19 +6,16 @@
 
 **123 tests** · Hypothesis-verified security properties · [Security properties](docs/SECURITY_PROPERTIES.md)
 
-**Signed proof of who — or what — wrote every commit.** Matrix Scroll is the
-**universal provenance SDK** — open Ed25519 envelopes for Git commits, CI steps,
-IaC changes, DB migrations, API calls, and smart-contract deploys — verified
-offline in CLI, browser, and CI. Hardware (SE050) is an optional preview trust
-upgrade; emulated mode ships today.
-
-**TAM wedge (honest):** Layer 2 universal provenance SDK ($50–200M) · Layer 3 SSX360 Scroll
-governance on Git ($200M–1B) · Scroll Gate CI ($50–150M) · Python-first ML/agent
-ecosystem via `pip install matrixscroll`.
-
-**Hosted control plane:** identity, billing, and device confirmation live at
-[ssx360.com](https://ssx360.com/). Teams evaluating protected-branch enforcement should
-[book a provenance pilot](https://ssx360.com/contact?intent=pilot);
+**Signed proof of who — or what — wrote every AI-assisted commit.** Matrix Scroll is an
+**open protocol for cryptographically signed, AI-assisted code provenance** — Ed25519 commit
+envelopes for Git (and universal action envelopes for CI, IaC, and migrations),
+verified offline in CLI, browser, and CI. Software emulated keys ship today; NXP SE050
+secure-element signing is on the roadmap with the same verifier contract.
+
+**Hosted control plane:** identity, billing, audit ledger, and Scroll Gate live at
+[ssx360.com](https://ssx360.com/). Enterprise teams evaluating protected-branch enforcement should
+[book a provenance pilot](https://ssx360.com/contact?intent=pilot) or visit
+[ssx360.com/enterprise](https://ssx360.com/enterprise).
 Provisioned pilot and team accounts sign in at [ssx360.com/signup](https://ssx360.com/signup).
 
 ## Compliance evidence mapping
@@ -48,18 +45,18 @@ Agents sign commits in-loop via the **provenance-only** MCP server:
 ```
 
 ```bash
-pip install "matrixscroll[mcp]==0.4.2"
+pip install "matrixscroll[mcp]==0.5.0"
 matrixscroll-mcp   # stdio — register in Cursor / Claude Desktop / VS Code
 ```
 
 **MCP tools (provenance verbs only):** `create_envelope`, `sign_action`, `verify_envelope`,
 `verify_pr_range` (Scroll Gate), `publish_notes`, `status`, `audit_export`, `list_envelopes`,
-`connect_card` (SE050 preview).
+`connect_card` (SE050 hardware preview, roadmap).
 
 ## Also available — CLI & hooks
 
 ```bash
-pip install "matrixscroll==0.4.2"
+pip install "matrixscroll==0.5.0"
 matrixscroll hook-install
 export MATRIXSCROLL_ACTOR_TYPE=agent
 export MATRIXSCROLL_TOOL=agent-runner
@@ -123,12 +120,12 @@ canonical UTF-8 JSON bytes (see [`SPEC.md`](SPEC.md) §4). Verifiers reject any
 
 ## Honest limits
 
-- Shipping now: PyPI `matrixscroll==0.4.2`, Git post-commit hooks,
+- Shipping now: PyPI `matrixscroll==0.5.0`, Git post-commit hooks,
   `matrixscroll sign-action`, `matrixscroll scroll commit` (thin wrapper),
   `matrixscroll envelope-verify`, Scroll Gate PR verification (partial SLSA L1–2),
   verifier, the GitHub Action, and a USB CDC host transport preview for the
   SE050 rollout path. Emulated mode is the default evaluation path.
-- In progress: nRF52840 + SE050 firmware validation (AP2 Vault Card PoC), external Ed25519-capable
+- In progress: nRF52840 + SE050 firmware validation for hardware-backed signing, external Ed25519-capable
   hardware key backends, and transparency-log integrations.
 - Not: IAM, sandboxing, prompt filtering, or an agent runtime.
 
@@ -138,8 +135,10 @@ canonical UTF-8 JSON bytes (see [`SPEC.md`](SPEC.md) §4). Verifiers reject any
   records who or what signed the change before push.
 - Hardware keys and build attestations remain complementary roots and downstream
   proofs; Matrix Scroll covers commit-time provenance.
-- The public contract stays pure Ed25519 over canonical manifest bytes,
-  whether the signer is emulated today or hardware-backed later.
+- The public contract stays pure Ed25519 over canonical manifest bytes for the
+  required `signature` block — whether the signer is emulated today or
+  hardware-backed later. Software signers may optionally attach ML-DSA/SLH-DSA
+  overlays (FIPS 204/205) via `matrixscroll[pqc]` without changing hardware firmware.
 
 ## Common questions
 
@@ -169,7 +168,7 @@ alongside your existing scanners, branch protection, and build attestations.
 ## Quickstart (CLI)
 
 ```bash
-pip install "matrixscroll==0.4.2"
+pip install "matrixscroll==0.5.0"
 matrixscroll hook-install
 matrixscroll hook-status
 
@@ -196,7 +195,7 @@ See [`docs/quickstart-git.md`](docs/quickstart-git.md) and run
     head-ref: ${{ github.event.pull_request.head.sha }}
     base-ref: ${{ github.event.pull_request.base.sha }}
     source: notes
-    matrixscroll-version: "0.4.2"
+    matrixscroll-version: "0.5.0"
     require-mode: emulated
 ```
 
@@ -216,7 +215,7 @@ git push origin refs/notes/matrixscroll
     head-ref: ${{ github.event.pull_request.head.sha }}
     base-ref: ${{ github.event.pull_request.base.sha }}
     source: notes
-    matrixscroll-version: "0.4.2"
+    matrixscroll-version: "0.5.0"
     summary-output: provenance-summary.json
 ```
 
@@ -224,7 +223,7 @@ See [`docs/quickstart-git.md`](docs/quickstart-git.md) and
 [`examples/ci/protected-branch.yml`](examples/ci/protected-branch.yml).
 
 The `--require-mode`, `--trusted-keys`, and actor or delegation policy checks
-ship in the current release line; examples in this README pin `0.4.2`.
+ship in the current release line; examples in this README pin `0.5.0`.
 
 ## Security: Ed25519 via cryptography
 
@@ -256,13 +255,14 @@ when they preserve the same pure Ed25519 byte contract.
 - Conformance vectors: [`vectors/`](vectors/)
 - GitHub Action: <https://github.com/SSX360/matrixscroll-verify-action>
 - Agentic AI controls: [`docs/AGENTIC_AI_SECURITY.md`](docs/AGENTIC_AI_SECURITY.md)
-- Site: <https://ssx360.com/docs> (matrixscroll.com redirects here)
-- Reference device path: [AP2 Vault Card hardware](https://ssx360.com/hardware)
+- Site: <https://matrixscroll.com> · Enterprise: <https://ssx360.com/enterprise>
+- [AP2 Vault Card hardware](https://ssx360.com/hardware)
+- SE050 hardware signing: <https://ssx360.com/enterprise#roadmap>
 
 ## Python API
 
 ```bash
-pip install "matrixscroll==0.4.2"
+pip install "matrixscroll==0.5.0"
 ```
 
 ```python
@@ -372,7 +372,7 @@ The MCP server exposes **provenance verbs only**: `create_envelope`, `verify_env
 Install and register in Cursor / Claude Desktop / VS Code:
 
 ```bash
-pip install "matrixscroll[mcp]==0.4.2"
+pip install "matrixscroll[mcp]==0.5.0"
 matrixscroll-mcp   # stdio
 ```
 

{matrixscroll-0.4.2 → matrixscroll-0.5.0}/SPEC.md

@@ -196,3 +196,58 @@ Signed release metadata (version, tag, artifact list). JSON Schema:
 
 Signed audit or agent-scope evidence. JSON Schema:
 [`schemas/evidence-pack.v1.json`](schemas/evidence-pack.v1.json).
+
+## 11. Post-quantum overlay (v1.1 extension)
+
+Matrix Scroll v1 **requires** an Ed25519 `signature` block (§5). USB, NFC, and SE050
+hardware signers produce **only** this block today and remain unchanged.
+
+Software signers MAY attach an optional `pqc_signatures` array for FIPS 204 (ML-DSA)
+and FIPS 205 (SLH-DSA) post-quantum overlays. This is an **additive** extension;
+verifiers that do not implement PQC MUST still verify Ed25519 and MAY ignore
+`pqc_signatures`.
+
+### 11.1 PQC signature block
+
+Each element of `pqc_signatures`:
+
+```json
+{
+  "schema": "matrixscroll.pqc_signature.v1",
+  "algorithm": "ml-dsa-65",
+  "public_key": "<base64(raw public key bytes)>",
+  "value": "<base64(detached signature)>",
+  "signed_at": "<RFC 3339 UTC, informational>"
+}
+```
+
+Allowed `algorithm` values: `ml-dsa-44`, `ml-dsa-65`, `ml-dsa-87`,
+`slh-dsa-sha2-128s`, `slh-dsa-sha2-128f`.
+
+Hardware envelopes (`signature.mode` = `"hardware"`) MUST NOT include
+`pqc_signatures` until secure-element firmware supports PQC. Policy engines
+MUST exempt hardware mode from `require_pqc` rules.
+
+### 11.2 Canonical input for PQC (§4.1)
+
+PQC signing and verification remove **both** top-level keys `"signature"` and
+`"pqc_signatures"` before applying §4 encoding rules. Because Ed25519 is applied
+first, the PQC signing input is byte-identical to the Ed25519 signing input.
+
+### 11.3 Verification
+
+1. Verify Ed25519 per §6 (always required).
+2. If `pqc_signatures` is absent, stop (valid for v1-only policy).
+3. For each PQC block: validate `schema`, decode keys, verify against PQC canonical bytes.
+4. If policy requires PQC and verification fails or array is missing (non-hardware), reject.
+
+### 11.4 Policy knobs
+
+| `require_pqc` | Behavior |
+| ------------- | -------- |
+| `false` (default) | PQC optional |
+| `emulated_only` | Require valid PQC when `signature.mode` is `emulated` or `tpm` |
+| `true` | Require valid PQC for all modes except `hardware` |
+
+JSON Schema: [`schemas/pqc-signature.v1.json`](schemas/pqc-signature.v1.json),
+[`schemas/commit-envelope.v1.1.json`](schemas/commit-envelope.v1.1.json).

{matrixscroll-0.4.2 → matrixscroll-0.5.0}/docs/CRYPTO_BACKEND.md

@@ -1,8 +1,12 @@
 # Cryptographic backend (middle path)
 
-Matrix Scroll v0.4.2+ routes all Ed25519 and security-relevant SHA-256
+Matrix Scroll v0.5.0+ routes all Ed25519 and security-relevant SHA-256
 operations through a single Python module: `matrixscroll/crypto_backend.py`.
 
+Post-quantum overlays (ML-DSA FIPS 204, SLH-DSA FIPS 205) are optional and
+implemented via `matrixscroll/pqc.py` when `matrixscroll[pqc]` (liboqs-python)
+is installed. **USB/NFC/SE050 hardware signers remain Ed25519-only.**
+
 ## Design
 
 | Approach | What users install | Crypto implementation |
@@ -22,6 +26,7 @@ moving primitive work onto battle-tested native code shipped inside official
 | Ed25519 key generation | `generate_ed25519_private_key()` | `cryptography.hazmat.primitives.asymmetric.ed25519` |
 | Ed25519 sign / verify | `ed25519_sign`, `ed25519_verify` | Same |
 | SHA-256 (device IDs, gate digests, Rekor bridge) | `sha256`, `sha256_hex` | `cryptography.hazmat.primitives.hashes.SHA256` |
+| ML-DSA / SLH-DSA overlay (optional) | `pqc_sign`, `pqc_verify` | `liboqs-python` via `matrixscroll[pqc]` extra |
 
 Git object hashing (`hashlib.sha1` in `matrixscroll/git.py`) stays on the
 stdlib because it implements Git wire-format identifiers, not provenance

{matrixscroll-0.4.2 → matrixscroll-0.5.0}/docs/ROADMAP_2026-07.md

@@ -8,13 +8,13 @@ what ships now before widening the story.
 ## Baseline on June 21, 2026
 
 - GitHub: early public repo, product-first docs, and offline verification
-- Current public release: `matrixscroll==0.4.1`
+- Current public release: `matrixscroll==0.5.0`
 - Public trust contract: pure Ed25519 over canonical manifest bytes
 - Hardware path: SSX360 SE050 reference implementation in progress
 
 ## Next 7 days
 
-- Public release: `matrixscroll==0.4.1` (universal provenance + scroll commit)
+- Public release: `matrixscroll==0.5.0` (universal provenance + scroll commit)
 - make the GitHub Action a real public proof surface
 - align site, README, action docs, and PyPI around one install flow
 - remove broken links and stale release drift from public copy

{matrixscroll-0.4.2 → matrixscroll-0.5.0}/docs/SECURITY_PROPERTIES.md

@@ -1,6 +1,6 @@
 # Matrix Scroll security properties
 
-Machine-checkable guarantees for the reference SDK (v0.4.2). Properties marked
+Machine-checkable guarantees for the reference SDK (v0.5.0). Properties marked
 **verified** have Hypothesis property tests in `tests/test_security_properties.py`.
 Formal TLA+ models are on the public roadmap.
 

{matrixscroll-0.4.2 → matrixscroll-0.5.0}/docs/WHITEPAPER.md

@@ -71,7 +71,7 @@ Full wire format: [`SPEC.md`](../SPEC.md). Schema: [`schemas/commit-envelope.v1.
 ### 1. Install
 
 ```bash
-pip install "matrixscroll==0.4.1"
+pip install "matrixscroll==0.5.0"
 matrixscroll hook-install
 matrixscroll hook-status
 ```
@@ -87,7 +87,7 @@ matrixscroll envelope-verify "$(git rev-parse HEAD)"
 
 Hooks default to **warn mode**; set `"enforce": true` in `.git/matrixscroll/config.json` to block commits when signing fails. See [`docs/quickstart-git.md`](quickstart-git.md).
 
-**Windows:** support landed in matrixscroll **0.2.1**; pin **0.4.1** in pilot environments.
+**Windows:** support landed in matrixscroll **0.2.1**; pin **0.5.0** in pilot environments.
 
 ### 3. CI gate
 
@@ -95,12 +95,12 @@ Hooks default to **warn mode**; set `"enforce": true` in `.git/matrixscroll/conf
 - uses: SSX360/matrixscroll-verify-action@v1
   with:
     manifest: path/to/signed-manifest.json
-    matrixscroll-version: "0.4.1"
+    matrixscroll-version: "0.5.0"
     require-mode: emulated
     trusted-keys: trusted-keys.json
 ```
 
-Policy flags (`--require-mode`, `--trusted-keys`) ship in the current release; this whitepaper pins `0.4.1` for copy-and-paste examples.
+Policy flags (`--require-mode`, `--trusted-keys`) ship in the current release; this whitepaper pins `0.5.0` for copy-and-paste examples.
 
 ### 4. Optional scope manifest
 

{matrixscroll-0.4.2 → matrixscroll-0.5.0}/docs/commercial/SSX360_SCROLL.md

@@ -12,7 +12,7 @@ See also the platform copy in [digital-rain/docs/commercial/SSX360_SCROLL.md](ht
 ## Quick start
 
 ```bash
-pip install "matrixscroll==0.4.2"
+pip install "matrixscroll==0.5.0"
 matrixscroll hook-install
 matrixscroll scroll commit -m "feat: governed commit"
 ```

{matrixscroll-0.4.2 → matrixscroll-0.5.0}/docs/registries-guide.md

@@ -5,11 +5,18 @@ This guide details how to submit the `matrixscroll-mcp` server to all major MCP
 ---
 
 ## 1. Glama Registry
-- **Status:** Integrated via `glama.json`.
-- **How to Publish:** 
+- **Status:** Live — quality **A** on [matrixscroll Glama listing](https://glama.ai/mcp/servers/SSX360/matrixscroll) (license A, maintenance A, TDQS tool-set A as of 2026-06-29).
+- **Listing:** [matrixscroll on Glama](https://glama.ai/mcp/servers/SSX360/matrixscroll)
+- **Internal only:** Do **not** submit `digital-rain-mcp` (private SSX360 repo intelligence). If it appears on Glama from an old public scrape, email **support@glama.ai** with server id `xwxknl3sgw` and request delisting of `SSX360/digital-rain`.
+- **TDQS checklist (quality A):**
+  1. Every `@mcp.tool()` declares MCP annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`).
+  2. Tool docstrings include **when to use**, **when not to use**, sibling alternatives, side effects, and return shape.
+  3. Pydantic `Field(description=...)` on every parameter (Glama introspection reads `tools/list` JSON Schema).
+  4. CI guard: `tests/test_mcp_server.py::MCPToolDefinitionTests` asserts ≥80% schema description coverage.
+- **How to publish / re-sync:**
   1. Log in to [Glama.ai](https://glama.ai/mcp).
-  2. Sync your repository `https://github.com/SSX360/matrixscroll`.
-  3. Glama will automatically parse `glama.json` and score the tools (our tight, attestation-focused tool docstrings will secure an **A** grade).
+  2. Sync repository `https://github.com/SSX360/matrixscroll` (auto on push; manual sync if stale).
+  3. Confirm per-tool TDQS ≥ B and server quality **A** on the listing page.
 
 ## 2. Official MCP Registry (Model Context Protocol)
 - **Status:** Ready for submission.

matrixscroll-0.5.0/matrixscroll/canonical.py

@@ -0,0 +1,38 @@
+"""Deterministic canonical JSON encoding for Matrix Scroll manifests."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+_SIGNATURE_KEYS = frozenset({"signature", "pqc_signatures"})
+
+
+def _canonical_body(payload: dict[str, Any], *, exclude_pqc: bool) -> dict[str, Any]:
+    if exclude_pqc:
+        return {k: v for k, v in payload.items() if k not in _SIGNATURE_KEYS}
+    return {k: v for k, v in payload.items() if k != "signature"}
+
+
+def _encode(body: dict[str, Any]) -> bytes:
+    return json.dumps(
+        body,
+        sort_keys=True,
+        ensure_ascii=True,
+        allow_nan=False,
+        separators=(",", ":"),
+    ).encode("utf-8")
+
+
+def canonical_bytes(payload: dict[str, Any]) -> bytes:
+    """Return deterministic signing bytes per SPEC.md section 4 (Ed25519 v1).
+
+    Excludes ``signature`` and optional ``pqc_signatures`` so Ed25519 verification
+    stays valid after a v1.1 PQC overlay is attached.
+    """
+    return _encode(_canonical_body(payload, exclude_pqc=True))
+
+
+def canonical_bytes_pqc(payload: dict[str, Any]) -> bytes:
+    """Return signing bytes for PQC overlay (§11) — excludes signature and pqc_signatures."""
+    return _encode(_canonical_body(payload, exclude_pqc=True))