Enterprise Edge

Local Vault

Local Vault es un componente customer edge outbound-only para connector secret storage, source attestation signing, offline spooling, event relay y optional customer-side witness operation. No es HashiCorp Vault.

Responsibilities

Encrypt connector credentials localmente.
Firmar source attestations antes de relay.
Spool events durante network outages.
Replay spooled events en orden con idempotency.
Operar como customer-side witness cuando tenant policy lo habilita.

Instalar y ejecutar

Instale Local Vault en el host edge controlado por el cliente. Las coordenadas runtime pueden venir de flags o variables de entorno, pero signing keys, spool encryption keys y connector credentials deben venir del secret manager local de despliegue. No las ponga en shell history, configuración frontend ni docs de 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

Comprobación de salud

Ejecute attesto-local-vault doctor después del bootstrap y durante operator troubleshooting. El doctor comprueba config, secrets locales, permisos de secrets.env, encrypted spool readback, reglas HTTPS de relay URL, disponibilidad del backend, server clock skew, cabeceras de servidor Date inválidas y dead-letter depth. Los failures devuelven un código distinto de cero. Los warnings mantienen el spool utilizable, pero el operador debe revisarlos.

attesto-local-vault doctor

Enrollment

Un tenant owner o admin crea un enrollment token corto con POST /v2/tenant/local-vault/enrollment-tokens. El edge host intercambia ese token en POST /v2/local-vault/enroll y recibe installation metadata más la credential necesaria para outbound relay. Los enrollment tokens son single-use; Attesto almacena solo su hash después de la creación.

Acknowledgement de entrega

Local Vault marca un ítem como delivered solo cuando Attesto devuelve un receipt JSON 2xx con localVaultAck.envelopeHash, stream binding y canonical event id coincidentes. Un proxy 2xx, malformed body, mismatched receipt o revoked installation sigue siendo una entrega fallida sujeta a retry o dead-letter policy.

Outbound relay flow

La customer source crea un attestation event.
Local Vault firma y almacena el event en el encrypted spool.
Local Vault relay el event a POST /v2/local-vault/installations/{installation_id}/events en https://verify.attesto.eu.
Attesto devuelve el Proofstream receipt.
Local Vault registra receipt state y conserva retry metadata hasta completar 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

El spool preserva events durante network outages. Replay es ordenado e idempotente: la misma source reference y body pueden reintentarse, pero changed content para la misma source reference es rechazado.

State	Significado
`queued`	Almacenado localmente y esperando relay.
`relaying`	Outbound request en progreso.
`receipted`	Attesto devolvió un Proofstream receipt.
`conflict`	Source reference reproducida con canonical content diferente.

Security model

No se requiere inbound internet route para relay mode.
Connector credentials permanecen encrypted en el customer edge.
Relay endpoints rechazan replay conflicts y tampered envelopes.
Revocation fails closed: una revoked installation no puede seguir relaying accepted events.

Customer witness mode

Cuando está habilitado, Local Vault puede firmar monotonic checkpoints para sus tenant streams. Una policy 2-of-3 puede combinar statements Attesto-operated, customer-operated y assurance witness para que ningún servicio único sea tratado como la única source of history.

En witness mode, Local Vault firma checkpoint statements solo cuando extienden el last accepted checkpoint del tenant stream. Un conflict crea fork visibility para el lado del cliente.

Los witness checkpoint statements se envían a POST /v2/local-vault/installations/{installation_id}/witness/checkpoints y se aceptan solo cuando la installation está enabled, scoped al tenant y es monotonic para el stream.

Comando witness

Use el comando de operador para firmar un monotonic checkpoint statement o devolver fork evidence para un checkpoint conflictivo. El comando imprime solo material público receipt/fork; nunca imprime 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 y online modes

Online relay: events se signed, spooled, relayed y receipted rápidamente.
Temporary offline relay: events permanecen encrypted en el local spool hasta que vuelve outbound network.
Witness online: checkpoint statements se verifican y firman según policy.
Witness unavailable: quorum puede retrasarse; receipts permanecen independientes de witness availability.