@unifiedmemory/cli 1.0.1 → 1.1.0

package/.env.example

@@ -1,9 +1,30 @@
-# Optional: Override Clerk OAuth Configuration
-# By default, the CLI uses the production UnifiedMemory Clerk application
-# Only set these if you're developing/testing with a different Clerk app
+# UnifiedMemory CLI Configuration
+# Copy this file to .env and fill in your values
 
-# CLERK_CLIENT_ID=your_test_clerk_client_id
-# CLERK_DOMAIN=your-test-app.clerk.accounts.dev
-# API_ENDPOINT=http://localhost:8000
+# ============================================
+# REQUIRED: Clerk OAuth Configuration
+# ============================================
+# Get these from your Clerk dashboard: https://dashboard.clerk.com
+CLERK_CLIENT_ID=your_clerk_client_id_here
+CLERK_DOMAIN=your-app.clerk.accounts.dev
+
+# ============================================
+# REQUIRED: API Configuration
+# ============================================
+# Your UnifiedMemory API gateway URL
+API_ENDPOINT=https://your-api-gateway.zuplo.dev
+
+# ============================================
+# OPTIONAL: OAuth Flow Configuration
+# ============================================
+# Customize the OAuth redirect URI and local server port
+# Default values work for most users
 # REDIRECT_URI=http://localhost:3333/callback
 # PORT=3333
+
+# ============================================
+# OPTIONAL: Clerk Client Secret
+# ============================================
+# Not required for PKCE flow (recommended)
+# Only set this if specifically instructed
+# CLERK_CLIENT_SECRET=your_clerk_client_secret

package/CHANGELOG.md

@@ -5,6 +5,238 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Fixed
+
+- **commands/init.js** - Enhanced error handling for 401/403/network errors during project fetching
+  - Previously, `um init` would silently suppress authentication errors and show "0 available projects"
+  - Now detects specific error types (401 UNAUTHORIZED, 403 FORBIDDEN, network errors, etc.)
+  - Validates organization context before making API calls to prevent user_id fallback issues
+  - Provides clear error messages with actionable recovery steps (e.g., "Run: um login")
+  - Exits gracefully instead of continuing with incorrect state
+  - Distinguishes between "legitimately 0 projects" and "failed to fetch projects"
+  - Adds `validateOrganizationContext()` helper to detect personal account context
+  - Enhanced `fetchProjects()` to return structured error objects instead of empty arrays
+  - Enhanced `createProject()` with specific error messages for 401/403/409 status codes
+
+- **lib/org-selection-ui.js** - Fixed organization selection prompt not displaying during `um login`
+  - Updated prompt type from deprecated `'list'` to `'select'` (inquirer v13 breaking change)
+  - Previously, the prompt would show question text but not the visual list of options
+  - Users now see a proper interactive list with arrow key navigation
+  - Removed debug console.log statements that could interfere with prompt rendering
+  - Kept helpful instruction: "💡 Use ↑/↓ arrow keys to navigate, Enter to select"
+
+- **commands/init.js** - Converted project selection prompts to arrow key navigation for consistent UX
+  - **Create vs Select choice**: Changed from numbered input (type "1" or "2") to arrow key selection
+  - **Project list selection**: Changed from numbered input (type project number) to arrow key navigation
+  - Added pagination support for long project lists (10 items per page)
+  - Removed ~22 lines of manual numbering, validation, and parseInt logic
+  - Direct value returns instead of array indexing (cleaner, less error-prone)
+  - Consistent with organization selection UX (all selections now use arrow keys)
+
+- **commands/init.js** - Added automatic re-authentication on 401 errors (self-healing behavior)
+  - Previously, `um init` would fail with "Run: um login" message when token was invalid/expired
+  - Now automatically triggers re-authentication when 401 errors occur during project fetch
+  - Opens browser for OAuth, gets fresh credentials, and retries the operation
+  - Single retry prevents infinite loops, falls back to error message if retry fails
+  - Users no longer need to manually run `um login` when their tokens expire
+  - Clear progress messages: "Attempting automatic re-authentication...", "✓ Re-authentication successful!"
+  - Gracefully handles user cancellation and persistent failures
+
+## [1.1.0] - 2026-01-07
+
+### ♻️ CODE QUALITY (Phase 1: Code Consolidation)
+
+This release focuses on code quality improvements, removing duplication, and eliminating dead code. **No breaking changes** - all existing commands work identically.
+
+#### Added
+
+- **lib/jwt-utils.js** - New centralized JWT utilities module
+  - `parseJWT(token)` - Parse JWT tokens
+  - `isJWTExpired(decoded, bufferMs)` - Check token expiration
+  - `validateJWTStructure(decoded)` - Validate JWT structure
+  - `getTimeUntilExpiration(decoded)` - Calculate time until expiration
+
+- **lib/org-selection-ui.js** - New shared organization selection UI module
+  - `promptOrganizationSelection(memberships, currentOrg, options)` - Interactive org selection
+  - `displayOrganizationSelection(selectedOrg)` - Display selection result
+
+#### Changed
+
+- **commands/login.js** - Removed ~60 lines of duplicate code
+  - Now imports `parseJWT` from `lib/jwt-utils.js`
+  - Now uses `promptOrganizationSelection` and `displayOrganizationSelection` from `lib/org-selection-ui.js`
+
+- **lib/token-refresh.js** - Removed ~15 lines of duplicate code
+  - Now imports `parseJWT` from `lib/jwt-utils.js`
+
+- **commands/org.js** - Removed ~50 lines of duplicate code
+  - Now uses `promptOrganizationSelection` and `displayOrganizationSelection` from `lib/org-selection-ui.js`
+
+- **lib/config.js** - Replaced custom .env parser with `dotenv` library
+  - Removed ~15 lines of fragile custom parsing code
+  - Now uses battle-tested `dotenv` package
+
+- **lib/provider-detector.js** - Replaced custom TOML parser with `@iarna/toml` library
+  - Removed ~60 lines of custom `parseTOML()` and `generateTOML()` functions
+  - Now uses standard `@iarna/toml` package
+
+#### Removed
+
+- **Dead code from commands/init.js**:
+  - `loginWithApiKey()` stub function (never implemented, always returned null)
+  - `refreshToken()` stub function (never called, real implementation exists elsewhere)
+  - Removed API key login path that never worked
+
+- **Stub commands from index.js**:
+  - `um project` command (non-functional stub that told users to use `um init`)
+  - `um configure` command (non-functional stub that told users to use `um init`)
+  - `--device` option on `um login` command (never used in implementation)
+
+#### Dependencies
+
+- Added `dotenv@^16.3.1` - Industry-standard .env file parsing
+- Added `@iarna/toml@^2.2.5` - Spec-compliant TOML parser
+
+#### Code Metrics
+
+- **Lines removed**: ~210 lines of duplicate and dead code
+- **New modules**: 2 shared utility modules
+- **Code coverage**: Increased maintainability and reduced technical debt
+
+#### Migration Guide
+
+**No action required** - This release is 100% backward compatible. All existing commands and workflows continue to work without changes.
+
+**Developer Notes**: If you were using the stub commands (`um project`, `um configure`), use `um init` instead as the stubs always instructed.
+
+## [1.0.2] - 2026-01-07
+
+### 🔒 SECURITY FIXES (Phase 0: Critical Security Hardening)
+
+This release addresses **5 critical security vulnerabilities** identified during comprehensive security audit. All users should upgrade immediately.
+
+#### Fixed
+
+1. **CRITICAL: Insecure Token Storage**
+   - **Issue**: Authentication tokens stored with default permissions (644), readable by all users on system
+   - **Fix**: Token directory now created with 0700 permissions (owner-only access)
+   - **Fix**: Token file (`~/.um/auth.json`) now written with 0600 permissions (owner read/write only)
+   - **Impact**: Prevents unauthorized access to OAuth tokens on shared systems
+   - **Files**: `lib/token-storage.js`
+
+2. **CRITICAL: Hardcoded Production Credentials**
+   - **Issue**: Clerk client ID, domain, and API endpoint hardcoded in source code
+   - **Fix**: Removed all hardcoded defaults, now requires environment variables
+   - **Fix**: Added `.env.example` template file
+   - **Fix**: Implemented actual validation in `validateConfig()` with helpful error messages
+   - **Impact**: Credentials can now be rotated without code changes, prevents exposure in git
+   - **Files**: `lib/config.js`, `.env.example` (new)
+
+3. **HIGH: Weak CSRF Protection**
+   - **Issue**: OAuth state parameter generated using `Math.random()` (predictable)
+   - **Fix**: Now uses `crypto.randomBytes(32)` for cryptographically secure random generation
+   - **Impact**: Prevents CSRF attacks during OAuth flow
+   - **Files**: `commands/login.js`
+
+4. **CRITICAL: Access Tokens in Bash Scripts**
+   - **Issue**: `lib/hooks.js` embedded access tokens directly in bash scripts with command injection vulnerability
+   - **Fix**: Completely removed hooks.js file and all hook installation code
+   - **Impact**: Eliminates token leakage and command injection attack surface
+   - **Files**: `lib/hooks.js` (DELETED), `lib/provider-detector.js`
+
+5. **MEDIUM: Token Leakage in Console Logs**
+   - **Issue**: Full JWT tokens, previews, and decoded payloads logged to console during login
+   - **Fix**: Removed all token logging (lines 228-250 in login.js, line 62 debug logging)
+   - **Impact**: Prevents token capture in terminal history, screen recordings, or log files
+   - **Files**: `commands/login.js`
+
+#### Added
+
+- `.env.example` - Template file for required environment variables
+- Comprehensive security documentation in README.md
+- Configuration section in README.md explaining .env setup
+- Enhanced error messages when environment variables are missing
+
+#### Changed
+
+- **BREAKING**: CLI now requires `.env` file with `CLERK_CLIENT_ID`, `CLERK_DOMAIN`, and `API_ENDPOINT`
+- Token storage file permissions upgraded automatically on next write
+- Validation errors now provide actionable guidance for users
+
+#### Removed
+
+- `lib/hooks.js` - Entire file deleted due to unfixable security vulnerabilities
+- Claude Code prompt-submit hook installation - Removed from provider detector
+- `BaseProvider.installHook()` method - No longer supported
+- `ClaudeProvider.installHook()` method - No longer supported
+- Console logging of tokens, JWT claims, and raw membership data
+
+#### Migration Guide
+
+**For Existing Users**:
+
+1. **Create `.env` file** (required):
+   ```bash
+   cd $(npm root -g)/@unifiedmemory/cli  # Or your installation directory
+   cp .env.example .env
+   # Edit .env with your credentials (see README Configuration section)
+   ```
+
+2. **Token permissions auto-upgrade**: Next time you login, token files will automatically get secure permissions
+
+3. **Hooks removed**: If you configured Claude Code hooks, they will no longer work. This feature has been removed for security reasons.
+
+**For New Users**: Follow the Configuration section in README.md
+
+#### Security Notes
+
+- All fixes are backward compatible with existing authentication flows
+- Token refresh continues to work without changes
+- No user data or credentials were compromised
+- Security audit report available in plan file
+
+## [1.0.1] - 2026-01-06
+
+### Added
+- Welcome splash screen with pink Axolotl ASCII art
+- `um welcome` command to display welcome message anytime
+- Automatic welcome display when running `um` without arguments
+
+### BREAKING CHANGES
+- Changed MCP server configuration key from "vault" to "unifiedmemory" for consistency
+- Changed MCP server instance name from "unifiedmemory-vault" to "unifiedmemory"
+
+### Migration Guide
+
+If you previously ran `um init` with v1.0.0, you need to update your AI assistant configuration files to rename the server key from "vault" to "unifiedmemory". Choose the instructions below based on which AI assistant(s) you use:
+
+**Cursor** (`~/.cursor/mcp.json`):
+- Edit the file and rename `mcpServers.vault` to `mcpServers.unifiedmemory`
+- Keep the same `command` and `args` values
+
+**Cline** (`~/.cline/mcp.json`):
+- Edit the file and rename `mcpServers.vault` to `mcpServers.unifiedmemory`
+- Keep the same `command` and `args` values
+
+**Codex CLI** (`~/.codex/config.toml`):
+- Edit the file and rename `[mcp_servers.vault]` to `[mcp_servers.unifiedmemory]`
+- Keep the same `command` and `args` values
+
+**Gemini CLI** (`~/.gemini/settings.json`):
+- Edit the file and rename `mcpServers.vault` to `mcpServers.unifiedmemory`
+- Keep the same `command` and `args` values
+
+**Claude Code** (project-specific):
+- Edit `.mcp.json` in your project: rename `mcpServers.vault` to `mcpServers.unifiedmemory`
+- Edit `.claude/settings.local.json` in your project: update the `enabledMcpjsonServers` array to replace `"vault"` with `"unifiedmemory"`
+- Keep the same `command` and `args` values
+
+After updating the configuration files, restart your AI assistant for the changes to take effect.
+
+**Note**: If you're doing a fresh installation of v1.0.1, no migration is needed - `um init` will automatically configure the correct server name.
+
 ## [1.0.0] - 2026-01-06
 
 ### Added

package/README.md

@@ -213,13 +213,74 @@ Tokens automatically refresh. If you see auth errors:
 um login
 ```
 
+### Missing environment variables
+If you see "Missing required environment variables" error:
+1. Copy `.env.example` to `.env` in the CLI installation directory
+2. Fill in your Clerk and API credentials
+3. See Configuration section below for details
+
+## Configuration
+
+The CLI requires environment variables for Clerk OAuth and API access. These should never be hardcoded in your project.
+
+**Step 1: Create `.env` file**
+```bash
+# In the um-cli installation directory (find with: npm root -g)
+cp .env.example .env
+```
+
+**Step 2: Add your credentials**
+```bash
+# Required: Clerk OAuth Configuration
+CLERK_CLIENT_ID=your_clerk_client_id_here
+CLERK_DOMAIN=your-app.clerk.accounts.dev
+
+# Required: API Configuration
+API_ENDPOINT=https://your-api-gateway.zuplo.dev
+```
+
+Get these values from:
+- **Clerk credentials**: [Clerk Dashboard](https://dashboard.clerk.com)
+- **API endpoint**: Your UnifiedMemory deployment
+
+**Optional configuration**:
+```bash
+# Customize OAuth redirect (defaults shown)
+REDIRECT_URI=http://localhost:3333/callback
+PORT=3333
+```
+
+See `.env.example` for the complete template with documentation.
+
 ## Privacy & Security
 
-- **Local-first**: All authentication happens on your machine
-- **Secure storage**: Tokens stored in `~/.um/auth.json` with proper file permissions
+UnifiedMemory CLI follows security best practices to protect your credentials and data:
+
+### Secure Token Storage
+- **File permissions**: Tokens stored in `~/.um/auth.json` with `0600` permissions (owner read/write only)
+- **Directory permissions**: `~/.um/` directory has `0700` permissions (owner access only)
+- **No plaintext exposure**: Tokens are never logged to console or stored in project files
 - **Auto-refresh**: Tokens refresh automatically before expiring
-- **No git commits**: `.um/` is automatically added to `.gitignore`
+
+### Authentication Security
+- **PKCE flow**: Uses OAuth 2.0 PKCE for secure authentication without client secrets
+- **CSRF protection**: Cryptographically secure random state parameters
+- **Local-first**: All authentication happens on your machine, never shared with third parties
+
+### Project Security
+- **No git commits**: `.um/` directory automatically added to `.gitignore`
 - **Project isolation**: Each project has its own configuration and vault
+- **Environment-based config**: No hardcoded credentials in source code
+- **Minimal permissions**: CLI only requests access it needs
+
+### What We Don't Collect
+- ❌ No tokens in analytics
+- ❌ No credentials in error reports
+- ❌ No project code sent to our servers
+- ✅ Only encrypted knowledge stored in your vault
+
+### Security Updates
+Security issues are taken seriously. To report a vulnerability, please email security@unifiedmemory.ai (do not use public issues).
 
 ## Learn More