◈ Vault CLI

The hardware-secured environment injector. Eliminate plain-text .env files with Libsodium encryption and macOS Secure Enclave (Touch ID) integration.

› Why Vault?

• ✘ No Plain-Text: Stop storing secrets in naked .env files that can be leaked or stolen.
• ◈ Hardware Gated: Your Global Identity is locked behind the macOS Secure Enclave. Use your fingerprint to unlock project secrets.
• ✔ Temporary Injection: Secrets are injected into a child process and destroyed the moment you exit the session.
• ◈ Agent Aware: AI agents can securely manage your secrets without ever seeing your master password.
• ◈ Clean Aesthetic: Warm, professional TUI using the Flexoki color palette.

› Demo

https://github.com/user-attachments/assets/dd49f93b-a19e-4872-938f-000ad8e82c85

› Acknowledgments

The Vault CLI interface is styled with Flexoki, an inky color scheme for toolmakers. Special thanks to Steph Ango for creating this beautiful, high-contrast palette that makes terminal work a delight.

› Installation

1. Prerequisites

• macOS (for Touch ID/Secure Enclave support).
• Swift (part of Xcode Command Line Tools).
• Node.js (v20+ recommended).

2. Build from Source

git clone https://github.com/LutfiGarzon/vault.git
cd vault
npm install

# Compile and sign the hardware bridge
./scripts/setup.sh

# Build TypeScript
npm run build

# Link globally
npm link

› Usage

1. Project Initialization

Scan your .env files and create an encrypted .env.vault:

vault init

2. Global Secrets (Migrate from .zshrc)

Store machine-wide secrets (like NPM_TOKEN or AWS_KEYS) in your global machine identity. You can automatically migrate secrets from your shell config:

vault init -g -f ~/.zshrc

Once migrated, you can safely delete the plain-text exports from your .zshrc.

3. Enable Biometrics (Touch ID)

Upgrade your machine identity from password-only to biometrics:

vault eb

4. Recovery (Identity Restoration)

If you lose your computer, you can restore your Global Identity on a new machine using your Recovery Key:

vault recover

5. Add/Update a secret

Add a variable to the local project or global vault:

# Interactively (securely hidden)
vault add API_KEY

# Machine-wide global secret
vault add NPM_TOKEN --global

6. List Keys

See what secrets are currently available in your environment (values are masked by default):

vault ls

# Reveal plain-text values
vault ls --show-secrets

7. Smart Clean

Securely strip secrets from your .env file while keeping public config (like PORT) intact:

# Preview changes first
vault clean --dry-run

# Execute clean
vault clean

# Clean global files (e.g., .zshrc)
vault clean -g -f ~/.zshrc

8. Export Vault

Eject secrets from .env.vault back into a plain-text .env file:

vault export

9. Execute with secrets

Inject variables into process.env (Node), os.environ (Python), or any child process. This automatically merges Global + Project secrets:

# Node.js
vault npm start

# Python
vault python app.py

10. Secure Subshell

Open a new shell session where your secrets are available to every command you type:

vault
echo $MY_SECRET
exit

11. OIDC Setup (CI/CD Trust Policy)

Generate Terraform templates to establish OIDC-based trust between your CI provider and cloud provider. This allows your CI pipelines to authenticate via OpenID Connect instead of long-lived cloud credentials.

# Interactive wizard
vault oidc

# With environment suffix (generates vault-oidc-aws-prod.tf)
vault oidc --env prod

Supported cloud providers: AWS, Azure, GCP
Supported CI providers: GitHub Actions, GitLab CI

| Cloud | Terraform resources created | |-------|----------------------------| | AWS | IAM OIDC provider, trust policy, IAM role, role ARN output | | Azure | Azure AD application, federated identity credential, object ID output | | GCP | Workload identity pool, pool provider, service account, IAM binding, project_id variable |

After generating the template, apply it with:

terraform init
terraform apply -var="project_id=$GCP_PROJECT_ID"  # GCP only
terraform apply  # AWS / Azure

CI Runtime (vault ci)

KMS Key: The OIDC templates configure trust between CI and your cloud provider, but do not create the encryption key (KMS key). Create the key manually in your cloud console, encrypt your vault's Group Master Key with it, and pass the ciphertext as an environment variable.

Inside your CI pipeline, vault ci uses OIDC to decrypt secrets at runtime. Configure these environment variables in your CI secrets:

AWS

VAULT_AWS_ROLE_ARN=arn:aws:iam::123456789:role/vault-ci-role
VAULT_KMS_CIPHERTEXT=base64-encrypted-kms-ciphertext

Azure

VAULT_AZURE_TENANT_ID=your-tenant-id
VAULT_AZURE_CLIENT_ID=your-app-registration-client-id
VAULT_AZURE_KEY_VAULT_URL=https://myvault.vault.azure.net
VAULT_AZURE_KEY_NAME=my-key
VAULT_AZURE_CIPHERTEXT=base64-encrypted-ciphertext
# Optional: override auto-detection
# VAULT_CLOUD_PROVIDER=azure

GitLab users: Configure your .gitlab-ci.yml id_tokens with audience api://AzureADTokenExchange for the Azure path.

GCP

VAULT_GCP_PROJECT_NUMBER=123456789
VAULT_GCP_POOL_ID=vault-pool
VAULT_GCP_PROVIDER_ID=github
VAULT_GCP_PROJECT_ID=my-project            # defaults to PROJECT_NUMBER
VAULT_GCP_KMS_LOCATION=global               # defaults to global
VAULT_GCP_KMS_KEY_RING=my-keyring
VAULT_GCP_KMS_KEY_NAME=my-key
VAULT_GCP_CIPHERTEXT=base64-encrypted-ciphertext

Disambiguation: If multiple cloud env vars are set, use:

VAULT_CLOUD_PROVIDER=aws|azure|gcp

GitHub Actions Workflow Example

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      id-token: write   # Required for OIDC
      contents: read
    steps:
      - uses: actions/checkout@v4
      - run: vault ci npm start
        env:
          VAULT_AWS_ROLE_ARN: ${{ secrets.VAULT_AWS_ROLE_ARN }}
          VAULT_KMS_CIPHERTEXT: ${{ secrets.VAULT_KMS_CIPHERTEXT }}

› Agent Mode (AI Support)

Vault is designed for the age of AI. When you run an agent with Vault (e.g., vault pi), the CLI creates a temporary session token.

1. Read Access: The agent automatically sees all decrypted secrets in its environment.
2. Write Access: The agent can call vault add KEY VALUE to store new secrets without triggering a biometric prompt.
3. Security: The session token is only valid for the life of the agent process. It is never stored on disk and cannot be used after you close the agent.

› Contributing & Forking

This project is built with a feature-first modular architecture and follows TDD (Test-Driven Development). To add a new command:

1. Write failing tests in test/features/your-feature/.
2. Create src/features/your-feature/ for logic, TUI, templates, and providers.
3. Add the route to src/cli.ts.
4. Run npm test to ensure all tests pass and coverage thresholds are met.

See src/features/oidc/ for a complete example of a feature with templates, providers, and full test coverage.

› Security Guidelines

• Memory Safety: All sensitive keys are wiped using sodium.memzero() immediately after use.
• Disk Safety: Decrypted payloads reside only in memory; they are never written to temporary files.
• Hardware Integrity: Any changes to src/core/bridge.swift require a re-compile and re-sign of vault-bridge.

Author: Lutfi Garzon
License: Apache-2.0

› Support the Project

If Vault has helped you secure your workflow, consider supporting its development: