From f318d3d08a7dff5fb48d12e7604c73bf004af204 Mon Sep 17 00:00:00 2001 From: James Russo Date: Tue, 10 Nov 2026 10:14:23 +0000 Subject: [PATCH] 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 * 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 --------- Co-authored-by: Dextheking1 Co-authored-by: Claude Opus 5.5 --- docs/packages/studio-server.mdx | 23 ++ packages/cli/src/server/desktopRoutes.test.ts | 3 +- packages/cli/src/server/desktopRoutes.ts | 26 +- packages/cli/src/server/studioServer.test.ts | 130 ++++++++ packages/cli/src/server/studioServer.ts | 24 +- packages/cli/src/server/telemetryIdentity.ts | 133 +------- packages/studio-server/package-subpaths.json | 6 + packages/studio-server/package.json | 10 + .../src/createStudioApi.originGuard.test.ts | 296 ++++++++++++++++++ packages/studio-server/src/createStudioApi.ts | 66 +++- .../src/helpers/requestIdentity.ts | 127 ++++++++ packages/studio-server/src/index.ts | 6 +- packages/studio-server/tsup.config.ts | 1 + packages/studio/vite.config.ts | 13 +- 14 files changed, 721 insertions(+), 143 deletions(-) create mode 100644 packages/studio-server/src/createStudioApi.originGuard.test.ts create mode 100644 packages/studio-server/src/helpers/requestIdentity.ts diff --git a/docs/packages/studio-server.mdx b/docs/packages/studio-server.mdx index 5b1dac940b..7ce459389c 100644 --- a/docs/packages/studio-server.mdx +++ b/docs/packages/studio-server.mdx @@ -47,6 +47,29 @@ Studio reads the flag once, when its modules load, so set `window.__HF_STUDIO_ENV__` before loading Studio; the CLI injects it, but a host that mounts the API itself must inject it too. +The API is unauthenticated, so state-changing requests are checked against +the request's own origin, scheme included: a write is accepted only when it +comes from the Studio page this server serves. Loopback works with no setup. +If you mount the API on a public host name (your own domain, a tunnel, a +Codespaces address), name it in `allowedHosts` so writes from that origin +pass: + +```ts +app.route( + "/api", + createStudioApi(adapter, { allowedHosts: ["studio.example.com"] }), +); +``` + +With `hyperframes preview` and the Studio dev server there is no code to +change: both read the extra hosts from `HYPERFRAMES_PREVIEW_ALLOWED_HOSTS` +(comma separated) and pass them as `allowedHosts`. A refused write answers +403 with the refused host named and this variable as the fix: + +```bash +HYPERFRAMES_PREVIEW_ALLOWED_HOSTS=demo.tunnels.example hyperframes preview +``` + A `StudioApiAdapter` supplies: - project listing and resolution; diff --git a/packages/cli/src/server/desktopRoutes.test.ts b/packages/cli/src/server/desktopRoutes.test.ts index 07b8dd9e37..6ef8dc19ed 100644 --- a/packages/cli/src/server/desktopRoutes.test.ts +++ b/packages/cli/src/server/desktopRoutes.test.ts @@ -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", diff --git a/packages/cli/src/server/desktopRoutes.ts b/packages/cli/src/server/desktopRoutes.ts index bd5d12b0dc..812339ee6a 100644 --- a/packages/cli/src/server/desktopRoutes.ts +++ b/packages/cli/src/server/desktopRoutes.ts @@ -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) diff --git a/packages/cli/src/server/studioServer.test.ts b/packages/cli/src/server/studioServer.test.ts index 962eef661d..1c1b400a64 100644 --- a/packages/cli/src/server/studioServer.test.ts +++ b/packages/cli/src/server/studioServer.test.ts @@ -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 { + // 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: "planted", + }, + ); + } + + it("refuses a tunnel write without the env var, naming the host and the var", async () => { + const projectDir = tmpProject(); + writeFileSync(join(projectDir, "index.html"), "before"); + 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"), "before"); + 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 = {}): Promise { + 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"), "secret-body"); + 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"), "secret-body"); + 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"), "secret-body"); + 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"), "secret-body"); + 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; + } + }); +}); diff --git a/packages/cli/src/server/studioServer.ts b/packages/cli/src/server/studioServer.ts index ff4f79ef89..691f48298f 100644 --- a/packages/cli/src/server/studioServer.ts +++ b/packages/cli/src/server/studioServer.ts @@ -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 diff --git a/packages/cli/src/server/telemetryIdentity.ts b/packages/cli/src/server/telemetryIdentity.ts index 0f76bf983b..6ed36658f0 100644 --- a/packages/cli/src/server/telemetryIdentity.ts +++ b/packages/cli/src/server/telemetryIdentity.ts @@ -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 // "" (or " or open a new tag. (The values are @@ -197,96 +176,6 @@ export function buildStudioHeadScripts( return `${buildCliIdentityScript(options)}${envScript}`; } -/** - * The `` 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 { - const names = new Set(); - 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 `` 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) }); diff --git a/packages/studio-server/package-subpaths.json b/packages/studio-server/package-subpaths.json index 7c1bb4e0fd..4dc051c4a4 100644 --- a/packages/studio-server/package-subpaths.json +++ b/packages/studio-server/package-subpaths.json @@ -26,6 +26,12 @@ "types": "./dist/helpers/safePath.d.ts", "environments": ["bun", "node"] }, + "./request-identity": { + "source": "./src/helpers/requestIdentity.ts", + "runtime": "./dist/helpers/requestIdentity.js", + "types": "./dist/helpers/requestIdentity.d.ts", + "environments": ["bun", "node"] + }, "./hf-ids": { "source": "./src/helpers/hfIdPersist.ts", "runtime": "./dist/helpers/hfIdPersist.js", diff --git a/packages/studio-server/package.json b/packages/studio-server/package.json index bced6f1783..4001fcc847 100644 --- a/packages/studio-server/package.json +++ b/packages/studio-server/package.json @@ -33,6 +33,12 @@ "import": "./src/helpers/safePath.ts", "types": "./src/helpers/safePath.ts" }, + "./request-identity": { + "bun": "./src/helpers/requestIdentity.ts", + "node": "./dist/helpers/requestIdentity.js", + "import": "./src/helpers/requestIdentity.ts", + "types": "./src/helpers/requestIdentity.ts" + }, "./hf-ids": { "bun": "./src/helpers/hfIdPersist.ts", "node": "./dist/helpers/hfIdPersist.js", @@ -128,6 +134,10 @@ "import": "./dist/helpers/safePath.js", "types": "./dist/helpers/safePath.d.ts" }, + "./request-identity": { + "import": "./dist/helpers/requestIdentity.js", + "types": "./dist/helpers/requestIdentity.d.ts" + }, "./hf-ids": { "import": "./dist/helpers/hfIdPersist.js", "types": "./dist/helpers/hfIdPersist.d.ts" diff --git a/packages/studio-server/src/createStudioApi.originGuard.test.ts b/packages/studio-server/src/createStudioApi.originGuard.test.ts new file mode 100644 index 0000000000..3658369add --- /dev/null +++ b/packages/studio-server/src/createStudioApi.originGuard.test.ts @@ -0,0 +1,296 @@ +// @vitest-environment node +// Node environment on purpose: the package default (happy-dom) implements +// the browser fetch spec, which drops forbidden request headers such as +// Origin and Sec-Fetch-Site when a Request is constructed. A test that +// simulates cross-origin browser traffic has to set exactly those headers, +// so it needs Node's fetch classes, which keep them. +import { afterEach, describe, expect, it } from "vitest"; +import { existsSync, mkdtempSync, rmSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { createStudioApi } from "./createStudioApi"; +import { previewAllowedHostsFromEnv } from "./helpers/requestIdentity"; +import { stubAdapter } from "./routes/stubAdapter.test-helpers"; + +const tempDirs: string[] = []; + +afterEach(() => { + for (const dir of tempDirs.splice(0)) { + rmSync(dir, { recursive: true, force: true }); + } +}); + +function createApp(): { app: ReturnType; projectDir: string } { + const projectDir = mkdtempSync(join(tmpdir(), "hf-origin-guard-")); + tempDirs.push(projectDir); + return { app: createStudioApi(stubAdapter(projectDir)), projectDir }; +} + +const EVIL_ORIGIN = "http://evil.example:9999"; + +function createFile( + app: ReturnType, + headers: Record, + name = "planted.html", +): Promise { + // A real browser request always carries a Host header; app.request does + // not derive one in this environment, so send it explicitly. That keeps + // every case exercising the Origin comparison itself. + return app.request(`http://localhost/projects/demo/files/${name}`, { + method: "POST", + headers: { Host: "localhost", ...headers }, + body: "planted", + }); +} + +describe("createStudioApi cross-origin write guard", () => { + it("rejects a cross-origin POST file create and writes nothing", async () => { + const { app, projectDir } = createApp(); + const res = await createFile(app, { Origin: EVIL_ORIGIN, "Content-Type": "text/plain" }); + expect(res.status).toBe(403); + expect(existsSync(join(projectDir, "planted.html"))).toBe(false); + }); + + it("rejects a cross-origin multipart upload", async () => { + const { app, projectDir } = createApp(); + const form = new FormData(); + form.append("files", new File(["planted"], "planted.html", { type: "text/html" })); + const res = await app.request("http://localhost/projects/demo/upload", { + method: "POST", + headers: { Host: "localhost", Origin: EVIL_ORIGIN }, + body: form, + }); + expect(res.status).toBe(403); + expect(existsSync(join(projectDir, "planted.html"))).toBe(false); + }); + + it("rejects a write whose Origin is the opaque literal null", async () => { + const { app } = createApp(); + const res = await createFile(app, { Origin: "null", "Content-Type": "text/plain" }); + expect(res.status).toBe(403); + }); + + it("rejects a write marked cross-site by Fetch Metadata even without Origin", async () => { + const { app } = createApp(); + const res = await createFile(app, { "Sec-Fetch-Site": "cross-site" }); + expect(res.status).toBe(403); + }); + + it("rejects a cross-origin PUT overwrite", async () => { + const { app } = createApp(); + const res = await app.request("http://localhost/projects/demo/files/planted.html", { + method: "PUT", + headers: { Host: "localhost", Origin: EVIL_ORIGIN, "If-None-Match": "*" }, + body: "overwritten", + }); + expect(res.status).toBe(403); + }); + + it("rejects a write from a DNS name pointing at loopback, even when Origin and Host match", async () => { + // The attacker's page is served from a name that resolves to 127.0.0.1, + // so its Origin and Host agree with each other and a guard that only + // compares the pair lets it through. The shared predicate also requires + // the Host to be an identity this server answers to, and + // "rebind.example" is not one, whatever it resolves to. + const { app, projectDir } = createApp(); + const res = await createFile(app, { + Host: "rebind.example:9999", + Origin: "http://rebind.example:9999", + "Sec-Fetch-Site": "same-origin", + "Content-Type": "text/plain", + }); + expect(res.status).toBe(403); + expect(existsSync(join(projectDir, "planted.html"))).toBe(false); + }); + + it("rejects a write with no Origin when the Host is a DNS name, not a server identity", async () => { + const { app, projectDir } = createApp(); + const res = await createFile(app, { Host: "rebind.example:9999" }); + expect(res.status).toBe(403); + expect(existsSync(join(projectDir, "planted.html"))).toBe(false); + }); + + it("rejects a same-site write even when Origin and Host match", async () => { + const { app } = createApp(); + const res = await createFile(app, { + Origin: "http://localhost", + "Sec-Fetch-Site": "same-site", + "Content-Type": "text/plain", + }); + expect(res.status).toBe(403); + }); + + it("allows a same-origin write (Origin host matches Host)", async () => { + const { app, projectDir } = createApp(); + const res = await createFile(app, { + Origin: "http://localhost", + "Content-Type": "text/plain", + }); + expect(res.status).toBe(201); + expect(existsSync(join(projectDir, "planted.html"))).toBe(true); + }); + + it("allows a write with no Origin header (non-browser callers)", async () => { + const { app, projectDir } = createApp(); + const res = await createFile(app, { "Content-Type": "text/plain" }); + expect(res.status).toBe(201); + expect(existsSync(join(projectDir, "planted.html"))).toBe(true); + }); + + it("does not block reads from any origin", async () => { + const { app } = createApp(); + await createFile(app, { "Content-Type": "text/plain" }); + const res = await app.request("http://localhost/projects/demo/files/planted.html", { + headers: { Origin: EVIL_ORIGIN }, + }); + expect(res.status).toBe(200); + }); + + it("allows an HTTPS same-origin write", async () => { + const { app, projectDir } = createApp(); + const res = await app.request("https://localhost:3002/projects/demo/files/planted.html", { + method: "POST", + headers: { + Host: "localhost:3002", + Origin: "https://localhost:3002", + "Content-Type": "text/plain", + }, + body: "planted", + }); + expect(res.status).toBe(201); + expect(existsSync(join(projectDir, "planted.html"))).toBe(true); + }); + + it("allows an HTTPS write behind a TLS proxy that forwards the proto", async () => { + const { app, projectDir } = createApp(); + const res = await app.request("http://localhost:3002/projects/demo/files/planted.html", { + method: "POST", + headers: { + Host: "localhost:3002", + Origin: "https://localhost:3002", + "X-Forwarded-Proto": "https", + "Content-Type": "text/plain", + }, + body: "planted", + }); + expect(res.status).toBe(201); + expect(existsSync(join(projectDir, "planted.html"))).toBe(true); + }); + + it("rejects an HTTPS Origin on a request that arrived over plain HTTP", async () => { + const { app, projectDir } = createApp(); + const res = await app.request("http://localhost:3002/projects/demo/files/planted.html", { + method: "POST", + headers: { + Host: "localhost:3002", + Origin: "https://localhost:3002", + "Content-Type": "text/plain", + }, + body: "planted", + }); + expect(res.status).toBe(403); + expect(existsSync(join(projectDir, "planted.html"))).toBe(false); + }); + + it("allows a write on a host named in the allowedHosts option", async () => { + const projectDir = mkdtempSync(join(tmpdir(), "hf-origin-guard-")); + tempDirs.push(projectDir); + const app = createStudioApi(stubAdapter(projectDir), { + allowedHosts: ["studio.example.com"], + }); + const res = await app.request("http://studio.example.com/projects/demo/files/planted.html", { + method: "POST", + headers: { + Host: "studio.example.com", + Origin: "https://studio.example.com", + "X-Forwarded-Proto": "https", + "Content-Type": "text/plain", + }, + body: "planted", + }); + expect(res.status).toBe(201); + expect(existsSync(join(projectDir, "planted.html"))).toBe(true); + }); + + it("rejects a write on that host without the allowedHosts option", async () => { + const { app, projectDir } = createApp(); + const res = await app.request("http://studio.example.com/projects/demo/files/planted.html", { + method: "POST", + headers: { + Host: "studio.example.com", + Origin: "https://studio.example.com", + "X-Forwarded-Proto": "https", + "Content-Type": "text/plain", + }, + body: "planted", + }); + expect(res.status).toBe(403); + expect(existsSync(join(projectDir, "planted.html"))).toBe(false); + }); + + it("names the refused host and the allowing env var in a refused write", async () => { + const { app, projectDir } = createApp(); + const res = await createFile(app, { + Host: "rebind.example:9999", + Origin: "http://rebind.example:9999", + "Sec-Fetch-Site": "same-origin", + "Content-Type": "text/plain", + }); + expect(res.status).toBe(403); + const body = (await res.json()) as { error: string }; + expect(body.error).toContain("rebind.example:9999"); + expect(body.error).toContain("HYPERFRAMES_PREVIEW_ALLOWED_HOSTS"); + expect(existsSync(join(projectDir, "planted.html"))).toBe(false); + }); + + it("rejects a forged X-Forwarded-Host whose Origin does not match it", async () => { + // The Host check alone would pass: the forwarded host names loopback. + // The Origin comparison is what stops it, since the page's real origin + // is the rebinding name, not the forwarded one. + const { app, projectDir } = createApp(); + const res = await createFile(app, { + Host: "rebind.example:9999", + Origin: "http://rebind.example:9999", + "X-Forwarded-Host": "localhost", + "Content-Type": "text/plain", + }); + expect(res.status).toBe(403); + expect(existsSync(join(projectDir, "planted.html"))).toBe(false); + }); + + it("allows a write through a tunnel that rewrites Host and forwards its own", async () => { + const projectDir = mkdtempSync(join(tmpdir(), "hf-origin-guard-")); + tempDirs.push(projectDir); + const app = createStudioApi(stubAdapter(projectDir), { + allowedHosts: ["demo.tunnels.example"], + }); + const res = await app.request("http://localhost/projects/demo/files/planted.html", { + method: "POST", + headers: { + Host: "localhost", + Origin: "https://demo.tunnels.example", + "X-Forwarded-Proto": "https", + "X-Forwarded-Host": "demo.tunnels.example", + "Content-Type": "text/plain", + }, + body: "planted", + }); + expect(res.status).toBe(201); + expect(existsSync(join(projectDir, "planted.html"))).toBe(true); + }); +}); + +describe("previewAllowedHostsFromEnv", () => { + it("parses a comma separated list, trimming blanks", () => { + expect( + previewAllowedHostsFromEnv({ + HYPERFRAMES_PREVIEW_ALLOWED_HOSTS: " demo.tunnels.example ,, studio.example.com ", + }), + ).toEqual(["demo.tunnels.example", "studio.example.com"]); + }); + + it("is empty when the variable is unset or blank", () => { + expect(previewAllowedHostsFromEnv({})).toEqual([]); + expect(previewAllowedHostsFromEnv({ HYPERFRAMES_PREVIEW_ALLOWED_HOSTS: " " })).toEqual([]); + }); +}); diff --git a/packages/studio-server/src/createStudioApi.ts b/packages/studio-server/src/createStudioApi.ts index e81904d5df..4c473bc759 100644 --- a/packages/studio-server/src/createStudioApi.ts +++ b/packages/studio-server/src/createStudioApi.ts @@ -19,6 +19,11 @@ import { registerGlobalAssetRoutes } from "./routes/globalAssets.js"; import { registerHistoryRoutes } from "./routes/history.js"; import { replaceWithProjectDirMissing } from "./helpers/projectDirMissing.js"; import { folderGone, isProjectRootMissing } from "./helpers/safePath.js"; +import { + PREVIEW_ALLOWED_HOSTS_ENV, + requestHost, + sameOriginPost, +} from "./helpers/requestIdentity.js"; import { previewErrorPage } from "./helpers/previewErrorPage.js"; async function answerRefusedFrameWithPage(c: Context, next: Next) { @@ -33,14 +38,61 @@ async function answerRefusedFrameWithPage(c: Context, next: Next) { }); } -/** - * Create a Hono sub-app with all studio API routes. - * - * Both the vite dev server and CLI embedded server mount this app - * under /api, each providing their own adapter for host-specific behavior. - */ -export function createStudioApi(adapter: StudioApiAdapter): Hono { +function urlHost(url: string): string | undefined { + try { + return new URL(url).host || undefined; + } catch { + return undefined; + } +} + +function urlScheme(url: string): string | undefined { + try { + return new URL(url).protocol.replace(/:$/, "") || undefined; + } catch { + return undefined; + } +} + +export interface StudioApiOptions { + allowedHosts?: readonly string[]; +} + +export function createStudioApi(adapter: StudioApiAdapter, options: StudioApiOptions = {}): Hono { const api = new Hono(); + // This API is unauthenticated and simple cross-origin POSTs need no + // preflight, so the guard rejects writes the shared predicate refuses. + api.use(async function rejectCrossOriginWrites(c, next) { + if (c.req.method === "GET" || c.req.method === "HEAD" || c.req.method === "OPTIONS") { + return next(); + } + const allowed = sameOriginPost({ + host: c.req.header("host") ?? urlHost(c.req.url), + origin: c.req.header("origin"), + fetchSite: c.req.header("sec-fetch-site"), + proto: urlScheme(c.req.url), + forwardedProto: c.req.header("x-forwarded-proto"), + forwardedHost: c.req.header("x-forwarded-host"), + allowedHosts: options.allowedHosts, + }); + if (!allowed) { + const refusedHost = + requestHost({ + host: c.req.header("host") ?? urlHost(c.req.url), + forwardedHost: c.req.header("x-forwarded-host"), + }) ?? "unknown host"; + return c.json( + { + error: + `forbidden: writes from host "${refusedHost}" are not allowed. ` + + `Set ${PREVIEW_ALLOWED_HOSTS_ENV}=${refusedHost} to allow it ` + + `(comma separated for several hosts).`, + }, + 403, + ); + } + return next(); + }); api.use("/projects/:id/preview/*", answerRefusedFrameWithPage); api.use("/projects/:id/preview", answerRefusedFrameWithPage); api.use(async function answerProjectDirMissingAfterErrorHandlers(c, next) { diff --git a/packages/studio-server/src/helpers/requestIdentity.ts b/packages/studio-server/src/helpers/requestIdentity.ts new file mode 100644 index 0000000000..7de237146f --- /dev/null +++ b/packages/studio-server/src/helpers/requestIdentity.ts @@ -0,0 +1,127 @@ +// The one answer to "is this write same origin" for the CLI server and the studio API. The Host checks here are a DNS-rebinding mitigation for browsers, not access control: a browser cannot forge Host, a local client can set it freely. +import { hostname, networkInterfaces } from "node:os"; + +export function isLoopbackHost(host: string | undefined): boolean { + if (!host) return false; + 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; + return /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(hostname); +} + +function hostnameOf(host: string | undefined): string { + if (!host) return ""; + const bracketed = /^\[([^\]]+)\]/.exec(host); + return (bracketed ? bracketed[1] : host.split(":")[0])?.toLowerCase() ?? ""; +} + +// Names this machine answers to on a wildcard bind: interface addresses, its own hostname, the .local mDNS form, and short forms of each. +function localNames(): Set { + const names = new Set(); + 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); + 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; +} + +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; +} + +// Extra hosts (Codespaces, tunnels) the preview server and studio API accept, comma separated. +export const PREVIEW_ALLOWED_HOSTS_ENV = "HYPERFRAMES_PREVIEW_ALLOWED_HOSTS"; + +export function previewAllowedHostsFromEnv( + env: { [key: string]: string | undefined } = process.env, +): string[] { + return (env[PREVIEW_ALLOWED_HOSTS_ENV] ?? "") + .split(",") + .map((host) => host.trim()) + .filter((host) => host !== ""); +} + +// The first forwarded host wins: it is the name the browser used. +export function requestHost(headers: { + host?: string; + forwardedHost?: string; +}): string | undefined { + return firstForwarded(headers.forwardedHost) ?? headers.host; +} + +// A loopback Host always passes. Any other Host passes only when the bind (HYPERFRAMES_PREVIEW_HOST) names it, or is a wildcard and the Host is a local name. +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); +} + +function hostAllowed(host: string, allowedHosts: readonly string[] | undefined): boolean { + if (identityAllowed(host)) return true; + if (!allowedHosts) return false; + const name = hostnameOf(host); + return name !== "" && allowedHosts.some((allowed) => hostnameOf(allowed) === name); +} + +// Reads included. Only Host counts: a page can set X-Forwarded-Host, and a read has no Origin to check. +export function hostHeaderAllowed( + host: string | undefined, + allowedHosts?: readonly string[], +): boolean { + return host !== undefined && host !== "" && hostAllowed(host, allowedHosts); +} + +function firstForwarded(value: string | undefined): string | undefined { + const first = value?.split(",")[0]?.trim(); + return first === "" ? undefined : first; +} + +function originMatches(origin: string, host: string, proto: string | undefined): boolean { + let parsed: URL; + try { + parsed = new URL(origin); + } catch { + return false; + } + if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return false; + if (proto !== undefined && parsed.protocol !== `${proto}:`) return false; + return parsed.host.toLowerCase() === host.toLowerCase(); +} + +// proto is the scheme on the request URL the caller saw. The forwarded pair wins when a proxy supplies it: that is the origin the browser actually used. With no scheme known, an http or https origin passes. +export function sameOriginPost(headers: { + host?: string; + origin?: string; + fetchSite?: string; + proto?: string; + forwardedProto?: string; + forwardedHost?: string; + allowedHosts?: readonly string[]; +}): boolean { + const host = firstForwarded(headers.forwardedHost) ?? headers.host; + if (!host || !hostAllowed(host, headers.allowedHosts)) return false; + if (headers.fetchSite && headers.fetchSite !== "same-origin") return false; + if (headers.origin === undefined) return true; + const proto = firstForwarded(headers.forwardedProto) ?? headers.proto; + return originMatches(headers.origin, host, proto); +} diff --git a/packages/studio-server/src/index.ts b/packages/studio-server/src/index.ts index 0c309af4b8..1c8b218509 100644 --- a/packages/studio-server/src/index.ts +++ b/packages/studio-server/src/index.ts @@ -1,4 +1,8 @@ -export { createStudioApi } from "./createStudioApi.js"; +export { createStudioApi, type StudioApiOptions } from "./createStudioApi.js"; +export { + PREVIEW_ALLOWED_HOSTS_ENV, + previewAllowedHostsFromEnv, +} from "./helpers/requestIdentity.js"; export { MAX_UPLOAD_BYTES } from "./routes/files.js"; export { createProjectSignature, diff --git a/packages/studio-server/tsup.config.ts b/packages/studio-server/tsup.config.ts index 07b9f53047..6e94837b53 100644 --- a/packages/studio-server/tsup.config.ts +++ b/packages/studio-server/tsup.config.ts @@ -14,6 +14,7 @@ export default defineConfig({ "helpers/finiteMutation": "src/helpers/finiteMutation.ts", "helpers/sourceMutation": "src/helpers/sourceMutation.ts", "helpers/safePath": "src/helpers/safePath.ts", + "helpers/requestIdentity": "src/helpers/requestIdentity.ts", "helpers/hfIdPersist": "src/helpers/hfIdPersist.ts", "helpers/encoderOptions": "src/helpers/encoderOptions.ts", "helpers/mediaRange": "src/helpers/mediaRange.ts", diff --git a/packages/studio/vite.config.ts b/packages/studio/vite.config.ts index 00af9240d5..f53dd2bc4d 100644 --- a/packages/studio/vite.config.ts +++ b/packages/studio/vite.config.ts @@ -143,9 +143,13 @@ function devProjectApi(): Plugin { let _api: { fetch: (req: Request) => Promise } | null = null; let _studioServerModule: { - createStudioApi: (adapter: ReturnType) => { + createStudioApi: ( + adapter: ReturnType, + options?: { allowedHosts?: readonly string[] }, + ) => { fetch: (req: Request) => Promise; }; + previewAllowedHostsFromEnv: () => string[]; identifyFileWrite: ( path: string, expectedVersion: string, @@ -170,6 +174,7 @@ function devProjectApi(): Plugin { "fileContentVersion", "affectsPreview", "openProjectHistory", + "previewAllowedHostsFromEnv", ] as const) { if (typeof mod[name] !== "function") { throw new Error(`@hyperframes/studio-server dev module is missing ${name}()`); @@ -183,7 +188,11 @@ function devProjectApi(): Plugin { // id and real root before the signature cache starts watching them. onResolveProject: (project) => watchedProjects.set(project.dir, project.id), }); - _api = mod.createStudioApi(adapter); + // Same env var as the CLI preview server: extra hosts whose + // writes the API accepts (Codespaces, tunnels). + _api = mod.createStudioApi(adapter, { + allowedHosts: mod.previewAllowedHostsFromEnv(), + }); } return _api; };