### Sei controlli sequenziali (si ferma al primo fallimento)

| # | Controllo | Blocca quando |
|---|-----------|---------------|
| 1 | Firma del ricevuta | Firma ECDSA P-256 non valida o ricevuta manomessa |
| 2 | Revoca | Il ricevuta è stata revocata tramite `RevocationRegistry` |
| 3 | Finestra temporale | Ricevuta scaduta o non ancora valida (oracolo timestamp del log, non orologio client) |
| 4 | Ambito | Azione non in `ScopeSchema.allowedActions` o fallisce corrispondenza ambito basata su testo |
| 5 | Istruzioni operatore | Le istruzioni attuali non corrispondono all'hash bloccato nella ricevuta al momento dell'emissione |
| 6 | Hash del programma | Il `programHash` fornito non corrisponde all'hash `executes` impegnato (prevenzione sostituzione codice) |

Ogni risultato del controllo — superato o fallito — viene automaticamente registrato in un `ActionLog` immutabile firmato con la propria chiave del verificatore.

### Integrazioni middleware

Wrapper plug-and-play per framework comuni. Ogni wrapper filtra ogni chiamata attraverso `PreExecutionVerifier` prima che il codice avvolto venga eseguito.

- **[LangChain](https://github.com/commonguy25/authproof-sdk/blob/HEAD/src/middleware/langchain.js)** — avvolge qualsiasi agente con un metodo `invoke()`
- **[Express/HTTP](https://github.com/commonguy25/authproof-sdk/blob/HEAD/src/middleware/express.js)** — middleware per richieste per qualsiasi framework compatibile con Express
- **[Generic function wrapper](https://github.com/commonguy25/authproof-sdk/blob/HEAD/src/middleware/generic.js)** — avvolge qualsiasi funzione asincrona```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 })

L'utente istruisce l'operatore. L'operatore istruisce l'agente. Ma nessuna registrazione crittografica dell'intento originale dell'utente esiste al momento della delega. L'operatore diventa un terzo fidato con autorità incontrollata di espandere, distorcere o omettere le istruzioni dell'utente prima che raggiungano l'agente.

Le conseguenze:

- Gli utenti non possono dimostrare cosa hanno autorizzato.
- I regolatori non hanno una pista di audit.
- I tribunali non hanno una catena di prove.
- Gli agenti non possono distinguere le istruzioni legittime dell'operatore da quelle compromesse o maligne.

AuthProof colma questa lacuna.

---

## Il Primitivo Fondamentale: Ricevuta di Delega

Una **Ricevuta di Delega** è un Oggetto di Autorizzazione firmato ancorato a un registro decentralizzato append-only prima che inizi qualsiasi azione dell'agente. Contiene quattro campi obbligatori:

### Ambito

Un elenco esplicito di operazioni consentite. Tutto ciò che non è elencato è negato per impostazione predefinita. Espresso in formato strutturato — non in linguaggio naturale. Classi di operazioni:

| Class | Description |
|---|---|
| `reads` | Accesso in lettura a risorse specificate |
| `writes` | Accesso in scrittura a risorse specificate |
| `deletes` | Cancellazione di risorse specificate |
| `executes` | Esecuzione di un programma specifico, referenziato dal suo **static capability signature hash** |

`executes` è la classe più pericolosa. Deve referenziare l'hash crittografico del DAG di capacità statica di un programma Safescript — non un nome, URI o descrizione. Nessuna corrispondenza hash significa nessuna esecuzione.

### Limiti

Proibizioni esplicite che non possono essere sovrascritte dalle istruzioni dell'operatore in nessuna circostanza. Limiti rigidi definiti dall'utente che sopravvivono a qualsiasi istruzione successiva dell'operatore.

### Finestra Temporale

Periodo di validità dell'autorizzazione. Il **timestamp del log** è l'oracolo del tempo — non l'orologio del client. Gli orologi dei client sono esplicitamente esclusi dalla validazione temporale.

### Hash delle Istruzioni dell'Operatore

Un hash crittografico delle istruzioni dichiarate dall'operatore al momento della delega. Se l'operatore successivamente istruisce l'agente in modo diverso, la discrepanza è rilevabile dal log senza ulteriori presupposti di fiducia.

L'utente firma questo oggetto con la propria chiave privata tramite **WebAuthn/FIDO2 utilizzando l'enclave sicuro del dispositivo**. La firma viene pubblicata sul log prima di qualsiasi azione dell'agente. Ogni azione successiva dell'agente referenzia l'hash della ricevuta. Le azioni al di fuori dell'ambito sono crittograficamente non valide.

---

## Architettura dello Stack di Fiducia

Tre livelli di protocollo eliminano tre terze parti fidate:

### Livello 1 — Manifesto di Capacità Firmato *(rimuove la fiducia nel registro)*

Nell'attuale ecosistema MCP, non esiste un'attestazione crittografica che le descrizioni di un server di strumenti corrispondano a ciò che effettivamente fa. Un operatore può presentare uno schema arbitrario.

La soluzione: i server di strumenti pubblicano un **manifesto di capacità firmato crittograficamente** prima che avvenga qualsiasi autorizzazione utente. Il campo `scope` della Ricevuta di Delega referenzia l'**hash di questo manifesto** — non lo schema auto-dichiarato dall'operatore. La divergenza tra il comportamento del server e il manifesto è rilevabile a livello di log.

### Livello 2 — Ricevuta di Delega *(rimuove la fiducia nell'operatore)*

L'intento originale dell'utente viene registrato in modo immutabile prima che le istruzioni dell'operatore raggiungano l'agente. La deviazione dell'operatore è dimostrabile.

### Livello 3 — Esecuzione Safescript *(rimuove la fiducia nel codice)*

[Safescript](https://github.com/safescript) è un linguaggio open-source in sandbox per l'esecuzione di agenti AI. La sua struttura DAG statica significa che l'intera firma di capacità di ogni programma è calcolabile prima che venga eseguito — nessun dispatch dinamico, nessuna espansione di capacità a runtime.

La classe di ambito `executes` referenzia uno specifico hash della firma di capacità Safescript. Se il programma fornito dall'operatore non corrisponde all'hash impegnato, l'esecuzione viene bloccata. L'agente non può essere sostituito con un programma diverso dopo la delega.

---

## Avvio Rapido```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,
  });
}

### API del Registro Azioni

| Metodo | Descrizione |
|---|---|
| `new ActionLog()` | Crea una nuova istanza del registro. Lo stato è in memoria. |
| `log.init({ privateKey, publicJwk })` | Inizializza con la chiave ECDSA P-256 dell'agente. Richiesto prima di `record()`. |
| `log.registerReceipt(receiptHash, receipt)` | Registra una ricevuta per il confronto dell'ambito. Richiesto prima di `diff()`. |
| `log.record(receiptHash, action)` | Aggiunge una voce firmata concatenata. Restituisce la voce sigillata. |
| `log.verify(entryId)` | Verifica la firma e la posizione nella catena di una voce. Restituisce `{ valid, reason }`. |
| `log.getEntries(receiptHash)` | Tutte le voci per una ricevuta in ordine cronologico. |
| `log.diff(receiptHash)` | Confronta tutte le voci con l'ambito della ricevuta. Restituisce `{ compliant, violations, clean }`. |

### Avviso di Produzione

I timestamp nella v1 utilizzano l'orologio del client. Per contesti normativi o legali in cui i timestamp devono essere verificabili in modo indipendente, sostituisci con un'autorità di timestamp fidato RFC 3161 prima di distribuire in produzione.

### Importante

Definisci sempre l'ambito utilizzando array `allowedActions` espliciti. La corrispondenza dell'ambito basata su testo è disponibile solo per lo sviluppo e non è adatta a contesti di produzione o conformità.

---

## Distribuzione Confidenziale

Esegui gli agenti AuthProof all'interno di Ambienti di Esecuzione Fidati (TEE) attestati dall'hardware. La classe `ConfidentialRuntime` associa le ricevute di delega alle misurazioni dell'enclave, quindi qualsiasi sostituzione dei pesi del modello, del codice di verifica o della piattaforma è rilevabile prima dell'esecuzione.

### Requisiti hardware

- **Intel TDX** — Intel Ice Lake Xeon o successivi (Xeon Scalable di 4a generazione). Azure DCdsv3-series, GCP C3 Confidential VMs.
- **AMD SEV-SNP** — AMD EPYC 3a generazione (Milan) o successivi. Azure DCasv5-series, AWS m6a con Nitro Enclaves.

### Crea una ricevuta con associazione della misurazione 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

Requisiti SKU di Azure: `Standard_DC4ds_v3` o superiore della serie DCdsv3. Abilita la crittografia del disco del sistema operativo riservato. Utilizza l'endpoint condiviso di Microsoft Azure Attestation (MAA) per la verifica delle attestazioni.

### Distribuzione su 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

Applicare con `kubectl apply -f` dopo aver serializzato in YAML. Il selettore di nodo `intel.feature.node.kubernetes.io/tdx: "true"` richiede l'Intel Device Plugin for Kubernetes.

### Modulo kernel eBPF — aiuto richiesto

Il livello di enforcement TEE è completo dal lato userspace (`ConfidentialRuntime`, `TokenPreparer`). Il passo finale di enforcement — convalidare il token di capability firmato su ogni syscall tramite un hook eBPF LSM — richiede un modulo kernel aperto ai contributi.

Ingegneri con esperienza in eBPF LSM (Isovalent, Red Canary, o simili) sono particolarmente benvenuti. Apri un issue o PR su https://github.com/Commonguy25/authproof-sdk/issues

---

## Esempi

Due esempi eseguibili si trovano nella directory `examples/`.

**[`examples/langchain-example.js`](https://github.com/commonguy25/authproof-sdk/blob/HEAD/examples/langchain-example.js)** — Mostra il percorso completo di integrazione con LangChain: genera una coppia di chiavi, emette un receipt di delega, inizializza `PreExecutionVerifier` e avvolge qualsiasi agente con `authproofMiddleware` in modo che ogni chiamata a `invoke()` sia bloccata prima che il runtime dell'agente ottenga il controllo. Include un agente fittizio che puoi eseguire immediatamente e il pattern di codice esatto per un vero `AgentExecutor`. Esegui con `npm run example:langchain`.

**[`examples/webauthn-example.html`](https://github.com/commonguy25/authproof-sdk/blob/HEAD/examples/webauthn-example.html)** — Una demo browser autonoma a tre carte dell'intero flusso di delega. La Carta 1 ti permette di definire ambito, confini e istruzioni dell'operatore, quindi firma una ricevuta con una chiave locale (sostituisci con `navigator.credentials` per un vero WebAuthn). La Carta 2 mostra l'ID della ricevuta, la scadenza, il prompt di sistema e il JSON grezzo. La Carta 3 ti permette di digitare qualsiasi azione proposta e verificarla in tempo reale rispetto alla ricevuta, mostrando ciascun risultato del controllo. Apri direttamente in un browser — nessun passo di build richiesto.

---

## Installazione```bash
npm install authproof-sdk