Open specification / v1 (frozen)

Spec

The Matrix Scroll protocol uses a compact JSON signature envelope for declared authorization records bound to Git commits and other machine actions. Frozen v1 under Apache-2.0: SPEC.md · commit-envelope.v1.json.

Read SPEC.md Open schema Test the verifier

Canonical bytes

Sorted keys, ASCII escaping, compact separators, and the top-level signature removed before signing.

Embedded proof

Public key, device ID, mode, timestamp, and signature value travel with the document.

One wire format

The same public contract spans release manifests, commit envelopes, and evidence packs.

Identity schemamatrixscroll.identity.v1

Signature schemamatrixscroll.signature.v1

Commit envelope schemamatrixscroll.commit_envelope.v1 - JSON schema - GitHub

Release manifest schemarelease-manifest.v1.json

Evidence pack schemaevidence-pack.v1.json

AlgorithmEd25519 signatures as defined by RFC 8032.

Canonical inputJSON object with the top-level signature property excluded before signing.

EncodingSorted object keys, compact separators, ASCII escaping, UTF-8 bytes, and no NaN or Infinity values.

Device IDMS-XXXX-XXXX derived from SHA-256(public_key), first eight uppercase hex characters split 4-4.

Wire formatEmbeddable JSON signature block carried inside release, commit, evidence, or vendor manifests.

Verifier ruleVerify the canonical manifest bytes with the embedded public key and signature value. Key access is never required.

Canonical encoding

The byte contract.

The top-level signature block is excluded, keys are sorted recursively, whitespace is stripped, non-ASCII is escaped with ensure_ascii, NaN and Infinity are rejected with allow_nan=False, compact separators are (",", ":"), and the resulting UTF-8 bytes are signed.

body = {k: v for k, v in payload.items() if k != "signature"}
json.dumps(
    body,
    sort_keys=True,
    ensure_ascii=True,
    allow_nan=False,
    separators=(",", ":"),
).encode("utf-8")

"signature": {
  "schema": "matrixscroll.signature.v1",
  "algorithm": "ed25519",
  "device_id": "MS-EAB9-1217",
  "public_key": "Vxee+i1db9b...",
  "mode": "emulated",
  "signed_at": "2026-06-19T09:43:35Z",
  "value": "SQPMBxv3Mvjl..."
}

Signature block

Minimum public envelope.

Every verifier should require the signature schema, Ed25519 algorithm, public key, device ID, mode, timestamp, and signature value. Unknown fields may be shown, but they should not be required for verification.

Signer paths

One format, multiple roots of trust.

Software signer

Software key

File-backed key for local development, tests, and CI. This remains the default provider.

USB signer

Dedicated USB signer

The completed SSX360 signer creates and retains the Ed25519 private key in hardware. Host integration ships in 0.7.0, and physical units are supplied by direct contact.

Additional providers

Operator integrations

TPM, YubiKey, and other external key-provider profiles remain separate integration work. They do not change the envelope format.