humanproof format specification

1. Conventions

The words MUST, MUST NOT, SHOULD and MAY have the meaning of RFC 2119. A conforming verifier is one that meets every MUST in this specification and gives, for each vector in the index (section 11), the result declared there.

The reference implementation is the humanproof-core library, in Rust, the same one that signs on Hummand’s server, runs in the humanproof-verify command-line verifier and, compiled to WebAssembly, in the public verifier at labs.hummand.com.br/verificar. Where this document and the reference implementation disagree, the disagreement is a defect to fix, and the vectors say which of the two is right.

2. Model

• Issuer: Hummand. Signs each object with a key whose public part is published.
• Tenant: Hummand’s customer. Each tenant has two chains of its own, the acts chain and the accesses chain, and no receipt of one tenant references a receipt of another.
• Act receipt (humanproof/1): issued when an act ends, whatever the result. Positive, negative, expired, cancelled, technical failure and revocation are all signed.
• Access receipt (humanproof-acesso/1): issued when someone opens the evidence of an act or the shared dossier. A denied attempt is signed too.
• Checkpoint (humanproof-ponto/1 and /2): a signed statement of how many receipts a chain had at an instant and which one was the last. It is what makes truncation of the end detectable.
• Anchoring proof (humanproof-ancoragem/1): a checkpoint or a receipt bound to a timestamp from a Time Stamping Authority (TSA, “ACT” in Brazil), a third party that is not Hummand. The checkpoint proof attests that the tenant chain already had those receipts at that instant; the receipt proof, that the receipt already existed, and it is checked with that receipt alone.
• Verifier: any person or program that checks the objects. It needs no access to Hummand beyond the public key.
• Revision: the version of a format’s rules, marked in the object by the revisao member (section 16). An object without the member is revision 1.

None of the formats carries biometrics, images, templates or the data subject’s data in the clear. What concerns the person goes in as a hash, and each format’s schema rejects unknown fields.

3. Canonicalization

Every hash and every signature in these formats is computed over the JCS canonical form (RFC 8785) of the object, with one restriction: numbers only as safe integers.

1. Input MUST be I-JSON (RFC 7493): valid UTF-8, no duplicate member names in the same object. A verifier MUST reject text with a duplicate name, at any depth, before any other check.
2. Numbers MUST be integers with |n| ≤ 2^53 − 1, written in the input without a fraction, without an exponent and without -0. Input with a number outside this MUST be rejected, not normalized: 1.0, 1e3, 1.5, -0 and 9007199254740992 are rejected.
3. Output has no whitespace outside strings.
4. Object members are sorted by name, compared as sequences of UTF-16 code units, not UTF-8 bytes. The two orders differ for characters outside the basic plane: "😀" (U+1F600, units D83D DE00) comes before "～" (U+FF5E).
5. Arrays keep their order.
6. Strings are written as JSON.stringify writes them: " and \ escaped with a backslash; \b, \f, \n, \r and \t in short form; the other control characters below U+0020 as \u followed by four lowercase hex digits; everything else literal in UTF-8, including /, U+007F and U+2028. Escapes in the input are undone first.
7. Numbers in decimal, with no leading zeros; true, false and null literal.

The canonicalizacao.json vector file has each of these rules as an input and output pair, with the hash of the output, and the inputs that MUST be rejected with canonico: null.

4. Hash

hash(x) = "sha256:" + hex(SHA-256(UTF-8(x))), with 64 lowercase hex digits. Every hash field in these formats has this form, and a verifier MUST reject what does not.

• Hash of an object: the hash of the JCS of the whole object, signature included. It is what goes into the prev_hash of the next object, which is why the chain also binds the signatures.
• Acts genesis of a tenant: hash("humanproof/1:genesis:" + tenant.id).
• Accesses genesis of a tenant: hash("humanproof-acesso/1:genesis:" + tenant.id).

In both geneses the hash is over the concatenated string, without JCS. The genesis.json file has the values for the test tenants.

5. Signature and keys

• Signed payload (revision 1; revision 2 is in section 16.1): the JCS of the object without the assinatura member. kid and alg stay inside the payload and are therefore covered by the signature.
• Algorithms: ES256 (ECDSA over P-256 with SHA-256) and EdDSA (Ed25519). Hummand’s issuer signs with ES256, with the private key in a managed key module it never leaves. EdDSA is part of the format and is exercised in the vectors.
• Encoding: unpadded base64url (RFC 4648 §5) of the raw signature bytes. For ES256, r || s with 32 bytes each, as in JWS (RFC 7518 §3.4), never DER. For EdDSA, the 64 signature bytes.
• Keys: a JWKS (RFC 7517). Each key has kid, kty and crv (EC/P-256 or OKP/Ed25519), the public coordinates and alg. Hummand’s issuer JWKS is at https://gateway.hummand.com.br/.well-known/humanproof/keys.json.
• Selection: the verifier MUST pick the key by the object’s kid and MUST require the object’s alg to match the key type. There is no negotiation: an alg that does not match the key is a signature failure, before any computation. So is a kid absent from the JWKS.
• A JWKS can hold more than one key, and a chain can cross a change of key and of algorithm: the chain is by hash and does not depend on the key.

6. The act receipt humanproof/1

The exact structure is in the JSON Schema humanproof-1.schema.json (draft 2020-12), which is part of this specification and rejects unknown fields. Field names are in Portuguese, as in the format. The required members:

Member	Content
formato	"humanproof/1"
recibo_id, ato_id	opaque identifiers
tenant	{ id, nome_publico }
tipo	act type, such as presenca.recorrente or mandato.pessoa
nivel	integer from 0 to 3: the level actually reached, not the one requested
resultado	positivo, negativo, expirado, cancelado, falhou or revogado
motivo_codigo	short reason code, or null
sujeito	ref_cliente_hash (HMAC-SHA256, with a per-tenant secret kept by the issuer, over the reference the customer gave the person, in hash form, or null) and, when there was one, referencia with the hash of the compared reference
contexto	hash of the JCS of the context the customer sent and chaves_declaradas, the key names; never the content
consentimentos	per layer: kind, versao, texto_hash and ts. texto_hash is the hash of the consent identifier (purpose, scope and version), not of the text shown; the text of each version is requested from the issuer
etapas	nome, resultado (ok or the short failure reason) and ts
fontes	source, the version of the issuer’s software (not that of the third-party component) and, when there is one, the component used
garantias	humano_vivo, mesma_pessoa_da_referencia, identidade_civil, consentiu (true, false or null when the step did not happen) and biometria_retida, always false
mandato_ref, encadeamento, revisado_por	mandate reference, position in a group of chained acts and human review mark, each null when not applicable
politica_versao	the policy applied
ts_criado, ts_concluido	RFC 3339 in UTC, with the Z suffix
prev_hash	hash of the previous receipt of the same tenant, or the acts genesis
kid, alg, assinatura	section 5

Optional members, by act type: backfill; escopo and mandatario in a mandate grant; verificacao_mandato in a mandate use; documento_anexo; assinatura_juridica; recibos_individuais and humanos_distintos in composite acts; gatilho.

Three reading notes:

• contexto.hash only checks against whoever has the context. Whoever has the original context recomputes hash(JCS(contexto)) alone; the verifier checks only the form of the hash. An act without context uses the hash of {}. Receipts issued before 2026-09-13 whose context had a non-ASCII character hold the hash of an earlier recipe, which escaped those characters instead of writing them in UTF-8; for ASCII-only context both recipes give the same value.
• etapas[].ts is the instant the step ended, when the issuer measured it. When it did not, the issuer puts the act’s ts_concluido there, and the receipt remains valid. Nothing in the receipt tells the two cases apart.
• inconclusivo is never a result. An act that goes through human review comes out as positivo or negativo, with revisado_por filled in: the id of the act in which the reviewer proved their own presence, in a review done by the issuer, or, since 2026-10-29, apikey:<id>, the key with which the customer decided through the integration. The review decides the act, not presence: garantias.humano_vivo is always the component’s verdict.

7. Coherence of humanproof/1

Beyond schema and signature, the verifier MUST apply the rules below. They ensure the receipt does not contradict itself, not that what it states happened outside it.

1. resultado from the vocabulary; nivel between 0 and 3; non-empty kid; every hash in the form of section 4; garantias.biometria_retida false.
2. positivo requires every step ok.
3. positivo at level 2 or above, without mandato_ref, requires a presenca step with ok, garantias.humano_vivo true and, when there is a sujeito.referencia, garantias.mesma_pessoa_da_referencia true.
4. positivo at level 3 requires garantias.identidade_civil true.
5. revisado_por only in positivo or negativo.
6. revogado requires mandato_ref, the revoked mandate.
7. Times in RFC 3339; ts_concluido does not precede ts_criado; no step after ts_concluido; steps in non-decreasing ts order. A step may precede ts_criado, because consent is collected before the act is born.
8. Mandate grant. escopo and mandatario go together. escopo.acoes not empty; escopo.revogavel present; escopo.validade_ate in RFC 3339 and, in the grant (without mandato_ref), later than ts_criado: a mandate born expired authorizes nothing. mandatario.tipo is pessoa or agente, and mandatario.ref_hash is a hash.
9. Mandate use. verificacao_mandato requires mandato_ref and the four statements valido, dentro_escopo, dentro_validade and revogado. They authorize when the first three are true and the last is false, and the receipt is positivo exactly when they authorize. motivo_codigo must be supported by them: mandato_invalido requires valido false; mandato_revogado, revogado true; mandato_vencido, dentro_validade false; fora_de_escopo, dentro_escopo false. The verificacao_mandato step is ok exactly when the four authorize. escopo and verificacao_mandato never appear in the same receipt.

The verifier does not check the referenced mandate against the grant receipt: whoever wants the whole proof verifies both receipts, which are in the same tenant chain.