> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truthlocks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Formato do Pacote de Prova

> Especificação para o formato de pacote de prova criptográfico Truthlocks versão 1.0.

Um **Pacote de Prova Truthlocks** contém evidências para verificações criptográficas suportadas de um registro. A verificação offline requer o payload correspondente, formato suportado e chaves de emissor e log confiáveis independentemente. Não estabelece o status de revogação atual, autoridade do emissor, verdade factual ou se uma ação no mundo real ocorreu.

ESPECIFICAÇÃO v1.0

## 1. Visão Geral

Um Pacote de Prova Truthlocks é um documento de evidência portátil. Use o formato e o verificador documentados para o endpoint que o produziu. O suporte a CBOR está listado abaixo como uma extensão futura, não uma garantia para exportações atuais.

A evidência pode incluir dados de atestado, referências de chave e provas de log de transparência. Verifique a assinatura e a inclusão do log separadamente; a ausência de evidências não deve ser relatada como uma verificação aprovada. Nunca confie em uma chave pública apenas porque ela está incluída no pacote: estabeleça a chave autorizada por meio de um canal confiável. O esquema abaixo é uma descrição de referência; corresponda à versão de exportação real e seu contrato de bytes assinados antes de implementar um verificador.

## 2. Estrutura do Pacote

Os pacotes de prova são serializados como objetos JSON e seguem este esquema:

```json theme={null}
{
  "header": {
    "version": "1.0",
    "bundle_id": "bun_a1b2c3d4...",
    "generated_at": "2026-03-12T14:30:00Z",
    "format": "json",
    "tenant_id": "ten_x9y8z7..."
  },
  "attestation": {
    "id": "att_k7x2m9...",
    "type": "content_protection",
    "subject": "main.ts",
    "subject_type": "file",
    "content_hash": "sha256:a1b2c3d4e5f6...",
    "metadata": {
      "title": "My Project",
      "category": "code",
      "file_size": 4096
    },
    "issued_at": "2026-03-12T14:28:00Z",
    "issuer_id": "iss_p4q5r6...",
    "issuer_key_id": "key_m1n2o3...",
    "signature": "base64url-encoded-signature",
    "signature_format": "Ed25519",
    "status": "active"
  },
  "proofs": [
    {
      "log_id": "log_main",
      "tree_size": 42857,
      "leaf_index": 42856,
      "leaf_hash": "sha256:...",
      "inclusion_proof": ["sha256:...", "sha256:...", "..."],
      "root_hash": "sha256:...",
      "timestamp": "2026-03-12T14:28:01Z"
    }
  ],
  "issuer_certificate": {
    "issuer_id": "iss_p4q5r6...",
    "issuer_did": "did:truthlock:iss_p4q5r6...",
    "key_id": "key_m1n2o3...",
    "algorithm": "Ed25519",
    "public_key_der": "base64-encoded-public-key",
    "valid_from": "2026-01-01T00:00:00Z",
    "trust_anchor": "truthlocks-root-2026"
  },
  "bundle_hash_b64url": "base64url-encoded-sha256-of-bundle",
  "bundle_signature": {
    "key_id": "truthlocks-signing-key-2026",
    "algorithm": "Ed25519",
    "value": "base64-encoded-bundle-signature"
  }
}
```

## 3. Definições de Campo

### 3.1 Cabeçalho

| Campo | Tipo | Obrigatório | Descrição |
| :- | :- | :- | :- |
| `version` | string | Sim | Versão do formato do pacote (atualmente "1.0") |
| `bundle_id` | string | Sim | Identificador único para este pacote |
| `generated_at` | datetime | Sim | Carimbo de data/hora ISO 8601 da geração do pacote |
| `format` | string | Sim | Formato de codificação: "json" ou "cbor" |
| `tenant_id` | string | Sim | Locatário que possui a atestação |

### 3.1.1 Hash de integridade do pacote

| Campo | Tipo | Obrigatório | Descrição |
| :- | :- | :- | :- |
| `bundle_hash_b64url` | string | Sim | Hash SHA-256 codificado em Base64url de todos os campos do pacote (excluindo `bundle_hash_b64url` e `bundle_signature`). Usado para detecção de adulteração — qualquer modificação no conteúdo do pacote invalida este hash. |

### 3.2 Atestado

| Campo | Tipo | Obrigatório | Descrição |
| :- | :- | :- | :- |
| `id` | string | Sim | Identificador de atestado |
| `type` | string | Sim | Tipo de atestado (ex: content\_protection, identity.kyc) |
| `subject` | string | Sim | Assunto da atestação (nome do arquivo, pessoa, etc.) |
| `subject_type` | string | Não | Dica de tipo para o assunto (arquivo, pessoa, organização) |
| `content_hash` | string | Sim | Hash SHA-256 do conteúdo atestado (prefixado sha256:) |
| `document_hash` | string | Não | Hash SHA-256 pré-calculado passado no momento da cunhagem. Quando fornecido, a plataforma usa este valor em vez de calcular o hash internamente. |
| `metadata` | objeto | Não | Metadados adicionais sobre a atestação |
| `issued_at` | datetime | Sim | Quando a atestação foi cunhada |
| `valid_from` | datetime | Não | Início do período de validade |
| `valid_until` | datetime | Não | Fim do período de validade (nulo = sem expiração) |
| `issuer_id` | string | Sim | ID da entidade emissora |
| `issuer_key_id` | string | Sim | ID da chave usada para assinar a atestação |
| `signature` | string | Sim | Assinatura codificada em Base64url sobre o payload da atestação |
| `signature_format` | string | Sim | Algoritmo usado: Ed25519, ES256, RS256 |
| `status` | string | Sim | Snapshot de status na exportação; atualize para aceitação atual |

### 3.3 Provas (Registro de Transparência)

| Campo | Tipo | Descrição |
| :- | :- | :- |
| `log_id` | string | Identificador do log de transparência |
| `tree_size` | inteiro | Tamanho da árvore Merkle no momento da inclusão |
| `leaf_index` | inteiro | Posição desta entrada na árvore |
| `leaf_hash` | string | Hash SHA-256 do nó folha |
| `inclusion_proof` | string\[] | Lista ordenada de hashes irmãos formando o caminho da prova de inclusão |
| `root_hash` | string | Hash raiz do cabeçalho da árvore assinado no momento da inclusão |
| `timestamp` | datetime | Quando a entrada foi anexada ao log |

### 3.4 Certificado do Emissor

| Campo | Tipo | Descrição |
| :- | :- | :- |
| `issuer_id` | string | UUID do emissor |
| `issuer_did` | string | Identificador Descentralizado W3C (did:truthlock:...) |
| `key_id` | string | Identificador da chave |
| `algorithm` | string | Algoritmo da chave: Ed25519, ES256, RS256 |
| `public_key_der` | string | Chave pública codificada em Base64 no formato DER |
| `valid_from` | datetime | Início da validade da chave |
| `valid_until` | datetime | Fim da validade da chave (nulo = sem expiração) |
| `trust_anchor` | string | Referência à âncora de confiança raiz |

## 4. Algoritmo de Verificação

Para verificar um Truthlocks Proof Bundle, execute os seguintes passos em ordem. Se qualquer passo falhar, o bundle é inválido.

### Passo 1: Validar a integridade do pacote

Calcule o hash SHA-256 de todos os campos do pacote, excluindo `bundle_hash_b64url` e `bundle_signature`. Decodifique o valor `bundle_hash_b64url` em Base64url e compare-o com o hash calculado. Se não corresponderem, o pacote foi adulterado.

### Passo 2: Verificar a assinatura da atestação

Usando a chave pública de `issuer_certificate.public_key_der` e o algoritmo especificado em `attestation.signature_format`, verifique `attestation.signature` contra o payload de atestado canônico (todos os campos de atestado, exceto `signature` e `status`).

### Passo 3: Verificar hash do conteúdo

Se você tiver o arquivo original, calcule seu hash SHA-256 e compare-o com `attestation.content_hash`. Isso confirma que o arquivo não foi modificado desde a atestação.

Se um valor `document_hash` estiver presente, você também pode compará-lo com seu hash calculado. O `document_hash` é um hash hexadecimal SHA-256 pré-calculado que o minter passou no momento da cunhagem, fornecendo uma verificação de integridade adicional independente da codificação da carga útil.

### Passo 4: Verificar inclusão no log de transparência

Para cada entrada em `proofs`, verifique a prova de inclusão Merkle. Começando de `leaf_hash` na posição `leaf_index`, recalcule a raiz fazendo hash com cada irmão em `inclusion_proof`. O resultado deve corresponder a `root_hash`.

### Passo 5: Verificar validade da chave

Confirme que `issuer_certificate.valid_from` ≤ `attestation.issued_at` ≤ `issuer_certificate.valid_until` (se presente).

## 5. Algoritmos Suportados

| Algoritmo | Tipo de Chave | Uso |
| :- | :- | :- |
| `Ed25519` | OKP (Curve25519) | Padrão para emissores consumidores. Assinaturas rápidas e compactas. |
| `ES256` | EC (P-256) | ECDSA com SHA-256. Compatível com FIPS. |
| `RS256` | RSA (2048+) | RSA com SHA-256. Compatibilidade legada. |

## 6. Ferramentas de Verificação

Os pacotes de prova podem ser verificados usando qualquer um destes métodos:

* **CLI**: `truthlock verify -b bundle.json -f original-file --trusted-log-key "$TRUTHLOCKS_LOG_PUBLIC_KEY" --trusted-issuer-key "$TRUTHLOCKS_ISSUER_PUBLIC_KEY"`. Fixe ambas as chaves públicas independentemente do pacote. As verificações offline não estabelecem o status de revogação atual.
* **Web**: Carregar em `verify.truthlocks.com/proof/[id]`
* **SDK**: `client.verify.verifyBundle(bundleJson, fileBuffer)`
* **Manual**: Siga o algoritmo de verificação acima com qualquer biblioteca Ed25519/ECDSA

## 7. Pontos de Extensão

O campo `metadata` no objeto de atestado é extensível. Esquemas personalizados podem incluir campos adicionais sem quebrar a verificação. O algoritmo de verificação principal depende apenas de `content_hash`, `signature` e das provas do log de transparência.

Versões futuras do formato podem introduzir:

* Codificação CBOR para representação binária compacta
* Pacotes de múltiplas atestações (verificação em lote)
* Provas de consistência entre logs
* Provas de status de revogação (incorporadas)

## 8. Princípios de Design

* **Autocontido**: Não é necessário acesso à rede para verificação
* **Confiança minimizada**: Verificável mesmo que a Truthlocks deixe de operar
* **Compatível com o futuro**: Campos desconhecidos são ignorados por verificadores mais antigos
* **Determinístico**: A codificação JSON canônica garante hashing consistente
* **Aberto**: Usa primitivas criptográficas padrão (sem formatos proprietários)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.