matrixscroll 0.2.2

Open protocol for signing AI-assisted code provenance with Ed25519; shipping software root of trust with SSX360 hardware support in progress.

Matrix Scroll

Signed provenance for agent-assisted Git commits — verify offline, one command.

Matrix Scroll is a cryptographic evidence layer: when an AI agent (Cursor, Claude Code, Copilot, etc.) produces a commit, a signed commit envelope records actor, tool, and optional scope. Verify locally or in CI without trusting the IDE. The v0.2.x reference SDK ships an emulated Ed25519 root of trust with Git hooks; SSX360/NXP SE050 hardware signing is the compatible reference-device path in progress.

Matrix Scroll is not an IAM system, agent sandbox, or prompt-injection filter — it complements those controls with tamper-evident signatures.

• 📜 Spec: SPEC.md — wire format, canonical encoding, schemas.
• 📄 Whitepaper: docs/WHITEPAPER.md — why Git commits, implementation guide.
• 🛡 Agentic AI controls: docs/AGENTIC_AI_SECURITY.md maps Matrix Scroll to the joint Careful Adoption of Agentic AI Services guidance.
• 🔐 Algorithm: Ed25519 (RFC 8032). Private keys are never exposed by the SDK API.
• 🧪 Conformance vectors: vectors/ — for non-Python implementations.
• 🌐 Site: https://matrixscroll.com
• 🔧 Reference device: SSX360 (NXP SE050 hardware path in progress).

pip install matrixscroll

Quickstart

import matrixscroll

# What identity is active on this machine?
print(matrixscroll.status())
# {'schema': 'matrixscroll.identity.v1', 'available': True,
#  'mode': 'emulated', 'device_id': 'MS-A3F2-9C81', ...}

# Sign anything (a release manifest, a commit envelope, a SBOM, an evidence pack)
signed = matrixscroll.sign_manifest({"release": "v1.0.0", "artifacts": [...]})

# Verify, anywhere, offline
assert matrixscroll.verify_manifest(signed)

Agent provenance for Git commits

When an AI agent (Cursor, Claude Code, Copilot, etc.) produces a commit, Matrix Scroll attaches a signed commit envelope with actor, tool, and scope metadata. Verify in CI without trusting the IDE.

pip install matrixscroll
matrixscroll hook-install

export MATRIXSCROLL_ACTOR_TYPE=agent
export MATRIXSCROLL_TOOL=cursor
git commit -m "feat: agent-assisted change"

matrixscroll envelope-verify "$(git rev-parse HEAD)"

See docs/quickstart-git.md and run examples/demo/agent-commit-demo.sh.

CI verify

- uses: SSX360/matrixscroll-verify-action@v1
  with:
    manifest: examples/agentic_ai_evidence_manifest.signed.json
    matrixscroll-version: "0.2.2"

CLI

$ 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, 2 on any failure (tampered manifest, missing signature block, wrong schema/algorithm, mismatched device id, malformed public key, unreadable file). Pipe it from CI without parsing the output.

How it works

   your IDE / agent / CI
            │
            │  manifest (release, commit, evidence pack, SBOM, anything)
            ▼
   matrixscroll.sign_manifest(...)
            │
            │  canonical JSON  (sorted keys, ASCII-escaped, no NaN,
            │                   signature block excluded from input)
            ▼
   IdentityProvider          ──►  Ed25519 signature
   (Emulated today,
    SSX360 / SE050 tomorrow)
            │
            ▼
   signed manifest  ──►  matrixscroll.verify_manifest(...)
                         (anyone, anywhere, offline)

The same Python API is designed to serve the local software emulator and the physical SSX360 device path. Switch with the MATRIXSCROLL_MODE environment variable; in v0.1.x, hardware mode reports unavailable until the SE050 transport ships.

Compliance levels

Level	Provider	Backed by	Status
L1 Emulated	EmulatedProvider	Software key, file-backed (0600)	✅ Shipping
L2 Hardware	HardwareProvider	NXP SE050 secure element (SSX360)	🛠 Stage-0 prototype
L3 Attested	future	L2 + remote attestation	🗺 Roadmap

status() exposes the active level via the mode and available fields so read-only dashboards can render before the hardware path is wired.

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 and a race cannot silently clobber an existing key store.
• A corrupt or truncated store fails loud (IdentityError) rather than silently minting a fresh identity. Identity rotation is an explicit operation.
• The planned hardware path holds nothing private on disk — the seed is sealed in the secure element. In v0.1.x, this path is a typed availability stub.

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/ to self-certify. See CONTRIBUTING.md.

Agentic AI guidance proof

The repo includes a machine-readable control matrix at controls/agentic_ai_controls.json, an example bounded-agent evidence manifest at examples/agentic_ai_evidence_manifest.json, and executable checks in tests/test_agentic_guidance.py. These prove each claim maps to repo evidence and that signed agent scope changes fail verify.

License

• Code: Apache-2.0 (LICENSE).
• Specification text (SPEC.md, vectors/): CC0 1.0 — public domain.

Security

See SECURITY.md. Report vulnerabilities privately to [e-mail] or via a GitHub Security Advisory.