# Matrix Scroll Protocol Specification

**Version:** commit-envelope v1 (frozen)  
**License:** Apache-2.0  
**Canonical schema:** [`schemas/commit-envelope.v1.json`](./schemas/commit-envelope.v1.json)  
**Published URL:** https://matrixscroll.com/schemas/commit-envelope.v1.json

## Scope

This specification defines the **commit envelope**, the per-commit signed artifact that Matrix Scroll produces at Git commit time. It is distinct from the aggregated **evidence pack** (`ssx360.evidence-pack.v1` / `matrixscroll.evidence_pack.v1`), which bundles ledger records for audit export.

## Frozen v1 contract

The v1 commit envelope is **frozen** as of 2026-07-03. Implementations MUST:

1. Set `schema` to the constant `matrixscroll.commit_envelope.v1`.
2. Include `commit`, `provenance`, and `repository` objects (see JSON Schema).
3. Sign canonical JSON bytes with **Ed25519** only (`signature.algorithm` = `ed25519`).
4. Derive `signature.device_id` as `MS-XXXX-XXXX` from the SHA-256 digest of raw public key bytes.
5. Verify offline. No network trust path required.

### Required top-level fields

| Field | Purpose |
|-------|---------|
| `schema` | Version discriminator (`matrixscroll.commit_envelope.v1`) |
| `commit` | Git commit object (tree, parents, author, committer, message; optional `expected_id` / `actual_id`) |
| `provenance` | Actor attribution (`actor_type`: human \| agent \| ci; `tool`; optional `agent_scope`, `session_id`) |
| `repository` | Repo identity (`name`; optional `remote_url`, `branch`) |
| `signature` | Ed25519 block (`public_key`, `value`, `mode`, `signed_at`, `device_id`) |

Optional: `delegation` for human owner/approver attestation on agent commits (AAI-04 pattern).

## Canonicalization

Before signing or verifying:

1. Remove the top-level `signature` key from the payload.
2. Recursively sort object keys.
3. Serialize with `ensure_ascii=True`, `allow_nan=False`, compact separators `(",", ":")`.
4. UTF-8 encode the result. These bytes are the Ed25519 message.

Reference implementation: Matrix Scroll SDK `matrixscroll.canonical`.

## Related schemas

| Schema | File | Purpose |
|--------|------|---------|
| Commit envelope v1 | `schemas/commit-envelope.v1.json` | Per-commit signed provenance |
| Evidence pack v1 | `schemas/evidence-pack.v1.json` | Aggregated audit export |
| Release manifest v1 | `schemas/release-manifest.v1.json` | Release attestation bundle |

## Change control policy

| Change type | Policy |
|-------------|--------|
| **Breaking** | Requires new major schema (`matrixscroll.commit_envelope.v2`) and a new JSON Schema file |
| **Additive (v1.x)** | Optional fields only; MUST NOT alter required fields or enum constraints in v1 |
| **Documentation** | Clarifications and examples may update without a schema bump |
| **Conformance** | Vectors in [`vectors/`](./vectors/) (when published) are normative for verifier behavior |

Producers SHOULD include `schema` on every envelope. Verifiers MUST reject envelopes with unknown `schema` values rather than silently accepting them.

## Verification surfaces

- CLI: `matrixscroll verify`
- Browser: https://matrixscroll.com/verify/
- CI: https://github.com/SSX360/matrixscroll-verify-action
- Hosted API (optional): `POST /api/v1/verify` on ssx360.com (does not replace offline verify)

## IP and licensing

The JSON Schema files and this specification are licensed under **Apache-2.0**. Third parties may implement compatible signers and verifiers without a separate license grant.