From 89011e1c0132e162f9ad6cddb023672f157b2bff Mon Sep 17 00:00:00 2001 From: Dextheking1 Date: Sat, 24 Oct 2026 18:15:03 +0200 Subject: [PATCH] fix(studio): scheme-aware origin check, allowedHosts option sameOriginPost compares the Origin against the request's own origin in a scheme-aware way: the scheme comes from the request URL, or from x-forwarded-proto when a TLS proxy supplies it, and x-forwarded-host is honored for tunnels that rewrite Host. An https origin on the same host now passes, where every write behind a TLS proxy 403d before. createStudioApi gains an allowedHosts option naming extra hosts the guard accepts, for hosts mounting the API on their own domain. Default is unchanged: loopback, or the HYPERFRAMES_PREVIEW_HOST bind. desktopRoutes drops its sameOriginPost re-export; its test imports the shared subpath directly. Comments trimmed so the comment ratchet passes. Docs note in docs/packages/studio-server.mdx. Tests: origin guard suite 17/17 (6 new: https same-origin write, forwarded proto, https origin on a plain http request, allowedHosts accept and reject, tunnel with rewritten Host). Full studio-server suite 1360 passed, 1 failed (history file-mode, fails on the base commit too in this environment). CLI server suites 226 passed. Typecheck, oxlint, oxfmt clean. --- docs/packages/studio-server.mdx | 14 +++ packages/cli/src/server/desktopRoutes.test.ts | 3 +- packages/cli/src/server/desktopRoutes.ts | 14 ++- .../src/createStudioApi.originGuard.test.ts | 103 ++++++++++++++++ packages/studio-server/src/createStudioApi.ts | 53 ++++---- .../src/helpers/requestIdentity.ts | 115 ++++++------------ packages/studio-server/src/index.ts | 2 +- 7 files changed, 193 insertions(+), 111 deletions(-) diff --git a/docs/packages/studio-server.mdx b/docs/packages/studio-server.mdx index 640e199f27..fab0f7e21c 100644 --- a/docs/packages/studio-server.mdx +++ b/docs/packages/studio-server.mdx @@ -47,6 +47,20 @@ 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"] }), +); +``` + 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 c583de0aac..831fa1bbba 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 fa06450a84..ad55f92a80 100644 --- a/packages/cli/src/server/desktopRoutes.ts +++ b/packages/cli/src/server/desktopRoutes.ts @@ -7,9 +7,14 @@ import { } from "../utils/desktopApp.js"; import { sameOriginPost } from "@hyperframes/studio-server/request-identity"; -// Re-exported for this module's tests; the definition is shared with -// the studio API's write guard. -export { sameOriginPost }; +/** 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}$/; @@ -40,6 +45,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/studio-server/src/createStudioApi.originGuard.test.ts b/packages/studio-server/src/createStudioApi.originGuard.test.ts index b163a794cf..5601fa4e58 100644 --- a/packages/studio-server/src/createStudioApi.originGuard.test.ts +++ b/packages/studio-server/src/createStudioApi.originGuard.test.ts @@ -144,4 +144,107 @@ describe("createStudioApi cross-origin write guard", () => { }); 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("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); + }); }); diff --git a/packages/studio-server/src/createStudioApi.ts b/packages/studio-server/src/createStudioApi.ts index de7b51e9d3..034d684967 100644 --- a/packages/studio-server/src/createStudioApi.ts +++ b/packages/studio-server/src/createStudioApi.ts @@ -21,7 +21,6 @@ import { replaceWithProjectDirMissing } from "./helpers/projectDirMissing.js"; import { folderGone, isProjectRootMissing } from "./helpers/safePath.js"; import { sameOriginPost } from "./helpers/requestIdentity.js"; -/** Host named by a request URL, or undefined when it does not parse. */ function urlHost(url: string): string | undefined { try { return new URL(url).host || undefined; @@ -30,36 +29,26 @@ function urlHost(url: string): string | undefined { } } -/** - * 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 urlScheme(url: string): string | undefined { + try { + return new URL(url).protocol.replace(/:$/, "") || undefined; + } catch { + return undefined; + } +} + +export interface StudioApiOptions { + /** + * Extra host names the write guard accepts as this server, for hosts + * mounting the API on their own domain or behind a tunnel or proxy. + */ + allowedHosts?: readonly string[]; +} + +export function createStudioApi(adapter: StudioApiAdapter, options: StudioApiOptions = {}): Hono { const api = new Hono(); - // The studio API is unauthenticated and its only legitimate caller is the - // Studio page this same server serves. A state-changing request that did - // not come from that page is a cross-origin request from some other - // website open in the user's browser. CORS does not stop such requests - // from being SENT: POST with a text/plain or form body is "simple" and - // needs no preflight. It only stops the page reading the response, which - // a fire-and-forget file write or render trigger does not need. Reject - // those writes outright. Reads are unaffected: the guard covers state - // changes only. - // - // The predicate is the CLI server's own `sameOriginPost`, shared from - // helpers/requestIdentity so both servers give one answer. Comparing the - // Origin host to the Host header alone is not enough: a page whose own - // DNS name resolves to 127.0.0.1 sends a matching pair and walks through. - // `sameOriginPost` also requires the Host to be an identity this server - // answers to (a loopback literal, or the LAN name it was bound with) and - // refuses any Sec-Fetch-Site other than "same-origin". Callers with no - // Origin header (curl, tests, in-process) still pass on a loopback Host, - // which is the only Host a loopback-bound server can be reached on. When - // the Host header is absent the request never came over the wire - // (in-process callers address the app by URL, and a real server builds - // that URL from the Host header), so the URL's host is the same value. + // 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(); @@ -68,6 +57,10 @@ export function createStudioApi(adapter: StudioApiAdapter): Hono { 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) return c.json({ error: "forbidden" }, 403); return next(); diff --git a/packages/studio-server/src/helpers/requestIdentity.ts b/packages/studio-server/src/helpers/requestIdentity.ts index 664be92137..2bc921b0f6 100644 --- a/packages/studio-server/src/helpers/requestIdentity.ts +++ b/packages/studio-server/src/helpers/requestIdentity.ts @@ -1,54 +1,22 @@ -/** - * The one answer to "is this write same origin", shared by the CLI server - * and the studio API. - * - * Lifted out of the CLI server so both import this one definition: the CLI's - * open-in-desktop route and the studio API's write guard ask the same - * question, and two copies of the check would drift into two different - * answers. The split also keeps the predicate unit-testable without pulling - * in either server's heavier dependencies. - */ +// 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"; -/** - * 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. + // 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); } -/** 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. - */ +// 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 { @@ -58,8 +26,6 @@ function localNames(): Set { 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 !== "") { @@ -73,13 +39,6 @@ function localNames(): Set { 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; @@ -90,28 +49,7 @@ function hostMatchesBind(host: string | undefined, bind: string): boolean { : false; } -/** - * May a request carrying this `Host` be treated as addressed to this server? - * - * 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. - */ +// 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(); @@ -119,19 +57,44 @@ export function identityAllowed(host: string | undefined): boolean { return hostMatchesBind(host, bind); } -/** - * A bodiless POST is a simple request, so any page can send one to localhost: - * it has to come from this Studio. Both write guards apply this one function, - * the CLI server's open-in-desktop route and the studio API's write - * middleware, so the two servers cannot drift into different answers. - */ +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); +} + +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, origin, fetchSite } = headers; - if (!host || !identityAllowed(host)) return false; - if (fetchSite && fetchSite !== "same-origin") return false; - return origin === undefined || origin === `http://${host}`; + 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 a12867c942..8b3aa95f62 100644 --- a/packages/studio-server/src/index.ts +++ b/packages/studio-server/src/index.ts @@ -1,4 +1,4 @@ -export { createStudioApi } from "./createStudioApi.js"; +export { createStudioApi, type StudioApiOptions } from "./createStudioApi.js"; export { MAX_UPLOAD_BYTES } from "./routes/files.js"; export { createProjectSignature,