fix(studio-server): refuse cross-origin writes and unknown hosts on the preview server (#7490)

* fix(studio-server): reject cross-origin state-changing requests

Non-GET routes in createStudioApi answer 403 unless the shared
sameOriginPost predicate (lifted into studio-server's ./request-identity
subpath) accepts the request: the Host must be a server identity, a
present Sec-Fetch-Site must be same-origin, and a present Origin must
match the effective host and scheme. Hosts behind Codespaces or tunnels
allow their public name with HYPERFRAMES_PREVIEW_ALLOWED_HOSTS, read by
`hyperframes preview` and the Studio dev server.

Squashed from #6128 (42574a7, 110a300, 89011e1, 41c6626, 27193bb) onto
current main.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(cli): the preview server answers only the hosts it is reached by

Every route of `hyperframes preview` (the forwarded studio API, the SSE
stream, /__hyperframes_config and the Studio page) now answers only
loopback names, the HYPERFRAMES_PREVIEW_HOST bind, or a host listed in
HYPERFRAMES_PREVIEW_ALLOWED_HOSTS, the same list the write guard uses.
Only the Host header counts here, since a page can set X-Forwarded-Host
on its own requests and a read carries no Origin to compare it with.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Dextheking1 <Dextheking1@users.noreply.github.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
James Russo
2026-11-10 10:14:23 +00:00
committed by GitHub
co-authored by Claude Opus 5.5 Dextheking1
parent b4c7f9cf7c
commit f318d3d08a
14 changed files with 721 additions and 143 deletions
@@ -1,7 +1,8 @@
import { Hono } from "hono";
import { describe, expect, it, vi } from "vitest";
import { desktopDownloadUrl, type DesktopOpenResult } from "../utils/desktopApp.js";
import { mountDesktopRoutes, sameOriginPost } from "./desktopRoutes.js";
import { mountDesktopRoutes } from "./desktopRoutes.js";
import { sameOriginPost } from "@hyperframes/studio-server/request-identity";
const STUDIO = {
host: "localhost:3002",
+13 -13
View File
@@ -5,22 +5,19 @@ import {
desktopInstalled,
openInDesktop,
} from "../utils/desktopApp.js";
import { identityAllowed } from "./telemetryIdentity.js";
import { sameOriginPost } from "@hyperframes/studio-server/request-identity";
/** Scheme of a request URL ("http" or "https"), or undefined when it does not parse. */
function urlSchemeOf(url: string): string | undefined {
try {
return new URL(url).protocol.replace(/:$/, "") || undefined;
} catch {
return undefined;
}
}
const CTA_ID = /^[A-Za-z0-9-]{1,64}$/;
/** A bodiless POST is a simple request, so any page can send one to localhost: it has to come from this Studio. */
export function sameOriginPost(headers: {
host?: string;
origin?: string;
fetchSite?: string;
}): boolean {
const { host, origin, fetchSite } = headers;
if (!host || !identityAllowed(host)) return false;
if (fetchSite && fetchSite !== "same-origin") return false;
return origin === undefined || origin === `http://${host}`;
}
/** The desktop-app button's route: show it or not, the download, and whether the app here takes the project. */
export function mountDesktopRoutes(
app: Hono,
@@ -49,6 +46,9 @@ export function mountDesktopRoutes(
host: c.req.header("host"),
origin: c.req.header("origin"),
fetchSite: c.req.header("sec-fetch-site"),
proto: urlSchemeOf(c.req.url),
forwardedProto: c.req.header("x-forwarded-proto"),
forwardedHost: c.req.header("x-forwarded-host"),
});
if (!allowed) return c.json({ error: "forbidden" }, 403);
if (!ready)
@@ -1063,3 +1063,133 @@ describe("Studio file-change SSE", () => {
expect(payload).toContain('"projectId":"demo-project"');
});
});
describe("createStudioServer /api write guard allowed hosts", () => {
const TUNNEL_HOST = "demo.tunnels.example";
async function tunnelWrite(projectDir: string): Promise<Response> {
// A write from the Studio page behind a tunnel, driven through the
// CLI's own /api/* forwarder, the way a browser save reaches the API.
return server!.app.request(
`http://${TUNNEL_HOST}/api/projects/${encodeURIComponent(basename(projectDir))}/files/planted.html`,
{
method: "POST",
headers: {
Host: TUNNEL_HOST,
Origin: `https://${TUNNEL_HOST}`,
"X-Forwarded-Proto": "https",
"Content-Type": "text/plain",
},
body: "<html>planted</html>",
},
);
}
it("refuses a tunnel write without the env var, naming the host and the var", async () => {
const projectDir = tmpProject();
writeFileSync(join(projectDir, "index.html"), "<html>before</html>");
delete process.env.HYPERFRAMES_PREVIEW_ALLOWED_HOSTS;
server = createStudioServer({ projectDir });
const res = await tunnelWrite(projectDir);
expect(res.status).toBe(403);
const body = (await res.json()) as { error: string };
expect(body.error).toContain(TUNNEL_HOST);
expect(body.error).toContain("HYPERFRAMES_PREVIEW_ALLOWED_HOSTS");
expect(existsSync(join(projectDir, "planted.html"))).toBe(false);
});
it("accepts a tunnel write when HYPERFRAMES_PREVIEW_ALLOWED_HOSTS names the host", async () => {
const projectDir = tmpProject();
writeFileSync(join(projectDir, "index.html"), "<html>before</html>");
process.env.HYPERFRAMES_PREVIEW_ALLOWED_HOSTS = `other.example, ${TUNNEL_HOST}`;
try {
server = createStudioServer({ projectDir });
const res = await tunnelWrite(projectDir);
expect(res.status).toBe(201);
expect(existsSync(join(projectDir, "planted.html"))).toBe(true);
} finally {
delete process.env.HYPERFRAMES_PREVIEW_ALLOWED_HOSTS;
}
});
});
describe("createStudioServer Host check on every route", () => {
const FOREIGN_HOST = "rebound.example:3002";
function read(path: string, host: string, extra: Record<string, string> = {}): Promise<Response> {
return Promise.resolve(
server!.app.request(`http://${host}${path}`, { headers: { Host: host, ...extra } }),
);
}
function routes(projectDir: string): string[] {
const id = encodeURIComponent(basename(projectDir));
return [
"/__hyperframes_config",
"/api/projects",
`/api/projects/${id}/files/index.html`,
"/api/events",
"/",
];
}
it("refuses reads on every route for a Host the server does not answer on", async () => {
const projectDir = tmpProject();
writeFileSync(join(projectDir, "index.html"), "<html>secret-body</html>");
delete process.env.HYPERFRAMES_PREVIEW_ALLOWED_HOSTS;
server = createStudioServer({ projectDir });
for (const path of routes(projectDir)) {
const res = await read(path, FOREIGN_HOST);
expect(res.status, path).toBe(403);
const text = await res.text();
expect(text, path).not.toContain("secret-body");
expect(text, path).not.toContain(projectDir);
expect(text, path).toContain("HYPERFRAMES_PREVIEW_ALLOWED_HOSTS");
}
});
it("does not let X-Forwarded-Host stand in for the Host header", async () => {
const projectDir = tmpProject();
writeFileSync(join(projectDir, "index.html"), "<html>secret-body</html>");
server = createStudioServer({ projectDir });
const res = await read("/__hyperframes_config", FOREIGN_HOST, {
"X-Forwarded-Host": "localhost:3002",
});
expect(res.status).toBe(403);
});
it("answers loopback names", async () => {
const projectDir = tmpProject();
writeFileSync(join(projectDir, "index.html"), "<html>secret-body</html>");
server = createStudioServer({ projectDir });
for (const host of ["localhost:3002", "127.0.0.1:3002", "[::1]:3002"]) {
const config = await read("/__hyperframes_config", host);
expect(config.status, host).toBe(200);
const file = await read(
`/api/projects/${encodeURIComponent(basename(projectDir))}/files/index.html`,
host,
);
expect(file.status, host).toBe(200);
expect(await file.text(), host).toContain("secret-body");
}
});
it("answers a host named in HYPERFRAMES_PREVIEW_ALLOWED_HOSTS", async () => {
const projectDir = tmpProject();
writeFileSync(join(projectDir, "index.html"), "<html>secret-body</html>");
process.env.HYPERFRAMES_PREVIEW_ALLOWED_HOSTS = "demo.tunnels.example";
try {
server = createStudioServer({ projectDir });
const res = await read("/__hyperframes_config", "demo.tunnels.example");
expect(res.status).toBe(200);
const other = await read("/__hyperframes_config", FOREIGN_HOST);
expect(other.status).toBe(403);
} finally {
delete process.env.HYPERFRAMES_PREVIEW_ALLOWED_HOSTS;
}
});
});
+23 -1
View File
@@ -36,6 +36,11 @@ import {
import { emitStudioRenderComplete, emitStudioRenderError } from "./studioRenderTelemetry.js";
import { startRenderCpuSampler } from "../telemetry/renderCpu.js";
import { mountDesktopRoutes } from "./desktopRoutes.js";
import {
hostHeaderAllowed,
PREVIEW_ALLOWED_HOSTS_ENV,
previewAllowedHostsFromEnv,
} from "@hyperframes/studio-server/request-identity";
import { isDevMode } from "../utils/env.js";
import { insideHostApp } from "../utils/desktopApp.js";
import { runRenderSetupWorker } from "../utils/cancellableProcess.js";
@@ -903,6 +908,23 @@ export function createStudioServer(options: StudioServerOptions): StudioServer {
// ── Build the Hono app ─────────────────────────────────────────────────
const app = new Hono();
// Extra hosts from HYPERFRAMES_PREVIEW_ALLOWED_HOSTS (Codespaces, tunnels).
const allowedHosts = previewAllowedHostsFromEnv();
// Every route answers only loopback, the bind or an allowed host; a browser cannot forge Host.
app.use(async function refuseUnknownHost(c, next) {
const host = c.req.header("host") ?? new URL(c.req.url).host;
if (hostHeaderAllowed(host, allowedHosts)) return next();
return c.json(
{
error:
`forbidden: host "${host}" is not allowed. ` +
`Set ${PREVIEW_ALLOWED_HOSTS_ENV}=${host} to allow it ` +
`(comma separated for several hosts).`,
},
403,
);
});
// Config probe endpoint — used by port detection to identify existing
// HyperFrames instances and reuse them instead of spawning duplicates.
@@ -1088,7 +1110,7 @@ export function createStudioServer(options: StudioServerOptions): StudioServer {
// Mount the shared studio API at /api.
// Use fetch() forwarding (not .route()) so the sub-app sees paths without
// the /api prefix — the shared module's path extraction uses c.req.path.
const api = createStudioApi(adapter);
const api = createStudioApi(adapter, { allowedHosts });
app.all("/api/*", async (c) => {
const url = new URL(c.req.url);
url.pathname = url.pathname.slice(4); // Strip "/api" prefix
+15 -118
View File
@@ -16,7 +16,7 @@
// server's heavy render dependencies (@hyperframes/producer, engine, …).
// ---------------------------------------------------------------------------
import { hostname, networkInterfaces } from "node:os";
import { identityAllowed, isLoopbackHost } from "@hyperframes/studio-server/request-identity";
import { readConfig, readConfigFresh } from "../telemetry/config.js";
import {
resetTelemetryPostureCache,
@@ -25,6 +25,12 @@ import {
import { canaryDecisionsForStudio, type CliCanaryDecision } from "../telemetry/canary.js";
import { detectAgentRuntime } from "../telemetry/agent_runtime.js";
// The host-identity half of this module moved to
// @hyperframes/studio-server/request-identity, where the studio API's
// write guard shares the same definition. Re-exported so this module's
// existing importers keep one source for it.
export { identityAllowed, isLoopbackHost };
/**
* The CLI's anonymous distinct id to hand to Studio, or null when CLI telemetry
* is disabled or no id is available. Fail-silent — telemetry must never break
@@ -58,33 +64,6 @@ function resolveCliBucketSeed(): string | null {
}
}
/**
* Is this request's `Host` a loopback name the studio server could have been
* reached on directly?
*
* A bare `[::1]`/`localhost`/dotted-quad check rather than a full parse: the
* port is irrelevant (any port on loopback is us), and anything exotic enough
* to miss here should be refused rather than guessed at.
*
* Scope, stated precisely: this is a **DNS-rebinding mitigation for browsers**,
* not access control. A browser sets `Host` from the URL it was given, so a
* page that rebinds its own hostname to 127.0.0.1 arrives carrying that
* hostname and is refused. A non-browser client sets `Host` to whatever it
* likes, so this stops nothing there — but on a loopback-bound server such a
* client is already local, and on a LAN-bound one it can read the project
* files through the unauthenticated studio API anyway. See `identityAllowed`.
*/
export function isLoopbackHost(host: string | undefined): boolean {
if (!host) return false;
// Strip the port. IPv6 literals are bracketed (`[::1]:1234`), so take the
// bracketed part when present and only split on ":" otherwise.
const bracketed = /^\[([^\]]+)\]/.exec(host);
const hostname = (bracketed ? bracketed[1] : host.split(":")[0])?.toLowerCase() ?? "";
if (hostname === "localhost" || hostname === "::1" || hostname === "0:0:0:0:0:0:0:1") return true;
// 127.0.0.0/8 — the whole loopback block, not just 127.0.0.1.
return /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(hostname);
}
// JSON.stringify does not escape "<" or "/". Escaping both means no
// "</script>" (or "</…") sequence can form in the emitted value, so it can
// never terminate the inline <script> or open a new tag. (The values are
@@ -197,96 +176,6 @@ export function buildStudioHeadScripts(
return `${buildCliIdentityScript(options)}${envScript}`;
}
/**
* The `<head>` scripts for a request, given its `Host`.
*
* The Host split lives here rather than in the route so it is testable
* without a Studio bundle on disk — the route's own test can only reach the
* injection branch when `packages/studio/dist` happens to be built, which is
* true locally and false in the CI test lane.
*/
/** Hostname of a `Host` header, port and IPv6 brackets removed. */
function hostnameOf(host: string | undefined): string {
if (!host) return "";
const bracketed = /^\[([^\]]+)\]/.exec(host);
return (bracketed ? bracketed[1] : host.split(":")[0])?.toLowerCase() ?? "";
}
/**
* Names this machine legitimately answers to on a wildcard bind: every
* interface address, plus its own hostname and the `.local` mDNS form people
* actually type. Fail closed — a throw yields an empty set, which denies.
*/
function localNames(): Set<string> {
const names = new Set<string>();
try {
for (const entries of Object.values(networkInterfaces())) {
for (const entry of entries ?? []) names.add(entry.address.toLowerCase());
}
const self = hostname().toLowerCase();
if (self !== "") {
names.add(self);
// `my-box` is reachable as `my-box.local`, and a `my-box.lan.example`
// FQDN is reachable by its short form. Register both directions.
names.add(`${self}.local`);
const short = self.split(".")[0];
if (short !== undefined && short !== "") {
names.add(short);
names.add(`${short}.local`);
}
}
} catch {
/* fail closed */
}
return names;
}
/**
* Wildcard binds answer on every local name; a specific bind on itself only.
*
* This is the part that was missing: the previous rule accepted ANY Host once
* the env var was set, so a rebinding page could name itself `evil.example.com`
* and still be handed the CLI identity.
*/
function hostMatchesBind(host: string | undefined, bind: string): boolean {
const requested = hostnameOf(host);
if (requested === "") return false;
const bound = bind.toLowerCase();
if (requested === bound) return true;
return bound === "0.0.0.0" || bound === "::" || bound === "*"
? localNames().has(requested)
: false;
}
/**
* May this request receive the CLI's identity (distinct id + bucket seed)?
*
* The server binds loopback by DEFAULT and exposes the LAN only when an
* operator sets `HYPERFRAMES_PREVIEW_HOST` (portUtils.ts, F-001). A loopback
* `Host` is always fine: whatever reached us came via loopback, and the only
* interesting attacker is a rebinding browser page — which the Host check
* catches, because a browser cannot forge `Host`.
*
* For anything else the bind decides:
*
* - **Unset, or bound to loopback.** No LAN exposure was requested, so the
* Host check is a live rebinding mitigation and a non-loopback Host is
* refused. Previously ANY non-empty value disabled the check, so even
* `HYPERFRAMES_PREVIEW_HOST=127.0.0.1` — which exposes nothing — turned the
* loopback service from hostile-Host refusal into accept-everything.
* - **Bound to a LAN address.** The operator opted into exposure, so identity
* has to reach the LAN name the user browses or the CLI-to-Studio stitch
* breaks and Studio mints a second person for the same human. But it is
* still checked: the Host must name an address this machine actually
* answers on, not any attacker-chosen name a rebinding page supplies.
*/
export function identityAllowed(host: string | undefined): boolean {
if (isLoopbackHost(host)) return true;
const bind = (process.env["HYPERFRAMES_PREVIEW_HOST"] ?? "").trim();
if (bind === "" || isLoopbackHost(bind)) return false;
return hostMatchesBind(host, bind);
}
/**
* Re-read the persisted telemetry preference for this request.
*
@@ -309,6 +198,14 @@ export function refreshTelemetryPosture(): void {
}
}
/**
* The `<head>` scripts for a request, given its `Host`.
*
* The Host split lives here rather than in the route so it is testable
* without a Studio bundle on disk — the route's own test can only reach the
* injection branch when `packages/studio/dist` happens to be built, which is
* true locally and false in the CI test lane.
*/
export function buildStudioHeadScriptsForHost(envScript: string, host: string | undefined): string {
refreshTelemetryPosture();
return buildStudioHeadScripts(envScript, { includeIdentity: identityAllowed(host) });