vibe-forge 0.3.12 → 0.8.1

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,48 +1,77 @@
-{
-  "name": "vibe-forge",
-  "version": "0.3.12",
-  "description": "Multi-agent development orchestration system for terminal-native vibe coding",
-  "keywords": [
-    "vibe-coding",
-    "claude",
-    "ai",
-    "agents",
-    "multi-agent",
-    "development",
-    "orchestration",
-    "terminal",
-    "cli"
-  ],
-  "author": "SpasticPalate",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/SpasticPalate/vibe-forge.git"
-  },
-  "homepage": "https://github.com/SpasticPalate/vibe-forge#readme",
-  "bugs": {
-    "url": "https://github.com/SpasticPalate/vibe-forge/issues"
-  },
-  "bin": {
-    "vibe-forge": "bin/cli.js"
-  },
-  "files": [
-    "bin/",
-    "agents/",
-    "config/",
-    "context/",
-    "tasks/",
-    ".claude/",
-    "docs/"
-  ],
-  "scripts": {
-    "test": "jest tests/js/",
-    "test:js": "jest tests/js/"
-  },
-  "devDependencies": {
-    "jest": "^30.0.0"
-  },
-  "engines": {
-    "node": ">=16.0.0"
-  }
-}
+{
+  "name": "vibe-forge",
+  "version": "0.8.1",
+  "description": "Multi-agent development orchestration system for terminal-native vibe coding",
+  "keywords": [
+    "vibe-coding",
+    "claude",
+    "ai",
+    "agents",
+    "multi-agent",
+    "development",
+    "orchestration",
+    "terminal",
+    "cli"
+  ],
+  "author": "sugar-crash-studios",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sugar-crash-studios/vibe-forge.git"
+  },
+  "homepage": "https://github.com/sugar-crash-studios/vibe-forge#readme",
+  "bugs": {
+    "url": "https://github.com/sugar-crash-studios/vibe-forge/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "vibe-forge": "bin/cli.js"
+  },
+  "files": [
+    "bin/cli.js",
+    "bin/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/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": {
+    "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/.claude/hooks/worker-loop.sh

@@ -1,141 +0,0 @@
-#!/usr/bin/env bash
-#
-# Vibe Forge Worker Loop - Stop Hook
-#
-# Implements the Ralph Loop technique for Vibe Forge workers.
-# When a worker tries to exit, this hook checks if there are pending tasks
-# and feeds the worker prompt back to continue working.
-#
-# Based on the Ralph Loop plugin by Anthropic.
-#
-# Activation modes:
-# 1. Config-based: worker_loop_enabled=true in .forge/config.json
-# 2. Runtime: State file created by /worker-loop command
-#
-
-set -euo pipefail
-
-# State file location (runtime toggle)
-STATE_FILE="${CLAUDE_LOCAL_DIR:-$HOME/.claude}/forge-worker-loop.json"
-FORGE_ROOT="${FORGE_ROOT:-$(pwd)}"
-
-# Check for runtime state file first (takes precedence)
-LOOP_ACTIVE=false
-WORKER_AGENT=""
-MAX_IDLE_CHECKS=10
-IDLE_COUNT=0
-POLL_INTERVAL=5
-
-if [[ -f "$STATE_FILE" ]]; then
-    LOOP_ACTIVE=true
-    WORKER_AGENT=$(jq -r '.agent // ""' "$STATE_FILE" 2>/dev/null || echo "")
-    MAX_IDLE_CHECKS=$(jq -r '.max_idle_checks // 10' "$STATE_FILE" 2>/dev/null || echo "10")
-    IDLE_COUNT=$(jq -r '.idle_count // 0' "$STATE_FILE" 2>/dev/null || echo "0")
-    POLL_INTERVAL=$(jq -r '.poll_interval // 5' "$STATE_FILE" 2>/dev/null || echo "5")
-fi
-
-# If no runtime state, check config-based setting
-if [[ "$LOOP_ACTIVE" == "false" ]]; then
-    CONFIG_FILE="$FORGE_ROOT/.forge/config.json"
-    if [[ -f "$CONFIG_FILE" ]]; then
-        CONFIG_ENABLED=$(jq -r '.worker_loop_enabled // false' "$CONFIG_FILE" 2>/dev/null || echo "false")
-        if [[ "$CONFIG_ENABLED" == "true" ]]; then
-            LOOP_ACTIVE=true
-            # For config-based, use "any" to match any worker
-            WORKER_AGENT="any"
-        fi
-    fi
-fi
-
-# Check if worker loop is active
-if [[ "$LOOP_ACTIVE" == "false" ]]; then
-    # No active loop, allow exit
-    echo '{"decision": "allow"}'
-    exit 0
-fi
-
-if [[ -z "$WORKER_AGENT" ]]; then
-    # Invalid state, clean up and allow exit
-    rm -f "$STATE_FILE" 2>/dev/null || true
-    echo '{"decision": "allow"}'
-    exit 0
-fi
-
-# Check for pending tasks (assigned to specific worker or any worker)
-TASKS_DIR="$FORGE_ROOT/tasks"
-PENDING_COUNT=0
-NEEDS_CHANGES_COUNT=0
-
-if [[ -d "$TASKS_DIR/pending" ]]; then
-    if [[ "$WORKER_AGENT" == "any" ]]; then
-        # Config mode: count all pending tasks
-        PENDING_COUNT=$(find "$TASKS_DIR/pending" -name "*.md" 2>/dev/null | wc -l || echo "0")
-    else
-        # Runtime mode: count only tasks assigned to specific worker
-        PENDING_COUNT=$(grep -l "assigned_to:.*$WORKER_AGENT" "$TASKS_DIR/pending/"*.md 2>/dev/null | wc -l || echo "0")
-    fi
-fi
-
-if [[ -d "$TASKS_DIR/needs-changes" ]]; then
-    if [[ "$WORKER_AGENT" == "any" ]]; then
-        # Config mode: count all needs-changes tasks
-        NEEDS_CHANGES_COUNT=$(find "$TASKS_DIR/needs-changes" -name "*.md" 2>/dev/null | wc -l || echo "0")
-    else
-        # Runtime mode: count only tasks assigned to specific worker
-        NEEDS_CHANGES_COUNT=$(grep -l "assigned_to:.*$WORKER_AGENT" "$TASKS_DIR/needs-changes/"*.md 2>/dev/null | wc -l || echo "0")
-    fi
-fi
-
-TOTAL_TASKS=$((PENDING_COUNT + NEEDS_CHANGES_COUNT))
-
-if [[ "$TOTAL_TASKS" -gt 0 ]]; then
-    # Tasks found! Reset idle counter and continue
-    if [[ -f "$STATE_FILE" ]]; then
-        jq --argjson idle 0 '.idle_count = $idle' "$STATE_FILE" > "$STATE_FILE.tmp" && mv "$STATE_FILE.tmp" "$STATE_FILE"
-    fi
-
-    # Block exit and feed prompt to continue working
-    cat << EOF
-{
-    "decision": "block",
-    "message": "[Forge Loop] Found $TOTAL_TASKS pending task(s). Continuing work...",
-    "prompt": "Check tasks/pending/ and tasks/needs-changes/ for tasks assigned to you and begin working on them immediately."
-}
-EOF
-    exit 0
-fi
-
-# No tasks - increment idle counter (only for runtime mode with state file)
-if [[ -f "$STATE_FILE" ]]; then
-    IDLE_COUNT=$((IDLE_COUNT + 1))
-    jq --argjson idle "$IDLE_COUNT" '.idle_count = $idle' "$STATE_FILE" > "$STATE_FILE.tmp" && mv "$STATE_FILE.tmp" "$STATE_FILE"
-
-    if [[ "$IDLE_COUNT" -ge "$MAX_IDLE_CHECKS" ]]; then
-        # Max idle checks reached, clean up and allow exit
-        rm -f "$STATE_FILE"
-        cat << EOF
-{
-    "decision": "allow",
-    "message": "[Forge Loop] No tasks found after $MAX_IDLE_CHECKS checks. Exiting."
-}
-EOF
-        exit 0
-    fi
-
-    # Still within idle limit - wait and check again
-    cat << EOF
-{
-    "decision": "block",
-    "message": "[Forge Loop] No tasks available. Idle check $IDLE_COUNT/$MAX_IDLE_CHECKS. Waiting...",
-    "prompt": "No tasks currently assigned to you. Wait briefly, then check tasks/pending/ and tasks/needs-changes/ again for new work. If still no tasks, announce you are idle and ready."
-}
-EOF
-else
-    # Config-based mode - no idle tracking, just allow exit when no tasks
-    cat << EOF
-{
-    "decision": "allow",
-    "message": "[Forge Loop] No pending tasks. Worker exiting."
-}
-EOF
-fi

package/.claude/settings.local.json

@@ -1,29 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(ls:*)",
-      "Bash(git pull:*)",
-      "Bash(npm view:*)",
-      "Bash(gh run list:*)",
-      "Bash(gh run view:*)",
-      "Bash(gh secret list:*)",
-      "Bash(git add:*)",
-      "Bash(git commit:*)",
-      "Bash(gh workflow run:*)",
-      "Bash(gh repo view:*)"
-    ]
-  },
-  "hooks": {
-    "Stop": [
-      {
-        "matcher": "",
-        "hooks": [
-          {
-            "type": "command",
-            "command": ".claude/hooks/worker-loop.sh"
-          }
-        ]
-      }
-    ]
-  }
-}