Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.algovoi.co.uk/llms.txt

Use this file to discover all available pages before exploring further.

The AlgoVoi audit verifier is the reference implementation that confirms a selective-disclosure audit bundle is genuine, untampered, and chain-consistent. It is standalone — an auditor can run it against any AlgoVoi-issued bundle without trusting AlgoVoi’s gateway, control plane, signing service, or any single attestation surface. Three deployment modes ship today, all from the same source code with the same byte-for-byte verification logic:

Hosted endpoint

verify.algovoi.co.uk — POST any audit bundle JSON, get back a structured pass/fail report. Stateless, no bundle retained. Rate-limited.

Python (PyPI)

pip install algovoi-audit-verifier. Bundles the CLI (algovoi-verify), the HTTP server (algovoi-verify-server), and the demo bundle generator.

TypeScript (npm)

npm install @algovoi/audit-verifier. Byte-for-byte parity with the Python sibling proven by 9 cross-impl tests. Same canonical bytes, same SHA-256, same HMAC on identical inputs.

​
What the verifier checks

#CheckWhat it proves
1per_row_content_hashEach row’s stored content_hash matches SHA-256(JCS(canonical-fields)) — per-row tamper-evidence
2continuityprev_hash walks unbroken across rows + bridging_rows ordered by chain_position — no fabricated gap or reorder
3bundle_signatureHMAC-SHA256 over JCS(bundle - signature) matches the stored bundle_signature.hex — proves AlgoVoi emission (when the shared signing key is supplied)
4selection_criteria_matchSelected rows actually match the filter declared in selection_criteria (when exact-match filters are set)
5off_vm_anchorOff-VM Object-Lock manifest tail entry matches chain_anchor.current_head (when a manifest directory is supplied)
A bundle passes when all_passed == true — every applicable check is ok or legitimately skiped (no signing key supplied, no manifest available, etc.). Any fail or fatal flips the verdict.

​
Hosted endpoint

curl -X POST -H 'Content-Type: application/json' \
    --data-binary @audit-bundle.json \
    https://verify.algovoi.co.uk/verify
Optional bundle-signature verification: pass the shared key in the X-Audit-Bundle-Key header. The hosted endpoint never logs or retains submitted bundles; the verification is in-memory and the response is the only side effect. Response is 200 OK on all_passed == true, 422 Unprocessable Entity on any failed check, 400 Bad Request on malformed JSON or empty body, 413 Payload Too Large for bodies above 5 MiB. OpenAPI / Swagger docs at verify.algovoi.co.uk/docs.

​
Programmatic use (Python)

import json
from algovoi_audit_verifier import verify_bundle  # not literal -- see below

# CLI:
#   algovoi-verify bundle.json --signing-key 'demo-key-not-for-production-use'

# Library:
import verify_audit_bundle as v
bundle = json.load(open('audit-bundle.json'))
report = v.verify_bundle(bundle, signing_key='shared-secret')
print(report.render())             # human-readable
print(report.to_dict())            # machine-readable
Run the HTTP server locally (same code path as verify.algovoi.co.uk): 
pip install 'algovoi-audit-verifier[server]'
algovoi-verify-server
# POST bundles to http://localhost:8000/verify

​
Programmatic use (TypeScript)

import { verifyBundle } from '@algovoi/audit-verifier';

const bundle = JSON.parse(fs.readFileSync('audit-bundle.json', 'utf-8'));
const report = await verifyBundle(bundle, {
  signingKey: process.env.AUDIT_BUNDLE_KEY,
});

console.log(report.render());          // human-readable PASS/FAIL
console.log(report.toJSON());          // machine-readable
if (!report.allPassed) process.exit(1);

​
Cross-implementation parity

The Python and TypeScript verifiers are byte-for-byte equivalent. The parity is exercised by 9 cross-impl tests in the repository which generate bundles in Python and verify them in TypeScript (and vice versa). The matrix:
  • Same JCS canonical bytes for the same input object (RFC 8785)
  • Same SHA-256 hash for the same canonical preimage
  • Same HMAC-SHA256 signature for the same (bundle - signature, key) pair
  • Same per-row content_hash for the same row content
  • Same bundle_signature.hex byte-for-byte across all 4 chain types (audit_log, screening_hits, compliance_events, negotiation_trace_events)
  • Same check-report shape (all_passed, fatal[], checks[])
Total test coverage: 103 tests (Python 65 + TypeScript 38) including the 9 cross-impl parity assertions.

​
Demo bundle

Both implementations ship a demo bundle generator that produces a synthetic signed bundle for smoke-testing the verifier without requiring a real AlgoVoi-issued bundle: 
# Python
algovoi-verify-demo > demo_bundle.json
algovoi-verify demo_bundle.json --signing-key 'demo-key-not-for-production-use'

# TypeScript / Node
node -e "import('@algovoi/audit-verifier').then(async m => { \
  const b = m.buildDemoBundle(); \
  const r = await m.verifyBundle(b, { signingKey: 'demo-key-not-for-production-use' }); \
  console.log(r.render()); \
})"
Both produce identical output (modulo the bundle_emitted_at timestamp).

​
Substrate

The verifier composes against the JCS canonicalisation substrate (pinned to urn:x402:canonicalisation:jcs-rfc8785-v1) and the 53-vector conformance corpus. The substrate reference implementations in Python and TypeScript are available as algovoi-substrate on PyPI and @algovoi/substrate on npm.

​
See also