vibe-forge 0.4.0 → 0.8.2

package/docs/security.md

@@ -1,144 +1,195 @@
-# Vibe Forge Security Documentation
-
-This document explains security considerations and intentional design decisions in Vibe Forge.
-
-## The `--dangerously-skip-permissions` Flag
-
-### What It Does
-
-When starting agents, Vibe Forge uses Claude Code's `--dangerously-skip-permissions` flag:
-
-```bash
-claude --dangerously-skip-permissions --system-prompt "$system_prompt" "startup"
-```
-
-This flag disables Claude Code's permission prompts for file operations, command execution, and other actions that would normally require user confirmation.
-
-### Why We Use It
-
-Vibe Forge is designed for **terminal-native vibe coding** - a workflow where you launch multiple AI agents that work autonomously on your codebase. The typical workflow involves:
-
-1. Starting a Planning Hub that coordinates work
-2. Spawning worker agents (frontend, backend, testing, etc.) in separate terminals
-3. Agents working autonomously on assigned tasks
-4. Human review at defined checkpoints
-
-With permission prompts enabled, each agent would constantly interrupt for confirmation, breaking the autonomous workflow that makes Vibe Forge effective.
-
-### Security Mitigations
-
-We implement several security measures to offset the risks:
-
-#### 1. Agent Whitelist Validation
-
-All agent names go through strict whitelist validation before execution:
-
-```bash
-# bin/lib/constants.sh
-VALID_AGENTS=("anvil" "furnace" "crucible" ...)
-
-# bin/lib/agents.sh
-resolve_agent() {
-    local canonical="${AGENT_ALIASES[$normalized]:-}"
-    if [[ -n "$canonical" ]]; then
-        echo "$canonical"
-        return 0
-    fi
-    return 1  # Reject unknown agents
-}
-```
-
-This prevents command injection through agent names.
-
-#### 2. Path Traversal Protection
-
-Personality file paths are validated to ensure they remain within the expected directory:
-
-```bash
-get_agent_personality_path() {
-    local real_path=$(cd "$(dirname "$personality_path")" && pwd)/$(basename "$personality_path")
-    local agents_dir=$(cd "$forge_root/agents" && pwd)
-
-    if [[ "$real_path" != "$agents_dir"/* ]]; then
-        echo "Security error: Path traversal detected" >&2
-        return 1
-    fi
-}
-```
-
-#### 3. Safe JSON Parsing
-
-We use Node.js for JSON parsing instead of `grep`/`cut` which could be vulnerable to injection:
-
-```bash
-json_get_string() {
-    node -e "
-        const fs = require('fs');
-        const data = JSON.parse(fs.readFileSync('$file', 'utf8'));
-        if (data['$key'] !== undefined) console.log(String(data['$key']));
-    "
-}
-```
-
-#### 4. Daemon Security
-
-The background daemon includes multiple protections:
-
-- **Symlink protection**: Skips symlinks to prevent symlink attacks
-- **Path validation**: Verifies destinations are within FORGE_ROOT
-- **Atomic operations**: Uses temp files + move for safe writes
-- **Lock files**: Prevents multiple daemon instances
-- **Log rotation**: Bounded log growth prevents disk exhaustion
-
-### Risks to Be Aware Of
-
-Even with mitigations, understand these risks:
-
-1. **AI agents can modify any file** in your project without confirmation
-2. **AI agents can execute any command** without confirmation
-3. **Malicious prompts** could potentially be injected if context files are compromised
-4. **Network access** is unrestricted - agents could make API calls
-
-### Recommendations
-
-1. **Use in development environments only** - Don't run on production systems
-2. **Use with version control** - Git makes it easy to review and revert changes
-3. **Review at checkpoints** - Check agent work during task transitions
-4. **Understand the personality files** - They define agent behavior
-5. **Keep project context secure** - Don't include secrets in context files
-6. **Run in isolated environments** - Consider containers for sensitive projects
-
-### Alternative: Manual Approval Mode
-
-If you prefer permission prompts, you can modify the agent startup in `bin/forge.sh`:
-
-```bash
-# Change this:
-claude --dangerously-skip-permissions --system-prompt "$system_prompt" "startup"
-
-# To this (removes the flag):
-claude --system-prompt "$system_prompt" "startup"
-```
-
-Note: This will significantly impact the autonomous workflow.
-
-## Reporting Security Issues
-
-If you discover a security vulnerability in Vibe Forge:
-
-1. **Do not open a public issue**
-2. Email security concerns to the maintainers
-3. Include steps to reproduce
-4. Allow time for a fix before public disclosure
-
-## Security Checklist for Contributors
-
-When contributing to Vibe Forge:
-
-- [ ] Never pass user input directly to shell commands
-- [ ] Always validate agent names against the whitelist
-- [ ] Use safe JSON parsing (Node.js, not grep/cut)
-- [ ] Validate file paths don't traverse outside expected directories
-- [ ] Use atomic file operations where race conditions are possible
-- [ ] Add tests for security-sensitive functions
-- [ ] Document any new security considerations
+# Vibe Forge Security Documentation
+
+This document explains security considerations and intentional design decisions in Vibe Forge.
+
+## Agent Permission Model
+
+### How It Works
+
+Vibe Forge agents run with **allowlist-based permissions** defined in `.claude/settings.json`. This replaces the previous `--dangerously-skip-permissions` approach with a defense-in-depth model:
+
+1. **Allowlist** (`.claude/settings.json`) - Pre-approves safe operations (file reads, writes, git, npm, etc.)
+2. **Heimdall** (pre-tool hook) - Intercepts and gates forge-specific policy (branch protection, etc.)
+3. **Claude Code native prompts** - Anything not in the allowlist still requires user approval
+
+```
+  Agent wants to run a command
+           |
+           v
+  ┌─────────────────┐
+  │ Allowlist check  │──── Not allowed ──> User prompted
+  └────────┬────────┘
+           │ Allowed
+           v
+  ┌─────────────────┐
+  │ Heimdall hook   │──── Policy violation ──> Blocked
+  └────────┬────────┘
+           │ Pass
+           v
+       Executed
+```
+
+### What Agents Can Do Without Prompting
+
+The allowlist covers normal development operations:
+- Read, write, and edit files
+- Search with glob/grep
+- Run git commands (status, diff, add, commit, push, branch, etc.)
+- Run GitHub CLI (PRs, runs, workflows)
+- Run npm (test, install, audit, build)
+- Run node/npx scripts
+- File operations (ls, cp, mv, mkdir, find)
+- SQLite operations
+
+### What Still Requires Approval
+
+Anything not in the allowlist prompts the user:
+- Installing system packages (apt, brew, etc.)
+- Running unfamiliar binaries
+- Network operations (curl, wget) unless via node
+- Destructive operations not covered by git (rm -rf, etc.)
+
+### Heimdall Policy Layer
+
+Heimdall is a pre-tool hook that enforces forge-specific rules on top of the allowlist:
+- Blocks direct pushes to main/master
+- Enforces branch naming conventions
+- Gates security-sensitive operations
+
+Heimdall runs on every Bash tool call regardless of allowlist status.
+
+### Why Not --dangerously-skip-permissions?
+
+The `--dsp` flag disables ALL permission checks. The allowlist approach is better because:
+- Only known-safe operations are pre-approved
+- Unknown commands still prompt for approval
+- Heimdall policies still enforce forge rules
+- The security posture is auditable (read `.claude/settings.json`)
+
+Users who prefer the fully autonomous workflow can still use `--dsp` in their own terminals.
+
+### Trust Boundary: Shared Allowlist
+
+All forge agents share a single allowlist defined in `.claude/settings.json`. There are no per-agent permission boundaries. This means:
+
+- **Anvil** (frontend) has the same file-write permissions as **Aegis** (security)
+- A compromised or confused agent personality cannot be contained by permissions alone
+- Heimdall policies provide some per-agent gating (e.g. branch protection) but do not restrict filesystem scope
+
+This is an accepted architectural trade-off. Per-agent permission boundaries would require separate `settings.json` files per agent and a launcher that selects the correct one, which adds complexity without proportional security benefit in a single-developer, local-only workflow.
+
+**Mitigations:**
+- Version control (git) makes all file changes reviewable and revertible
+- Heimdall enforces structural policies (no direct push to main, naming conventions)
+- Sentinel code review catches inappropriate changes before merge
+- The dashboard provides visibility into what each agent is doing
+
+**Future consideration:** If Vibe Forge supports multi-developer or remote execution (T3-4), per-agent permission boundaries should be revisited.
+
+## Dashboard Security
+
+### Session Token Authentication
+
+The dashboard server generates a cryptographic session token at startup:
+- Written to `.forge/dashboard.token` with mode 0600
+- All API endpoints require `X-Forge-Token` header
+- WebSocket connections require `?token=` query parameter
+- Token is cleaned up on server shutdown
+- `/api/health` is exempt (monitoring probes)
+
+### Same-Origin Protection
+
+The dashboard serves no CORS headers. Browsers enforce same-origin policy, meaning:
+- Only the dashboard UI (served from the same origin) can call the API
+- Cross-origin requests from malicious websites are blocked
+- The `/api/token` bootstrap endpoint is protected by same-origin policy
+
+### Why This Matters
+
+Without these protections, any website you visit could dispatch tasks to your forge agents via cross-origin API calls. Combined with agent permissions, this would allow arbitrary code execution. The session token + same-origin combination eliminates this attack vector.
+
+## Additional Security Measures
+
+### Agent Whitelist Validation
+
+All agent names go through strict whitelist validation before execution:
+
+```bash
+resolve_agent() {
+    local canonical="${AGENT_ALIASES[$normalized]:-}"
+    if [[ -n "$canonical" ]]; then
+        echo "$canonical"
+        return 0
+    fi
+    return 1  # Reject unknown agents
+}
+```
+
+### Path Traversal Protection
+
+Personality file paths are validated to remain within expected directories:
+
+```bash
+get_agent_personality_path() {
+    local real_path=$(cd "$(dirname "$personality_path")" && pwd)/$(basename "$personality_path")
+    local agents_dir=$(cd "$forge_root/agents" && pwd)
+    if [[ "$real_path" != "$agents_dir"/* ]]; then
+        echo "Security error: Path traversal detected" >&2
+        return 1
+    fi
+}
+```
+
+### Daemon Security
+
+The background daemon includes:
+- **Symlink protection**: Skips symlinks to prevent symlink attacks
+- **Path validation**: Verifies destinations within FORGE_ROOT
+- **Atomic operations**: Temp files + move for safe writes
+- **Lock files**: Prevents multiple daemon instances
+- **SQL escaping**: All database inputs go through `db_escape()`
+- **Input sanitization**: Frontmatter extraction strips shell metacharacters
+
+### Alias Collision Detection
+
+Agent alias collisions are checked at three levels:
+- Pre-commit hook (local development)
+- CI lint job (GitHub Actions)
+- `forge init` (project setup)
+
+## Risks to Be Aware Of
+
+1. **Allowlisted operations execute without confirmation** - agents can modify files, run tests, and push code
+2. **Prompt injection** - crafted task files or context could influence agent behavior
+3. **Heimdall is not exhaustive** - it enforces known policies, not all possible risks
+4. **Local network exposure** - the dashboard binds to localhost only; changing this has security implications
+
+## Recommendations
+
+1. **Use in development environments only**
+2. **Use with version control** - git makes it easy to review and revert
+3. **Review at checkpoints** - check agent work during task transitions
+4. **Keep project context secure** - don't include secrets in context files
+5. **Audit the allowlist** - review `.claude/settings.json` for your comfort level
+6. **Run in isolated environments** - consider containers for sensitive projects
+
+## Reporting Security Issues
+
+If you discover a security vulnerability in Vibe Forge:
+
+1. **Do not open a public issue**
+2. Email security concerns to the maintainers
+3. Include steps to reproduce
+4. Allow time for a fix before public disclosure
+
+## Security Checklist for Contributors
+
+When contributing to Vibe Forge:
+
+- [ ] Never pass user input directly to shell commands
+- [ ] Always validate agent names against the whitelist
+- [ ] Use safe JSON parsing (Node.js, not grep/cut)
+- [ ] Validate file paths don't traverse outside expected directories
+- [ ] Use atomic file operations where race conditions are possible
+- [ ] Add tests for security-sensitive functions
+- [ ] Document any new security considerations

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibe-forge",
-  "version": "0.4.0",
+  "version": "0.8.2",
   "description": "Multi-agent development orchestration system for terminal-native vibe coding",
   "keywords": [
     "vibe-coding",
@@ -13,38 +13,65 @@
     "terminal",
     "cli"
   ],
-  "author": "SpasticPalate",
+  "author": "sugar-crash-studios",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/SpasticPalate/vibe-forge.git"
+    "url": "git+https://github.com/sugar-crash-studios/vibe-forge.git"
   },
-  "homepage": "https://github.com/SpasticPalate/vibe-forge#readme",
+  "homepage": "https://github.com/sugar-crash-studios/vibe-forge#readme",
   "bugs": {
-    "url": "https://github.com/SpasticPalate/vibe-forge/issues"
+    "url": "https://github.com/sugar-crash-studios/vibe-forge/issues"
+  },
+  "publishConfig": {
+    "access": "public"
   },
   "bin": {
     "vibe-forge": "bin/cli.js"
   },
   "files": [
-    "bin/",
+    "bin/cli.js",
+    "src/lib/",
+    "bin/forge.cmd",
+    "bin/forge.sh",
+    "bin/forge-daemon.sh",
+    "bin/forge-setup.sh",
+    "bin/forge-spawn.sh",
+    "bin/dashboard/server.js",
+    "bin/dashboard/api/",
+    "bin/dashboard/public/",
     "agents/",
     "config/",
-    "context/",
-    "tasks/",
-    ".claude/",
-    "docs/"
+    "templates/project-context-template.md",
+    "context/architecture.md",
+    "context/modern-conventions.md",
+    "context/agent-overrides/README.md",
+    ".claude/commands/",
+    ".claude/hooks/",
+    ".claude/scripts/",
+    ".claude/settings.json",
+    "docs/security.md",
+    "docs/architecture.md",
+    "docs/agents.md",
+    "docs/commands.md"
   ],
   "scripts": {
+    "prepare": "husky",
     "test": "node --no-warnings node_modules/jest/bin/jest.js tests/unit/",
     "test:unit": "node --no-warnings node_modules/jest/bin/jest.js tests/unit/",
     "test:integration": "node --no-warnings node_modules/jest/bin/jest.js tests/integration/",
     "test:all": "node --no-warnings node_modules/jest/bin/jest.js tests/"
   },
   "devDependencies": {
-    "jest": "^30.0.0"
+    "husky": "^9.1.7",
+    "jest": "^30.0.0",
+    "ws": "^8.18.0"
   },
   "engines": {
     "node": ">=16.0.0"
+  },
+  "dependencies": {
+    "js-yaml": "^4.1.1",
+    "msedge-tts": "^2.0.4"
   }
 }

package/src/lib/check-aliases.js

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+/**
+ * Agent alias collision detector.
+ *
+ * Used by:
+ *   - .husky/pre-commit (pre-commit hook)
+ *   - .github/workflows/ci.yml (CI lint job)
+ *   - bin/cli.js validateAgentsConfig() (forge init)
+ *
+ * Exit code 0: no collisions
+ * Exit code 1: collisions found (printed to stderr)
+ */
+
+const path = require('path');
+const fs = require('fs');
+
+const configPath = process.argv[2] || path.join(__dirname, '..', '..', 'config', 'agents.json');
+
+if (!fs.existsSync(configPath)) {
+    // No agents.json is fine (e.g., fresh clone before setup)
+    process.exit(0);
+}
+
+let config;
+try {
+    config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+} catch (err) {
+    console.error(`ERROR: Failed to parse ${configPath}: ${err.message}`);
+    process.exit(1);
+}
+
+const agents = config.agents || {};
+const seen = {};
+const dupes = [];
+
+for (const [name, info] of Object.entries(agents)) {
+    for (const alias of [name, ...(info.aliases || [])]) {
+        if (seen[alias] && seen[alias] !== name) {
+            dupes.push(`${alias} (${seen[alias]} vs ${name})`);
+        }
+        seen[alias] = name;
+    }
+}
+
+if (dupes.length) {
+    console.error(`ERROR: Alias collision in agents.json: ${dupes.join(', ')}`);
+    process.exit(1);
+}
+
+console.log(`No alias collisions found (${Object.keys(agents).length} agents checked)`);

package/{bin → src}/lib/colors.sh

@@ -1,7 +1,8 @@
 #!/usr/bin/env bash
 #
 # Vibe Forge - Shared Color Definitions and Logging
-# Source this file in other scripts: source "$SCRIPT_DIR/lib/colors.sh"
+# Source this file in other scripts: source "$LIB_DIR/colors.sh"
+# NOTE: JavaScript equivalent exists in bin/cli.js:26-33. Keep in sync.
 #
 
 # Colors (only if terminal supports them)