Especificação dos formatos humanproof

12. Versões

Mudança de formato é formato novo (humanproof/2, por exemplo); um formato publicado não é editado. Esta especificação pode ganhar valores aditivos dentro de um formato, como o papel terceiro acrescentado em 2026-10-19, e o documento registra cada um com data. Na versão 1.1 do documento, do mesmo dia da 1.0, a recusa de nome duplicado passou de DEVERIA a DEVE, com o vetor invalidos/nome-duplicado.json. A versão 1.2, também de 2026-10-19, acrescenta o formato humanproof-ancoragem/1 (seção 15). A versão 1.3, de 2026-10-20, acrescenta a ele a prova de recibo (recibo_hash), antes de o formato ter qualquer prova emitida em produção. A versão 1.4, de 2026-10-29, corrige três descrições que não batiam com o emissor (o texto_hash é o hash do identificador do consentimento, não do texto; a versão em fontes é a do software do emissor, não a do componente; o segredo do ref_cliente_hash fica com o emissor) e descreve o revisado_por da revisão feita pelo cliente; nenhum formato mudou. A versão 2.0, de 2026-10-30, acrescenta a revisão 2 dos formatos (seções 16 a 20), com a data de corte, e as licenças do texto e dos artefatos; o que descreve a revisão 1 não mudou. A versão 2.1, também de 2026-10-30, corrige descrições sem mudar formato, schema nem vetor: a ancoragem ainda não está ativa em produção (seções 13 a 15 e 20); sem a chave, o compromisso não liga dois recibos da mesma pessoa, mas referencia.hash é igual em recibos que usaram a mesma imagem (17.2); participantes e mandatario trazem ref_sal (17 e 17.6); o recibo identifica o componente, e a versão registrada depende da revisão (13); o que cada hash permite conferir, por revisão (14); os vetores da revisão 2 e esperado.valido (11); a validade por chave é admitida pelo formato, não exigida (16.2). A versão 2.2, também de 2026-10-30, acrescenta vetores sem mudar formato nem schema: quatro recibos inválidos em revisao-2/invalidos/ (regra 11 da dupla aprovação, crit, motivo fora do resultado e revisão 1 depois do corte) e dois JWKS com a chave vencida ou comprometida antes da emissão, contra os quais o recibo válido falha na assinatura (11). A versão 2.3, de 2026-11-01, acrescenta a data de corte do ponto (seção 16) e corrige a conferência da validade por chave, que passava sem conferir quando o instante da emissão não era RFC 3339 e agora recusa; nenhum formato, schema ou vetor muda. Um verificador anterior recusa o valor que não conhece, porque os schemas são fechados; nunca o aceita por omissão.

13. O que os formatos não provam

• O recibo afirma o que as fontes declaradas sustentam, e nada além. A presença viva é o veredito de um componente de terceiro, identificado no recibo, que decide por critério probabilístico; o recibo registra o veredito, não um escore. Na revisão 1, a versão em fontes é a do software do emissor, não a do componente; na revisão 2, versao_componente pode ser nao_informada.
• O recibo não prova a legitimidade da referência que o cliente enviou: uma boa comparação contra a referência errada é confiança alta na pessoa errada.
• A cadeia e o ponto cobrem o que foi emitido. Um ato que nunca virou recibo não aparece em cadeia nenhuma.
• O recibo de acesso cobre a abertura pelo caminho oficial. Acesso por fora dele não gera recibo.
• Coerência é ausência de contradição interna, não confirmação externa.
• O compromisso da referência (17.2) prova de quem é o recibo só para quem tem a chave de referência e a referência; ele não diz se a referência que o cliente cadastrou é de fato da pessoa.
• O carimbo atesta quando o ponto ou o recibo existia, não que o que os recibos afirmam aconteceu. Recibos emitidos entre uma ancoragem e a seguinte ficam sem âncora até ela. A ancoragem ainda não está ativa em produção: até lá, nenhum recibo nem ponto do emissor tem âncora.

14. Segurança

• Confiança na chave. A assinatura prova só que quem tinha a chave privada assinou. O verificador DEVE obter o JWKS pelo endereço do emissor ou guardá-lo de antemão, e NÃO DEVE confiar numa chave que veio no mesmo pacote que os recibos: quem forja um pacote forja também a chave que vai dentro dele. A chave do pacote serve só para comparar.
• Nomes duplicados. Dois parsers que resolvem nomes duplicados de modos diferentes (o primeiro vence, o último vence) leriam o mesmo texto como recibos diferentes. Por isso a entrada DEVE ser I-JSON, e um verificador DEVE recusar o texto com nome duplicado em vez de escolher um dos valores. O vetor invalidos/nome-duplicado.json é um recibo negativo verdadeiro com um segundo resultado, positivo, no começo do objeto: quem fica com o último valor confere a assinatura, e quem fica com o primeiro lê um positivo.
• Chave de referência. Quem tiver a chave de referência de um tenant consegue testar referências candidatas contra os compromissos dos recibos daquele tenant. Ela não é trocada (não há rotação), porque trocá-la impediria conferir os recibos antigos, e deve ser guardada como senha.
• Privacidade. Na revisão 1, ref_cliente_hash é HMAC com um segredo por tenant, guardado pelo emissor, porque o hash puro de um documento de identificação se reverte por enumeração; só o emissor o recompõe. Também na revisão 1, texto_hash só é conferível por quem tem a finalidade, o escopo e a versão do consentimento. Na revisão 2, ref_compromisso é conferível por quem tem a chave de referência e a referência (17.2), e texto_hash por qualquer pessoa com o texto publicado (17.3). Nas duas revisões, motivo_hash e contexto.hash só são conferíveis por quem tem o texto original.
• Ponto. Ver a seção 10: só o ponto guardado antes da conferência acusa o corte do fim, ou o ponto ancorado (seção 15), quando a ancoragem estiver ativa em produção.
• Raízes da ancoragem. O carimbo vale o que vale a raiz em que o verificador confia. As raízes DEVEM vir da fonte oficial (para a ICP-Brasil, o ITI), nunca do mesmo pacote que traz a prova.

15. A prova de ancoragem humanproof-ancoragem/1

O emissor faz periodicamente uma árvore de Merkle com duas espécies de folha e pede a uma ACT um carimbo do tempo RFC 3161 sobre a raiz:

• o humanproof-ponto/2 assinado de cada tenant com recibo novo, que protege a cadeia inteira contra o corte do fim;
• cada recibo emitido desde a ancoragem anterior, de ato ou de acesso, pelo hash (seção 4), que prova a existência daquele recibo para quem só tem ele.

Cada folha tem a sua prova. A do ponto:

{
  "formato": "humanproof-ancoragem/1",
  "ponto": { "formato": "humanproof-ponto/2", "...": "o ponto assinado do tenant" },
  "caminho": [
    { "lado": "direita", "hash": "sha256:..." },
    { "lado": "direita", "hash": "sha256:..." }
  ],
  "raiz": "sha256:...",
  "carimbo": "<token RFC 3161, DER, em base64 com preenchimento>"
}

A do recibo troca ponto por recibo_hash, o hash do recibo:

{
  "formato": "humanproof-ancoragem/1",
  "recibo_hash": "sha256:...",
  "caminho": [ { "lado": "esquerda", "hash": "sha256:..." } ],
  "raiz": "sha256:...",
  "carimbo": "<token RFC 3161, DER, em base64 com preenchimento>"
}

formato, caminho, raiz e carimbo são obrigatórios, com exatamente um entre ponto e recibo_hash; nenhum outro membro é aceito, e nos itens de caminho só lado e hash. A prova não tem assinatura da Hummand: o ponto dentro dela é assinado, o recibo é assinado e está nas mãos de quem confere, e o carimbo é assinado pela ACT. A prova de recibo não traz nada do recibo além do hash: nem tenant, nem ato.

A árvore segue a RFC 6962 §2.1, sobre os 32 bytes de cada hash:

• folha de ponto: SHA-256(0x00 || JCS(ponto)), com a assinatura do ponto;
• folha de recibo: SHA-256(0x00 || "humanproof-ancoragem/1:recibo:" || recibo_hash), com o hash na forma sha256:<hex>, em UTF-8. A pré-imagem da folha de ponto começa por { e a de recibo por h: uma nunca se passa pela outra;
• nó: SHA-256(0x01 || esquerda || direita);
• com n folhas, n ≥ 2, a raiz é o nó das raízes das k primeiras e das n − k restantes, sendo k a maior potência de dois menor que n; com uma folha, a raiz é a folha.

caminho lista os irmãos da folha até a raiz, do mais baixo ao mais alto; lado diz de que lado o irmão está. Subir é: começar na folha e, para cada item, fazer o nó com o irmão à esquerda ou à direita. O caminho vazio é a árvore de uma folha.

O carimbo é um TimeStampToken (RFC 3161 §2.4.2): um ContentInfo CMS SignedData (RFC 5652) com conteúdo TSTInfo. O messageImprint usa SHA-256, e o hashedMessage são os 32 bytes da raiz.

Conferir uma prova, relatando cada etapa:

1. Forma: os membros acima, raiz, recibo_hash e cada hash na forma da seção 4, carimbo em base64.
2. Folha: na prova de ponto, o ponto confere com o JWKS da Hummand, como na seção 10. Na prova de recibo, quem confere tem o recibo e verifica que o hash dele (seção 4) é recibo_hash; a prova vale para aquele recibo e nenhum outro.
3. Caminho: a folha, subindo pelo caminho, dá exatamente raiz.
4. Carimbo, sobre os bytes de raiz:
   1. o TSTInfo carimba esses 32 bytes, com SHA-256;
   2. há um só SignerInfo, e seus atributos assinados têm content-type igual a id-ct-TSTInfo e message-digest igual ao resumo do TSTInfo, com o digestAlgorithm do SignerInfo (SHA-256, SHA-384 ou SHA-512);
   3. a assinatura, sobre a codificação DER dos atributos assinados com a etiqueta de SET, confere com a chave do certificado da ACT, que vem no carimbo e é identificado pelo sid. Algoritmos: RSA PKCS #1 v1.5 com SHA-256, SHA-384 ou SHA-512, e ECDSA P-256 com SHA-256;
   4. o certificado da ACT tem uso estendido timeStamping;
   5. a cadeia sobe do certificado da ACT até uma das raízes confiáveis do verificador, cada certificado assinado pelo de cima e válido no instante genTime, e todo emissor intermediário com basicConstraints de AC.
5. Na prova de ponto, o ts do ponto não é posterior ao genTime.

A prova é válida quando passa em todas. O verificador DEVERIA mostrar o genTime, a política, a ACT e a raiz a que a cadeia chegou.

O que cada uma prova: a de recibo, que aquele recibo existia no instante genTime, o que basta a quem recebe um dossiê com ele, sem ver nenhum outro recibo do tenant. A de ponto, que a cadeia do tenant tinha total recibos terminando em ultimo_hash naquele instante; o lote do tenant é conferido contra esse ponto como contra um ponto guardado (seção 10), e o auditor não precisa ter guardado um ponto antes.

O que a conferência offline não faz, e o verificador DEVE dizer quando relevante: consultar a lista de revogação da ACT, que exige rede; conferir o atributo signing-certificate do carimbo (a assinatura e a cadeia já prendem o certificado); aceitar RSASSA-PSS.

Estado em produção. A ancoragem ainda não está ativa em produção. O formato, os vetores e o verificador estão prontos; o emissor ainda não emite provas de ancoragem.