flowforge-map 0.1.0__py3-none-any.whl

flowforge/security/finders.py

@@ -0,0 +1,127 @@
+"""Key finders (D31, CLAUDE.md §6.4 step 1): pure functions over one file's text, no I/O.
+
+Two ways a key shows: a known shape (`KEY_PATTERNS`, on any line, comments included), or a high-entropy string given
+to a key-like name (Python by the AST, JS/TS and Dart by patterns). A hit holds the line, what kind of key it is and
+the name it is given to, never the value. Pattern-based: known key formats and these shapes, not everything.
+"""
+
+from __future__ import annotations
+
+import ast
+import math
+import re
+from collections import Counter
+from dataclasses import dataclass
+
+from flowforge.security.logfilter import KEY_PATTERNS
+
+# Names for KEY_PATTERNS, in the same order
+KEY_SHAPES = list(zip(
+    ("private key", "Stripe key", "Razorpay key", "Google API key", "NVIDIA key", "Anthropic key", "OpenAI-style key",
+     "token (JWT)"),
+    KEY_PATTERNS, strict=True))
+PEM_START = re.compile(r"-----BEGIN [A-Z ]*PRIVATE KEY-----")
+SECRET_PARTS = frozenset({"key", "apikey", "token", "secret", "password", "passwd", "pwd", "credential", "credentials"})
+MIN_LENGTH = 16
+MIN_ENTROPY = 3.5   # bits per character
+_PLACEHOLDER = re.compile(r"your|example|sample|placeholder|changeme|change_me|replace|dummy|todo|<[^>]*>|\$\{|^\$|"
+                          r"^(.)\1+$|x{4,}|\*{3,}|\.\.\.", re.IGNORECASE)
+_KEY_CHARS = re.compile(r"^[A-Za-z0-9_\-+=]+$")
+_ENV_NAME = re.compile(r"^[A-Z][A-Z0-9_]*$")
+_WORDS = re.compile(r"[A-Z]?[a-z]+|[A-Z]+(?![a-z])|\d+")
+# JS/TS/Dart: a name, then `=` or `:`, then a quoted string on the same line
+_GIVEN = re.compile(r"""\b([A-Za-z_$][\w$]*)["']?\s*(?::\s*[\w<>?, ]+\s*)?[:=]\s*(['"`])((?:(?!\2).)*)\2""")
+
+
+@dataclass(frozen=True)
+class KeyHit:
+    line: int
+    label: str              # "Google API key", or "secret" when only entropy and the name tell
+    name: str | None = None  # the variable, key or argument it is given to
+
+
+def entropy(value: str) -> float:
+    counts = Counter(value)
+    return -sum(n / len(value) * math.log2(n / len(value)) for n in counts.values())
+
+
+def is_placeholder(value: str) -> bool:
+    return bool(_PLACEHOLDER.search(value))
+
+
+def is_secret_name(name: str) -> bool:
+    """`apiKey`, `api_key`, `SUPABASE_KEY`, `accessToken`: a part of the name is a key word; `keyboard` is not."""
+    parts = [p.lower() for p in _WORDS.findall(name)]
+    return any(p in SECRET_PARTS for p in parts) or name.lower() in SECRET_PARTS
+
+
+def looks_secret(value: str) -> bool:
+    """Long, random-looking, one run of key characters: not a sentence, URL, path, reference (`env:NAME`), pattern,
+    template, env var name (`GITHUB_TOKEN`) or placeholder."""
+    if len(value) < MIN_LENGTH or not _KEY_CHARS.match(value) or _ENV_NAME.match(value) or is_placeholder(value):
+        return False
+    classes = sum(bool(re.search(p, value)) for p in (r"[a-z]", r"[A-Z]", r"\d"))
+    return classes >= 2 and entropy(value) >= MIN_ENTROPY
+
+
+def _shape(text: str) -> str | None:
+    if PEM_START.search(text):
+        return "private key"
+    return next((label for label, pattern in KEY_SHAPES if pattern.search(text)), None)
+
+
+def _python_names(text: str) -> dict[int, list[tuple[str, str]]]:
+    """line -> (name, value) for each string given to a name: assignments, keywords, dict keys. Values stay here."""
+    try:
+        tree = ast.parse(text)
+    except SyntaxError:
+        return {}
+    out: dict[int, list[tuple[str, str]]] = {}
+
+    def strings(node: ast.AST) -> list[str]:
+        if isinstance(node, ast.Constant) and isinstance(node.value, str):
+            return [node.value]
+        if isinstance(node, ast.JoinedStr):
+            return [v.value for v in node.values if isinstance(v, ast.Constant) and isinstance(v.value, str)]
+        return []
+
+    def target_name(t: ast.AST) -> str | None:
+        return t.id if isinstance(t, ast.Name) else t.attr if isinstance(t, ast.Attribute) else None
+
+    for node in ast.walk(tree):
+        pairs: list[tuple[str | None, ast.AST]] = []
+        if isinstance(node, ast.Assign):
+            pairs = [(target_name(t), node.value) for t in node.targets]
+        elif isinstance(node, ast.AnnAssign) and node.value is not None:
+            pairs = [(target_name(node.target), node.value)]
+        elif isinstance(node, ast.keyword) and node.arg:
+            pairs = [(node.arg, node.value)]
+        elif isinstance(node, ast.Dict):
+            pairs = [(k.value, v) for k, v in zip(node.keys, node.values, strict=True)
+                     if isinstance(k, ast.Constant) and isinstance(k.value, str)]
+        for name, value in pairs:
+            if name:
+                for s in strings(value):
+                    out.setdefault(value.lineno, []).append((name, s))
+    return out
+
+
+def _given(line: str) -> list[tuple[str, str]]:
+    return [(m.group(1), m.group(3)) for m in _GIVEN.finditer(line)]
+
+
+def find_keys(text: str, language: str | None) -> list[KeyHit]:
+    """Every line that holds a key, once, in line order."""
+    python = _python_names(text) if language == "python" else {}
+    hits: list[KeyHit] = []
+    for n, line in enumerate(text.splitlines(), 1):
+        given = python.get(n, []) if language == "python" else _given(line) if language else []
+        label = _shape(line)
+        if label is not None:
+            name = next((name for name, value in given if _shape(value) is not None), None)
+            hits.append(KeyHit(n, label, name))
+            continue
+        name = next((name for name, value in given if is_secret_name(name) and looks_secret(value)), None)
+        if name is not None:
+            hits.append(KeyHit(n, "secret", name))
+    return hits

flowforge/security/findings.py

@@ -0,0 +1,169 @@
+"""Security findings from what the scan read (D31): keys in code and configs, plain http, unpinned or over-broad MCP
+servers. Each with the dependency it belongs to, a masked excerpt, a one-sentence fix and a prompt for a coding agent.
+
+Called by the scanner with the text it already has; nothing is read again, run or sent (D20).
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import PurePosixPath
+
+from flowforge.scan.models import Dependency, Finding
+from flowforge.scan.urls import is_local
+from flowforge.security.finders import KeyHit, find_keys
+
+Excerpt = Callable[[str, int], tuple[int, list[str]]]   # (path, line) -> (first line, masked lines)
+CODE = frozenset({"python", "javascript", "typescript", "dart"})
+NEAR = 3   # a key belongs to the dependency called within this many lines of where its name is used
+RUNNERS = frozenset({"npx", "uvx", "bunx", "pnpx"})
+BROAD = re.compile(r"^(?:/|~/?|\$\{?HOME\}?/?|[A-Za-z]:[\\/]?)$")
+_HTTP = re.compile(r"""\bhttp://([^/\s'"`:?#]+)""")
+LEVEL_ORDER = {"high": 0, "medium": 1, "low": 2}
+
+
+@dataclass
+class ConfigKey:
+    """A key-like env name whose value is written in an MCP config (the value itself is never passed here)."""
+
+    dep_id: str
+    server: str
+    name: str
+    path: str
+    line: int
+
+
+def _id(kind: str, path: str, line: int) -> str:
+    return f"{kind}-{re.sub(r'[^a-z0-9]+', '-', path.lower()).strip('-')}-{line}"[:120]
+
+
+def env_name(name: str | None, label: str) -> str:
+    """`apiKey` → API_KEY, `GOOGLE_STATIC_MAPS_KEY` stays; no name → one from the kind of key."""
+    base = name or label
+    snake = re.sub(r"(?<=[a-z0-9])(?=[A-Z])", "_", base)
+    return re.sub(r"[^A-Za-z0-9]+", "_", snake).strip("_").upper() or "API_KEY"
+
+
+def _lookup(language: str | None, name: str) -> str:
+    return {"python": f'os.environ["{name}"]', "javascript": f"process.env.{name}", "typescript": f"process.env.{name}",
+            "dart": f"String.fromEnvironment('{name}') (or your env package)"}.get(language or "", "the environment")
+
+
+class _Builder:
+    def __init__(self, texts: dict[str, list[str]], deps: list[Dependency],
+                 places: dict[str, list[tuple[str, int, str]]], excerpt: Excerpt):
+        self.texts, self.deps, self.places, self.excerpt = texts, deps, places, excerpt
+        self.out: list[Finding] = []
+
+    def add(self, kind: str, level: str, path: str, line: int, title: str, fix: str, prompt: str,
+            dep_id: str | None) -> None:
+        first, lines = self.excerpt(path, line)
+        self.out.append(Finding(id=_id(kind, path, line), kind=kind, level=level, title=title[:160],
+                                ref=f"{path}:{line}", line=line, dep_id=dep_id, first_line=first, excerpt=lines,
+                                fix=fix, prompt=prompt))
+
+    def dep_at(self, path: str, line: int, near: int = 0) -> str | None:
+        for dep in self.deps:
+            if any(p == path and abs(n - line) <= near for p, n, _ in self.places.get(dep.id, [])):
+                return dep.id
+        return None
+
+    def key_owner(self, path: str, hit: KeyHit) -> str | None:
+        """The dependency on the key's own line; else the one called near a line that uses the key's name."""
+        if dep := self.dep_at(path, hit.line):
+            return dep
+        if not hit.name:
+            return None
+        used = re.compile(rf"(?<![\w$]){re.escape(hit.name)}(?![\w$])")
+        for p, lines in sorted(self.texts.items()):
+            for n, text in enumerate(lines, 1):
+                if (p, n) != (path, hit.line) and used.search(text) and (dep := self.dep_at(p, n, NEAR)):
+                    return dep
+        return None
+
+    def keys(self, path: str, language: str | None, skip: set[int]) -> None:
+        for hit in find_keys("\n".join(self.texts[path]), language if language in CODE else None):
+            if hit.line in skip:
+                continue
+            dep_id = self.key_owner(path, hit)
+            used = next((f" for {d.name}" for d in self.deps if d.id == dep_id), "")
+            article = "An" if hit.label[0].lower() in "aeiou" else "A"
+            name = env_name(hit.name, "API_KEY" if hit.label == "secret" else hit.label)
+            self.add("key_in_code", "high", path, hit.line, f"{article} {hit.label} is written in the code",
+                     "Move it to .env and read it from the environment. Then replace the key: it may be in your git "
+                     "history.",
+                     f"In {path}:{hit.line}, a {hit.label}{used} is written in the code. Move it to an environment "
+                     f"variable named {name}: add it to .env (check that .env is in .gitignore) and read it with "
+                     f"{_lookup(language, name)} wherever it is used. Remove the written value. Never print or log it. "
+                     "Then remind me to replace the key with the provider, because the old one may be in git history.",
+                     dep_id)
+
+    def config_key(self, c: ConfigKey) -> None:
+        self.add("key_in_config", "high", c.path, c.line, f"{c.server}'s config holds {c.name} as plain text",
+                 f'Reference it instead ("${{{c.name}}}") and keep the value in your environment. '
+                 "Then replace the key.",
+                 f'In {c.path}:{c.line}, the MCP server "{c.server}" gets {c.name} as a value written in the file. '
+                 f'Change it to "${{{c.name}}}" so the value comes from the environment, and tell me to set {c.name} '
+                 "there and to replace the old key, because it may be in git history. Never print the value.",
+                 c.dep_id)
+
+    def plain_http(self, dep: Dependency) -> None:
+        for path, line, _ in self.places.get(dep.id, []):
+            text = self.texts.get(path, [""] * line)[line - 1] if line <= len(self.texts.get(path, [])) else ""
+            host = next((h for h in _HTTP.findall(text) if not is_local(h)), None)
+            if host:
+                self.add("plain_http", "medium", path, line, f"{dep.name} is called over http://",
+                         "Use https:// if the service offers it: anyone on the network can read or change plain http.",
+                         f"In {path}:{line}, {dep.name} is called over plain http://{host}. Check that {host} serves "
+                         "https, and if it does, change the address to https://. If it doesn't, tell me, and don't "
+                         "send keys or personal data to it.", dep.id)
+                return
+
+    def server(self, dep: Dependency) -> None:
+        if not dep.command or not dep.evidence:
+            return
+        path, _, line = dep.evidence[0].ref.rpartition(":")
+        program, args = PurePosixPath(dep.command[0]).name, dep.command[1:]
+        if program in RUNNERS:
+            package = args[args.index("--from") + 1] if "--from" in args[:-1] else next(
+                (a for a in args if not a.startswith("-")), None)
+            if package and not _pinned(program, package):
+                pin = f"{package}=={{version}}" if program == "uvx" else f"{package}@{{version}}"
+                self.add("unpinned_server", "medium", path, int(line), f"{dep.name} runs whatever version is newest",
+                         f"Pin a version ({pin.format(version='<version>')}) so a new release can't change it "
+                         "under you.",
+                         f'In {dep.evidence[0].ref}, the MCP server "{dep.name}" starts {package} with no version, so '
+                         f"each start may run a new release. Find the version in use now and pin it: "
+                         f"{pin.format(version='<that version>')}. Change nothing else.", dep.id)
+        if any("server-filesystem" in a for a in args) and (wide := next((a for a in args if BROAD.match(a)), None)):
+            self.add("broad_files", "medium", path, int(line), f"{dep.name} can read every file under {wide}",
+                     "Give it only the folder it needs.",
+                     f'In {dep.evidence[0].ref}, the filesystem MCP server "{dep.name}" is given {wide}, so it can '
+                     "read and change everything under it. Replace it with the one folder the app needs. Ask me which "
+                     "folder if it isn't clear.", dep.id)
+
+
+def _pinned(program: str, package: str) -> bool:
+    if program == "uvx":
+        return "==" in package or "@" in package
+    return package.count("@") >= 2 if package.startswith("@") else "@" in package
+
+
+def findings_for(texts: dict[str, list[str]], languages: dict[str, str | None], deps: list[Dependency],
+                 places: dict[str, list[tuple[str, int, str]]], config_keys: list[ConfigKey],
+                 excerpt: Excerpt) -> list[Finding]:
+    """Every finding, high first, then by file and line."""
+    b = _Builder(texts, deps, places, excerpt)
+    for c in config_keys:
+        b.config_key(c)
+    in_configs = {(c.path, c.line) for c in config_keys}
+    for path in sorted(texts):
+        b.keys(path, languages.get(path), {n for p, n in in_configs if p == path})
+    for dep in deps:
+        if dep.kind in ("api", "llm"):
+            b.plain_http(dep)
+        elif dep.kind == "mcp":
+            b.server(dep)
+    return sorted(b.out, key=lambda f: (LEVEL_ORDER[f.level], f.ref.rsplit(":", 1)[0], f.line))

flowforge/security/logfilter.py

@@ -0,0 +1,129 @@
+"""Minimal redaction, pulled forward into Phase 2 (D16; full spec in CLAUDE.md §6.4–6.5).
+
+Masks two things as "[REDACTED]":
+  - strings shaped like known keys (Stripe, Razorpay, Google, NVIDIA, Anthropic, JWTs, PEM blocks)
+  - the current values of env vars that connectors reference (secret_ref / env_refs), plus
+    NVIDIA_API_KEY, and their Basic-auth base64 form. Values under 8 characters are skipped.
+
+It is applied to run events and results before they are stored or served, and to every log
+record. It catches known key formats and configured keys, not everything; Phase 4 replaces
+it with the vault and redact/verify/scan/restore.
+"""
+
+from __future__ import annotations
+
+import base64
+import logging
+import os
+import re
+from collections.abc import Callable, Iterable
+from typing import Any
+
+REDACTED = "[REDACTED]"
+MIN_SECRET_LEN = 8
+
+KEY_PATTERNS = [re.compile(p) for p in (
+    r"-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----",
+    r"\b[sr]k_(?:live|test)_[A-Za-z0-9]{8,}",
+    r"\brzp_(?:live|test)_[A-Za-z0-9]{8,}",
+    r"\bAIza[0-9A-Za-z_\-]{20,}",
+    r"\bnvapi-[A-Za-z0-9_\-]{8,}",
+    r"\bsk-ant-[A-Za-z0-9_\-]{8,}",
+    r"\bsk-[A-Za-z0-9]{20,}",
+    r"\beyJ[A-Za-z0-9_\-]{8,}\.[A-Za-z0-9_\-]{8,}\.[A-Za-z0-9_\-]{8,}",
+)]
+
+
+# Names whose values are secrets (CLAUDE.md §6.4 b): `--api-key X`, `TOKEN=X`, `password = "..."`
+SECRET_WORDS = "key|token|secret|password|passwd|credential"
+SECRET_NAME = re.compile(SECRET_WORDS, re.IGNORECASE)
+# In code shown back to the user (scan evidence, D21/D22): what a key of an unknown shape could hide in
+_SECRET_VALUE = re.compile(rf"""(\b\w*(?:{SECRET_WORDS})\w*\b["']?\s*(?::\s*[\w\[\], |]+\s*)?"""
+                           r"""[:=]\s*)(['"`])[^'"`\n]*\2""", re.IGNORECASE)
+_URL_CREDENTIALS = re.compile(r"""(\b[a-z][a-z0-9+.-]*://)[^/\s:@'"`]+:[^@\s'"`/]+@""", re.IGNORECASE)
+_URL_QUERY = re.compile(r"""(\bhttps?://[^\s'"`?#]+)\?[^\s'"`#]+""", re.IGNORECASE)
+
+
+def redact_code(line: str, redactor: Redactor | None = None) -> str:
+    """A line of the user's code, safe to store and show: known key shapes, URL credentials and query strings,
+    and string values given to key/token/secret/password names are masked. Pattern-based: it catches known
+    key formats and these shapes, not everything."""
+    line = (redactor or Redactor()).redact_text(line)
+    line = _URL_CREDENTIALS.sub(rf"\1{REDACTED}@", line)
+    line = _URL_QUERY.sub(rf"\1?{REDACTED}", line)
+    return _SECRET_VALUE.sub(rf"\1\2{REDACTED}\2", line)
+
+
+class Redactor:
+    def __init__(self, values: Iterable[str] = ()) -> None:
+        self._values: list[str] = []
+        self.set_values(values)
+
+    def set_values(self, values: Iterable[str]) -> None:
+        """Replace the configured secret values (call again when connectors change)."""
+        found: set[str] = set()
+        for value in values:
+            if value and len(value) >= MIN_SECRET_LEN:
+                found.add(value)
+                found.add(base64.b64encode(value.encode()).decode())
+        self._values = sorted(found, key=len, reverse=True)  # longest first: no partial leftovers
+
+    def redact_text(self, text: str) -> str:
+        for value in self._values:
+            if value in text:
+                text = text.replace(value, REDACTED)
+        for pattern in KEY_PATTERNS:
+            text = pattern.sub(REDACTED, text)
+        return text
+
+    def redact(self, value: Any) -> Any:
+        """A copy of `value` with every string inside it redacted (dicts, lists, tuples)."""
+        if isinstance(value, str):
+            return self.redact_text(value)
+        if isinstance(value, dict):
+            return {self.redact(k) if isinstance(k, str) else k: self.redact(v) for k, v in value.items()}
+        if isinstance(value, (list, tuple)):
+            return [self.redact(v) for v in value]
+        return value
+
+
+def secret_values_for(connectors: Iterable[Any]) -> set[str]:
+    """Current values of every env var the connectors reference, plus NVIDIA_API_KEY (D8)."""
+    names = {"NVIDIA_API_KEY"}
+    for c in connectors:
+        refs = [c.secret_ref] + list(getattr(c.connection, "env_refs", {}).values())
+        names.update(ref.split(":", 1)[1] for ref in refs if ref and ref.startswith("env:"))
+    return {os.environ[n] for n in names if os.environ.get(n)}
+
+
+def install_log_redaction(redactor: Redactor) -> Callable[[], None]:
+    """Redact every log record at creation, whichever logger or handler it goes to.
+
+    Uses the log-record factory, because logger-level filters miss records propagated from
+    child loggers. Returns a function that restores the previous factory.
+    """
+    previous = logging.getLogRecordFactory()
+
+    def redact_arg(value: Any) -> Any:
+        if isinstance(value, str):
+            return redactor.redact_text(value)
+        if value is None or isinstance(value, (int, float, bool)):
+            return value  # keeps %d and friends working
+        return redactor.redact_text(str(value))
+
+    def factory(*args: Any, **kwargs: Any) -> logging.LogRecord:
+        record = previous(*args, **kwargs)
+        # Redact in place and keep the shape: some formatters (uvicorn's access log) unpack args.
+        if isinstance(record.msg, str):
+            record.msg = redactor.redact_text(record.msg)
+        if isinstance(record.args, tuple):
+            record.args = tuple(redact_arg(a) for a in record.args)
+        elif isinstance(record.args, dict):
+            record.args = {k: redact_arg(v) for k, v in record.args.items()}
+        if record.exc_info and record.exc_info[0] is not None:
+            # formatters reuse exc_text when it is set, so the traceback is printed redacted
+            record.exc_text = redactor.redact_text(logging.Formatter().formatException(record.exc_info))
+        return record
+
+    logging.setLogRecordFactory(factory)
+    return lambda: logging.setLogRecordFactory(previous)

flowforge/spa.py

@@ -0,0 +1,52 @@
+"""Serve the built dashboard (frontend/dist) next to the API (D15).
+
+Page routes and API paths overlap (/runs/:id, /connectors/:id), so a GET whose Accept header
+asks for HTML gets the app's index.html, and everything else reaches the API unchanged. curl,
+CI and fetch() calls (Accept: application/json or */*) keep getting JSON.
+
+  /classic   the V1 status page, kept until the new dashboard reaches parity
+  /assets/*  hashed build assets (cached hard)
+"""
+
+from __future__ import annotations
+
+from fastapi import FastAPI, Request
+from fastapi.responses import FileResponse, Response
+from fastapi.staticfiles import StaticFiles
+
+from flowforge.home import resource
+
+DIST = resource("dashboard")   # inside the package when installed, frontend/dist in a checkout (D34)
+CLASSIC = resource("classic")
+API_DOCS = ("/docs", "/redoc", "/openapi.json")
+
+
+def wants_html(request: Request) -> bool:
+    accept = request.headers.get("accept", "")
+    return request.method == "GET" and "text/html" in accept
+
+
+def install(app: FastAPI) -> None:
+    @app.middleware("http")
+    async def spa_fallback(request: Request, call_next):  # type: ignore[no-untyped-def]
+        path = request.url.path
+        index = DIST / "index.html"
+        if wants_html(request) and index.is_file() and not path.startswith(API_DOCS) and path != "/classic":
+            return FileResponse(index, headers={"Cache-Control": "no-cache"})
+        return await call_next(request)
+
+    app.mount("/assets", StaticFiles(directory=DIST / "assets", check_dir=False), name="assets")
+
+    @app.get("/classic", include_in_schema=False)
+    def classic() -> FileResponse:
+        return FileResponse(CLASSIC)
+
+    @app.get("/", include_in_schema=False)
+    def index() -> Response:
+        built = DIST / "index.html"
+        return FileResponse(built if built.is_file() else CLASSIC, headers={"Cache-Control": "no-cache"})
+
+    @app.get("/favicon.svg", include_in_schema=False)
+    def favicon() -> Response:
+        icon = DIST / "favicon.svg"
+        return FileResponse(icon, media_type="image/svg+xml") if icon.is_file() else Response(status_code=404)

flowforge/state.py

@@ -0,0 +1,73 @@
+"""App state shared by the API routers: nodes, buckets, storage, redaction, live runs (D16)."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from dataclasses import dataclass, field
+from typing import Any
+
+from fastapi import HTTPException
+
+from flowforge.connectors.registry import Registry
+from flowforge.nodes.base import Node
+from flowforge.scheduler.executor import Event
+from flowforge.scheduler.rate_limit import TokenBucket
+from flowforge.schema import Workflow
+from flowforge.security.logfilter import Redactor
+from flowforge.storage import Storage
+
+
+def plain(value: Any, redactor: Redactor) -> Any:
+    """Redacted, JSON-shaped copy, identical to what a later read from storage returns."""
+    return json.loads(json.dumps(redactor.redact(value), default=str))
+
+
+@dataclass
+class Run:
+    """A run while this server process is executing it. History lives in storage."""
+
+    id: str
+    workflow: Workflow
+    storage: Storage
+    redactor: Redactor
+    events: list[Event] = field(default_factory=list)
+    status: str = "running"
+    result: dict[str, Any] | None = None
+    error: str | None = None
+    done: bool = False
+    changed: asyncio.Event = field(default_factory=asyncio.Event)
+    task: asyncio.Task[Any] | None = None
+
+    def push(self, event: Event) -> None:
+        """Every event is redacted before it is kept, stored or streamed (D16)."""
+        event = plain(event, self.redactor)
+        self.events.append(event)
+        self.storage.append_event(self.id, len(self.events) - 1, event)
+        self.changed.set()
+
+
+@dataclass
+class AppState:
+    nodes: dict[str, Node]
+    rate_limits: dict[str, TokenBucket]
+    storage: Storage
+    registry: Registry
+    redactor: Redactor
+    file_managed: set[str] = field(default_factory=set)  # ids from connectors.json: read-only (D16)
+    connector_tests: dict[str, dict[str, Any]] = field(default_factory=dict)  # last "Test connection"
+    retired_nodes: list[Node] = field(default_factory=list)  # replaced nodes, closed at shutdown
+    runs: dict[str, Run] = field(default_factory=dict)
+    tasks: set[asyncio.Task[Any]] = field(default_factory=set)
+    shutting_down: bool = False
+    example: bool = False  # example-data mode (D16): the UI labels everything as example data
+    flows: dict[str, Any] = field(default_factory=dict)  # map id -> FlowService (D17, D21); Any avoids a cycle
+
+
+current: AppState | None = None
+
+
+def app_state() -> AppState:
+    if current is None:
+        raise HTTPException(503, "app not started")
+    return current