[shafty023]

Purpose

A prd-dependency-graph page was self-contained to view but not to refresh: the refresh depended on ~/.local/share/prd-dependency-graph/<graph-id>.json, which held the scope and options, labels and columns, me, a per-graph token the page also embedded, and absolute output paths on the author's machine. A shared page could not be refreshed anywhere else.

This makes a page (or a report with embedded graphs) portable: copy the HTML file to any machine with the skill and a CLOSEDLOOP_API_KEY, click refresh, and that copy is rewritten in place. There is no side file, and nothing from the author's machine or identity.

Design

• Config in the page. Each graph block carries <template class="dg-config" data-dg-graph="<id>"> with HTML-escaped JSON: scope, options, labels, column overrides, column_labels, nodes, edges, PRODUCES links and the last refresh's changes. It holds no token, output paths, API base or me. A <template> is used instead of <script type="application/json"> because pages rendered by the previous version re-create every <script> they swap in as executable, which would turn the JSON into a syntax error in tabs that are already open. Standalone pages now get depgraph markers too, so every refresh replaces only the region between the markers.
• POST /v2/refresh (JSON body: graph, scope, optional outside):
  • a page opened from a file sends path (its own location.pathname). The helper validates the file, reads the embedded config, re-reads the scope with this machine's key, rewrites only that graph, and answers {ok, written, refresh_id} with no ticket data. The page stores the refresh id and zoom in sessionStorage and reloads; on load it shows the change dialog from last_refresh in its own config and restores the zoom;
  • a page that is not a file sends config instead. The helper answers with the rendered block only for loopback origins (or a local program with no Origin), and the page swaps it in with a note that no file on disk changed;
  • an older helper refuses the JSON preflight, so the page probes /health and tells "out of date, run prd-graph-helper --ensure" apart from "not running".
• "Yours" comes from GET /me (the API key's owner), cached for 10 minutes per key. --me is now only a fallback for when that lookup fails. A copy shows the author's highlighting until its new owner refreshes it.
• CLI: --once <page.html> (plus --graph for reports), --export-config <page.html>, --once <page.html> --apply-config <json> for label and column edits, and render_graph.py <page.html> --print-columns. --new writes no side file.

Security model (SKILL.md "Security", pinned by test_prd_dependency_graph_security.py)

Any website open in the browser can send requests to 127.0.0.1:8765, and pages no longer carry a token.

• Exfiltration: a file refresh returns no ticket data; the data goes into the file, which only the page itself can read from disk. Ticket data goes back only to loopback origins and to local programs with no Origin. Origin null is refused too, since a sandboxed frame on any website sends it. Errors carry no ticket data, and /health and the old token endpoint no longer reveal the home path to other origins. The remaining signal is whether a guessed path holds a given graph.
• Arbitrary writes: only an absolute .html/.htm path (checked before and after resolving symlinks) that is an existing regular file owned by the user, up to 64 MB, holding this graph's markers and an embedded config for the requested scope. Only the text between the markers is replaced, atomically, and the write is refused if the file changed during the refresh.
• Cost: the request must name a graph id and a strictly formatted scope that the file holds, and these checks run before any API call. JSON is required, so browsers preflight the request, and the preflight is granted only to null and loopback origins. There is a 3 second cooldown per target, at most 2 refreshes at once, and bodies are capped at 4 MB.
• API key: never written to any file, and only sent to https://api.closedloop.ai. An api_base in a page is ignored; only an older local config can set one.

Backward compatibility

• The old token endpoint (/refresh?graph=&token=) is unchanged, so pages from 1.3.0 and 1.4.x keep refreshing through their running helper or the new one.
• While an older config in ~/.local/share/prd-dependency-graph/ lists a file, that config stays the file's source of truth whichever way the refresh arrives, and --once <graph-id> still works.
• Every refresh writes the portable format into the listed files, which migrates the page and removes its token. The config file is kept.
• A copied pre-1.5.0 page with no config on the new machine gets a clear message to have its author refresh it once.

Files changed

• skills/prd-dependency-graph/scripts/refresh_server.py: v2 endpoint, path, origin and scope validation, rate gate, /me lookup, file and config refresh, CLI additions, legacy routing.
• skills/prd-dependency-graph/scripts/render_graph.py: embedded config, markers on standalone pages, a portable start command, page JS for v2 (reload, report and old-helper detection), HTML input.
• skills/prd-dependency-graph/scripts/check_graph.cjs: works on a copy; checks the file refresh (request shape, reload, dialog, zoom) and the served-page swap.
• skills/prd-dependency-graph/SKILL.md: steps, refresh, sharing, older graphs, security, config.
• tools/python/conftest.py, test_prd_dependency_graph_security.py, test_prd_dependency_graph_portable.py: new tests with a stubbed API and an isolated HOME.
• README.md, CHANGELOG.md, .claude-plugin/plugin.json, .codex-plugin/plugin.json: closedloop-core 1.5.0.

Commands run

uv run ruff check .                                  # All checks passed
uv run pyright                                       # 0 errors
uv run pytest plugins/                               # 2423 passed, 3 skipped
uv run pytest plugins/closedloop-core/tools/python   # 80 passed
(cd tools/plugin-manifests && npm ci && npm test)    # 6 passed
python3 scripts/render_graph.py <example+refresh>.json -o page.html
python3 scripts/render_graph.py <example+refresh>.json --embed-into report.html
node scripts/check_graph.cjs page.html ISS-10797 shot.png     # ok, no errors
node scripts/check_graph.cjs report.html ISS-10797 shot.png   # ok, no errors

Manual end to end against the real API, on scratch copies only, with a helper on port 8799 under a scratch HOME (the user's helper on 8765 and their files were not touched):

• Old PRD-800 page and old PRD-751 briefing, each with its old config: the first click refreshed through the token URL in the old page script and migrated the file. The second click went through /v2/refresh with a reload and the change dialog. The briefing's prose outside the markers was byte-identical, and its labels and depth all were kept.
• Copies of the migrated pages in another folder, refreshed by a helper with an empty HOME (no configs): refresh with the dialog and zoom kept, the gear toggle to depth all, and the original file unchanged.
• --once <file>, --export-config, --new (and its refusal to overwrite), --ensure and --print-columns on HTML. me resolved from the key.
• curl probes: an evil origin got 403 with no CORS header, null was refused ticket data via config, and file mode answered {ok, written, refresh_id} only.