Skip to main content
The AlgoVoi compliance receipt verifier decodes, cryptographically verifies, and structurally validates a compact JWS compliance receipt against AlgoVoi’s Ed25519 signing key. It is standalone — a recipient can verify any receipt without contacting AlgoVoi’s gateway, control plane, or JWKS endpoint (the public key can be fetched once and cached). Three deployment modes ship today, all from the same source code with the same byte-for-byte verification logic:

Hosted endpoint

POST api.algovoi.co.uk/v1/receipt/verify — submit any JWS receipt, get back a structured pass/fail report. Stateless. Rate-limited at 120 req/min.

Python (PyPI)

pip install algovoi-receipt-verifier. Exposes verify_compliance_receipt() and ReceiptVerificationError with nine typed error codes.

TypeScript (npm)

npm install @algovoi/receipt-verifier. Byte-for-byte parity with the Python sibling proven by 13 shared cross-validation vectors.

​
What the verifier checks

#CheckError if fails
1JWS format — three-part header.payload.signature base64urlINVALID_JWS_FORMAT
2Algorithm whitelist — EdDSA, ES256K, RS256 only; reject without fallbackUNSUPPORTED_ALG
3Ed25519 signature — cryptographic verification against the issuer’s public keyTAMPERED_SIGNATURE
4canon_version — must be in the supported registry (jcs-rfc8785-v1)UNSUPPORTED_CANON_VERSION
5JCS re-canonicalisation — re-canonicalise payload via RFC 8785; compare byte-for-byteNON_CANONICAL_PAYLOAD
6Required fields — payer_ref, screen_result, screen_timestamp_ms, screen_provider_did, jurisdiction_flags, canon_versionMISSING_FIELD
7screen_result enum — must be ALLOW, REFER, or DENYINVALID_PAYLOAD
8payment_hash binding — if expected_payment_hash is supplied, must match exactlyPAYMENT_HASH_MISMATCH
All nine error codes map 1:1 to the Phase 8 Agent Trust Bench threat surface (OWASP LLM09).

​
Hosted endpoint

curl -X POST https://api.algovoi.co.uk/v1/receipt/verify \
  -H 'Content-Type: application/json' \
  -d '{
    "jws": "<compact-jws>",
    "expected_payment_hash": "sha256:<hex>"
  }'
Response on success (200 OK): 
{
  "verified": true,
  "screen_result": "ALLOW",
  "settlement_status": "SETTLED",
  "canon_version": "jcs-rfc8785-v1",
  "alg": "EdDSA",
  "payer_ref": "payer-abc123"
}
On failure (422 Unprocessable Entity): 
{
  "verified": false,
  "error_code": "TAMPERED_SIGNATURE",
  "error_message": "signature verification failed"
}
Optional: pass jwks to verify a receipt signed by a third-party key rather than AlgoVoi’s platform key.

​
Programmatic use (Python)

from algovoi_receipt_verifier import verify_compliance_receipt, ReceiptVerificationError

# Fetch AlgoVoi's public key once and cache it
import urllib.request, json
jwks = json.loads(urllib.request.urlopen(
    'https://api.algovoi.co.uk/.well-known/jwks.json'
).read())

try:
    receipt = verify_compliance_receipt(
        jws_token,
        jwks=jwks,
        expected_payment_hash='sha256:...',
    )
    print(receipt.screen_result)   # ALLOW / REFER / DENY
except ReceiptVerificationError as e:
    print(e.code, e.message)
    # TAMPERED_SIGNATURE / UNSUPPORTED_ALG / UNSUPPORTED_CANON_VERSION /
    # NON_CANONICAL_PAYLOAD / PAYMENT_HASH_MISMATCH / MISSING_ENVELOPE /
    # MISSING_FIELD / INVALID_JWS_FORMAT / INVALID_PAYLOAD

​
Programmatic use (TypeScript)

import { verifyComplianceReceipt, ReceiptVerificationError } from '@algovoi/receipt-verifier';

// Fetch AlgoVoi's public key once and cache it
const jwks = await fetch('https://api.algovoi.co.uk/.well-known/jwks.json')
  .then(r => r.json());

try {
  const receipt = verifyComplianceReceipt({
    jws: token,
    jwks,
    expectedPaymentHash: 'sha256:...',
  });
  console.log(receipt.screenResult);  // ALLOW / REFER / DENY
} catch (e) {
  if (e instanceof ReceiptVerificationError) {
    console.error(e.code, e.message);
  }
}

​
Phase 8 ATB threat mapping

Each of the eight invalid cross-validation vectors maps directly to a Phase 8 Agent Trust Bench threat profile:
VectorATB threatError code
i01_tampered_signature.jsonreceipt-tampered-sigTAMPERED_SIGNATURE
i02_unsupported_alg.jsonreceipt-alg-unknownUNSUPPORTED_ALG
i03_unsupported_canon_version.jsonreceipt-canon-version-mismatchUNSUPPORTED_CANON_VERSION
i04_payment_hash_mismatch.jsonreceipt-replay-modifiedPAYMENT_HASH_MISMATCH
i05_missing_envelope.jsonreceipt-missing-envelopeMISSING_ENVELOPE
i06_non_canonical_payload.jsonreceipt-bad-jcsTAMPERED_SIGNATURE or NON_CANONICAL_PAYLOAD
i07_malformed_jws.json—INVALID_JWS_FORMAT
i08_missing_screen_result.json—MISSING_FIELD

​
Cross-validation vectors

13 self-contained JSON fixtures (vectors/valid/ and vectors/invalid/) are run by both test suites. Each fixture embeds its own jwks — no external key store required.
SuiteUnit testsVector testsE2E (from registry)Total
Python2813/1313/1341/41
TypeScript19 (incl. vectors)—13/1319/19
E2E tests install from the live registries (algovoi-receipt-verifier==0.1.0 from PyPI and @algovoi/receipt-verifier@0.1.0 from npm) into a clean environment and run all 13 vectors. Source: e2e/test_registry_python.py and e2e/test_registry_npm.mjs. Regenerate vectors at any time: 
python vectors/generate_vectors.py

​
JWKS endpoint

AlgoVoi’s public key is available at: 
GET https://api.algovoi.co.uk/.well-known/jwks.json
Pass the response body directly as jwks. The kid in the JWS header is used for key selection; falls back to the first key if no kid match.

​
See also

  • Compliance gate — the POST /compliance/screen endpoint that emits the JWS receipts this verifier checks
  • JCS canonicalisation substrate — the build_compliance_receipt() emitter and JCS substrate underlying the canon_version pin
  • Audit verifier — selective-disclosure audit bundle verifier; composes with receipt verification in the compliance audit chain
  • Composite trust query — sits above this verifier; aggregates receipt signals into a single TRUSTED / PROVISIONAL / UNTRUSTED verdict
  • Settlement attestation — multi-chain settlement record that pairs with the compliance receipt
  • Agent Trust Bench — Phase 8 receipt/substrate-integrity profiles (OWASP LLM09)