# Matrix Scroll

An open protocol for signed machine-action authorization records.

Matrix Scroll is the free Apache-2.0 Python SDK for portable, offline-verifiable Ed25519 records of machine actions. Release 0.7.0 includes commit envelopes, CI verification, a 14-tool MCP stdio server, MCP tool-surface baselines, and USB CDC support for the SSX360 signer. Local signing and verification require no account.

matrixscroll.com is the package's front door. The site carries the specification, a short install page, the browser verifier and the MCP scanner. The install is `pip install "matrixscroll==0.7.0"`.

Category: non-human identity (NHI) and machine identity provenance. The protocol
binds a declared actor and tool to a specific change and signs that declaration
with Ed25519. What a verifier establishes is that the declaration came from the
holder of the key and has not been altered since. It does not establish that the
declaration is true, and it does not detect authorship on its own. State it that
way: the envelope records and signs a claim about identity, it does not prove
identity.

Cryptography (state precisely, do not upgrade):
- Ed25519 (RFC 8032), deterministic PureEdDSA. Canonical bytes per JCS RFC 8785.
- Optional post-quantum overlay, shipping since 0.6.0 behind the `pqc` extra (liboqs):
  ML-DSA-44/65/87 (algorithms specified in FIPS 204) and SLH-DSA-SHA2-128s/128f
  (FIPS 205). Default ML-DSA-65. Attached alongside the Ed25519 signature, never
  replacing it.
- This implements those algorithms; it is NOT a CMVP-validated cryptographic
  module. Never describe it as FIPS validated, FIPS certified or FIPS compliant.
- Hardware signers are Ed25519 only. The post-quantum overlay
  cannot be attached to a hardware-signed envelope.
- SSX360 has completed and produces the USB signer. Physical
  units are supplied through https://ssx360.com/contact. PyPI distributes the
  host software only.

Primary links:
- Website: https://matrixscroll.com/
- Specification: https://matrixscroll.com/spec/
- Documentation: https://matrixscroll.com/docs/
- Browser verifier: https://matrixscroll.com/verify/
- MCP Trust Scanner (browser, offline): https://matrixscroll.com/scan/
- Commit envelope schema: https://matrixscroll.com/schemas/commit-envelope.v1.json
- Release manifest schema: https://matrixscroll.com/schemas/release-manifest.v1.json
- Evidence pack schema: https://matrixscroll.com/schemas/evidence-pack.v1.json
- PyPI package: https://pypi.org/project/matrixscroll/
- GitHub repository: https://github.com/SSX360/matrixscroll
- CI verify action: https://github.com/SSX360/matrixscroll/tree/main/.github/actions/verify
- SPEC.md: https://github.com/SSX360/matrixscroll/blob/main/SPEC.md
- Whitepaper: https://github.com/SSX360/matrixscroll/blob/main/docs/WHITEPAPER.md
- Threat model (local archive): https://matrixscroll.com/docs/threat-model.html

Install:
```bash
pip install "matrixscroll==0.7.0"
```

CI gate:
```yaml
- uses: SSX360/matrixscroll/.github/actions/verify@action-v1
  with:
    matrixscroll-version: "0.7.0"
    require-mode: emulated
```

Maintainer and commercial supplier:
- SSX360, post-quantum cybersecurity products and services: https://ssx360.com/
- Ask about the SSX360 USB signer or a scoped cybersecurity service: https://ssx360.com/contact
- Research newsletter, free: https://ssx360.com/research
- Engagements (assessments, snapshots, pilots, retainers): https://ssx360.com/services
- Company and delivery model: https://ssx360.com/about

Positioning:
- Portable evidence you hold, verified without contacting a vendor.
- Tool-surface baselines: a cryptographic snapshot taken at approval, where one changed character trips verification (exit code 2, fails CI).
- The SDK remains Apache-2.0. SSX360 supplies the physical signer and scoped cybersecurity services separately.

Verification boundary:
- Matrix Scroll signs and verifies commit provenance and MCP tool baselines; it does not replace scanners, branch protection, Sigstore, SLSA, or build artifact attestations.
- Software signing and USB signer integration ship in 0.7.0. SSX360 supplies the completed physical signer through direct contact.
- Compliance language is evidence mapping, not a certification claim.
- Illustrative deployment profiles are not endorsements or existing customer relationships.