@bostonuniversity/buwp-local 0.4.0 → 0.5.0

package/lib/compose-generator.js

@@ -57,9 +57,6 @@ function generateComposeConfig(config) {
  * @returns {object} Database service config
  */
 function generateDbService(config, dbVolumeName) {
-  const dbPassword = config.db?.password || 'password';
-  const rootPassword = config.db?.rootPassword || 'rootpassword';
-
   return {
     image: 'mariadb:latest',
     restart: 'always',
@@ -67,8 +64,8 @@ function generateDbService(config, dbVolumeName) {
     environment: {
       MYSQL_DATABASE: 'wordpress',
       MYSQL_USER: 'wordpress',
-      MYSQL_PASSWORD: dbPassword,
-      MYSQL_ROOT_PASSWORD: rootPassword
+      MYSQL_PASSWORD: '${WORDPRESS_DB_PASSWORD:-password}',
+      MYSQL_ROOT_PASSWORD: '${DB_ROOT_PASSWORD:-rootpassword}'
     },
     ports: [`${config.ports.db}:3306`],
     networks: ['wp-network']
@@ -91,7 +88,7 @@ function generateWordPressService(config, wpVolumeName) {
   const environment = {
     WORDPRESS_DB_HOST: 'db:3306',
     WORDPRESS_DB_USER: 'wordpress',
-    WORDPRESS_DB_PASSWORD: config.db?.password || 'password',
+    WORDPRESS_DB_PASSWORD: '${WORDPRESS_DB_PASSWORD:-password}',
     WORDPRESS_DB_NAME: 'wordpress',
     WORDPRESS_DEBUG: config.env?.WP_DEBUG || '0',
     SERVER_NAME: config.hostname,
@@ -104,11 +101,11 @@ function generateWordPressService(config, wpVolumeName) {
 
   // Add Shibboleth config if enabled
   if (config.services.shibboleth) {
-    environment.SP_ENTITY_ID = config.shibboleth?.entityId || '';
-    environment.IDP_ENTITY_ID = config.shibboleth?.idpEntityId || '';
-    environment.SHIB_IDP_LOGOUT = config.shibboleth?.idpLogout || '';
-    environment.SHIB_SP_KEY = config.shibboleth?.spKey || '';
-    environment.SHIB_SP_CERT = config.shibboleth?.spCert || '';
+    environment.SP_ENTITY_ID = '${SP_ENTITY_ID:-}';
+    environment.IDP_ENTITY_ID = '${IDP_ENTITY_ID:-}';
+    environment.SHIB_IDP_LOGOUT = '${SHIB_IDP_LOGOUT:-}';
+    environment.SHIB_SP_KEY = '${SHIB_SP_KEY:-}';
+    environment.SHIB_SP_CERT = '${SHIB_SP_CERT:-}';
   }
 
   // Add S3 config if enabled
@@ -130,12 +127,12 @@ function generateWordPressService(config, wpVolumeName) {
     wpConfigExtra += "define('SUBDOMAIN_INSTALL', false);\n";
   }
 
-  if (config.services.s3proxy && config.s3) {
-    wpConfigExtra += `define('S3_UPLOADS_BUCKET', '${config.s3.bucket || ''}');\n`;
-    wpConfigExtra += `define('S3_UPLOADS_REGION', '${config.s3.region || 'us-east-1'}');\n`;
-    wpConfigExtra += `define('S3_UPLOADS_KEY', '${config.s3.accessKeyId || ''}');\n`;
-    wpConfigExtra += `define('S3_UPLOADS_SECRET', '${config.s3.secretAccessKey || ''}');\n`;
-    wpConfigExtra += `define('ACCESS_RULES_TABLE', '${config.s3.accessRulesTable || ''}');\n`;
+  if (config.services.s3proxy) {
+    wpConfigExtra += "define('S3_UPLOADS_BUCKET', '${S3_UPLOADS_BUCKET}');\n";
+    wpConfigExtra += "define('S3_UPLOADS_REGION', '${S3_UPLOADS_REGION:-us-east-1}');\n";
+    wpConfigExtra += "define('S3_UPLOADS_KEY', '${S3_UPLOADS_ACCESS_KEY_ID}');\n";
+    wpConfigExtra += "define('S3_UPLOADS_SECRET', '${S3_UPLOADS_SECRET_ACCESS_KEY}');\n";
+    wpConfigExtra += "define('ACCESS_RULES_TABLE', '${S3_ACCESS_RULES_TABLE}');\n";
     wpConfigExtra += "define('S3_UPLOADS_OBJECT_ACL', null);\n";
     wpConfigExtra += "define('S3_UPLOADS_AUTOENABLE', true);\n";
     wpConfigExtra += "define('S3_UPLOADS_DISABLE_REPLACE_UPLOAD_URL', true);\n";
@@ -183,14 +180,10 @@ function generateWordPressService(config, wpVolumeName) {
 
 /**
  * Generate S3 proxy service configuration
- * @param {object} config - buwp-local configuration
+ * @param {object} _config - buwp-local configuration (unused - env vars used instead)
  * @returns {object} S3 proxy service config
  */
-function generateS3ProxyService(config) {
-  const region = config.olap?.region || config.s3?.region || 'us-east-1';
-  const olapName = config.olap?.name || '';
-  const olapAcctNbr = config.olap?.accountNumber || '';
-
+function generateS3ProxyService(_config) {
   return {
     image: 'public.ecr.aws/bostonuniversity-nonprod/aws-sigv4-proxy',
     restart: 'always',
@@ -199,16 +192,16 @@ function generateS3ProxyService(config) {
       '--name',
       's3-object-lambda',
       '--region',
-      region,
+      '${OLAP_REGION:-us-east-1}',
       '--no-verify-ssl',
       '--host',
-      `${olapName}-${olapAcctNbr}.s3-object-lambda.${region}.amazonaws.com`
+      '${OLAP}-${OLAP_ACCT_NBR}.s3-object-lambda.${OLAP_REGION:-us-east-1}.amazonaws.com'
     ],
     environment: {
       healthcheck_path: '/s3proxy-healthcheck',
-      AWS_ACCESS_KEY_ID: config.s3?.accessKeyId || '',
-      AWS_SECRET_ACCESS_KEY: config.s3?.secretAccessKey || '',
-      REGION: region
+      AWS_ACCESS_KEY_ID: '${S3_UPLOADS_ACCESS_KEY_ID}',
+      AWS_SECRET_ACCESS_KEY: '${S3_UPLOADS_SECRET_ACCESS_KEY}',
+      REGION: '${S3_UPLOADS_REGION:-us-east-1}'
     },
     networks: ['wp-network']
   };

package/lib/config.js

@@ -7,6 +7,7 @@ import fs from 'fs';
 import path from 'path';
 import chalk from 'chalk';
 import dotenv from 'dotenv';
+import * as keychain from './keychain.js';
 
 const CONFIG_FILE_NAME = '.buwp-local.json';
 const ENV_FILE_NAME = '.env.local';
@@ -283,6 +284,96 @@ function sanitizeProjectName(name) {
     .replace(/^-+|-+$/g, ''); // Remove leading/trailing dashes
 }
 
+/**
+ * Load credentials from macOS keychain
+ * Returns all 15 credentials if available, with platform and keychain support checks
+ * @returns {object} Credentials object or empty object if not supported
+ */
+export function loadKeychainCredentials() {
+  // Only load on macOS where keychain is supported
+  if (!keychain.isPlatformSupported()) {
+    return {};
+  }
+
+  const credentials = {};
+  
+  // Try to load each known credential from keychain
+  for (const key of keychain.CREDENTIAL_KEYS) {
+    const value = keychain.getCredential(key);
+    if (value !== null) {
+      credentials[key] = value;
+    }
+  }
+  
+  return credentials;
+}
+
+/**
+ * Create a secure temporary .env file from credentials
+ * File is created with restrictive permissions (600) in /tmp
+ * @param {object} credentials - Credential key-value pairs
+ * @param {string} projectName - Project name for unique filename
+ * @returns {string} Path to created temp file
+ */
+export function createSecureTempEnvFile(credentials, projectName) {
+  const timestamp = Date.now();
+  const tempPath = path.join('/tmp', `.buwp-local-${projectName}-${timestamp}.env`);
+  
+  // Build env file content with proper escaping for multiline values
+  const lines = Object.entries(credentials).map(([key, value]) => {
+    // Escape special characters in values
+    const escaped = String(value)
+      .replace(/\\\\/g, '\\\\\\\\')  // Escape backslashes first
+      .replace(/"/g, '\\"')      // Escape double quotes
+      .replace(/\\n/g, '\\\\n');   // Escape newlines for shell
+    
+    return `${key}="${escaped}"`;
+  });
+  
+  const content = lines.join('\n') + '\n';
+  
+  try {
+    // Atomic create with strict permissions: user read/write only (600)
+    // 'wx' means create exclusive (fail if exists) and writable
+    const fd = fs.openSync(tempPath, 'wx', 0o600);
+    fs.writeSync(fd, content);
+    fs.closeSync(fd);
+    
+    return tempPath;
+  } catch (err) {
+    throw new Error(`Failed to create secure temp env file: ${err.message}`);
+  }
+}
+
+/**
+ * Securely delete a temporary env file
+ * Overwrites file contents with zeros before deletion to prevent recovery
+ * @param {string} filePath - Path to temp file to delete
+ * @returns {boolean} True if deleted successfully, false if error (non-fatal)
+ */
+export function secureDeleteTempEnvFile(filePath) {
+  try {
+    // Check if file exists
+    if (!fs.existsSync(filePath)) {
+      return true; // Already gone, consider success
+    }
+    
+    // Get file size and overwrite with zeros (secure deletion)
+    const stat = fs.statSync(filePath);
+    const fd = fs.openSync(filePath, 'r+');
+    fs.writeSync(fd, Buffer.alloc(stat.size, 0));
+    fs.closeSync(fd);
+    
+    // Now delete the file
+    fs.unlinkSync(filePath);
+    return true;
+  } catch (err) {
+    // Log warning but don't fail - temp files are ephemeral anyway
+    console.warn(chalk.yellow(`⚠️  Warning: Could not securely delete temp file ${filePath}: ${err.message}`));
+    return false;
+  }
+}
+
 export {
   loadConfig,
   validateConfig,

package/lib/index.js

@@ -5,6 +5,7 @@
 
 import * as config from './config.js';
 import * as composeGenerator from './compose-generator.js';
+import * as keychain from './keychain.js';
 
 export const loadConfig = config.loadConfig;
 export const validateConfig = config.validateConfig;
@@ -14,3 +15,17 @@ export const generateComposeFile = composeGenerator.generateComposeFile;
 export const CONFIG_FILE_NAME = config.CONFIG_FILE_NAME;
 export const ENV_FILE_NAME = config.ENV_FILE_NAME;
 export const DEFAULT_CONFIG = config.DEFAULT_CONFIG;
+
+// Keychain exports
+export const setCredential = keychain.setCredential;
+export const getCredential = keychain.getCredential;
+export const hasCredential = keychain.hasCredential;
+export const listCredentials = keychain.listCredentials;
+export const clearAllCredentials = keychain.clearAllCredentials;
+export const isPlatformSupported = keychain.isPlatformSupported;
+export const isMultilineCredential = keychain.isMultilineCredential;
+export const parseCredentialsFile = keychain.parseCredentialsFile;
+export const CREDENTIAL_KEYS = keychain.CREDENTIAL_KEYS;
+export const CREDENTIAL_GROUPS = keychain.CREDENTIAL_GROUPS;
+export const CREDENTIAL_DESCRIPTIONS = keychain.CREDENTIAL_DESCRIPTIONS;
+export const MULTILINE_CREDENTIALS = keychain.MULTILINE_CREDENTIALS;

package/lib/keychain.js

@@ -0,0 +1,339 @@
+/**
+ * macOS Keychain integration for secure credential storage
+ * Uses the `security` command-line tool to interact with macOS Keychain
+ */
+
+import { execSync } from 'child_process';
+import fs from 'fs';
+
+// Keychain service name for all buwp-local credentials
+const KEYCHAIN_SERVICE = 'buwp-local';
+
+/**
+ * All credential keys that can be stored in keychain
+ */
+export const CREDENTIAL_KEYS = [
+  'WORDPRESS_DB_PASSWORD',
+  'DB_ROOT_PASSWORD',
+  'SP_ENTITY_ID',
+  'IDP_ENTITY_ID',
+  'SHIB_IDP_LOGOUT',
+  'SHIB_SP_KEY',
+  'SHIB_SP_CERT',
+  'S3_UPLOADS_BUCKET',
+  'S3_UPLOADS_REGION',
+  'S3_UPLOADS_ACCESS_KEY_ID',
+  'S3_UPLOADS_SECRET_ACCESS_KEY',
+  'S3_ACCESS_RULES_TABLE',
+  'OLAP',
+  'OLAP_ACCT_NBR',
+  'OLAP_REGION'
+];
+
+/**
+ * Credentials organized by functional group
+ */
+export const CREDENTIAL_GROUPS = {
+  database: ['WORDPRESS_DB_PASSWORD', 'DB_ROOT_PASSWORD'],
+  shibboleth: ['SP_ENTITY_ID', 'IDP_ENTITY_ID', 'SHIB_IDP_LOGOUT', 'SHIB_SP_KEY', 'SHIB_SP_CERT'],
+  s3: ['S3_UPLOADS_BUCKET', 'S3_UPLOADS_REGION', 'S3_UPLOADS_ACCESS_KEY_ID', 'S3_UPLOADS_SECRET_ACCESS_KEY', 'S3_ACCESS_RULES_TABLE'],
+  olap: ['OLAP', 'OLAP_ACCT_NBR', 'OLAP_REGION']
+};
+
+/**
+ * Credentials that contain multiline content (cryptographic keys, certificates)
+ */
+export const MULTILINE_CREDENTIALS = ['SHIB_SP_KEY', 'SHIB_SP_CERT'];
+
+/**
+ * Human-readable descriptions for each credential
+ */
+export const CREDENTIAL_DESCRIPTIONS = {
+  WORDPRESS_DB_PASSWORD: 'WordPress database password',
+  DB_ROOT_PASSWORD: 'Database root password',
+  SP_ENTITY_ID: 'Shibboleth Service Provider Entity ID',
+  IDP_ENTITY_ID: 'Shibboleth Identity Provider Entity ID',
+  SHIB_IDP_LOGOUT: 'Shibboleth IDP logout URL',
+  SHIB_SP_KEY: 'Shibboleth Service Provider private key (multiline)',
+  SHIB_SP_CERT: 'Shibboleth Service Provider certificate (multiline)',
+  S3_UPLOADS_BUCKET: 'S3 bucket name',
+  S3_UPLOADS_REGION: 'S3 region (e.g., us-east-1)',
+  S3_UPLOADS_ACCESS_KEY_ID: 'AWS access key ID',
+  S3_UPLOADS_SECRET_ACCESS_KEY: 'AWS secret access key',
+  S3_ACCESS_RULES_TABLE: 'S3 access rules table name',
+  OLAP: 'OLAP name',
+  OLAP_ACCT_NBR: 'OLAP account number',
+  OLAP_REGION: 'OLAP region'
+};
+
+/**
+ * Check if the current platform supports keychain operations
+ * @returns {boolean} True if macOS, false otherwise
+ */
+export function isPlatformSupported() {
+  return process.platform === 'darwin';
+}
+
+/**
+ * Validate that a credential key is recognized
+ * @param {string} key - Credential key to validate
+ * @returns {boolean} True if valid
+ */
+export function isValidCredentialKey(key) {
+  return CREDENTIAL_KEYS.includes(key);
+}
+
+/**
+ * Get the group name for a credential key
+ * @param {string} key - Credential key
+ * @returns {string|null} Group name or null if not found
+ */
+export function getCredentialGroup(key) {
+  for (const [groupName, keys] of Object.entries(CREDENTIAL_GROUPS)) {
+    if (keys.includes(key)) {
+      return groupName;
+    }
+  }
+  return null;
+}
+
+/**
+ * Check if a credential contains multiline content
+ * @param {string} key - Credential key
+ * @returns {boolean} True if credential is multiline
+ */
+export function isMultilineCredential(key) {
+  return MULTILINE_CREDENTIALS.includes(key);
+}
+
+/**
+ * Set a credential in the macOS keychain
+ * Uses -U flag to update existing entries instead of creating duplicates
+ * @param {string} key - Credential key (e.g., 'WORDPRESS_DB_PASSWORD')
+ * @param {string} value - Credential value
+ * @throws {Error} If platform is not supported or operation fails
+ */
+export function setCredential(key, value) {
+  if (!isPlatformSupported()) {
+    throw new Error('Keychain operations are only supported on macOS');
+  }
+
+  if (!isValidCredentialKey(key)) {
+    throw new Error(`Invalid credential key: ${key}`);
+  }
+
+  try {
+    // Use -U flag to update if exists, create if doesn't
+    // -w flag allows password on command line (needed for automation)
+    execSync(
+      `security add-generic-password -s "${KEYCHAIN_SERVICE}" -a "${key}" -w "${value}" -U`,
+      { stdio: 'pipe' }
+    );
+  } catch (err) {
+    throw new Error(`Failed to store credential in keychain: ${err.message}`);
+  }
+}
+
+/**
+ * Get a credential from the macOS keychain
+ * @param {string} key - Credential key
+ * @returns {string|null} Credential value or null if not found
+ * @throws {Error} If platform is not supported
+ */
+export function getCredential(key) {
+  if (!isPlatformSupported()) {
+    throw new Error('Keychain operations are only supported on macOS');
+  }
+
+  if (!isValidCredentialKey(key)) {
+    throw new Error(`Invalid credential key: ${key}`);
+  }
+
+  try {
+    // -w flag returns only the password (no other metadata)
+    let result = execSync(
+      `security find-generic-password -s "${KEYCHAIN_SERVICE}" -a "${key}" -w`,
+      { stdio: 'pipe', encoding: 'utf8' }
+    );
+    result = result.trim();
+
+    // Handle hex-encoded values (legacy format for multiline credentials)
+    // Check if the value looks like hex (only hex digits, even length)
+    if (isMultilineCredential(key) && isHexEncoded(result)) {
+      try {
+        result = Buffer.from(result, 'hex').toString('utf8');
+      } catch (err) {
+        // If hex decode fails, return original value
+        console.warn(`Warning: Could not decode hex-encoded credential ${key}`);
+      }
+    }
+
+    return result;
+  } catch (err) {
+    // Credential not found
+    if (err.message.includes('could not be found')) {
+      return null;
+    }
+    throw new Error(`Failed to retrieve credential from keychain: ${err.message}`);
+  }
+}
+
+/**
+ * Check if a string appears to be hex-encoded
+ * @param {string} value - Value to check
+ * @returns {boolean} True if value looks like hex
+ */
+function isHexEncoded(value) {
+  // Must be even length and only contain hex digits
+  return /^[0-9a-fA-F]+$/.test(value) && value.length % 2 === 0;
+}
+
+/**
+ * Check if a credential exists in the keychain
+ * @param {string} key - Credential key
+ * @returns {boolean} True if credential exists
+ */
+export function hasCredential(key) {
+  if (!isPlatformSupported()) {
+    return false;
+  }
+
+  if (!isValidCredentialKey(key)) {
+    return false;
+  }
+
+  try {
+    execSync(
+      `security find-generic-password -s "${KEYCHAIN_SERVICE}" -a "${key}"`,
+      { stdio: 'pipe' }
+    );
+    return true;
+  } catch (err) {
+    return false;
+  }
+}
+
+/**
+ * Delete a credential from the keychain
+ * @param {string} key - Credential key
+ * @throws {Error} If platform is not supported or operation fails
+ */
+export function deleteCredential(key) {
+  if (!isPlatformSupported()) {
+    throw new Error('Keychain operations are only supported on macOS');
+  }
+
+  if (!isValidCredentialKey(key)) {
+    throw new Error(`Invalid credential key: ${key}`);
+  }
+
+  try {
+    execSync(
+      `security delete-generic-password -s "${KEYCHAIN_SERVICE}" -a "${key}"`,
+      { stdio: 'pipe' }
+    );
+  } catch (err) {
+    // Ignore if credential doesn't exist
+    if (!err.message.includes('could not be found')) {
+      throw new Error(`Failed to delete credential from keychain: ${err.message}`);
+    }
+
+    console.log("foobar");
+  }
+}
+
+/**
+ * List all stored credentials (returns keys only, not values)
+ * @returns {string[]} Array of credential keys that are stored
+ */
+export function listCredentials() {
+  if (!isPlatformSupported()) {
+    return [];
+  }
+
+  const storedKeys = [];
+  
+  for (const key of CREDENTIAL_KEYS) {
+    if (hasCredential(key)) {
+      storedKeys.push(key);
+    }
+  }
+  
+  return storedKeys;
+}
+
+/**
+ * Clear all buwp-local credentials from keychain
+ * @returns {number} Number of credentials deleted
+ */
+export function clearAllCredentials() {
+  if (!isPlatformSupported()) {
+    throw new Error('Keychain operations are only supported on macOS');
+  }
+
+  let deletedCount = 0;
+  
+  for (const key of CREDENTIAL_KEYS) {
+    try {
+      deleteCredential(key);
+      deletedCount++;
+    } catch (err) {
+      // Continue deleting others even if one fails
+    }
+  }
+  
+  return deletedCount;
+}
+
+/**
+ * Parse credentials from a JSON file
+ * Expected format: { "credentials": { "KEY": "value", ... }, "version": "1.0", ... }
+ * @param {string} filePath - Path to credentials JSON file
+ * @returns {object} { parsed, unknown, metadata }
+ */
+export function parseCredentialsFile(filePath) {
+  // Read and parse JSON file
+  let data;
+  try {
+    const content = fs.readFileSync(filePath, 'utf8');
+    data = JSON.parse(content);
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      throw new Error(`File not found: ${filePath}`);
+    } else if (err instanceof SyntaxError) {
+      throw new Error(`Invalid JSON format: ${err.message}`);
+    }
+    throw new Error(`Failed to read file: ${err.message}`);
+  }
+  
+  // Validate structure
+  if (!data.credentials || typeof data.credentials !== 'object') {
+    throw new Error('Invalid credentials file format: missing "credentials" object');
+  }
+  
+  // Filter and validate keys
+  const parsed = {};
+  const unknown = [];
+  
+  for (const [key, value] of Object.entries(data.credentials)) {
+    if (CREDENTIAL_KEYS.includes(key)) {
+      // Validate value is non-empty string
+      if (typeof value === 'string' && value.trim().length > 0) {
+        parsed[key] = value;
+      } else {
+        unknown.push({ key, reason: 'empty or invalid value' });
+      }
+    } else {
+      unknown.push({ key, reason: 'unknown credential key' });
+    }
+  }
+  
+  // Extract metadata
+  const metadata = {
+    version: data.version || 'unknown',
+    source: data.source || 'unknown',
+    exported: data.exported || null
+  };
+  
+  return { parsed, unknown, metadata };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bostonuniversity/buwp-local",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Local WordPress development environment for Boston University projects",
   "type": "module",
   "main": "lib/index.js",
@@ -9,7 +9,7 @@
   },
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1",
-    "buwp-local": "node bin/buwp-local.js",
+    "buwp-local": "node bin/buwp-local.js start",
     "lint": "eslint ."
   },
   "keywords": [

package/plan-environmentBasedCredentials.prompt.md

@@ -0,0 +1,57 @@
+## Plan: Environment-Based Credentials Migration (v0.4.1)
+
+We've successfully shipped v0.4.0 with interactive init, sandbox support, configurable Docker images, and smart hostname defaults. The codebase is in excellent shape with real-world testing validated in both plugin and sandbox scenarios.
+
+**Current Problem:** Credentials (database passwords, AWS keys, Shibboleth certs) are currently being read from the config/environment and then **written directly into the generated `docker-compose.yml`**. This means sensitive data sits in a generated file, which isn't ideal for security.
+
+**Better Approach:** Use Docker Compose's native environment variable interpolation (`${VAR_NAME}`) so credentials stay in `.env.local` and never get written to the compose file.
+
+### Steps
+
+1. **Update `compose-generator.js` to use environment variable references**
+   - Database service: Change from `MYSQL_PASSWORD: dbPassword` to `MYSQL_PASSWORD: '${WORDPRESS_DB_PASSWORD:-password}'`
+   - WordPress service: Change from `WORDPRESS_DB_PASSWORD: config.db?.password` to `WORDPRESS_DB_PASSWORD: '${WORDPRESS_DB_PASSWORD:-password}'`
+   - S3 proxy service: Change from `AWS_ACCESS_KEY_ID: config.s3?.accessKeyId` to `AWS_ACCESS_KEY_ID: '${S3_UPLOADS_ACCESS_KEY_ID}'`
+   - WordPress `WORDPRESS_CONFIG_EXTRA`: Change from injecting actual S3 keys to using `${S3_UPLOADS_ACCESS_KEY_ID}` references
+
+2. **Update `start.js` to pass `.env.local` to docker compose**
+   - Add `--env-file` flag to `docker compose up` command
+   - Ensure `.env.local` path is correctly resolved relative to project
+
+3. **Update config loading to remove credential reading**
+   - Keep `extractEnvVars()` for backward compatibility but mark as deprecated
+   - Config validation no longer needs to check for credential presence in config object
+   - Document that credentials should only live in `.env.local`
+
+4. **Update documentation**
+   - `USAGE.md` - Clarify that `.env.local` is the source of truth for credentials
+   - Add example showing compose file will have `${VAR}` references
+   - Security best practices section emphasizes this approach
+
+5. **Test migration path**
+   - Verify existing projects with credentials in config still work (backward compat)
+   - Test new projects using only `.env.local`
+   - Verify generated compose file contains variable references, not actual values
+   - Ensure `docker compose` properly reads `.env.local`
+
+### Further Considerations
+
+1. **Backward compatibility**: Should we warn users if credentials exist in config? Or silently prefer `.env.local`?
+2. **`.env.local` template**: Should we create `.env.local.example` during `init` command?
+3. **Validation**: Should `config --validate` check that `.env.local` exists and has required variables?
+
+---
+
+**Why This Matters:**
+- **Security**: Credentials never written to files, only referenced
+- **Git safety**: Generated compose files are safe to accidentally commit (no secrets)
+- **Best practices**: Aligns with Docker Compose's standard env var pattern
+- **Simplicity**: Reduces complexity in config merging logic
+
+**Effort Estimate:** Low-Medium (4-6 hours)
+- Compose generation changes: ~2 hours
+- Start command changes: ~1 hour  
+- Documentation: ~1 hour
+- Testing: ~1-2 hours
+
+**Ready to proceed?** This sets up a cleaner foundation before tackling Phase 2 features like keychain integration.