Transparency log

CloakAPI operates an append-only transparency log for receipt issuances. The log allows third parties to verify that a specific receipt was genuinely produced by the gateway and was not retroactively deleted or modified.

---

Design

Append-only seed chain

Each receipt issuance writes one entry to the transparency_seeds table. Entries form a forward-linked hash chain:

seed[n].chain_hash = SHA-256(seed[n-1].chain_hash || receipt_id[n] || timestamp[n])

Properties:

• Append-only — entries cannot be deleted or modified without breaking all subsequent chain hashes.
• Deterministic — given the full sequence of receipt_id and timestamp values, anyone can recompute the chain and verify consistency.
• Receipt-linked — each seed entry references the receipt ID it was created for, so a specific receipt can be located in the chain.

Note

The current implementation uses a database-backed append-only table with a chain hash column. Merkle tree roots and third-party witness gossip (for external auditability) are planned for a future release — see Roadmap.

---

Public feed

https://api.cloakapi.io/api/v1/transparency/seeds.jsonl

• Format: JSONL (newline-delimited JSON), one entry per line.
• Entries are append-only and ordered by insertion sequence.
• The feed does not paginate — it streams all entries from genesis to current tail. For large feeds, use the ?since=<chain_hash> query parameter to resume from a checkpoint.

Entry schema

{
  "seq":        12345,
  "receipt_id": "rcpt_01HVXXXXXXXXXXXXXXXXXX",
  "org_id":     "org_YYYYYYYYY",
  "timestamp":  "2026-05-04T10:23:45.123Z",
  "chain_hash": "sha256:<hex>"
}

Field	Description
seq	Monotonic sequence number, gap-free
receipt_id	Opaque receipt identifier matching the id field in the signed receipt envelope
org_id	Org that issued the receipt (only present if org has enabled transparency participation)
timestamp	UTC ISO-8601 timestamp of issuance
chain_hash	SHA-256 of the previous chain hash concatenated with this entry’s receipt_id and timestamp

---

Per-org opt-in

Transparency participation is opt-in per organisation. When disabled (the default), receipts are still cryptographically signed and verifiable against the JWKS, but they do not appear in the public seed feed.

To enable:

1. Go to Settings → Privacy & compliance → Transparency log.
2. Toggle Contribute receipts to public transparency feed.
3. Changes take effect immediately for new receipts. Historical receipts are not backfilled.

Caution

When transparency is enabled, receipt_id and org_id become public. Do not enable if your organisation’s identity or receipt volume is itself sensitive.

---

How to verify a single receipt against the log

Given a receipt envelope (from the X-CloakAPI-Receipt-v2 response header or a stored .receipt.json file):

1. Extract the receipt ID. The id field in the receipt JSON, e.g. rcpt_01HVXXXXXXXXXXXXXXXXXX.

2. Fetch the public feed (or download a snapshot) from https://api.cloakapi.io/api/v1/transparency/seeds.jsonl.

3. Find the entry with receipt_id matching your receipt. The entry must exist for the receipt to be in the log.

4. Verify the chain hash at that entry by recomputing:

   expected = SHA-256(prev_chain_hash || entry.receipt_id || entry.timestamp)

   where prev_chain_hash is the chain_hash of the immediately preceding entry (or a known genesis value for seq=0).

5. Verify the receipt signature using the JWKS:

   https://api.cloakapi.io/api/.well-known/cloakapi-receipt-pubkeys.jwks

   Match kid in the receipt header to the JWKS entry, then verify the ECDSA P-256 signature over the receipt body.

Both checks together confirm: (a) the receipt was produced by CloakAPI’s signing key, and (b) it appears in the append-only public log.

Reference verification code is published: a Python reference verifier at signedreceipts.org/source/reference-python, a JS/TS reference verifier at signedreceipts.org/source/reference-typescript, and a live in-browser verifier at app.cloakapi.io/receipt-verifier — see Reproducibility.

---

Roadmap

The following features are planned but not yet shipped:

Feature	Status
Merkle tree roots (periodic checkpoint hashes)	Planned post-launch
Third-party witness gossip (external log mirrors)	Planned post-launch
Signed tree heads (STH) in the style of RFC 9162)	Planned
Self-contained feed snapshots with inclusion proofs	Planned

The current feed is an append-only chain suitable for manual and automated sequential verification. It is not yet a full Certificate Transparency-style log with inclusion proofs.