Verificação

Duas provas independentes protegem cada envelope concluído:

1. O selo, dentro do PDF: um carimbo temporal de documento PAdES de uma autoridade de carimbo temporal pública. O Adobe Acrobat e o Reader verificam-no e mostram o documento como não modificado desde que foi selado.
2. A âncora, fora do PDF: a impressão digital do documento é uma folha numa árvore de Merkle que só admite acréscimos, e a Bona Fide assina cada raiz da árvore com Ed25519. Qualquer pessoa pode verificar essa prova com as chaves públicas publicadas, sem conta e sem ter de confiar num visualizador de PDF.

Selagem

Quando o último destinatário assina, o envelope é concluído (envelope.completed) e o selador assume o processo:

1. Compara o SHA-256 do original com o que foi registado quando o envelope foi criado.
2. Aplana o documento: os valores dos campos (texto, caixas de verificação, assinaturas desenhadas, escritas ou carregadas) são desenhados no conteúdo da página, e todos os campos de formulário, anotações, ações JavaScript e ficheiros incorporados são removidos.
3. Anexa o certificado de conclusão: id do envelope, o SHA-256 do original, cada signatário com o método de verificação efetivamente utilizado (por exemplo, Ligação por e-mail (ligação única enviada para …) ou Ligação por e-mail + código de utilização única; consulte verificação do signatário), as horas, o endereço IP e o dispositivo, e a cronologia dos eventos. Cada página recebe o rodapé Bona Fide Envelope ID … · Verify at bonafidesign.com/verify.
4. Acrescenta um carimbo temporal de documento PAdES (/DocTimeStamp, ETSI.RFC3161, SHA-256) de uma autoridade de carimbo temporal pública (vários fornecedores de confiança pública, com comutação automática em caso de falha) e incorpora os dados de validação da cadeia de certificados da TSA (OCSP/CRL no DSS), para que se mantenha verificável a longo prazo (LTV).
5. Valida o seu próprio resultado, guarda-o e regista o SHA-256 selado (sealedDocumentHash) e uma folha para o registo de âncoras.

Em seguida, é disparado envelope.sealed e GET /v1/envelopes/{id}/document?version=sealed devolve o ficheiro. Se nenhuma TSA estiver disponível, a selagem é repetida; entretanto, o envelope mantém-se completed com seal: "pending".

Ancoragem

Cada envelope selado contribui com uma folha, o JSON canónico (chaves ordenadas, sem espaços em branco) de:

{
  "completed_at": "2026-10-13T14:09:52.004Z",
  "envelope_id": "env_8Gm2kQ4rT1",
  "event_chain_head": "<head of the envelope's audit hash chain>",
  "original_document_sha256": "<SHA-256 of the document as sent>",
  "sealed_document_sha256": "<SHA-256 of the sealed PDF>"
}

De hora a hora, as folhas registadas desde a âncora anterior formam uma árvore de Merkle (RFC 6962 / RFC 9162: leaf = SHA-256(0x00 ‖ leaf JSON), node = SHA-256(0x01 ‖ left ‖ right)), e a respetiva raiz é publicada como uma âncora assinada:

GET /v1/public/anchors/latest

{
  "id": "…",
  "version": "bona-fide-anchor-v1",
  "sequence": 412,
  "root": "<hex Merkle root>",
  "previous_root": "<root of anchor 411>",
  "leaf_count": 37,
  "created_at": "2026-10-13T15:00:00.118Z",
  "key_id": "<first 16 hex of SHA-256(public key)>",
  "signature": "<base64url Ed25519 signature>",
  "signed_message": "bona-fide-anchor-v1|412|<root>|<previous_root>|2026-10-13T15:00:00.118Z|37"
}

A assinatura Ed25519 abrange bona-fide-anchor-v1|sequence|root|previous_root|created_at|leaf_count (UTF-8). previous_root encadeia cada âncora à anterior (a primeira aponta para 64 zeros), pelo que uma âncora não pode ser removida nem reordenada sem quebrar a cadeia, e as tabelas de âncoras só admitem acréscimos.

As chaves de assinatura são publicadas com os respetivos períodos de validade; as chaves retiradas continuam listadas para que as âncoras antigas se mantenham verificáveis:

GET /.well-known/bona-fide/keys.json

{
  "issuer": "Bona Fide",
  "anchor_format": "bona-fide-anchor-v1|sequence|root|previous_root|created_at|leaf_count (UTF-8, Ed25519; root = RFC 6962 SHA-256 Merkle tree)",
  "keys": [
    {
      "key_id": "<16 hex>",
      "algorithm": "Ed25519",
      "public_key": "<base64url raw 32-byte key>",
      "public_key_pem": "-----BEGIN PUBLIC KEY-----…",
      "valid_from": "2026-10-14T00:00:00.000Z",
      "valid_until": null,
      "status": "active"
    }
  ]
}

Verificar um documento

A forma mais rápida é a página pública: bonafidesign.com/verify. Calcula o hash do PDF no seu navegador (o ficheiro nunca é carregado), procura esse hash e verifica a prova e a assinatura no seu dispositivo. O registo de âncoras lista todas as âncoras.

A mesma consulta está disponível como API pública: sem chave, a partir de qualquer origem, com limite de pedidos por IP. Envie apenas o SHA-256:

curl https://api.bonafidesign.com/v1/public/verify \
  -H "Content-Type: application/json" \
  -d "{\"sha256\": \"$(shasum -a 256 signed.pdf | cut -d' ' -f1)\"}"

{
  "sha256": "…",
  "status": "verified",
  "results": [
    {
      "status": "verified",
      "matched": "sealed_document",
      "envelope": {
        "id": "env_8Gm2kQ4rT1",
        "status": "completed",
        "completed_at": "2026-10-13T14:09:52.004Z",
        "sealed_at": "2026-10-13T14:10:31.442Z",
        "organization_name": "Acme Robotics, Inc.",
        "signer_count": 1,
        "signers": [{ "name": "Jane Doe", "email": "jane@acme.dev", "role": "client", "verification_method": "Email OTP", "signed_at": "…" }],
        "verification_methods": ["Email OTP"],
        "test_mode": false
      },
      "leaf": { "envelope_id": "env_8Gm2kQ4rT1", "…": "…" },
      "leaf_hash": "…",
      "proof": { "leaf_index": 12, "tree_size": 37, "hashes": ["…", "…"] },
      "anchor": { "sequence": 412, "…": "…" },
      "links": { "anchor": "…", "keys": "…/.well-known/bona-fide/keys.json" }
    }
  ]
}

status é verified, pending_anchor (concluído e registado, a aguardar a próxima âncora horária) ou not_found: nenhum envelope concluído tem exatamente este ficheiro, pelo que não é o documento que foi assinado (ou foi modificado entretanto). Tanto o ficheiro selado como o original enviado são reconhecidos.

Verificar a prova por si próprio

Não se limite a confiar na palavra da API: tudo o que é necessário para verificar a resposta está na própria resposta e no keys.json.

1. Documento: o SHA-256 do seu ficheiro é igual a leaf.sealed_document_sha256 (ou a original_document_sha256).
2. Folha: SHA-256(0x00 ‖ canonical JSON of leaf) é igual a leaf_hash.
3. Inclusão: percorrer proof.hashes a partir do hash da folha (RFC 9162 §2.1.3.2, com leaf_index e tree_size == anchor.leaf_count) dá anchor.root.
4. Chave: anchor.key_id consta do keys.json, o id da chave corresponde aos primeiros 16 caracteres hexadecimais do SHA-256 da chave pública em bruto e anchor.created_at está dentro do período de validade da chave.
5. Assinatura: a assinatura Ed25519 é válida sobre bona-fide-anchor-v1|sequence|root|previous_root|created_at|leaf_count.

Python

# pip install requests cryptography
import base64, hashlib, json, sys, requests
from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey

API = "https://api.bonafidesign.com"
b64url = lambda s: base64.urlsafe_b64decode(s + "=" * (-len(s) % 4))
sha = lambda b: hashlib.sha256(b).digest()

def root_from_proof(leaf: bytes, index: int, size: int, path: list[bytes]) -> bytes:
    fn, sn, r = index, size - 1, leaf
    for p in path:
        if sn == 0: raise ValueError("proof too long")
        if fn % 2 == 1 or fn == sn:
            r = sha(b"\x01" + p + r)
            while fn % 2 == 0 and fn != 0:
                fn, sn = fn // 2, sn // 2
        else:
            r = sha(b"\x01" + r + p)
        fn, sn = fn // 2, sn // 2
    if sn != 0: raise ValueError("proof too short")
    return r

digest = hashlib.sha256(open(sys.argv[1], "rb").read()).hexdigest()
res = requests.post(f"{API}/v1/public/verify", json={"sha256": digest}).json()
keys = {k["key_id"]: k for k in requests.get(f"{API}/.well-known/bona-fide/keys.json").json()["keys"]}

for m in res["results"]:
    leaf, proof, anchor = m["leaf"], m["proof"], m["anchor"]
    if not anchor:
        print("pending anchor"); continue
    assert digest in (leaf["sealed_document_sha256"], leaf["original_document_sha256"])
    leaf_json = json.dumps(leaf, sort_keys=True, separators=(",", ":")).encode()
    leaf_hash = sha(b"\x00" + leaf_json)
    assert proof["tree_size"] == anchor["leaf_count"]
    root = root_from_proof(leaf_hash, proof["leaf_index"], proof["tree_size"], [bytes.fromhex(h) for h in proof["hashes"]])
    assert root.hex() == anchor["root"], "not included under the anchor root"
    key = keys[anchor["key_id"]]
    raw = b64url(key["public_key"])
    assert hashlib.sha256(raw).hexdigest()[:16] == anchor["key_id"]
    message = "|".join([anchor["version"], str(anchor["sequence"]), anchor["root"], anchor["previous_root"],
                        anchor["created_at"], str(anchor["leaf_count"])]).encode()
    Ed25519PublicKey.from_public_bytes(raw).verify(b64url(anchor["signature"]), message)  # raises if invalid
    print(f"VERIFIED {leaf['envelope_id']} in anchor #{anchor['sequence']}")

A folha só tem valores do tipo string com chaves ASCII, pelo que json.dumps(…, sort_keys=True, separators=(",", ":")) produz o mesmo JSON canónico. Verifique também valid_from / valid_until da chave em relação a anchor["created_at"].

TypeScript

O verificador de referência, @bona-fide/verify, é isomórfico (navegador e Node, sem segredos da Bona Fide) e é o que a página /verify executa:

import { sha256Hex, verifyProof, type KeySet, type PublicVerifyResponse } from '@bona-fide/verify';
import { readFile } from 'node:fs/promises';

const api = 'https://api.bonafidesign.com';
const sha256 = sha256Hex(new Uint8Array(await readFile('signed.pdf')));
const body = (await (await fetch(`${api}/v1/public/verify`, {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({ sha256 }),
})).json()) as PublicVerifyResponse;
const keys = (await (await fetch(`${api}/.well-known/bona-fide/keys.json`)).json()) as KeySet;

for (const m of body.results) {
  if (!m.leaf || !m.proof || !m.anchor) continue; // pending_anchor
  const r = await verifyProof(m.leaf, m.proof, m.anchor, keys, { documentSha256: sha256, expectedLeafHash: m.leaf_hash ?? undefined });
  console.log(r.valid ? 'VERIFIED' : 'INVALID', m.envelope.id, r.checks);
}

O pacote inclui também um verificador de linha de comandos (bona-fide-verify <file.pdf | sha256> [--api URL] [--json]; a partir de um checkout do repositório da Bona Fide: pnpm --filter @bona-fide/verify cli signed.pdf). Calcula o hash do ficheiro localmente, verifica cada um dos passos acima e termina com 0 quando verificado, 1 quando não encontrado ou inválido e 2 quando o documento ainda não foi ancorado.

OpenSSL

Verifique a assinatura de uma âncora com a chave PEM do keys.json (OpenSSL 3):

curl -s https://api.bonafidesign.com/v1/public/anchors/412 > anchor.json
curl -s https://api.bonafidesign.com/.well-known/bona-fide/keys.json > keys.json

printf %s "$(jq -r .signed_message anchor.json)" > message.txt
jq -r .signature anchor.json | python3 -c 'import base64,sys; s=sys.stdin.read().strip(); sys.stdout.buffer.write(base64.urlsafe_b64decode(s + "=" * (-len(s) % 4)))' > signature.bin
KEY_ID=$(jq -r '.key_id' anchor.json)
jq -r --arg k "$KEY_ID" '.keys[] | select(.key_id == $k) | .public_key_pem' keys.json > key.pem

openssl pkeyutl -verify -pubin -inkey key.pem -rawin -in message.txt -sigfile signature.bin
# Signature Verified Successfully

O que a âncora comprova

Uma prova válida mostra que exatamente este ficheiro foi registado pela Bona Fide como o documento de um envelope concluído, e que esse registo estava numa raiz de árvore que a Bona Fide assinou em created_at. O carimbo temporal de documento do próprio PDF, verificado por qualquer validador PAdES, como o Adobe Acrobat, comprova de forma independente que os bytes selados não foram alterados desde a selagem.

As âncoras são listadas da mais recente para a mais antiga com GET /v1/public/anchors?limit=20&before=<sequence> (passe next_before para recuar nas páginas) e obtidas uma a uma com GET /v1/public/anchors/{sequence}.