Enterprise Edge

Local Vault

Local Vault to outbound-only customer edge component dla connector secret storage, source attestation signing, offline spooling, event relay i opcjonalnego customer-side witness operation. To nie jest HashiCorp Vault.

Responsibilities

Encrypt connector credentials lokalnie.
Podpisywać source attestations przed relay.
Spool events podczas network outages.
Replay spooled events w kolejności z idempotency.
Działać jako customer-side witness, gdy tenant policy to włącza.

Instalacja i uruchomienie

Zainstaluj Local Vault na kontrolowanym przez klienta hoście edge. Współrzędne runtime mogą pochodzić z flag lub zmiennych środowiskowych, ale signing keys, spool encryption keys i connector credentials muszą pochodzić z lokalnego deployment secret managera. Nie umieszczaj ich w shell history, konfiguracji frontendu ani 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

Kontrola zdrowia

Uruchom attesto-local-vault doctor po bootstrapie oraz podczas operator troubleshooting. Doctor sprawdza config, lokalne secrets, uprawnienia secrets.env, encrypted spool readback, reguły HTTPS dla relay URL, osiągalność backendu, server clock skew, nieprawidłowe nagłówki serwera Date oraz dead-letter depth. Failures zwracają non-zero exit code. Warnings pozostawiają spool używalny, ale operator musi je przejrzeć.

attesto-local-vault doctor

Enrollment

Tenant owner albo admin tworzy krótkotrwały enrollment token przez POST /v2/tenant/local-vault/enrollment-tokens. Edge host wymienia ten token w POST /v2/local-vault/enroll i otrzymuje installation metadata oraz credential potrzebny do outbound relay. Enrollment tokens są single-use; Attesto po utworzeniu zapisuje tylko ich hash.

Potwierdzenie dostarczenia

Local Vault oznacza element jako delivered tylko wtedy, gdy Attesto zwróci 2xx JSON receipt z pasującym localVaultAck.envelopeHash, stream binding i canonical event id. Proxy 2xx, malformed body, mismatched receipt albo revoked installation pozostają nieudaną dostawą pod retry lub dead-letter policy.

Outbound relay flow

Customer source tworzy attestation event.
Local Vault podpisuje i zapisuje event w encrypted spool.
Local Vault relay event do POST /v2/local-vault/installations/{installation_id}/events na https://verify.attesto.eu.
Attesto zwraca Proofstream receipt.
Local Vault zapisuje receipt state i przechowuje retry metadata do zakończenia delivery.

{
  "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

Spool zachowuje events podczas network outages. Replay jest uporządkowany i idempotent: ta sama source reference i body mogą być retried, ale changed content dla tej samej source reference jest odrzucany.

State	Znaczenie
`queued`	Zapisane lokalnie i oczekujące na relay.
`relaying`	Outbound request jest w toku.
`receipted`	Attesto zwróciło Proofstream receipt.
`conflict`	Source reference została replayed z inną canonical content.

Security model

Inbound internet route nie jest wymagana dla relay mode.
Connector credentials pozostają encrypted na customer edge.
Relay endpoints odrzucają replay conflicts i tampered envelopes.
Revocation fails closed: revoked installation nie może dalej relaying accepted events.

Customer witness mode

Po włączeniu Local Vault może podpisywać monotonic checkpoints dla swoich tenant streams. Policy 2-of-3 może łączyć Attesto-operated, customer-operated i assurance witness statements, aby żaden pojedynczy service nie był traktowany jako jedyna source of history.

W witness mode Local Vault podpisuje checkpoint statements tylko wtedy, gdy rozszerzają last accepted checkpoint dla tenant stream. Conflict tworzy fork visibility po stronie klienta.

Witness checkpoint statements są wysyłane do POST /v2/local-vault/installations/{installation_id}/witness/checkpoints i akceptowane tylko wtedy, gdy installation jest enabled, scoped do tenant i monotonic dla streamu.

Komenda witness

Użyj komendy operatora, aby podpisać monotonic checkpoint statement albo zwrócić fork evidence dla konfliktowego checkpointu. Komenda wypisuje tylko publiczny materiał receipt/fork; nigdy nie wypisuje 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 i online modes

Online relay: events są szybko signed, spooled, relayed i receipted.
Temporary offline relay: events pozostają encrypted w local spool do powrotu outbound network.
Witness online: checkpoint statements są weryfikowane i podpisywane zgodnie z policy.
Witness unavailable: quorum może być opóźnione; receipts pozostają niezależne od witness availability.