Vault module

Overview

SHC’s vault provides encrypted secrets storage with support for multiple providers.

Encryption

Fernet (AES-128 + HMAC)
PBKDF2 key derivation with 480,000 iterations
User-provided vault password

Secret Scoping

Path depth determines scope:

{tenant}/{secret} → tenant scope (2 levels)
{tenant}/{stack}/{secret} → stack scope (3 levels)
{tenant}/envs/{environment}/{secret} → environment scope (4 levels)
{tenant}/{stack}/{environment}/{secret} → deployment scope (4 levels)

Resolution order (specific to general):

Deployment (tenant + stack + environment)
Stack (tenant + stack)
Environment (tenant + environment)
Tenant

Note: “system” is a tenant, not a special scope. “envs” is reserved and cannot be used as a stack name.

Secret References

In config files:

database:
  password: !ref+vault://db_password
smtp:
  api_key: !ref+env://SMTP_API_KEY?default=test-key

External Providers

Supported providers:

Provider	Config Key	Required Settings	Transport
Built-in encrypted database	`local` (default)	`vault.password`	Database
Pass (password-store)	`pass`	None (uses ~/.password-store)	CLI (apt)
SOPS	`sops`	`file_path`	CLI
Doppler	`doppler`	`token`, `project`, `config`	HTTP
Infisical	`infisical`	`client_id`, `client_secret`, `project_id`, `environment`	HTTP
1Password Connect	`1password`	`connect_host`, `connect_token`, `vault_uuid`	HTTP
HashiCorp Vault	`hashicorp`	`address`, `token` or `role_id`/`secret_id`	HTTP/SDK
AWS Secrets Manager	`aws`	`region`	SDK (boto3)
Azure Key Vault	`azure`	`vault_url`	SDK
Google Secret Manager	`gcp`	`project_id`	SDK
Bitwarden Secrets Manager	`bitwarden`	`access_token`, `organization_id`	SDK

Configure per scope in config.yaml:

vault:
  provider: aws
  aws:
    region: us-east-1

# Or use multiple providers
vault:
  provider: doppler  # default
  providers:
    doppler:
      token: dop_...
      project: myproject
      config: prod
    sops:
      file_path: /etc/shc/secrets.yaml
      age_key_file: /etc/shc/age.key

Provider Chaining

Vault providers can reference secrets from other providers in their configuration. This enables bootstrapping complex setups where credentials for one provider are stored in another.

vault:
  providers:
    # Pass has no dependencies - initialized first
    pass:
      gpg_id: ABCD1234

    # AWS credentials stored in pass
    aws:
      region: us-east-1
      access_key_id: ref+vault://aws_access_key
      secret_access_key: ref+vault://aws_secret_key

    # HashiCorp token from pass or aws
    hashicorp:
      address: https://vault.example.com
      token: ref+vault://hc_token

Resolution algorithm:

Providers with no vault refs are initialized first
Remaining providers are iteratively resolved using already-resolved ones
Process continues until all resolved or no progress (circular/missing deps)

Vault paths follow scoping rules (tenant/stack/secret), not provider names. Auto-resolution tries all resolved providers in order until one succeeds.

Explicit provider (discouraged): ref+vault://secret?provider=pass targets specific provider via query param.

Export/Import

Export format (.vlt):

{
  "version": "1",
  "encrypted": true,
  "secrets": {
    "db_password": "Z0FBQUFCYWJjMTIz..."
  }
}