@bostonuniversity/buwp-local 0.4.1 → 0.5.1

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,97 @@ function sanitizeProjectName(name) {
     .replace(/^-+|-+$/g, ''); // Remove leading/trailing dashes
 }
 
+/**
+ * Load credentials from macOS keychain
+ * Returns all available credentials if present, 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
+    // Order matters: backslashes first, then quotes, then newlines
+    const escaped = String(value)
+      .replace(/\\/g, '\\\\')      // Escape backslashes first (\ -> \\)
+      .replace(/"/g, '\\"')        // Escape double quotes (" -> \")
+      .replace(/\n/g, '\\n');      // Escape actual newlines (\n -> \n literal in file)
+    
+    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,337 @@
+/**
+ * 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}`);
+    }
+  }
+}
+
+/**
+ * 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.1",
+  "version": "0.5.1",
   "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 start",
+    "buwp-local": "node bin/buwp-local.js",
     "lint": "eslint ."
   },
   "keywords": [

package/readme.md

@@ -1,3 +1,82 @@
 # BU WordPress Local Development
 
 This repository contains resources and instructions for setting up a local WordPress development environment for Boston University projects. It uses the BU WordPress container image and provides the additional resoures needed to run it locally with Docker.
+
+
+## Quickstart for plugin or theme development
+
+1. **Install Docker**: Make sure you have [Docker Desktop](https://www.docker.com/products/docker-desktop) installed and running on your machine.
+
+2. Login to GitHub Packages to access the BU WordPress Docker image (you will need a GitHub access token with `read:packages` scope):
+
+   ```bash
+   echo YOUR_GITHUB_TOKEN | docker login ghcr.io -u YOUR_GITHUB_USERNAME --password-stdin
+   ```
+
+3. **Install buwp-local CLI**: Install the `buwp-local` CLI tool in your project directory:
+
+   ```bash
+   npm install @bostonuniversity/buwp-local --save-dev
+   ```
+
+4. **One time credential keychain setup**: Install credentials in the macOS Keychain for secure storage (optional, macOS only right now):
+
+    First, download a credentials JSON file through ssh from the dev server:
+
+    ```bash
+    scp user@devserver:/path/to/buwp-local-credentials.json ~/Downloads/
+    ```
+
+    Then run the setup command:
+
+    ```bash
+    npx buwp-local keychain setup --file ~/Downloads/buwp-local-credentials.json
+    ```
+
+    This will store all necessary credentials in your Keychain for future use, for this project and any other buwp-local projects (Keychain is global). (The global Keychain can also be overridden by `.env.local` files in each project.)
+
+5. **Initialize your project**: Run the interactive setup to create your `.buwp-local.json` configuration file:
+
+    ```bash
+    npx buwp-local init
+    ```
+
+    This will guide you through setting up your project name, hostname, port mappings, volume mappings, and service options.
+
+6. **Setup local hostname**: Add your project's local hostname (e.g. `myproject.local`) to your `/etc/hosts` file
+
+7. **Start your local environment**:
+
+    ```bash
+    npx buwp-local start
+    ```
+
+    This will read your configuration, load credentials from Keychain (or `.env.local` if present), and start the Docker containers for your WordPress project.
+
+Your local WordPress site should now be accessible at the hostname you configured (e.g. `http://myproject.local`).
+
+## Basic Local setup
+
+
+1. **Setup local user**: Create a local WordPress user and add it to the super admin role:
+
+    If running with Shibboleth enabled, you can set up a local WordPress user with super admin privileges:
+
+    Create the user:
+    ```bash
+    npx buwp-local wp user create username username@bu.edu --role=administrator
+    ```
+
+    Promote to super admin:
+    ```bash
+    npx buwp-local wp super-admin add username@bu.edu
+    ```
+2. Pull snapshot site content:
+
+    You can pull a snapshot of the production or staging site database and media files into your local environment for testing and development.
+
+    ```bash
+    npx buwp-local wp site-manager snapshot-pull --source=https://www.bu.edu/admissions/ --destination=http://myproject.local/admissions
+    ```
+
+    This will download the latest snapshot from the specified source and import it into your local WordPress environment.

package/.buwp-local.json

@@ -1,22 +0,0 @@
-{
-  "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/plan-environmentBasedCredentials.prompt.md

@@ -1,57 +0,0 @@
-## 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.