> ## 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.

# Audit verifier

> Standalone reference verifier for AlgoVoi selective disclosure audit bundles. Hosted, pip installable and npm installable, no infrastructure trust needed.

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:

<CardGroup cols={2}>
  <Card title="Hosted endpoint" icon="cloud" href="https://verify.algovoi.co.uk">
    `verify.algovoi.co.uk` -- POST any audit bundle JSON, get back a
    structured pass/fail report. Stateless, no bundle retained. Rate-limited.
  </Card>

  <Card title="Python (PyPI)" icon="python" href="https://pypi.org/project/algovoi-audit-verifier/">
    `pip install algovoi-audit-verifier`. Bundles the CLI (`algovoi-verify`),
    the HTTP server (`algovoi-verify-server`), and the demo bundle generator.
  </Card>
</CardGroup>

## What the verifier checks

| # | Check                      | What it proves                                                                                                                                            |
| - | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1 | `per_row_content_hash`     | Each row's stored `content_hash` matches `SHA-256(JCS(canonical-fields))` -- per-row tamper-evidence                                                      |
| 2 | `continuity`               | `prev_hash` walks unbroken across `rows + bridging_rows` ordered by `chain_position` -- no fabricated gap or reorder                                      |
| 3 | `bundle_signature`         | HMAC-SHA256 over `JCS(bundle - signature)` matches the stored `bundle_signature.hex` -- proves AlgoVoi emission (when the shared signing key is supplied) |
| 4 | `selection_criteria_match` | Selected rows actually match the filter declared in `selection_criteria` (when exact-match filters are set)                                               |
| 5 | `off_vm_anchor`            | Off-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 `skip`ed (no signing key supplied, no manifest available,
etc.). Any `fail` or `fatal` flips the verdict.

## Hosted endpoint

```bash theme={null}
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](https://verify.algovoi.co.uk/docs).

## Programmatic use (Python)

```python theme={null}
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`):

```bash theme={null}
pip install 'algovoi-audit-verifier[server]'
algovoi-verify-server
# POST bundles to http://localhost:8000/verify
```

## Programmatic use (TypeScript)

```ts theme={null}
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](https://github.com/chopmob-cloud/algovoi-audit-verifier)
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: **86 tests** (Python 56 + TypeScript 30), including
the cross-implementation 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:

```bash theme={null}
# 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](/canonicalisation-substrate) (pinned to
`urn:x402:canonicalisation:jcs-rfc8785-v1`) and the
[conformance corpus](/conformance-vectors). The substrate
reference implementations in Python and TypeScript are available as
[`algovoi-substrate`](https://pypi.org/project/algovoi-substrate/) on
PyPI and [`@algovoi/substrate`](https://www.npmjs.com/package/@algovoi/substrate)
on npm.

## See also

* [JCS canonicalisation substrate](/canonicalisation-substrate)
* [Conformance vectors](/conformance-vectors)
* [Ecosystem contributions](/ecosystem-contributions)
* [Compliance](/compliance) -- how AlgoVoi's `/compliance/attestation` chain is the live reference exhibit the verifier was built to audit