Skip to main content

Configuration

This page is the canonical configuration surface for jhf-keystore.

Runtime Modes​

Supported provider modes:

  • cli
    • default and preferred
    • reads via local bw execution
  • serve
    • loopback-only
    • must stay local and explicitly guarded

jhf-keystore is not a remote secret service and must not expose a public write or read API.

Primary Environment Variables​

Core runtime inputs:

  • VW_PROVIDER
  • VW_BW_BIN
  • VW_BW_SERVE_URL
  • VW_REQUIRE_LOCAL
  • BW_SESSION
  • VW_BW_SECRET_ENV_FILE
  • BW_PASSWORD_ENV

Live-gated verification inputs:

  • VW_RUNTIME_DRIFT_VERIFY_LIVE
  • VW_RUNTIME_DRIFT_VERIFY_HOST
  • VW_RUNTIME_DRIFT_VERIFY_USER
  • VW_SSO_VERIFY_LIVE
  • VW_PROJECTION_VERIFY_LIVE
  • VOICE_V6_VERIFY_LIVE
  • VOICE_W7_VERIFY_LIVE

Execution-policy rule:

  • secrets or passwords may be injected at runtime
  • secrets must never be checked into repo truth, docs, manifests, or evidence artifacts

Configuration Truth Sources​

Canonical configuration surfaces:

  • STACK_CONTRACT.md (docs/STACK_CONTRACT.md)
  • ../contracts/runtime-stack-contract.json (contracts/runtime-stack-contract.json)
  • ../contracts/vaultwarden-sso-consumer-runtime.json (contracts/vaultwarden-sso-consumer-runtime.json)
  • ../contracts/non-interactive-bw-auth-bootstrap.md (contracts/non-interactive-bw-auth-bootstrap.md)

Deployment Profile And Resolver Boundary​

Deployment profiles describe the Vaultwarden container runtime. Resolver settings describe the local process that reads from that runtime through bw or loopback-only bw serve. These are related, but they are not the same configuration layer.

Profile-owned truth:

  • local-example, production-hasicloud, and production-lowcpu are defined by ../contracts/runtime-stack-contract.json (contracts/runtime-stack-contract.json)
  • profile truth covers compose file order, required container environment keys, ports, volumes, healthchecks, resource limits, and rollback commands
  • profile verification uses compose/readback checks such as docker compose config, docker inspect, and the runtime materialization drift verifier

Resolver-owned truth:

  • VW_PROVIDER, VW_BW_BIN, VW_BW_SERVE_URL, VW_REQUIRE_LOCAL, BW_SESSION, VW_BW_SECRET_ENV_FILE, and BW_PASSWORD_ENV are process-local resolver inputs
  • cli remains the default resolver provider; serve is allowed only when loopback locality validation passes
  • probe and doctor checks may read resolver readiness, but they must not infer deployment success from a profile name alone

Boundary rules:

  • deployment profile selection must not materialize secret values into repo truth, docs, manifests, or Gitea evidence
  • resolver readiness must fail closed when bw is missing, locked, unauthenticated, non-local, or timed out
  • downstream consumers must use profile readback for container/runtime posture and resolver probes for local secret-read readiness
  • a green compose profile does not prove that the local resolver can read secrets, and a green resolver probe does not prove that the container profile is materially current

Execution Hooks​

Primary repo-owned verification hooks:

  • bash scripts/verify-docs-inventory-adoption.sh
  • bash scripts/verify-runtime-materialization-drift.sh
  • bash scripts/verify-vaultwarden-projection-presence.sh
  • bash scripts/verify-vaultwarden-sso-consumer-contract.sh

These hooks are the canonical readback path for configuration drift.

Known Limits​

  • no live secret values in docs or manifests
  • no remote control plane
  • no repo-owned reconciliation of upstream identity truth

AGPLv3. See LICENSE (LICENSE).

Learn more at helpifyr.com.