### Seis verificações sequenciais (para na primeira falha)

| # | Verificação | Bloqueia quando |
|---|-------------|-----------------|
| 1 | Assinatura do recibo | Assinatura ECDSA P-256 inválida ou recibo adulterado |
| 2 | Revogação | Recibo foi revogado via `RevocationRegistry` |
| 3 | Janela de tempo | Recibo expirado ou ainda não válido (oráculo de timestamp de log, não relógio do cliente) |
| 4 | Escopo | Ação não está em `ScopeSchema.allowedActions` ou falha na correspondência de escopo baseada em texto |
| 5 | Instruções do operador | As instruções atuais não correspondem ao hash bloqueado no recibo na emissão |
| 6 | Hash do programa | O `programHash` fornecido não corresponde ao hash `executes` comprometido (prevenção de substituição de código) |

Cada resultado de verificação — aprovado ou reprovado — é registrado automaticamente em um `ActionLog` imutável assinado com a própria chave do verificador.

### Integrações de middleware

Wrappers plug-and-play para frameworks comuns. Cada wrapper protege cada chamada através de `PreExecutionVerifier` antes que o código encapsulado seja executado.

- **[LangChain](https://github.com/commonguy25/authproof-sdk/blob/HEAD/src/middleware/langchain.js)** — encapsula qualquer agente com um método `invoke()`
- **[Express/HTTP](https://github.com/commonguy25/authproof-sdk/blob/HEAD/src/middleware/express.js)** — middleware de requisição para qualquer framework compatível com Express
- **[Generic function wrapper](https://github.com/commonguy25/authproof-sdk/blob/HEAD/src/middleware/generic.js)** — encapsula qualquer função assíncrona```js
// LangChain
import { authproofMiddleware } from 'authproof-sdk/middleware/langchain'
const guardedAgent = authproofMiddleware(agent, { receiptHash, verifier })

// Express
import { authproofMiddleware } from 'authproof-sdk/middleware/express'
app.use(authproofMiddleware({ verifier, getReceiptHash: (req) => req.headers['x-receipt-hash'] }))

// Any function
import { guardFunction } from 'authproof-sdk/middleware/generic'
const guardedExecute = guardFunction(executeAction, { receiptHash, verifier, action })

O usuário instrui o operador. O operador instrui o agente. Mas não existe nenhum registro criptográfico da intenção original do usuário no momento da delegação. O operador se torna um terceiro confiável com autoridade irrestrita para expandir, distorcer ou omitir as instruções do usuário antes que elas cheguem ao agente.

As consequências:

- Os usuários não podem provar o que autorizaram.
- Os reguladores não têm trilha de auditoria.
- Os tribunais não têm cadeia de evidências.
- Os agentes não conseguem distinguir instruções legítimas do operador daquelas comprometidas ou maliciosas.

AuthProof preenche essa lacuna.

---

## O Primitivo Principal: Delegation Receipt

Um **Delegation Receipt** é um Objeto de Autorização assinado ancorado em um log descentralizado somente de adição antes do início de qualquer ação do agente. Ele contém quatro campos obrigatórios:

### Escopo

Uma lista de permissões explícita das operações permitidas. Tudo que não está listado é negado por padrão. Expresso em formato estruturado — não em linguagem natural. Classes de operação:

| Classe | Descrição |
|---|---|
| `reads` | Acesso de leitura a recursos especificados |
| `writes` | Acesso de escrita a recursos especificados |
| `deletes` | Exclusão de recursos especificados |
| `executes` | Execução de um programa específico, referenciado pelo seu **hash de assinatura de capacidade estática** |

`executes` é a classe mais perigosa. Ela deve referenciar o hash criptográfico do DAG de capacidade estática de um programa Safescript — não um nome, URI ou descrição. Nenhuma correspondência de hash significa nenhuma execução.

### Limites

Proibições explícitas que não podem ser substituídas por instruções do operador em nenhuma circunstância. Limites rígidos definidos pelo usuário que sobrevivem a qualquer instrução subsequente do operador.

### Janela de Tempo

Período de validade da autorização. O **timestamp do log** é o oráculo de tempo — não o relógio do cliente. Relógios do cliente são explicitamente excluídos da validação de tempo.

### Hash da Instrução do Operador

Um hash criptográfico das instruções declaradas pelo operador no momento da delegação. Se o operador subsequentemente instruir o agente de forma diferente, a discrepância é detectável a partir do log sem suposições adicionais de confiança.

O usuário assina este objeto com sua chave privada via **WebAuthn/FIDO2 usando o enclave seguro do dispositivo**. A assinatura é publicada no log antes de qualquer ação do agente. Cada ação subsequente do agente referencia o hash do recibo. Ações fora do escopo são criptograficamente inválidas.

---

## Arquitetura da Pilha de Confiança

Três camadas de protocolo eliminam três terceiros confiáveis:

### Camada 1 — Manifesto de Capacidade Assinado *(remove a confiança no registro)*

No ecossistema MCP atual, não há atestação criptográfica de que as descrições do servidor de ferramentas correspondem ao que ele realmente faz. Um operador pode apresentar um esquema arbitrário.

A correção: servidores de ferramentas publicam um **manifesto de capacidade assinado criptograficamente** antes de qualquer autorização do usuário ocorrer. O campo `scope` do Delegation Receipt referencia o **hash deste manifesto** — não o esquema auto-relatado pelo operador. A divergência entre o comportamento do servidor e o manifesto é detectável na camada do log.

### Camada 2 — Delegation Receipt *(remove a confiança no operador)*

A intenção original do usuário é registrada imutavelmente antes que as instruções do operador cheguem ao agente. O desvio do operador é comprovável.

### Camada 3 — Execução Safescript *(remove a confiança no código)*

[Safescript](https://github.com/safescript) é uma linguagem de código aberto em sandbox para execução de agentes de IA. Sua estrutura DAG estática significa que a assinatura completa de capacidade de cada programa é computável antes de ser executado — sem despacho dinâmico, sem expansão de capacidade em tempo de execução.

A classe de escopo `executes` referencia um hash de assinatura de capacidade Safescript específico. Se o programa fornecido pelo operador não corresponder ao hash comprometido, a execução é bloqueada. O agente não pode ser substituído por um programa diferente após a delegação.

---

## Início Rápido```js
import { AuthProof, Scope, KeyCustody } from 'authproof-sdk';

// Initialize with hardware-backed key custody (recommended)
const authproof = new AuthProof({
  custody: KeyCustody.HARDWARE, // WebAuthn/FIDO2 via device secure enclave
  log: 'https://log.authproof.dev',
});

// Define permitted operations — explicit allowlist, deny-by-default
const scope = new Scope()
  .allow('reads',  ['resource://calendar/events', 'resource://email/inbox'])
  .allow('writes', ['resource://calendar/events'])
  .deny('deletes', '*')
  .execute('sha256:a3f1c9d8...', { program: 'scheduler-v1.sg' }); // Safescript hash

// Hard limits that survive any operator instruction
const boundaries = {
  never: ['external-network', 'credential-store', 'payment-methods'],
};

// Issue the Delegation Receipt — anchored to log before any agent action
const receipt = await authproof.delegate({
  scope,
  boundaries,
  window: { duration: '8h' },           // validated against log timestamp
  operatorInstructions: instructionText, // hashed and committed
});

// receipt.id    — unique receipt identifier
// receipt.hash  — reference in every agent action
// receipt.log   — append-only log anchor

// Agent-side: validate an action against the receipt
const check = await authproof.validate({
  receiptHash: receipt.hash,
  action: { class: 'writes', resource: 'resource://calendar/events' },
});

if (!check.authorized) {
  // Out-of-scope action: surface a micro-receipt request to the user
  const microReceipt = await authproof.requestMicroReceipt({
    action: check.requestedAction,
    parent: receipt.hash,
  });
}

### Action Log API

| Método | Descrição |
|---|---|
| `new ActionLog()` | Cria uma nova instância de log. O estado fica na memória. |
| `log.init({ privateKey, publicJwk })` | Inicializa com a chave ECDSA P-256 do agente. Necessário antes de `record()`. |
| `log.registerReceipt(receiptHash, receipt)` | Registra um recibo para comparação de escopo. Necessário antes de `diff()`. |
| `log.record(receiptHash, action)` | Adiciona uma entrada assinada e encadeada. Retorna a entrada selada. |
| `log.verify(entryId)` | Verifica a assinatura de uma entrada e sua posição na cadeia. Retorna `{ valid, reason }`. |
| `log.getEntries(receiptHash)` | Todas as entradas de um recibo em ordem cronológica. |
| `log.diff(receiptHash)` | Compara todas as entradas com o escopo do recibo. Retorna `{ compliant, violations, clean }`. |

### Aviso de Produção

Os timestamps na v1 usam o relógio do cliente. Para contextos de conformidade ou legais onde os timestamps precisam ser verificáveis de forma independente, substitua por uma autoridade de timestamp confiável RFC 3161 antes de implantar em produção.

### Importante

Sempre defina o escopo usando arrays explícitos de `allowedActions`. A correspondência de escopo baseada em texto está disponível apenas para desenvolvimento e não é adequada para produção ou contextos de conformidade.

---

## Implantação Confidencial

Execute os agentes AuthProof dentro de Ambientes de Execução Confiáveis (TEEs) atestados por hardware. A classe `ConfidentialRuntime` vincula os recibos de delegação às medições do enclave, de modo que qualquer substituição de pesos do modelo, código do verificador ou plataforma seja detectável antes da execução.

### Requisitos de hardware

- **Intel TDX** — Intel Ice Lake Xeon ou mais recente (4ª geração Xeon Scalable). Azure DCdsv3-series, GCP C3 Confidential VMs.
- **AMD SEV-SNP** — AMD EPYC 3ª geração (Milan) ou mais recente. Azure DCasv5-series, AWS m6a com Nitro Enclaves.

### Criar um recibo com vinculação de medição TEE```javascript
import { AuthProofClient } from 'authproof-sdk';

const client = new AuthProofClient();
const { receipt } = await client.delegate({
  scope: 'Summarize calendar events',
  operatorInstructions: 'Stay within scope.',
  expiresIn: '2h',
  privateKey,
  publicJwk,
  teeConfig: {
    platform:     'intel-tdx',
    verifierHash: verifierCodeHash,   // SHA-256 of your verifier binary
    modelHash:    modelWeightsHash,   // SHA-256 of model weights
  },
});
// receipt.teeMeasurement.expectedMrenclave is now bound to the receipt

Azure SKU requirements: `Standard_DC4ds_v3` or larger from the DCdsv3-series. Enable Confidential OS disk encryption. Use Microsoft Azure Attestation (MAA) shared endpoint for quote verification.

### Implante no AWS Nitro Enclaves```javascript
const config = ConfidentialRuntime.awsNitroConfig({
  receiptHash,
  verifierHash,
  modelHash,
  region: 'us-east-1',
});
// config.instanceType === 'c6a.xlarge'
// config.enclaveOptions.enabled === true
// config.pcr0 is the combined receipt+verifier+model measurement

Aplique com `kubectl apply -f` após serializar para YAML. O seletor de nós `intel.feature.node.kubernetes.io/tdx: "true"` requer o Intel Device Plugin for Kubernetes.

### Módulo do kernel eBPF — ajuda necessária

A camada de imposição do TEE está completa pelo lado do espaço do usuário (`ConfidentialRuntime`, `TokenPreparer`). O passo final de imposição — validar o token de capacidade assinado em cada chamada de sistema através de um hook eBPF LSM — requer um módulo do kernel que está aberto para contribuição.

Engenheiros com experiência em eBPF LSM (Isovalent, Red Canary ou similar) são especialmente bem-vindos. Abra uma issue ou PR em https://github.com/Commonguy25/authproof-sdk/issues

---

## Exemplos

Dois exemplos executáveis estão no diretório `examples/`.

**[`examples/langchain-example.js`](https://github.com/commonguy25/authproof-sdk/blob/HEAD/examples/langchain-example.js)** — Mostra o caminho completo de integração com LangChain: gerar um par de chaves, emitir um recibo de delegação, inicializar `PreExecutionVerifier` e envolver qualquer agente com `authproofMiddleware` para que cada chamada `invoke()` seja bloqueada antes que o runtime do agente obtenha controle. Inclui um agente simulado que você pode executar imediatamente e o padrão de código exato para um `AgentExecutor` real. Execute com `npm run example:langchain`.

**[`examples/webauthn-example.html`](https://github.com/commonguy25/authproof-sdk/blob/HEAD/examples/webauthn-example.html)** — Uma demonstração auto-suficiente de três cartões no navegador de todo o fluxo de delegação. O Cartão 1 permite definir escopo, limites e instruções do operador, depois assina um recibo com uma chave local (substitua por `navigator.credentials` para WebAuthn real). O Cartão 2 exibe o ID do recibo, expiração, prompt do sistema e JSON bruto. O Cartão 3 permite digitar qualquer ação proposta e verificar contra o recibo em tempo real, mostrando cada resultado da verificação. Abra diretamente em um navegador — nenhuma etapa de build necessária.

---

## Instalação```bash
npm install authproof-sdk