matrixscroll 0.1.1__tar.gz → 0.2.1__tar.gz

{matrixscroll-0.1.1 → matrixscroll-0.2.1}/CHANGELOG.md

@@ -4,6 +4,38 @@ 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.1] - 2026-06-20
+
+Windows and cross-platform commit envelope fix.
+
+### Fixed
+- **`parse_commit()` on Windows** — read author/committer timezone from `git cat-file commit`
+  instead of reconstructing dates with `%z` (unsupported in `git show` format on Windows).
+
+## [0.2.0] - 2026-06-20
+
+Agent provenance release: Git commit envelopes, SDK module split, CI scaffolding.
+
+### Added
+- **Git integration** — `matrixscroll/git.py` with post-commit envelope signing
+  and pre-push verification for commits being pushed.
+- **Hook installer** — `matrixscroll hook-install` / `matrixscroll hook-status`
+  (hooks ship inside the wheel at `matrixscroll/hooks/`).
+- **Commit envelope schema** — `schemas/commit-envelope.v1.json` plus release and
+  evidence-pack schemas under `schemas/`.
+- **Signed examples** — `examples/*.signed.json` for CI and documentation.
+- **Agent demo** — `examples/demo/agent-commit-demo.sh` and signed-example generator.
+- **SDK split** — `canonical.py`, `manifest.py`, `policy.py`, `providers/` with
+  `_core.py` retained as a compatibility shim.
+- **Policy verification** — `verify_manifest_with_policy()` for mode and trusted-key gates.
+- **YubiKey prototype** — `providers/yubikey.py` boundary (`MATRIXSCROLL_MODE=yubikey`).
+- **CI** — `verify-manifest` workflow and protected-branch example using
+  `SSX360/matrixscroll-verify-action@v1`.
+
+### Changed
+- CLI adds `envelope`, `envelope-verify`, and hook subcommands.
+- Commit envelopes bind to the **actual** commit SHA via post-commit signing.
+
 ## [0.1.1] - 2026-06-19
 
 Copy and citation hardening patch. No protocol or API changes.
@@ -44,5 +76,6 @@ 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.2.0]: https://github.com/SSX360/matrixscroll/releases/tag/v0.2.0
 [0.1.1]: https://github.com/SSX360/matrixscroll/releases/tag/v0.1.1
 [0.1.0]: https://github.com/SSX360/matrixscroll/releases/tag/v0.1.0

{matrixscroll-0.1.1 → matrixscroll-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matrixscroll
-Version: 0.1.1
+Version: 0.2.1
 Summary: Open protocol for signing AI-assisted code provenance with Ed25519; shipping software root of trust with SSX360 hardware support in progress.
 Project-URL: Homepage, https://matrixscroll.com
 Project-URL: Documentation, https://matrixscroll.com/docs
@@ -31,6 +31,8 @@ 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: yubikey
 Description-Content-Type: text/markdown
 
 # Matrix Scroll
@@ -39,9 +41,9 @@ Description-Content-Type: text/markdown
 
 Every AI-generated change in your IDE can be cryptographically signed by an
 Ed25519 identity and verified offline with a public key and one command. The
-v0.1.x reference implementation ships a well-tested software root of trust;
-SSX360/NXP SE050 hardware signing is the compatible reference-device path in
-progress.
+v0.2.x reference implementation ships a well-tested software root of trust
+with Git commit-envelope hooks; SSX360/NXP SE050 hardware signing is the
+compatible reference-device path in progress.
 
 - 📜 **Spec:** [`SPEC.md`](SPEC.md) — wire format, canonical encoding, schemas.
 - 🛡 **Agentic AI controls:** [`docs/AGENTIC_AI_SECURITY.md`](docs/AGENTIC_AI_SECURITY.md)
@@ -72,6 +74,35 @@ signed = matrixscroll.sign_manifest({"release": "v1.0.0", "artifacts": [...]})
 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.
+
+```bash
+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`](docs/quickstart-git.md) and run
+[`examples/demo/agent-commit-demo.sh`](examples/demo/agent-commit-demo.sh).
+
+### CI verify
+
+```yaml
+- uses: SSX360/matrixscroll-verify-action@v1
+  with:
+    manifest: examples/agentic_ai_evidence_manifest.signed.json
+    matrixscroll-version: "0.2.0"
+```
+
 ## CLI
 
 ```bash

{matrixscroll-0.1.1 → matrixscroll-0.2.1}/README.md

@@ -4,9 +4,9 @@
 
 Every AI-generated change in your IDE can be cryptographically signed by an
 Ed25519 identity and verified offline with a public key and one command. The
-v0.1.x reference implementation ships a well-tested software root of trust;
-SSX360/NXP SE050 hardware signing is the compatible reference-device path in
-progress.
+v0.2.x reference implementation ships a well-tested software root of trust
+with Git commit-envelope hooks; SSX360/NXP SE050 hardware signing is the
+compatible reference-device path in progress.
 
 - 📜 **Spec:** [`SPEC.md`](SPEC.md) — wire format, canonical encoding, schemas.
 - 🛡 **Agentic AI controls:** [`docs/AGENTIC_AI_SECURITY.md`](docs/AGENTIC_AI_SECURITY.md)
@@ -37,6 +37,35 @@ signed = matrixscroll.sign_manifest({"release": "v1.0.0", "artifacts": [...]})
 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.
+
+```bash
+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`](docs/quickstart-git.md) and run
+[`examples/demo/agent-commit-demo.sh`](examples/demo/agent-commit-demo.sh).
+
+### CI verify
+
+```yaml
+- uses: SSX360/matrixscroll-verify-action@v1
+  with:
+    manifest: examples/agentic_ai_evidence_manifest.signed.json
+    matrixscroll-version: "0.2.0"
+```
+
 ## CLI
 
 ```bash

matrixscroll-0.2.1/docs/hardware-provider.md

@@ -0,0 +1,20 @@
+# SSX360 hardware provider (L2)
+
+**Status:** Stage-0 prototype — `HardwareProvider` reports unavailable until the
+NXP SE050 transport ships on the SSX360 reference device.
+
+## Planned behavior
+
+- `MATRIXSCROLL_MODE=hardware` selects the secure-element provider
+- Private keys never leave the SE050; no seed on disk
+- User-presence touch gating for protected-branch commits
+- Compatible with the same manifest and commit-envelope schemas as L1 emulated mode
+
+## Related docs
+
+- [`docs/yubikey-bridge.md`](yubikey-bridge.md) — bridge path before SSX360 GA
+- [`SPEC.md`](../SPEC.md) — wire format (unchanged for L2 signing algorithm)
+
+## Device
+
+Reference hardware: [matrixscroll.com/device](https://matrixscroll.com/device)

matrixscroll-0.2.1/docs/quickstart-git.md

@@ -0,0 +1,61 @@
+# Git Quickstart
+
+Matrix Scroll Git hooks attach a signed **commit envelope** to every local commit.
+
+## Install hooks
+
+```bash
+pip install matrixscroll
+matrixscroll hook-install
+matrixscroll hook-status
+```
+
+Hooks ship inside the Python wheel (`matrixscroll/hooks/`). No separate clone path
+is required for pip-installed users.
+
+## What happens on commit
+
+1. **post-commit** reads the new commit SHA and builds a commit envelope from `git show`
+2. The envelope is signed with your active Matrix Scroll identity
+3. The signed envelope is stored at `.git/matrixscroll/envelopes/<sha>.json`
+
+**pre-push** verifies envelopes only for commits being pushed (not every envelope
+ever stored locally).
+
+By default hooks run in **warn mode** (signing failures do not block commits).
+Enable enforce mode in `.git/matrixscroll/config.json`:
+
+```json
+{
+  "enforce": true,
+  "actor_type": "human",
+  "tool": "cursor"
+}
+```
+
+## Agent provenance
+
+Set environment variables before committing:
+
+```bash
+export MATRIXSCROLL_ACTOR_TYPE=agent
+export MATRIXSCROLL_TOOL=cursor
+export MATRIXSCROLL_AGENT_SCOPE=examples/agentic_ai_evidence_manifest.signed.json
+```
+
+## Verify in CI
+
+```bash
+matrixscroll verify .git/matrixscroll/envelopes/<commit-sha>.json
+matrixscroll envelope-verify <commit-sha>
+```
+
+Or use [`SSX360/matrixscroll-verify-action@v1`](https://github.com/SSX360/matrixscroll-verify-action).
+
+## Demo
+
+```bash
+bash examples/demo/agent-commit-demo.sh
+```
+
+See [spec](../superpowers/specs/2026-06-19-matrixscroll-git-design.md).

matrixscroll-0.2.1/docs/superpowers/plans/2026-06-19-ci-action-plan.md

@@ -0,0 +1,88 @@
+# CI Action Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development or superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Provide a zero-config GitHub Action that runs `matrixscroll verify` with CI-friendly exit codes.
+
+**Architecture:** Composite action installs matrixscroll from PyPI, runs verify on one or more manifest paths, optionally applies policy flags.
+
+**Tech Stack:** GitHub Actions, Python 3.10+, matrixscroll CLI
+
+---
+
+## Exit code contract
+
+| Code | Meaning | CI interpretation |
+|------|---------|-------------------|
+| 0 | Valid signature | Pass check |
+| 1 | Usage/config error | Fail workflow (misconfiguration) |
+| 2 | Verification failed | Fail workflow (tampered/invalid) |
+
+The action MUST propagate CLI exit codes unchanged (`set -e` in bash step).
+
+## Action inputs
+
+| Input | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `manifest` | yes | — | Path to signed manifest JSON |
+| `python-version` | no | `3.12` | Python for pip install |
+| `matrixscroll-version` | no | `latest` | Pin e.g. `0.1.1` for reproducibility |
+| `require-mode` | no | `` | Pass through to policy verify (v0.2.1) |
+| `trusted-keys` | no | `` | Path to trusted keys JSON (v0.2.1) |
+
+## Action outputs
+
+| Output | Description |
+|--------|-------------|
+| `ok` | `true` or `false` |
+| `device_id` | Signer device id from manifest |
+| `mode` | Provider mode (`emulated`, `hardware`, `yubikey`) |
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `matrixscroll-action/action.yml` | Composite action definition |
+| `matrixscroll-action/README.md` | Usage docs |
+| `matrixscroll/.github/workflows/verify-manifest.yml` | Dogfood workflow |
+| `matrixscroll/examples/ci/protected-branch.yml` | Copy-paste template |
+
+## Protected branch pattern
+
+```yaml
+name: provenance
+on:
+  pull_request:
+    branches: [main]
+jobs:
+  verify-release-manifest:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: SSX360/matrixscroll-verify-action@v1
+        with:
+          manifest: examples/release-manifest.signed.json
+```
+
+## Release verification pattern
+
+1. Build job signs release manifest, uploads artifact
+2. Verify job downloads artifact, runs action
+3. Deploy job requires verify job success
+
+## Task checklist
+
+- [x] Write action.yml composite action
+- [x] Add dogfood workflow in matrixscroll repo
+- [x] Add protected-branch example
+- [ ] Publish action repo and tag v1 (manual release step)
+- [ ] Add signed release-manifest to examples once v0.2.0 ships
+
+## Verification
+
+```bash
+cd matrixscroll
+pip install -e ".[dev]"
+pytest tests/test_cli.py -v
+matrixscroll verify examples/agentic_ai_evidence_manifest.json  # expect exit 2 unsigned
+```

matrixscroll-0.2.1/docs/superpowers/plans/2026-06-19-sdk-refactor-plan.md

@@ -0,0 +1,166 @@
+# SDK Refactor Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development or superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Split the monolithic `_core.py` into focused modules while preserving the public API in `matrixscroll/__init__.py`.
+
+**Architecture:** Move crypto, canonical encoding, manifest signing, providers, and policy into separate modules. Keep `_core.py` as a thin compatibility shim that re-exports everything until v0.3.0.
+
+**Tech Stack:** Python 3.10+, cryptography, pytest
+
+---
+
+## Target module layout
+
+```
+matrixscroll/
+  __init__.py          # unchanged public API
+  _core.py             # compatibility re-exports (deprecated v0.3.0)
+  canonical.py         # deterministic JSON encoding
+  manifest.py          # sign_manifest / verify_manifest
+  policy.py            # policy-aware verification
+  errors.py            # IdentityError, VerificationError
+  git.py               # git hooks (v0.2.0)
+  providers/
+    __init__.py
+    base.py            # IdentityProvider ABC
+    emulated.py        # EmulatedProvider
+    hardware.py        # HardwareProvider stub
+    yubikey.py         # YubiKey bridge (optional extra)
+  cli.py
+  py.typed
+```
+
+## Public API contract (must not break)
+
+These symbols remain importable from `matrixscroll`:
+
+- Constants: `SCHEMA`, `SIGNATURE_SCHEMA`, `ALGORITHM`, `DEVICE_FILE`
+- Exceptions: `IdentityError`
+- Providers: `IdentityProvider`, `EmulatedProvider`, `HardwareProvider`
+- Functions: `store_dir`, `device_id`, `get_provider`, `identity_info`, `status`, `public_key_b64`, `sign`, `verify`, `sign_manifest`, `verify_manifest`
+
+## Task 1: Extract errors and constants
+
+**Files:**
+- Create: `matrixscroll/errors.py`
+- Create: `matrixscroll/constants.py`
+- Modify: `matrixscroll/_core.py`
+
+Move `IdentityError`, `SCHEMA`, `SIGNATURE_SCHEMA`, `ALGORITHM`, `DEVICE_FILE`, `SEED_LEN`, mode constants.
+
+## Task 2: Extract canonical encoding
+
+**Files:**
+- Create: `matrixscroll/canonical.py`
+- Modify: `matrixscroll/manifest.py`
+
+Move `_canonical()` → `canonical_bytes(payload: dict) -> bytes`.
+
+## Task 3: Extract manifest signing
+
+**Files:**
+- Create: `matrixscroll/manifest.py`
+
+Move `sign_manifest`, `verify_manifest`, keep importing `sign`/`verify` from providers layer.
+
+## Task 4: Extract providers
+
+**Files:**
+- Create: `matrixscroll/providers/base.py`
+- Create: `matrixscroll/providers/emulated.py`
+- Create: `matrixscroll/providers/hardware.py`
+- Create: `matrixscroll/providers/__init__.py`
+
+Move provider classes and `get_provider()`.
+
+## Task 5: Add policy module
+
+**Files:**
+- Create: `matrixscroll/policy.py`
+- Modify: `matrixscroll/cli.py`
+
+Add:
+
+```python
+@dataclass
+class VerifyPolicy:
+    require_mode: str | None = None
+    trusted_public_keys: set[str] | None = None
+    allowed_schemas: set[str] | None = None
+
+def verify_manifest_with_policy(manifest: dict, policy: VerifyPolicy) -> tuple[bool, str | None]:
+    ...
+```
+
+CLI flags (v0.2.1):
+
+```
+matrixscroll verify manifest.json --require-mode hardware --trusted-keys keys.json
+```
+
+## Task 6: Compatibility shim
+
+**Files:**
+- Modify: `matrixscroll/_core.py`
+
+Replace body with re-exports:
+
+```python
+from .canonical import canonical_bytes as _canonical
+from .manifest import sign_manifest, verify_manifest
+from .providers import EmulatedProvider, HardwareProvider, IdentityProvider, get_provider
+...
+```
+
+Add deprecation comment; remove shim in v0.3.0.
+
+## Task 7: Update tests
+
+**Files:**
+- Modify: `tests/test_core.py` — add imports from new modules
+- Create: `tests/test_policy.py`
+- Create: `tests/test_canonical.py`
+
+Run: `pytest -ra`
+
+## Task 8: Update packaging
+
+**Files:**
+- Modify: `pyproject.toml` — include `schemas/`, optional `[yubikey]` extra
+
+```toml
+[project.optional-dependencies]
+yubikey = []  # PKCS#11 deps added when bridge ships
+git = []
+```
+
+## Migration guide (for downstream consumers)
+
+| Before | After (preferred) |
+|--------|-------------------|
+| `from matrixscroll._core import _canonical` | `from matrixscroll.canonical import canonical_bytes` |
+| `verify_manifest(m)` | `verify_manifest_with_policy(m, policy)` for CI gates |
+| `MATRIXSCROLL_MODE=hardware` | unchanged |
+
+## Version bump
+
+- v0.2.0: git module, schemas, provider split (shim retained)
+- v0.2.1: policy CLI flags
+- v0.3.0: remove `_core.py` shim, add YubiKey extra
+
+## Risks
+
+| Risk | Mitigation |
+|------|------------|
+| Import cycles | providers → manifest → canonical (one direction) |
+| Vector drift | run `tests/test_vectors.py` after every task |
+| Breaking private imports | document `_core` deprecation; grep GitHub for `_core` usage |
+
+## Verification checklist
+
+- [ ] `pytest` green
+- [ ] `matrixscroll status` unchanged output shape
+- [ ] All vectors pass
+- [ ] `pip install -e .` works
+- [ ] No new runtime deps without CONTRIBUTING discussion