bws-secure

# BWS Secure Environment Manager A secure environment variable manager for Vercel and Netlify deployments using Bitwarden Secrets Manager, now available as an npm package. ## Installation ```bash npm install bws-secure # or yarn add bws-secure # or pnpm add bws-secure ``` ## First-Time Setup ### 1. Create a Bitwarden Secrets Manager Account and Get Your Access Token First, you'll need to create a Bitwarden Secrets Manager account and obtain your access token: 1. Sign up or log in to your Bitwarden account 2. Navigate to the Secrets Manager section 3. Create a new project (or use an existing one) 4. Generate an access token with appropriate permissions 5. Save your BWS_ACCESS_TOKEN securely ### 2. Add BWS Access Token to Your Environment Add your BWS access token to your `.env` file: ```bash BWS_ACCESS_TOKEN=your_token_here ``` > **Security Best Practice**: For improved security, attach your BWS_ACCESS_TOKEN to a machine account in your CI/CD system rather than storing it directly in project files or within the project configuration in Bitwarden. This isolates the token to the execution environment and prevents it from being exposed in your codebase or project settings. ### 3. Initialize Your Project (First-Time Setup) Run the setup command to initialize your project with BWS Secure: ```bash npx bws-setup ``` This will guide you through creating a `bwsconfig.json` file and configuring your project. ## Configuration ### bwsconfig.json Create or update `bwsconfig.json` in your project root: ```json { "projects": [ { "platform": "vercel", // or "netlify" "projectName": "your-project-name", "bwsProjectIds": { "prod": "your-prod-project-id", "dev": "your-dev-project-id", "local": "your-local-project-id" }, "preserveVars": ["BWS_ACCESS_TOKEN"], "excludeVars": ["NODE_ENV", "VERCEL_URL", "VERCEL_ENV", "DEPLOY_URL"] } ] } ``` ### Platform Configuration #### Vercel For Vercel projects, add your Vercel auth token to your `.env` file: ```bash VERCEL_AUTH_TOKEN=your_token_here ``` #### Netlify For Netlify projects, add your Netlify auth token to your `.env` file: ```bash NETLIFY_AUTH_TOKEN=your_token_here ``` > **Security Best Practice**: For maximum security, attach platform auth tokens (Vercel/Netlify) to your machine account in your CI/CD system rather than storing them directly in project files or within the project's bwsProjectIds configuration. This approach isolates sensitive credentials to the deployment environment and prevents them from being exposed in your codebase or project configuration. ## Usage ### Update Your Build Scripts Update your `package.json` build scripts to use the secure runner: ```json { "scripts": { "dev": "secure-run -- next dev", "build": "secure-run -- turbo build", "start": "secure-run -- next start" } } ``` ### Uploading Secrets to Bitwarden You can upload environment variables directly to your Bitwarden Secrets Manager projects: 1. **Create environment files with the correct naming convention**: ``` .env.bws.<project-id> ``` For example: `.env.bws.12345678-1234-1234-1234-123456789abc` The project ID must be a valid UUID that matches your Bitwarden project. 2. **Add your environment variables** to these files in standard `.env` format: ``` API_KEY=your_api_key_value DATABASE_URL=your_database_url ``` 3. **Upload secrets to Bitwarden** using the upload command: ```bash # Upload secrets while preserving existing secrets in Bitwarden npx bws-upload # or npx secure-run --upload-secrets # Clear existing secrets before uploading (recommended for complete replacement) npx secure-run --upload-secrets --clear-vars ``` The `--clear-vars` flag removes all existing secrets in the project before uploading, ensuring a clean state and preventing orphaned variables. > **Note**: Sensitive variables like `BWS_ACCESS_TOKEN` are automatically excluded from upload to prevent security issues. ### Manually Updating Platform Projects Locally If you need to update your Vercel or Netlify projects manually in your local environment: 1. Ensure your `bwsconfig.json` is properly configured with your project details 2. Make sure you have the correct auth tokens available in your environment: - `VERCEL_AUTH_TOKEN` for Vercel projects - `NETLIFY_AUTH_TOKEN` for Netlify projects 3. Set the appropriate platform flag when running the secure command: ```bash # For Vercel projects vercel=1 npx secure-run -- your-command # For Netlify projects netlify=true npx secure-run -- your-command ``` This will execute your command with the appropriate platform environment configured, allowing you to test platform-specific configurations locally before deployment. ### Available CLI Commands ```bash # Run a command with secrets loaded from Bitwarden npx secure-run <your-command> # List available projects npx bws-list # Upload secrets to Bitwarden Secrets Manager npx bws-upload # Scan for required environment variables npx bws-secure scan ``` ## Troubleshooting ### Environment Variables Not Being Detected If your environment variables are not appearing in scans: 1. **Check Path Configuration**: By default, BWS Secure scans these paths for environment variables: - `functions` - `api` - `apps/web/src` - `packages` 2. **Custom Scanning Paths**: You can specify custom paths to scan in several ways: a. **Command Line**: Specify paths when running the scan ```bash npx bws-secure scan "src,pages,components,your-custom-path" ``` b. **Add Path Patterns**: You can use glob patterns for more specific scanning ```bash npx bws-secure scan "my-next-app/**/*.js" ``` 3. **Using Turbo Config**: If you're using Turborepo, you can specify environment variables in your `turbo.json` file: ```json { "globalEnv": ["API_URL", "DATABASE_URL", "OTHER_ENV_VAR"], "tasks": { "build": { "env": ["BUILD_VAR1", "BUILD_VAR2"] } } } ``` 4. **Exclude from .gitignore**: If you want to track your scanned variables in your repository, remove `requiredVars.env` from your `.gitignore` file. ## Features - **Secure Secret Management:** Uses Bitwarden Secrets Manager for storing sensitive data - **Platform Integration:** Built-in support for Vercel and Netlify - **Environment Management:** Handles different environments (production, development, local) - **Automatic Variable Scanning:** Detects required environment variables in your codebase - **Debug Mode:** Helps troubleshoot environment variable issues ## Requirements - Node.js (no version constraints) - Bitwarden Secrets Manager account and access token - Vercel or Netlify account (if using those platforms) ## License MIT ## Links For complete documentation, visit: [GitHub Repository](https://github.com/last-rev-llc/bws-secure)