Enterprise Edge

Local Vault

Local Vault è un customer edge component outbound-only per connector secret storage, source attestation signing, offline spooling, event relay, optional customer-side witness operation e, in Local Vault 2.x, il provenance mode di Attesto 3, in cui le capsules restano sull'host edge e solo i commitments raggiungono la piattaforma. Non è HashiCorp Vault.

Responsibilities

Encrypt connector credentials localmente.
Firma source attestations prima del relay.
Spool events durante network outages.
Replay spooled events in ordine con idempotency.
Opera come customer-side witness quando tenant policy lo abilita.

La provenance locale delle immagini usa il provider isolato e il registro keyed cifrato descritti nella guida AttestoMark Image.

Installare ed eseguire

Installa Local Vault sull’host edge controllato dal cliente. Le coordinate runtime possono arrivare da flag o variabili d’ambiente, ma signing keys, spool encryption keys e connector credentials devono arrivare dal secret manager locale di deployment. Non inserirle in shell history, configurazione frontend o docs Attesto.

L'installazione raccomandata è il canale container firmato: un installer a comando singolo scarica l'immagine del vault bloccata per digest, crea le directory di state e config e installa un wrapper attesto-local-vault così che ogni comando CLI giri in modo trasparente nel container. Richiede Docker (Docker Desktop su macOS e Windows).

# Linux / macOS
curl -fsSL https://get.attesto.eu/local-vault/install.sh | sh

# Windows (PowerShell)
irm https://get.attesto.eu/local-vault/install.ps1 | iex

# Image pinned by digest (override: ATTESTO_LOCAL_VAULT_IMAGE):
# git.attesto.eu/attesto/local-vault@sha256:5799e7f0669c9b42a55a338f4233cfa5afb5aa6a2627c2c50f7545a41bff1551

Su macOS e Windows il vault e la sua provider sandbox solo-Linux girano nella VM Linux di Docker Desktop; le garanzie di isolamento valgono all'interno di quella VM. Un processo nativo macOS o Windows non le porterebbe — è esattamente per questo che gli installer sono wrapper di container. Disinstallazione: rimuovi il wrapper, rimuovi l'immagine con docker rmi e, solo se l'evidenza non serve più, elimina la directory di state — install.sh --help stampa i comandi esatti.

Su macOS e Linux lo stesso wrapper container si installa anche tramite Homebrew. Gli hash della formula sono copiati alla lettera dal manifest del canale firmato con cosign e Homebrew li impone a ogni installazione; i caveats ripetono il requisito Docker e la nota di onestà qui sopra:

brew tap attesto/attesto https://git.attesto.eu/attesto/homebrew-attesto.git
brew trust attesto/attesto
brew install attesto-local-vault

Su host Debian/Ubuntu e Fedora/RHEL, i pacchetti nativi installano lo stesso wrapper come /usr/bin/attesto-local-vault, eseguendo la stessa immagine bloccata per digest. Il deb dipende da un engine compatibile con Docker (docker-ce | docker.io | podman-docker); rpm non può esprimere quell'alternativa tra repository, quindi si limita a raccomandare docker — l'engine resta richiesto a runtime. Verifica il manifest firmato, controlla l'hash del pacchetto, poi installa:

curl -fsSLO https://get.attesto.eu/local-vault/2.0.1/SHA256SUMS
curl -fsSLO https://get.attesto.eu/local-vault/2.0.1/SHA256SUMS.sig
cosign verify-blob --key https://get.attesto.eu/cosign.pub --insecure-ignore-tlog --signature SHA256SUMS.sig SHA256SUMS

# Debian / Ubuntu (run the install as root)
curl -fsSLO https://get.attesto.eu/local-vault/2.0.1/attesto-local-vault_2.0.1-1_all.deb
sha256sum -c --ignore-missing SHA256SUMS
apt install ./attesto-local-vault_2.0.1-1_all.deb

# Fedora / RHEL (run the install as root)
curl -fsSLO https://get.attesto.eu/local-vault/2.0.1/attesto-local-vault-2.0.1-1.noarch.rpm
sha256sum -c --ignore-missing SHA256SUMS
dnf install ./attesto-local-vault-2.0.1-1.noarch.rpm

Il canale wheel Python resta disponibile per gli host che eseguono il vault nativamente su Linux:

pipx install attesto-local-vault

export ATTESTO_LOCAL_VAULT_SPOOL_DB=/var/lib/attesto/local-vault.sqlite3
export ATTESTO_LOCAL_VAULT_INSTALLATION_ID="$ATTESTO_LOCAL_VAULT_INSTALLATION_ID"
export ATTESTO_LOCAL_VAULT_RELAY_URL="https://verify.attesto.eu/v2/local-vault/installations/$ATTESTO_LOCAL_VAULT_INSTALLATION_ID/events"
export ATTESTO_LOCAL_VAULT_KEY_ID="$ATTESTO_LOCAL_VAULT_KEY_ID"

attesto-local-vault drain-loop

Controllo salute

Eseguire attesto-local-vault doctor dopo il bootstrap e durante operator troubleshooting. Il doctor controlla config, secrets locali, permessi di secrets.env, encrypted spool readback, regole HTTPS della relay URL, raggiungibilità del backend, server clock skew, header server Date non validi e dead-letter depth. I failures restituiscono un codice diverso da zero. I warnings mantengono lo spool utilizzabile, ma devono essere esaminati dall'operatore.

attesto-local-vault doctor

Enrollment

Un tenant owner o admin crea un enrollment token breve con POST /v2/tenant/local-vault/enrollment-tokens. L'edge host scambia quel token su POST /v2/local-vault/enroll e riceve installation metadata più la credential necessaria per outbound relay. Gli enrollment tokens sono single-use; Attesto salva solo il loro hash dopo la creazione.

Conferma di consegna

Local Vault marca un item come delivered solo quando Attesto restituisce un receipt JSON 2xx con localVaultAck.envelopeHash, stream binding e canonical event id corrispondenti. Un proxy 2xx, malformed body, mismatched receipt o revoked installation resta una delivery fallita soggetta a retry o dead-letter policy.

Outbound relay flow

La customer source crea un attestation event.
Local Vault firma e archivia l'event nell'encrypted spool.
Local Vault relay l'event a POST /v2/local-vault/installations/{installation_id}/events su https://verify.attesto.eu.
Attesto restituisce il Proofstream receipt.
Local Vault registra receipt state e mantiene retry metadata finché delivery è completa.

{
  "source_ref": "local-source-2026-0001",
  "event_type": "source.attestation",
  "payload_hash": "sha256-hex",
  "local_signature": {
    "alg": "Ed25519",
    "kid": "local-vault-key-epoch",
    "signature": "hex-encoded-signature"
  }
}

Encrypted spool

Lo spool preserva events durante network outages. Replay è ordinato e idempotent: la stessa source reference e body possono essere retried, ma changed content per la stessa source reference viene rifiutato.

State	Significato
`queued`	Archiviato localmente e in attesa di relay.
`relaying`	Outbound request in corso.
`receipted`	Attesto ha restituito un Proofstream receipt.
`conflict`	Source reference replayed con canonical content diverso.

Security model

Nessuna inbound internet route è richiesta per relay mode.
Connector credentials restano encrypted al customer edge.
Relay endpoints rifiutano replay conflicts e tampered envelopes.
Revocation fails closed: una revoked installation non può continuare a relaying accepted events.

Customer witness mode

Quando abilitato, Local Vault può firmare monotonic checkpoints per i suoi tenant streams. Una policy 2-of-3 può combinare statements Attesto-operated, customer-operated e assurance witness, così nessun singolo service viene trattato come unica source of history.

In witness mode, Local Vault firma checkpoint statements solo quando estendono il last accepted checkpoint per il tenant stream. Un conflict crea fork visibility lato cliente.

I witness checkpoint statements sono inviati a POST /v2/local-vault/installations/{installation_id}/witness/checkpoints e accettati solo quando l'installation è enabled, scoped al tenant e monotonic per lo stream.

Comando witness

Usa il comando operatore per firmare un monotonic checkpoint statement o restituire fork evidence per un checkpoint in conflitto. Il comando stampa solo materiale pubblico receipt/fork; non stampa mai la private signing key.

attesto-local-vault --witness-db /var/lib/attesto/local-vault-witness.sqlite3 \
  witness-checkpoint \
  --tenant-id ten_... \
  --stream-id str_... \
  --checkpoint-id chk_... \
  --checkpoint-seq-no 42 \
  --checkpoint-hash "$CHECKPOINT_HASH" \
  --previous-checkpoint-hash "$PREVIOUS_CHECKPOINT_HASH"

Provenance mode (Attesto 3)

Local Vault 2.x gira in una di tre modalità, commutate con attesto-local-vault mode --set legacy-relay|provenance|shadow. legacy-relay è il flusso di relay descritto sopra. In modalità provenance il vault costruisce una capsule per asset con il suo Rust edge core fissato, esegue i provider abilitati dentro la provider sandbox (AttestoMark Image, Audio e Video, C2PA) o come daemon misurati (l'inference gateway che trasporta AttestoMark Text), valuta la policy multi-segnale, conserva la capsule nel capsule store locale cifrato e inoltra un envelope ATTESTO-PROVENANCE-001 che porta solo commitments: il subject commitment, la capsule root, le root di claims, evidence e policy-results, il key id dell'installazione, il suo livello di assurance firmato e, a L1/L2, un'attestation reference. Contenuto grezzo, prompt, nomi dei file e output dei provider non lasciano mai l'host; la piattaforma non può restituire una capsule perché non ne conserva mai una. shadow esegue entrambe le lane per una migrazione guidata da attesto-local-vault migration status|advance|roll-back|cutover-evidence; non esiste --force, per scelta.

attesto-local-vault mode --set provenance
attesto-local-vault provenance self-test
attesto-local-vault provenance relay-loop

Il vault inoltra a POST /v2/local-vault/installations/{installation_id}/provenance-events, il percorso che l'oggetto installazione annuncia come provenanceEndpointPath; la firma Ed25519 dell'envelope è la credenziale. La piattaforma risponde con il receipt Proofstream più un provenanceAck. Lo stream deve essere un provenance stream creato con POST /v2/provenance/streams sotto una witness policy dichiarata prima con PUT /v2/tenant/witness/policies/{policy_id}; la guida API elenca ogni route.

Livelli di assurance e hardware custody

Livello	Richiede	Cosa verifica la piattaforma
`L0`	Una chiave software (predefinita).	La firma Ed25519.
`L1`	La stessa chiave Ed25519 custodita in un token PKCS#11, non estraibile.	Un attestation record `pkcs11-key-custody` firmato dalla chiave.
`L2`	L1 più un quote TPM 2.0 sulla misurazione del vault: versione del vault, checksum dell'edge core, provider manifests e signing key.	La firma del quote, il suo legame con il measurement digest e l'attestation key.
`L3`	Mai firmato da un vault.	Derivato dal verificatore da `L2` più un witness quorum raggiunto sul checkpoint che lo contiene; l'anchoring non promuove mai un livello.

L'algoritmo di firma non cambia tra i livelli. Un attestation record (ATTESTO-VAULT-ATTESTATION-001) viene registrato su POST /v2/local-vault/installations/{installation_id}/attestations; la piattaforma lo verifica e rifiuta un envelope L1/L2 che non può sostanziare. L2 non significa che l'host non possa essere compromesso: significa che un TPM ha firmato una dichiarazione su ciò che il vault ha misurato all'avvio. I provider PKCS#11 e TPM 2.0 sono esercitati in continuous integration contro SoftHSM2 e swtpm, doppioni software di quelle interfacce; nessuna installazione di produzione ha ancora firmato con hardware, e l'installazione del rollout first-party firma con una chiave software a L0.

Key lifecycle e revoca

Revocare un'installazione (DELETE /v2/tenant/local-vault/installations/{installation_id}) registra l'orologio della piattaforma come istante di revoca e lo pubblica su GET /v2/local-vault/installations/{installation_id}/key-status, pubblico di proposito affinché un verificatore che non è utente del tenant possa controllare le prove offline. La revoca viene valutata rispetto al platform receipt time di ogni evento, mai rispetto all'occurred_at dichiarato dal vault, con un confine inclusivo; una dichiarazione antecedente alla revoca il cui receipt non lo è riceve il flag suspect_backdated. Un verifier bundle su un provenance stream porta il key lifecycle del momento della sua costruzione, quindi una revoca successiva non è nel bundle.

Stato del rollout

La provenance lane è attiva in produzione. La fase A del rollout controllato è stata eseguita in produzione il 2026-08-23 con un tenant first-party: 15 receipts, 0 rilevamenti di privacy canary sui body HTTP, nei log del backend e in 92 tabelle del database, lo stream con checkpoint e witness. Il rollback per lane, che riporta i nuovi eventi alla legacy lane e non riscrive nulla, è stato provato contro la produzione. Le fasi da B a D, comprese le migrazioni dei design partner e il passaggio predefinito delle nuove configurazioni a provenance, non sono iniziate.

Offline e online modes

Online relay: events sono rapidamente signed, spooled, relayed e receipted.
Temporary offline relay: events restano encrypted nel local spool finché outbound network ritorna.
Witness online: checkpoint statements sono verificati e firmati secondo policy.
Witness unavailable: quorum può essere ritardato; receipts restano indipendenti da witness availability.