matrixscroll 0.2.5__tar.gz → 0.3.0__tar.gz

{matrixscroll-0.2.5 → matrixscroll-0.3.0}/CHANGELOG.md

@@ -4,9 +4,43 @@ 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.2.5] - 2026-06-24
+## [0.3.0] - 2026-06-28
 
-Post-HN patch: GitHub gpgsig commit binding, SE050 mock transport, YubiKey pubkey export, Rekor/GUAC CLI MVP.
+Digital Rain removal and provenance-only SDK surface.
+
+### Removed
+- **Workspace intelligence modules** — deleted unused Digital Rain-era helpers
+  (`benchmark`, `brainstorm`, `scanner`, `vault`, radar modules, and related tests).
+
+### Changed
+- **Public copy** — removed Digital Rain funnel language from README, MCP docs,
+  and hero demo script; SSX360 remains the hosted control plane reference.
+- **Version pins** — bumped public quickstart and product docs to `0.3.0`.
+
+## [0.2.6] - 2026-06-21
+
+SDK rollout hardening: generic public attribution, SE050 host transport preview,
+and repo-local hardware rollout docs.
+
+### Added
+- **USB CDC host transport preview** - `SerialSE050Transport` for newline-delimited
+  JSON `ping` / `pubkey` / `sign` framing over the RP2350 USB bridge.
+- **Hardware extra** - `pip install "matrixscroll[hardware]"` now pulls in
+  `pyserial` for the SE050 host path.
+- **Rollout docs** - adopter kit, five-minute guide, hardware provider quickstart,
+  SE050 protocol reference, and contractor-facing PoC scope kept inside the SDK repo.
+
+### Changed
+- **Public quickstarts** - replaced editor-specific public quickstarts with
+  generic agent-facing guidance while keeping the manifest schema and API unchanged.
+- **Hardware messaging** - clarified that the SDK now ships a host transport
+  preview and mock path, while real device signing still depends on firmware PoC validation.
+- **Release copy** - aligned README, support docs, CI examples, and package metadata
+  around the `0.2.6` rollout surface.
+
+## [0.2.5] - 2026-06-20
+
+Credibility and compatibility patch: GitHub gpgsig commit binding, SE050 mock transport, YubiKey pubkey export, Rekor/GUAC CLI MVP.
 
 ### Added
 - **GitHub `gpgsig` commit binding** — verify envelopes against raw commit object SHA when OpenPGP signatures are present.

{matrixscroll-0.2.5 → matrixscroll-0.3.0}/CONTRIBUTING.md

@@ -36,7 +36,7 @@ For PRs that include agent-assisted commits, publish signed commit envelopes to
 ```bash
 matrixscroll hook-install
 export MATRIXSCROLL_ACTOR_TYPE=agent   # or human / ci as appropriate
-export MATRIXSCROLL_TOOL=cursor        # or your IDE / agent tool name
+export MATRIXSCROLL_TOOL=agent-runner  # or your editor / agent tool name
 git commit -m "feat: your change"
 matrixscroll envelope-publish-notes --base origin/main --head HEAD
 git push origin refs/notes/matrixscroll

matrixscroll-0.3.0/PKG-INFO

@@ -0,0 +1,411 @@
+Metadata-Version: 2.4
+Name: matrixscroll
+Version: 0.3.0
+Summary: Signed provenance for agent-assisted Git commits with offline verification; emulated Ed25519 ships today and the SE050 hardware path remains an optional preview.
+Project-URL: Homepage, https://matrixscroll.com
+Project-URL: Documentation, https://matrixscroll.com/docs
+Project-URL: Source, https://github.com/SSX360/matrixscroll
+Project-URL: Issues, https://github.com/SSX360/matrixscroll/issues
+Project-URL: Specification, https://github.com/SSX360/matrixscroll/blob/main/SPEC.md
+Project-URL: Whitepaper, https://github.com/SSX360/matrixscroll/blob/main/docs/WHITEPAPER.md
+Project-URL: Verifier, https://matrixscroll.com/verify
+Project-URL: Compare, https://matrixscroll.com/compare
+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-verify-action
+Project-URL: PyPI Provenance, https://pypi.org/project/matrixscroll/
+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: Reference Device, https://matrixscroll.com/device
+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
+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>=41.0
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Provides-Extra: git
+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: tpm
+Provides-Extra: yubikey
+Requires-Dist: python-pkcs11>=0.7; extra == 'yubikey'
+Description-Content-Type: text/markdown
+
+# Matrix Scroll
+
+**Signed proof of who — or what — wrote every commit.** Matrix Scroll is the
+open Ed25519 commit-provenance protocol for agent-assisted Git — verified
+offline in CLI, browser, and CI. Hardware (SE050) is an optional preview trust
+upgrade; emulated mode ships today.
+
+**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](mailto:mission@ssx360.com?subject=Provenance%20Pilot%20Inquiry);
+Provisioned pilot and team accounts sign in at [ssx360.com/signup](https://ssx360.com/signup).
+
+## Compliance evidence mapping
+
+Matrix Scroll **maps to** and **produces evidence for** (never “required by”):
+
+- **Five Eyes · Agentic AI (Apr 2026)** — cryptographic attestation that agents
+  run expected, unmodified code.
+- **EU AI Act · high-risk traceability** — verifiable commit-time audit artifacts.
+- **US federal SSDF · self-attestation** — evidence packs for supply-chain review.
+
+Full matrix: [`controls/agentic_ai_controls.json`](controls/agentic_ai_controls.json)
+
+## Adoption signals
+
+Track outbound and registry traction while rolling out:
+
+| Signal | Counter |
+|--------|---------|
+| PyPI `matrixscroll` | [![PyPI downloads](https://img.shields.io/pypi/dm/matrixscroll)](https://pypi.org/project/matrixscroll/) |
+| PyPI `[mcp]` extra | [![PyPI MCP downloads](https://img.shields.io/pypi/dm/matrixscroll?label=mcp%20extra)](https://pypi.org/project/matrixscroll/) |
+| GitHub stars | [![GitHub stars](https://img.shields.io/github/stars/SSX360/matrixscroll?style=social)](https://github.com/SSX360/matrixscroll/stargazers) |
+| Scroll Gate Action | [![GitHub Action](https://img.shields.io/github/stars/SSX360/matrixscroll-verify-action?style=social)](https://github.com/SSX360/matrixscroll-verify-action) |
+| Glama MCP registry | [matrixscroll on Glama](https://glama.ai/mcp/servers/SSX360/matrixscroll) |
+
+## Hero demo (post–MCP merge)
+
+Record the 60–90s provenance flow in [`docs/HERO_DEMO.md`](docs/HERO_DEMO.md) — Scroll Gate + browser verifier + MCP verbs only.
+
+## Install — MCP server (headline path)
+
+Agents sign commits in-loop via the **provenance-only** MCP server:
+
+```json
+{
+  "mcpServers": {
+    "matrixscroll-mcp": {
+      "command": "matrixscroll-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+```bash
+pip install "matrixscroll[mcp]==0.3.0"
+matrixscroll-mcp   # stdio — register in Cursor / Claude Desktop / VS Code
+```
+
+**MCP tools (provenance verbs only):** `create_envelope`, `verify_envelope`,
+`verify_pr_range` (Scroll Gate), `publish_notes`, `status`, `audit_export`.
+
+## Also available — CLI & hooks
+
+```bash
+pip install "matrixscroll==0.3.0"
+matrixscroll hook-install
+export MATRIXSCROLL_ACTOR_TYPE=agent
+export MATRIXSCROLL_TOOL=agent-runner
+git commit -m "feat: agent-assisted change"
+matrixscroll envelope-verify "$(git rev-parse HEAD)"
+```
+
+See [`docs/quickstart-git.md`](docs/quickstart-git.md) and
+[`examples/demo/agent-commit-demo.sh`](examples/demo/agent-commit-demo.sh).
+
+---
+
+This repository is the canonical SDK, verifier contract, fixture set, and
+release surface for the product.
+
+Matrix Scroll is a cryptographic evidence layer for Git. When an agent, CI
+workflow, or human operator produces a commit, a signed commit envelope can
+record the actor, tool, and optional bounded scope. Anyone can verify that
+envelope locally, in CI, or in the browser without trusting the editor session
+that produced it.
+
+Keep GitHub Advanced Security, Semgrep, Snyk, branch protection, and artifact
+attestations. Matrix Scroll adds signed commit-time authorship proof before
+merge, and it keeps the same offline verification contract across the CLI,
+browser, CI, and the SE050 preview path.
+
+The reference SDK ships pure Ed25519 over canonical manifest bytes today. The
+SSX360 / NXP SE050 path is the compatible next trust layer and remains a
+preview path until device acceptance is complete.
+
+## Honest limits
+
+- Shipping now: PyPI `matrixscroll==0.3.0`, Git post-commit hooks,
+  `matrixscroll envelope-verify`, Scroll Gate PR verification, browser
+  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: RP2350 + SE050 firmware validation, external Ed25519-capable
+  hardware key backends, and transparency-log integrations.
+- Not: IAM, sandboxing, prompt filtering, or an agent runtime.
+
+## Where it fits
+
+- Scanners and branch protection catch code and policy issues; Matrix Scroll
+  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.
+
+## Common questions
+
+### What is Matrix Scroll and how does it secure Git?
+
+Matrix Scroll is signed commit-time provenance for agent-assisted Git. It
+secures Git by attaching an Ed25519-signed commit envelope to a commit,
+recording the actor, tool, and optional bounded scope, then letting reviewers
+verify that proof offline in the CLI, browser, or CI before merge.
+
+### How do hardware and emulated modes differ in Matrix Scroll?
+
+Emulated mode ships today and keeps the signing key on disk with owner-only
+permissions so teams can evaluate the full workflow now. Hardware mode keeps
+the same verifier contract and commit envelope schema, but moves the private
+key into the SE050 secure element so the host cannot export it; that path
+remains preview-only until device acceptance is complete.
+
+### How can I integrate Matrix Scroll into a CI/CD workflow?
+
+Install the SDK and hooks in your repo, publish commit envelopes to
+`refs/notes/matrixscroll` before PR review, and use
+`SSX360/matrixscroll-verify-action@v1` to verify the full PR commit range in
+GitHub Actions. Protected branches can then require Matrix Scroll proof
+alongside your existing scanners, branch protection, and build attestations.
+
+## Quickstart (CLI)
+
+```bash
+pip install "matrixscroll==0.3.0"
+matrixscroll hook-install
+matrixscroll hook-status
+
+export MATRIXSCROLL_ACTOR_TYPE=agent
+export MATRIXSCROLL_TOOL=agent-runner
+git commit -m "feat: agent-assisted change"
+
+matrixscroll envelope-verify "$(git rev-parse HEAD)"
+```
+
+See [`docs/quickstart-git.md`](docs/quickstart-git.md) and run
+[`examples/demo/agent-commit-demo.sh`](examples/demo/agent-commit-demo.sh).
+
+## CI verify
+
+### Scroll Gate for a PR commit range
+
+```yaml
+- uses: actions/checkout@v4
+  with:
+    fetch-depth: 0
+- uses: SSX360/matrixscroll-verify-action@v1
+  with:
+    head-ref: ${{ github.event.pull_request.head.sha }}
+    base-ref: ${{ github.event.pull_request.base.sha }}
+    source: notes
+    matrixscroll-version: "0.3.0"
+    require-mode: emulated
+```
+
+Publish envelopes to git notes before review:
+
+```bash
+matrixscroll envelope-publish-notes --base origin/main --head HEAD
+git push origin refs/notes/matrixscroll
+```
+
+```yaml
+- uses: actions/checkout@v4
+  with:
+    fetch-depth: 0
+- uses: SSX360/matrixscroll-verify-action@v1
+  with:
+    head-ref: ${{ github.event.pull_request.head.sha }}
+    base-ref: ${{ github.event.pull_request.base.sha }}
+    source: notes
+    matrixscroll-version: "0.3.0"
+    summary-output: provenance-summary.json
+```
+
+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
+are available in the `0.2.x` line; the examples in this README pin `0.3.0`.
+
+## Why it is different from Sigstore
+
+Sigstore, GitHub artifact attestations, and SLSA answer "what was built in
+CI?" Matrix Scroll answers "who signed this commit before push?" The systems
+are complementary: Matrix Scroll signs commit envelopes at commit time, while
+artifact-attestation systems sign build outputs later in the delivery chain.
+
+Matrix Scroll does not compete with general authentication keys on their home
+field. Existing hardware roots can become Matrix Scroll signing backends only
+when they preserve the same pure Ed25519 byte contract.
+
+## Public proof links
+
+- Browser verifier: <https://matrixscroll.com/verify/>
+- Compare page: <https://matrixscroll.com/compare/>
+- Specification: [`SPEC.md`](SPEC.md)
+- Commit envelope schema: [`schemas/commit-envelope.v1.json`](schemas/commit-envelope.v1.json)
+- Whitepaper: [`docs/WHITEPAPER.md`](docs/WHITEPAPER.md)
+- 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://matrixscroll.com>
+- Reference device path: [SSX360](https://matrixscroll.com/device)
+
+## Python API
+
+```bash
+pip install "matrixscroll==0.3.0"
+```
+
+```python
+import matrixscroll
+
+print(matrixscroll.status())
+# {'schema': 'matrixscroll.identity.v1', 'available': True,
+#  'mode': 'emulated', 'device_id': 'MS-A3F2-9C81', ...}
+
+signed = matrixscroll.sign_manifest({"release": "v1.0.0", "artifacts": [...]})
+
+assert matrixscroll.verify_manifest(signed)
+```
+
+## CLI
+
+```bash
+$ matrixscroll status
+{
+  "available": true,
+  "device_id": "MS-A3F2-9C81",
+  "mode": "emulated",
+  "public_key": "...",
+  "schema": "matrixscroll.identity.v1"
+}
+
+$ matrixscroll sign release.json > release.signed.json
+$ matrixscroll verify release.signed.json
+{"device_id": "MS-A3F2-9C81", "mode": "emulated", "ok": true, "signed_at": "..."}
+```
+
+`matrixscroll verify` exits `0` on a valid signature and `2` on failure
+(tampered manifest, missing signature block, wrong schema or algorithm,
+mismatched device ID, malformed public key, unreadable file).
+
+## How it works
+
+```text
+your IDE / agent / CI
+         |
+         |  commit envelope, release manifest, evidence pack, SBOM
+         v
+matrixscroll.sign_manifest(...)  /  post-commit hook
+         |
+         |  canonical JSON (sorted keys, ASCII-escaped, no NaN,
+         |  signature block excluded from input)
+         v
+IdentityProvider          -->  Ed25519 signature
+(L1 emulated today,
+ SSX360 / SE050 roadmap)
+         |
+         v
+signed document  -->  matrixscroll.verify_manifest(...)
+                      (anyone, anywhere, offline)
+```
+
+Switch providers with `MATRIXSCROLL_MODE`. Hardware mode includes a USB CDC
+host transport preview and a mock path for CI; real SE050 signing still
+depends on device firmware validation. External-key backends stay out of the
+mainline until they can sign the same canonical bytes with Ed25519.
+
+For rollout order, start with `MATRIXSCROLL_MODE=emulated` for evaluation,
+layer in external Ed25519-capable signers only when they stay verifier
+compatible, and treat `hardware` as the SE050 preview path until device
+acceptance is complete.
+
+## Compliance levels
+
+| Level | Provider | Backed by | Status |
+| ----- | -------- | --------- | ------ |
+| **L1** Emulated | `EmulatedProvider` | Software key, file-backed (0600) | Shipping |
+| **L2** Hardware | `HardwareProvider` | NXP SE050 secure element (SSX360) | In progress |
+| **L3** Attested | future | L2 + remote attestation | Roadmap |
+
+`status()` exposes the active level via the `mode` and `available` fields.
+
+## Storage and trust boundaries
+
+- Emulated key store: `~/.matrixscroll/device.json`
+  (override with `MATRIXSCROLL_HOME`).
+- The directory is created `0700`; the seed file is opened `0600` with
+  `O_CREAT|O_EXCL` so the private seed is never momentarily world-readable.
+- A corrupt or truncated store fails loud (`IdentityError`) rather than
+  silently minting a fresh identity.
+- The planned hardware path holds nothing private on disk; the seed is sealed
+  in the secure element.
+
+## Reference implementation, not the only one
+
+Matrix Scroll is a protocol. This Python package is the reference. We welcome
+implementations in Rust, Go, TypeScript, and embedded C. Run them against
+[`vectors/`](vectors/) to self-certify. See `CONTRIBUTING.md`.
+
+## Agentic AI guidance proof
+
+The repo includes a machine-readable control matrix at
+[`controls/agentic_ai_controls.json`](controls/agentic_ai_controls.json), an
+example bounded-agent evidence manifest at
+[`examples/agentic_ai_evidence_manifest.json`](examples/agentic_ai_evidence_manifest.json),
+and executable checks in `tests/test_agentic_guidance.py`.
+
+## Model Context Protocol (MCP) Server
+
+The MCP server exposes **provenance verbs only**: `create_envelope`, `verify_envelope`,
+`verify_pr_range`, `publish_notes`, `status`, and `audit_export`.
+
+Install and register in Cursor / Claude Desktop / VS Code:
+
+```bash
+pip install "matrixscroll[mcp]==0.3.0"
+matrixscroll-mcp   # stdio
+```
+
+See the [Install — MCP server](#install--mcp-server-headline-path) section above for
+the recommended `mcp.json` snippet.
+
+## License
+
+- Code: **Apache-2.0** (`LICENSE`).
+- Specification text (`SPEC.md`, `vectors/`): **CC0 1.0** - public domain.
+
+## Security
+
+See [`SECURITY.md`](SECURITY.md). Report vulnerabilities privately to
+**security@matrixscroll.com** or via a GitHub Security Advisory.
+
+---
+
+**Protocol:** https://matrixscroll.com · **Verify:** https://matrixscroll.com/verify/  
+**Control plane:** https://ssx360.com · **Pilot:** mission@ssx360.com · **Sign in:** https://ssx360.com/signup