@lockzero/vault-sync

Bidirectional sync between LockZero and HashiCorp Vault KV v2.

Installation

npm install -g @lockzero/vault-sync

Authentication

| Credential | How to provide | |---|---| | LockZero API key | --lz-key <key> or LOCKZERO_API_KEY env var | | Vault address | --vault-addr <addr> or VAULT_ADDR env var | | Vault token | --vault-token <token> or VAULT_TOKEN env var |

Secret layout

Each LockZero namespace is stored as a single KV v2 secret at lockzero/<namespace>. All fields are stored as key→value pairs within the same secret (Vault KV naturally stores maps).

Example: namespace openai → Vault path secret/data/lockzero/openai

Commands

push — LockZero → Vault

lockzero-vault push \
  --namespace openai \
  --vault-addr https://vault.example.com \
  --vault-token $VAULT_TOKEN \
  --mount secret

# Preview without writing
lockzero-vault push --namespace openai --dry-run

pull — Vault → LockZero

lockzero-vault pull \
  --namespace openai \
  --vault-addr https://vault.example.com \
  --vault-token $VAULT_TOKEN

# Preview without writing
lockzero-vault pull --namespace openai --dry-run

diff — show what would change

# Show what a push would do
lockzero-vault diff --namespace openai --direction push

# Show what a pull would do
lockzero-vault diff --namespace openai --direction pull

watch — continuous sync (Vault → LockZero)

Polls Vault every N seconds. When field values change, they are automatically synced to LockZero. Uses SHA-256 hash comparison to detect changes with no false positives from key-ordering differences.

lockzero-vault watch \
  --namespace openai \
  --vault-addr https://vault.example.com \
  --vault-token $VAULT_TOKEN \
  --interval 30

# Output:
# [2026-05-10T06:00:00.000Z] Baseline established: 3 field(s) at lockzero/openai
# [2026-05-10T06:00:30.000Z] No changes (3 field(s) unchanged)
# [2026-05-10T06:01:00.000Z] Change detected at lockzero/openai — syncing to LockZero…
# [2026-05-10T06:01:00.123Z] Synced 3 field(s) successfully

Press Ctrl+C to stop.

Options

| Flag | Default | Description | |---|---|---| | --namespace | required | LockZero namespace (e.g. openai, stripe) | | --lz-key | env | LockZero API key | | --lz-base-url | https://api.lockzero.io | LockZero base URL | | --vault-addr | env | Vault server address | | --vault-token | env | Vault token | | --mount | secret | Vault KV mount path | | --direction | push | Diff direction: push or pull | | --interval | 30 | Watch polling interval in seconds | | --dry-run | false | Preview changes without writing |

Minimal Vault policy

path "secret/data/lockzero/*" {
  capabilities = ["create", "read", "update", "list"]
}
path "secret/metadata/lockzero/*" {
  capabilities = ["list"]
}