API BORA

Cria a pessoa sem biometria (status pending_enrollment). O cadastro da palma vem depois por POST /v1/enrollment-sessions. cpf é opcional e só serve para KYC e deduplicação dentro do tenant: já existir outra pessoa ativa com o mesmo CPF dá 409 cpf_conflict (sem revelar qual).

Com external_ref, devolve 0 ou 1 item. Não existe busca por CPF (CPF nunca vai em URL).

Apagamento definitivo (LGPD art. 18, VI). Na nuvem, na hora: crypto-shred da DEK do template, remoção do HMAC e da cifra do CPF, do external_ref e do onboard_ref, tombstone no próximo delta e compactação do log de deltas (o vetor some também do histórico servido). Nos aparelhos: o tombstone chega pelo delta; aparelho offline aplica no próximo sync e, se passar do TTL de 6 h da galeria, para de reconhecer todo mundo (fail-closed). O recibo é assinado pela BORA (bora.erasure.receipt.v1) e o andamento da propagação fica em GET /v1/erasure-receipts/{receipt_id}. Depois do apagamento, GET da pessoa dá 404.

Na mesma transação saem também: o external_ref dos eventos da pessoa (e o subject_id dos eventos verdict.recorded), o vínculo dos vereditos com o subject_id (o filtro ?subject_id= deixa de achar as passagens dela), o onboard_ref dos deltas guardados e as respostas gravadas de Idempotency-Key que falavam dela.

O que fica, sem biometria:

• o recibo assinado e o pedido (auditoria do próprio apagamento);
• a prova assinada das passagens já registradas (signed_verdict, com o pseudônimo subject_ref e, se havia, o onboard_ref que andaram no cabo), até o fim da retenção de vereditos (13 meses), porque a assinatura cobre esses bytes e reescrever quebraria a prova. Base legal proposta: conciliação tarifária e defesa em disputa (LGPD art. 16, I e art. 7º, VI), a validar com o jurídico. Quando há prova retida, o recibo diz isso em retained: [verdict_proofs].

Registra o consentimento coletado pelo parceiro (por exemplo, no app dele) com a evidência. O consentimento dado na tela do totem durante o cadastro é registrado pelo próprio POST /v1/enrollments. Repetir a mesma finalidade com consentimento vigente devolve o registro existente (200).

Efeitos: identification revogado suspende o reconhecimento (mesmo efeito do block); enrollment revogado apaga o template (crypto-shred) e a pessoa volta a pending_enrollment; dataset_collection revogado apaga as amostras coletadas para treino. Para apagar a pessoa inteira, use DELETE /v1/subjects/{subject_id}.

Abre uma sessão de cadastro para uma pessoa já criada. Devolve um token de uso único e um qr_payload para o totem ou o BORA ACCESS ler. Aparelho sem leitor de QR: o operador digita o short_code e o aparelho troca o código pelo token em POST /v1/enrollment-sessions/redeem. O token aparece só nesta resposta, a BORA guarda só o hash dele. O aparelho conclui com POST /v1/enrollments. O consentimento é mostrado e aceito na tela do totem antes da captura. Limite: 60 sessões por minuto por tenant.

Nunca devolve o token. Falha de captura aparece só como capture_rejected (sem dizer se foi qualidade ou liveness, para não virar oráculo de ataque de apresentação).

Vereditos que os aparelhos subiram (POST /v1/verdicts/batch), já resolvidos para subject_id e external_ref (só em accept), com a decisão e a passagem do DBD quando chegaram. Ordem padrão: mais recente primeiro por decided_at. Retenção: 13 meses (proposta).

Devolve o SignedVerdict exato que o aparelho mandou ao DBD, a SignedDecision e a SignedPassage do DBD (quando chegaram) e o material para verificar fora da BORA: chaves públicas e prefixos de domínio. Serve para contestação de cobrança e conciliação com o BDOS.

Mata as chaves do aparelho (o kill é da chave, não do nome). Na próxima consulta a GET /v1/devices/self/status o aparelho recebe wipe assinado e apaga galeria, DEKs e seeds; depois disso toda rota de aparelho responde 401 para essas chaves. Com o DBD offline, a revogação chega pelo trust.bundle (v1.1). Irreversível para estas chaves: para pôr o aparelho de volta, o admin BORA emite um token de provisionamento novo para o MESMO device_id e o aparelho se registra com chaves novas (as antigas ficam arquivadas, só para verificar vereditos antigos).

Carteiro, ida. Registros que a BORA selou para este aparelho: atualização da base, revogações, config assinada, trust.bundle e atualizações de app ou modelo. O BDOS busca aqui e entrega ao DBD, que oferece ao aparelho pelo cabo (file.offer kind post.in). Nem o BDOS nem o DBD conseguem abrir, forjar ou escolher o que levam: o conteúdo vai cifrado para a chave de selo do aparelho e assinado pela BORA. Peça sempre a partir do último seq entregue (after_seq); o aparelho aplica em ordem estrita.

Carteiro, volta. O aparelho sela para a BORA os vereditos, recibos e eventos (post.out); o DBD puxa pelo cabo e o BDOS entrega aqui do jeito que recebeu, sem abrir. A BORA confere a assinatura do aparelho, o destino e o sha256 de cada registro e guarda. acked_upto_seq é o maior seq contíguo já recebido: o recibo assinado (bora.post.receipt) volta pela caixa de entrada e é ele que libera o aparelho para apagar a cópia local. Reenviar o mesmo registro é seguro (sai em duplicates).

Chaves Ed25519 que a BORA usa para assinar recibos de apagamento, cabeças e deltas de galeria, status de aparelho e webhooks. O cliente deve fixar (pin) estas chaves por kid e aceitar rotação só quando a nova chave aparecer aqui antes do not_before.