Enterprise Edge

Local Vault

Local Vault is an outbound-only customer edge component for connector secret storage, source attestation signing, offline spooling, event relay, optional customer-side witness operation and, in Local Vault 2.x, Attesto 3 provenance mode, where capsules stay on the edge host and only commitments reach the platform. It is not HashiCorp Vault.

Responsibilities

• Encrypt connector credentials locally.
• Sign source attestations before relay.
• Spool events during network outages.
• Replay spooled events in order with idempotency.
• Operate as a customer-side witness when the tenant policy enables it.

Local image provenance uses the isolated provider and encrypted keyed registry described in the AttestoMark Image guide.

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.

The recommended install is the signed container channel: a one-command installer pulls the vault image pinned by digest, creates the state and config directories, and installs an attesto-local-vault wrapper so every CLI command runs in the container transparently. It requires Docker (Docker Desktop on macOS and Windows).

# Linux / macOS
curl -fsSL https://get.attesto.eu/local-vault/install.sh | sh

# Windows (PowerShell)
irm https://get.attesto.eu/local-vault/install.ps1 | iex

# Image pinned by digest (override: ATTESTO_LOCAL_VAULT_IMAGE):
# git.attesto.eu/attesto/local-vault@sha256:5799e7f0669c9b42a55a338f4233cfa5afb5aa6a2627c2c50f7545a41bff1551

On macOS and Windows the vault and its Linux-only provider sandbox run inside Docker Desktop's Linux VM; the isolation claims apply within that VM. A native macOS or Windows process would not carry them, which is why the installers are container wrappers. To uninstall, remove the wrapper, remove the image with docker rmi and, only if the evidence is no longer needed, delete the state directory — install.sh --help prints the exact commands.

On macOS and Linux the same container wrapper also installs through Homebrew. The formula hashes are copied verbatim from the cosign-signed channel manifest and Homebrew enforces them on every install; the caveats repeat the Docker requirement and the honesty note above:

brew tap attesto/attesto https://git.attesto.eu/attesto/homebrew-attesto.git
brew trust attesto/attesto
brew install attesto-local-vault

On Debian/Ubuntu and Fedora/RHEL hosts, native packages install the same wrapper as /usr/bin/attesto-local-vault, running the same digest-pinned image. The deb depends on a Docker-compatible engine (docker-ce | docker.io | podman-docker); rpm cannot express that alternation across repositories, so it only recommends docker — the engine stays required at runtime. Verify the signed manifest, check the package hash, then install:

curl -fsSLO https://get.attesto.eu/local-vault/2.0.1/SHA256SUMS
curl -fsSLO https://get.attesto.eu/local-vault/2.0.1/SHA256SUMS.sig
cosign verify-blob --key https://get.attesto.eu/cosign.pub --insecure-ignore-tlog --signature SHA256SUMS.sig SHA256SUMS

# Debian / Ubuntu (run the install as root)
curl -fsSLO https://get.attesto.eu/local-vault/2.0.1/attesto-local-vault_2.0.1-1_all.deb
sha256sum -c --ignore-missing SHA256SUMS
apt install ./attesto-local-vault_2.0.1-1_all.deb

# Fedora / RHEL (run the install as root)
curl -fsSLO https://get.attesto.eu/local-vault/2.0.1/attesto-local-vault-2.0.1-1.noarch.rpm
sha256sum -c --ignore-missing SHA256SUMS
dnf install ./attesto-local-vault-2.0.1-1.noarch.rpm

The Python wheel channel remains available for hosts that run the vault natively on Linux:

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.

Security model

• No inbound internet route is required for relay mode.
• Connector credentials remain encrypted at the customer edge.
• Relay endpoints reject replay conflicts and tampered envelopes.
• Revocation fails closed: a revoked installation cannot keep relaying accepted events.

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"

Provenance mode (Attesto 3)

Local Vault 2.x runs in one of three modes, switched with attesto-local-vault mode --set legacy-relay|provenance|shadow. legacy-relay is the relay flow above. In provenance mode the vault builds a capsule per asset with its pinned Rust edge core, runs the enabled providers inside the provider sandbox (AttestoMark Image, Audio and Video, C2PA) or as measured daemons (the inference gateway carrying AttestoMark Text), evaluates the multi-signal policy, keeps the capsule in the encrypted local capsule store, and relays an ATTESTO-PROVENANCE-001 envelope that carries commitments only: the subject commitment, the capsule root, the claims, evidence and policy-results roots, the installation's key id, its signed assurance level and, at L1/L2, an attestation reference. Raw content, prompts, file names and provider output never leave the host; the platform cannot return a capsule because it never holds one. shadow runs both lanes for a migration driven by attesto-local-vault migration status|advance|roll-back|cutover-evidence; there is no --force, by design.

attesto-local-vault mode --set provenance
attesto-local-vault provenance self-test
attesto-local-vault provenance relay-loop

The vault relays to POST /v2/local-vault/installations/{installation_id}/provenance-events, the path the installation object advertises as provenanceEndpointPath; the envelope's Ed25519 signature is the credential. The platform answers with the Proofstream receipt plus a provenanceAck. The stream must be a provenance stream created with POST /v2/provenance/streams under a witness policy declared first with PUT /v2/tenant/witness/policies/{policy_id}; the API guide lists every route.

Assurance levels and hardware custody

The signature algorithm does not change between levels. An attestation record (ATTESTO-VAULT-ATTESTATION-001) is registered at POST /v2/local-vault/installations/{installation_id}/attestations; the platform verifies it and refuses an L1/L2 envelope it cannot substantiate. L2 does not mean the host cannot be compromised: it means a TPM signed a statement about what the vault measured when it started. The PKCS#11 and TPM 2.0 providers are exercised in continuous integration against SoftHSM2 and swtpm, which are software doubles of those interfaces; no production installation has signed with hardware yet, and the first-party rollout installation signs with a software key at L0.

Key lifecycle and revocation

Revoking an installation (DELETE /v2/tenant/local-vault/installations/{installation_id}) records the platform clock as the revocation instant and publishes it at GET /v2/local-vault/installations/{installation_id}/key-status, which is public on purpose so a verifier who is not the tenant's user can check evidence offline. Revocation is evaluated against the platform receipt time of each event, never the vault-claimed occurred_at, with an inclusive boundary; a claim that predates the revocation while its receipt does not is flagged suspect_backdated. A verifier bundle over a provenance stream carries the key lifecycle as of bundle build, so a later revocation is not in the bundle.

Rollout state

The provenance lane is on in production. Phase A of the controlled rollout ran on production on 2026-08-23 with a first-party tenant: 15 receipts, 0 privacy-canary hits over the HTTP bodies, the backend logs and 92 database tables, the stream checkpointed and witnessed. The lane-based rollback, which returns new events to the legacy lane and rewrites nothing, was rehearsed against production. Phases B to D, including design-partner migrations and the default switch to provenance for new setups, have not started.

Offline and online modes

• Online relay: events are signed, spooled, relayed, and receipted quickly.
• Temporary offline relay: events remain encrypted in the local spool until outbound network returns.
• Witness online: checkpoint statements are verified and signed according to policy.
• Witness unavailable: quorum may be delayed; receipts remain independent from witness availability.