matrixscroll 0.4.0__tar.gz → 0.4.1__tar.gz

{matrixscroll-0.4.0 → matrixscroll-0.4.1}/CHANGELOG.md

@@ -4,6 +4,18 @@ 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.4.1] - 2026-06-29
+
+Universal provenance SDK expansion and SSX360 Scroll Phase 1 wrapper.
+
+### Added
+- **`matrixscroll.provenance`** — action envelope builders for `ci_step`, `iac_change`,
+  `db_migration`, `api_call`, and `contract_deploy` (`schemas/action-envelope.v1.json`).
+- **`matrixscroll sign-action`** CLI — sign typed action envelopes with Ed25519.
+- **`matrixscroll scroll commit`** — thin Git wrapper (Phase 1; not a Git replacement).
+- **MCP** — `sign_action` validates typed payloads; new `matrixscroll://schema/action-envelope.v1` resource.
+- **Docs** — SSX360 Scroll brief, Scroll Gate v2 SLSA L1–2 honest mapping.
+
 ## [0.3.0] - 2026-06-28
 
 Digital Rain removal and provenance-only SDK surface.

{matrixscroll-0.4.0 → matrixscroll-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matrixscroll
-Version: 0.4.0
+Version: 0.4.1
 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://ssx360.com
 Project-URL: Documentation, https://ssx360.com/docs
@@ -41,6 +41,8 @@ Requires-Python: >=3.10
 Requires-Dist: cryptography>=41.0
 Provides-Extra: dev
 Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: hypothesis>=6.100; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1; extra == 'dev'
 Requires-Dist: pytest>=7.4; extra == 'dev'
 Provides-Extra: git
 Provides-Extra: hardware
@@ -54,10 +56,15 @@ Description-Content-Type: text/markdown
 
 # Matrix Scroll
 
+[![ci-unit](https://github.com/SSX360/matrixscroll/actions/workflows/ci-unit.yml/badge.svg)](https://github.com/SSX360/matrixscroll/actions/workflows/ci-unit.yml)
 [![Scroll Gate v2 (hosted)](https://github.com/SSX360/matrixscroll/actions/workflows/provenance-gate.yml/badge.svg)](https://github.com/SSX360/matrixscroll/actions/workflows/provenance-gate.yml)
+[![codecov](https://codecov.io/gh/SSX360/matrixscroll/graph/badge.svg)](https://codecov.io/gh/SSX360/matrixscroll)
+
+**112 tests** · Hypothesis-verified security properties · [Security properties](docs/SECURITY_PROPERTIES.md)
 
 **Signed proof of who — or what — wrote every commit.** Matrix Scroll is the
-open Ed25519 commit-provenance protocol for agent-assisted Git — verified
+**universal provenance SDK** — open Ed25519 envelopes for Git commits, CI steps,
+IaC changes, DB migrations, API calls, and smart-contract deploys — verified
 offline in CLI, browser, and CI. Hardware (SE050) is an optional preview trust
 upgrade; emulated mode ships today.
 
@@ -93,17 +100,18 @@ Agents sign commits in-loop via the **provenance-only** MCP server:
 ```
 
 ```bash
-pip install "matrixscroll[mcp]==0.4.0"
+pip install "matrixscroll[mcp]==0.4.1"
 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`.
+**MCP tools (provenance verbs only):** `create_envelope`, `sign_action`, `verify_envelope`,
+`verify_pr_range` (Scroll Gate), `publish_notes`, `status`, `audit_export`, `list_envelopes`,
+`connect_card` (SE050 preview).
 
 ## Also available — CLI & hooks
 
 ```bash
-pip install "matrixscroll==0.4.0"
+pip install "matrixscroll==0.4.1"
 matrixscroll hook-install
 export MATRIXSCROLL_ACTOR_TYPE=agent
 export MATRIXSCROLL_TOOL=agent-runner
@@ -111,6 +119,29 @@ git commit -m "feat: agent-assisted change"
 matrixscroll envelope-verify "$(git rev-parse HEAD)"
 ```
 
+### Universal action envelopes (Layer 2)
+
+Sign provenance for CI, IaC, migrations, API calls, and contract deploys:
+
+```bash
+matrixscroll sign-action --type ci_step \
+  --payload ./payloads/ci-step.json \
+  --output ./ci-step.signed.json \
+  --actor-type ci
+```
+
+Action schema: [`schemas/action-envelope.v1.json`](schemas/action-envelope.v1.json)
+
+### SSX360 Scroll — Git wrapper (Layer 3, Phase 1)
+
+Git under the hood; governance on top. **Not a Git replacement.**
+
+```bash
+matrixscroll scroll commit -m "feat: governed commit"
+```
+
+See [`docs/commercial/SSX360_SCROLL.md`](docs/commercial/SSX360_SCROLL.md).
+
 See [`docs/quickstart-git.md`](docs/quickstart-git.md) and
 [`examples/demo/agent-commit-demo.sh`](examples/demo/agent-commit-demo.sh).
 
@@ -134,10 +165,19 @@ 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.
 
+## RFC 8032 (Ed25519) alignment
+
+Matrix Scroll v1 binds exclusively to [RFC 8032](https://www.rfc-editor.org/rfc/rfc8032)
+Ed25519: 32-byte seeds, 32-byte public keys, 64-byte detached signatures over
+canonical UTF-8 JSON bytes (see [`SPEC.md`](SPEC.md) §4). Verifiers reject any
+`signature.algorithm` other than `"ed25519"`. Conformance vectors live in
+[`vectors/`](vectors/); property tests in [`docs/SECURITY_PROPERTIES.md`](docs/SECURITY_PROPERTIES.md).
+
 ## Honest limits
 
-- Shipping now: PyPI `matrixscroll==0.4.0`, Git post-commit hooks,
-  `matrixscroll envelope-verify`, Scroll Gate PR verification, browser
+- Shipping now: PyPI `matrixscroll==0.4.1`, Git post-commit hooks,
+  `matrixscroll sign-action`, `matrixscroll scroll commit` (thin wrapper),
+  `matrixscroll envelope-verify`, Scroll Gate PR verification (partial SLSA L1–2),
   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: nRF52840 + SE050 firmware validation (AP2 Vault Card PoC), external Ed25519-capable
@@ -181,7 +221,7 @@ alongside your existing scanners, branch protection, and build attestations.
 ## Quickstart (CLI)
 
 ```bash
-pip install "matrixscroll==0.4.0"
+pip install "matrixscroll==0.4.1"
 matrixscroll hook-install
 matrixscroll hook-status
 
@@ -208,7 +248,7 @@ See [`docs/quickstart-git.md`](docs/quickstart-git.md) and run
     head-ref: ${{ github.event.pull_request.head.sha }}
     base-ref: ${{ github.event.pull_request.base.sha }}
     source: notes
-    matrixscroll-version: "0.4.0"
+    matrixscroll-version: "0.4.1"
     require-mode: emulated
 ```
 
@@ -228,7 +268,7 @@ git push origin refs/notes/matrixscroll
     head-ref: ${{ github.event.pull_request.head.sha }}
     base-ref: ${{ github.event.pull_request.base.sha }}
     source: notes
-    matrixscroll-version: "0.4.0"
+    matrixscroll-version: "0.4.1"
     summary-output: provenance-summary.json
 ```
 
@@ -265,7 +305,7 @@ when they preserve the same pure Ed25519 byte contract.
 ## Python API
 
 ```bash
-pip install "matrixscroll==0.4.0"
+pip install "matrixscroll==0.4.1"
 ```
 
 ```python
@@ -375,7 +415,7 @@ The MCP server exposes **provenance verbs only**: `create_envelope`, `verify_env
 Install and register in Cursor / Claude Desktop / VS Code:
 
 ```bash
-pip install "matrixscroll[mcp]==0.4.0"
+pip install "matrixscroll[mcp]==0.4.1"
 matrixscroll-mcp   # stdio
 ```
 
@@ -389,7 +429,8 @@ the recommended `mcp.json` snippet.
 
 ## Security
 
-See [`SECURITY.md`](SECURITY.md). Report vulnerabilities privately to
+See [`SECURITY.md`](SECURITY.md) and [`docs/SECURITY_PROPERTIES.md`](docs/SECURITY_PROPERTIES.md).
+Report vulnerabilities privately to
 **security@matrixscroll.com** or via a GitHub Security Advisory.
 
 ---

{matrixscroll-0.4.0 → matrixscroll-0.4.1}/README.md

@@ -1,9 +1,14 @@
 # Matrix Scroll
 
+[![ci-unit](https://github.com/SSX360/matrixscroll/actions/workflows/ci-unit.yml/badge.svg)](https://github.com/SSX360/matrixscroll/actions/workflows/ci-unit.yml)
 [![Scroll Gate v2 (hosted)](https://github.com/SSX360/matrixscroll/actions/workflows/provenance-gate.yml/badge.svg)](https://github.com/SSX360/matrixscroll/actions/workflows/provenance-gate.yml)
+[![codecov](https://codecov.io/gh/SSX360/matrixscroll/graph/badge.svg)](https://codecov.io/gh/SSX360/matrixscroll)
+
+**112 tests** · Hypothesis-verified security properties · [Security properties](docs/SECURITY_PROPERTIES.md)
 
 **Signed proof of who — or what — wrote every commit.** Matrix Scroll is the
-open Ed25519 commit-provenance protocol for agent-assisted Git — verified
+**universal provenance SDK** — open Ed25519 envelopes for Git commits, CI steps,
+IaC changes, DB migrations, API calls, and smart-contract deploys — verified
 offline in CLI, browser, and CI. Hardware (SE050) is an optional preview trust
 upgrade; emulated mode ships today.
 
@@ -39,17 +44,18 @@ Agents sign commits in-loop via the **provenance-only** MCP server:
 ```
 
 ```bash
-pip install "matrixscroll[mcp]==0.4.0"
+pip install "matrixscroll[mcp]==0.4.1"
 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`.
+**MCP tools (provenance verbs only):** `create_envelope`, `sign_action`, `verify_envelope`,
+`verify_pr_range` (Scroll Gate), `publish_notes`, `status`, `audit_export`, `list_envelopes`,
+`connect_card` (SE050 preview).
 
 ## Also available — CLI & hooks
 
 ```bash
-pip install "matrixscroll==0.4.0"
+pip install "matrixscroll==0.4.1"
 matrixscroll hook-install
 export MATRIXSCROLL_ACTOR_TYPE=agent
 export MATRIXSCROLL_TOOL=agent-runner
@@ -57,6 +63,29 @@ git commit -m "feat: agent-assisted change"
 matrixscroll envelope-verify "$(git rev-parse HEAD)"
 ```
 
+### Universal action envelopes (Layer 2)
+
+Sign provenance for CI, IaC, migrations, API calls, and contract deploys:
+
+```bash
+matrixscroll sign-action --type ci_step \
+  --payload ./payloads/ci-step.json \
+  --output ./ci-step.signed.json \
+  --actor-type ci
+```
+
+Action schema: [`schemas/action-envelope.v1.json`](schemas/action-envelope.v1.json)
+
+### SSX360 Scroll — Git wrapper (Layer 3, Phase 1)
+
+Git under the hood; governance on top. **Not a Git replacement.**
+
+```bash
+matrixscroll scroll commit -m "feat: governed commit"
+```
+
+See [`docs/commercial/SSX360_SCROLL.md`](docs/commercial/SSX360_SCROLL.md).
+
 See [`docs/quickstart-git.md`](docs/quickstart-git.md) and
 [`examples/demo/agent-commit-demo.sh`](examples/demo/agent-commit-demo.sh).
 
@@ -80,10 +109,19 @@ 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.
 
+## RFC 8032 (Ed25519) alignment
+
+Matrix Scroll v1 binds exclusively to [RFC 8032](https://www.rfc-editor.org/rfc/rfc8032)
+Ed25519: 32-byte seeds, 32-byte public keys, 64-byte detached signatures over
+canonical UTF-8 JSON bytes (see [`SPEC.md`](SPEC.md) §4). Verifiers reject any
+`signature.algorithm` other than `"ed25519"`. Conformance vectors live in
+[`vectors/`](vectors/); property tests in [`docs/SECURITY_PROPERTIES.md`](docs/SECURITY_PROPERTIES.md).
+
 ## Honest limits
 
-- Shipping now: PyPI `matrixscroll==0.4.0`, Git post-commit hooks,
-  `matrixscroll envelope-verify`, Scroll Gate PR verification, browser
+- Shipping now: PyPI `matrixscroll==0.4.1`, Git post-commit hooks,
+  `matrixscroll sign-action`, `matrixscroll scroll commit` (thin wrapper),
+  `matrixscroll envelope-verify`, Scroll Gate PR verification (partial SLSA L1–2),
   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: nRF52840 + SE050 firmware validation (AP2 Vault Card PoC), external Ed25519-capable
@@ -127,7 +165,7 @@ alongside your existing scanners, branch protection, and build attestations.
 ## Quickstart (CLI)
 
 ```bash
-pip install "matrixscroll==0.4.0"
+pip install "matrixscroll==0.4.1"
 matrixscroll hook-install
 matrixscroll hook-status
 
@@ -154,7 +192,7 @@ See [`docs/quickstart-git.md`](docs/quickstart-git.md) and run
     head-ref: ${{ github.event.pull_request.head.sha }}
     base-ref: ${{ github.event.pull_request.base.sha }}
     source: notes
-    matrixscroll-version: "0.4.0"
+    matrixscroll-version: "0.4.1"
     require-mode: emulated
 ```
 
@@ -174,7 +212,7 @@ git push origin refs/notes/matrixscroll
     head-ref: ${{ github.event.pull_request.head.sha }}
     base-ref: ${{ github.event.pull_request.base.sha }}
     source: notes
-    matrixscroll-version: "0.4.0"
+    matrixscroll-version: "0.4.1"
     summary-output: provenance-summary.json
 ```
 
@@ -211,7 +249,7 @@ when they preserve the same pure Ed25519 byte contract.
 ## Python API
 
 ```bash
-pip install "matrixscroll==0.4.0"
+pip install "matrixscroll==0.4.1"
 ```
 
 ```python
@@ -321,7 +359,7 @@ The MCP server exposes **provenance verbs only**: `create_envelope`, `verify_env
 Install and register in Cursor / Claude Desktop / VS Code:
 
 ```bash
-pip install "matrixscroll[mcp]==0.4.0"
+pip install "matrixscroll[mcp]==0.4.1"
 matrixscroll-mcp   # stdio
 ```
 
@@ -335,7 +373,8 @@ the recommended `mcp.json` snippet.
 
 ## Security
 
-See [`SECURITY.md`](SECURITY.md). Report vulnerabilities privately to
+See [`SECURITY.md`](SECURITY.md) and [`docs/SECURITY_PROPERTIES.md`](docs/SECURITY_PROPERTIES.md).
+Report vulnerabilities privately to
 **security@matrixscroll.com** or via a GitHub Security Advisory.
 
 ---

{matrixscroll-0.4.0 → matrixscroll-0.4.1}/controls/agentic_ai_controls.json

@@ -78,7 +78,7 @@
       "title": "Supply-chain and dependency management",
       "guidance": "Understand third-party components, models, tools, integrations, and update exposure.",
       "matrixscroll_control": "The repo uses minimal runtime dependencies, Dependabot, CI build verification, and a public spec/conformance suite.",
-      "evidence_paths": ["pyproject.toml", ".github/dependabot.yml", ".github/workflows/test.yml", "vectors/README.md"],
+      "evidence_paths": ["pyproject.toml", ".github/dependabot.yml", ".github/workflows/ci-unit.yml", "vectors/README.md"],
       "goes_beyond": "Third-party implementations can self-test against public vectors before being trusted."
     },
     {
@@ -94,7 +94,7 @@
       "title": "Governance and change control",
       "guidance": "Integrate agentic AI risk with existing security governance and define ownership before deployment.",
       "matrixscroll_control": "Spec, core crypto, vectors, security policy, and CI are CODEOWNERS-protected and tested across OS/Python versions.",
-      "evidence_paths": [".github/CODEOWNERS", ".github/workflows/test.yml", "CONTRIBUTING.md"],
+      "evidence_paths": [".github/CODEOWNERS", ".github/workflows/ci-unit.yml", ".github/workflows/ci-integration.yml", "CONTRIBUTING.md"],
       "goes_beyond": "Protocol-impacting changes require both human review and machine conformance checks."
     },
     {

matrixscroll-0.4.1/docs/SECURITY_PROPERTIES.md

@@ -0,0 +1,36 @@
+# Matrix Scroll security properties
+
+Machine-checkable guarantees for the reference SDK (v0.4.0). Properties marked
+**verified** have Hypothesis property tests in `tests/test_security_properties.py`.
+Formal TLA+ models are on the public roadmap.
+
+| ID | Property | Statement | Status |
+| -- | -------- | ----------- | ------ |
+| **P1** | Sign–verify roundtrip | For any canonical manifest bytes, `verify(pub, msg, sign(msg, key))` is true when `pub` derives from the same key material. | **Verified** (Hypothesis) |
+| **P2** | Tamper detection | Changing any signed byte (manifest body or signature octet) causes verification to fail. | **Verified** (Hypothesis) |
+| **P3** | Wrong-key rejection | A signature valid under key A MUST NOT verify under key B's public key. | **Verified** (Hypothesis) |
+| **P4** | Canonical determinism | Identical logical manifests produce identical signing input bytes after canonical JSON encoding (sorted keys, ASCII escapes, no NaN). | **Verified** (unit + vectors) |
+| **P5** | Offline verification | Envelope verification requires no network, hosted API, or hardware ping once the envelope and trusted key set are local. | **Verified** (unit) |
+| **P6** | Algorithm binding | Only Ed25519 (RFC 8032) signatures with `algorithm: "ed25519"` are accepted; other algorithms are rejected. | **Verified** (unit + vectors) |
+
+## Standards alignment
+
+- **Ed25519:** [RFC 8032](https://www.rfc-editor.org/rfc/rfc8032) — 32-byte seed, 32-byte public key, 64-byte signature.
+- **Canonical JSON:** Deterministic UTF-8 encoding per [`SPEC.md`](../SPEC.md) §4.
+- **Commit envelopes:** `matrixscroll.commit_envelope.v1` schema in [`schemas/commit-envelope.v1.json`](../schemas/commit-envelope.v1.json).
+
+## Trust modes (honest scope)
+
+| Mode | Private key location | Shipping status |
+| ---- | -------------------- | --------------- |
+| **Emulated** | Owner-only file (`~/.matrixscroll/device.json`, mode 0600) | **Shipping today** |
+| **Hardware (SE050)** | NXP secure element on AP2 Vault Card pilot | **Pilot / preview** — same verifier contract, key not exportable from chip |
+
+## Roadmap (not claimed today)
+
+- TLA+ specification of Scroll Gate merge semantics
+- Third-party cryptographic audit and public threat model
+- npm `@ssx360/verify` browser/Node verifier package
+- IETF informational draft for commit-envelope wire format
+
+See [`SECURITY.md`](../SECURITY.md) for vulnerability reporting.

matrixscroll-0.4.1/docs/commercial/SCROLL_GATE_V2.md

@@ -0,0 +1,82 @@
+# Scroll Gate v2 — hosted verification
+
+Scroll Gate **v2** calls the SSX360 hosted API. Local-only verification remains in the Matrix Scroll SDK and MCP (`verify_envelope`, offline `source=local|notes|bundle`).
+
+## Requirements
+
+- **`SSX360_API_KEY`** — required for CI and hosted MCP Scroll Gate
+- Community tier includes **100 CI verifications/day**
+- Get a key at [ssx360.com/signup](https://ssx360.com/signup)
+
+## GitHub Actions
+
+Add repository secret `SSX360_API_KEY` (Settings → Secrets → Actions).
+
+The workflow in `.github/workflows/provenance-gate.yml` posts to:
+
+```text
+POST https://ssx360.com/api/v1/verify
+Authorization: Bearer $SSX360_API_KEY
+```
+
+Example body:
+
+```json
+{
+  "base": "<base-sha>",
+  "head": "<head-sha>",
+  "commits": []
+}
+```
+
+## Migration from v1
+
+| v1 (local) | v2 (hosted) |
+|------------|-------------|
+| `matrixscroll-verify-action@v1` | `curl` or `@v2` action against ssx360.com |
+| Local git notes only | Network audit + usage metering |
+| No API key | `SSX360_API_KEY` required |
+
+## MCP
+
+Set `SSX360_API_KEY` in your MCP server environment. The default `verify_pr_range` source is `hosted`. Use `source=notes` for offline git-notes verification without a key.
+
+---
+
+## SLSA mapping (honest — partial today)
+
+Scroll Gate provides **governance-as-a-service** aligned with [SLSA](https://slsa.dev/) Build Level 1–2 concepts. SSX360 does **not** claim full SLSA Build Level 3 or certification.
+
+| SLSA concept | SSX360 / Scroll Gate today | Gap |
+|--------------|----------------------------|-----|
+| **Version control** | Git + signed commit envelopes on every governed commit | Scroll client MVP still rolling out |
+| **Retained history** | Git immutable objects + optional hosted envelope storage (Team+) | Community: local/git-notes only |
+| **Authenticated source** | Ed25519 commit envelopes bind actor, tool, scope | Default **emulated** keys; SE050 hardware is pilot |
+| **Hosted build platform** | ⚠️ Partial — `ci_step` action envelopes + hosted verify API | Not a replacement for GitHub Actions / Cloud Build |
+| **Non-falsifiable provenance** | ❌ Not claimed at L3+ | Requires hardware-backed signing + builder attestations (Layer 4) |
+
+### What hosted verify proves today
+
+When Scroll Gate passes for a PR range:
+
+1. Each commit in range has a **cryptographically valid** envelope (or policy allows warn-mode gaps).
+2. Signatures verify against trusted keys / team policy when configured.
+3. Verification is **logged** on ssx360.com for Team+ audit export (usage-metered on Community).
+
+This maps to **SLSA Source L1–L2** style controls (versioned, authenticated change history) for **commit provenance**, not full **build artifact** provenance.
+
+### Roadmap toward stronger SLSA alignment
+
+| Phase | Deliverable | SLSA relevance |
+|-------|-------------|----------------|
+| Phase 1 (now) | `sign-action --type ci_step`, hosted verify | CI step attestation alongside commits |
+| Phase 2 | Scroll `push` + mandatory notes | Stronger retained provenance chain |
+| Phase 3 | Builder attestations (Layer 4 doc) | Toward L3 build provenance — not committed |
+
+Portal reference: [ssx360.com/docs/slsa](https://ssx360.com/docs/slsa)
+
+## Docs
+
+- Platform docs: [ssx360.com/docs](https://ssx360.com/docs)
+- Migration guide: [PLATFORM_PIVOT.md](./PLATFORM_PIVOT.md)
+- Layer 3 roadmap: [LAYER3 governance (digital-rain)](https://github.com/SSX360/digital-rain/blob/main/docs/commercial/LAYER3_GOVERNANCE_ROADMAP.md)

matrixscroll-0.4.1/docs/commercial/SSX360_SCROLL.md

@@ -0,0 +1,31 @@
+# SSX360 Scroll — Provenance-native Git governance
+
+**Status:** Phase 1 thin wrapper + hooks. **Not** a Git replacement.
+
+See also the platform copy in [digital-rain/docs/commercial/SSX360_SCROLL.md](https://github.com/SSX360/digital-rain/blob/main/docs/commercial/SSX360_SCROLL.md).
+
+## Module location
+
+- `matrixscroll/scroll/` — Phase 1 `scroll commit` wrapper
+- `matrixscroll/provenance/` — universal action envelope builders
+
+## Quick start
+
+```bash
+pip install "matrixscroll==0.4.1"
+matrixscroll hook-install
+matrixscroll scroll commit -m "feat: governed commit"
+```
+
+## Universal actions (Layer 2)
+
+```bash
+matrixscroll sign-action --type ci_step \
+  --payload ./ci-step.json \
+  --output ./ci-step.signed.json \
+  --actor-type ci
+```
+
+Action types: `git_commit`, `ci_step`, `iac_change`, `db_migration`, `api_call`, `contract_deploy`.
+
+Schema: [`schemas/action-envelope.v1.json`](../schemas/action-envelope.v1.json)

{matrixscroll-0.4.0 → matrixscroll-0.4.1}/matrixscroll/cli.py

@@ -328,6 +328,46 @@ def _cmd_sign_payment(args: argparse.Namespace) -> int:
         return 1
 
 
+def _cmd_sign_action(args: argparse.Namespace) -> int:
+    from .provenance import build_action_envelope, sign_action_envelope, validate_action_payload
+
+    payload_path = Path(args.payload)
+    try:
+        payload = json.loads(payload_path.read_text(encoding="utf-8-sig"))
+    except (OSError, ValueError) as exc:
+        print(json.dumps({"ok": False, "error": f"cannot read payload: {exc}"}))
+        return 2
+    ok, err = validate_action_payload(args.type, payload)
+    if not ok:
+        print(json.dumps({"ok": False, "error": err}))
+        return 2
+    envelope = build_action_envelope(
+        args.type,  # type: ignore[arg-type]
+        payload,
+        actor_type=args.actor_type,
+        tool=args.tool,
+    )
+    signed = sign_action_envelope(envelope)
+    if args.output:
+        Path(args.output).write_text(json.dumps(signed, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    else:
+        print(json.dumps(signed, indent=2, sort_keys=True))
+    return 0
+
+
+def _cmd_scroll_commit(args: argparse.Namespace) -> int:
+    from .scroll import commit as scroll_commit
+
+    result = scroll_commit(
+        args.message,
+        actor_type=args.actor_type,
+        tool=args.tool,
+        allow_empty=args.allow_empty,
+    )
+    print(json.dumps(result, indent=2, sort_keys=True))
+    return 0 if result.get("ok") else 2
+
+
 def build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
         prog="matrixscroll",
@@ -454,6 +494,36 @@ def build_parser() -> argparse.ArgumentParser:
     pay_p.add_argument("--key-path", help="Alternative signing key path")
     pay_p.set_defaults(command="sign-payment")
 
+    sign_action_p = sub.add_parser(
+        "sign-action",
+        help="Sign a universal provenance action envelope (ci_step, iac_change, etc.)",
+    )
+    sign_action_p.add_argument(
+        "--type",
+        required=True,
+        choices=["git_commit", "ci_step", "iac_change", "db_migration", "api_call", "contract_deploy"],
+        help="Action type per schemas/action-envelope.v1.json",
+    )
+    sign_action_p.add_argument("--payload", required=True, help="JSON file with action-specific payload")
+    sign_action_p.add_argument("--output", "-o", help="Write signed envelope to file")
+    sign_action_p.add_argument(
+        "--actor-type",
+        default="human",
+        choices=["human", "agent", "ci"],
+        help="Provenance actor label",
+    )
+    sign_action_p.add_argument("--tool", default="matrixscroll", help="Producing tool name")
+    sign_action_p.set_defaults(command="sign-action")
+
+    scroll_p = sub.add_parser("scroll", help="SSX360 Scroll — Git wrapper with auto-envelope (Phase 1)")
+    scroll_sub = scroll_p.add_subparsers(dest="scroll_command")
+    scroll_commit_p = scroll_sub.add_parser("commit", help="git commit + signed envelope")
+    scroll_commit_p.add_argument("-m", "--message", required=True)
+    scroll_commit_p.add_argument("--actor-type", default="human", choices=["human", "agent", "ci"])
+    scroll_commit_p.add_argument("--tool", default="scroll")
+    scroll_commit_p.add_argument("--allow-empty", action="store_true")
+    scroll_commit_p.set_defaults(command="scroll-commit")
+
     return parser
 
 
@@ -479,6 +549,8 @@ def main(argv: list[str] | None = None) -> int:
         "claim": cmd_claim,
         "identity": cmd_identity,
         "sign-payment": _cmd_sign_payment,
+        "sign-action": _cmd_sign_action,
+        "scroll-commit": _cmd_scroll_commit,
     }
     handler = handlers.get(args.command)
     if handler is None:

{matrixscroll-0.4.0 → matrixscroll-0.4.1}/matrixscroll/cloud/client.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import json
 import os
 import urllib.error
+import urllib.parse
 import urllib.request
 from typing import Any
 
@@ -81,11 +82,37 @@ def verify_range(
     )
 
 
-def list_envelopes(*, limit: int = 50) -> dict[str, Any]:
+def list_envelopes(
+    *,
+    limit: int = 50,
+    offset: int = 0,
+    signer_filter: str = "",
+) -> dict[str, Any]:
     """List stored envelopes for the authenticated organization."""
-    return _request("GET", f"/api/v1/envelopes?limit={limit}")
+    params = [f"limit={limit}", f"offset={offset}"]
+    if signer_filter.strip():
+        params.append(f"signer_filter={urllib.parse.quote(signer_filter.strip())}")
+    query = "&".join(params)
+    return _request("GET", f"/api/v1/envelopes?{query}")
 
 
-def audit_export(*, format: str = "json") -> dict[str, Any]:
+def audit_export(
+    *,
+    format: str = "json",
+    start_date: str = "",
+    end_date: str = "",
+    signer_id: str = "",
+    include_verification: bool = True,
+) -> dict[str, Any]:
     """Export audit bundle from the hosted platform (Team+)."""
-    return _request("GET", f"/api/v1/audit/export?format={format}")
+    params = [f"format={urllib.parse.quote(format)}"]
+    if start_date.strip():
+        params.append(f"start_date={urllib.parse.quote(start_date.strip())}")
+    if end_date.strip():
+        params.append(f"end_date={urllib.parse.quote(end_date.strip())}")
+    if signer_id.strip():
+        params.append(f"signer_id={urllib.parse.quote(signer_id.strip())}")
+    if include_verification:
+        params.append("include_verification=true")
+    query = "&".join(params)
+    return _request("GET", f"/api/v1/audit/export?{query}")