@ipul-labs/forge 1.16.6 → 1.16.8

package/README.md

@@ -252,6 +252,25 @@ FORGE_REPOS=gitlab:ipul/web-app,github:my-org/mobile
 
 ---
 
+## Security
+
+Forge is designed for self-hosted deployment on trusted infrastructure. Security measures in place:
+
+- **Timing-safe auth** — token comparison uses `crypto.timingSafeEqual` to prevent timing attacks
+- **Rate limiting** — API endpoints are rate-limited (60 req/min per IP) to prevent brute-force
+- **Security headers** — Helmet middleware sets X-Frame-Options, HSTS, X-Content-Type-Options, and CSP (production)
+- **Request size limits** — JSON body capped at 1MB to prevent memory exhaustion
+- **Secret redaction** — error logs and API responses scrub tokens (`glpat-*`, `ghp_*`, `oauth2:*@`) before output
+- **File permissions** — config files (`~/.forge/config.json`) written with `0600`, session directories with `0700`
+- **Git credential isolation** — SCM tokens passed via `GIT_ASKPASS` helper, never embedded in clone URLs
+- **Path traversal protection** — symlink-aware `realpath` checks prevent file writes outside clone directories
+- **No shell injection** — all subprocess calls use `spawn()` with argument arrays, never shell strings
+- **Atomic config writes** — config updates use temp file + rename to prevent corruption
+
+`FORGE_TOKEN` is a standalone dashboard password — never reuse an SCM token for this value.
+
+---
+
 ## Production deployment
 
 ```bash

package/bin/cli/sessionStore.js

@@ -48,17 +48,14 @@ export function sessionDir(repo, iid) {
 }
 
 async function ensureDir(dir) {
-	await fs.mkdir(dir, { recursive: true });
+	await fs.mkdir(dir, { recursive: true, mode: 0o700 });
 }
 
 export async function writeAnalysis(repo, iid, analysis) {
 	const dir = sessionDir(repo, iid);
 	await ensureDir(dir);
-	await fs.writeFile(
-		path.join(dir, "analysis.json"),
-		JSON.stringify(analysis, null, 2),
-		"utf8",
-	);
+	const file = path.join(dir, "analysis.json");
+	await fs.writeFile(file, JSON.stringify(analysis, null, 2), { encoding: "utf8", mode: 0o600 });
 }
 
 export async function readAnalysis(repo, iid) {
@@ -84,7 +81,7 @@ export async function updateState(repo, iid, partial) {
 		createdAt: now,
 	};
 	const next = { ...prev, ...partial, updatedAt: now };
-	await fs.writeFile(file, JSON.stringify(next, null, 2), "utf8");
+	await fs.writeFile(file, JSON.stringify(next, null, 2), { encoding: "utf8", mode: 0o600 });
 	return next;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ipul-labs/forge",
-  "version": "1.16.6",
+  "version": "1.16.8",
   "description": "AI-powered code change & deploy control panel — connects Claude, GitLab, and Kubernetes",
   "readmeFilename": "README.md",
   "type": "module",
@@ -34,6 +34,8 @@
     "diff": "^9.0.0",
     "dotenv": "^16.6.1",
     "express": "^4.21.0",
+    "express-rate-limit": "^8.5.1",
+    "helmet": "^8.1.0",
     "htm": "^3.1.1",
     "ink": "^7.0.1",
     "ink-select-input": "^6.2.0",
@@ -81,5 +83,5 @@
     "url": "git+https://gitlab.com/ipul-labs/forge.git"
   },
   "license": "MIT",
-  "readme": "# Forge by iPuL\n\nAI-powered code change & deploy control panel. Connect an issue tracker, let Claude propose a fix, review the diff, approve — and Forge creates the branch, commits the changes, opens the MR/PR, and monitors the CI pipeline.\n\nBuilt on: Claude Code CLI · GitLab / GitHub / Azure DevOps · Kubernetes\n\n---\n\n## Why Forge\n\n**The CI refinement loop is the thing.** Every other AI coding tool hands off after the PR is open. Forge keeps going: when your pipeline fails, it grabs the last 150 lines of the failed job log, feeds them back to Claude with the original fix context, generates a targeted patch, and commits it to the branch — automatically. No human has to read the stack trace, translate it into a prompt, and paste it somewhere. The loop closes itself.\n\nEverything else fills in the gaps that matter for real teams:\n\n- **No per-token cost** — Claude runs via the `claude` CLI using your existing Claude subscription, not API credits. Heavy use doesn't trigger a bill.\n- **Multi-provider** — GitLab, GitHub, and Azure DevOps are all first-class. Switch providers with a single env var; all normalized data shapes stay the same.\n- **Self-hosted** — your code never leaves your infrastructure. The backend runs wherever you deploy it; AI calls go to Anthropic (or a local gateway via OpenClaw).\n- **Two-pass analysis keeps context focused** — Claude first identifies the 6 most relevant files, then reads only those when proposing the fix. This produces sharper diffs than dumping the whole repo into one prompt.\n\n---\n\n## How it works\n\n1. **Connect** — enter your Forge token to authenticate\n2. **Pick an issue** — Forge loads open issues from your project\n3. **Analyze** — Claude reads the repo file tree, identifies relevant files, and proposes a targeted fix\n4. **Review** — inspect the diff file-by-file; refine with natural-language feedback if needed\n5. **Apply** — Forge creates a branch, commits all changes, and opens a merge/pull request\n6. **Monitor** — watch the CI pipeline run; if it fails, click \"Fix with AI\" to iterate\n\n---\n\n## Getting started\n\n### Prerequisites\n\n- Node.js 20+\n- `claude` CLI installed and authenticated (`claude auth login`)\n- Credentials for your SCM provider (see [Configuration](#configuration))\n\n### Install\n\n```bash\ngit clone https://gitlab.com/ipul-labs/forge.git\ncd forge\nnpm install\n```\n\n### Configure\n\n```bash\n# Interactive setup — writes .env and ~/.forge/config.json\nnpx forge init\n```\n\nOr copy the example env and fill in the values manually:\n\n```bash\ncp .env.example .env\n# fill in FORGE_TOKEN plus your provider credentials\n```\n\n### Launch the UI\n\n```bash\nnpm run dev\n# opens http://localhost:5000 (frontend) with API on :5001\n```\n\nFor production:\n\n```bash\nnpm run build:app   # builds Vite SPA to dist/\nnpm start           # NODE_ENV=production node server.js\n```\n\n### CLI usage\n\nThe `forge` CLI drives the same orchestrator from the terminal. Install globally or use `npx`:\n\n```bash\n# Global install (adds `forge` to PATH)\nnpm install -g @ipul-labs/forge\n\n# Or run via npx from the repo\nnpx forge <command>\n```\n\n#### Interactive mode\n\nRun `forge` with no arguments to enter an interactive terminal session:\n\n```bash\nforge\n```\n\n```\n  forge v1.15.1\n\n──────────────────────────────────────────────────\n ❯ issues --limit 5\n──────────────────────────────────────────────────\n group/repo  |  agent:claude  |  v1.15.1\n```\n\nTab-completes command names. Type `use <repo>` to switch repos. Commands that error stay in the session — only `exit`, `quit`, or Ctrl+D leave.\n\n#### End-to-end: issue to production\n\n```bash\nforge ship 42\n```\n\nRuns: analyze → review → validate → apply → watch CI → merge → watch deploy → close, with a `y/N` gate at every state-changing step.\n\n#### Step-by-step commands\n\n```bash\nforge issues                   # List open issues (--label X, --mine, --limit N)\nforge issue 42                 # Show full description\nforge create-issue --title \"fix: broken widget\"  # Create a new issue\nforge analyze 42               # Run two-pass analysis, cache result\nforge show                     # Re-render cached analysis\nforge refine --feedback \"...\"  # Iterate with feedback\nforge validate                 # Run lint/typecheck/test against proposed changes\nforge apply                    # Push branch + open MR\nforge watch                    # Poll the MR pipeline\nforge ci-fix                   # Re-analyze with failed-pipeline logs\nforge merge                    # Merge the MR\nforge resolution-check         # Verify merged MR closes the issue\nforge close                    # Close the issue\nforge use group/other-repo     # Switch active repo\nforge update                   # Pull latest + reinstall dependencies\n```\n\n#### Options\n\n```\n-p, --port <n>           Port for start\n--repo <group/repo>      Primary repo\n--secondary <repo>       Additional repo (repeatable)\n--all-repos              Include every configured repo\n--model <id>             Claude model override\n--agent <name>           Agent backend: claude | openclaw\n--prompt <text>          Extra user prompt\n--json                   JSON output\n--quiet                  Suppress progress\n--yes                    Skip confirmation gates\n--validate               Run validate before apply\n```\n\n#### Diagnostics\n\n```bash\nforge doctor             # Check prerequisites (node, claude CLI, env vars)\nforge session list       # List cached sessions\nforge session clean      # Remove stale session data\n```\n\nSee [`docs/cli.md`](./docs/cli.md) for the full command reference and [`docs/cli-ship-workflow.md`](./docs/cli-ship-workflow.md) for the workflow design.\n\n---\n\n## Configuration\n\n### Core\n\n| Variable | Required | Description |\n|---|---|---|\n| `FORGE_TOKEN` | Yes | Dashboard password — also auto-fills the UI login form |\n| `FORGE_REPOS` | Yes | Comma-separated repo list; first entry is the primary project |\n| `SCM_PROVIDER` | — | `gitlab` (default) · `github` · `azuredevops` |\n| `ANTHROPIC_API_KEY` | — | Enables live model list from Anthropic; falls back to hardcoded list |\n| `FORGE_MODEL` | — | Override default model (default: `claude-sonnet-4-6`) |\n| `K8S_CLUSTER_TOKEN` | — | K8s service account token for rollout monitoring |\n| `K8S_CLUSTER_SERVER` | — | K8s API server URL |\n| `PORT` | — | HTTP server port (default: `5001`) |\n| `OPENCLAW_GATEWAY_URL` | — | Enables OpenClaw agent backend; point at your local Gateway |\n| `OPENCLAW_TOKEN` | — | Bearer token for OpenClaw Gateway auth |\n\n### Provider credentials\n\nSCM tokens can be set here **or** in the Forge Settings UI (Settings → Connections). The UI value takes precedence over env vars.\n\n#### GitLab (`SCM_PROVIDER=gitlab`, default)\n\n| Variable | Required | Description |\n|---|---|---|\n| `GITLAB_TOKEN` | Yes | Personal access token with `api` + `write_repository` scopes |\n\n#### GitHub (`SCM_PROVIDER=github`)\n\n| Variable | Required | Description |\n|---|---|---|\n| `GITHUB_TOKEN` | Yes | Personal access token with `repo` + `workflow` scopes |\n| `GITHUB_OWNER` | Yes | Organization or user, e.g. `ipul-labs` |\n| `GITHUB_REPO` | Yes | Repository name, e.g. `web-app` |\n| `GITHUB_BASE_BRANCH` | — | Default target branch (default: `main`) |\n\n#### Azure DevOps (`SCM_PROVIDER=azuredevops`)\n\n| Variable | Required | Description |\n|---|---|---|\n| `AZURE_DEVOPS_TOKEN` | Yes | Personal access token (Full access or Code + Work Items) |\n| `AZURE_DEVOPS_ORG` | Yes | Organization name, e.g. `ipul-labs` |\n| `AZURE_DEVOPS_PROJECT` | Yes | Team project name, e.g. `web-app` |\n| `AZURE_DEVOPS_REPO` | — | Git repo name (defaults to project name) |\n| `AZURE_DEVOPS_BASE_BRANCH` | — | Default target branch (default: `main`) |\n\n### Deprecated (still work as fallbacks)\n\n| Variable | Replaced by |\n|---|---|\n| `FORGE_GITLAB_PROJECT` | First entry in `FORGE_REPOS` |\n| `VITE_FORGE_TOKEN` | Auto-derived from `FORGE_TOKEN` |\n| `FORGE_REFINE_REPO_ACCESS` | Settings UI toggle (Settings → Defaults) |\n\nSee `.env.example` for a full annotated list.\n\n---\n\n## Multi-provider support\n\nForge's SCM layer is a clean provider abstraction — all three providers implement the same `ScmProvider` interface and return identical normalized shapes (`NormalIssue`, `NormalMR`, `NormalPipeline`, etc.). The rest of the codebase never knows which provider is active.\n\n### Switching providers\n\n```bash\n# .env\nSCM_PROVIDER=github\nGITHUB_TOKEN=ghp_...\nGITHUB_OWNER=my-org\nGITHUB_REPO=my-repo\n```\n\n### Per-repo prefix (multi-repo mixed-provider setups)\n\n```bash\nFORGE_REPOS=gitlab:ipul/web-app,github:my-org/mobile\n```\n\n### Provider capabilities\n\n| Feature | GitLab | GitHub | Azure DevOps |\n|---|---|---|---|\n| Issues / Work Items | Yes | Yes | Yes (Work Items) |\n| Multi-file commits | Yes | Yes (Git Data API) | Yes (Pushes API) |\n| Merge / Pull Requests | Yes | Yes | Yes |\n| CI pipelines | Yes (GitLab CI) | Yes (GitHub Actions) | Yes (Azure Pipelines) |\n| Job log traces | Yes | Yes | Yes |\n| Server-side rebase | Yes | — | — |\n\n---\n\n## Production deployment\n\n```bash\nnpm run build:app      # builds Vite SPA to dist/\nNODE_ENV=production node server.js\n```\n\nOr with Docker:\n\n```bash\ndocker build -t forge .\ndocker run -p 5001:5001 --env-file .env forge\n```\n\n---\n\n## Architecture\n\n```\nbin/\n  forge-agent.js        # CLI entry point (forge command)\n  cli/\n    ship.js             # End-to-end orchestrator (Ink UI)\n    analyze.js          # Two-pass issue analysis\n    resolution.js       # Post-merge resolution check\n    sessionStore.js     # ~/.forge/sessions/ persistence\n    ...\n\nserver/\n  forge/\n    routes.js           # Express router — all /api/forge/* endpoints\n    core/\n      ForgeAgent.js     # Orchestrates the full pipeline (analyze -> apply -> refine)\n      claudeClient.js   # Shells out to the claude CLI for structured output\n      openclawClient.js # OpenClaw Gateway HTTP client\n      agentClient.js    # Dispatcher: routes to claudeClient or openclawClient\n      k8s.js            # Kubernetes client for rollout monitoring\n      providers/\n        base.js         # Abstract ScmProvider — normalized shapes + interface\n        gitlab.js       # GitLab REST API v4\n        github.js       # GitHub REST API v3 + Git Data API\n        azuredevops.js  # Azure DevOps REST API\n        index.js        # createProvider() factory\n\nsrc/\n  views/Forge/\n    ForgeDashboard.tsx      # Root UI component with tabbed issue/MR views\n    api.ts                  # Token management + fetch helper\n    types.ts                # Shared TypeScript types\n    utils.ts                # SSE helper + state utilities\n    components/             # Analysis progress, pipeline status, diff viewer\n    hooks/\n      useForgeDashboard.ts  # All state, phase transitions, and API calls\n```\n\n### Two-pass analysis\n\n**Pass 1** — `identifyRelevantFiles`: Claude reads the issue + file tree, returns the max-6 most relevant paths.\n\n**Pass 2** — `proposeFix`: Claude reads the actual file contents and proposes a targeted fix as a JSON diff.\n\nBoth passes use `claude --print --output-format json` so cost and service tier are tracked automatically.\n\n### CI refinement\n\nWhen a pipeline fails, Forge fetches the last 150 lines of each failed job's trace log and feeds them to pass 2 with an explicit \"pipeline failed\" framing — not generic reviewer feedback. This improves fix quality for common failures like lint errors and type errors.\n\n### Provider abstraction\n\nAll three SCM providers implement `ScmProvider` from `providers/base.js`. The contract is:\n- **Normalized return types** — all methods return `NormalIssue`, `NormalMR`, `NormalPipeline`, etc., regardless of provider\n- **Instance-scoped** — each provider is instantiated with a repo string; no global state\n- **`supportsRebase`** — providers that don't support server-side rebase return `false`; the UI and API layer check this before showing the rebase button\n\n---\n\n## Programmatic usage\n\nMount the Forge Express router or use the core classes directly:\n\n```js\nimport forgeRouter from \"@ipul-labs/forge\";             // Express router\nimport { ForgeAgent } from \"@ipul-labs/forge/agent\";    // Core pipeline class\nimport { createProvider } from \"@ipul-labs/forge/providers\"; // SCM factory\n```\n\n```js\nconst agent = new ForgeAgent({ project: \"group/repo\" });\nconst result = await agent.analyzeIssue(42, (event) => console.log(event));\nconst { branchName, mr } = await agent.applyFix(result);\n```\n\n---\n\n## License\n\nMIT\n"
+  "readme": "# Forge by iPuL\n\nAI-powered code change & deploy control panel. Connect an issue tracker, let Claude propose a fix, review the diff, approve — and Forge creates the branch, commits the changes, opens the MR/PR, and monitors the CI pipeline.\n\nBuilt on: Claude Code CLI · GitLab / GitHub / Azure DevOps · Kubernetes\n\n---\n\n## Why Forge\n\n**The CI refinement loop is the thing.** Every other AI coding tool hands off after the PR is open. Forge keeps going: when your pipeline fails, it grabs the last 150 lines of the failed job log, feeds them back to Claude with the original fix context, generates a targeted patch, and commits it to the branch — automatically. No human has to read the stack trace, translate it into a prompt, and paste it somewhere. The loop closes itself.\n\nEverything else fills in the gaps that matter for real teams:\n\n- **No per-token cost** — Claude runs via the `claude` CLI using your existing Claude subscription, not API credits. Heavy use doesn't trigger a bill.\n- **Multi-provider** — GitLab, GitHub, and Azure DevOps are all first-class. Switch providers with a single env var; all normalized data shapes stay the same.\n- **Self-hosted** — your code never leaves your infrastructure. The backend runs wherever you deploy it; AI calls go to Anthropic (or a local gateway via OpenClaw).\n- **Two-pass analysis keeps context focused** — Claude first identifies the 6 most relevant files, then reads only those when proposing the fix. This produces sharper diffs than dumping the whole repo into one prompt.\n\n---\n\n## How it works\n\n1. **Connect** — enter your Forge token to authenticate\n2. **Pick an issue** — Forge loads open issues from your project\n3. **Analyze** — Claude reads the repo file tree, identifies relevant files, and proposes a targeted fix\n4. **Review** — inspect the diff file-by-file; refine with natural-language feedback if needed\n5. **Apply** — Forge creates a branch, commits all changes, and opens a merge/pull request\n6. **Monitor** — watch the CI pipeline run; if it fails, click \"Fix with AI\" to iterate\n\n---\n\n## Getting started\n\n### Prerequisites\n\n- Node.js 20+\n- `claude` CLI installed and authenticated (`claude auth login`)\n- Credentials for your SCM provider (see [Configuration](#configuration))\n\n### Install\n\n```bash\ngit clone https://gitlab.com/ipul-labs/forge.git\ncd forge\nnpm install\n```\n\n### Configure\n\n```bash\n# Interactive setup — writes .env and ~/.forge/config.json\nnpx forge init\n```\n\nOr copy the example env and fill in the values manually:\n\n```bash\ncp .env.example .env\n# fill in FORGE_TOKEN plus your provider credentials\n```\n\n### Launch the UI\n\n```bash\nnpm run dev\n# opens http://localhost:5000 (frontend) with API on :5001\n```\n\nFor production:\n\n```bash\nnpm run build:app   # builds Vite SPA to dist/\nnpm start           # NODE_ENV=production node server.js\n```\n\n### CLI usage\n\nThe `forge` CLI drives the same orchestrator from the terminal. Install globally or use `npx`:\n\n```bash\n# Global install (adds `forge` to PATH)\nnpm install -g @ipul-labs/forge\n\n# Or run via npx from the repo\nnpx forge <command>\n```\n\n#### Interactive mode\n\nRun `forge` with no arguments to enter an interactive terminal session:\n\n```bash\nforge\n```\n\n```\n  forge v1.15.1\n\n──────────────────────────────────────────────────\n ❯ issues --limit 5\n──────────────────────────────────────────────────\n group/repo  |  agent:claude  |  v1.15.1\n```\n\nTab-completes command names. Type `use <repo>` to switch repos. Commands that error stay in the session — only `exit`, `quit`, or Ctrl+D leave.\n\n#### End-to-end: issue to production\n\n```bash\nforge ship 42\n```\n\nRuns: analyze → review → validate → apply → watch CI → merge → watch deploy → close, with a `y/N` gate at every state-changing step.\n\n#### Step-by-step commands\n\n```bash\nforge issues                   # List open issues (--label X, --mine, --limit N)\nforge issue 42                 # Show full description\nforge create-issue --title \"fix: broken widget\"  # Create a new issue\nforge analyze 42               # Run two-pass analysis, cache result\nforge show                     # Re-render cached analysis\nforge refine --feedback \"...\"  # Iterate with feedback\nforge validate                 # Run lint/typecheck/test against proposed changes\nforge apply                    # Push branch + open MR\nforge watch                    # Poll the MR pipeline\nforge ci-fix                   # Re-analyze with failed-pipeline logs\nforge merge                    # Merge the MR\nforge resolution-check         # Verify merged MR closes the issue\nforge close                    # Close the issue\nforge use group/other-repo     # Switch active repo\nforge update                   # Pull latest + reinstall dependencies\n```\n\n#### Options\n\n```\n-p, --port <n>           Port for start\n--repo <group/repo>      Primary repo\n--secondary <repo>       Additional repo (repeatable)\n--all-repos              Include every configured repo\n--model <id>             Claude model override\n--agent <name>           Agent backend: claude | openclaw\n--prompt <text>          Extra user prompt\n--json                   JSON output\n--quiet                  Suppress progress\n--yes                    Skip confirmation gates\n--validate               Run validate before apply\n```\n\n#### Diagnostics\n\n```bash\nforge doctor             # Check prerequisites (node, claude CLI, env vars)\nforge session list       # List cached sessions\nforge session clean      # Remove stale session data\n```\n\nSee [`docs/cli.md`](./docs/cli.md) for the full command reference and [`docs/cli-ship-workflow.md`](./docs/cli-ship-workflow.md) for the workflow design.\n\n---\n\n## Configuration\n\n### Core\n\n| Variable | Required | Description |\n|---|---|---|\n| `FORGE_TOKEN` | Yes | Dashboard password — also auto-fills the UI login form |\n| `FORGE_REPOS` | Yes | Comma-separated repo list; first entry is the primary project |\n| `SCM_PROVIDER` | — | `gitlab` (default) · `github` · `azuredevops` |\n| `ANTHROPIC_API_KEY` | — | Enables live model list from Anthropic; falls back to hardcoded list |\n| `FORGE_MODEL` | — | Override default model (default: `claude-sonnet-4-6`) |\n| `K8S_CLUSTER_TOKEN` | — | K8s service account token for rollout monitoring |\n| `K8S_CLUSTER_SERVER` | — | K8s API server URL |\n| `PORT` | — | HTTP server port (default: `5001`) |\n| `OPENCLAW_GATEWAY_URL` | — | Enables OpenClaw agent backend; point at your local Gateway |\n| `OPENCLAW_TOKEN` | — | Bearer token for OpenClaw Gateway auth |\n\n### Provider credentials\n\nSCM tokens can be set here **or** in the Forge Settings UI (Settings → Connections). The UI value takes precedence over env vars.\n\n#### GitLab (`SCM_PROVIDER=gitlab`, default)\n\n| Variable | Required | Description |\n|---|---|---|\n| `GITLAB_TOKEN` | Yes | Personal access token with `api` + `write_repository` scopes |\n\n#### GitHub (`SCM_PROVIDER=github`)\n\n| Variable | Required | Description |\n|---|---|---|\n| `GITHUB_TOKEN` | Yes | Personal access token with `repo` + `workflow` scopes |\n| `GITHUB_OWNER` | Yes | Organization or user, e.g. `ipul-labs` |\n| `GITHUB_REPO` | Yes | Repository name, e.g. `web-app` |\n| `GITHUB_BASE_BRANCH` | — | Default target branch (default: `main`) |\n\n#### Azure DevOps (`SCM_PROVIDER=azuredevops`)\n\n| Variable | Required | Description |\n|---|---|---|\n| `AZURE_DEVOPS_TOKEN` | Yes | Personal access token (Full access or Code + Work Items) |\n| `AZURE_DEVOPS_ORG` | Yes | Organization name, e.g. `ipul-labs` |\n| `AZURE_DEVOPS_PROJECT` | Yes | Team project name, e.g. `web-app` |\n| `AZURE_DEVOPS_REPO` | — | Git repo name (defaults to project name) |\n| `AZURE_DEVOPS_BASE_BRANCH` | — | Default target branch (default: `main`) |\n\n### Deprecated (still work as fallbacks)\n\n| Variable | Replaced by |\n|---|---|\n| `FORGE_GITLAB_PROJECT` | First entry in `FORGE_REPOS` |\n| `VITE_FORGE_TOKEN` | Auto-derived from `FORGE_TOKEN` |\n| `FORGE_REFINE_REPO_ACCESS` | Settings UI toggle (Settings → Defaults) |\n\nSee `.env.example` for a full annotated list.\n\n---\n\n## Multi-provider support\n\nForge's SCM layer is a clean provider abstraction — all three providers implement the same `ScmProvider` interface and return identical normalized shapes (`NormalIssue`, `NormalMR`, `NormalPipeline`, etc.). The rest of the codebase never knows which provider is active.\n\n### Switching providers\n\n```bash\n# .env\nSCM_PROVIDER=github\nGITHUB_TOKEN=ghp_...\nGITHUB_OWNER=my-org\nGITHUB_REPO=my-repo\n```\n\n### Per-repo prefix (multi-repo mixed-provider setups)\n\n```bash\nFORGE_REPOS=gitlab:ipul/web-app,github:my-org/mobile\n```\n\n### Provider capabilities\n\n| Feature | GitLab | GitHub | Azure DevOps |\n|---|---|---|---|\n| Issues / Work Items | Yes | Yes | Yes (Work Items) |\n| Multi-file commits | Yes | Yes (Git Data API) | Yes (Pushes API) |\n| Merge / Pull Requests | Yes | Yes | Yes |\n| CI pipelines | Yes (GitLab CI) | Yes (GitHub Actions) | Yes (Azure Pipelines) |\n| Job log traces | Yes | Yes | Yes |\n| Server-side rebase | Yes | — | — |\n\n---\n\n## Security\n\nForge is designed for self-hosted deployment on trusted infrastructure. Security measures in place:\n\n- **Timing-safe auth** — token comparison uses `crypto.timingSafeEqual` to prevent timing attacks\n- **Rate limiting** — API endpoints are rate-limited (60 req/min per IP) to prevent brute-force\n- **Security headers** — Helmet middleware sets X-Frame-Options, HSTS, X-Content-Type-Options, and CSP (production)\n- **Request size limits** — JSON body capped at 1MB to prevent memory exhaustion\n- **Secret redaction** — error logs and API responses scrub tokens (`glpat-*`, `ghp_*`, `oauth2:*@`) before output\n- **File permissions** — config files (`~/.forge/config.json`) written with `0600`, session directories with `0700`\n- **Git credential isolation** — SCM tokens passed via `GIT_ASKPASS` helper, never embedded in clone URLs\n- **Path traversal protection** — symlink-aware `realpath` checks prevent file writes outside clone directories\n- **No shell injection** — all subprocess calls use `spawn()` with argument arrays, never shell strings\n- **Atomic config writes** — config updates use temp file + rename to prevent corruption\n\n`FORGE_TOKEN` is a standalone dashboard password — never reuse an SCM token for this value.\n\n---\n\n## Production deployment\n\n```bash\nnpm run build:app      # builds Vite SPA to dist/\nNODE_ENV=production node server.js\n```\n\nOr with Docker:\n\n```bash\ndocker build -t forge .\ndocker run -p 5001:5001 --env-file .env forge\n```\n\n---\n\n## Architecture\n\n```\nbin/\n  forge-agent.js        # CLI entry point (forge command)\n  cli/\n    ship.js             # End-to-end orchestrator (Ink UI)\n    analyze.js          # Two-pass issue analysis\n    resolution.js       # Post-merge resolution check\n    sessionStore.js     # ~/.forge/sessions/ persistence\n    ...\n\nserver/\n  forge/\n    routes.js           # Express router — all /api/forge/* endpoints\n    core/\n      ForgeAgent.js     # Orchestrates the full pipeline (analyze -> apply -> refine)\n      claudeClient.js   # Shells out to the claude CLI for structured output\n      openclawClient.js # OpenClaw Gateway HTTP client\n      agentClient.js    # Dispatcher: routes to claudeClient or openclawClient\n      k8s.js            # Kubernetes client for rollout monitoring\n      providers/\n        base.js         # Abstract ScmProvider — normalized shapes + interface\n        gitlab.js       # GitLab REST API v4\n        github.js       # GitHub REST API v3 + Git Data API\n        azuredevops.js  # Azure DevOps REST API\n        index.js        # createProvider() factory\n\nsrc/\n  views/Forge/\n    ForgeDashboard.tsx      # Root UI component with tabbed issue/MR views\n    api.ts                  # Token management + fetch helper\n    types.ts                # Shared TypeScript types\n    utils.ts                # SSE helper + state utilities\n    components/             # Analysis progress, pipeline status, diff viewer\n    hooks/\n      useForgeDashboard.ts  # All state, phase transitions, and API calls\n```\n\n### Two-pass analysis\n\n**Pass 1** — `identifyRelevantFiles`: Claude reads the issue + file tree, returns the max-6 most relevant paths.\n\n**Pass 2** — `proposeFix`: Claude reads the actual file contents and proposes a targeted fix as a JSON diff.\n\nBoth passes use `claude --print --output-format json` so cost and service tier are tracked automatically.\n\n### CI refinement\n\nWhen a pipeline fails, Forge fetches the last 150 lines of each failed job's trace log and feeds them to pass 2 with an explicit \"pipeline failed\" framing — not generic reviewer feedback. This improves fix quality for common failures like lint errors and type errors.\n\n### Provider abstraction\n\nAll three SCM providers implement `ScmProvider` from `providers/base.js`. The contract is:\n- **Normalized return types** — all methods return `NormalIssue`, `NormalMR`, `NormalPipeline`, etc., regardless of provider\n- **Instance-scoped** — each provider is instantiated with a repo string; no global state\n- **`supportsRebase`** — providers that don't support server-side rebase return `false`; the UI and API layer check this before showing the rebase button\n\n---\n\n## Programmatic usage\n\nMount the Forge Express router or use the core classes directly:\n\n```js\nimport forgeRouter from \"@ipul-labs/forge\";             // Express router\nimport { ForgeAgent } from \"@ipul-labs/forge/agent\";    // Core pipeline class\nimport { createProvider } from \"@ipul-labs/forge/providers\"; // SCM factory\n```\n\n```js\nconst agent = new ForgeAgent({ project: \"group/repo\" });\nconst result = await agent.analyzeIssue(42, (event) => console.log(event));\nconst { branchName, mr } = await agent.applyFix(result);\n```\n\n---\n\n## License\n\nMIT\n"
 }

package/server/forge/core/localRepo.js

@@ -14,6 +14,7 @@
  */
 
 import { spawn } from "child_process";
+import { writeFileSync, unlinkSync } from "fs";
 import fs from "fs/promises";
 import os from "os";
 import path from "path";
@@ -55,9 +56,26 @@ function sanitizeRepo(repo) {
 }
 
 function gitlabCloneUrl(project) {
+	return `https://gitlab.com/${project}.git`;
+}
+
+function createAskpassScript(token) {
+	const script = path.join(os.tmpdir(), `.forge-askpass-${process.pid}-${Date.now()}`);
+	writeFileSync(script, `#!/bin/sh\ncase "$1" in *Username*) echo oauth2;; *) echo "${token}";; esac\n`, { mode: 0o700 });
+	return script;
+}
+
+function gitEnvWithToken() {
 	const { token } = getConnection("gitlab");
 	if (!token) throw new Error("GitLab token is required to clone the repo locally. Set it in Settings → Connections or via GITLAB_TOKEN env var.");
-	return `https://oauth2:${token}@gitlab.com/${project}.git`;
+	const askpass = createAskpassScript(token);
+	return {
+		env: {
+			GIT_ASKPASS: askpass,
+			GIT_TERMINAL_PROMPT: "0",
+		},
+		cleanup: () => { try { unlinkSync(askpass); } catch {} },
+	};
 }
 
 function resolveCloneUrl(repoInput) {
@@ -90,26 +108,32 @@ export async function ensureWorkingTree(repo, branchName, onLog) {
 	const hasRepo = await exists(path.join(dir, ".git"));
 	const log = (m) => onLog?.(m);
 
-	if (!hasRepo) {
-		log(`Cloning ${repo} → ${dir}`);
-		await fs.mkdir(dir, { recursive: true });
-		const clone = await runGit(["clone", "--depth=1", resolveCloneUrl(repo), dir], {}, onLog);
-		if (clone.code !== 0) throw new Error(`git clone failed (code ${clone.code})`);
-	} else {
-		log(`Reusing clone at ${dir}`);
-	}
+	const { env: gitEnv, cleanup } = gitEnvWithToken();
+	const envOpts = { env: { ...process.env, ...gitEnv } };
+	try {
+		if (!hasRepo) {
+			log(`Cloning ${repo} → ${dir}`);
+			await fs.mkdir(dir, { recursive: true });
+			const clone = await runGit(["clone", "--depth=1", resolveCloneUrl(repo), dir], envOpts, onLog);
+			if (clone.code !== 0) throw new Error(`git clone failed (code ${clone.code})`);
+		} else {
+			log(`Reusing clone at ${dir}`);
+		}
 
-	const fetch = await runGit(["fetch", "--depth=1", "origin", "main"], { cwd: dir }, onLog);
-	if (fetch.code !== 0) throw new Error(`git fetch failed (code ${fetch.code})`);
+		const fetch = await runGit(["fetch", "--depth=1", "origin", "main"], { cwd: dir, ...envOpts }, onLog);
+		if (fetch.code !== 0) throw new Error(`git fetch failed (code ${fetch.code})`);
 
-	const reset = await runGit(["reset", "--hard", "origin/main"], { cwd: dir }, onLog);
-	if (reset.code !== 0) throw new Error(`git reset failed (code ${reset.code})`);
-	await runGit(["clean", "-fd"], { cwd: dir }, onLog);
+		const reset = await runGit(["reset", "--hard", "origin/main"], { cwd: dir }, onLog);
+		if (reset.code !== 0) throw new Error(`git reset failed (code ${reset.code})`);
+		await runGit(["clean", "-fd"], { cwd: dir }, onLog);
 
-	const checkout = await runGit(["checkout", "-B", branchName], { cwd: dir }, onLog);
-	if (checkout.code !== 0) throw new Error(`git checkout ${branchName} failed (code ${checkout.code})`);
+		const checkout = await runGit(["checkout", "-B", branchName], { cwd: dir }, onLog);
+		if (checkout.code !== 0) throw new Error(`git checkout ${branchName} failed (code ${checkout.code})`);
 
-	return dir;
+		return dir;
+	} finally {
+		cleanup();
+	}
 }
 
 /**
@@ -121,9 +145,10 @@ export async function ensureWorkingTree(repo, branchName, onLog) {
  * @param {(msg: string) => void} [onLog]
  */
 export async function overlayChanges(dir, changes, onLog) {
+	const realBase = await fs.realpath(dir);
 	for (const c of changes) {
-		const full = path.join(dir, c.file);
-		if (!full.startsWith(dir + path.sep) && full !== dir) {
+		const full = path.resolve(dir, c.file);
+		if (!full.startsWith(realBase + path.sep) && full !== realBase) {
 			throw new Error(`Refusing to write outside clone dir: ${c.file}`);
 		}
 		if (c.action === "delete") {

package/server/forge/core/validator/clone.js

@@ -10,6 +10,7 @@
  *     - Emits clone-step progress / log / step_result events.
  */
 
+import { writeFileSync, unlinkSync } from "node:fs";
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
@@ -26,11 +27,28 @@ function sanitizeRepo(repo) {
 }
 
 function gitlabCloneUrl(project) {
+	return `https://gitlab.com/${project}.git`;
+}
+
+function createAskpassScript(token) {
+	const script = path.join(os.tmpdir(), `.forge-askpass-${process.pid}`);
+	writeFileSync(script, `#!/bin/sh\ncase "$1" in *Username*) echo oauth2;; *) echo "${token}";; esac\n`, { mode: 0o700 });
+	return script;
+}
+
+function gitEnvWithToken() {
 	const { token } = getConnection("gitlab");
 	if (!token) {
 		throw new Error("GitLab token is required to clone the repo for validation. Set it in Settings → Connections or via GITLAB_TOKEN env var.");
 	}
-	return `https://oauth2:${token}@gitlab.com/${project}.git`;
+	const askpass = createAskpassScript(token);
+	return {
+		env: {
+			GIT_ASKPASS: askpass,
+			GIT_TERMINAL_PROMPT: "0",
+		},
+		cleanup: () => { try { unlinkSync(askpass); } catch {} },
+	};
 }
 
 function resolveCloneUrl(repoInput) {
@@ -54,23 +72,29 @@ export async function ensureClone(repo, branchName, emit) {
 	emit({ type: "progress", step: "clone", status: "running" });
 	emit({ type: "log", step: "clone", message: hasRepo ? `Reusing clone at ${dir}` : `Cloning ${repo} → ${dir}` });
 
-	if (!hasRepo) {
-		await fs.mkdir(dir, { recursive: true });
-		const clone = await runCmd(
-			"git", ["clone", "--depth=1", resolveCloneUrl(repo), dir],
-			{},
+	const { env: gitEnv, cleanup } = gitEnvWithToken();
+	const envOpts = { env: { ...process.env, ...gitEnv } };
+	try {
+		if (!hasRepo) {
+			await fs.mkdir(dir, { recursive: true });
+			const clone = await runCmd(
+				"git", ["clone", "--depth=1", resolveCloneUrl(repo), dir],
+				envOpts,
+				(l) => emit({ type: "log", step: "clone", message: l }),
+			);
+			if (clone.code !== 0) throw new Error(`git clone failed (code ${clone.code})`);
+		}
+
+		const fetch = await runCmd(
+			"git", ["fetch", "--depth=1", "origin", "main"],
+			{ cwd: dir, ...envOpts },
 			(l) => emit({ type: "log", step: "clone", message: l }),
 		);
-		if (clone.code !== 0) throw new Error(`git clone failed (code ${clone.code})`);
+		if (fetch.code !== 0) throw new Error(`git fetch failed (code ${fetch.code})`);
+	} finally {
+		cleanup();
 	}
 
-	const fetch = await runCmd(
-		"git", ["fetch", "--depth=1", "origin", "main"],
-		{ cwd: dir },
-		(l) => emit({ type: "log", step: "clone", message: l }),
-	);
-	if (fetch.code !== 0) throw new Error(`git fetch failed (code ${fetch.code})`);
-
 	// Two-step reset+clean before the branch switch so any lingering overlay
 	// from a prior run is wiped — `git checkout -B` alone refuses if dirty.
 	// `clean -fd` preserves node_modules because it's .gitignored.

package/server/forge/core/validator/overlay.js

@@ -8,10 +8,10 @@ import path from "node:path";
 
 export async function overlayChanges(dir, changes, emit) {
 	emit({ type: "progress", step: "overlay", status: "running" });
+	const realBase = await fs.realpath(dir);
 	for (const c of changes) {
-		const full = path.join(dir, c.file);
-		// Defensive: refuse to escape the clone dir.
-		if (!full.startsWith(dir + path.sep) && full !== dir) {
+		const full = path.resolve(dir, c.file);
+		if (!full.startsWith(realBase + path.sep) && full !== realBase) {
 			throw new Error(`Refusing to write outside clone dir: ${c.file}`);
 		}
 		if (c.action === "delete") {

package/server/forge/routes.js

@@ -21,6 +21,7 @@ import { Router } from "express";
 import * as configStore from "./core/configStore.js";
 import { listDeployments } from "./core/k8s.js";
 import { ForgeAgent } from "./core/ForgeAgent.js";
+import crypto from "node:crypto";
 import { probeQuota } from "./core/quotaClient.js";
 import { validate as runValidation } from "./core/validator.js";
 import { createProvider } from "./core/providers/index.js";
@@ -39,13 +40,16 @@ function requireAuth(req, res, next) {
 		});
 	}
 
-	const auth = req.headers.authorization ?? `Bearer ${req.query.token ?? ""}`;
+	const auth = req.headers.authorization
+		?? (req.query.token ? `Bearer ${req.query.token}` : null);
 
 	if (!auth?.startsWith("Bearer ")) {
 		return res.status(401).json({ error: "Missing Authorization header." });
 	}
 
-	if (auth.slice(7) !== token) {
+	const provided = Buffer.from(auth.slice(7));
+	const expected = Buffer.from(token);
+	if (provided.length !== expected.length || !crypto.timingSafeEqual(provided, expected)) {
 		return res.status(403).json({ error: "Invalid token." });
 	}
 
@@ -54,12 +58,20 @@ function requireAuth(req, res, next) {
 
 // ─── Error handler ────────────────────────────────────────────────────────────
 
+function redactSecrets(text) {
+	return text
+		.replace(/(?:token|key|secret|password|bearer)[=:\s]+\S+/gi, (m) => m.slice(0, m.indexOf(m.match(/[=:\s]/)[0]) + 1) + "***")
+		.replace(/oauth2:[^@]+@/gi, "oauth2:***@")
+		.replace(/ghp_\w+/g, "ghp_***")
+		.replace(/glpat-\w+/g, "glpat-***");
+}
+
 function handleError(res, error, operation) {
 	const msg = error?.message ?? "Unknown error";
-	console.error(`[forge] ${operation} failed:`, msg);
+	console.error(`[forge] ${operation} failed:`, redactSecrets(msg));
 	const upstream = /^(?:GitLab|GitHub) (\d{3}) on /.exec(msg);
 	const status = error?.status ?? (upstream ? Number(upstream[1]) : 500);
-	res.status(status).json({ error: msg, operation });
+	res.status(status).json({ error: redactSecrets(msg), operation });
 }
 
 // ─── Repo helpers ─────────────────────────────────────────────────────────────