Biometrics

O Biometrics responde a duas perguntas sobre quem está diante da câmera: está vivo? e é a mesma pessoa? — do documento, na abertura de conta, ou do cadastro facial, na autenticação.

O sistema da empresa abre uma sessão, manda a pessoa para a página de captura hospedada pelo bloco e recebe de volta uma decisão explicada: cada verificação com o score, o limiar usado e a versão do modelo, mais uma evidência assinada que qualquer um confere sem depender da Catalisa.

Por trás, um motor próprio, o face-engine, montado sobre modelos de pesos abertos e rodando na nossa infraestrutura: nenhuma imagem de rosto sai para terceiro. FaceTec, Unico e Serpro Datavalid estão declarados no mesmo contrato e entram como drivers quando houver credencial.

Segurança em seis camadas, nível de garantia ENHANCED, em conformidade com os requisitos da ISO/IEC 30107-3

O Biometrics segue os requisitos e as recomendações das normas de mercado para biometria facial — ISO/IEC 30107-1 e 30107-3 na detecção de ataque, ISO/IEC 19795-1 nas métricas de desempenho, ICAO 9303 na leitura de documento e LGPD no tratamento do dado. Não é homologado nem certificado por laboratório: a certificação iBeta está no roadmap, e até lá a conformidade é declarada pela Catalisa e demonstrada pelo relatório de avaliação no formato da ISO/IEC 30107-3.

Em teste de injeção por câmera virtual, um vídeo genuíno de uma sessão aprovada, reinjetado numa sessão nova, foi reprovado pelo desafio sorteado. Onde a operação exigir certificação de laboratório, os drivers CERTIFIED entram no mesmo contrato, sem mudar a integração.

Abrir conta pelo celular exige saber que a pessoa é quem diz ser. O jeito comum de resolver é comparar uma selfie com a foto do documento — e uma selfie é só uma foto. Uma foto impressa do rosto de outra pessoa passa, e uma foto na tela do celular também.

Os provedores que resolvem isso bem, como FaceTec, iProov e Unico, cobram por verificação em contrato anual, e o SDK deles decide dentro do app. Três consequências aparecem depois:

• A decisão é caixa-preta. Quando a verificação reprova um cliente bom, o time não sabe se foi luz, câmera, limiar ou modelo. Quando aprova um fraudador, também não.
• A auditoria não tem o que ver. A LGPD trata biometria como dado sensível, e "o fornecedor aprovou" não é evidência de como a decisão foi tomada.
• Trocar de fornecedor é reescrever. Cada SDK tem fluxo, formato de resposta e vocabulário de erro próprios, e a integração vira dívida no dia em que o contrato muda.

• Prova de vida em camadas. Passiva, por modelo que distingue pele de papel e de tela, e ativa, com gestos sorteados em quantidade, ordem e duração a cada sessão.
• Continuidade de identidade. O rosto do começo do vídeo tem que ser o do fim: trocar de pessoa no meio reprova.
• Decisão explicável. Nove status em vez de dois. INCONCLUSIVE vai para revisão humana (LGPD art. 20); RETRY_ALLOWED é experiência de uso, porque foto escura não é fraude.
• Evidência assinada. Hash do vídeo, do melhor quadro, da referência, dos checks e da política, assinado com chave Ed25519 da organização.
• Garantia declarada. O driver diz o que entrega — BASIC, ENHANCED ou CERTIFIED — e a política exige um mínimo. O motor aberto é ENHANCED.
• Página de captura pronta, com a cor, o logo e os textos da empresa, contagem de preparo antes de gravar e guia ao vivo que diz o que falta no gesto.
• Tudo parametrizável pela empresa: quantos gestos, quais, quanto tempo cada um, limiares, bloqueio por titular, retenção. Sem deploy.

Abertura de conta com documento

[Cenário ilustrativo] Fintech de crédito pessoal abre conta pelo celular e precisa de KYC com prova de vida.

A dor. A comparação da selfie com a foto do documento, sozinha, aprova uma foto impressa, e o fornecedor certificado custa mais por verificação do que a margem da primeira operação.

A solução com o bloco. Sessão ONBOARDING com a foto do documento como referência e enrollOnApprove: true. Na criação, o bloco lê a MRZ do passaporte ou o QR da CNH digital e recusa documento vencido se a política pedir. Depois avalia liveness e match e, ao aprovar, já grava o cadastro facial da pessoa.

O resultado. Validado em staging com passaporte e rosto reais: aprovado na primeira tentativa, match 0,702 contra o documento.

Confirmação de operação de alto valor

[Cenário ilustrativo] O mesmo cliente, meses depois, pede um saque acima do limite habitual.

A dor. SMS e senha provam posse de aparelho e conhecimento, não presença.

A solução com o bloco. Sessão AUTHENTICATION com referência ENROLLED_TEMPLATE. A comparação é contra o rosto que o próprio bloco capturou, não contra a foto do documento.

O resultado. Match 0,951 contra o cadastro feito pelo próprio bloco — o desenho é "documento uma vez, cadastro facial depois". E cinco falhas seguidas do mesmo CPF em uma hora bloqueiam o titular por 30 minutos.

Calibrar antes de contratar

[Cenário ilustrativo] Antes de decidir qual provedor contratar, é preciso saber como a própria base se comporta: quantos genuínos o sistema reprova, e por quê.

A solução com o bloco. Link de convite (POST /invites) compartilhado com voluntários. Cada pessoa rotula o que vai mostrar à câmera — ela mesma, uma foto impressa, uma tela, uma máscara — e o relatório cruza o rótulo com a decisão.

O resultado. Na medição em staging, nenhuma das 59 sessões genuínas foi reprovada pelo liveness; os ajustes ficaram no tempo e na leitura dos gestos, cada um com teste de regressão sobre as sessões reais gravadas.

O mercado de biometria facial tem três faixas. Os provedores certificados — FaceTec, iProov — vendem prova de vida auditada por laboratório. As redes de identidade — Unico — vendem a base compartilhada de rostos e fraudes. E a fonte primária estatal — Serpro Datavalid — compara com a foto da base oficial, sem prova de vida.

O bloco é a camada que fala com todos, com um motor próprio que atende sem contrato de terceiro.

Quando escolher o concorrente. Quando a regulação ou um parceiro exigir certificação de laboratório, a FaceTec ou a iProov entram como driver CERTIFIED no próprio bloco, mantendo política, evidência e trilha. Para somar o sinal de fraude compartilhado entre instituições, a Unico entra da mesma forma.

Unidade: sessão de verificação avaliada. Precificação em definição.

Drivers de custo: sessões avaliadas, tentativas por sessão (o limite padrão é 3), o fornecedor quando não for o motor próprio, e a retenção de mídia, que por padrão é de 30 dias.

Com o motor próprio não há custo por consulta a terceiro: o custo é CPU. Uma sessão de celular leva cerca de 8 segundos de avaliação num nó de 4 vCPUs, e o motor escala horizontalmente por réplica.

Com um driver externo, o custo do fornecedor fica registrado por sessão. Em ambos os casos o consumo vai ao Billing no medidor biometrics.verification, com o id da sessão como chave de idempotência.

flowchart TB
  TENANT["Sistema da empresa<br/>backend"]
  PESSOA["Pessoa<br/>navegador ou app"]

  subgraph BIO["Building Block Biometrics"]
    SESSAO["POST /sessions<br/>política e sorteio dos gestos"]
    PAGINA["Página de captura<br/>token de uso único"]
    SUBMIT["Submissão<br/>vídeo e telemetria"]
    DECISAO["Decisão<br/>checks, limiares, status"]
    EVID["Evidência<br/>hashes assinados Ed25519"]
  end

  ENGINE["face-engine<br/>motor próprio"]
  EXT["FaceTec, Unico, Serpro<br/>drivers declarados"]
  FS["File Storage<br/>vídeo e documento"]
  EVT["Webhooks Engine<br/>biometrics.session.completed"]

  TENANT --> SESSAO
  SESSAO -- "captureUrl" --> TENANT
  TENANT -- "link ou iframe" --> PESSOA
  PESSOA --> PAGINA
  PAGINA --> SUBMIT
  SUBMIT --> ENGINE
  SUBMIT -.-> EXT
  SUBMIT --> FS
  ENGINE --> DECISAO
  DECISAO --> EVID
  EVID --> EVT
  EVT --> TENANT

O motor. O face-engine é um serviço separado, em Python, que só o bloco alcança, com bearer próprio. Ele encadeia modelos de pesos abertos, todos publicados por terceiros com licença permissiva:

Os pesos são fixados por hash em models.lock.json: trocar um modelo muda a versão do motor, e a versão sai em todo check.

O que o bloco não faz, e quem faz

Glossário

Modelo de dados

Status de uma sessão

Os motivos da decisão formam um vocabulário fechado, com namespace, que a esteira da empresa pode automatizar: quality.too_dark, liveness.passive.failed, liveness.active.gesture_missing, liveness.active.timeout, identity.continuity_broken, match.below_threshold, match.gray_zone, capture.injection_suspected, capture.device_changed, policy.assurance_insufficient, subject.locked, entre outros — 27 no total.

Todas as rotas ficam sob /biometrics. As de /api/v1 exigem JWT com organizationId; as de captura e convite aceitam só o próprio token.

Sessões

POST /biometrics/api/v1/sessions

Request

{
  "flow": "ONBOARDING",
  "purpose": "abertura de conta",
  "subjectRef": { "type": "CPF", "value": "529.982.247-25" },
  "reference": { "source": "DOCUMENT_IMAGE", "fileId": "7c1e…" },
  "enrollOnApprove": true
}

{
  "flow": "ONBOARDING",
  "purpose": "abertura de conta",
  "subjectRef": { "type": "CPF", "value": "529.982.247-25" },
  "reference": { "source": "DOCUMENT_IMAGE", "fileId": "7c1e…" },
  "enrollOnApprove": true
}

Resposta 201

{
  "data": {
    "sessionId": "5b0e…",
    "flow": "ONBOARDING",
    "provider": "OPENSOURCE",
    "assurance": "ENHANCED",
    "status": "SESSION_OPEN",
    "attempt": 0,
    "maxAttempts": 3,
    "subjectRef": { "type": "CPF", "hmac": "…", "masked": "***.***.247-25" },
    "reference": {
      "source": "DOCUMENT_IMAGE",
      "portraitExtracted": true,
      "document": { "authenticity": "mrz-valid", "mrz": { "…": "mascarado" }, "qr": null }
    },
    "handoff": {
      "captureUrl": "https://biometrics.bb.stg.catalisa.app/biometrics/capture/eyJ…",
      "captureToken": "eyJ…",
      "captureMode": "RAW_FRAMES",
      "challenge": { "script": ["SMILE", "TURN_LEFT", "BLINK"], "timeoutMs": 22000, "slotsMs": [5200, 6100, 4800] },
      "expiresAt": "2026-09-18T15:00:00.000Z"
    },
    "expiresAt": "2026-09-18T15:00:00.000Z"
  }
}

{
  "data": {
    "sessionId": "5b0e…",
    "flow": "ONBOARDING",
    "provider": "OPENSOURCE",
    "assurance": "ENHANCED",
    "status": "SESSION_OPEN",
    "attempt": 0,
    "maxAttempts": 3,
    "subjectRef": { "type": "CPF", "hmac": "…", "masked": "***.***.247-25" },
    "reference": {
      "source": "DOCUMENT_IMAGE",
      "portraitExtracted": true,
      "document": { "authenticity": "mrz-valid", "mrz": { "…": "mascarado" }, "qr": null }
    },
    "handoff": {
      "captureUrl": "https://biometrics.bb.stg.catalisa.app/biometrics/capture/eyJ…",
      "captureToken": "eyJ…",
      "captureMode": "RAW_FRAMES",
      "challenge": { "script": ["SMILE", "TURN_LEFT", "BLINK"], "timeoutMs": 22000, "slotsMs": [5200, 6100, 4800] },
      "expiresAt": "2026-09-18T15:00:00.000Z"
    },
    "expiresAt": "2026-09-18T15:00:00.000Z"
  }
}

Perfil avaliado. Todo envelope do motor próprio traz evaluation: o perfil de avaliação ISO/IEC 30107-3 a que a sessão se refere, se ela rodou dentro dele (conforms) e, se não, o que saiu (violations). A garantia CERTIFIED vale só para sessão conforme a um perfil com laudo emitido. GET /policy e PUT /policy devolvem a mesma conformidade em meta.evaluationProfiles, e GET /catalog lista os perfis.

"evaluation": {
  "profileId": "pad-l1-2026-09",
  "label": "Candidato ISO/IEC 30107-3 Nível 1",
  "standard": "ISO/IEC 30107-3",
  "conforms": true,
  "certified": false,
  "violations": []
}

"evaluation": {
  "profileId": "pad-l1-2026-09",
  "label": "Candidato ISO/IEC 30107-3 Nível 1",
  "standard": "ISO/IEC 30107-3",
  "conforms": true,
  "certified": false,
  "violations": []
}

Depois da decisão, GET /sessions/:id traz decision com outcome, reasons e reviewRequired; checks[] com status, score, threshold, reasons e o engine (nome, modelo e versão) de cada verificação; evidence com os hashes e a assinatura; e enrollment.templateId quando enrollOnApprove gravou o cadastro.

Erros

Captura e convite (públicas, por token)

Cadastro facial

Evidência e direitos do titular

O CPF vai no corpo, nunca na URL, para não aparecer em log de acesso.

Fornecedores, política e consumo

1. Autenticar

TOKEN=$(curl -s -X POST https://iam.bb.stg.catalisa.app/iam/api/v1/users/login \
  -H "Content-Type: application/json" \
  -d '{"email":"SEU-EMAIL","password":"SUA-SENHA","organizationId":"SUA-ORG"}' \
  | jq -r .accessToken)
BIO=https://biometrics.bb.stg.catalisa.app/biometrics/api/v1

TOKEN=$(curl -s -X POST https://iam.bb.stg.catalisa.app/iam/api/v1/users/login \
  -H "Content-Type: application/json" \
  -d '{"email":"SEU-EMAIL","password":"SUA-SENHA","organizationId":"SUA-ORG"}' \
  | jq -r .accessToken)
BIO=https://biometrics.bb.stg.catalisa.app/biometrics/api/v1

2. Cadastrar o motor próprio como padrão

curl -X POST $BIO/providers \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "name": "motor-proprio", "providerType": "OPENSOURCE", "isDefault": true }'

curl -X POST $BIO/providers \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "name": "motor-proprio", "providerType": "OPENSOURCE", "isDefault": true }'

3. Abrir uma sessão de prova de vida

curl -s -X POST $BIO/sessions \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "flow": "LIVENESS_ONLY", "purpose": "teste do inicio rapido" }' \
  | jq '.data | {sessionId, captureUrl: .handoff.captureUrl}'

curl -s -X POST $BIO/sessions \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "flow": "LIVENESS_ONLY", "purpose": "teste do inicio rapido" }' \
  | jq '.data | {sessionId, captureUrl: .handoff.captureUrl}'

4. Abrir o captureUrl no celular e seguir a página. Ela pede a câmera, mostra o primeiro gesto com uma contagem de 2,5 s antes de gravar, guia os gestos sorteados e envia sozinha.

5. Ler a decisão

curl -s $BIO/sessions/$SESSION_ID -H "Authorization: Bearer $TOKEN" \
  | jq '.data | {status, decision, checks: [.checks[] | {kind, status, score, threshold}]}'

curl -s $BIO/sessions/$SESSION_ID -H "Authorization: Bearer $TOKEN" \
  | jq '.data | {status, decision, checks: [.checks[] | {kind, status, score, threshold}]}'

{
  "status": "APPROVED",
  "decision": { "outcome": "APPROVED", "reasons": [], "reviewRequired": false },
  "checks": [
    { "kind": "quality.capture", "status": "PASSED", "score": 0.91, "threshold": 0.6 },
    { "kind": "liveness.passive", "status": "PASSED", "score": 0.97, "threshold": 0.8 },
    { "kind": "liveness.active", "status": "PASSED", "score": 1, "threshold": 1 },
    { "kind": "identity.continuity", "status": "PASSED", "score": 0.95, "threshold": 0.7 }
  ]
}

{
  "status": "APPROVED",
  "decision": { "outcome": "APPROVED", "reasons": [], "reviewRequired": false },
  "checks": [
    { "kind": "quality.capture", "status": "PASSED", "score": 0.91, "threshold": 0.6 },
    { "kind": "liveness.passive", "status": "PASSED", "score": 0.97, "threshold": 0.8 },
    { "kind": "liveness.active", "status": "PASSED", "score": 1, "threshold": 1 },
    { "kind": "identity.continuity", "status": "PASSED", "score": 0.95, "threshold": 0.7 }
  ]
}

Mais tempo para cada gesto. Público mais velho ou celular mais lento pedem janela maior. A política aceita o intervalo sorteado por gesto e o teto do vídeo:

curl -X PUT $BIO/policy -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "challenge": { "gestures": 2, "gesturesMax": 3, "slotMinMs": 5500, "slotMaxMs": 7500, "timeoutMs": 24000 } }'

curl -X PUT $BIO/policy -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "challenge": { "gestures": 2, "gesturesMax": 3, "slotMinMs": 5500, "slotMaxMs": 7500, "timeoutMs": 24000 } }'

O vídeo inteiro não passa de 24 segundos — é o limite do motor. Menos gestos com mais tempo costumam reprovar menos gente do que mais gestos com pouco tempo.

Escolher os gestos. challenge.pool restringe o catálogo; o padrão tem sete (virar à esquerda e à direita, piscar, sorrir, abrir a boca, acenar com a cabeça, erguer as sobrancelhas). approachEnabled: true inclui aproximar o rosto da câmera, que funciona bem no celular e mal no notebook.

Página com a cara da empresa. appearance no fornecedor vale para todas as sessões; na sessão, só para ela. Cores, raio dos cantos, fonte de uma lista fechada, logo por fileId, modo claro, escuro ou automático, textos por idioma e redirectUrl. Nada vira CSS ou JavaScript livre.

Embutir em iframe. Liste a origem em allowedEmbedHosts do fornecedor e use allow="camera". A página avisa o andamento por postMessage — nunca o resultado:

<iframe id="bio" src="CAPTURE_URL" allow="camera"></iframe>
<script>
  window.addEventListener('message', (e) => {
    if (e.origin !== 'https://biometrics.bb.stg.catalisa.app' || e.data?.source !== 'catalisa-biometrics') return
    if (e.data.event === 'done') consultarSessaoNoBackend()
  })
</script>

<iframe id="bio" src="CAPTURE_URL" allow="camera"></iframe>
<script>
  window.addEventListener('message', (e) => {
    if (e.origin !== 'https://biometrics.bb.stg.catalisa.app' || e.data?.source !== 'catalisa-biometrics') return
    if (e.data.event === 'done') consultarSessaoNoBackend()
  })
</script>

Verificar a evidência sem a Catalisa. Baixe a chave pública em GET /evidence-keys e confira a assinatura de GET /sessions/:id/evidence. A mensagem assinada é sessionId|attempt|bundleHash|signedAt, e o bundleHash já resume checks, artefatos, política e roteiro — basta openssl pkeyutl -verify com a chave pública.

Modo avaliação para laboratório e pré-teste. Numa organização listada em BIOMETRICS_EVALUATION_ORG_IDS, a página mostra um selo com a sessão e a tentativa e, ao fim, o resultado com os motivos, para o avaliador registrar cada apresentação. Fora dessas organizações a página nunca mostra o resultado.

Medir antes de ligar em produção. POST /invites gera um link válido por até 90 dias para voluntários. A página rotula o que a pessoa mostra à câmera — ela mesma, foto impressa, foto numa tela, vídeo numa tela ou máscara, as espécies da ISO/IEC 30107-3 — e o relatório devolve APCER por espécie, BPCER e as taxas de não resposta, no vocabulário do laudo.

Eventos publicados

Variáveis de ambiente

As duas master keys são separadas de propósito: a da credencial gira com o contrato do fornecedor; a do cadastro facial exige recifrar a base inteira.

Política por organização, sem deploy (PUT /policy)

Observabilidade. O bloco publica métricas OpenTelemetry de baixa cardinalidade: sessões por fluxo e resultado, checks por tipo, histograma de score, motivos da decisão, duração da avaliação e de cada etapa do motor, e criações recusadas. Nenhum rótulo carrega CPF, sessão ou organização.

O motor em operação. O face-engine sobe com os pesos embutidos na imagem e aquece os modelos antes de se declarar saudável. Uma sessão de celular leva ~8 s em 4 vCPUs; a análise dos pontos do rosto roda em paralelo por quadro.

Biometria é dado pessoal sensível (LGPD art. 5º, II). O desenho parte disso:

Quem está diante da câmera não carrega credencial. A página recebe um captureToken de escopo único e uso único por tentativa, e só as rotas de captura o aceitam. A página roda com CSP por nonce; os arquivos do guia ao vivo são servidos pelo próprio bloco com hash fixo, sem CDN.

A página não diz o resultado. Nem aprovado, nem reprovado: quem decide o que dizer à pessoa é a empresa, depois de ler o envelope pelo servidor. Isso impede que um fraudador use a página como oráculo para ajustar o ataque.

Contra injeção de vídeo. Os gestos são sorteados em quantidade, ordem e duração por sessão, e a janela de cada um é conferida no vídeo. Na medição, um vídeo genuíno aprovado, reinjetado por câmera virtual, passou no liveness passivo e na continuidade — é rosto real — e foi reprovado pela janela sorteada. Troca de dispositivo entre tentativas vira INCONCLUSIVE.

Contra força bruta. O mesmo CPF com 5 sessões reprovadas ou inconclusivas em 60 minutos fica bloqueado por 30. Os três números são da política.

Evidência assinada. Cada organização tem uma chave Ed25519 própria, criada no primeiro uso, com a privada cifrada. A pública é publicada para que a auditoria verifique sem depender da Catalisa.

Conformidade com normas

O bloco é desenvolvido em conformidade com os requisitos e as recomendações das normas abaixo. Conformidade declarada pela Catalisa — sem homologação nem certificação de terceiro.

Certificações no roadmap (nenhuma emitida até aqui)

Usa inteligência artificial de terceiros?

Usa modelos de pesos abertos publicados por terceiros — YuNet, MiniFASNet, MediaPipe, Facenet512 —, rodando na nossa infraestrutura. Nenhuma imagem sai para serviço externo. Os pesos são fixados por hash e a versão aparece em cada check.

Substitui a FaceTec?

O motor próprio atende sem contrato de terceiro nos fluxos em que o nível ENHANCED basta. Onde a certificação for exigida, a FaceTec entra como driver e a integração não muda.

Por que a página não mostra se aprovou?

Porque a página está nas mãos de quem está diante da câmera, que pode ser um fraudador. Mostrar o resultado transforma a página num oráculo para ajustar o ataque. A empresa lê o envelope pelo servidor e decide o que dizer.

A empresa pode configurar quanto tempo cada gesto dura?

Pode, pela política da organização, sem deploy: quantidade de gestos, janela mínima e máxima de cada um, o tempo total até 24 segundos e quais gestos entram no sorteio.

Qual a diferença entre REJECTED e INCONCLUSIVE?

REJECTED é o sistema seguro de que não deve aprovar. INCONCLUSIVE é zona cinzenta — match entre os limiares, sinal heurístico de câmera virtual, troca de dispositivo — e vai para revisão humana, como pede a LGPD para decisão automatizada com efeito relevante.

Precisa pedir o documento em toda verificação?

Não. O documento entra uma vez, no ONBOARDING com enrollOnApprove. Depois, a autenticação compara com o cadastro facial, que chega a 0,95 de match.

Funciona no navegador ou precisa de app?

No navegador, sem instalar nada. Antes de gravar, a página mostra o primeiro gesto com uma contagem de 2,5 s. O guia ao vivo roda no próprio navegador e se desliga sozinho em conexão lenta ou com economia de dados; a captura funciona sem ele. Para app nativo, a rota POST /sessions/:id/captures aceita a submissão de um SDK próprio com o mesmo captureToken.