Integração com um agente de IA de programação

Muitas equipes integram o FingerTrackID com um agente de IA de programação. Esta página dá ao agente a documentação no formato que ele lê melhor e as regras que ele não pode quebrar. A entrega da implementação continua sendo o roteiro da integração em si.

Início rápido

1. Baixe o arquivo de integração. No console, Integração e saúde › Arquivo da integração baixa o fingertrackid.integration.json. Quem o gera é um administrador da empresa ou um gestor de integração. Salve-o na raiz do repositório que integra o FingerTrackID (o arquivo de integração).

2. Guarde o segredo você mesmo. Quem recebeu o segredo HMAC uma única vez no console o coloca direto no gerenciador de segredos do backend, de onde o backend o lê como FTID_HMAC_SECRET_HEX. Ele nunca vai para o agente (o que nunca vai para uma IA).

3. Adicione o servidor MCP ao seu agente. No Claude Code, a partir da raiz do repositório:

   claude mcp add --scope project fingertrackid -- npx -y @fingertrackid/mcp@0.1.3

   Para outros clientes, veja o servidor MCP. Um agente sem MCP lê, em vez disso, o /llms-full.txt e o arquivo de integração.

4. Dê as regras ao agente. Cole o bloco de regras no AGENTS.md, no CLAUDE.md ou no equivalente da sua ferramenta.

5. Peça ao agente que faça a integração. No Claude Code, rode o prompt do servidor com as suas etiquetas, separadas por vírgula:

   /mcp__fingertrackid__integrate_fingertrackid login,withdrawal

   Em outro agente, ou sem MCP, cole o prompt de integração. O agente lê o arquivo de integração e adiciona uma chamada fail-open por etiqueta com o SDK de servidor. Depois, ele inclui o token do Web SDK na requisição que você já tem e valida um corpo de requisição sintético.

6. Confira a credencial real você mesmo. Passe por pipe o segredo do seu gerenciador de segredos para o npx --no fingertrackid-server check (como). Ele envia uma avaliação real em modo shadow e imprime o veredito. Depois, revise o trabalho do agente antes do tráfego real.

O prompt de integração

Copie este prompt para o seu agente de IA de programação, a partir da raiz do repositório que contém o seu site e o seu backend. Ele funciona com ou sem o servidor MCP. O agente para e espera a sua confirmação antes de editar qualquer coisa, e nunca precisa do segredo.

Prompt de integração

Cole-o no seu agente de IA de programação ou abra-o em um agente.

Integrate FingerTrackID into this project, in shadow mode: FingerTrackID recommends, and our
system keeps deciding and acting as it does today.

Sources, in this order:
- The fingertrackid MCP server, when it is connected: start with ftid_read_manifest.
- fingertrackid.integration.json at the repository root: the issued values (API origin,
  application public key, allowed origins, collection origin, key_id, Web SDK package). Never
  invent them or copy them from an example.
- The documentation, https://docs.fingertrackid.com/llms-full.txt. The published contracts win
  over any prose or example.

Never ask for, print, log, commit or store the HMAC secret. The backend reads it at runtime, by
name, as FTID_HMAC_SECRET_HEX from our secret manager. If a step needs its value, stop and tell me.

Show me your plan before you edit anything, then work in this order:

1. Inventory. Find where users sign in (including MFA and redirects such as Google sign-in), sign
   up, recover a password and take sensitive actions (withdrawals, transfers, changes of email,
   phone or password). Propose one lowercase tag per moment, such as login, signup,
   password_recovery or withdrawal, using the FingerTrackID templates. Wait for my confirmation.
2. Missing inputs. Check the integration file. If the collection origin, a server credential with
   assessment:write or the Web SDK package is missing, tell me what to do in the console, and
   continue only with the work that does not depend on it.
3. Backend. In Node.js, install the server SDK with the exact version:
   npm install --save-exact @fingertrackid/server@0.1.2
   Create one module with one function per tag (the MCP tool ftid_server_recipe generates it).
   In another language, implement the signature from
   https://docs.fingertrackid.com/api/authentication/ and match the public test vector first.
   - Call each function after our own checks and before our product acts: for login, after the
     real authentication and MFA. Keep our own decision.
   - Fail open: when FingerTrackID is slow, unavailable or misconfigured, the product works as
     today, and the failure is logged without secrets.
   - subject_ref and account_ref are keyed pseudonyms the backend derives, for example
     HMAC-SHA-256 of our internal ID with a key only the backend holds. Never an email, tax ID,
     phone number or name.
   - Log only identifiers and verdicts: tag, result kind, assessment_id, recommended action and
     correlation ID. Never the token, the signature or the request body.
   - When a result is UNAVAILABLE or UNEXPECTED_RESPONSE, keep result.operation with our record
     so it can be resent.
4. Browser. Install the private Web SDK archive named in the integration file's sdk_package. A
   person downloads it from the console. Verify its SHA-256 and SHA-512 against the file, then
   run npm install --save-exact --ignore-scripts ./fingertrackid-sdk-web.tgz. Never install a
   public package with a similar name. Then follow
   https://docs.fingertrackid.com/web-sdk/collection/#the-recipe:
   - one module with initializeSdk, only in browser code, with the publicKey and
     collectionOrigin from the integration file, and createActionContextHelper;
   - prefetch() on the first focus or pointer-down of each assessed form, never at page load,
     and only after any consent our privacy rules require;
   - take() once per submit;
   - the token and its expiresAt, or null, sent inside the existing authenticated,
     CSRF-protected request;
   - the helper closed on logout or account switch.
   The SDK never reads form values or passwords.
5. Site configuration. Add the collection origin to connect-src in our Content-Security-Policy.
   Keep that origin out of tracing header propagation (Sentry tracePropagationTargets, Datadog
   allowedTracingUrls, OpenTelemetry propagateTraceHeaderCorsUrls).
6. Checks.
   - Run npx --no fingertrackid-server self-check.
   - Validate one synthetic request body (ftid_validate_request in the MCP server).
   - Add tests for the fail-open paths: FingerTrackID unavailable, and a null token.
   - Run our test suite.
7. Hand-off.
   - List every file you changed, and what I must still do in the console.
   - Ask me to run npx --no fingertrackid-server check with the secret piped from our secret
     manager. It sends one real assessment in shadow mode.

Documentação para o agente

Arquivo	Conteúdo	Use para
/llms.txt	Um resumo curto da plataforma, as regras dela e um link para cada conjunto de documentação	O ponto de partida do agente
/llms-full.txt	Todas as páginas deste site em um único arquivo de texto simples	Trabalho de integração completo
/llms-small.txt	As mesmas páginas com os espaços em branco removidos; todas as notas, avisos e seções expansíveis são mantidos	Janelas de contexto menores

Os três arquivos são gerados a partir destas páginas a cada publicação, então não dizem nada que as páginas não digam. Os contratos publicados (OpenAPI e JSON Schema, com links na visão geral da API) prevalecem sobre qualquer texto ou exemplo, nesses arquivos e em todas as páginas.

O arquivo de integração

No console, Integração e saúde › Arquivo da integração (também no Início, na etapa do SDK) baixa o fingertrackid.integration.json. Salve-o na raiz do repositório que integra o FingerTrackID: o agente lê dele os valores emitidos em vez de copiá-los à mão.

Campo	Conteúdo
api_origin, documentation, request_profile	A origem da API de produção, esta documentação para agentes e o perfil de requisição a enviar
secret	Só o nome da variável da qual o backend lê o segredo, FTID_HMAC_SECRET_HEX. Nunca o segredo
application	O ID, o slug, o nome, o ambiente, a chave pública do navegador e as origens permitidas da aplicação
collection	A origem de coleta first-party confirmada, ou null até o domínio de coleta estar ativo
server_credentials	O key_id, as capacidades e a taxa aprovada de cada credencial de servidor vigente
sdk_package	A versão, o SHA-256 e o SHA-512 do arquivo compactado aprovado do Web SDK, ou null

O arquivo contém apenas identificadores públicos, então você pode fazer commit dele. Baixe-o de novo quando uma chave, o pacote do SDK ou as origens mudarem: ele não se atualiza sozinho. O contrato dele é o schema do manifesto de integração.

O servidor MCP

O @fingertrackid/mcp é um servidor local do Model Context Protocol para agentes de programação que suportam MCP. Ele roda na máquina do desenvolvedor, via stdio, lê o arquivo de integração e valores públicos, e não altera nada. Nenhuma ferramenta aceita o segredo HMAC.

Adicione-o com a versão exata. No Claude Code, para este projeto:

claude mcp add --scope project fingertrackid -- npx -y @fingertrackid/mcp@0.1.3

Outros clientes que leem um arquivo mcpServers, como o .mcp.json:

{
  "mcpServers": {
    "fingertrackid": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@fingertrackid/mcp@0.1.3"]
    }
  }
}

Inicie o agente a partir da raiz do repositório, onde está o arquivo de integração. Depois, peça que ele rode o prompt integrate_fingertrackid ou que use as ferramentas diretamente:

Ferramenta	O que faz
ftid_read_manifest	Lê o arquivo de integração e lista o que ainda falta no console
ftid_list_templates	Os dez momentos comuns a avaliar, com a etiqueta sugerida e as referências (modelos)
ftid_server_recipe	Um módulo TypeScript completo para o SDK de servidor, com uma função fail-open por etiqueta
ftid_validate_request	Confere um corpo de requisição exatamente como a API o lê
ftid_explain_signature	As dez linhas canônicas e o MAC de um corpo, com o segredo de teste público
ftid_check_vector_mac	Compara um assinador em qualquer linguagem com o vetor de teste público
ftid_interpret_response	Explica uma avaliação ou um Problem, e se deve haver nova tentativa
ftid_check_collection_domain	Lê o DNS e o TLS públicos do seu domínio de coleta, só para um domínio das origens da aplicação no arquivo de integração

O servidor também serve os contratos públicos como recursos. Toda ferramenta é somente leitura; a primeira chamada real continua partindo do seu backend, com o segredo que ele lê do seu gerenciador de segredos.

Regras para o seu repositório

Cole este bloco no arquivo de instruções que o seu agente lê (AGENTS.md, CLAUDE.md ou o equivalente da sua ferramenta), no repositório que chama o FingerTrackID.

Regras do repositório

Cole-as no AGENTS.md, no CLAUDE.md ou no equivalente da sua ferramenta.

## FingerTrackID integration

Documentation: https://docs.fingertrackid.com/llms-full.txt. The published contracts win over
any prose or example.

- Shadow mode. FingerTrackID recommends; this system decides and executes every action. Never
  block, allow, hold or settle anything because of a recommendation unless the product team
  decided it explicitly.
- Fail open. If FingerTrackID is slow, unavailable or misconfigured, the product keeps working
  with its own decision, and the failure is reported, not hidden.
- HMAC secret. Read it at runtime from the server-side secret manager, by name. Never ask for
  its value, and never print, log, commit or store it, or put it in a test, fixture, example or
  browser-exposed variable.
- Issued values. The key_id, the browser public key, the collection origin and the DNS records
  come from the FingerTrackID console. Never take them from a documentation example or from
  another application.
- Signing. FTID-HMAC-SHA256-V1 over the decoded secret bytes, never the hexadecimal text.
  Reproduce the published test vector byte for byte before the first real call.
- Body. Serialize it once. A retry resends the same bytes with a new X-FTID-Request-Id
  (UUIDv7), the current X-FTID-Timestamp and a new signature. Content-Type is exactly
  application/json, with no Content-Encoding.
- References. subject_ref and account_ref are keyed pseudonyms created by this backend (for
  example HMAC-SHA-256 of the internal ID with a backend key). Never send an email, tax ID,
  phone number, name or account number. account_ref requires subject_ref.
- Browser token. The event_context_token goes from the browser SDK to this backend inside the
  existing authenticated, CSRF-protected request. It is not a result; never log it.
- Response. trust_score null means no score, never 0 or 100, and INCONCLUSIVE is a normal
  outcome. Keep X-Correlation-Id for support.
- Logs. Never log the secret, the token, the signature or the full request body.

O que nunca vai para uma IA

• O segredo HMAC. Um administrador da empresa ou gestor de integração o recebe uma única vez no console e o coloca direto no gerenciador de segredos do backend. O agente escreve código que o lê pelo nome; ele nunca precisa do valor.
• Dados reais de usuários. Logs de produção, corpos de requisição com referências reais, tokens de contexto do evento e exportações do console ficam fora dos prompts e do contexto do agente.
• Acesso ao console. Sua senha, seus códigos do autenticador e sua sessão do console são pessoais.

Um agente que pede o segredo

Se um agente pedir o valor do segredo para testar uma chamada, a resposta é não. Ele confere o próprio código de assinatura com o vetor de teste e a autoverificação públicos, que usam um segredo sintético que não autentica nada. A primeira chamada real parte do seu backend, com o segredo que ele lê do seu gerenciador de segredos.

Como conferir o trabalho do agente

• A autoverificação da assinatura imprime o MAC esperado no Node.js que roda o seu backend.
• As orientações de integração tratam do fail-open, do orçamento de tempo e de testar em produção sem sandbox.
• O checklist de integração é a lista de revisão antes do tráfego real.