Enterprise Edge

Local Vault

Local Vault è un customer edge component outbound-only per connector secret storage, source attestation signing, offline spooling, event relay e optional customer-side witness operation. 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.

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.

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"

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.