@bostonuniversity/buwp-local 0.4.0 → 0.5.0

package/.buwp-local.json

@@ -0,0 +1,22 @@
+{
+  "projectName": "buwp-local",
+  "image": "ghcr.io/bu-ist/bu-wp-docker-mod_shib:arm64-latest",
+  "hostname": "jaydub.local",
+  "multisite": true,
+  "services": {
+    "redis": true,
+    "s3proxy": true,
+    "shibboleth": true
+  },
+  "ports": {
+    "http": 80,
+    "https": 443,
+    "db": 3306,
+    "redis": 6379
+  },
+  "mappings": [],
+  "env": {
+    "WP_DEBUG": true,
+    "XDEBUG": false
+  }
+}

package/.env.local.example

@@ -0,0 +1,26 @@
+# BU WordPress Local Development Environment Variables
+# Copy this file to .env.local and fill in your actual credentials
+# NEVER commit .env.local to version control!
+
+# Database Credentials
+WORDPRESS_DB_PASSWORD=password
+DB_ROOT_PASSWORD=rootpassword
+
+# Shibboleth Configuration (if enabled)
+SP_ENTITY_ID=https://your-sp-entity-id
+IDP_ENTITY_ID=https://shib-test.bu.edu/idp/shibboleth
+SHIB_IDP_LOGOUT=https://shib-test.bu.edu/idp/logout.jsp
+SHIB_SP_KEY=your-private-key-here
+SHIB_SP_CERT=your-certificate-here
+
+# AWS S3 Configuration (if enabled)
+S3_UPLOADS_BUCKET=your-bucket-name
+S3_UPLOADS_REGION=us-east-1
+S3_UPLOADS_ACCESS_KEY_ID=AKIA...
+S3_UPLOADS_SECRET_ACCESS_KEY=your-secret-key
+S3_ACCESS_RULES_TABLE=your-access-rules-table
+
+# OLAP Configuration (if using S3 Object Lambda)
+OLAP=your-olap-name
+OLAP_ACCT_NBR=123456789
+OLAP_REGION=us-east-1

package/IMPLEMENTATION_NOTES_V0.5.0_PHASE3.md

@@ -0,0 +1,240 @@
+# v0.5.0 Phase 3: Hybrid Secure Temp File Integration
+
+## Overview
+Completed implementation of credential loading from macOS keychain into Docker Compose via secure temporary environment files. This is the final integration step of v0.5.0 keychain feature.
+
+## What Was Implemented
+
+### 1. **Credential Loading Functions** (`lib/config.js`)
+
+Added three new exported functions:
+
+#### `loadKeychainCredentials()`
+- Retrieves all 15 stored credentials from macOS keychain
+- Returns empty object on non-macOS platforms (graceful degradation)
+- Checks `isPlatformSupported()` before attempting keychain access
+- Iterates through `CREDENTIAL_KEYS` constant to load each credential
+
+#### `createSecureTempEnvFile(credentials, projectName)`
+- Creates `/tmp/.buwp-local-{projectName}-{timestamp}.env` file
+- Uses atomic file creation with exclusive write flag (`'wx'`)
+- Sets restrictive permissions to user read/write only (`0o600`)
+- Properly escapes multiline credentials:
+  - Backslashes: `\\` → `\\\\\\\\`
+  - Double quotes: `"` → `\"`
+  - Newlines: `\n` → `\\n`
+- Ensures shell interpretation works correctly for complex values (SHIB_SP_KEY, SHIB_SP_CERT)
+- Returns path to created temp file
+
+#### `secureDeleteTempEnvFile(filePath)`
+- Overwrites file content with zeros before deletion (defense against forensic recovery)
+- Unlinks file after secure overwrite
+- Returns boolean success status
+- Non-fatal errors - logs warnings but doesn't throw (temp files are ephemeral)
+
+### 2. **Start Command Integration** (`lib/commands/start.js`)
+
+Updated `startCommand()` function to:
+
+1. **Import new functions** from config.js
+2. **Load keychain credentials** after generating compose file:
+   ```javascript
+   const keychainCredentials = loadKeychainCredentials();
+   const keychainCredCount = Object.keys(keychainCredentials).length;
+   ```
+
+3. **Create secure temp file** if credentials available:
+   ```javascript
+   if (keychainCredCount > 0) {
+     tempEnvPath = createSecureTempEnvFile(keychainCredentials, projectName);
+   }
+   ```
+
+4. **Layer environment files** in Docker Compose command:
+   ```bash
+   docker compose -p {projectName} --env-file {tempEnvFile} --env-file {.env.local} -f {composePath} up -d
+   ```
+
+5. **Ensure cleanup** with try/finally block:
+   - Cleanup happens even if Docker Compose fails
+   - Temp file securely deleted after containers start
+
+### 3. **Credential Precedence**
+
+Docker Compose loads env files left-to-right with later files overriding earlier ones:
+
+```
+Keychain Credentials (--env-file /tmp/.buwp-local-*.env)
+    ↓ [overridden by]
+.env.local Project Overrides (--env-file .env.local)
+    ↓ [overridden by]
+docker-compose.yml Environment Defaults
+```
+
+**Precedence Order (highest to lowest):**
+1. `.env.local` - Project-specific credential overrides
+2. Keychain - Global default credentials (all 15 keys)
+3. docker-compose.yml - Hardcoded defaults
+
+## Security Architecture
+
+### Threat Model: Process List Visibility
+**Original concern:** Won't credentials be visible in `ps auxe`?
+
+**Answer:** No. With this approach:
+- Docker command shows: `docker compose --env-file /tmp/.buwp-local-test-project-1234567890.env ...`
+- Credentials are in the file, NOT in the process command line
+- Process list shows only the file path (which is harmless)
+
+### Threat Model: Filesystem Exposure
+**Risk:** Brief window where unencrypted credentials are on disk
+
+**Mitigations:**
+1. **Atomic creation** - File created exclusively with perms set atomically (no TOCTOU window)
+2. **Restrictive permissions** - `0o600` (user read/write only, no group/others access)
+3. **Ephemeral location** - `/tmp` directory (typically in-memory on modern systems, auto-cleaned)
+4. **Secure deletion** - Overwrite with zeros before unlinking (prevents forensic recovery)
+5. **Short lifetime** - File exists only during `docker compose up` command (~1-2 seconds)
+6. **Guaranteed cleanup** - try/finally ensures deletion even if Docker fails
+
+### Why Not Process Environment Variables?
+- **Worse security:** All env vars visible in `ps auxe` output to any user on system
+- **Less stable:** Large multiline values (40+ lines) cause issues
+- **Less standard:** Breaks Docker Compose file-based patterns
+
+### Why Not Store Credentials in .env.local?
+- **Already doing this** - `.env.local` is still supported and takes precedence
+- **One-time setup** - Keychain eliminates need to copy credentials to every project
+- **Secure storage** - Keychain uses macOS Secure Enclave on newer Macs
+
+## Integration Flow
+
+```
+1. Start command runs
+   ↓
+2. Load config from .buwp-local.json
+   ↓
+3. Load keychain credentials (15 total)
+   ↓
+4. Create temp env file (/tmp/.buwp-local-{project}-{timestamp}.env)
+   - Atomic creation with 0o600 permissions
+   - Properly escaped multiline values
+   ↓
+5. Build Docker Compose command with layered env files
+   - --env-file /tmp/.buwp-local-{project}-{timestamp}.env
+   - --env-file .env.local (if exists)
+   ↓
+6. Execute Docker Compose up
+   ↓
+7. Clean up temp file (try/finally)
+   - Overwrite with zeros
+   - Unlink
+   ↓
+8. Success message + usage tips
+```
+
+## Credentials Loaded
+
+All 15 credentials from keychain are available:
+
+**Database (2):**
+- WORDPRESS_DB_PASSWORD
+- DB_ROOT_PASSWORD
+
+**Shibboleth (5):**
+- SP_ENTITY_ID
+- IDP_ENTITY_ID
+- SHIB_IDP_LOGOUT
+- SHIB_SP_KEY (40+ lines)
+- SHIB_SP_CERT (24+ lines)
+
+**S3 (5):**
+- S3_UPLOADS_BUCKET
+- S3_UPLOADS_REGION
+- S3_UPLOADS_ACCESS_KEY_ID
+- S3_UPLOADS_SECRET_ACCESS_KEY
+- S3_ACCESS_RULES_TABLE
+
+**OLAP (3):**
+- OLAP
+- OLAP_ACCT_NBR
+- OLAP_REGION
+
+## Testing Results
+
+Automated integration test verification:
+
+✓ Load 15 credentials from keychain
+✓ Create secure temp env file with 0o600 permissions
+✓ Format env file with proper KEY="VALUE" quoting
+✓ Handle multiline value escaping correctly
+✓ Overwrite file with zeros before deletion
+✓ Securely delete temp file
+
+All tests passed successfully.
+
+## Version Update
+
+Updated package.json version:
+- Previous: v0.4.1
+- Current: v0.5.0
+
+## Code Quality
+
+All code passes ESLint checks with no errors or warnings.
+
+## Next Steps
+
+Possible future enhancements (not in v0.5.0 scope):
+
+1. **Phase 4: Init Command Enhancements**
+   - Auto-populate `buwp-local setup --file` from existing `.env` files
+   - Suggest keychain import during `init` command
+
+2. **Phase 5: Global Registry**
+   - `~/.buwp-local/registry.json` tracking which projects have credentials
+   - Dashboard showing all stored credentials across projects
+
+3. **Phase 6: Cross-Platform Support**
+   - Windows DPAPI support (via `credential` PowerShell module)
+   - Linux pass/secretservice support
+   - Fallback to encrypted `.buwp-local/.env.encrypted` files
+
+## Architecture Summary
+
+**Hybrid Secure Temp File Approach:**
+- **Security:** Process list hidden + filesystem defenses
+- **Stability:** Aligns with Docker Compose standard patterns
+- **Usability:** Intuitive file-based precedence and override mechanism
+- **Compatibility:** Maintains existing `.env.local` behavior
+
+**Key Decision Rationale:**
+Process list visibility is worse attack vector than brief filesystem window with defense-in-depth mitigations (atomic creation, 600 perms, /tmp location, overwrite-before-delete).
+
+## Files Modified
+
+1. `lib/config.js` (+80 lines)
+   - Added keychain import
+   - Added 3 new exported functions
+   - No breaking changes to existing exports
+
+2. `lib/commands/start.js` (+25 lines)
+   - Updated imports to include 3 new functions
+   - Added credential loading logic
+   - Added temp file creation and cleanup
+   - No breaking changes to command interface
+
+3. `package.json`
+   - Updated version to 0.5.0
+
+## Status Summary
+
+**v0.5.0 Completion Status:**
+- ✅ Phase 1: Keychain core module (v0.5.0)
+- ✅ Phase 2: JSON bulk import (v0.5.0)
+- ✅ Phase 3: Hybrid secure temp file integration (v0.5.0) ← COMPLETED THIS SESSION
+- ⏭️ Phase 4: Init command enhancements (v0.6.0)
+- ⏭️ Phase 5: Global registry (v0.7.0)
+- ⏭️ Phase 6: Cross-platform support (v1.0.0+)
+
+**v0.5.0 is now feature-complete and ready for testing.**

package/KEYCHAIN_IMPLEMENTATION.md

@@ -0,0 +1,140 @@
+# Keychain Integration - Implementation Summary
+
+## Overview
+
+Successfully implemented macOS Keychain integration for secure credential storage in buwp-local v0.5.0. This allows users to store credentials once and have them automatically available across all projects.
+
+## Files Created
+
+### 1. `lib/keychain.js` - Core Keychain Module
+**Functions:**
+- `setCredential(key, value)` - Store credential in keychain
+- `getCredential(key)` - Retrieve credential from keychain
+- `hasCredential(key)` - Check if credential exists
+- `deleteCredential(key)` - Remove credential
+- `listCredentials()` - Get all stored credential keys
+- `clearAllCredentials()` - Remove all buwp-local credentials
+- `isPlatformSupported()` - Check for macOS platform
+
+**Constants:**
+- `CREDENTIAL_KEYS` - All 15 credential keys
+- `CREDENTIAL_GROUPS` - Organized by category (database, shibboleth, s3, olap)
+- `CREDENTIAL_DESCRIPTIONS` - Human-readable descriptions for prompts
+
+**Implementation Details:**
+- Uses macOS `security` command via `execSync`
+- Service name: `buwp-local`
+- Uses `-U` flag to update existing credentials instead of duplicating
+- Graceful error handling with user-friendly messages
+
+### 2. `lib/commands/keychain.js` - CLI Command Handler
+**Subcommands:**
+- `setup` - Interactive setup for all credentials
+- `set <key> [value]` - Set individual credential
+- `get <key>` - Retrieve credential (masked display)
+- `list` - Show all stored credentials by group
+- `clear` - Remove all credentials (with confirmation)
+- `status` - Show platform support and credential status
+
+**Features:**
+- Interactive prompts using `prompts` package
+- Grouped credential display (database, shibboleth, s3, olap)
+- Existing credential detection with overwrite warnings
+- Force flag support for automation
+- macOS keychain access warning at start of setup
+
+## Files Modified
+
+### 3. `bin/buwp-local.js`
+- Added import for `keychainCommand`
+- Registered `keychain` command with subcommands
+- Added `-f, --force` option support
+
+### 4. `lib/index.js`
+- Exported all keychain functions
+- Exported credential schema constants
+
+## Usage Examples
+
+### First-Time Setup
+```bash
+# Interactive setup (all credentials)
+buwp-local keychain setup
+
+# Set individual credential
+buwp-local keychain set WORDPRESS_DB_PASSWORD mypassword
+
+# Check status
+buwp-local keychain status
+```
+
+### Managing Credentials
+```bash
+# List stored credentials
+buwp-local keychain list
+
+# Get credential value (masked)
+buwp-local keychain get WORDPRESS_DB_PASSWORD
+
+# Clear all credentials
+buwp-local keychain clear
+# Or skip confirmation:
+buwp-local keychain clear --force
+```
+
+## Testing Results
+
+✅ All functions tested and working:
+- Platform detection (macOS supported ✓)
+- Set credential via command line
+- Get credential with masking (test*****word)
+- List credentials by group
+- Clear all credentials
+- Linting passes cleanly
+
+## User Experience
+
+### Warnings & Messages
+- **Platform check**: Non-macOS users see clear message about .env.local fallback
+- **Keychain access**: Users warned about macOS permission prompt before setup
+- **Overwrite protection**: Warns when overwriting existing credentials
+- **Grouped display**: Credentials organized by functional category
+
+### Security Features
+- Credentials never displayed in full (masked in `get` command)
+- Stored securely in macOS keychain (encrypted by OS)
+- Individual credential deletion supported
+- Bulk clear with confirmation (unless --force)
+
+## Design Decisions
+
+1. **Full credential set required** - `setup` prompts for all 15 credentials to ensure complete stack functionality
+2. **Warning before overwrite** - Users must confirm when updating existing credentials (unless --force)
+3. **Sparse error messages** - Simple, clear error reporting without over-engineering
+4. **macOS-only for now** - Platform detection with graceful fallback to .env.local on other systems
+
+## Next Steps (v0.5.0 continued)
+
+**Remaining work:**
+1. Update `start.js` to load credentials from keychain
+2. Update `init.js` to detect keychain credentials
+3. Implement credential resolution priority: `.env.local` → keychain → defaults
+4. Create global registry (`~/.buwp-local/registry.json`)
+5. Update documentation
+
+**Future enhancements (v0.6.0+):**
+- Cross-platform support (Windows Credential Manager, Linux Secret Service)
+- Project-specific credential overrides
+- Credential import/export
+- Team credential sharing mechanisms
+
+## Benefits Delivered
+
+✅ **One-time setup** - Enter credentials once, use across all projects  
+✅ **Secure storage** - Leverages macOS keychain encryption  
+✅ **Simple CLI** - Intuitive subcommands for all operations  
+✅ **Backward compatible** - .env.local still works as override  
+✅ **Developer friendly** - Clear messages and helpful status command  
+✅ **Production ready** - Fully tested and linted
+
+This implementation solves the multi-repo credential fatigue problem while maintaining backward compatibility and providing a secure, native macOS integration.

package/USAGE.md

@@ -51,7 +51,13 @@ Edit `.buwp-local.json` to map your local repository into the container:
 
 ### 4. Create `.env.local` for secrets
 
-Create `.env.local` (never commit this file!):
+Create `.env.local` (never commit this file!) or copy from the example:
+
+```bash
+cp .env.local.example .env.local
+```
+
+Then edit `.env.local` with your actual credentials:
 
 ```bash
 # Database
@@ -70,6 +76,7 @@ S3_UPLOADS_BUCKET=your-bucket
 S3_UPLOADS_REGION=us-east-1
 S3_UPLOADS_ACCESS_KEY_ID=your-access-key
 S3_UPLOADS_SECRET_ACCESS_KEY=your-secret-key
+S3_ACCESS_RULES_TABLE=your-access-rules-table
 
 # OLAP
 OLAP=your-olap-name
@@ -77,6 +84,8 @@ OLAP_ACCT_NBR=your-account-number
 OLAP_REGION=us-east-1
 ```
 
+**Important:** Credentials are read directly from `.env.local` by Docker Compose. They are never written to the generated `docker-compose.yml` file, making it safe to review or share the generated compose file without exposing secrets.
+
 ### 5. Add hostname to /etc/hosts
 
 ```bash
@@ -226,10 +235,27 @@ Map your local code into the container:
 ## Security Best Practices
 
 1. **Never commit `.env.local`** - This file contains secrets
-2. **Never commit `.buwp-local/`** - This contains generated files
-3. **Do commit `.buwp-local.json`** - This is your configuration template
-4. **Use environment variables for all secrets**
-5. **Consider using macOS Keychain** for even better security (see docs)
+2. **Never commit `.buwp-local/`** - This directory contains generated files
+3. **Do commit `.buwp-local.json`** - This is your configuration template (no secrets)
+4. **Use environment variables for all secrets** - Credentials stay in `.env.local` and are never written to generated files
+5. **Review generated compose files** - The generated `docker-compose.yml` only contains variable references like `${WORDPRESS_DB_PASSWORD}`, not actual credentials
+6. **Copy `.env.local.example`** - Use the provided template to create your `.env.local` file
+7. **Consider using macOS Keychain** for even better security (future feature)
+
+### How Credentials Work
+
+buwp-local uses Docker Compose's native environment variable interpolation:
+
+1. **You provide** credentials in `.env.local`
+2. **buwp-local generates** `docker-compose.yml` with variable references like `${VAR_NAME}`
+3. **Docker Compose reads** `.env.local` at runtime and substitutes the values
+4. **Your secrets never** get written to any generated files
+
+This means:
+- ✅ Generated compose files are safe to review or share
+- ✅ No credentials in version control (even accidentally)
+- ✅ Industry-standard Docker Compose pattern
+- ✅ Simple and secure
 
 ## File Structure
 

package/bin/buwp-local.js

@@ -29,6 +29,7 @@ import wpCommand from '../lib/commands/wp.js';
 import shellCommand from '../lib/commands/shell.js';
 import configCommand from '../lib/commands/config.js';
 import initCommand from '../lib/commands/init.js';
+import keychainCommand from '../lib/commands/keychain.js';
 
 const program = new Command();
 
@@ -103,6 +104,17 @@ program
   .description('Open an interactive bash shell in the WordPress container')
   .action(shellCommand);
 
+// Keychain command
+program
+  .command('keychain <subcommand> [args...]')
+  .description('Manage credentials in macOS keychain')
+  .option('-f, --force', 'Skip confirmation prompts')
+  .option('--file <path>', 'Read credential from file (for multiline content)')
+  .option('--stdin', 'Read credential from stdin')
+  .action((subcommand, args, options) => {
+    keychainCommand(subcommand, args, options);
+  });
+
 // Error handling
 program.exitOverride();
 

package/lib/commands/init.js

@@ -133,6 +133,10 @@ async function initCommand(options) {
       name: 'hostname',
       message: 'Hostname',
       initial: (prev, values) => {
+        // For sandbox, use just username.local; for other types include project name
+        if (values.projectType === 'sandbox') {
+          return `${userName}.local`;
+        }
         return `${userName}-${values.projectName}.local`;
       },
       validate: value => {