Metadata-Version: 2.5
Name: matrixscroll
Version: 0.11.0
Summary: Protocol v2 signed machine-action records with ML-DSA-87 and offline verification.
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/explanation/roadmap.md
Project-URL: Crypto Roadmap, https://github.com/SSX360/matrixscroll/blob/main/docs/explanation/roadmap.md#later-work
Project-URL: Maintainer, https://ssx360.com/about
Author-email: SSX360 <security@matrixscroll.com>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: authorization,fips-204,machine-action,matrixscroll,ml-dsa,ml-kem,post-quantum,provenance,root-of-trust,signing,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>=50.0.2
Requires-Dist: rfc8785==0.1.4
Provides-Extra: dev
Requires-Dist: build>=1.5.0; extra == 'dev'
Requires-Dist: hypothesis>=6.165.2; extra == 'dev'
Requires-Dist: jsonschema[format]>=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'
Requires-Dist: tomli>=2.0.1; (python_version < '3.11') and 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
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/)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/SSX360/matrixscroll/blob/59f1ac4e040da027c99bc1a9a6167cd28d320d6c/LICENSE)

**Version 0.11.0, protocol v2.** Protocol v2 makes pure, hedged ML-DSA-87 mandatory and uses SHA-384 ledger commitments. Build, publication and website promotion follow the [release checklist](https://github.com/SSX360/matrixscroll/blob/59f1ac4e040da027c99bc1a9a6167cd28d320d6c/docs/how-to/release-v0.11.0.md).

[![Matrix Scroll protocol v2: ML-DSA-87 signatures, COSE and JCS signed bytes, SHA-384 ledgers, and Python, Rust and JavaScript verifiers. Version 0.11.0. Hardware deferred. Signer authorization requires a trust policy.](https://raw.githubusercontent.com/SSX360/matrixscroll/59f1ac4e040da027c99bc1a9a6167cd28d320d6c/docs/assets/ssx360-trust-checkable-v0.11.0.png)](https://github.com/SSX360/matrixscroll/blob/59f1ac4e040da027c99bc1a9a6167cd28d320d6c/SPEC.md)

An MCP server can change its tool descriptions after installation. A Git commit can declare an actor without carrying a signed authorization record. Matrix Scroll signs records of those surfaces so you can verify their bytes and apply your own trust policy.

Start with [signing a record](#install) or [verifying evidence offline](#verify-offline). The [migration guide](https://github.com/SSX360/matrixscroll/blob/59f1ac4e040da027c99bc1a9a6167cd28d320d6c/docs/how-to/migrate-v2.md) covers enrollment of a new v2 identity.

## Verification boundaries

**Available now.** Version 0.11.0 provides v2 signatures, authenticated ledger checkpoints, Git and MCP workflows, and Python, Rust and JavaScript verification.

**In progress.** Independent external assessment, KMS/HSM adapters, witnesses, transparency services, hardware custody and an extracted Lean 4 or F* verifier remain later work.

**Outside the claim.** A valid signature checks the supplied bytes against the included key. You must enroll that key to authorize its signer. A signed clock value cannot establish trusted time, event truth, complete external history, runtime safety or physical key protection. IAM, sandboxing, prompt controls and runtime enforcement remain separate controls.

The v2 signature and ledger profile is CNSA-aligned in algorithm selection only: pure ML-DSA-87 and SHA-384. The project claims no NSA approval, CMVP module validation or complete-system assurance. NIST references provide evidence mapping, not a certification claim. Optional sealed-pack encryption uses its separate X25519/ML-KEM-1024/HKDF-SHA-256/AES-256-GCM profile and carries no broader CNSA claim.

ML-KEM-1024 is the sealed-pack default. The optional ML-KEM-768 variant remains available under the separately authenticated `x25519-mlkem768-hkdfsha256-aes256gcm-v1` identifier.

## Install

Use Python 3.10 or newer in a virtual environment. For the published package:

```bash
python -m pip install "matrixscroll[mcp]==0.11.0"
```

To build and install from this source checkout:

```bash
python -m pip install build
python -m build
python -m pip install "dist/matrixscroll-0.11.0-py3-none-any.whl[mcp]"
```

The [PyPI version page](https://pypi.org/project/matrixscroll/0.11.0/) records package availability and provenance. Source checkouts can be built before publication.

Local signing and verification require no account or API key. The base package includes ML-DSA signing. Install the `mcp` extra to add the MCP server. The optional hosted SSX360 API has separate credentials.

In Bash, create and verify a record:

```bash
matrixscroll status
printf '%s\n' '{"event":"build","artifact":"example"}' > record.json
matrixscroll sign record.json > signed.json
matrixscroll verify signed.json
```

In PowerShell 7, write the JSON files with explicit UTF-8 encoding:

```powershell
'{"event":"build","artifact":"example"}' | Set-Content -Encoding utf8NoBOM record.json
matrixscroll sign record.json | Set-Content -Encoding utf8NoBOM signed.json
matrixscroll verify signed.json
```

Successful verification exits with `0` and includes these fields:

```json
{"verdict":"CONSISTENT","exit_code":0,"ok":true,"reason":"verified","signer_authorized":false}
```

`signer_authorized: false` means that no enrolled signer policy was applied. After independently checking and enrolling the public key as described in the [migration guide](https://github.com/SSX360/matrixscroll/blob/59f1ac4e040da027c99bc1a9a6167cd28d320d6c/docs/how-to/migrate-v2.md), run `matrixscroll verify signed.json --trusted-keys trusted-keys.json` to enforce that policy.

The verifier rejects duplicate fields, invalid Unicode, nonfinite numbers and integers outside the interoperable safe range. Start the MCP server with `matrixscroll-mcp` after installing the `mcp` extra.

## Signed bytes and keys

Every v2 record carries a tagged COSE_Sign1 object with an attached RFC 8785 canonical JSON payload. Protected headers authenticate algorithm -50, key identifier, content type, protocol version and record type. The readable JSON view must agree with the authenticated payload, including signer metadata and timestamps.

The default IdentityProvider creates a fresh ML-DSA-87 identity in `~/.matrixscroll/v2/device.json`. It stores a seed-based PKCS#8 key with restricted permissions and atomic creation. Existing keys stay intact. Enroll the new public key explicitly in each trust policy. Old enrollment cannot authorize it.

`cryptography>=50.0.2` supplies base signing support. Every signing path verifies its output before returning it. Unsupported providers and algorithms fail closed. `MATRIXSCROLL_FIPS=1` fails because this release has no adapter that establishes validated custody.

## Verify offline

All three current implementations accept protocol v2 only:

```bash
matrixscroll verify signed.json
cargo run --locked --manifest-path rust/Cargo.toml -p matrixscroll-verify --bin verify -- signed.json
node js/matrixscroll-verify/src/verify.mjs signed.json --webcrypto
```

Install JavaScript dependencies with `npm ci --prefix js/matrixscroll-verify`. Node 24.7 or newer supports the native ML-DSA path. The `--noble` option exercises the pinned portable backend explicitly.

Build the single-file browser verifier with `npm run build --prefix js/matrixscroll-verify`. Open `artifacts/v2/matrixscroll-offline-0.11.0.html` and select a record or ledger bundle. Dependencies and licenses accompany the artifact. Verification needs no network. The noble browser fallback has no independent security audit.

| Verdict | Exit code | Meaning |
| --- | --- | --- |
| CONSISTENT | 0 | Required cryptographic checks pass for supplied evidence |
| INDETERMINATE | 1 | Evidence or backend support is missing, or the format is historical |
| INCONSISTENT | 2 | Current-format evidence is malformed, altered or invalid |

For a detached commit envelope, use `matrixscroll envelope-verify downloaded.json --commit <full-commit-id>`. The expected ID must come from the caller or the filename. See the [commit envelope reference](https://github.com/SSX360/matrixscroll/blob/59f1ac4e040da027c99bc1a9a6167cd28d320d6c/docs/reference/commit-envelope.md) for repository scope handling.

Every verification result includes `verdict`, `exit_code`, `ok` and a machine-readable `reason`. Empty ranges, unsigned ledgers and incomplete checkpoint coverage cannot report success. Hosted aggregate summaries without raw verifiable evidence remain INDETERMINATE.

## Migration and evidence

Start a new v2 ledger. Preserve historical chains, signatures and release tags. The [legacy artifact](https://github.com/SSX360/matrixscroll/blob/59f1ac4e040da027c99bc1a9a6167cd28d320d6c/legacy/0.10.0/README.md) handles historical verification separately. No current compatibility flag restores old acceptance.

- [Protocol specification](https://github.com/SSX360/matrixscroll/blob/59f1ac4e040da027c99bc1a9a6167cd28d320d6c/SPEC.md) and [schemas](https://github.com/SSX360/matrixscroll/tree/59f1ac4e040da027c99bc1a9a6167cd28d320d6c/schemas)
- [Migration guide](https://github.com/SSX360/matrixscroll/blob/59f1ac4e040da027c99bc1a9a6167cd28d320d6c/docs/how-to/migrate-v2.md) and [MCP setup](https://github.com/SSX360/matrixscroll/blob/59f1ac4e040da027c99bc1a9a6167cd28d320d6c/docs/how-to/use-mcp-server.md)
- [Protocol v2 roadmap](https://github.com/SSX360/matrixscroll/blob/59f1ac4e040da027c99bc1a9a6167cd28d320d6c/docs/explanation/roadmap.md)
- [Research review](https://github.com/SSX360/matrixscroll/blob/59f1ac4e040da027c99bc1a9a6167cd28d320d6c/docs/research/2026-10-05-protocol-v2.md) and [source register](https://github.com/SSX360/matrixscroll/blob/59f1ac4e040da027c99bc1a9a6167cd28d320d6c/docs/research/2026-10-05-source-register.md)
- [Randomness diagnostics](https://github.com/SSX360/matrixscroll/blob/59f1ac4e040da027c99bc1a9a6167cd28d320d6c/docs/reference/v2-randomness.md): measured output behavior and source-assessment limits; no claim of maximum entropy
- [Reproducible verification](https://github.com/SSX360/matrixscroll/blob/59f1ac4e040da027c99bc1a9a6167cd28d320d6c/docs/reference/v2-conformance.md)
- [Security policy](https://github.com/SSX360/matrixscroll/blob/59f1ac4e040da027c99bc1a9a6167cd28d320d6c/SECURITY.md) and [changelog](https://github.com/SSX360/matrixscroll/blob/59f1ac4e040da027c99bc1a9a6167cd28d320d6c/CHANGELOG.md)

External NIST ACVP, RFC and Wycheproof inputs retain their source versions and digests. Generated protocol fixtures remain separate. The 10,000-document corpus compares canonical bytes and verdicts across Python, Rust, native WebCrypto and noble.

## Gold standard and license

The [gold-standard policy](https://github.com/SSX360/matrixscroll/blob/59f1ac4e040da027c99bc1a9a6167cd28d320d6c/docs/explanation/gold-standard.md) requires source-traceable evidence and code-owner review. Agent-generated proposals and fixtures cannot act as authority. No AI system decides a technical conclusion.

Matrix Scroll is an open protocol, free permanently. SDK code uses Apache-2.0. Specification text and project-authored schemas use CC0 1.0. External vectors and bundled dependencies retain their source licenses. SSX360 provides separate assessments. Local protocol use has no paid tier.
