vibe-forge 0.8.3 → 0.8.6

package/docs/security.md

@@ -1,195 +1,195 @@
-# 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
+# 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.8.3",
+  "version": "0.8.6",
   "description": "Multi-agent development orchestration system for terminal-native vibe coding",
   "keywords": [
     "vibe-coding",
@@ -71,7 +71,6 @@
     "node": ">=16.0.0"
   },
   "dependencies": {
-    "js-yaml": "^4.1.1",
-    "msedge-tts": "^2.0.4"
+    "js-yaml": "^4.1.1"
   }
 }