@beltec/face-gate 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,218 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @beltec/face-gate
+
+**Face Gate, uma solução BelTec** — validação de fotos de rosto para o cadastro de visitantes e moradores no
+controle de acesso. Este pacote traz:
+
+- **`<FaceGate>`** (React): webcam com validação em **tempo real** — mira que segue o rosto, orientação do que
+  corrigir, captura automática só quando a pessoa fica parada com tudo aprovado, scanner sobre a foto e a foto
+  final (com o fundo removido, se contratado).
+- **`@beltec/face-gate/server`** (Node/Next): guarda a sua chave, emite o ticket do navegador e valida arquivos.
+
+O `client_secret` **nunca** vai ao navegador: o seu servidor pede um ticket de uso único (60 s) e só ele chega à
+página.
+
+```
+navegador ──POST /api/face-gate/ticket──▶ seu servidor ──chave──▶ Face Gate API
+navegador ◀──────── ticket (60 s) ────────┘
+navegador ══ WebSocket (ticket) ══▶ Face Gate API  (quadros ao vivo → captura → resultado)
+```
+
+## Instalação
+
+```bash
+npm install @beltec/face-gate
+```
+
+React 18+ no navegador; Node 18.17+ no servidor. Crie a chave no portal do Face Gate
+(**Chaves de acesso**): você recebe o `client_id` e o `client_secret` (este aparece uma vez só).
+
+```bash
+# .env do seu servidor
+FACE_GATE_CLIENT_ID=...
+FACE_GATE_CLIENT_SECRET=...
+```
+
+## Next.js (App Router)
+
+**1. Rota que emite o ticket** — `app/api/face-gate/ticket/route.ts`
+
+```ts
+import { createFaceGate } from "@beltec/face-gate/server";
+
+const faceGate = createFaceGate({
+  clientId: process.env.FACE_GATE_CLIENT_ID!,
+  clientSecret: process.env.FACE_GATE_CLIENT_SECRET!,
+});
+
+// Só usuários logados no SEU sistema abrem a câmera (cada captura consome tokens do seu plano).
+export const POST = faceGate.ticketHandler({
+  authorize: async (req) => Boolean(await getSessionFromYourApp(req)),
+});
+```
+
+**2. A tela** — um Client Component
+
+```tsx
+"use client";
+import { FaceGate } from "@beltec/face-gate";
+import "@beltec/face-gate/styles.css";
+
+export function CadastroFoto() {
+  return (
+    <FaceGate
+      clean // devolve a foto sem fundo (serviço "validar e remover fundo" contratado)
+      getTicket={async () => {
+        const r = await fetch("/api/face-gate/ticket", { method: "POST" });
+        if (!r.ok) throw new Error("Não foi possível abrir a câmera");
+        return r.json();
+      }}
+      onCapture={({ image, result }) => {
+        if (result.accepted) salvarFoto(image); // data URL (PNG sem fundo ou JPEG do quadro)
+      }}
+      onError={(e) => console.warn(e.code, e.message)}
+    />
+  );
+}
+```
+
+## Validar um arquivo (sem webcam)
+
+```ts
+import { createFaceGate } from "@beltec/face-gate/server";
+
+const faceGate = createFaceGate({ clientId, clientSecret });
+const result = await faceGate.validate(fileBuffer, { clean: true, model: "birefnet-portrait" });
+
+result.accepted;        // true | false
+result.hard_fails;      // ex.: ["eyes_closed", "glasses_sunglasses"]
+result.cleaned_image;   // PNG sem fundo (data URL), quando clean
+result.usage?.tokens;   // tokens gastos nesta análise
+```
+
+Com melhoria de imagem: `faceGate.validate(fileBuffer, { enhance: "classic" })` (veja abaixo).
+
+Express/Fastify funcionam igual: use `createStreamTicket()` na sua rota e devolva `{ ticket, url }` ao navegador.
+
+## `<FaceGate>` — propriedades
+
+| Prop | Tipo | Padrão | |
+|---|---|---|---|
+| `getTicket` | `() => Promise<{ ticket, url }>` | — | chama a sua rota de ticket |
+| `onCapture` | `({ image, frame, result }) => void` | — | foto capturada e validada |
+| `onLive` | `(result) => void` | — | cada quadro analisado ao vivo |
+| `onError` | `(error: FaceGateError) => void` | — | câmera negada, limite de tokens, rede… |
+| `clean` | `boolean` | `false` | remover o fundo da foto capturada |
+| `model` | `"u2net" \| "u2netp" \| "birefnet-portrait"` | servidor | modelo da remoção de fundo |
+| `device` | `"cpu" \| "gpu"` | servidor | onde rodar a remoção de fundo |
+| `enhance` | `"classic" \| "gfpgan" \| null` | `null` | melhorar a foto capturada antes de validar (serviço "validar com melhoria") |
+| `thresholds` | `Record<string, number>` | servidor | limiares (nomes de `GET /v1/thresholds`) |
+| `autoFrame` | `boolean` | `true` | enquadramento automático: a imagem aproxima e acompanha o rosto, mantendo-o no centro; a foto capturada é esse recorte e só sai com o rosto centralizado (tolerância de 8%, ou a sua em `thresholds` se for mais rígida). Ignora as tarjas pretas que algumas câmeras acrescentam |
+| `mirror` | `boolean` | `true` | prévia espelhada, como um espelho (a foto enviada e a final não são espelhadas) |
+| `autoStart` | `boolean` | `false` | ligar a câmera ao montar |
+| `intro` | `boolean` | `true` | abertura animada do escudo |
+| `watermark` | `boolean` | `true` | escudo no canto do vídeo |
+| `labels` | `Partial<FaceGateLabels>` | pt-BR | troque qualquer texto |
+
+### Aparência
+
+Os estilos usam o prefixo `.fg-` e variáveis CSS:
+
+```css
+.minha-tela .fg-root {
+  --fg-accent: #c9a43e;      /* mira, botão, barra de "fique parado" */
+  --fg-accent-text: #1d2125; /* texto sobre o botão */
+  --fg-surface: #1d2125;     /* fundo do vídeo */
+  --fg-radius: 12px;
+}
+```
+
+Respeita `prefers-reduced-motion` (sem animações).
+
+## Melhoria de imagem
+
+Serviço contratável **"Validar com melhoria"** (scope `validate_enhance`). A API melhora a foto, valida a
+versão melhorada e devolve `enhancement` com o resultado **antes** (original) e **depois** (melhorada) e a
+imagem melhorada (`enhancement.enhanced_image`, JPEG). No `<FaceGate enhance="classic">`, só a foto
+capturada passa pela melhoria (os quadros ao vivo não), o `onCapture` entrega a melhorada em `image` e a
+tela mostra o selo "Imagem melhorada".
+
+| Método | O que faz | Custo |
+|---|---|---|
+| `classic` | balanço de branco, exposição, contraste local, redução de ruído e nitidez leve. Determinística, não altera o rosto | baixo |
+| `gfpgan` | a clássica + restauração do rosto com IA (GFPGAN). Recria detalhes do rosto: a resposta traz o aviso `face_restored_ai` e o componente mostra o alerta | alto |
+
+**Regra:** a melhoria só corrige luz (`poor_lighting`, `overexposed`) e rosto não encontrado por falta de
+luz (`no_face`). As demais falhas da foto original — desfoque, olhos fechados, óculos escuros, pose… —
+continuam reprovando (`enhancement.carried_over`). Com `clean`, o fundo é removido da foto melhorada (exige
+também o serviço "validar e remover fundo").
+
+**Tokens:** a validação roda duas vezes (antes e depois) e soma a etapa `usage.breakdown.enhance`
+(a clássica é barata; o GFPGAN custa bem mais).
+
+## Avatar
+
+Serviço **Avatar** contratado (`POST /v1/photos/avatar`): valida a foto e, se aprovada, devolve o avatar só com a
+pessoa do rosto em foco — o fundo e outros elementos ou pessoas são removidos —, recortado centrado no rosto.
+
+```ts
+import { createFaceGate } from "@beltec/face-gate/server";
+
+const faceGate = createFaceGate({ clientId, clientSecret });
+const r = await faceGate.avatar(fileBuffer, {
+  shape: "round",            // "round" (padrão; fora do círculo transparente) | "square"
+  size: 512,                 // 64 a 1024
+  backgroundColor: "#1d252a", // ou background: <imagem> (tem prioridade); sem nenhum = PNG transparente
+  margin: 25,                 // só com fundo: % do quadro deixado para o fundo (0 a 60)
+  layout: "bottom",           // só com fundo: "center" | "bottom" | "left" | "right"
+});
+
+if (r.accepted) r.avatar_image; // data:image/png;base64,...
+else r.hard_fails;             // sem avatar: os mesmos motivos da validação
+```
+
+| Opção | Tipo | Padrão | |
+|---|---|---|---|
+| `shape` | `"round" \| "square"` | `"round"` | formato do recorte |
+| `size` | `number` | `512` | lado em pixels (64 a 1024) |
+| `backgroundColor` | `string` | — | cor sólida `#RRGGBB` |
+| `background` | `Blob \| ArrayBuffer \| Uint8Array` | — | imagem de fundo (preenche o quadro) |
+| `template` | `number` | — | id de um **template de avatar** salvo no portal (Avatares): formato, tamanho, fundo e enquadramento prontos, sem reenviar a imagem; as outras opções têm prioridade |
+| `backgroundPosition` | `{ x?, y?, zoom? }` | centro, `zoom` 100 | **só com `background`**: qual parte da imagem aparece — `x`/`y` de 0 a 100 (50 = centro, como o `object-position` do CSS) e `zoom` de 100 a 300 % |
+| `margin` | `number` | `0` | **só com fundo**: % do quadro deixado para o fundo em volta da pessoa (0 a 60) |
+| `layout` | `"center" \| "bottom" \| "left" \| "right"` | `"center"` | **só com fundo**: onde a pessoa fica (centro, apoiada na base, base à esquerda/direita) |
+| `model` / `device` | | servidor (BiRefNet) | modelo de remoção de fundo que separa a pessoa |
+| `thresholds` | `Record<string, number>` | servidor | limiares da validação |
+
+O resultado traz também `avatar` (`shape`, `size`, `model`, `background`, `margin`, `layout`). **Tokens:** soma a etapa `avatar`
+em `usage.breakdown` (a separação da pessoa roda na imagem analisada inteira).
+
+## Tokens e erros
+
+Cada foto capturada (e cada `validate`) consome **tokens** do seu plano — megapixels processados × peso de cada
+etapa; foto maior ou remoção de fundo com BiRefNet gastam mais. Os quadros ao vivo da webcam não consomem.
+O plano limita os tokens por **janela** (ex.: 5 h a partir do 1º uso) e por **mês** (renova no aniversário do
+contrato).
+
+`FaceGateError.code`:
+
+| code | quando |
+|---|---|
+| `token_window_limit` | janela de tokens esgotada (`resetsAt` = quando renova) |
+| `token_month_limit` | teto mensal atingido (`resetsAt` = data da renovação) |
+| `forbidden` | serviço não contratado, chave bloqueada/expirada, fora do contrato ou IP não liberado |
+| `unauthorized` | chave/ticket inválido ou expirado |
+| `camera_denied` / `camera_unavailable` | permissão negada, sem câmera ou página sem HTTPS |
+| `network` / `server` / `bad_request` | falhas de conexão ou da API |
+
+## Segurança e LGPD
+
+- A whitelist de IPs da chave vale para o **seu servidor** (onde o ticket é emitido); o navegador usa só o
+  ticket de uso único.
+- A API não guarda as imagens: só o resultado e metadados da validação.
+- A câmera exige HTTPS (ou `localhost`).
+- As chamadas do servidor saem com o User-Agent `face-gate-sdk/<versão> (node <versão>; <sistema>)`
+  (`SDK_USER_AGENT`). Assim, uma tentativa de um IP não liberado aparece no portal como "SDK Face Gate <versão>".
+
+---
+
+© BelTec, do grupo Belfort. Uso sujeito ao contrato do Face Gate.