Companion boundary and API v1

The companion is local scientific execution, not a remotely hosted inference service. It executes approved Python with the current user's permissions. Virtual environments separate dependencies; they do not sandbox malicious code.

Authorization

Only 127.0.0.1 is bound (default port 8765). Exact Host (127.0.0.1:port or localhost:port) and exact configured Origin are required, including discovery. Defaults allow https://microscope.io and https://www.microscope.io; other development or hosted HTTPS origins require explicit --origin. Wildcard CORS and credential cookies are not used. Requests without Origin or with an attacker-controlled Host fail, resisting DNS rebinding and cross-origin CSRF.

Discovery is read-only. Pairing requires a one-use, random terminal code, expires in ten minutes, and permits at most five attempts/minute. Successful pairing rotates the code; at most eight paired sessions exist. Privileged requests require an origin-bound random bearer, expiring after eight hours. The viewer retains it only in session storage/in-memory, never in workflow JSON, URLs or cloud telemetry. Pairing grants code-execution authority to that browser origin; XSS on a trusted paired viewer is consequently within the threat boundary. Disconnect forgets the browser token; restarting the companion invalidates all tokens.

HTTPS website to loopback

Fetch targets http://127.0.0.1:8765 directly, with explicit CORS and targetAddressSpace: loopback for browsers implementing it. JSON and bearer requests preflight. The companion permits only configured origins/methods and Authorization/Content-Type, and answers supported Private Network Access preflight headers. Loopback is treated as potentially trustworthy by current browsers, but modern Chromium's Local Network Access permission can require user approval. Never proxy execution through OVH to work around browser policy.

The automated secure-origin test uses a local HTTPS site with COOP/COEP and a public HTTPS page, with actual Chromium 141/Firefox 142 HTTP loopback discovery, JSON pairing and authenticated preflights. Chromium’s public-origin request is blocked without permission; the positive test explicitly grants local-network-access, simulating user approval without disabling browser security. Both browsers then pass. This does not prove OS firewall, Safari, corporate policy, macOS permission prompts or every later browser release. A denied permission produces a reconnect/pair explanation; slide viewing remains usable. Enable the site’s local-network permission and reload the viewer if the browser keeps a previous denial. The app cannot override browser or corporate policy. References: Chromium Local Network Access, MDN local network access.