flowforge-map 0.2.0__tar.gz → 0.3.0__tar.gz

{flowforge_map-0.2.0 → flowforge_map-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: flowforge-map
-Version: 0.2.0
+Version: 0.3.0
 Summary: Map what your app depends on (LLMs, MCP servers, APIs), check their health and security, and see what could run faster. Local and free; the scan needs no AI.
 Project-URL: Homepage, https://github.com/Vishwa-Thangapandiyan/flowforge-agent-orchestrator
 Project-URL: Issues, https://github.com/Vishwa-Thangapandiyan/flowforge-agent-orchestrator/issues
@@ -29,6 +29,7 @@ Requires-Dist: openai>=1.40
 Requires-Dist: pydantic>=2.8
 Requires-Dist: python-dotenv>=1.0
 Requires-Dist: python-multipart>=0.0.32
+Requires-Dist: segno>=1.6
 Requires-Dist: uvicorn[standard]>=0.30
 Description-Content-Type: text/markdown
 
@@ -113,7 +114,18 @@ FlowForge is also an **MCP server**, so Claude Code, Codex or Antigravity can as
 claude mcp add flowforge -- uv --directory /path/to/flowforge run flowforge mcp --repo /path/to/your/app
 ```
 
-Your agent gets seven read-only tools: `get_map`, `get_flow`, `get_advice`, `check_health`, `get_security_findings`, `get_keys` and `what_changed`. Every answer is masked (key values never appear), FlowForge never edits your code, and a check starts an MCP server only after you said yes to it on the Checks page. FlowForge needs no AI of its own for any of this.
+Your agent gets ten tools: `get_map`, `get_flow`, `get_advice`, `check_health`, `get_security_findings`, `get_keys`, `get_fix_requests`, `request_key`, `wait_for_keys` and `what_changed`. All read only, except `request_key`, which only asks you for a key by name. Every answer is masked (key values never appear), the agent can't make FlowForge change your code, and a check starts an MCP server only after you said yes to it on the Checks page. FlowForge needs no AI of its own for any of this.
+
+### Fix what's unsafe, with one click
+
+The **Issues** page lists what the scan found unsafe, and every issue has one button:
+
+| Issue | Button | What happens |
+|---|---|---|
+| A key written in Python, or in JS/TS that runs on Node | **Fix** | FlowForge shows the change (the key masked). On **Approve**, the key goes to your keys and the line reads it from the environment, on a new branch `flowforge/fix-…`. Your branch and files aren't touched; merge it when you're ready. |
+| `http://`, an unpinned MCP server, a server given the whole disk, a key in `.mcp.json`, Dart or browser code | **Send to agent** | It joins your coding agent's list (`get_fix_requests`). Tell your agent "do the FlowForge fixes". |
+
+Fix needs a git repo and the file committed. FlowForge works out the change itself, with no AI. Replace a key that was in your code with its provider anyway: older commits still hold it.
 
 ### Keys your coding agent never sees
 
@@ -126,9 +138,13 @@ flowforge key import                       # move a .env into FlowForge (then de
 flowforge run -- python app.py             # your app starts with the keys in its environment
 ```
 
-Each command takes `--repo PATH` (default: the folder you're in). On the map, a 🔑 badge marks a block whose key is missing, and the ⚠ list has a box to paste it into. Your agent's `get_keys` tool gets names, statuses and the command to ask you to run, never a value. With no keychain (a server, CI), keys go to an encrypted file in `~/.flowforge`.
+Each command takes `--repo PATH` (default: the folder you're in). In the dashboard, the **Keys** page does the same with no commands: paste a missing key into its box, or click **Move into FlowForge** for one that's in `.env`. On the map, a 🔑 badge marks a block whose key is missing. Your agent's `get_keys` tool gets names, statuses and the command to ask you to run, never a value. With no keychain (a server, CI), keys go to an encrypted file in `~/.flowforge`.
+
+**When your agent adds a dependency that needs a key**, it calls `request_key("STRIPE_SECRET_KEY", "for Stripe in pay.py")`. The map says "Your agent asked for a key", and the new block shows in coral, "key missing". Click it, paste the key on the Keys page, and the agent's `wait_for_keys` returns the moment it's saved. The agent only ever sees the name.
+
+**See a key again** in the **Vault**: set a password and scan the QR with an authenticator app (Google Authenticator, Authy, 1Password), once. After that, your password, then the 6-digit code on your phone, open it for 5 minutes. It lists every key with its health: healthy, written in code, in `.env`, can't read, unused, or old. It also shows where each key lives, what uses it, and whether it's a live or test key. Each value shows for 30 seconds. Forgot the password? `flowforge lock reset --forget` drops the lock (your keys stay) and the dashboard says so.
 
-What this does and doesn't promise: the key is never handed to your agent and isn't left in a file it reads by habit. An agent that can run commands as you could still run `flowforge run -- printenv`, or read your keychain, so it isn't impossible. MCP servers your coding tool starts get their environment from that tool, not from FlowForge.
+What this does and doesn't promise: the key is never handed to your agent and isn't left in a file it reads by habit. An agent that can run commands as you could still run `flowforge run -- printenv`, read your keychain, or reset the lock (the dashboard then shows it was reset), so it isn't impossible. The 2FA stops web pages, anyone at your browser, and anything without your phone. MCP servers your coding tool starts get their environment from that tool, not from FlowForge.
 
 ### Send someone the map
 
@@ -255,7 +271,9 @@ FlowForge itself keeps keys out of its runs, events, cache, logs and the dashboa
 | `POST /connectors/{id}/test` | One harmless check (MCP and local apps) |
 | `GET /connectors/{id}/activity`, `GET /connectors/{id}/tools` | What an app has done; an MCP server's tools |
 | `GET /security` | The scan's security findings, by level, with the fix and a prompt for each (D31) |
-| `GET /keys`, `PUT /keys/{name}`, `DELETE /keys/{name}` | The keys the code reads and their status; save one (write-only: the value never comes back) or forget it (D36) |
+| `GET /keys`, `PUT /keys/{name}`, `DELETE /keys/{name}`, `POST /keys/{name}/import` | The keys the code reads and their status; save one (write-only), move one in from `.env`, or forget it (D36, D37) |
+| `GET /issues`, `POST /issues/{id}/preview\|fix\|send` | Every issue with its button; the masked change; make it on a new branch; send it to your agent (D37) |
+| `GET /lock`, `POST /lock/setup\|confirm\|password\|code\|close`, `GET /vault/keys`, `POST /keys/reveal` | The Vault: its lock (your password, then the authenticator code) and, once open, every key's health and one value at a time (D37, D38) |
 | `GET /health/tools`, `GET /stats/savings`, `GET /meta`, `GET /presets` | Tool health, money and time, app info, ready-made apps |
 | `GET /workflows`, `GET /workflows/{name}` | The example workflows |
 | `GET /flow?layer=mine\|planner` | The flow map: blocks, lines, positions, critical path, your edits |

{flowforge_map-0.2.0 → flowforge_map-0.3.0}/README.md

@@ -79,7 +79,18 @@ FlowForge is also an **MCP server**, so Claude Code, Codex or Antigravity can as
 claude mcp add flowforge -- uv --directory /path/to/flowforge run flowforge mcp --repo /path/to/your/app
 ```
 
-Your agent gets seven read-only tools: `get_map`, `get_flow`, `get_advice`, `check_health`, `get_security_findings`, `get_keys` and `what_changed`. Every answer is masked (key values never appear), FlowForge never edits your code, and a check starts an MCP server only after you said yes to it on the Checks page. FlowForge needs no AI of its own for any of this.
+Your agent gets ten tools: `get_map`, `get_flow`, `get_advice`, `check_health`, `get_security_findings`, `get_keys`, `get_fix_requests`, `request_key`, `wait_for_keys` and `what_changed`. All read only, except `request_key`, which only asks you for a key by name. Every answer is masked (key values never appear), the agent can't make FlowForge change your code, and a check starts an MCP server only after you said yes to it on the Checks page. FlowForge needs no AI of its own for any of this.
+
+### Fix what's unsafe, with one click
+
+The **Issues** page lists what the scan found unsafe, and every issue has one button:
+
+| Issue | Button | What happens |
+|---|---|---|
+| A key written in Python, or in JS/TS that runs on Node | **Fix** | FlowForge shows the change (the key masked). On **Approve**, the key goes to your keys and the line reads it from the environment, on a new branch `flowforge/fix-…`. Your branch and files aren't touched; merge it when you're ready. |
+| `http://`, an unpinned MCP server, a server given the whole disk, a key in `.mcp.json`, Dart or browser code | **Send to agent** | It joins your coding agent's list (`get_fix_requests`). Tell your agent "do the FlowForge fixes". |
+
+Fix needs a git repo and the file committed. FlowForge works out the change itself, with no AI. Replace a key that was in your code with its provider anyway: older commits still hold it.
 
 ### Keys your coding agent never sees
 
@@ -92,9 +103,13 @@ flowforge key import                       # move a .env into FlowForge (then de
 flowforge run -- python app.py             # your app starts with the keys in its environment
 ```
 
-Each command takes `--repo PATH` (default: the folder you're in). On the map, a 🔑 badge marks a block whose key is missing, and the ⚠ list has a box to paste it into. Your agent's `get_keys` tool gets names, statuses and the command to ask you to run, never a value. With no keychain (a server, CI), keys go to an encrypted file in `~/.flowforge`.
+Each command takes `--repo PATH` (default: the folder you're in). In the dashboard, the **Keys** page does the same with no commands: paste a missing key into its box, or click **Move into FlowForge** for one that's in `.env`. On the map, a 🔑 badge marks a block whose key is missing. Your agent's `get_keys` tool gets names, statuses and the command to ask you to run, never a value. With no keychain (a server, CI), keys go to an encrypted file in `~/.flowforge`.
+
+**When your agent adds a dependency that needs a key**, it calls `request_key("STRIPE_SECRET_KEY", "for Stripe in pay.py")`. The map says "Your agent asked for a key", and the new block shows in coral, "key missing". Click it, paste the key on the Keys page, and the agent's `wait_for_keys` returns the moment it's saved. The agent only ever sees the name.
+
+**See a key again** in the **Vault**: set a password and scan the QR with an authenticator app (Google Authenticator, Authy, 1Password), once. After that, your password, then the 6-digit code on your phone, open it for 5 minutes. It lists every key with its health: healthy, written in code, in `.env`, can't read, unused, or old. It also shows where each key lives, what uses it, and whether it's a live or test key. Each value shows for 30 seconds. Forgot the password? `flowforge lock reset --forget` drops the lock (your keys stay) and the dashboard says so.
 
-What this does and doesn't promise: the key is never handed to your agent and isn't left in a file it reads by habit. An agent that can run commands as you could still run `flowforge run -- printenv`, or read your keychain, so it isn't impossible. MCP servers your coding tool starts get their environment from that tool, not from FlowForge.
+What this does and doesn't promise: the key is never handed to your agent and isn't left in a file it reads by habit. An agent that can run commands as you could still run `flowforge run -- printenv`, read your keychain, or reset the lock (the dashboard then shows it was reset), so it isn't impossible. The 2FA stops web pages, anyone at your browser, and anything without your phone. MCP servers your coding tool starts get their environment from that tool, not from FlowForge.
 
 ### Send someone the map
 
@@ -221,7 +236,9 @@ FlowForge itself keeps keys out of its runs, events, cache, logs and the dashboa
 | `POST /connectors/{id}/test` | One harmless check (MCP and local apps) |
 | `GET /connectors/{id}/activity`, `GET /connectors/{id}/tools` | What an app has done; an MCP server's tools |
 | `GET /security` | The scan's security findings, by level, with the fix and a prompt for each (D31) |
-| `GET /keys`, `PUT /keys/{name}`, `DELETE /keys/{name}` | The keys the code reads and their status; save one (write-only: the value never comes back) or forget it (D36) |
+| `GET /keys`, `PUT /keys/{name}`, `DELETE /keys/{name}`, `POST /keys/{name}/import` | The keys the code reads and their status; save one (write-only), move one in from `.env`, or forget it (D36, D37) |
+| `GET /issues`, `POST /issues/{id}/preview\|fix\|send` | Every issue with its button; the masked change; make it on a new branch; send it to your agent (D37) |
+| `GET /lock`, `POST /lock/setup\|confirm\|password\|code\|close`, `GET /vault/keys`, `POST /keys/reveal` | The Vault: its lock (your password, then the authenticator code) and, once open, every key's health and one value at a time (D37, D38) |
 | `GET /health/tools`, `GET /stats/savings`, `GET /meta`, `GET /presets` | Tool health, money and time, app info, ready-made apps |
 | `GET /workflows`, `GET /workflows/{name}` | The example workflows |
 | `GET /flow?layer=mine\|planner` | The flow map: blocks, lines, positions, critical path, your edits |

{flowforge_map-0.2.0 → flowforge_map-0.3.0}/backend/flowforge/agent/server.py

@@ -9,6 +9,7 @@ from __future__ import annotations
 
 import json
 import logging
+import time
 import uuid
 from collections import Counter
 from pathlib import Path
@@ -19,6 +20,8 @@ from mcp.server.mcpserver import MCPServer
 from mcp.types import ToolAnnotations
 
 from flowforge.api.checks import CHECKABLE, check_workflow, command_text, confirmed_commands, target_for
+from flowforge.api.issues import FIX_REQUESTS_SETTING, fix_requests
+from flowforge.api.keys import add_key_request, clear_key_requests
 from flowforge.api.scan import REPO_SETTING
 from flowforge.checks import starts_process
 from flowforge.connectors.registry import Registry
@@ -28,7 +31,7 @@ from flowforge.flowmap.validate import code_writes, critical
 from flowforge.nodes.check_node import CheckNode
 from flowforge.scan import ScanResult, scan
 from flowforge.scheduler.executor import StepState, run_workflow
-from flowforge.security.keystore import KeyStore, report
+from flowforge.security.keystore import NAME, KeyStore, report
 from flowforge.security.logfilter import Redactor, redact_code, secret_values_for
 from flowforge.storage import Storage, now_iso
 
@@ -43,10 +46,12 @@ INSTRUCTIONS = (
     "each with the file:line it comes from, checks their health, and shows the order the code calls them, the "
     "critical path and which calls could run together, and what is unsafe (keys in code, plain http, risky MCP "
     "servers). It reads code without running it and sends nothing to any "
-    "LLM. Answers are masked: key values never appear. It never edits code: you make the change, then call "
-    "what_changed to confirm."
+    "LLM. Answers are masked: key values never appear. It doesn't edit code for you: you make the change, "
+    "then call what_changed to confirm. When the user says \"do the FlowForge fixes\", call get_fix_requests."
 )
 READ = ToolAnnotations(read_only_hint=True, open_world_hint=False)
+ASK = ToolAnnotations(read_only_hint=False, destructive_hint=False, idempotent_hint=True, open_world_hint=False)
+MAX_WAIT_S = 110
 CHECKS = ToolAnnotations(read_only_hint=True, open_world_hint=True)   # makes requests and may start servers
 
 
@@ -165,6 +170,12 @@ def headline(tool: str, data: dict[str, Any]) -> str | None:
         counts = data["summary"]
         parts = [f"{counts[k]} {w}" for k, w in (("missing", "missing"), ("env_file", "in .env")) if counts.get(k)]
         return " · ".join(parts) or ("All saved" if data["keys"] else "No keys read")
+    if tool == "request_key":
+        return f"Asked for {data['name']}"
+    if tool == "wait_for_keys":
+        return "All saved" if data["done"] else f"{_plural(len(data['waiting']), 'key')} still missing"
+    if tool == "get_fix_requests":
+        return _plural(len(data["requests"]), "fix", "fixes") + " sent to you" if data["requests"] else "Nothing sent"
     if tool == "what_changed":
         if not data["saved"]:
             return "No saved map yet"
@@ -195,6 +206,20 @@ def _keys_data(root: Path, result: ScanResult) -> dict[str, Any]:
                     "`flowforge key list` is what confirms it can be read"}
 
 
+def _fix_requests_data(r: _Repo) -> dict[str, Any]:
+    """The user's queue (D37), without the issues the code no longer has. Only when the dashboard maps this repo."""
+    if not r.shared:
+        return {"requests": [], "message": "The dashboard doesn't map this repo, so nothing was sent from it."}
+    queue = fix_requests(r.storage)
+    here = str(r.root)
+    now = {f.id for f in r.scan().findings}
+    done = [q for q in queue if q["repo"] == here and q["id"] not in now]   # the code no longer has it
+    if done:
+        r.storage.set_setting(FIX_REQUESTS_SETTING, json.dumps([q for q in queue if q not in done]))
+    live = [q for q in queue if q["repo"] == here and q["id"] in now]
+    return {"requests": [{k: q.get(k) for k in ("id", "kind", "title", "ref", "fix", "prompt")} for q in live]}
+
+
 def _flow_data(result: Any) -> dict[str, Any]:
     if result.flow is None:
         return {"available": False, "message": result.message}
@@ -251,6 +276,8 @@ def preview(repo: Path, storage: Storage) -> dict[str, Any]:
          if advice["available"] else None,
          "sub": f"saves ~{_seconds(advice['saved_ms'])}, the change written out" if advice["available"] else None,
          "tone": "warn" if advice["available"] and advice["advice"] else "plain"},
+        {"tool": "get_fix_requests", "headline": headline("get_fix_requests", _fix_requests_data(r)),
+         "sub": "issues you send from the Issues page", "tone": "plain"},
         {"tool": "what_changed", "headline": None, "sub": "After your agent edits: what it added or removed",
          "tone": "plain"},
     ]
@@ -337,6 +364,54 @@ def build_server(repo: Path, storage: Storage, *, transport: httpx.AsyncBaseTran
         run the `command` given (they type the key, hidden). Their app gets the keys with `flowforge run -- <app>`."""
         return r.answer("get_keys", _keys_data(r.root, r.scan()))
 
+    @server.tool(annotations=ASK)
+    def request_key(name: str, why: str) -> dict[str, Any]:
+        """Ask the user for a key your change needs (D38), e.g. after adding Stripe: name="STRIPE_SECRET_KEY",
+        why="for Stripe in pay.py". It shows first on FlowForge's Keys page. You never get or send the value: write
+        code that reads the name from the environment, tell the user to paste the key on the Keys page, then call
+        wait_for_keys. Their app gets it with `flowforge run`."""
+        if not NAME.fullmatch(name):
+            raise ValueError("name must be an env var name: letters, digits and _, not starting with a digit")
+        add_key_request(r.storage, r.root, name, why.strip() or "asked by your coding agent")
+        saved = KeyStore(r.root).status([name], verify=False)[name] == "saved"
+        if saved:
+            clear_key_requests(r.storage, r.root, [name])
+        where = "" if r.shared else " (open the dashboard on this repo: `flowforge --repo " + str(r.root) + "`)"
+        return r.answer("request_key", {
+            "name": name, "status": "saved" if saved else "requested",
+            "message": f"{name} is saved already: use it." if saved else
+            f"Ask the user to paste {name} on FlowForge's Keys page{where}; it's at the top. Then call wait_for_keys."})
+
+    @server.tool(annotations=READ)
+    async def wait_for_keys(names: list[str], seconds: int = 60) -> dict[str, Any]:
+        """Wait until the user has saved these keys on the Keys page (D38): returns as soon as all are saved, or
+        after `seconds` (at most 110; call again to keep waiting). Reads only which names are saved, never a
+        value."""
+        import asyncio
+
+        wanted = [n for n in dict.fromkeys(names) if NAME.fullmatch(n)]
+        deadline = time.monotonic() + max(1, min(MAX_WAIT_S, int(seconds)))
+        store = KeyStore(r.root)
+        while True:
+            status = store.status(wanted, verify=False)
+            saved = [n for n in wanted if status[n] == "saved"]
+            if len(saved) == len(wanted) or time.monotonic() >= deadline:
+                break
+            await asyncio.sleep(1)
+        clear_key_requests(r.storage, r.root, saved)
+        waiting = [n for n in wanted if n not in saved]
+        return r.answer("wait_for_keys", {
+            "saved": saved, "waiting": waiting, "done": not waiting,
+            "message": "All saved: run the app with `flowforge run -- <its command>`." if not waiting else
+            f"Still waiting for {', '.join(waiting)}: call wait_for_keys again, or remind the user."})
+
+    @server.tool(annotations=READ)
+    def get_fix_requests() -> dict[str, Any]:
+        """The issues the user sent you from FlowForge's Issues page ("do the FlowForge fixes"): each with its
+        file:line, what is wrong, how to fix it and the whole change described (masked: no key value). An issue leaves
+        the list once the code no longer has it, so call what_changed after your edit to confirm."""
+        return r.answer("get_fix_requests", _fix_requests_data(r))
+
     @server.tool(annotations=READ)
     def what_changed() -> dict[str, Any]:
         """After an edit: the dependencies added or removed since the map saved in the dashboard, and the flow's

flowforge_map-0.3.0/backend/flowforge/api/issues.py

@@ -0,0 +1,150 @@
+"""The Issues page (D37): every security finding with the button it gets. Fix (FlowForge changes the code on a new
+branch) or Send to agent (queued for the coding agent's `get_fix_requests`).
+
+GET  /issues                {repo, example, summary: {high, medium, low}, issues: [{...finding, action, state, branch}]}
+                            (read from the code each time)
+POST /issues/{id}/preview   the change Fix will make, masked, and whether it can be made now
+POST /issues/{id}/fix       make it: a new branch, the key saved → {id, branch, commit, file, name}
+POST /issues/{id}/send      queue it for the agent → {id, state: "sent"}
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+from collections import Counter
+from pathlib import Path
+from typing import Any
+
+from fastapi import APIRouter, Depends, HTTPException
+
+from flowforge.api.keys import from_this_machine, learn_saved_keys
+from flowforge.api.scan import repo_path
+from flowforge.scan import scan as scan_repo
+from flowforge.scan.models import Finding
+from flowforge.security.fixes import CantFix, apply_fix, fixable, preview
+from flowforge.state import AppState, app_state
+from flowforge.storage import Storage, now_iso
+
+router = APIRouter()
+
+FIX_REQUESTS_SETTING = "fix_requests"   # [{repo, id, kind, title, ref, fix, prompt, sent_at}]: what the agent is asked
+FIXES_SETTING = "fixes_made"            # [{repo, id, branch, commit, at}]: fixes made on a branch, not yet merged
+# Issue ids repeat across repos (kind, path, line), so every entry names its folder and only counts there (Codex review)
+EXAMPLE_WHY = "Example data: FlowForge shows the change but makes none. Map your own repo to fix it."
+
+
+def _load(storage: Storage, key: str, empty: Any) -> Any:
+    try:
+        return json.loads(storage.setting(key) or "null") or empty
+    except ValueError:
+        return empty
+
+
+def _entries(storage: Storage, key: str) -> list[dict[str, Any]]:
+    """A list setting's entries that name their folder (older ones didn't, and are dropped)."""
+    found = _load(storage, key, [])
+    return [e for e in found if isinstance(e, dict) and e.get("repo")] if isinstance(found, list) else []
+
+
+def fix_requests(storage: Storage, repo: Path | None = None) -> list[dict[str, Any]]:
+    """The queue, or only `repo`'s part of it."""
+    queue = _entries(storage, FIX_REQUESTS_SETTING)
+    return queue if repo is None else [r for r in queue if r["repo"] == str(repo.resolve())]
+
+
+def _fixes(storage: Storage, repo: Path) -> dict[str, dict[str, Any]]:
+    """The fixes made in `repo`, by issue id."""
+    return {m["id"]: m for m in _entries(storage, FIXES_SETTING) if m["repo"] == str(repo.resolve())}
+
+
+def _branch_exists(repo: Path, branch: str) -> bool:
+    done = subprocess.run(["git", "show-ref", "--verify", "--quiet", f"refs/heads/{branch}"], cwd=repo,
+                          capture_output=True)
+    return done.returncode == 0
+
+
+def _repo(s: AppState) -> Path:
+    repo = repo_path(s)
+    if repo is None or not repo.is_dir():
+        raise HTTPException(409, "Map a folder first.")
+    return repo
+
+
+def _finding(repo: Path, issue_id: str) -> Finding:
+    """The issue as the code is now (read again, so a fix starts from the current file)."""
+    found = next((f for f in scan_repo(repo).findings if f.id == issue_id), None)
+    if found is None:
+        raise HTTPException(404, "That issue isn't in the code any more. Re-scan.")
+    return found
+
+
+@router.get("/issues")
+def issues() -> dict[str, Any]:
+    s = app_state()
+    repo = repo_path(s)
+    if repo is None or not repo.is_dir():
+        return {"repo": None, "example": s.example, "summary": {}, "issues": []}
+    result = scan_repo(repo)   # the code as it is now: a merged fix or an agent's edit shows at once
+    sent = {r["id"] for r in fix_requests(s.storage, repo)}
+    made = _fixes(s.storage, repo)
+    out = []
+    for f in result.findings:
+        branch = made.get(f.id, {}).get("branch")
+        if branch and not _branch_exists(repo, branch):
+            branch = None   # the branch was deleted: the issue is open again
+        state = "fixed" if branch else "sent" if f.id in sent else "open"
+        out.append({**f.model_dump(mode="json"), "action": "fix" if fixable(repo, f) else "agent",
+                    "state": state, "branch": branch})
+    return {"repo": repo.name, "example": s.example, "summary": dict(Counter(f.level for f in result.findings)),
+            "issues": out}
+
+
+@router.post("/issues/{issue_id}/preview")
+def preview_fix(issue_id: str) -> dict[str, Any]:
+    s = app_state()
+    repo = _repo(s)
+    try:
+        shown = preview(repo, _finding(repo, issue_id))
+    except CantFix as e:
+        raise HTTPException(409, str(e)) from None
+    if s.example:
+        shown.update(can_apply=False, why_not=EXAMPLE_WHY)
+    return shown
+
+
+@router.post("/issues/{issue_id}/fix", dependencies=[Depends(from_this_machine)])
+def fix(issue_id: str) -> dict[str, Any]:
+    s = app_state()
+    repo = _repo(s)
+    if s.example:
+        raise HTTPException(409, EXAMPLE_WHY)
+    made = _fixes(s.storage, repo)
+    if made.get(issue_id) and _branch_exists(repo, made[issue_id]["branch"]):
+        raise HTTPException(409, f"Already fixed on {made[issue_id]['branch']}: merge that branch.")
+    found = _finding(repo, issue_id)
+    if not fixable(repo, found):
+        raise HTTPException(409, "FlowForge doesn't fix this one itself: send it to your agent.")
+    try:
+        done = apply_fix(repo, found)
+    except CantFix as e:
+        raise HTTPException(409, str(e)) from None
+    learn_saved_keys(s, repo)
+    here = str(repo.resolve())
+    kept = [m for m in _entries(s.storage, FIXES_SETTING) if (m["repo"], m.get("id")) != (here, issue_id)]
+    kept.append({"repo": here, "id": issue_id, "branch": done["branch"], "commit": done["commit"], "at": now_iso()})
+    s.storage.set_setting(FIXES_SETTING, json.dumps(kept))
+    return done
+
+
+@router.post("/issues/{issue_id}/send", dependencies=[Depends(from_this_machine)])
+def send(issue_id: str) -> dict[str, Any]:
+    s = app_state()
+    repo = _repo(s)
+    found = _finding(repo, issue_id)
+    here = str(repo.resolve())
+    queue = [r for r in fix_requests(s.storage) if (r["repo"], r["id"]) != (here, issue_id)]
+    queue.append({"repo": here, "id": found.id, "kind": found.kind, "title": found.title, "ref": found.ref,
+                  "fix": found.fix, "prompt": found.prompt, "sent_at": now_iso()})
+    s.storage.set_setting(FIX_REQUESTS_SETTING, json.dumps(queue))
+    return {"id": issue_id, "state": "sent"}

flowforge_map-0.3.0/backend/flowforge/api/keys.py

@@ -0,0 +1,184 @@
+"""Keys the coding agent never sees (D36): their statuses for the map, and the dashboard's write-only box.
+
+GET    /keys          {repo, example, summary: {missing, env_file}, keys: [{name, status, ref, deps, command}]}
+PUT    /keys/{name}          {"value": "..."} → {name, status: "saved"}; the value is never sent back
+POST   /keys/{name}/import   the value of `name` in the folder's .env, saved (D37) → {name, status: "saved"}
+DELETE /keys/{name}          → {name, removed}
+"""
+
+from __future__ import annotations
+
+import json
+from collections import Counter
+from collections.abc import Iterable
+from pathlib import Path
+from typing import Any
+from urllib.parse import urlsplit
+
+from fastapi import APIRouter, Depends, HTTPException, Request
+from pydantic import BaseModel, ConfigDict
+
+from flowforge.api.scan import repo_path
+from flowforge.home import command_line
+from flowforge.scan import ScanResult
+from flowforge.scan import scan as scan_repo
+from flowforge.security.keystore import BadKey, KeyStore, report
+from flowforge.state import AppState, app_state
+from flowforge.storage import Storage, now_iso
+
+router = APIRouter()
+
+KEY_REQUESTS_SETTING = "key_requests"   # [{repo, name, why, at}]: keys your agent asked for (D38), never a value
+
+
+def key_requests(storage: Storage, repo: Path) -> list[dict[str, Any]]:
+    """`repo`'s open requests, oldest first."""
+    try:
+        found = json.loads(storage.setting(KEY_REQUESTS_SETTING) or "[]")
+    except ValueError:
+        return []
+    here = str(repo.resolve())
+    return [r for r in found if isinstance(r, dict) and r.get("repo") == here] if isinstance(found, list) else []
+
+
+def _all_requests(storage: Storage) -> list[dict[str, Any]]:
+    try:
+        found = json.loads(storage.setting(KEY_REQUESTS_SETTING) or "[]")
+    except ValueError:
+        return []
+    return [r for r in found if isinstance(r, dict) and r.get("repo")] if isinstance(found, list) else []
+
+
+def add_key_request(storage: Storage, repo: Path, name: str, why: str) -> None:
+    here = str(repo.resolve())
+    kept = [r for r in _all_requests(storage) if (r["repo"], r.get("name")) != (here, name)]
+    kept.append({"repo": here, "name": name, "why": why[:200], "at": now_iso()})
+    storage.set_setting(KEY_REQUESTS_SETTING, json.dumps(kept))
+
+
+def clear_key_requests(storage: Storage, repo: Path, names: Iterable[str]) -> None:
+    """A request ends once its key is saved."""
+    here, done = str(repo.resolve()), set(names)
+    found = _all_requests(storage)
+    kept = [r for r in found if not (r["repo"] == here and r.get("name") in done)]
+    if len(kept) != len(found):
+        storage.set_setting(KEY_REQUESTS_SETTING, json.dumps(kept))
+
+
+class KeyValue(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    value: str
+
+
+def learn_saved_keys(s: AppState, repo: Path | None) -> None:
+    """The redactor masks every value saved for this folder from now on, wherever it would show (D36)."""
+    if repo is None:
+        return
+    try:
+        s.redactor.learn(KeyStore(repo).env().values())
+    except Exception:   # a keychain that can't be read must not stop FlowForge
+        pass
+
+
+def stored_scan(s: AppState, repo: Path) -> ScanResult:
+    """The map's stored scan, so a re-scan updates the keys; the folder read again if none is stored."""
+    analysis = s.flows["deps"].analysis() if "deps" in s.flows else None
+    stored = (analysis or {}).get("scan")
+    if stored:
+        try:
+            return ScanResult.model_validate(stored)
+        except ValueError:
+            pass
+    return scan_repo(repo)
+
+
+_LOOPBACK = {"localhost", "127.0.0.1", "::1"}
+
+
+def _loopback_peer(address: str | None) -> bool:
+    """The connection itself comes from this machine (127.0.0.0/8 or ::1)."""
+    import ipaddress
+
+    try:
+        ip = ipaddress.ip_address(address or "")
+    except ValueError:
+        return False
+    mapped = getattr(ip, "ipv4_mapped", None)   # ::ffff:127.0.0.1 on a dual-stack socket
+    return (mapped or ip).is_loopback
+
+
+def from_this_machine(request: Request) -> None:
+    """Saving a key, a fix, the lock and the key view need the dashboard on this machine (D36, D37). The caller's real
+    address must be this machine (with --host 0.0.0.0 another machine could fake the headers: Codex review), and
+    Host and Origin must name it too, so a web page can't reach it through DNS rebinding or from another site."""
+    host = urlsplit(f"//{request.headers.get('host', '')}").hostname
+    origin = request.headers.get("origin")
+    peer = request.client.host if request.client else None
+    if (not _loopback_peer(peer) or host not in _LOOPBACK
+            or (origin is not None and urlsplit(origin).hostname not in _LOOPBACK)):
+        raise HTTPException(403, "This works only from the dashboard on this machine (open it at localhost).")
+
+
+def _writable(s: AppState) -> Path:
+    """The folder keys are saved for. Example data saves too (D37): its keys belong to the example's folder."""
+    repo = repo_path(s)
+    if repo is None:
+        raise HTTPException(409, "Map a folder first: keys belong to one folder.")
+    return repo
+
+
+@router.get("/keys")
+def keys() -> dict[str, Any]:
+    s = app_state()
+    repo = repo_path(s)
+    if repo is None or not repo.is_dir():
+        return {"repo": None, "example": s.example, "summary": {}, "keys": []}
+    store = KeyStore(repo)
+    asked = key_requests(s.storage, repo)
+    clear_key_requests(s.storage, repo, [n for n in store.names() if any(r["name"] == n for r in asked)])
+    asked = [r for r in asked if r["name"] not in set(store.names())]
+    found = report(store, stored_scan(s, repo), also=[r["name"] for r in asked])
+    for k in found:
+        k["requested"] = any(r["name"] == k["name"] for r in asked)
+    summary = Counter(k["status"] for k in found if k["status"] != "saved")
+    return {"repo": repo.name, "example": s.example, "summary": dict(summary), "keys": found,
+            "requests": [{"name": r["name"], "why": r["why"], "at": r["at"]} for r in asked],
+            "run": command_line("run", "--repo", str(repo), "--")}   # + how you start your app
+
+
+@router.put("/keys/{name}", dependencies=[Depends(from_this_machine)])
+def save_key(name: str, body: KeyValue) -> dict[str, Any]:
+    s = app_state()
+    repo = _writable(s)
+    try:
+        KeyStore(repo).add(name, body.value)
+    except BadKey as e:
+        raise HTTPException(400, str(e)) from None
+    s.redactor.learn([body.value.strip()])
+    clear_key_requests(s.storage, repo, [name])
+    return {"name": name, "status": "saved"}
+
+
+@router.post("/keys/{name}/import", dependencies=[Depends(from_this_machine)])
+def import_key(name: str) -> dict[str, Any]:
+    """Move one key in from .env: the server reads that value from the file, so nothing is copied by hand (D37)."""
+    from dotenv import dotenv_values
+
+    s = app_state()
+    repo = _writable(s)
+    value = dotenv_values(repo / ".env").get(name) if (repo / ".env").is_file() else None
+    if not value or not value.strip():
+        raise HTTPException(404, f"{name} isn't set in .env.")
+    try:
+        KeyStore(repo).add(name, value)
+    except BadKey as e:
+        raise HTTPException(400, str(e)) from None
+    s.redactor.learn([value.strip()])
+    clear_key_requests(s.storage, repo, [name])
+    return {"name": name, "status": "saved"}
+
+
+@router.delete("/keys/{name}", dependencies=[Depends(from_this_machine)])
+def remove_key(name: str) -> dict[str, Any]:
+    repo = _writable(app_state())
+    return {"name": name, "removed": KeyStore(repo).remove(name)}