Skip to content

Latest commit

 

History

History
111 lines (74 loc) · 5.5 KB

README.md

File metadata and controls

111 lines (74 loc) · 5.5 KB

parmana-verifier (Python)

Every action stays within what your business allowed, and Parmana keeps proof of what happened. This package checks that proof using only a record and a trust file. No network access, no account, no Parmana server needed.

This is the Python counterpart of the Node verifier in the repository root. It checks the same things in the same order, and it returns the same result shape and exit codes. Its results match the Node verifier on every test vector and on records generated by each implementation.

What it checks, and what it does not

Checked

  • The record hash (trustRecordHash) against the canonical record fields.
  • The schema version 3 whole-record message, and the signatures array: one entry in single mode, two in hybrid.
  • Trust rules: the key's fingerprint, its validity window, and the compromised flag.
  • Execution correspondence, as a separate correspondence report in the output: each execution's dispatched content hash must equal the authorized one, and the nonce, business transaction hash, policy content hash and authority grant must match the authorization. A passed report needs every execution checked and corresponding. The report does not change valid or the exit code. See Execution correspondence in the repository README; the Node verifier gives the same report.
  • The hybridRequiredFrom cutover, when the trust file sets one. A record created at or after it must carry both entries; one created before it is accepted with one valid entry. The removed flags allowLegacyOnly and allowLegacyV2 are refused.

ML-DSA-65 (dilithium3) signatures are checked with cryptography 48.0.0 or later, over the same message as the Ed25519 entry. A hybrid record is accepted only when both entries verify, so one valid part is never enough.

Other differences from the Node verifier

  • A timestamp without a time zone offset is rejected. Node reads it in the local time zone, so this verifier gives the same answer on every machine.
  • Integers beyond 2^53 are rounded the way JavaScript rounds them when it parses JSON. Use records written by Parmana, which never contain such integers.

Install

Requires Python 3.11 or later (tested on 3.11, 3.12 and 3.13). The only dependency is cryptography (version 48.0.0 or later, needed for ML-DSA-65).

pip install parmana-verifier

From a clone of this repository:

cd python
pip install -e .

For the tests, install the test extra as well: pip install -e ".[test]".

Quick start

From a clone of this repository, at the repository root:

pip install -e python
parmana-verify test/vectors/parmana-core-generated/v3-single-record.json test/vectors/parmana-core-generated/trust-v3-single.json
{"valid":true,"errors":[],"checks":{"trustRecordHash":true,"signatures":true},"correspondence":{"status":"not_checked","executions":[]}}

The record is schema version 3 with one Ed25519 signature (single mode). The exit code is 0. The correspondence report is not_checked here because the record embeds no authorization, so there is nothing to compare. That is not a mismatch. The report does not change valid or the exit code. Change a covered field and the record is rejected. The sample below changes the amount in a copy and runs the same trust file:

parmana-verify <tampered-copy.json> test/vectors/parmana-core-generated/trust-v3-single.json

The exit code is 1, and errors names the failed checks: trustRecordHash mismatch and signature verification failed. The same check from Python:

import json
from parmana_verifier import parse_trust_policy, verify_execution_trust_record

record = json.load(open("test/vectors/parmana-core-generated/v3-single-record.json"))
policy = parse_trust_policy(json.load(open("test/vectors/parmana-core-generated/trust-v3-single.json")))
result = verify_execution_trust_record(record, policy.keys, policy.hybrid_required_from)
print(result["valid"], result["errors"])

The sample files are test material, signed with a fixed test key. For real records, pin the keys you trust with parmana-verify key-fingerprint (see below).

Command line

parmana-verify <proof.json> <trust.json>
parmana-verify key-fingerprint <public-key.pem>
  • verify prints one line of JSON and exits 0 when the record is valid, 1 when it is invalid, and 2 for a usage or read error.
  • key-fingerprint prints the sha256:... value to pin in a trust file.

The output has the same fields as the Node CLI: valid, errors, checks and correspondence. The trust-file flags allowLegacyOnly and allowLegacyV2 were removed under decision D24; a trust file that sets either is refused with exit 2.

Python API

import json
from parmana_verifier import parse_trust_policy, verify_execution_trust_record

record = json.load(open("proof.json"))
policy = parse_trust_policy(json.load(open("trust.json")))

result = verify_execution_trust_record(record, policy.keys, policy.hybrid_required_from)
print(result["valid"], result["errors"])

Trust file

The trust file lists each key you accept, pinned by its fingerprint. See the main README for the format. The verifier never fetches keys.

Tests

cd python
pip install -e ".[test]"
pytest

The tests run the shared test vectors in ../test/vectors, check the canonical serialization against JavaScript's number and string formatting, and generate Ed25519 records at test time to cover the trust rules and the CLI.