Bootstrap vault password provider¶

Purpose: Enable non-interactive vault operations by bootstrapping the local vault password provider.
Owner: Platform operations
Trigger: First-time install or when vault provider is not ready.
Impact: Without a provider, vault bundles cannot be decrypted or updated.
Severity: P3
Pre-reqs: pass, gpg, and a terminal pinentry are installed.
Rollback strategy: Remove stored entry via hyops vault reset.

Context¶

HybridOps.Core uses an Ansible Vault encrypted env bundle for bootstrap and CI/DR execution. The local password provider is backed by pass and gpg and is invoked as an executable vault password file.

Preconditions and safety checks¶

Confirm prerequisites:
```
command -v pass gpg ansible-vault
```

Steps¶

1) Bootstrap the provider
- Command:

hyops vault bootstrap

- Expected result: Provider stores the vault password and reports success. - Note: HyOps persists the default provider command at ~/.hybridops/config/vault-password-command so other HyOps commands can decrypt vault files without extra flags.

2) Confirm provider readiness
- Command:

hyops vault status-verbose

- Expected result: Output is ready. - Note: in a fresh shell, if you see not ready with a GPG/pinentry error, unlock once:

hyops vault password >/dev/null

Then re-run hyops vault status-verbose.

3) Verify vault operations (optional)
- Action: generate a test key into the runtime vault bundle (values are not printed). - Command:

hyops secrets ensure --env dev VAULT_PROVIDER_TEST

- Expected result: command succeeds and the encrypted bundle exists at:
~/.hybridops/envs/dev/vault/bootstrap.vault.env

Verification¶

hyops vault status-verbose returns exit code 0 and prints ready.
hyops secrets ensure --env dev VAULT_PROVIDER_TEST succeeds.

Troubleshooting¶

`hyops vault bootstrap` fails with permission denied¶

Cause: provider script is not executable.
Remediation:
If using a HybridOps.Core repo checkout, ensure the script is executable:
```
chmod 0755 tools/secrets/vault/vault-pass.sh
```
If HyOps is installed outside the core repo, pass an explicit script path:
```
hyops vault --script /path/to/vault-pass.sh bootstrap
```

`hyops vault bootstrap` fails due to missing `pass` or `gpg`¶

Cause: prerequisites not installed.
Remediation:
```
hyops setup base --sudo
```

Bootstrap hangs on pinentry¶

Cause: pinentry backend requires TTY.
Remediation:
Execute from an interactive terminal session.

Confirm pinentry-curses is installed:

dpkg -l | grep -E '^ii\s+pinentry-curses\b' || true

`hyops vault status-verbose` prints `not ready` with `No pinentry`¶

Meaning: the vault password exists in pass but your GPG key is locked and cannot prompt (common in a fresh shell).

Remediation (interactive shells):

hyops vault password >/dev/null
hyops vault status-verbose

Post-actions and clean-up¶

For CI usage, provide a distinct password source and use --vault-password-command 'printenv <VAR>' for init targets that support it.