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
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
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.jsxindex 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.jsxindex 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.jsindex 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 errorif (err.code === 'PLATFORM_UNAVAILABLE') {diff --git a/client/src/services/apiCore.test.js b/client/src/services/apiCore.test.jsindex 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.jsindex 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.jsindex 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.jsindex 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.jsindex 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 subsystemsrouter.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.jsindex 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.jsindex 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.jsindex 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.jsnew file mode 100644index 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 };+}