Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

feat: guard GET routes that reach host processes (#13097)

Adam Eivy0ce2b369d779
diff --git a/client/src/components/musicVideo/DependencyImpactPanel.jsx b/client/src/components/musicVideo/DependencyImpactPanel.jsx
index 6a4d05cd64..d40e0f277f 100644
--- a/client/src/components/musicVideo/DependencyImpactPanel.jsx
+++ b/client/src/components/musicVideo/DependencyImpactPanel.jsx
@@ -4,6 +4,10 @@ import { openRevisionOf } from '../../lib/musicVideoAttention.js';
import { formatCount } from '../../utils/formatters.js';
const REVISION_HINT_ID = 'mv-repair-blocked-hint';
+// The preview decodes the song with ffmpeg, so the server gates it like other
+// host work (#13097); a remote password-free viewer still gets the page.
+const UNAVAILABLE = 'unavailable';
+const UNAVAILABLE_NOTE = 'Asset dependency check needs an operator session, or a local connection when no password is set.';
/** Preview first; only the director's Repair action starts any work. */
export default function DependencyImpactPanel({ project, busy, onRepair }) {
@@ -17,15 +21,18 @@ export default function DependencyImpactPanel({ project, busy, onRepair }) {
let active = true;
setResult(null);
setError(null);
- getMusicVideoDependencyImpact(project.id, { silent: true }).then((impact) => {
+ getMusicVideoDependencyImpact(project.id, { silent: true, hostControlOptional: true }).then((impact) => {
if (active) setResult(impact);
}).catch((err) => {
- if (active) setError(err.message || 'Could not check asset dependencies');
+ if (!active) return;
+ if (err.code === 'HOST_CONTROL_FORBIDDEN') setResult(UNAVAILABLE);
+ else setError(err.message || 'Could not check asset dependencies');
});
return () => { active = false; };
}, [project.id, basisKey, retry]);
const revisionActive = !!openRevisionOf(project);
if (error) return <div role="alert" className="text-xs text-port-error">{error} <button type="button" onClick={() => setRetry((value) => value + 1)}>Retry dependency check</button></div>;
+ if (result === UNAVAILABLE) return <p className="text-xs text-port-text-muted">{UNAVAILABLE_NOTE}</p>;
if (!result || (!result.shots.length && !result.evidence.length)) return null;
return (
<section aria-label="Stale asset impact" className="rounded border border-port-warning/40 bg-port-warning/5 p-3 space-y-2 text-xs">
diff --git a/client/src/components/musicVideo/DependencyImpactPanel.test.jsx b/client/src/components/musicVideo/DependencyImpactPanel.test.jsx
index 79b660ab32..96eab25a09 100644
--- a/client/src/components/musicVideo/DependencyImpactPanel.test.jsx
+++ b/client/src/components/musicVideo/DependencyImpactPanel.test.jsx
@@ -18,6 +18,14 @@ describe('rendered stale impact', () => {
fireEvent.click(screen.getByRole('button', { name: 'Repair affected dependencies' }));
expect(repair).toHaveBeenCalledWith('example-basis');
});
+ it('shows the impact as unavailable, with no error or retry, when host control is refused', async () => {
+ getMusicVideoDependencyImpact.mockRejectedValue(Object.assign(new Error('Host control requires an operator session.'), { code: 'HOST_CONTROL_FORBIDDEN', status: 403 }));
+ render(<DependencyImpactPanel project={project} onRepair={vi.fn()} />);
+ expect(await screen.findByText(/Asset dependency check needs an operator session/)).toBeInTheDocument();
+ expect(screen.queryByRole('alert')).not.toBeInTheDocument();
+ expect(screen.queryByRole('button', { name: 'Repair affected dependencies' })).not.toBeInTheDocument();
+ expect(getMusicVideoDependencyImpact).toHaveBeenCalledWith('example-project', { silent: true, hostControlOptional: true });
+ });
it('says no clips are needed when only review evidence is stale', async () => {
getMusicVideoDependencyImpact.mockResolvedValue({ ...impact, shots: [], estimate: { maxGenerations: 0, outputSeconds: 0, evidenceRebuilds: 2 } });
render(<DependencyImpactPanel project={project} onRepair={vi.fn()} />);
diff --git a/client/src/services/apiCore.js b/client/src/services/apiCore.js
index 9178b16205..1e8d1e044e 100644
--- a/client/src/services/apiCore.js
+++ b/client/src/services/apiCore.js
@@ -56,7 +56,9 @@ export function request(endpoint, options = {}) {
}
async function performRequest(endpoint, options = {}) {
- const { silent, responseType, ...fetchOptions } = options;
+ // `hostControlOptional` marks a background read whose caller renders its own
+ // "needs operator authority" state, so a host-control refusal does not toast.
+ const { silent, responseType, hostControlOptional, ...fetchOptions } = options;
const url = `${API_BASE}${endpoint}`;
// Skip the JSON content-type header for FormData bodies — the browser must
// set `multipart/form-data; boundary=…` itself, and any pre-supplied value
@@ -84,11 +86,12 @@ async function performRequest(endpoint, options = {}) {
try {
await throwApiError(response);
} catch (err) {
- // A host-control refusal (server: lib/hostControlRoutes.js) always
- // surfaces, even from a silent caller: the operator pressed a button
- // that ran nothing, and only this message says why.
+ // A host-control refusal (server: lib/hostControlRoutes.js) surfaces even
+ // from a silent caller: the operator pressed a button that ran nothing,
+ // and only this message says why. A `hostControlOptional` read was not a
+ // button press and shows the refusal itself.
if (err.code === 'HOST_CONTROL_FORBIDDEN') {
- toast.error(err.message);
+ if (!hostControlOptional) toast.error(err.message);
} else if (!silent) {
// Platform unavailability is a warning, not an error
if (err.code === 'PLATFORM_UNAVAILABLE') {
diff --git a/client/src/services/apiCore.test.js b/client/src/services/apiCore.test.js
index 56f8715fa6..b5a180685e 100644
--- a/client/src/services/apiCore.test.js
+++ b/client/src/services/apiCore.test.js
@@ -105,6 +105,16 @@ describe('request() error path (now delegating to throwApiError)', () => {
expect(toast.error).not.toHaveBeenCalled();
});
+ it('toasts a host-control refusal even for a silent caller, unless the read is marked optional', async () => {
+ const refusal = { error: 'Host control requires an operator session.', code: 'HOST_CONTROL_FORBIDDEN' };
+ global.fetch.mockResolvedValue(makeResponse({ status: 403, json: refusal }));
+ await expect(request('/x', { silent: true })).rejects.toMatchObject({ code: 'HOST_CONTROL_FORBIDDEN', status: 403 });
+ expect(toast.error).toHaveBeenCalledWith(refusal.error);
+ toast.error.mockClear();
+ await expect(request('/x', { silent: true, hostControlOptional: true })).rejects.toMatchObject({ code: 'HOST_CONTROL_FORBIDDEN' });
+ expect(toast.error).not.toHaveBeenCalled();
+ });
+
it('rejects with SERVER_UNREACHABLE code when fetch fails to connect', async () => {
global.fetch.mockRejectedValue(new Error('Connection refused'));
await expect(request('/x', { silent: true })).rejects.toMatchObject({
diff --git a/server/hostControlCoverage.test.js b/server/hostControlCoverage.test.js
index 45f2ada1f0..3f7994aa0f 100644
--- a/server/hostControlCoverage.test.js
+++ b/server/hostControlCoverage.test.js
@@ -17,10 +17,24 @@
* not tool-free belongs in HOST_CONTROL_ROUTES. Otherwise add it here with the
* reason constant that matches, or a new one. Every entry names what the
* route actually does; there is no catch-all "not yet reviewed" reason (#13055).
+ *
+ * GETs are covered by a static trace (#13097, test/processReachScan.js): a
+ * mounted GET whose handler can reach child_process, node-pty, a browser
+ * driver, ws, keytar, a DevTools endpoint, a computed import or an injected
+ * router dependency must be gated, or listed in REVIEWED_PROCESS_GETS with a
+ * reason. A fixed probe shared by many GETs is reviewed once, in
+ * REVIEWED_PROCESS_SITES, and ends the trace there. The trace follows a
+ * reached binding whole, so a GET that only reads a table of executors is
+ * still listed; its reason says so.
*/
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
import { describe, expect, it } from 'vitest';
import { scanRouteGraph } from './lib/apiRouteGraph.js';
import { hostControlBodyRouteFor, hostControlRouteFor } from './lib/hostControlRoutes.js';
+import { createProcessReachTracer } from './test/processReachScan.js';
const MUTATING_METHODS = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
@@ -1374,3 +1388,346 @@ describe('host-control coverage of mounted mutating routes (#12952)', () => {
expect(classify([{ method: 'PUT', path: '/api/settings' }], []).unclassified).toEqual([]);
});
});
+
+// --- GET routes that reach host-process work (#13097) ---
+
+// Site reasons: one reviewed binding, which ends the trace for every GET.
+const HOST_QUERY = 'Runs one fixed read-only host query (sysctl, nvidia-smi, vm_stat, ps or a process listing, lsof/netstat, du/find, `which`, `defaults read`, an is-running AppleScript, `tailscale status`, `ffmpeg -filters` or `-list_devices`); the caller chooses no command, argument or path, and host state does not change.';
+const VERSION_PROBE = 'Runs an installed tool or interpreter only to check it (`--version`, `brew list`, `--probe`, or a fixed `python -c` import or version script); the executable is PortOS-managed or comes from code or gated settings, and the check installs, starts and changes nothing.';
+const ICLOUD_HEAL = 'Asks iCloud (`brctl download`) to download the evicted file PortOS is already reading; the caller names no path and nothing else runs.';
+const GIT_PROBE = 'Runs a fixed read-only git or gh query (`rev-parse`, `remote get-url`, `status`, `gh api user` or `rate_limit`) and changes no repository or remote state.';
+const KILLS_OWN_CHILD = 'Signals a child process PortOS itself started (its timeout or cancel path); starts nothing.';
+const PM2_LIST = 'Reads `pm2 jlist` through a short-lived cache; starts, stops or changes no process.';
+const STATIC_JSON = 'Loads the checked-in prompt-integrity JSON snapshot with `require`; the path is a constant, not a computed module.';
+const CDP_VERSION = "Reads the managed browser's DevTools `/json/version` endpoint; opens, lists or steers no page.";
+
+// 'path#binding', repo-relative, as the trace labels module-scope bindings.
+const REVIEWED_PROCESS_SITES = [
+ ['server/lib/buildIdentity.js#probe', GIT_PROBE],
+ ['server/lib/bufferedSpawn.js#killProcessTree', KILLS_OWN_CHILD],
+ ['server/lib/commandExists.js#commandExists', VERSION_PROBE],
+ ['server/lib/cudaCapability.js#detectCudaComputeCapability', HOST_QUERY],
+ ['server/lib/cudaCapability.js#detectCudaGpus', HOST_QUERY],
+ ['server/lib/cudaCapability.js#detectCudaUtilization', HOST_QUERY],
+ ['server/lib/cudaCapability.js#queryNvidiaSmi', HOST_QUERY],
+ ['server/lib/detachedSpawn.js#processMatches', HOST_QUERY],
+ ['server/lib/detachedSpawn.js#queryWin32Command', HOST_QUERY],
+ ['server/lib/detachedSpawn.js#snapshotProcesses', HOST_QUERY],
+ ['server/lib/ffmpeg.js#supportsSetparamsFilter', HOST_QUERY],
+ ['server/lib/fileCore.js#dirSize', HOST_QUERY],
+ ['server/lib/fullDiskAccess.js#defaultReadProcess', HOST_QUERY],
+ ['server/lib/gitRemote.js#readRemoteUrl', GIT_PROBE],
+ ['server/lib/icloudFile.js#materializeAndWait', ICLOUD_HEAL],
+ ['server/lib/icloudFile.js#requestMaterialization', ICLOUD_HEAL],
+ ['server/lib/memoryStats.js#macMemory', HOST_QUERY],
+ ['server/lib/platform.js#getListeningPorts', HOST_QUERY],
+ ['server/lib/platform.js#probeArm64Hardware', HOST_QUERY],
+ ['server/lib/processEnv.js#whichFirst', HOST_QUERY],
+ ['server/lib/processEnv.js#whichFirstSync', HOST_QUERY],
+ ['server/lib/pythonSetup.js#isMuscriptorRuntimeReady', VERSION_PROBE],
+ ['server/lib/pythonSetup.js#probeFlux2Venv', VERSION_PROBE],
+ ['server/lib/pythonSetup.js#probePythonArch', VERSION_PROBE],
+ ['server/lib/pythonSetup.js#probePythonHealth', VERSION_PROBE],
+ ['server/lib/tailscale.js#readTailscaleStatus', HOST_QUERY],
+ ['server/services/agentManagement.js#getAgentProcessStats', HOST_QUERY],
+ ['server/services/agents.js#getProcessInfo', HOST_QUERY],
+ ['server/services/agents.js#readUnixSnapshot', HOST_QUERY],
+ ['server/services/agents.js#readWindowsSnapshot', HOST_QUERY],
+ ['server/services/browserService.js#getCdpVersion', CDP_VERSION],
+ ['server/services/dataManager.js#getDirSizeAndCount', HOST_QUERY],
+ ['server/services/git.js#isRepo', GIT_PROBE],
+ ['server/services/github.js#getGitHubAuthStatus', GIT_PROBE],
+ ['server/services/github.js#probeGh', GIT_PROBE],
+ ['server/services/imageGen/mossRuntime.js#probeMossBinary', VERSION_PROBE],
+ ['server/services/itermAuth.js#isItermRunning', HOST_QUERY],
+ ['server/services/itermAuth.js#readApiServerEnabled', HOST_QUERY],
+ ['server/services/jev.js#isBasePythonSupported', VERSION_PROBE],
+ ['server/services/llamaServerManager.js#readLlamaServerVersion', VERSION_PROBE],
+ ['server/services/mediaService.js#listDevices', HOST_QUERY],
+ ['server/services/modelAbuseGuard.js#isBasePythonSupported', VERSION_PROBE],
+ ['server/services/pipeline/musicGen.js#isEngineHealthy', VERSION_PROBE],
+ ['server/services/pm2.js#fetchJlist', PM2_LIST],
+ ['server/services/rigging/runtime.js#probeBlenderModule', VERSION_PROBE],
+ ['server/services/taskPromptDefaults/integrityHash.js#readPromptIntegritySnapshot', STATIC_JSON],
+ ['server/services/videoGen/runtimes.js#isByovRuntimeCurrent', VERSION_PROBE],
+ ['server/services/videoGen/runtimes.js#isByovRuntimeReady', VERSION_PROBE],
+ ['server/services/videoGen/runtimes.js#probeRuntimeFingerprint', VERSION_PROBE],
+ ['server/services/videoGen/runtimes.js#resolveByovRuntimeLoraCapable', VERSION_PROBE],
+ ['server/services/ytdlpUpdate.js#readYtDlpVersion', VERSION_PROBE],
+];
+
+// GET reasons.
+const FORGE_READ = "Reads repository and forge state: read-only git (status, branch, log, ls-files, ls-remote) in a registered app checkout or PortOS's own, and gh/glab queries authenticated with the stored forge token; changes no repository or remote state beyond PortOS's own records.";
+const PM2_READ = 'Reads PM2 process state or logs (`pm2 jlist`, `pm2 logs --nostream`) of a PortOS-managed process; starts, stops or reconfigures nothing.';
+const RUNTIME_STATUS = "Reports an installed local runtime's state with fixed status, version and import probes and PM2 reads (Ollama, llama-server, MTPLX, SlotStream, JEV, LAYA, the abuse guard, Docker, SuperCollider, a TTS or image backend, the database); installs, starts and reconfigures nothing.";
+const PROVIDER_STATUS = 'Reads installed provider CLIs and runtimes: `--version` and `models` probes of the configured commands, cached runtime readiness, and the Codex app-server account or model list; takes no caller prompt, command or provider choice, and the install and run functions in the runtime table run only from gated routes.';
+const PROVIDER_USAGE = 'Reads quota and usage from the enabled provider CLIs on their fixed usage commands (`claude /usage`, a TUI usage screen, the Codex app-server account read), cached; takes no caller prompt or provider choice.';
+const TOOLKIT_INJECTED = 'Toolkit factory route (lib/aiToolkit/routes and their PortOS wrappers): the handler reads provider, run, prompt or benchmark records through the injected service and starts no run.';
+const TOOL_CATALOG = 'Lists a catalog whose entries carry executors (agent, voice and creative tools, MCP tool adapters, mind recipes); the handler returns metadata, and the executors run only through the gated tool dispatch.';
+const JOB_TABLE = "Reads media-job queue state or a job record; the traced encoders and generators sit in the queue's runtime table and run only from the queue worker after a gated enqueue.";
+const ACTIVE_WORK_READ = 'Reports in-flight work by reading the in-memory state of the runner, backup and media-job modules, loaded lazily, plus GPU telemetry; starts none of it.';
+const STORED_MEDIA = 'Runs ffmpeg or ffprobe over media PortOS already stored (a generation history item, the song master, a music-library track, a sprite run) to probe it, decode it or write a derived cache file; the caller supplies no path or argument.';
+const MOLTBOOK_READ = 'Reads from the Moltbook API with the stored agent key; a response that demands verification is answered with the account\'s configured model and screened by the local abuse classifier, as on every Moltbook call.';
+const PEER_PAYLOAD = 'Peer endpoint in PEER_API_SURFACE that builds its payload from stored records; the executors the trace reaches come from whole-module namespace imports of the stores it reads.';
+const PEER_ADMIN_READ = 'Describes peer-administration state from stored grants and catalog reviews; the installer and execution adapters the trace reaches run only from the handler-gated execution and catalog-review writes.';
+
+// 'METHOD /path' as scanRouteGraph spells it, like REVIEWED_OPEN_MUTATIONS.
+const REVIEWED_PROCESS_GETS = [
+ ['GET /api/agent-context/manifest', TOOL_CATALOG],
+ ['GET /api/agents/tools/feed', MOLTBOOK_READ],
+ ['GET /api/agents/tools/post/:postId', MOLTBOOK_READ],
+ ['GET /api/agents/tools/published', MOLTBOOK_READ],
+ ['GET /api/agents/tools/rate-limits', MOLTBOOK_READ],
+ ['GET /api/agents/tools/relevant-posts', MOLTBOOK_READ],
+ ['GET /api/agents/tools/submolts', MOLTBOOK_READ],
+ ['GET /api/apps/:id', FORGE_READ],
+ ['GET /api/apps/:id/issues', FORGE_READ],
+ ['GET /api/apps/:id/lane-health', FORGE_READ],
+ ['GET /api/apps/:id/logs', PM2_READ],
+ ['GET /api/apps/:id/pull-requests', FORGE_READ],
+ ['GET /api/apps/:id/quality-schedule', FORGE_READ],
+ ['GET /api/apps/:id/repository-sources', "Inspects a managed app's checkouts with read-only git and gh queries, and refreshes origin with `git fetch` when the last fetch is stale; a fetch updates only remote-tracking refs, and the caller chooses no repository, remote or command."],
+ ['GET /api/beeper/oauth/callback', 'OAuth redirect target: stores the credential Beeper returns and arms its ingestion socket to the fixed Beeper endpoint, as completing the connection the operator started requires.'],
+ ['GET /api/browser', "Reads the managed browser's status, including its tab list over CDP; a caller without host control gets pages and downloads stripped (#12488)."],
+ ['GET /api/browser/logs', PM2_READ],
+ ['GET /api/capabilities', PROVIDER_STATUS],
+ ['GET /api/code-animation/execution', 'Reports which containment mechanism the code-animation worker would use, from a fixed Docker or sandbox availability probe; runs no worker.'],
+ ['GET /api/code-animation/generate/:id', JOB_TABLE],
+ ['GET /api/code-review/reviewer-identities', FORGE_READ],
+ ['GET /api/cos/actionable-insights', 'Runs the PM2 health sweep (it restarts errored processes) only for a caller with host control, like its gated twin POST /api/cos/health/check; anyone else reads the recorded snapshot. Leftover-branch detection runs read-only git and gh queries.'],
+ ['GET /api/cos/mind/recipes', TOOL_CATALOG],
+ ['GET /api/cos/mind/recipes/:recipeId', TOOL_CATALOG],
+ ['GET /api/cos/mind/tools', TOOL_CATALOG],
+ ['GET /api/cos/mind/visibility', 'Reads persistent-mind workspace preflights: read-only git status of each workspace and `--version` checks of the CLIs it would use; starts nothing.'],
+ ['GET /api/cos/schedule', FORGE_READ],
+ ['GET /api/cos/schedule/due', FORGE_READ],
+ ['GET /api/cos/schedule/due/:appId', FORGE_READ],
+ ['GET /api/cos/schedule/task/:taskType', FORGE_READ],
+ ['GET /api/cos/tools', TOOL_CATALOG],
+ ['GET /api/cos/upcoming', FORGE_READ],
+ ['GET /api/cos/workflow', FORGE_READ],
+ ['GET /api/creative-director/:id/execution', PROVIDER_STATUS],
+ ['GET /api/creative-director/tools', TOOL_CATALOG],
+ ['GET /api/database/status', 'Runs the fixed `scripts/db.sh status` report and Postgres size queries; changes no database or container.'],
+ ['GET /api/devtools/video-download/yt-dlp', RUNTIME_STATUS],
+ ['GET /api/digital-twin/gaps', 'Computes twin confidence locally: the handler calls calculateConfidence without a provider, so the provider branch the trace reaches never runs here.'],
+ ['GET /api/docker-containment/status', RUNTIME_STATUS],
+ ['GET /api/eidoverse/world/controllers', 'Lists Eidoverse controller definitions loaded with `import()` from the definitions directory PortOS ships; the caller names no module and no controller runs.'],
+ ['GET /api/federation/media/v1/status', 'Reports which local media generators this install offers peers, from readiness probes and the media-job queue\'s in-memory state; the encoders in the queue\'s runtime table run only from its worker.'],
+ ['GET /api/git/:appId', FORGE_READ],
+ ['GET /api/git/submodules/status', FORGE_READ],
+ ['GET /api/github/accounts/:id/status', FORGE_READ],
+ ['GET /api/harnesses', PROVIDER_STATUS],
+ ['GET /api/html-composition/beats', STORED_MEDIA],
+ ['GET /api/image-gen/status', RUNTIME_STATUS],
+ ['GET /api/image-to-3d/targets', 'Reports image-to-3D target install state with each adapter\'s fixed probes (Metal toolchain, module imports); the adapter table\'s install and generate functions run only from the gated install and generate routes.'],
+ ['GET /api/image-to-3d/targets/:targetId/install', 'Reports image-to-3D target install state with each adapter\'s fixed probes (Metal toolchain, module imports); the adapter table\'s install and generate functions run only from the gated install and generate routes.'],
+ ['GET /api/image-to-3d/trellis2/install', 'Reports image-to-3D target install state with each adapter\'s fixed probes (Metal toolchain, module imports); the adapter table\'s install and generate functions run only from the gated install and generate routes.'],
+ ['GET /api/iterm/status', 'Reports iTerm2 bridge availability from fixed probes (`defaults read`, an is-running AppleScript) and the bridge\'s current state; opens no API connection.'],
+ ['GET /api/local-llm/assessments', RUNTIME_STATUS],
+ ['GET /api/local-llm/capability-tests', RUNTIME_STATUS],
+ ['GET /api/local-llm/jev/heads', 'Lists trained JEV heads and whether training runs; the trainer module is loaded whole, but only its in-memory running flag is read.'],
+ ['GET /api/local-llm/jev/status', RUNTIME_STATUS],
+ ['GET /api/local-llm/laya-mlx/status', RUNTIME_STATUS],
+ ['GET /api/local-llm/llama-server/status', RUNTIME_STATUS],
+ ['GET /api/local-llm/llama-server/update-status', RUNTIME_STATUS],
+ ['GET /api/local-llm/mtplx/models/search', 'Searches the MTPLX model catalog with the installed CLI (`mtplx forge discover --json`), the caller\'s query passed as one argument with no shell; downloads nothing.'],
+ ['GET /api/local-llm/mtplx/status', RUNTIME_STATUS],
+ ['GET /api/local-llm/persistent-mind-setup', RUNTIME_STATUS],
+ ['GET /api/local-llm/security-guard/status', RUNTIME_STATUS],
+ ['GET /api/local-llm/slotstream/status', RUNTIME_STATUS],
+ ['GET /api/local-llm/status', RUNTIME_STATUS],
+ ['GET /api/logs/:processName', PM2_READ],
+ ['GET /api/logs/app/:appId', PM2_READ],
+ ['GET /api/managed-visitor-admin', 'Lists managed-app visitor credentials through the injected broker (services/managedVisitors.js); it issues and runs nothing.'],
+ ['GET /api/managed-visitors/v1/capabilities', 'Reads a managed-app visitor\'s capabilities through the injected broker (services/managedVisitors.js), whose credentials work only for a local same-origin app; it runs nothing.'],
+ ['GET /api/media-jobs', JOB_TABLE],
+ ['GET /api/media-jobs/:id', JOB_TABLE],
+ ['GET /api/media-jobs/holds', JOB_TABLE],
+ ['GET /api/media-jobs/queue', JOB_TABLE],
+ ['GET /api/models/performance/task-benchmark', TOOLKIT_INJECTED],
+ ['GET /api/music-video', JOB_TABLE],
+ ['GET /api/music-video/:id', JOB_TABLE],
+ ['GET /api/music-video/:id/film-looks', STORED_MEDIA],
+ ['GET /api/music-video/:id/media-pool/library', 'Searches stored media for the pool; the trace reaches the local image backend whole through a namespace import, while the handler reads only its gallery records.'],
+ ['GET /api/music-video/:id/media-pool/search', 'Searches stored media for the pool; the trace reaches the local image backend whole through a namespace import, while the handler reads only its gallery records.'],
+ ['GET /api/music-video/:id/publish/drafts', 'Checks whether each publish draft the operator opened through the gated prepare route is still a tab in the managed browser (a CDP target lookup); opens, fills or submits nothing.'],
+ ['GET /api/music-video/:id/render-cleanup', STORED_MEDIA],
+ ['GET /api/music-video/:id/shot-renders', STORED_MEDIA],
+ ['GET /api/music-video/:id/shot-renders/:name', STORED_MEDIA],
+ ['GET /api/music/supercollider/status', RUNTIME_STATUS],
+ ['GET /api/palette/manifest', TOOL_CATALOG],
+ ['GET /api/peer-administration/catalog-review', PEER_ADMIN_READ],
+ ['GET /api/peer-administration/catalog-reviews', PEER_ADMIN_READ],
+ ['GET /api/peer-administration/peers/:peerId', PEER_ADMIN_READ],
+ ['GET /api/peer-sync/cos-tasks', PEER_PAYLOAD],
+ ['GET /api/peer-sync/eidoverse-foundations', PEER_PAYLOAD],
+ ['GET /api/peer-sync/library-manifest', PEER_PAYLOAD],
+ ['GET /api/pipeline/tts/voices', 'Lists TTS voices from the configured engines\' catalogs; the synthesize functions in the engine table run only from the speak and synthesis routes.'],
+ ['GET /api/prompts', TOOLKIT_INJECTED],
+ ['GET /api/prompts/:stage', TOOLKIT_INJECTED],
+ ['GET /api/prompts/variables', TOOLKIT_INJECTED],
+ ['GET /api/prompts/variables/:key', TOOLKIT_INJECTED],
+ ['GET /api/providers', PROVIDER_STATUS],
+ ['GET /api/providers/:id', PROVIDER_STATUS],
+ ['GET /api/providers/:id/status', TOOLKIT_INJECTED],
+ ['GET /api/providers/active', PROVIDER_STATUS],
+ ['GET /api/providers/catalog', PROVIDER_STATUS],
+ ['GET /api/providers/codex/account', PROVIDER_STATUS],
+ ['GET /api/providers/codex/models', PROVIDER_STATUS],
+ ['GET /api/providers/comparison', TOOLKIT_INJECTED],
+ ['GET /api/providers/composites/:id', PROVIDER_STATUS],
+ ['GET /api/providers/fleet-host', PROVIDER_STATUS],
+ ['GET /api/providers/harnesses', PROVIDER_STATUS],
+ ['GET /api/providers/management/preview', TOOLKIT_INJECTED],
+ ['GET /api/providers/model-pins', FORGE_READ],
+ ['GET /api/providers/opencode/installation', PROVIDER_STATUS],
+ ['GET /api/providers/readiness', PROVIDER_STATUS],
+ ['GET /api/providers/runtimes', PROVIDER_STATUS],
+ ['GET /api/providers/samples', PROVIDER_STATUS],
+ ['GET /api/providers/status', TOOLKIT_INJECTED],
+ ['GET /api/quota-burn', PROVIDER_USAGE],
+ ['GET /api/remote-desktop/status', 'Reports whether a VNC server answers on the fixed loopback port; mints no session.'],
+ ['GET /api/review/queue', 'Builds the review queue from stored records and read-only git and forge queries; the provider calls in the trace come from a local `identity` that shadows the identity-service namespace import, so the whole service is followed.'],
+ ['GET /api/runs', TOOLKIT_INJECTED],
+ ['GET /api/runs/:id', TOOLKIT_INJECTED],
+ ['GET /api/runs/:id/output', TOOLKIT_INJECTED],
+ ['GET /api/runs/:id/prompt', TOOLKIT_INJECTED],
+ ['GET /api/settings/ai-assignments', FORGE_READ],
+ ['GET /api/settings/media-share-candidates', 'Reports which local media generators this install offers peers, from readiness probes and the media-job queue\'s in-memory state; the encoders in the queue\'s runtime table run only from its worker.'],
+ ['GET /api/sprites/:id/walk/runs/:runId/source-frames', STORED_MEDIA],
+ ['GET /api/system/activity', ACTIVE_WORK_READ],
+ ['GET /api/system/health/details', JOB_TABLE],
+ ['GET /api/system/processing', ACTIVE_WORK_READ],
+ ['GET /api/update/auto', ACTIVE_WORK_READ],
+ ['GET /api/update/status', FORGE_READ],
+ ['GET /api/usage', PROVIDER_USAGE],
+ ['GET /api/usage/claude-code', PROVIDER_USAGE],
+ ['GET /api/usage/providers', PROVIDER_USAGE],
+ ['GET /api/video-gen/active', JOB_TABLE],
+ ['GET /api/video-gen/history/:id', STORED_MEDIA],
+ ['GET /api/video-gen/history/:id/sharing-download', STORED_MEDIA],
+ ['GET /api/video-gen/upscale/:id/plan', STORED_MEDIA],
+ ['GET /api/voice/facetime/status', RUNTIME_STATUS],
+ ['GET /api/voice/public/voices', 'Lists TTS voices from the configured engines\' catalogs; the synthesize functions in the engine table run only from the speak and synthesis routes.'],
+ ['GET /api/voice/qwen3/status', RUNTIME_STATUS],
+ ['GET /api/voice/status', RUNTIME_STATUS],
+ ['GET /api/voice/voices', 'Lists TTS voices from the configured engines\' catalogs; the synthesize functions in the engine table run only from the speak and synthesis routes.'],
+ ['GET /api/workspace-contexts/:appId', FORGE_READ],
+];
+
+const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
+/** Classification problems of the GET `routes` (scanRouteGraph rows) traced with `routeSinks` against `entries`. */
+const classifyProcessGets = (routes, entries, routeSinks) => {
+ const reaching = new Set(routes
+ .filter((route) => route.method === 'GET' && route.declarations.some((declaration) => routeSinks(declaration).length))
+ .map(routeKey));
+ const seen = new Set();
+ const duplicated = [];
+ for (const [key] of entries) {
+ if (seen.has(key)) duplicated.push(key);
+ seen.add(key);
+ }
+ const alsoGated = [...seen].filter((key) => isGated(...key.split(' ')));
+ return {
+ unclassified: [...reaching].filter((key) => !seen.has(key) && !isGated(...key.split(' '))),
+ stale: [...seen].filter((key) => !reaching.has(key) && !alsoGated.includes(key)),
+ alsoGated,
+ duplicated,
+ };
+};
+
+const GET_RULES = 'Gate the GET in HOST_CONTROL_ROUTES (server/lib/hostControlRoutes.js), or list it in REVIEWED_PROCESS_GETS '
+ + '(server/hostControlCoverage.test.js) with what it actually runs. A fixed read-only probe many GETs share belongs in REVIEWED_PROCESS_SITES instead.';
+
+describe('host-control coverage of GET routes that reach host processes (#13097)', () => {
+ const { routes } = scanRouteGraph();
+ const tracer = createProcessReachTracer({ repoRoot: REPO_ROOT, reviewedSites: REVIEWED_PROCESS_SITES.map(([site]) => site) });
+
+ it('classifies every GET whose handler reaches host-process work, with no stale, gated or doubled entries', () => {
+ const problems = classifyProcessGets(routes, REVIEWED_PROCESS_GETS, tracer.routeSinks);
+ const evidence = problems.unclassified.map((key) => {
+ const route = routes.find((candidate) => routeKey(candidate) === key);
+ const declaration = route.declarations.find((candidate) => tracer.routeSinks(candidate).length);
+ return `${key}\n ${tracer.explainRoute(declaration).chain.join('\n > ')}`;
+ });
+ expect(evidence, `GET routes that reach host-process work. ${GET_RULES}`).toEqual([]);
+ expect(problems.stale, 'Reviewed GET entries whose route is gone or no longer reaches host-process work; delete them.').toEqual([]);
+ expect(problems.alsoGated, 'Reviewed GET entries that are also gated; delete them from REVIEWED_PROCESS_GETS.').toEqual([]);
+ expect(problems.duplicated, 'Reviewed GET entries listed twice.').toEqual([]);
+ }, 120_000);
+
+ it('keeps every reviewed site a live binding that still reaches host-process work', () => {
+ const dead = REVIEWED_PROCESS_SITES
+ .filter(([site]) => !tracer.traceSite(site)?.sinks.length)
+ .map(([site]) => site);
+ expect(dead, 'Reviewed sites that no longer exist or no longer reach a sink; delete them.').toEqual([]);
+ const sites = REVIEWED_PROCESS_SITES.map(([site]) => site);
+ expect(sites.filter((site, index) => sites.indexOf(site) !== index), 'Reviewed sites listed twice.').toEqual([]);
+ }, 120_000);
+
+ it('gives every reviewed GET and site a reason', () => {
+ expect([...REVIEWED_PROCESS_GETS, ...REVIEWED_PROCESS_SITES]
+ .filter(([, reason]) => typeof reason !== 'string' || !reason.trim())).toEqual([]);
+ });
+
+ it('fails on a new process-spawning GET, through a lazy import, a barrel, a namespace and an injected dependency', () => {
+ const root = mkdtempSync(join(tmpdir(), 'portos-process-gets-'));
+ const write = (relative, text) => {
+ mkdirSync(dirname(join(root, relative)), { recursive: true });
+ writeFileSync(join(root, relative), text);
+ };
+ try {
+ write('server/index.js', [
+ "import exampleRoutes from './routes/example.js';",
+ "import { createFactoryRoutes } from './routes/factory.js';",
+ "app.use('/api/example', exampleRoutes);",
+ "app.use('/api/factory', createFactoryRoutes(service));",
+ ].join('\n'));
+ write('server/routes/example.js', [
+ "import { Router } from 'express';",
+ "import { probe } from '../services/index.js';",
+ "import * as tabs from '../services/tabs.js';",
+ "import { readNotes } from '../services/notes.js';",
+ "import { fixedProbe } from '../services/fixed.js';",
+ 'const router = Router();',
+ "router.get('/lazy', async (req, res) => { const { encode } = await import('../services/encode.js'); res.json(await encode()); });",
+ "router.get('/barrel', async (req, res) => res.json(await probe()));",
+ "router.get('/namespace', async (req, res) => res.json(await tabs.open()));",
+ "router.get('/notes', async (req, res) => res.json(await readNotes()));",
+ "router.get('/reviewed', async (req, res) => res.json(await fixedProbe()));",
+ 'export default router;',
+ ].join('\n'));
+ write('server/routes/factory.js', [
+ "import { Router } from 'express';",
+ 'export function createFactoryRoutes(service) {',
+ ' const router = Router();',
+ " router.get('/', async (req, res) => res.json(await service.list()));",
+ ' return router;',
+ '}',
+ ].join('\n'));
+ write('server/services/encode.js', "import { spawn } from 'node:child_process';\nexport const encode = () => spawn('ffmpeg', ['-version']);\n");
+ write('server/services/index.js', "export * from './notes.js';\nexport * from './probe.js';\n");
+ write('server/services/probe.js', "import { execFile } from 'child_process';\nexport function probe() { return execFile('git', ['status']); }\n");
+ write('server/services/tabs.js', "export const open = () => fetch('http://127.0.0.1:9222/json/new?about:blank', { method: 'PUT' });\n");
+ write('server/services/notes.js', "import { readFile } from 'node:fs/promises';\nexport const readNotes = () => readFile('notes.json', 'utf8');\n");
+ write('server/services/fixed.js', "import { execFileSync } from 'node:child_process';\nexport const fixedProbe = () => execFileSync('sysctl', ['-n', 'hw.ncpu']);\n");
+
+ const fixture = scanRouteGraph({ repoRoot: root }).routes;
+ const traced = createProcessReachTracer({ repoRoot: root, reviewedSites: ['server/services/fixed.js#fixedProbe'] });
+ expect(classifyProcessGets(fixture, [], traced.routeSinks).unclassified.sort()).toEqual([
+ 'GET /api/example/barrel',
+ 'GET /api/example/lazy',
+ 'GET /api/example/namespace',
+ 'GET /api/factory',
+ ]);
+ expect(fixture.find((route) => route.path === '/api/example/namespace').declarations.flatMap(traced.routeSinks)).toEqual(['browser']);
+ expect(fixture.find((route) => route.path === '/api/factory').declarations.flatMap(traced.routeSinks)).toEqual(['injected-dependency']);
+ expect(traced.traceSite('server/services/fixed.js#fixedProbe').sinks).toEqual(['child_process']);
+ expect(classifyProcessGets(fixture, [['GET /api/example/notes', 'Reads notes.']], traced.routeSinks).stale).toEqual(['GET /api/example/notes']);
+ } finally {
+ rmSync(root, { recursive: true, force: true });
+ }
+ });
+});
diff --git a/server/lib/apiRouteGraph.js b/server/lib/apiRouteGraph.js
index 026c85709d..d6a918fda8 100644
--- a/server/lib/apiRouteGraph.js
+++ b/server/lib/apiRouteGraph.js
@@ -20,7 +20,10 @@
*
* `scanRouteGraph()` also returns every declaration's content key
* (`routeDeclarationKey`) so `apiRouteGraph.test.js` can prove the walk reaches
- * every declaration under `server/routes/` by comparing two in-memory scans.
+ * every declaration under `server/routes/` by comparing two in-memory scans,
+ * and each operation's `declarations` (module, router id, local path) so the
+ * host-control guard can find the handler a mounted route runs. The catalog
+ * omits `declarations`.
*/
import { readFileSync, statSync } from 'node:fs';
@@ -190,8 +193,10 @@ export function scanRouteGraph({ repoRoot = DEFAULT_REPO_ROOT, indexSource } = {
path,
mountPath,
sources: [],
+ declarations: [],
};
existing.sources.push(declaration.source);
+ existing.declarations.push(declaration);
operations.set(key, existing);
};
@@ -257,7 +262,11 @@ export function scanRouteGraph({ repoRoot = DEFAULT_REPO_ROOT, indexSource } = {
}
const routes = [...operations.values()]
- .map((operation) => ({ ...operation, sources: [...new Set(operation.sources)].sort() }))
+ .map((operation) => ({
+ ...operation,
+ sources: [...new Set(operation.sources)].sort(),
+ declarations: [...new Map(operation.declarations.map((d) => [routeDeclarationKey(d), d])).values()],
+ }))
.sort((a, b) => a.path.localeCompare(b.path) || a.method.localeCompare(b.method));
// Collisions are counted PER MODULE, from the parsed declarations rather than
@@ -291,7 +300,7 @@ export function buildApiRouteCatalog(options = {}) {
return {
derivedFrom: DERIVED_FROM,
mounts,
- routes,
+ routes: routes.map(({ declarations: _declarations, ...route }) => route),
stats: {
mounts: mounts.length,
operations: routes.length,
diff --git a/server/lib/hostControlRoutes.js b/server/lib/hostControlRoutes.js
index 13b577b0db..926cd6dba6 100644
--- a/server/lib/hostControlRoutes.js
+++ b/server/lib/hostControlRoutes.js
@@ -242,6 +242,25 @@
* (server/hostControlCoverage.test.js), which fails CI on a new, stale or
* double-listed route. Classify a new route when you add it, using the
* family notes above.
+ *
+ * GET routes are covered by a static trace instead (#13097): the same guard
+ * follows each mounted GET handler through the module-scope bindings it names,
+ * lazy `import()`s, barrels and namespace imports included, to child_process,
+ * node-pty, playwright/puppeteer, ws, keytar, a DevTools endpoint, a computed
+ * import or an injected router dependency (server/test/processReachScan.js).
+ * A GET whose trace reaches one is gated here or listed in
+ * REVIEWED_PROCESS_GETS with a reason; a fixed probe that many GETs share
+ * (sysctl, nvidia-smi, `--version`, `brctl download`) is reviewed once in
+ * REVIEWED_PROCESS_SITES and ends the trace. The trace over-approximates —
+ * a reached binding counts whole — so a reason may say that the traced
+ * executor sits in a table the handler only reads. Gated GETs: the dependency
+ * impact preview (an ffmpeg decode of the song master) and the YouTube setup
+ * check (it opens and reads a tab in the signed-in browser); the client shows
+ * a refused preview as unavailable. Open with a reason: version, status and
+ * import probes, PM2 and git/forge reads, ffprobe of stored media, and the
+ * actionable-insights PM2 sweep, which runs only for a caller with host
+ * control (POST /api/cos/health/check is its gated twin). A callback stored at
+ * runtime or an EventEmitter listener is not followed, so read for those.
*/
import { canonicalStringify, isPlainObject, POLLUTING_KEYS } from './objects.js';
@@ -1288,6 +1307,13 @@ export const HOST_CONTROL_ROUTES = Object.freeze([
'POST /api/eidoverse/travel/depart',
'PUT /api/eidoverse/world/config',
'PATCH /api/eidoverse/world/controllers/:id/config',
+
+ // GET routes the process-reach trace found starting host work (#13097): the
+ // dependency-impact preview decodes the current song master with ffmpeg to
+ // compare sung windows, and the YouTube setup check opens or reuses a tab in
+ // the signed-in managed browser and reads it (#12488 rule).
+ 'GET /api/music-video/:id/dependency-impact',
+ 'GET /api/youtube/setup-check',
]);
/**
diff --git a/server/routes/cosInsightRoutes.js b/server/routes/cosInsightRoutes.js
index 8d25ff0ca0..5474180671 100644
--- a/server/routes/cosInsightRoutes.js
+++ b/server/routes/cosInsightRoutes.js
@@ -17,6 +17,7 @@ import { asyncHandler, ServerError } from '../lib/errorHandler.js';
import { parsePagination, validateRequest } from '../lib/validation.js';
import { runningAgentsByTaskId, withoutSpawningTasks } from '../lib/cosSpawnWindow.js';
import { detectIdleLeftoverBranches } from '../services/userActionDetectors.js';
+import { requestHasHostControl } from '../services/authGate.js';
const router = Router();
@@ -33,10 +34,13 @@ router.get('/activity-calendar', asyncHandler(async (req, res) => {
// Surfaces the most important things to address right now across all CoS subsystems
router.get('/actionable-insights', asyncHandler(async (req, res) => {
const { cachedHealth } = validateRequest(z.object({ cachedHealth: z.literal('1').optional() }), req.query);
+ // The live check is the PM2 sweep that restarts errored processes, the work
+ // POST /api/cos/health/check gates; anyone else reads the last snapshot (#13097).
+ const liveHealth = !cachedHealth && requestHasHostControl(req);
const [tasksData, learningSummary, healthCheck, notificationsModule, pendingFeedbackCount, leftoverFindings, agents] = await Promise.all([
getAllTasks().catch(err => { console.error(`❌ Failed to load tasks: ${err.message}`); return { user: null, cos: null }; }),
taskLearning.getLearningInsights().catch(err => { console.error(`❌ Failed to load learning insights: ${err.message}`); return null; }),
- (cachedHealth ? getHealthStatus() : runHealthCheck()).catch(err => { console.error(`❌ Failed to run health check: ${err.message}`); return null; }),
+ (liveHealth ? runHealthCheck() : getHealthStatus()).catch(err => { console.error(`❌ Failed to run health check: ${err.message}`); return null; }),
import('../services/notifications.js').catch(err => { console.error(`❌ Failed to load notifications: ${err.message}`); return null; }),
getPendingAgentFeedbackCount().catch(err => { console.error(`❌ Failed to load pending agent feedback: ${err.message}`); return 0; }),
detectIdleLeftoverBranches().catch(err => { console.error(`❌ Failed to detect leftover branches: ${err.message}`); return []; }),
diff --git a/server/routes/cosInsightRoutes.test.js b/server/routes/cosInsightRoutes.test.js
index 4db0a69916..cbbdbaf2ce 100644
--- a/server/routes/cosInsightRoutes.test.js
+++ b/server/routes/cosInsightRoutes.test.js
@@ -61,10 +61,21 @@ import * as notifications from '../services/notifications.js';
describe('CoS Insight Routes', () => {
let app;
+ // A password-free install: the loopback test client is a local operator.
+ const appFor = (address) => {
+ const instance = express();
+ instance.use((req, _res, next) => {
+ if (address) Object.defineProperty(req.socket, 'remoteAddress', { value: address });
+ req.portosAuthContext = { enabled: false };
+ next();
+ });
+ instance.use(express.json());
+ instance.use('/api/cos', insightRoutes);
+ return instance;
+ };
+
beforeEach(() => {
- app = express();
- app.use(express.json());
- app.use('/api/cos', insightRoutes);
+ app = appFor();
vi.clearAllMocks();
getPendingAgentFeedbackCount.mockResolvedValue(0);
// clearAllMocks keeps implementations, so a per-test override would leak
@@ -119,6 +130,16 @@ describe('CoS Insight Routes', () => {
expect(response.body.unavailableSources).toEqual([]);
});
+ it('reads the recorded health snapshot for a caller without host control instead of running the PM2 sweep', async () => {
+ getAllTasks.mockResolvedValue({ user: null, cos: null });
+ taskLearning.getLearningInsights.mockResolvedValue(null);
+ getHealthStatus.mockResolvedValue({ issues: [] });
+ const response = await request(appFor('192.0.2.10')).get('/api/cos/actionable-insights');
+ expect(response.status).toBe(200);
+ expect(getHealthStatus).toHaveBeenCalledTimes(1);
+ expect(runHealthCheck).not.toHaveBeenCalled();
+ });
+
it('should return actionable insights sorted by priority', async () => {
getAllTasks.mockResolvedValue({
user: { grouped: { pending: [{ id: 't1', description: 'Task' }], blocked: [] } },
diff --git a/server/routes/hostControlMusicVideoPreGuard.test.js b/server/routes/hostControlMusicVideoPreGuard.test.js
index ce2a435e92..6582f4e694 100644
--- a/server/routes/hostControlMusicVideoPreGuard.test.js
+++ b/server/routes/hostControlMusicVideoPreGuard.test.js
@@ -33,6 +33,7 @@ const effects = vi.hoisted(() => {
importDocumentZip: resolves({ project }),
checkOverlayTextInBackground: vi.fn(),
startDependencyRepair: resolves({ project }),
+ getDependencyImpact: resolves({ shots: [], evidence: [] }),
reviewArtifact: resolves({ project }),
prepareProductionReview: resolves({ project }),
renderProductionProof: resolves({ jobId: 'example-job' }),
@@ -118,6 +119,7 @@ vi.mock('../services/musicVideo/overlayTextService.js', async (importOriginal) =
vi.mock('../services/musicVideo/revisionService.js', async (importOriginal) => ({
...await importOriginal(),
startDependencyRepair: effects.startDependencyRepair,
+ getDependencyImpact: effects.getDependencyImpact,
resumeRevision: effects.resumeRevision,
}));
vi.mock('../services/musicVideo/devArtifactService.js', async (importOriginal) => ({
@@ -195,6 +197,8 @@ const operations = [
['post', `${PROJECT}/cast-and-sets/approve`, {}, effects.approveCastAndSets, 200],
['post', `${PROJECT}/cast-and-sets/skip`, {}, effects.skipCastAndSets, 200],
['post', `${PROJECT}/dependency-repairs`, { basis: 'example-basis' }, effects.startDependencyRepair, 201],
+ // The preview decodes the song master with ffmpeg (#13097).
+ ['get', `${PROJECT}/dependency-impact`, undefined, effects.getDependencyImpact, 200],
['post', `${PROJECT}/production-review/prepare`, { providerId: 'example-provider', model: 'example-model' }, effects.prepareProductionReview, 200],
['post', `${PROJECT}/production-review/proof`, { startSec: 0, endSec: 12 }, effects.renderProductionProof, 202],
['post', `${PROJECT}/production-review/text-check`, {}, effects.startOverlayTextCheck, 202],
@@ -225,9 +229,9 @@ const appFor = (address = '192.0.2.10') => {
};
const call = (app, [method, path, body], headers = {}) => {
const pending = request(app)[method](path);
- if (body.raw) pending.set('Content-Type', `multipart/form-data; boundary=${BOUNDARY}`);
+ if (body?.raw) pending.set('Content-Type', `multipart/form-data; boundary=${BOUNDARY}`);
for (const [name, value] of Object.entries(headers)) pending.set(name, value);
- return pending.send(body.raw ?? body);
+ return pending.send(body?.raw ?? body);
};
const expectNoEffects = () => {
for (const effect of Object.values(effects)) expect(effect).not.toHaveBeenCalled();
diff --git a/server/routes/hostControlPreGuardPrivacy.test.js b/server/routes/hostControlPreGuardPrivacy.test.js
index 9c64bcb96f..f4be97bcfb 100644
--- a/server/routes/hostControlPreGuardPrivacy.test.js
+++ b/server/routes/hostControlPreGuardPrivacy.test.js
@@ -13,7 +13,7 @@ afterAll(cleanupTempDataRoots);
// Privacy broker scans, opt-out and verification passes, arming the broker
// recheck (route body or the `privacy` settings slice), broker consent grants,
-// YouTube scrapes in the managed browser and Google Calendar goal blocks need
+// YouTube scrapes and the setup check in the managed browser, and Google Calendar goal blocks need
// operator authority (#13055). Real routers behind the real gates; the first
// service boundary is doubled so no browser, mail, DB or Google call runs.
const auth = vi.hoisted(() => ({ enabled: false }));
@@ -25,6 +25,7 @@ const effects = vi.hoisted(() => ({
restartRecheck: vi.fn(async () => {}),
recordConsent: vi.fn(async (grant) => ({ id: 'example-grant', ...grant })),
youtubeSync: vi.fn(async () => ({ ok: true })),
+ youtubeSetupCheck: vi.fn(async () => ({ ok: true })),
playlistSync: vi.fn(async () => ({ ok: true })),
scheduleGoal: vi.fn(async () => ({ scheduled: 0 })),
rescheduleGoal: vi.fn(async () => ({ scheduled: 0 })),
@@ -56,7 +57,7 @@ vi.mock('../services/privacyVault.js', () => ({}));
vi.mock('../services/privacyOrgs.js', () => ({}));
vi.mock('../services/privacyBrokers.js', () => ({}));
vi.mock('../services/privacyChanges.js', () => ({}));
-vi.mock('../services/youtubeSync.js', () => ({ runSync: effects.youtubeSync }));
+vi.mock('../services/youtubeSync.js', () => ({ runSync: effects.youtubeSync, checkSetup: effects.youtubeSetupCheck }));
vi.mock('../services/youtubePlaylists.js', () => ({ syncYoutubePlaylists: effects.playlistSync }));
vi.mock('../services/goalCalendarScheduler.js', () => ({
scheduleTimeBlocks: effects.scheduleGoal, rescheduleTimeBlocks: effects.rescheduleGoal,
@@ -79,6 +80,8 @@ const operations = [
['post', '/api/privacy/optout/verify', {}, effects.verify, 200],
['post', '/api/youtube/sync', {}, effects.youtubeSync, 200],
['post', '/api/youtube/playlists/sync', {}, effects.playlistSync, 200],
+ // Opens or reuses a YouTube tab in the signed-in browser and reads it (#13097).
+ ['get', '/api/youtube/setup-check', undefined, effects.youtubeSetupCheck, 200],
['post', '/api/digital-twin/identity/goals/example-goal/schedule', {}, effects.scheduleGoal, 200],
['post', '/api/digital-twin/identity/goals/example-goal/reschedule', {}, effects.rescheduleGoal, 200],
['put', schedule, { enabled: true }, effects.restartRecheck, 200],
diff --git a/server/test/processReachScan.js b/server/test/processReachScan.js
new file mode 100644
index 0000000000..3647c7fe0d
--- /dev/null
+++ b/server/test/processReachScan.js
@@ -0,0 +1,725 @@
+/**
+ * Static trace from a mounted route handler to host-process work (#13097).
+ *
+ * The host-control guard (server/hostControlCoverage.test.js) uses this to find
+ * GET routes whose handler can start a process, drive a browser or read the
+ * keychain. Matching module imports would flag nearly every route, because
+ * almost every route module reaches `child_process` somewhere in its import
+ * closure. The trace therefore works on module-scope bindings instead:
+ *
+ * handler arguments → the module-scope bindings and imports they name
+ * → each binding's own body → … → a SINK
+ *
+ * Sinks: an import (or `require` / `process.getBuiltinModule`) of
+ * child_process, node-pty, playwright, puppeteer, keytar or ws; a global
+ * `WebSocket`; a DevTools HTTP endpoint literal (`/json/new`, `/json/list`, …);
+ * an `import()` whose specifier is computed; and a dependency injected into a
+ * router factory (a parameter of the function that declares the route), which
+ * the trace cannot see through.
+ *
+ * Over-approximations, all in the direction of reporting more:
+ * - a binding is reached whole: every name its body mentions is followed,
+ * whichever branch would run it;
+ * - a module-scope name is followed even where a local shadows it;
+ * - `ns.member` on a namespace import follows `member`; any other use of the
+ * namespace follows the whole module, as does an `import()` whose result
+ * is not destructured;
+ * - `export *` barrels try every star source;
+ * - an `import()` target's top-level statements count, because the first
+ * request evaluates them.
+ *
+ * Not followed, so a classifier must read for them: a callback stored at
+ * runtime (a setter, a Map registry) and later called through module state,
+ * an EventEmitter listener registered in another module, and router-level
+ * `use()` middleware.
+ */
+import { parse } from '@babel/parser';
+import { readFileSync, statSync } from 'node:fs';
+import { dirname, extname, join, relative, resolve, sep } from 'node:path';
+
+const SINK_PACKAGES = new Map([
+ ['child_process', 'child_process'],
+ ['node:child_process', 'child_process'],
+ ['node-pty', 'pty'],
+ ['playwright', 'browser'],
+ ['playwright-core', 'browser'],
+ ['puppeteer', 'browser'],
+ ['puppeteer-core', 'browser'],
+ ['keytar', 'keychain'],
+ ['ws', 'websocket'],
+]);
+// PortOS's drop-in child_process wrapper; its callers are the sites worth naming.
+const SINK_MODULES = new Map([['server/lib/childProcess.js', 'child_process']]);
+// DevTools HTTP endpoints: opening, listing or closing tabs in a Chrome over CDP.
+const CDP_ENDPOINT_RE = /\/json\/(?:new|list|close|activate|version|protocol)\b/;
+const FUNCTION_TYPES = new Set(['FunctionDeclaration', 'FunctionExpression', 'ArrowFunctionExpression', 'ObjectMethod', 'ClassMethod', 'ClassPrivateMethod']);
+const SKIP_KEYS = new Set(['loc', 'extra', 'leadingComments', 'trailingComments', 'innerComments', 'start', 'end', 'range']);
+
+const isFile = (path) => statSync(path, { throwIfNoEntry: false })?.isFile() === true;
+const isDirectory = (path) => statSync(path, { throwIfNoEntry: false })?.isDirectory() === true;
+
+const resolveLocalModule = (fromFile, specifier) => {
+ const candidate = resolve(dirname(fromFile), specifier.split(/[?#]/)[0]);
+ if (extname(candidate) && isFile(candidate)) return candidate;
+ if (isFile(`${candidate}.js`)) return `${candidate}.js`;
+ if (isDirectory(candidate) && isFile(join(candidate, 'index.js'))) return join(candidate, 'index.js');
+ return null;
+};
+
+const stringValue = (node) => {
+ if (node?.type === 'StringLiteral') return node.value;
+ if (node?.type === 'TemplateLiteral' && node.expressions.length === 0) return node.quasis[0].value.cooked;
+ return null;
+};
+
+const sinkForSpecifier = (specifier) => SINK_PACKAGES.get(specifier)
+ ?? SINK_PACKAGES.get(specifier?.split('/').slice(0, specifier.startsWith('@') ? 2 : 1).join('/'));
+
+/** Names a binding pattern declares, and the expressions inside it (defaults, computed keys) that are references. */
+function patternParts(pattern, names = [], expressions = []) {
+ if (!pattern) return { names, expressions };
+ switch (pattern.type) {
+ case 'Identifier': names.push(pattern.name); break;
+ case 'AssignmentPattern': patternParts(pattern.left, names, expressions); expressions.push(pattern.right); break;
+ case 'RestElement': patternParts(pattern.argument, names, expressions); break;
+ case 'ArrayPattern': pattern.elements.forEach((element) => patternParts(element, names, expressions)); break;
+ case 'ObjectPattern':
+ for (const property of pattern.properties) {
+ if (property.type === 'RestElement') patternParts(property.argument, names, expressions);
+ else {
+ if (property.computed) expressions.push(property.key);
+ patternParts(property.value, names, expressions);
+ }
+ }
+ break;
+ default: expressions.push(pattern); // MemberExpression targets in assignment patterns
+ }
+ return { names, expressions };
+}
+
+/** Property names destructured from an `await import()` result, or null for "the whole module". */
+function destructuredNames(pattern) {
+ if (pattern?.type !== 'ObjectPattern') return null;
+ const names = [];
+ for (const property of pattern.properties) {
+ if (property.type === 'RestElement' || property.computed) return null;
+ names.push(property.key.name ?? property.key.value);
+ }
+ return names;
+}
+
+const isDynamicImport = (node) => node?.type === 'ImportExpression'
+ || (node?.type === 'CallExpression' && node.callee?.type === 'Import');
+const dynamicImportSource = (node) => (node.type === 'ImportExpression' ? node.source : node.arguments[0]);
+
+/**
+ * Everything one subtree refers to: `names` it mentions in reference position,
+ * `namespaceMembers` read off a namespace import, `imports` it loads lazily,
+ * `sinks` it touches directly, and the `declared` names it binds itself.
+ */
+function collectReferences(root, namespaces) {
+ const names = new Set();
+ const declared = new Set();
+ const namespaceMembers = [];
+ const memberRefs = [];
+ const imports = [];
+ const sinks = [];
+ // Locals holding an `import()` namespace: `const mod = await import('./x.js')`
+ // or `import('./x.js').then((mod) => …)`. `mod.member` loads only that member.
+ const aliases = new Map();
+
+ const declare = (pattern) => {
+ const parts = patternParts(pattern);
+ parts.names.forEach((name) => declared.add(name));
+ parts.expressions.forEach((expression) => visit(expression));
+ };
+
+ const visitDynamicImport = (node, members) => {
+ const specifier = stringValue(dynamicImportSource(node));
+ if (specifier === null) sinks.push('computed-import');
+ else imports.push({ specifier, members });
+ (node.arguments ?? []).slice(1).forEach(visit);
+ if (node.options) visit(node.options);
+ };
+
+ // `const { a } = await import('./x.js')` and `(await import('./x.js')).a` load only `a`.
+ const awaitedImport = (node) => {
+ const inner = node?.type === 'AwaitExpression' ? node.argument : node;
+ return isDynamicImport(inner) ? inner : null;
+ };
+
+ // Bind an `import()` result to a pattern: destructured names, an alias, or the whole module.
+ const bindImport = (importNode, pattern) => {
+ if (pattern?.type === 'Identifier') {
+ const specifier = stringValue(dynamicImportSource(importNode));
+ if (specifier !== null) {
+ visitDynamicImport(importNode, []);
+ aliases.set(pattern.name, specifier);
+ declared.add(pattern.name);
+ return;
+ }
+ }
+ visitDynamicImport(importNode, destructuredNames(pattern));
+ declare(pattern);
+ };
+
+ function visit(node) {
+ if (!node || typeof node !== 'object') return;
+ if (Array.isArray(node)) { node.forEach(visit); return; }
+ if (typeof node.type !== 'string') return;
+ switch (node.type) {
+ case 'Identifier':
+ names.add(node.name);
+ return;
+ case 'StringLiteral':
+ if (CDP_ENDPOINT_RE.test(node.value)) sinks.push('browser');
+ return;
+ case 'TemplateLiteral':
+ if (node.quasis.some((quasi) => CDP_ENDPOINT_RE.test(quasi.value.raw))) sinks.push('browser');
+ node.expressions.forEach(visit);
+ return;
+ case 'MemberExpression':
+ case 'OptionalMemberExpression': {
+ if (node.object.type === 'Identifier' && !node.computed && node.property.type === 'Identifier') {
+ const { name } = node.object;
+ const member = node.property.name;
+ if (aliases.has(name)) imports.push({ specifier: aliases.get(name), members: [member] });
+ else if (namespaces.has(name)) namespaceMembers.push({ local: name, member });
+ else memberRefs.push({ name, member });
+ return;
+ }
+ const imported = awaitedImport(node.object);
+ if (imported && !node.computed) {
+ visitDynamicImport(imported, [node.property.name]);
+ return;
+ }
+ visit(node.object);
+ if (node.computed) visit(node.property);
+ return;
+ }
+ case 'VariableDeclarator': {
+ const imported = awaitedImport(node.init);
+ if (imported) { bindImport(imported, node.id); return; }
+ // `const [{ a }, { b }] = await Promise.all([import('./x.js'), import('./y.js')])`
+ const all = node.init?.type === 'AwaitExpression' ? node.init.argument : null;
+ if (node.id.type === 'ArrayPattern' && all?.type === 'CallExpression' && all.callee.type === 'MemberExpression'
+ && all.callee.object.name === 'Promise' && all.callee.property.name === 'all'
+ && all.arguments[0]?.type === 'ArrayExpression' && all.arguments[0].elements.every(isDynamicImport)) {
+ all.arguments[0].elements.forEach((element, index) => {
+ const pattern = node.id.elements[index];
+ if (pattern) bindImport(element, pattern);
+ else visitDynamicImport(element, []);
+ });
+ return;
+ }
+ visit(node.init);
+ declare(node.id);
+ return;
+ }
+ case 'ImportExpression':
+ visitDynamicImport(node, null);
+ return;
+ case 'CallExpression':
+ case 'OptionalCallExpression':
+ case 'NewExpression': {
+ if (isDynamicImport(node)) { visitDynamicImport(node, null); return; }
+ const callee = node.callee;
+ const handler = node.arguments?.[0];
+ if ((callee.type === 'MemberExpression' || callee.type === 'OptionalMemberExpression') && !callee.computed
+ && callee.property.name === 'then' && isDynamicImport(callee.object)
+ && (handler?.type === 'ArrowFunctionExpression' || handler?.type === 'FunctionExpression')) {
+ bindImport(callee.object, handler.params[0]);
+ handler.params.slice(1).forEach(declare);
+ visit(handler.body);
+ node.arguments.slice(1).forEach(visit);
+ return;
+ }
+ const first = stringValue(node.arguments?.[0]);
+ const isRequire = callee.type === 'Identifier' && callee.name === 'require';
+ const isBuiltin = (callee.type === 'MemberExpression' || callee.type === 'OptionalMemberExpression')
+ && callee.object.type === 'Identifier' && callee.object.name === 'process'
+ && !callee.computed && callee.property.name === 'getBuiltinModule';
+ if ((isRequire || isBuiltin) && first !== null && sinkForSpecifier(first)) sinks.push(sinkForSpecifier(first));
+ if (isRequire && first === null) sinks.push('computed-import');
+ break;
+ }
+ case 'ObjectProperty':
+ if (node.computed) visit(node.key);
+ visit(node.value);
+ return;
+ case 'ObjectMethod':
+ case 'ClassMethod':
+ case 'ClassPrivateMethod':
+ if (node.computed) visit(node.key);
+ node.params.forEach(declare);
+ visit(node.body);
+ return;
+ case 'ClassProperty':
+ case 'ClassPrivateProperty':
+ case 'ClassAccessorProperty':
+ if (node.computed) visit(node.key);
+ visit(node.value);
+ return;
+ case 'FunctionDeclaration':
+ case 'FunctionExpression':
+ case 'ArrowFunctionExpression':
+ case 'ClassDeclaration':
+ case 'ClassExpression':
+ if (node.id) declared.add(node.id.name);
+ (node.params ?? []).forEach(declare);
+ visit(node.superClass);
+ visit(node.body);
+ return;
+ case 'CatchClause':
+ declare(node.param);
+ visit(node.body);
+ return;
+ case 'LabeledStatement':
+ visit(node.body);
+ return;
+ case 'BreakStatement':
+ case 'ContinueStatement':
+ case 'MetaProperty':
+ case 'PrivateName':
+ return;
+ default:
+ break;
+ }
+ for (const [key, child] of Object.entries(node)) {
+ if (!SKIP_KEYS.has(key) && key !== 'type') visit(child);
+ }
+ }
+
+ visit(root);
+ // An alias used other than as `alias.member` (passed on, spread, indexed) loads the whole module.
+ for (const [alias, specifier] of aliases) {
+ if (names.has(alias)) imports.push({ specifier, members: null });
+ }
+ return { names, declared, namespaceMembers, memberRefs, imports, sinks };
+}
+
+function parseModule(file) {
+ const source = readFileSync(file, 'utf8');
+ const ast = parse(source, {
+ sourceType: 'module',
+ errorRecovery: true,
+ allowReturnOutsideFunction: true,
+ createImportExpressions: true,
+ });
+ const imports = new Map(); // local → { specifier, imported } ('*' for a namespace)
+ const bindings = new Map(); // top-level name → [node]
+ const exports = new Map(); // exported name → { local } | { specifier, imported }
+ const stars = [];
+ const sideEffects = [];
+ const addBinding = (name, node) => bindings.set(name, [...(bindings.get(name) ?? []), node]);
+ const declareTop = (declaration) => {
+ if (!declaration) return [];
+ if (declaration.type === 'VariableDeclaration') {
+ return declaration.declarations.flatMap((declarator) => {
+ const { names } = patternParts(declarator.id);
+ names.forEach((name) => addBinding(name, declarator));
+ return names;
+ });
+ }
+ if (declaration.id) {
+ addBinding(declaration.id.name, declaration);
+ return [declaration.id.name];
+ }
+ return [];
+ };
+
+ for (const statement of ast.program.body) {
+ switch (statement.type) {
+ case 'ImportDeclaration':
+ for (const specifier of statement.specifiers) {
+ const imported = specifier.type === 'ImportNamespaceSpecifier' ? '*'
+ : specifier.type === 'ImportDefaultSpecifier' ? 'default'
+ : (specifier.imported.name ?? specifier.imported.value);
+ imports.set(specifier.local.name, { specifier: statement.source.value, imported });
+ }
+ break;
+ case 'ExportNamedDeclaration':
+ if (statement.declaration) {
+ declareTop(statement.declaration).forEach((name) => exports.set(name, { local: name }));
+ }
+ for (const specifier of statement.specifiers ?? []) {
+ const exported = specifier.exported.name ?? specifier.exported.value;
+ if (statement.source) {
+ const imported = specifier.type === 'ExportNamespaceSpecifier' ? '*' : (specifier.local.name ?? specifier.local.value);
+ exports.set(exported, { specifier: statement.source.value, imported });
+ } else {
+ exports.set(exported, { local: specifier.local.name });
+ }
+ }
+ break;
+ case 'ExportAllDeclaration':
+ if (statement.exported) exports.set(statement.exported.name, { specifier: statement.source.value, imported: '*' });
+ else stars.push(statement.source.value);
+ break;
+ case 'ExportDefaultDeclaration': {
+ const declaration = statement.declaration;
+ if (declaration.type === 'Identifier') exports.set('default', { local: declaration.name });
+ else if (declaration.id) {
+ addBinding(declaration.id.name, declaration);
+ exports.set('default', { local: declaration.id.name });
+ } else {
+ addBinding('*default*', declaration);
+ exports.set('default', { local: '*default*' });
+ }
+ break;
+ }
+ case 'VariableDeclaration':
+ case 'FunctionDeclaration':
+ case 'ClassDeclaration':
+ declareTop(statement);
+ break;
+ default:
+ sideEffects.push(statement);
+ }
+ }
+ const namespaces = new Set([...imports].filter(([, entry]) => entry.imported === '*').map(([local]) => local));
+ return { file, ast, imports, bindings, exports, stars, sideEffects, namespaces };
+}
+
+/** Route-registration calls (`<router>.<method>('<path>', …handlers)`) with the functions enclosing each. */
+function routeCalls(ast) {
+ const calls = [];
+ const walk = (node, enclosing) => {
+ if (!node || typeof node !== 'object') return;
+ if (Array.isArray(node)) { node.forEach((child) => walk(child, enclosing)); return; }
+ if (typeof node.type !== 'string') return;
+ if (node.type === 'CallExpression' && node.callee.type === 'MemberExpression' && !node.callee.computed
+ && node.callee.object.type === 'Identifier' && stringValue(node.arguments[0]) !== null) {
+ calls.push({
+ routerId: node.callee.object.name,
+ method: node.callee.property.name,
+ path: stringValue(node.arguments[0]),
+ handlers: node.arguments.slice(1),
+ enclosing,
+ });
+ }
+ const next = FUNCTION_TYPES.has(node.type) ? [node, ...enclosing] : enclosing;
+ for (const [key, child] of Object.entries(node)) {
+ if (!SKIP_KEYS.has(key) && key !== 'type') walk(child, next);
+ }
+ };
+ walk(ast.program, []);
+ return calls;
+}
+
+/** Declarations a function makes in its own scope (params, and declarations not nested in another function). */
+function functionScope(fn) {
+ const params = new Set(fn.params.flatMap((param) => patternParts(param).names));
+ const locals = new Map();
+ const walk = (node) => {
+ if (!node || typeof node !== 'object') return;
+ if (Array.isArray(node)) { node.forEach(walk); return; }
+ if (typeof node.type !== 'string') return;
+ if (node.type === 'VariableDeclarator') {
+ patternParts(node.id).names.forEach((name) => locals.set(name, [...(locals.get(name) ?? []), node]));
+ } else if ((node.type === 'FunctionDeclaration' || node.type === 'ClassDeclaration') && node.id) {
+ locals.set(node.id.name, [...(locals.get(node.id.name) ?? []), node]);
+ }
+ if (FUNCTION_TYPES.has(node.type)) return;
+ for (const [key, child] of Object.entries(node)) {
+ if (!SKIP_KEYS.has(key) && key !== 'type') walk(child);
+ }
+ };
+ walk(fn.body);
+ return { params, locals };
+}
+
+const objectLiteral = (node) => {
+ let value = node?.type === 'VariableDeclarator' ? node.init : node;
+ if (value?.type === 'CallExpression' && value.callee.type === 'MemberExpression'
+ && value.callee.object.name === 'Object' && value.callee.property.name === 'freeze') value = value.arguments[0];
+ return value?.type === 'ObjectExpression' ? value : null;
+};
+
+/**
+ * The parts of a module-scope object literal that `binding.member` can read:
+ * the matching properties plus every spread and computed key. Null when the
+ * binding is not one plain object literal, or no part can supply the member
+ * (it was added at runtime), so the caller follows the whole binding.
+ */
+function memberNodes(nodes, member) {
+ const object = nodes.length === 1 ? objectLiteral(nodes[0]) : null;
+ if (!object) return null;
+ const parts = object.properties.filter((property) => property.type === 'SpreadElement' || property.computed
+ || (property.key.name ?? property.key.value) === member);
+ return parts.length ? parts : null;
+}
+
+/**
+ * `createProcessReachTracer({ repoRoot, reviewedSites })`. Each reviewed site
+ * is a repo-relative `path#binding` that ends the trace. Returns:
+ * - `routeSinks(declaration)`: the sorted sink kinds one scanRouteGraph
+ * `declarations` entry can reach (empty when none);
+ * - `explainRoute(declaration)`: `{ sinks, chain }`, with the shortest path
+ * to a sink as `path#binding` steps, for a failure message;
+ * - `traceSite(site)`: the same for one binding, ignoring its own review, or
+ * null when the binding no longer exists.
+ */
+export function createProcessReachTracer({ repoRoot, reviewedSites = [] }) {
+ const modules = new Map();
+ const moduleFor = (file) => {
+ if (!modules.has(file)) modules.set(file, parseModule(file));
+ return modules.get(file);
+ };
+ const repoPath = (file) => relative(repoRoot, file).split(sep).join('/');
+ const keyLabel = (key) => {
+ const at = key.lastIndexOf('#');
+ return `${repoPath(key.slice(0, at))}#${key.slice(at + 1)}`;
+ };
+ const labelKey = (siteLabel) => {
+ const at = siteLabel.lastIndexOf('#');
+ return `${join(repoRoot, siteLabel.slice(0, at))}#${siteLabel.slice(at + 1)}`;
+ };
+ const reviewedKeys = new Set(reviewedSites.map(labelKey));
+ const referenceCache = new WeakMap();
+
+ // Targets one import specifier names: a relative module's export, or a sink.
+ const importTargets = (fromFile, specifier, imported) => {
+ const sink = sinkForSpecifier(specifier);
+ if (sink) return [{ sink }];
+ if (!specifier.startsWith('.')) return [];
+ const file = resolveLocalModule(fromFile, specifier);
+ if (!file || !/\.[cm]?js$/.test(file)) return [];
+ if (SINK_MODULES.has(repoPath(file))) return [{ sink: SINK_MODULES.get(repoPath(file)) }];
+ return imported === '*' ? [{ file, name: '*' }] : [{ file, name: imported }];
+ };
+
+ // An exported name resolved to the nodes that declare it, through re-exports and stars.
+ // `viaStar` is set while searching `export *` sources, where a module that
+ // lacks the name is simply not the one providing it.
+ const exportTargets = (file, name, seen = new Set(), viaStar = false) => {
+ const key = `${file}#${name}`;
+ if (seen.has(key)) return [];
+ seen.add(key);
+ const module = moduleFor(file);
+ if (name === '*') return [{ file, name: '*' }];
+ const entry = module.exports.get(name);
+ if (entry?.local) return [{ file, name: entry.local }];
+ if (entry?.specifier) {
+ return importTargets(file, entry.specifier, entry.imported)
+ .flatMap((target) => (target.sink || target.name === '*' ? [target] : exportTargets(target.file, target.name, seen)));
+ }
+ const viaStars = module.stars.flatMap((specifier) => importTargets(file, specifier, name)
+ .flatMap((target) => (target.sink ? [target] : exportTargets(target.file, target.name, seen, true))));
+ if (viaStars.length || viaStar) return viaStars;
+ // A name no declaration or star provides (a CommonJS module, a parse the
+ // scan does not understand) is followed through the whole module, never dropped.
+ return [{ file, name: '*' }];
+ };
+
+ // Graph successors of a set of references made in `module`.
+ const successors = (module, references, outer = () => []) => {
+ const next = references.sinks.map((sink) => ({ sink }));
+ for (const name of references.names) {
+ if (module.bindings.has(name)) next.push({ file: module.file, name });
+ else if (module.imports.has(name)) {
+ const { specifier, imported } = module.imports.get(name);
+ next.push(...importTargets(module.file, specifier, imported)
+ .flatMap((target) => (target.sink ? [target] : exportTargets(target.file, target.name))));
+ } else if (!references.declared.has(name)) next.push(...outer(name));
+ if (name === 'WebSocket' && !module.bindings.has(name) && !module.imports.has(name)) next.push({ sink: 'websocket' });
+ }
+ for (const { name, member } of references.memberRefs) {
+ if (module.bindings.has(name)) next.push({ file: module.file, name, member });
+ else if (module.imports.has(name)) {
+ const { specifier, imported } = module.imports.get(name);
+ next.push(...importTargets(module.file, specifier, imported)
+ .flatMap((target) => (target.sink ? [target] : exportTargets(target.file, target.name)))
+ .map((target) => (target.sink || target.name === '*' ? target : { ...target, member })));
+ } else if (!references.declared.has(name)) next.push(...outer(name));
+ }
+ for (const { local, member } of references.namespaceMembers) {
+ const { specifier } = module.imports.get(local);
+ next.push(...importTargets(module.file, specifier, '*')
+ .flatMap((target) => (target.sink ? [target] : exportTargets(target.file, member))));
+ }
+ for (const { specifier, members } of references.imports) {
+ const targets = importTargets(module.file, specifier, '*');
+ for (const target of targets) {
+ if (target.sink) { next.push(target); continue; }
+ next.push({ file: target.file, name: '*load*' });
+ if (members) members.forEach((member) => next.push(...exportTargets(target.file, member)));
+ else next.push(target);
+ }
+ }
+ return next;
+ };
+
+ const nodeReferences = (module, node) => {
+ if (!referenceCache.has(node)) referenceCache.set(node, collectReferences(node, module.namespaces));
+ return referenceCache.get(node);
+ };
+
+ // Successors of a graph node `file#name`; `*` is the whole module, `*load*` its top-level statements.
+ const expand = ({ file, name, member }) => {
+ const module = moduleFor(file);
+ if (member !== undefined) {
+ const properties = memberNodes(module.bindings.get(name) ?? [], member);
+ if (properties) return properties.flatMap((node) => successors(module, nodeReferences(module, node)));
+ return expand({ file, name });
+ }
+ if (name === '*') {
+ return [
+ { file, name: '*load*' },
+ ...[...module.bindings.keys()].map((binding) => ({ file, name: binding })),
+ ...[...module.exports.keys()].flatMap((exported) => exportTargets(file, exported)),
+ ...module.stars.flatMap((specifier) => importTargets(file, specifier, '*')),
+ ];
+ }
+ const nodes = name === '*load*' ? module.sideEffects : (module.bindings.get(name) ?? []);
+ return nodes.flatMap((node) => successors(module, nodeReferences(module, node)));
+ };
+
+ const nodeKey = ({ file, name, member }) => `${file}#${name}${member === undefined ? '' : `.${member}`}`;
+
+ // Breadth-first, so the reported chain is a shortest path to a sink.
+ const search = (start, { skipReviewed = true } = {}) => {
+ const parent = new Map();
+ const queue = [];
+ const sinks = new Set();
+ let first = null;
+ const push = (target, from) => {
+ if (target.sink) {
+ sinks.add(target.sink);
+ first ??= { from, sink: target.sink };
+ return;
+ }
+ if (skipReviewed && reviewedKeys.has(`${target.file}#${target.name}`)) return;
+ const key = nodeKey(target);
+ if (parent.has(key)) return;
+ parent.set(key, from);
+ queue.push(target);
+ };
+ start.forEach((target) => push(target, null));
+ for (let index = 0; index < queue.length; index += 1) {
+ const current = queue[index];
+ expand(current).forEach((target) => push(target, nodeKey(current)));
+ }
+ const chain = [];
+ for (let key = first?.from; key; key = parent.get(key)) chain.unshift(keyLabel(key));
+ return { sinks: [...sinks].sort(), chain: first ? [...chain, first.sink] : [] };
+ };
+
+ // Names a handler takes from enclosing functions: a parameter is an injected
+ // dependency (opaque); a local is followed through its declaration.
+ const enclosingResolver = (module, enclosing) => {
+ const scopes = enclosing.map(functionScope);
+ const resolveName = (name, depth = 0, seen = new Set()) => {
+ if (seen.has(name)) return [];
+ seen.add(name);
+ for (const scope of scopes) {
+ if (scope.params.has(name)) return [{ sink: 'injected-dependency' }];
+ const locals = scope.locals.get(name);
+ if (locals) {
+ return locals.flatMap((node) => {
+ const references = nodeReferences(module, node);
+ return successors(module, references, (inner) => (depth > 20 ? [] : resolveName(inner, depth + 1, seen)));
+ });
+ }
+ }
+ return []; // a global (process, JSON, setTimeout, …)
+ };
+ return resolveName;
+ };
+
+ // Sink kinds each node reaches, memoized over strongly connected components
+ // (iterative Tarjan), so the whole route table costs one walk of the graph.
+ const sinksOf = new Map();
+ const reachedSinks = (root) => {
+ const rootKey = nodeKey(root);
+ if (sinksOf.has(rootKey)) return sinksOf.get(rootKey);
+ const index = new Map();
+ const low = new Map();
+ const local = new Map();
+ const stack = [];
+ const onStack = new Set();
+ let counter = 0;
+ const open = (target) => {
+ const key = nodeKey(target);
+ index.set(key, counter);
+ low.set(key, counter);
+ counter += 1;
+ local.set(key, new Set());
+ stack.push(key);
+ onStack.add(key);
+ return { key, successors: expand(target), next: 0 };
+ };
+ const frames = [open(root)];
+ while (frames.length) {
+ const frame = frames[frames.length - 1];
+ if (frame.next < frame.successors.length) {
+ const target = frame.successors[frame.next];
+ frame.next += 1;
+ if (target.sink) { local.get(frame.key).add(target.sink); continue; }
+ if (reviewedKeys.has(`${target.file}#${target.name}`)) continue;
+ const key = nodeKey(target);
+ if (sinksOf.has(key)) sinksOf.get(key).forEach((sink) => local.get(frame.key).add(sink));
+ else if (!index.has(key)) frames.push(open(target));
+ else if (onStack.has(key)) low.set(frame.key, Math.min(low.get(frame.key), index.get(key)));
+ continue;
+ }
+ frames.pop();
+ const parent = frames[frames.length - 1];
+ if (low.get(frame.key) === index.get(frame.key)) {
+ const members = [];
+ let member;
+ do {
+ member = stack.pop();
+ onStack.delete(member);
+ members.push(member);
+ } while (member !== frame.key);
+ const kinds = new Set(members.flatMap((key) => [...local.get(key)]));
+ members.forEach((key) => sinksOf.set(key, kinds));
+ }
+ if (parent) {
+ low.set(parent.key, Math.min(low.get(parent.key), low.get(frame.key)));
+ // A finished child outside the parent's component is final; one inside
+ // it merges when the component closes.
+ if (sinksOf.has(frame.key)) sinksOf.get(frame.key).forEach((sink) => local.get(parent.key).add(sink));
+ else local.get(frame.key).forEach((sink) => local.get(parent.key).add(sink));
+ }
+ }
+ return sinksOf.get(rootKey);
+ };
+
+ const handlerCalls = new Map();
+ const routeStart = ({ source, routerId, method, path }) => {
+ const module = moduleFor(join(repoRoot, source));
+ if (!handlerCalls.has(module.file)) handlerCalls.set(module.file, routeCalls(module.ast));
+ const calls = handlerCalls.get(module.file).filter((call) => call.routerId === routerId
+ && [method.toLowerCase(), 'all'].includes(call.method) && call.path === path);
+ if (calls.length === 0) throw new Error(`No ${method.toUpperCase()} '${path}' registration on ${routerId} in ${source}`);
+ return calls.flatMap((call) => {
+ const resolveOuter = enclosingResolver(module, call.enclosing);
+ return call.handlers.flatMap((handler) => successors(module, collectReferences(handler, module.namespaces), resolveOuter));
+ });
+ };
+
+ /** Sink kinds one route declaration (a scanRouteGraph `declarations` entry) can reach, sorted. */
+ const routeSinks = (declaration) => {
+ const kinds = new Set();
+ for (const target of routeStart(declaration)) {
+ if (target.sink) kinds.add(target.sink);
+ else if (!reviewedKeys.has(`${target.file}#${target.name}`)) reachedSinks(target).forEach((sink) => kinds.add(sink));
+ }
+ return [...kinds].sort();
+ };
+
+ const explainRoute = (declaration) => search(routeStart(declaration));
+
+ const traceSite = (siteLabel) => {
+ const key = labelKey(siteLabel);
+ const at = key.lastIndexOf('#');
+ const file = key.slice(0, at);
+ const name = key.slice(at + 1);
+ if (!isFile(file) || !moduleFor(file).bindings.has(name)) return null;
+ return search(expand({ file, name }), { skipReviewed: false });
+ };
+
+ return { routeSinks, explainRoute, traceSite };
+}