Attesto

Enterprise Edge

Local Vault

Local Vault is an outbound-only customer edge component for connector secret storage, source attestation signing, offline spooling, event relay, and optional customer-side witness operation. It is not HashiCorp Vault.

Responsibilities

Install and run

Install Local Vault on the customer-controlled edge host. Runtime coordinates can come from flags or environment variables, but signing keys, spool encryption keys, and connector credentials must come from the local deployment secret manager. Do not place them in shell history, frontend config, or 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

Run attesto-local-vault doctor after bootstrap and during operator troubleshooting. The doctor checks config presence, local secret availability, secrets.env permissions, encrypted spool readback, relay URL HTTPS rules, backend reachability, server clock skew, invalid server Date headers, and dead-letter depth. Failures return a non-zero exit code. Warnings keep the spool usable but must be reviewed by the operator. 

attesto-local-vault doctor

Enrollment

A tenant owner or admin creates a short-lived enrollment token with POST /v2/tenant/local-vault/enrollment-tokens. The edge host exchanges that token at POST /v2/local-vault/enroll and receives installation metadata plus the credential needed for outbound relay. Enrollment tokens are single-use; Attesto stores only their hash after creation.

Delivery acknowledgement

Local Vault marks an item as delivered only when Attesto returns a 2xx JSON receipt with a matching localVaultAck.envelopeHash, stream binding, and canonical event id. A proxy 2xx, malformed body, mismatched receipt, or revoked installation remains a failed delivery and stays subject to retry or dead-letter policy.

Outbound relay flow

  1. The customer source creates an attestation event.
  2. Local Vault signs and stores the event in the encrypted spool.
  3. Local Vault relays the event to POST /v2/local-vault/installations/{installation_id}/events on https://verify.attesto.eu.
  4. Attesto returns the Proofstream receipt.
  5. Local Vault records receipt state and keeps retry metadata until delivery is complete.
{
  "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

The spool preserves events during network outages. Replay is ordered and idempotent: the same source reference and body can be retried, but changed content for the same source reference is rejected.

StateMeaning
queuedStored locally and waiting for relay.
relayingOutbound request is in progress.
receiptedAttesto returned a Proofstream receipt.
conflictSource reference replayed with different canonical content.

Security model

Customer witness mode

When enabled, Local Vault can sign monotonic checkpoints for its tenant streams. A 2-of-3 policy can combine Attesto-operated, customer-operated, and assurance witness statements so no single service is treated as the only source of history.

Witness checkpoint statements are submitted to POST /v2/local-vault/installations/{installation_id}/witness/checkpoints and are accepted only when the installation is enabled, scoped to the tenant, and monotonic for the stream.

In witness mode, Local Vault signs checkpoint statements only when they extend the last accepted checkpoint for the tenant stream. A conflict creates fork visibility for the customer side.

Witness command

Use the operator command to sign a monotonic checkpoint statement or return fork evidence for a conflicting checkpoint. The command prints public receipt/fork material only; it never prints the 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 and online modes