Enterprise Edge

Local Vault

Local Vault is een outbound-only customer edge component voor connector secret storage, source attestation signing, offline spooling, event relay en optionele customer-side witness operation. Het is geen HashiCorp Vault.

Responsibilities

• Encrypt connector credentials lokaal.
• Onderteken source attestations vóór relay.
• Spool events tijdens network outages.
• Replay spooled events in volgorde met idempotency.
• Operate als customer-side witness wanneer tenant policy dit inschakelt.

Installeren en draaien

Installeer Local Vault op de klantbeheerde edge host. Runtime-coördinaten mogen uit flags of environment variables komen, maar signing keys, spool encryption keys en connector credentials moeten uit de lokale deployment secret manager komen. Plaats ze niet in shell history, frontendconfig of Attesto-docs.

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

Health check

Draai attesto-local-vault doctor na bootstrap en tijdens operator troubleshooting. De doctor controleert config, lokale secrets, secrets.env-permissies, encrypted spool readback, relay URL HTTPS regels, backend bereikbaarheid, server clock skew, invalid server Date headers en dead-letter depth. Failures geven een non-zero exit code. Warnings houden de spool bruikbaar maar moeten door de operator worden beoordeeld.

attesto-local-vault doctor

Enrollment

Een tenant owner of admin maakt een kortlevend enrollment token met POST /v2/tenant/local-vault/enrollment-tokens. De edge host wisselt dat token om via POST /v2/local-vault/enroll en ontvangt installation metadata plus de credential voor outbound relay. Enrollment tokens zijn single-use; Attesto slaat na creatie alleen hun hash op.

Delivery acknowledgement

Local Vault markeert een item alleen als delivered wanneer Attesto een 2xx JSON receipt teruggeeft met matchende localVaultAck.envelopeHash, streambinding en canonical event id. Een proxy 2xx, malformed body, mismatched receipt of revoked installation blijft een mislukte delivery en valt onder retry of dead-letter policy.

Outbound relay flow

1. De customer source maakt een attestation event.
2. Local Vault ondertekent en bewaart het event in de encrypted spool.
3. Local Vault relayt het event naar POST /v2/local-vault/installations/{installation_id}/events op https://verify.attesto.eu.
4. Attesto retourneert de Proofstream receipt.
5. Local Vault registreert receipt state en bewaart retry metadata totdat delivery compleet is.

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

De spool bewaart events tijdens network outages. Replay is geordend en idempotent: dezelfde source reference en body kunnen worden retried, maar changed content voor dezelfde source reference wordt geweigerd.

Security model

• Geen inbound internet route is vereist voor relay mode.
• Connector credentials blijven encrypted aan de customer edge.
• Relay endpoints verwerpen replay conflicts en tampered envelopes.
• Revocation faalt gesloten: een revoked installation kan niet blijven relaying accepted events.

Customer witness mode

Wanneer ingeschakeld kan Local Vault monotonic checkpoints voor zijn tenant streams ondertekenen. Een 2-of-3 policy kan Attesto-operated, customer-operated en assurance witness statements combineren zodat geen enkele service als enige source of history wordt behandeld.

In witness mode ondertekent Local Vault checkpoint statements alleen wanneer ze de last accepted checkpoint voor de tenant stream uitbreiden. Een conflict maakt fork visibility aan de klantzijde.

Witness checkpoint statements worden ingediend bij POST /v2/local-vault/installations/{installation_id}/witness/checkpoints en worden alleen geaccepteerd wanneer de installation enabled is, aan de tenant is scoped en monotonic is voor de stream.

Witness command

Gebruik de operator command om een monotonic checkpoint statement te signeren of fork evidence terug te geven voor een conflicterend checkpoint. Het commando print alleen publiek receipt/fork-materiaal; het print nooit de 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 en online modes

• Online relay: events worden snel signed, spooled, relayed en receipted.
• Temporary offline relay: events blijven encrypted in de local spool totdat outbound network terugkeert.
• Witness online: checkpoint statements worden volgens policy geverifieerd en ondertekend.
• Witness unavailable: quorum kan vertraagd zijn; receipts blijven onafhankelijk van witness availability.