Proof certificates

A proof certificate is the receipt of one AI call. It answers, for an auditor who was not there: what was asked, what actually left toward the model provider after personal data was masked, what came back, which provider and model answered, and in what order this happened relative to every other certificate.

Three properties make it worth keeping next to the business record it supports:

• It holds no content. Prompts and answers are committed by SHA-256 only, so a certificate can be sent to a client, an insurer or a regulator as is.
• It cannot be forged or edited. The document is signed with an Ed25519 key held by the Gateway. Changing one character changes the hash and breaks the signature.
• It cannot be silently removed. Each certificate contains the hash of the previous one in a single chain, so a deleted certificate leaves a hole that every verifier can see.

Every successful call on POST /v1/chat/completions and POST /v1/messages carries the id in the x-pulse-proof response header. It has the form pf_ followed by 32 hex characters. On the OpenAI dialect the same id also appears in the completion id (chatcmpl-pf_...) and in the pulse.proof field of the body.

On a streamed response the header is sent with the first byte, before any token, so you have the id even if the stream is interrupted. The certificate itself is persisted before the final [DONE] event (OpenAI dialect), so it is fetchable the moment your stream iterator returns.

A proof failure never fails a completion that was already produced. In the rare case where the certificate could not be written, the header is present but the fetch returns 404; treat that as an incident to report rather than as a client error.

GET /v1/proofs/:id returns the envelope below. The payload is the signed document; the other fields are the signature material and bookkeeping.

Verifying anything requires reproducing the exact bytes that were hashed. The rule is short:

1. Strings, numbers, booleans and null are serialised with standard JSON (JSON.stringify semantics).
2. Arrays keep their order: [a,b,c] with no spaces.
3. Objects have their keys sorted in ascending order, recursively, and any key whose value is undefined is dropped: {"a":1,"b":2} with no spaces.
4. The result is encoded as UTF-8 before hashing.

In Python, json.dumps(value, sort_keys=True, separators=(',', ':'), ensure_ascii=False) produces the same bytes for the integers, strings and nulls that certificates contain. ensure_ascii=False matters as soon as an agent name or a source file name has an accent.

Signature. The Gateway signs the 64-character hex payload_hash string (as UTF-8 bytes, not the raw digest) with an Ed25519 private key generated on first start and stored with the installation. The matching public key is served openly at GET /v1/gateway/public-key in SPKI PEM form.

Chain. Every attestation the engine issues, a completion, a verification report, a register export, is appended to one sequence. Each document includes its chainIndex and the payload_hash of the previous one as prevHash. Two consequences worth knowing:

• The chain is global to the installation, not per workspace. Your own certificates are interleaved with others', so consecutive ids of yours do not have consecutive indexes. You can only rebuild a link offline when you hold both neighbouring certificates.
• A certificate you are not allowed to read (another workspace's) is indistinguishable from a missing one. The server-side verification below checks the link for you, because it can see the whole chain.

This is the check an auditor runs. It needs two files and no network, no account and no trust in the server: the certificate JSON and the public key PEM. It proves that the payload is byte-for-byte what the Gateway signed.

A certificate is strong evidence about the pipeline, and says nothing beyond it. State the limits when you show one to someone:

• Not that the answer is correct. It proves what was answered, not that it is true. To check an answer against your documents, use Le Vérificateur.
• Not the content. The certificate holds hashes. Whoever holds the original text can confirm a match; whoever holds only the certificate learns the shape of the exchange, not its substance.
• Not independent of the Gateway. The signing key belongs to the Gateway. The certificate proves the document was issued by this installation and not edited since; it cannot prove that the installation recorded the truth, for example that the provider received exactly the masked text hashed in egress.sha256. That hash is computed by the Gateway, which is the party being audited.
• Not the provider's behaviour. Retention, training use and logging on the provider side are governed by your contract with the provider. The certificate tells you which provider and model answered, and whether the call stayed local.
• Not that the answer used the grounding faithfully. grounding shows which passages were supplied to the model, not that the model quoted them accurately.
• Not a trusted timestamp. issuedAt comes from the Gateway clock and is signed, but it is not countersigned by an independent time authority. The chain proves order, not wall-clock time.
• Not completeness of your own records. A call that was never made through the Gateway has no certificate. The chain exposes deleted certificates, not calls made elsewhere.
• Not cost. Billing in questions is not part of the document. Usage tokens are included for transparency.