Skip to content

Verify + get the badge

Building on CloakAPI means your users inherit a real, verifiable guarantee — but only if your integration actually keeps to it. The conformance suite and the “Verified by CloakAPI” badge make that falsifiable rather than a promise.

This page is a pointer. The conformance corpus and the badge/trademark governance rules are maintained alongside the platform (see below) — this page tells you where they live and how they fit the builder flow, so the two don’t drift.

Why verify

CloakAPI can guarantee the parts it controls — the sealed engine, the blind relay, the signed receipt (enforcement, pushed to ~100%). What it cannot see is whether your build wired those parts correctly: did you tokenise on the client before egress, do you actually emit and check receipts, do you keep your privacy claims inside the honest wording? The conformance suite tests exactly that residual, and the badge signals a build that passed.

The conformance suite

@cloakapi/conformance is a small CLI + programmatic API you point at the receipts your deployed integration actually produced — not a fixture corpus you run. Because CloakAPI is a blind pure-relay, it can’t inspect your server, so it proves correctness from the verifiable artifacts your build emits (OpenReceipt v3 receipts + declared engine identity). It reuses the exact same cryptography as the shipped @cloakapi/verify-widget (JCS → SHA-256 → P-256 raw r‖s).

Terminal window
# Point it at your integration's receipts (a v3 envelope, a countersigned result,
# or a JSON array = a chain). The engine floor is fetched from the gateway.
npx cloakapi-conformance --receipts ./session.json


# Air-gapped / CI: supply the floor yourself, no network.
npx cloakapi-conformance -r ./session.json --engine-hashes ./engine-hashes.json --offline


# Also verify a gateway countersignature against a JWKS; machine-readable output.
npx cloakapi-conformance -r ./cs-result.json --jwks ./jwks.json --json

It runs four checks, each with a plain PASS / FAIL / UNKNOWN (UNKNOWN = a fact a blind relay structurally cannot establish — never silently passed):

  • receipt-signatures — every receipt is cryptographically valid (verifies against the key embedded in the signed envelope, or the gateway JWKS for a countersigned result) and, for a chain, the receipts are hash-linked & monotonic.
  • engine-current — the declared engine_ruleset_version is at/above the current published floor (GET /api/v1/engine/hashes ruleset_version).
  • engine-genuine — the declared engine_binary_hash is on the official published allowlist (honestly UNKNOWN while the allowlist is unpublished).
  • client-side-tokenisation — the receipt attests tokenisation happened on-device before egress (Level-1: no_raw_pii_egress, a tokenised_body_hash, tier ≠ off).

Verdict: CONFORMANT only when nothing FAILs and the signature + client-side-tokenisation checks both PASS; NON-CONFORMANT if anything fails; INCONCLUSIVE if nothing failed but there wasn’t enough provable evidence. Exit codes: 0 CONFORMANT · 1 NON-CONFORMANT · 2 INCONCLUSIVE · 3 usage error — so you can gate CI on it. The same run is available programmatically:

import { runConformance, fetchEngineHashes } from '@cloakapi/conformance';
const engineHashes = await fetchEngineHashes('https://api.cloakapi.io');
const report = await runConformance(receipts, { engineHashes });
report.verdict; // 'CONFORMANT' | 'NON-CONFORMANT' | 'INCONCLUSIVE'

Note this is distinct from the vendor-neutral OpenReceipt spec conformance corpus (repo/tests/conformance, published at signedreceipts.org/conformance), which proves a verifier implementation reads the receipt format correctly. See Verifying a receipt and the OpenReceipt protocol for the receipt half of the contract.

Every run prints, verbatim, what it cannot prove — CloakAPI is blind to your server; PII detection is best-effort and fail-closed, never “100%”; gateway-witnessed facts need a countersignature; it checks the receipts you supply, so pair it with the end-user @cloakapi/verify-widget so your users can check their own live sessions.

The “Verified by CloakAPI” badge

Builds that pass conformance may display the “Verified by CloakAPI” badge. The badge is trademark-governed: it asserts a specific, tested claim (this build inherits the client-side guarantee and emits verifiable receipts), so its use is tied to passing the suite and to the honest-wording rules on the Build on CloakAPI page. The badge and governance rules are maintained with the conformance program; follow those rules rather than copying badge assets ad-hoc.

What the badge does not claim. It does not claim “100% detection” or “100% safe” — no build can, because detection is best-effort and fail-closed by design. It attests to the enforcement and receipt guarantees, and to honest client-side privacy wording. Keep your own copy inside those same lines.

How the badge is issued (honest)

There is no automated issuance service, registry, or signing backend today — the badge is a trademark-governed, self-attested claim, not a cryptographic entitlement. Displaying it requires a currently-passing run and honest wording:

  1. Self-attest (available now): run @cloakapi/conformance against your receipts; on CONFORMANT, generate the content-free attestation (badge/attestation.js → buildAttestation, no PII / no receipt bodies), host it next to your badge, and keep re-running it (e.g. in CI) so it stays current as the engine floor rises.
  2. Manual review (optional): email your attestation to trust@cloakapi.io. A human courtesy acknowledgement — not an automated entitlement.

Full terms — who may display it, honest-wording rules, and automatic revocation on floor-fail / sig-fail / tokenisation-fail — are in the badge governance doc (docs/governance/verified-by-cloakapi.md), shipped with the conformance program.

Where these live

  • Conformance CLI + programmatic API: @cloakapi/conformance (repo/packages/cloakapi-conformance — run against your emitted receipts).
  • Badge assets (theme-adaptive SVGs) + the attestation builder: shipped inside that same package (badge/).
  • Badge/trademark governance rules: docs/governance/verified-by-cloakapi.md — reference those, don’t duplicate.
  • The assurance model your build is measured against: Build on CloakAPI.
© 2026 CloakAPI · Made in the EU · Privacy · Terms · Security · Status · Trust