Valid HATS Bundle Walkthrough

Version: 1.0.0
Status: Production
Last Updated: 2026-05-23
Editor: Eric Beans, H33.ai, Inc.
Canonical URL: https://h33.ai/verification/valid-bundle/

1. Scope

This walkthrough demonstrates end-to-end verification of a valid HATS governance bundle containing three governance nodes. The bundle represents a complete attestation session: an agent initiates a policy check, executes a computation under that policy, and records the result. All nodes are correctly signed with three post-quantum signature families, all predecessor hashes are valid, and all timestamps are monotonically increasing.

The expected verifier output is VERIFIED with all three nodes passing all checks.

2. Definitions

Session: A temporally ordered sequence of governance nodes sharing a common session_id. A session begins with a node whose predecessor_hash is the null hash and ends when the session is explicitly closed or a timeout occurs.
Null Hash: The 32-byte zero value 0x0000...0000 used as the predecessor_hash for the first node in a session. Indicates no preceding node exists.
Governance Node: A single attested action within a session. Contains the action type, payload hash, timestamp, predecessor hash, and multi-family post-quantum signatures.
Multi-Family Signature: The set of independent post-quantum signatures (ML-DSA-65, FALCON-512, SLH-DSA-SHA2-128f) applied to a governance node. All families present MUST verify independently.

3. Input Bundle

The following JSON represents a valid governance bundle with three nodes. Save this content to a file named valid-bundle.json.

valid-bundle.json

{
  "schema_version": "1.0.0",
  "bundle_id": "b8f3c2a1-4e5d-4a6b-9c8d-7e6f5a4b3c2d",
  "session_id": "s-20260515-143000-a1b2c3",
  "tenant_id": "t-9f8e7d6c-5b4a-3c2d-1e0f-a9b8c7d6e5f4",
  "created_at": "2026-05-15T14:30:00.000Z",
  "nodes": [
    {
      "node_index": 0,
      "action_type": "POLICY_BIND",
      "payload_hash": "a3f1b2c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1",
      "timestamp": "2026-05-15T14:30:00.000Z",
      "predecessor_hash": "0000000000000000000000000000000000000000000000000000000000000000",
      "node_hash": "c7a8b9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7",
      "signatures": {
        "ml_dsa_65": "ML-DSA-65:3045022100...truncated_for_display...b8c9d0e1f2",
        "falcon_512": "FALCON-512:3045022100...truncated_for_display...a1b2c3d4e5",
        "slh_dsa": "SLH-DSA-SHA2-128f:3045022100...truncated_for_display...f6a7b8c9d0"
      }
    },
    {
      "node_index": 1,
      "action_type": "COMPUTE_EXECUTE",
      "payload_hash": "d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4",
      "timestamp": "2026-05-15T14:30:01.247Z",
      "predecessor_hash": "c7a8b9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7",
      "node_hash": "e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5",
      "signatures": {
        "ml_dsa_65": "ML-DSA-65:3045022100...truncated_for_display...c9d0e1f2a3",
        "falcon_512": "FALCON-512:3045022100...truncated_for_display...b2c3d4e5f6",
        "slh_dsa": "SLH-DSA-SHA2-128f:3045022100...truncated_for_display...a7b8c9d0e1"
      }
    },
    {
      "node_index": 2,
      "action_type": "RESULT_RECORD",
      "payload_hash": "f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6",
      "timestamp": "2026-05-15T14:30:02.891Z",
      "predecessor_hash": "e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5",
      "node_hash": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1",
      "signatures": {
        "ml_dsa_65": "ML-DSA-65:3045022100...truncated_for_display...d0e1f2a3b4",
        "falcon_512": "FALCON-512:3045022100...truncated_for_display...c3d4e5f6a7",
        "slh_dsa": "SLH-DSA-SHA2-128f:3045022100...truncated_for_display...b8c9d0e1f2"
      }
    }
  ]
}

Signature values are truncated for display. In a production bundle, each ML-DSA-65 signature is 3,309 bytes, each FALCON-512 signature is approximately 690 bytes, and each SLH-DSA-SHA2-128f signature is 17,088 bytes. Full test vectors with complete signatures are available in the Conformance Vectors repository.

4. CLI Command

Execute the following command to verify the bundle:

$ hats verify valid-bundle.json

The verifier accepts the following optional flags:

Flag	Default	Description
`--verbose`	off	Print per-node verification details
`--format`	`text`	Output format: `text`, `json`, or `csv`
`--strict`	on	Reject bundles with unknown fields
`--timing`	off	Include per-check latency in output

5. Verification Procedure

The verifier executes the following checks in order. If any check fails, verification halts and the failure is reported with the specific node index and check name.

5.1. Schema Validation

The verifier validates the bundle against the HATS Governance Bundle Schema v1.0. This includes structural checks (required fields, field types, value constraints) and semantic checks (node indices are sequential starting from 0, timestamps are ISO 8601 with millisecond precision, hash values are 64-character lowercase hexadecimal strings).

5.2. Chain Integrity

For each node at index i where i > 0:

Compute the canonical serialization of node i-1.
Compute SHA3-256 over the canonical serialization.
Compare the result against node i's predecessor_hash field.
If the values differ, report CHAIN_BREAK at position i.

For node 0, the verifier confirms that predecessor_hash is the null hash (64 zero characters).

5.3. Node Hash Verification

For each node, the verifier computes the SHA3-256 digest of the node's canonical form (all fields except node_hash and signatures) and compares it against the declared node_hash. A mismatch indicates the node content was modified after hashing.

5.4. Signature Verification (AND-Gate)

For each node, the verifier independently verifies every signature family present in the signatures object:

ML-DSA-65: Verify the ML-DSA-65 signature over the node_hash using the session's ML-DSA public key. Algorithm per NIST FIPS 204.
FALCON-512: Verify the FALCON-512 signature over the node_hash using the session's FALCON public key. Algorithm per the FALCON specification (Round 3).
SLH-DSA-SHA2-128f: Verify the SLH-DSA signature over the node_hash using the session's SLH-DSA public key. Algorithm per NIST FIPS 205.

All three families MUST verify. If any single family fails, the entire node fails verification. This is the AND-gate requirement: the attestation is only as strong as all of its signature families combined.

5.5. Temporal Ordering

The verifier confirms that timestamps are strictly monotonically increasing across nodes. For each node at index i where i > 0, the timestamp of node i MUST be strictly greater than the timestamp of node i-1.

6. Expected Output

stdout

$ hats verify valid-bundle.json

HATS Verifier v1.0.0
Bundle: b8f3c2a1-4e5d-4a6b-9c8d-7e6f5a4b3c2d
Session: s-20260515-143000-a1b2c3

Checking schema .............. OK
Checking chain integrity ..... OK (3 links)
Checking node hashes ......... OK (3 nodes)
Checking signatures .......... OK (9 signatures, 3 families x 3 nodes)
Checking temporal ordering ... OK (monotonic)

Result: VERIFIED
Nodes checked: 3/3
Signatures verified: 9/9
Chain links validated: 2/2
Duration: 47ms

A VERIFIED result indicates that the governance bundle is structurally valid, cryptographically intact, and temporally consistent. The verifier has confirmed that no node was modified after signing, no node was removed or inserted, and all three post-quantum signature families independently verify for every node.

7. Verbose Output

With the --verbose flag, the verifier prints per-node details:

$ hats verify --verbose valid-bundle.json

HATS Verifier v1.0.0
Bundle: b8f3c2a1-4e5d-4a6b-9c8d-7e6f5a4b3c2d

Node 0 [POLICY_BIND]
  predecessor_hash: null (genesis node)
  node_hash:        c7a8b9d0...e5f6a7 (recomputed: match)
  ML-DSA-65:        VALID (2,592 bytes verified)
  FALCON-512:       VALID (690 bytes verified)
  SLH-DSA-128f:     VALID (17,088 bytes verified)
  timestamp:        2026-05-15T14:30:00.000Z

Node 1 [COMPUTE_EXECUTE]
  predecessor_hash: c7a8b9d0...e5f6a7 (matches node 0 hash)
  node_hash:        e5f6a7b8...d4e5 (recomputed: match)
  ML-DSA-65:        VALID
  FALCON-512:       VALID
  SLH-DSA-128f:     VALID
  timestamp:        2026-05-15T14:30:01.247Z (delta: +1.247s)

Node 2 [RESULT_RECORD]
  predecessor_hash: e5f6a7b8...d4e5 (matches node 1 hash)
  node_hash:        a1b2c3d4...f0a1 (recomputed: match)
  ML-DSA-65:        VALID
  FALCON-512:       VALID
  SLH-DSA-128f:     VALID
  timestamp:        2026-05-15T14:30:02.891Z (delta: +1.644s)

Result: VERIFIED (3/3 nodes, 9/9 signatures)

8. JSON Output

With --format json, the verifier produces machine-readable output:

{
  "status": "VERIFIED",
  "bundle_id": "b8f3c2a1-4e5d-4a6b-9c8d-7e6f5a4b3c2d",
  "session_id": "s-20260515-143000-a1b2c3",
  "nodes_checked": 3,
  "nodes_passed": 3,
  "signatures_checked": 9,
  "signatures_passed": 9,
  "chain_links_checked": 2,
  "chain_links_passed": 2,
  "temporal_ordering": "monotonic",
  "duration_ms": 47,
  "verifier_version": "1.0.0",
  "nodes": [
    { "index": 0, "action_type": "POLICY_BIND", "status": "PASS", "chain": "PASS", "hash": "PASS", "signatures": { "ml_dsa_65": "PASS", "falcon_512": "PASS", "slh_dsa": "PASS" } },
    { "index": 1, "action_type": "COMPUTE_EXECUTE", "status": "PASS", "chain": "PASS", "hash": "PASS", "signatures": { "ml_dsa_65": "PASS", "falcon_512": "PASS", "slh_dsa": "PASS" } },
    { "index": 2, "action_type": "RESULT_RECORD", "status": "PASS", "chain": "PASS", "hash": "PASS", "signatures": { "ml_dsa_65": "PASS", "falcon_512": "PASS", "slh_dsa": "PASS" } }
  ]
}

9. Failure Modes

This walkthrough demonstrates the successful case. No failures are expected. For failure scenarios, see the following walkthroughs:

Tampered Receipt Detection -- hash mismatch when node content is modified post-signing.
Broken Chain Detection -- chain discontinuity when a node is deleted.
Invalid PQ Signature Detection -- AND-gate failure when one signature family is corrupted.
Replay Determinism Verification -- confirms deterministic output across repeated executions.

10. Conformance

A verifier implementation is conformant with this walkthrough if, given the input bundle above and valid cryptographic keys for the specified session, it produces the VERIFIED status with 3/3 nodes passed and 9/9 signatures verified. The chain link count MUST be 2 (the number of non-genesis predecessor links). The temporal ordering check MUST report monotonic.

Conformance test vector ID: HATS-VW-001-VALID-3NODE

Related Walkthroughs & Specifications

Verification Index Tampered Receipt Broken Chain Invalid Signature Replay Determinism Conformance Suite H33-74 Specification