DOCSEARCHbyAlgolia
Submit Docs

Varlock

repository·main·Indexed 25 days ago

https://github.com/dmno-dev/varlock

AI-safe environment variable management using schemas. Varlock allows developers to define strict types and validation rules for .env files, enabling secure secret loading from backends like 1Password or AWS. It includes @env-spec, a DSL for attaching structured metadata via decorators and dynamic value assignment through function calls, as well as native encryption binaries for Rust (cross-platform) and Swift (macOS Secure Enclave and Keychain integration).

Tokens
189.3K
Snippets
644
Records
1K
Agent score
87%

What's inside varlock

  1. Overview of Varlock Integrations

    main

    Varlock provides official integrations that connect the CLI, runtime helpers, and framework-specific plugins. These integrations ensure your environment configuration is validated, type-safe, and protected across different environments.

    Key capabilities of integrations:

    • Automatic Loading & Validation: Automatically load and validate .env files during development and use them in CI/CD and production.
    • Config Injection: Inject configuration into your code at either build time or request time.
    • Runtime Protections: Enable features like leak prevention and log redaction.

  2. Overview of Varlock features

    main

    Varlock is a universal configuration, secrets, and environment variable management tool built on the @env-spec specification. It is designed to be language and framework agnostic, providing type-safe environment variables, multi-environment management, and secure secret handling. It is intended for use in projects requiring configuration at build or boot time, typically passed via environment variables.

    Key capabilities include:

    • AI-Safe Config: Uses .env.schema to provide AI agents with configuration context without exposing actual secret values. Includes varlock scan to detect leaked secrets.
    • Security: Features automatic log redaction for sensitive values, leak detection in bundled code/server responses, and proactive scanning.
    • Validation & Type Safety: Provides validation with clear error messages and automatic type generation for IntelliSense.
    • Secure Secrets: Supports device-local encryption (using Secure Enclave or TPM) and provider plugins (e.g., 1Password, AWS Secrets Manager, HashiCorp Vault) or custom CLI tools via exec().
    • Multi-Environment Management: Supports environment-specific files, local overrides, and value composition.
    • Value Composition: Allows composing values using functions, references, and external data sources.
    • Framework Integrations: Official integrations for Next.js, Vite, Astro, and others, with support for any language via varlock run.
    • dotenv Replacement: Can serve as a direct replacement for dotenv with minimal code changes.

  3. Overview of @varlock/encryption-binary-swift

    main

    The @varlock/encryption-binary-swift package provides a macOS native binary for Varlock's local encryption. It is built in Swift to leverage Apple's Security, LocalAuthentication, and AppKit frameworks. This allows Varlock to use the Secure Enclave for hardware-backed key storage, support Touch ID biometric prompts, and provide native UI elements like status bar menus and secure input dialogs.

    While the encryption logic is platform-agnostic via an IPC protocol (length-prefixed JSON over a Unix socket), this Swift implementation is specifically required for macOS to ensure proper code signing, notarization, and access to hardware-level security features.

  4. Overview of env-graph

    main

    The env-graph suite of tools is designed to load environment variables (both schema and values) from multiple, heterogeneous sources. It manages the complexity of merging configuration from .env files, process/shell environment variables, and remote sources (like SaaS providers or 1Password vaults).

    Key capabilities include:

    • Multi-source merging: Combines schema info and values from various sources with specific precedence rules.
    • Cross-referencing: Allows sources to refer to each other (e.g., one .env file importing another) and individual values to reference each other via string templates or function arguments.
    • Validation and Coercion: Applies validation and type coercion to the final merged configuration.
    • Extensibility: Supports function-call style values to pull or transform data using external plugins or functions.
    • Monorepo support: Enables referencing values across different services within a monorepo.

  5. Overview of @env-spec DSL

    main

    @env-spec is a domain-specific language (DSL) that extends standard .env syntax. It allows you to attach structured metadata to environment variables using @decorator style comments (similar to JSDoc) and formalize value assignment via function calls.

    Key capabilities include:

    • Structured Metadata: Use decorators like @required, @sensitive, or @type to provide validation, coercion, and type-safety.
    • Function Calls: Use syntax like VAR=fetchSecret("key") to load values from external sources or decrypt data.
    • Schema Files: It is recommended to use a .env.schema file committed to version control to share schema information across teams, while using git-ignored .env files for actual values.
    # Stripe secret api key
# @required @sensitive @type=string(startsWith="sk_")
# @docs(https://docs.stripe.com/keys)
STRIPE_SECRET_KEY=fetchSecret("stripe/secret-key")

  6. Overview of the @varlock/kubernetes-plugin

    main

    The @varlock/kubernetes-plugin allows you to load values from Kubernetes Secrets and ConfigMaps into your Varlock environment graph using declarative instructions in your .env files.

    Key Capabilities

    • Fetch Secret keys: Use k8sSecret() to retrieve specific keys (values are automatically base64-decoded).
    • Fetch ConfigMap keys: Use k8sConfigMap() to retrieve specific keys (including binaryData).
    • Bulk-load: Use k8sSecretBulk() or k8sConfigMapBulk() to load entire resources.
    • Auto-infer keys: The plugin can automatically infer keys from your environment variable names.
    • Multiple instances: Support for different namespaces or clusters within the same configuration.

    Authentication Modes

    • Zero-config local development: Automatically uses your default kubeconfig (~/.kube/config).
    • In-cluster authentication: Automatically detects the mounted service account when running inside a Kubernetes pod.
    • Explicit auth: Allows providing a cluster API URL and bearer token directly.

    Important Limitations

    • Read-only: The plugin only performs get requests. It cannot create, update, or delete cluster resources, generate manifests, watch for changes, or manage deployments.

  7. Overview of Varlock Sandboxing Recipes

    main

    Varlock allows you to run an agent inside a third-party sandbox while Varlock maintains control of the real credentials. The sandbox hosts the agent, and the credential proxy provides placeholders, swapping in real secrets only during verified connections to allowed hosts.

    Before using these recipes, you should read the sandboxing guide to understand the relationship between the two layers, the built-in --sandbox option (which uses macOS jail or containers), and the required shared setup.

  8. IntelliSense and Autocomplete features in `@env-spec`

    main

    The extension provides advanced IntelliSense for writing @env-spec schemas within your .env files:

    • Decorators and Types: Autocomplete for common item/root decorators and built-in @type= values.
    • Type Option Completions: Context-aware suggestions for type-specific options, such as email(normalize=...), ip(version=..., normalize=...), and url(prependHttps=...).
    • Enum Value Completions: When using @type=enum(...), the allowed values are suggested directly on the item's value line.
    • Variable References: Typing $ inside values or decorator expressions suggests existing configuration keys from the current file.
    • Prefix-aware Completions: Supports prefix-related configuration scenarios while editing schema comments.

  9. Integrate Varlock into Next.js projects

    main

    Use @varlock/nextjs-integration to integrate Varlock into a Next.js project. This package acts as a drop-in replacement for @next/env and provides a plugin for your next.config.* file to enable enhanced security features.

    Key Features:

    • Validation: Validates environment variables against your .env.schema.
    • Type Safety: Provides type-generation and type-safe access to environment variables with built-in documentation.
    • Security:
      • Redacts sensitive values from application logs.
      • Detects and prevents environment variable leaks at both build and runtime.
      • Scrubs sourcemaps to prevent secrets from leaking in production.
    • Flexibility: Supports more flexible multi-environment handling, allowing you to load environment-specific files beyond the standard .env.development or .env.production.

  10. Understand Varlock environment variable namespaces

    main

    Varlock uses three distinct environment variable namespaces. It is critical to use the correct prefix to avoid configuration errors or unexpected behavior:

    • VARLOCK_* (no underscore): Computed by Varlock. These are Builtin variables (e.g., VARLOCK_ENV).
    • _VARLOCK_* (single underscore): Configuration variables set by you to control Varlock's behavior.
    • __VARLOCK_* (double underscore): Internal variables injected automatically by Varlock. Never set these yourself.

    :::caution[The _VARLOCK_ prefix is reserved] Config items whose key starts with _VARLOCK_ are reserved for Varlock. They are excluded from the injected env blob, generated types, and override provenance, even if you define them in your .env.schema. Varlock will emit a warning if you attempt to use this prefix for your own application variables. :::

  11. Available Varlock Plugins

    main

    Varlock functionality can be extended using plugins. Currently, only official plugins under the @varlock npm scope are supported. Plugins are categorized by their integration type: Password Managers, Secrets Platforms, Cloud Secret Stores, and Infrastructure.

    Password Managers

    • 1Password: @varlock/1password-plugin
    • Bitwarden: @varlock/bitwarden-plugin
    • Dashlane: @varlock/dashlane-plugin
    • Keeper: @varlock/keeper-plugin
    • KeePass: @varlock/keepass-plugin
    • Pass: @varlock/pass-plugin
    • Passbolt: @varlock/passbolt-plugin
    • Proton Pass: @varlock/proton-pass-plugin
    • macOS Keychain: Built-in (no npm package required)

    Secrets Platforms

    • Doppler: @varlock/doppler-plugin
    • Infisical: @varlock/infisical-plugin
    • HashiCorp Vault (and OpenBao): @varlock/hashicorp-vault-plugin
    • Akeyless: @varlock/akeyless-plugin

    Cloud Secret Stores

    • AWS (Secrets Manager & Parameter Store): @varlock/aws-secrets-plugin
    • Azure Key Vault: @varlock/azure-key-vault-plugin
    • GCP Secret Manager: @varlock/google-secret-manager-plugin

    Infrastructure

    • Kubernetes (Secrets & ConfigMaps): @varlock/kubernetes-plugin

  12. Understand Varlock's Next.js Runtime Protection

    main

    The integration protects secrets through several automated mechanisms:

    • Runtime Redaction: Patches console and HTTP responses to prevent sensitive values from leaking.
    • Init Bundle Injection: Injects initialization code into runtime files (like webpack-runtime.js or Turbopack's runtime files) to ensure environment loading and patching occur before user code executes.
    • Per-File Init Guards: Injects a guarded snippet into server-side files to ensure initialization runs even in pre-rendering workers via IPC.
    • Post-Build Leak Scanning: Scans static chunks and prerendered HTML for leaked secrets. If a leak is detected, the file is overwritten with a redacted version and the build fails.
    • Sourcemap Scrubbing: Replaces sensitive values in .map files with same-length * strings to preserve column offsets while preventing leaks.