# VMARAS Standalone Evidence Packet Verifier

Check a VMARAS Evidence Packet yourself: no VMARAS account, no network, no
dependencies. Two equivalent tools:

- `verifier.html`: open it in a current browser and drop in the packet.
- `verifier.py`: Python 3.8+ standard library (uses `cryptography` for faster
  Ed25519 if installed; otherwise a built-in RFC 8032 implementation).

Both tools and the server implement the same rules, and the test suite
(`tests/node/proof/proofChain.test.js`) checks that they agree.

## What is checked

For a v2 packet (`"format": "vmaras-evidence-packet-v2"`):

1. **Receipt hashes are recomputed** from each receipt's own fields:
   `SHA-256("VMARAS-RECEIPT-v2\n" + JCS(receipt))`, where JCS is RFC 8785
   canonical JSON over tenant, chain, sequence, recall, action, actor, role,
   entity, the full nested payload, description, input/output hashes,
   previous hash and signing time. Editing any of them is detected.
2. **Chain linkage and sequence continuity**: each `prev_hash` is the hash of
   the receipt before it, and sequence numbers have no gaps (deleted or
   inserted receipts are detected).
3. **Input hashes**: `input_hash = SHA-256(payload_json)`.
4. **Ed25519 signatures** on every receipt hash.
5. **Integrity Manifest**: ordered hash list, chain head and the RFC 6962
   Merkle root (leaf `0x00`, node `0x01`).
6. **Packet signature**: Ed25519 over
   `SHA-256("VMARAS-PACKET-v2\n" + JCS(packet without packet_signature))`.
7. **Signing-time order.**
8. **Evidence-bound approvals.** For every `ALERT_ACKNOWLEDGED` receipt that
   carries an approval, the approval digest is recomputed:
   `SHA-256("VMARAS-APPROVAL-v2\n" + JCS({evidence_state, upto_sequence,
   proposed_action, policy_context, approver_id}))`, where `evidence_state` is
   the SHA-256 of the receipt hashes 0..N joined with `|`. The server's
   Ed25519 approval signature over `"VMARAS-APPROVAL-v2\n" + digest` is checked.
9. **Passkey (WebAuthn) approval confirmations**, when the receipt has
   `approval_passkey`. This is the approver's own signature and needs no
   VMARAS key: `clientDataJSON.type == "webauthn.get"`,
   `clientDataJSON.challenge == base64url(bytes(approval_digest))`,
   `authenticatorData.rpIdHash == SHA-256(rp_id)`, the UP and UV flags are
   set, the origin is on the RP ID, and the signature over
   `authenticatorData || SHA-256(clientDataJSON)` verifies with the COSE
   public key in the record (ES256, EdDSA and RS256). A server that edits the
   receipt and re-signs it with its own key still fails this check.

Legacy (v1) receipts inside a v2 packet are recomputed with the v1 rule;
their HMAC seal can only be checked by the server (or with `--hmac-key`).

Redacted packets hide PHI-named fields with salted hashes, so those receipts'
hashes cannot be recomputed. Their signatures are still checked, and the
report says how many were not recomputed.

## Pin the public key

A packet lists the public key that signed it, but a forger could list their
own. For an independent result, get the key from VMARAS separately:

```bash
curl https://<your-vmaras-host>/verify/keys > keys.json
python verifier.py packet.json --keys keys.json
# or: python verifier.py packet.json --pubkey <base64-ed25519-public-key>
```

Without a pinned key the result is `PASS (UNPINNED KEY)`.

### Pin approvers' passkeys

The passkey record names its public key and the key's SHA-256 fingerprint.
Each user sees the fingerprint of their passkeys under **My Account →
Passkeys** (also logged when the passkey is registered). Pin it to make sure
the approval was signed by that person's authenticator and not by a key
someone else added:

Also pin the **RP ID** (the site the passkeys belong to, `vmaras.com` for
production). Without it the RP ID recorded in the receipt is used and the
report carries a WARNING, because an assertion made for another site would
otherwise be checked against that site's own RP ID:

```bash
python verifier.py packet.json --keys keys.json --rp-id vmaras.com --passkey-fingerprint <sha256-hex>
```

In `verifier.html`, fill in "Expected passkey RP ID" and paste fingerprints
into "Approver passkey fingerprints".

The passkey check also refuses a record whose algorithm does not match its key
type (ES256 ↔ EC P-256, EdDSA ↔ Ed25519, RS256 ↔ RSA) and ECDSA signatures that
are not strict DER (trailing bytes, non-minimal integers), in both tools.

## CLI

```bash
python verifier.py packet.json --keys keys.json      # recommended
python verifier.py packet.json --verbose             # every receipt
python verifier.py packet.json --json                # for automation
```

Exit codes: `0` all checks passed with a pinned key, `1` a check failed or
the key was not pinned, `2` file error.

## Scope

A PASS proves the packet's receipts are exactly what VMARAS signed, in order,
with nothing removed. It does not prove the underlying operational data (for
example, a count entered by a user) was correct when it was recorded.

Patent Pending — MedNexLabs LLC
