C->>A: Authenticated OpenAI-compatible or Anthropic request
A->>W: Size, canonicalization, WAF, session, rate-limit
W-->>C: Fail-closed response + durable error evidence when rejected
W->>U: Forward only after admission
U-->>A: Complete response or bounded SSE events
A->>L: Non-stream: hash, sign, append, flush, fsync
L-->>A: Non-stream durable evidence status
A->>Q: Optional bounded response analysis
A-->>C: Non-stream response + portable MMR proof headers
A-->>C: Stream events through bounded queue
A->>L: Stream terminal summary, sign, append, flush, fsync
L-->>A: Terminal commit complete
A-->>C: Protocol terminal marker

Il ciclo di vita rigoroso è:

1. Autenticare il chiamante e assegnare un identificatore di richiesta.
2. Applicare i limiti di dimensione della richiesta e canonicalizzare la rappresentazione della richiesta.
3. Applicare i controlli WAF, comportamento di sessione, egress e limitazione della frequenza.
4. Rifiutare in caso di mancato controllo obbligatorio invece di indebolire silenziosamente il percorso di sicurezza.
5. Inoltrare al provider upstream configurato.
6. Per le chiamate non in streaming, acquisire la risposta, calcolare hash canonici, firmare le prove, aggiungere al WAL, eseguire il flush e `fsync` prima di restituirla.
7. Per le chiamate SSE, inoltrare eventi logici sanitizzati attraverso una coda limitata con contabilità dei byte. Hash incrementale dei byte esatti emessi; alla terminazione, impegnare un riepilogo terminale firmato prima di emettere il marcatore terminale del protocollo. L'header iniziale di streaming è quindi `X-Aegis-Evidence-Status: pending-terminal`, non `durable`.
8. Eseguire l'arricchimento opzionale della risposta attraverso un percorso worker limitato dopo che il record autorevole esiste.

## Contratto principale

| Controllo | Comportamento implementato | Prove e confine |
|---|---|---|
| Durabilità delle prove | Per le chiamate governate non in streaming, il proxy principale impegna le prove di richiesta/risposta prima di restituire ed emette `X-Aegis-Evidence-Status: durable`. Lo streaming SSE inizia con `pending-terminal`; un riepilogo terminale firmato viene impegnato prima del marcatore terminale del protocollo e la prova viene recuperata dopo la terminazione. | `tests/test_p0_release_gates.py`, `tests/test_proxy_streaming.py`, test del percorso di errore del proxy e test di integrità WAL. Il filesystem di destinazione e il provider di storage richiedono ancora la validazione di deployment. |
| Errori terminali durevoli | Le risposte upstream non-2xx, i percorsi di circuito aperto e i guasti di rete utilizzano il percorso di prove di errore durevoli quando il confine delle prove è disponibile. | `tests/test_enterprise_durable_evidence.py` e prove della release v3.1.0. Un errore di storage dopo l'ammissione è un incidente operativo fail-closed, non una risposta riuscita. |
| Integrità della catena | I nodi di audit collegano predecessore, hash della richiesta, hash della risposta, radice Merkle, firma e metadati dello schema. | `aegis/core/crypto_audit.py` e `verify_integrity()`. Il rilevamento di manomissioni non equivale a storage esterno immutabile. |
| Firma forte | I ledger rigorosi rifiutano il fallback Ed25519 effimero. HMAC-SHA256, PKCS#11 configurato o firma nativa configurata devono soddisfare la policy selezionata; la vecchia interfaccia HSM ora fallisce in modalità chiusa invece di derivare una chiave software. | Test del firmatario e gate di avvio rigorosi. I test PKCS#11 simulati sono solo prove dell'adattatore, HMAC è simmetrico e non è stabilita alcuna interoperabilità HSM, non-esportabilità delle chiavi, validazione FIPS o non-ripudio di terze parti. |
| Rotazione delle chiavi | Il firmatario enterprise supporta un portachiavi HMAC atomico e versionato con una chiave attiva, chiavi di verifica storiche, scadenza esplicita e metadati `key_id` non segreti. | `aegis_server/crypto/keyring.py`, `tests/test_keyring_rotation.py`. Le prove di deployment a tre repliche rimangono necessarie per un'affermazione di produzione. |
| Limitazione della frequenza | La limitazione distribuita basata su Redis fallisce in modalità chiusa quando il backend non è disponibile; la limitazione in memoria di sviluppo non è un sostituto di produzione. | Test del limitatore di frequenza e configurazione di deployment. Il comportamento Redis/TLS/HA dipende dal deployment. |
| Identità enterprise e binding del tenant | Il candidato non rilasciato deriva principal immutabili da mapping di chiavi API configurati, claim OIDC rigorosi o certificati mTLS esplicitamente fissati. Gli header tenant/sessione non selezionano il tenant delle prove o la chiave di quota. | `aegis/auth/`, `aegis/proxy/dependencies.py` e test di integrazione dell'autenticazione. IdP, terminatore TLS, ciclo di vita dei certificati e accettazione Redis rimangono dipendenti dal deployment; la sorgente mTLS attuale è in modalità leaf-pin, non validazione PKI universale. |
| Archiviazione dei segmenti finalizzati | I segmenti WAL JSONL ruotati ricevono manifest versionati e possono essere caricati tramite l'adattatore opzionale S3 Object Lock con verifica SHA-256, versione, modalità di blocco e conservazione. L'accettazione opzionale RFC 3161 richiede verifica OpenSSL contro un file CA esplicito. | `aegis/storage/`, `aegis/anchoring/` e test mirati. Questo non è un WORM normativo, una garanzia di ammissibilità legale o di tempo esterno senza accettazione di destinazione. |
| Telemetria privacy-safe | Gli eventi di sicurezza a schema chiuso omettono testo di prompt/risposta/token, embedding, identificatori grezzi di tenant/sessione, nomi dei firmatari e stringhe di eccezione; uno spool SQLite opzionale limitato esporta verso codifiche SIEM supportate. | `aegis/telemetry/` e test sentinella della privacy. Consegna a valle, conservazione, controllo accessi e SLO operativi sono esterni. |
| Report delle capacità | `aegis.crypto` espone un inventario leggibile da macchina che distingue stati implementati, runtime opzionale, stub e validazione esterna richiesta. | `aegis/crypto/capabilities.py` e test mirati. L'attuale API ZK è uno stub di test non reale, le prove MMR portabili crescono O(log n) e non è rivendicata alcuna validazione FIPS. |
| Confine di attestazione TEE | I nodi dispositivo TEE sono segnalati solo come scoperta. I report legacy scritti dal chiamante sono rifiutati; un verificatore iniettato può fornire claim normalizzati autenticati per la valutazione della policy di misurazione esatta, firmatario, nonce, freschezza, debug, TCB e dati di report. | `aegis/core/tee_manager.py` e test dei moduli hardware. Il repository non implementa un loader enclave, parsing delle quote del fornitore, validazione di certificati/collaterali, riservatezza dell'host root o accettazione di attestazione di destinazione. |
| Confine di privacy differenziale | Un primitivo interno di conteggio Laplace usa sensibilità uno e un CSPRNG di sistema per una singola release sotto adiacenza add/remove-one-record. | `aegis/core/dp_analytics.py` e test deterministici. Nessun endpoint HTTP DP è pubblicato; release ripetute richiedono un contabile durevole, identità stabile di dataset/query, memoizzazione e limiti di contribuzione revisionati che non sono implementati qui. |
| Confine delle capacità di fuzzing | Il fuzzing è disponibile solo quando esistono `cargo`, `cargo-fuzz`, un workspace privato, un manifest analizzabile limitato e tutti i file target regolari confinati esatti; lo stato di esecuzione distingue pulito, artefatto di crash, errore dello strumento, timeout e non disponibile. | `aegis/core/fuzzing_harness.py` e test mirati. L'albero attuale non ha un workspace cargo-fuzz o un harness Kani, la copertura misurata rimane non disponibile e i test limitati non sono una prova esaustiva. |
| Contesto AI consultivo | `AGENTS.md`, `llms.txt` e `.aegis_ai_context/` forniscono navigazione del repository e confini delle affermazioni per gli assistenti di codifica. | Questi file sono dati consultivi: non possono sovrascrivere l'autorizzazione, stabilire il comportamento runtime o trasformare il sorgente unito in una release. |
| Limiti della richiesta | I body sovradimensionati sono rifiutati prima dell'elaborazione normale dell'applicazione. | Test di release P0/P1. I limiti devono essere dimensionati per il provider distribuito e la policy di streaming. |
| WAF | Normalizzazione NFKC, rimozione degli zero-width, blocchi di pattern critici, guardia di profondità strutturale e analisi locale ponderata vengono eseguiti al confine dell'applicazione. | `tests/data/waf_corpus_v1.json` e `tools/security/run_waf_corpus.py`. Il parsing HTTP/2 in ingresso è al di fuori del confine dell'applicazione. |
| Egress | Le allowlist canoniche rifiutano schemi, userinfo, porte malformate, forme non supportate ed endpoint non approvati. | `aegis/proxy/egress_guard.py` e test. Questo non sostituisce firewall, namespace, NetworkPolicy o controlli egress cloud. |
| Controlli del kernel | L'avvio rigoroso può richiedere capacità Seccomp e LSM/AppArmor/SELinux e rifiuta l'enforcement mancante al di fuori della modalità sandbox esplicita. | `aegis/core/seccomp_guard.py`, `aegis/core/lsm_guard.py`, test di deployment. Il kernel di destinazione richiede ancora test di accettazione. |
| Arricchimento della risposta | L'analisi è limitata, osservabile e serializzata per sessione dove richiesto. È opzionale e non può indebolire il contratto di prove durevoli. | Test di analizzatori e code. Il comportamento della coda sotto saturazione I/O reale è descritto nel runbook di backpressure. |
| Prova di inclusione portabile | Ogni nuovo record del ledger memorizza una prova `aegis-mmr-inclusion-v1` autocontenuta, digest foglia, picchi ordinati e radice. Le risposte non in streaming restituiscono queste come header `X-Aegis-MMR-*`; le chiamate in streaming espongono un link di prova post-terminale autenticato. | Vettori golden cross-language e test di replay/manomissione WAL. Una prova valida stabilisce l'inclusione nella radice MMR dichiarata; non stabilisce da sola timestamping esterno, conservazione o ammissibilità legale. |

## Avvio rapido per valutazione locale

Il percorso locale è per sviluppo, test e replay delle prove. Non è un profilo di deployment di produzione.```bash
git clone https://github.com/JuanLunaIA/aegis-latent-core.git
cd aegis-latent-core
python3 -m venv .venv
. .venv/bin/activate
python -m pip install --require-hashes -r requirements.lock
python -m pip install --no-deps -e .
python -m compileall -q aegis aegis_server
pytest -q

`development` è l'unica modalità non-strict accettata nel modello di impostazioni corrente; il valore precedente `permissive` e il comando `uvicorn aegis.main:app` sono obsoleti. Non inserire mai chiavi di provider, bearer token, segreti di firma, record WAL o payload dei clienti nel controllo del codice sorgente.

## SDK con sorgente unificata

La distribuzione Python con sorgente unificata in [`sdk/python`](https://github.com/juanlunaia/aegis-latent-core/blob/HEAD/sdk/python) è un'integrazione drop-in che sottoclassa i client ufficiali OpenAI e Anthropic. I tipi di modelli di richiesta/risposta esistenti e le API di risorse sync/async vengono preservati mentre le intestazioni Aegis di tenant, sessione e bearer-auth vengono iniettate in fase di costruzione. L'ingresso nativo `/v1/messages` di Anthropic richiede `AEGIS_PROVIDER=anthropic`; preserva la forma della risposta Anthropic Messages invece di tradurla in oggetti OpenAI.

Il pacchetto TypeScript con sorgente unificata compatibile con edge in [`sdk/typescript`](https://github.com/juanlunaia/aegis-latent-core/blob/HEAD/sdk/typescript) verifica le prove `aegis-mmr-inclusion-v1` con Web Crypto e fornisce wrapper nativi del provider e opzioni del costruttore anziché ridichiarare i payload del provider. I pacchetti ufficiali OpenAI e Anthropic sono dipendenze peer, quindi le loro risorse native, i parametri di richiesta, i modelli di risposta, gli iteratori di streaming, i retry e i tipi di errore rimangono autorevoli. Entrambi gli SDK consumano gli stessi vettori di prova congelati in `sdk/shared/`.

Il candidato SDK Python non ancora rilasciato include anche adattatori di callback LangChain e LlamaIndex con privacy minimizzata. I flussi di pubblicazione sono disabilitati a meno che non siano configurati i prerequisiti esterni di trusted-publisher, ambiente, tag firmati e variabili di repository. Vedi [`docs/DEVELOPER_INTEGRATIONS_GUIDE.md`](https://github.com/juanlunaia/aegis-latent-core/blob/HEAD/docs/DEVELOPER_INTEGRATIONS_GUIDE.md).```python
from aegis_sdk.openai import OpenAI

client = OpenAI(
    aegis_api_key="gateway-token",
    gateway_url="https://aegis.internal",
    tenant_id="tenant-42",
)
response = client.chat.completions.create(
    model="gpt-4.1-mini",
    messages=[{"role": "user", "content": "hello"}],
)

`AEGIS_DASHBOARD_API_KEY` è solo lato server e non viene mai serializzato nei bundle del browser. L'endpoint di esportazione richiede lo scope `audit:export` quando sono configurati scope per-chiave. Ogni ZIP delimitato contiene un `manifest.json` RFC 8785 JCS, un `ledger_slice.cbor` canonico DAG-CBOR identificato da CIDv1, `merkle_proof.json`, `audit_certificate.pdf` e `VERIFY.sh`. Il certificato è un report tecnico di integrità, non una certificazione o una conclusione di ammissibilità legale.

## Percorso di distribuzione rigoroso

La modalità rigorosa è la postura di produzione prevista. Richiede autenticazione, prove durevoli, firma forte, corpi di richiesta limitati, un backend di rate-limit distribuito, storage durevole e i controlli del kernel configurati. Utilizza un secret manager e monta il WAL su un percorso durevole e leggibile dal proprietario.```bash
export AEGIS_SECURITY_ENFORCEMENT_MODE=strict
export AEGIS_API_KEYS='replace-with-a-secret-manager-reference'
export AEGIS_SIGNING_KEY='at-least-32-bytes-of-secret-material'
export AEGIS_RATE_LIMIT_BACKEND=redis
export AEGIS_REDIS_URL='rediss://redis.internal:6380/0'
export AEGIS_REQUIRE_DISTRIBUTED_LIMITER=true
export AEGIS_REQUIRE_DURABLE_EVIDENCE=true
export AEGIS_REQUIRE_LSM=true
export AEGIS_REQUIRE_SECCOMP=true
export AEGIS_MAX_REQUEST_BODY_BYTES=1048576
export AEGIS_BACKEND_URL='https://llm.internal.example/v1'
export AEGIS_WAL_PATH='/var/lib/aegis/aegis.wal.jsonl'

Il protocollo keyring, la finestra di sovrapposizione, la scadenza, il rollback e i criteri di accettazione a tre repliche sono in [`docs/operations/KEY_ROTATION_RUNBOOK.md`](https://github.com/juanlunaia/aegis-latent-core/blob/HEAD/docs/operations/KEY_ROTATION_RUNBOOK.md). Un percorso keyring non è un gestore di segreti; la distribuzione deve comunque stabilire custodia, controllo degli accessi, consegna atomica, backup, distruzione e verificabilità.

## Modello di evidenza e firma

Il registro locale è un WAL JSONL append-only con una catena limitata in memoria e segmenti archiviati opzionali. Ogni record contiene hash di richiesta e risposta, collegamento di catena, una radice Merkle, metadati di firma e l'identificatore della richiesta. Il WAL viene scaricato e sincronizzato prima che il percorso di risposta durevole venga completato.

Le scelte di firma supportate dipendono dalla distribuzione:

| Firmatario | Confine appropriato | Limitazione importante |
|---|---|---|
| HMAC-SHA256 | Distribuzioni self-hosted a nodo singolo o con segreto condiviso | Chiave simmetrica; ogni verificatore che detiene la chiave può anche firmare. HMAC è classico, non resistente ai quantistici. |
| Firmatario basato su HSM/Vault | Distribuzioni aziendali che richiedono isolamento delle chiavi o custodia remota | Disponibilità, policy, TLS/mTLS, rotazione e verifica offline richiedono l'evidenza della distribuzione target stessa. |
| Firmatario nativo ML-DSA-65 | Ambienti che compilano e caricano il backend Rust reale | L'artefatto candidato conservato di 1M campioni non ha rilevato differenze temporali significative per `sign` (`p=0.8521504207157158`) ma non ha soddisfatto la soglia per `verify` (`p=0.0`); nessuna affermazione di tempo costante è approvata. Vedere [`docs/security/PQC_CONSTANT_TIME.md`](https://github.com/juanlunaia/aegis-latent-core/blob/HEAD/docs/security/PQC_CONSTANT_TIME.md). |

Aegis non fabbrica firme ML-DSA quando il backend nativo non è disponibile. Segnala il backend come non disponibile e richiede una policy di fallback reale esplicita. Un risultato temporale con `p > 0.05` significherebbe solo che non è stata rilevata una fuga statisticamente significativa nell'esperimento nominato; non proverebbe l'esecuzione a tempo costante.

## Semantica di backpressure e guasto

L'evidenza durevole è un invariante del percorso critico. In caso di stallo di storage o `fsync`, il percorso di richiesta può bloccarsi o rifiutare secondo i limiti configurati; non deve eliminare silenziosamente evidenza autorevole. La coda di arricchimento può rifiutare lavoro opzionale, ma una policy di coda non può trasformare una risposta accettata governata in una risposta non registrata.

L'harness deterministico di fault-injection è:```bash
PYTHONPATH=. .venv/bin/python tools/benchmarks/run_backpressure_stall.py \
  --duration-s 0.25 --offered-rps 10000 --fsync-delay-ms 2 --max-workers 64 \
  --output evidence/backpressure_stall_report.json