mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-19 00:18:27 +00:00
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.
This commit is contained in:
@@ -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;
|
||||
|
||||
@@ -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",
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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: "<html>planted</html>",
|
||||
});
|
||||
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: "<html>planted</html>",
|
||||
});
|
||||
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: "<html>planted</html>",
|
||||
});
|
||||
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: "<html>planted</html>",
|
||||
});
|
||||
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: "<html>planted</html>",
|
||||
});
|
||||
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: "<html>planted</html>",
|
||||
});
|
||||
expect(res.status).toBe(201);
|
||||
expect(existsSync(join(projectDir, "planted.html"))).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
@@ -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();
|
||||
|
||||
@@ -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<string> {
|
||||
const names = new Set<string>();
|
||||
try {
|
||||
@@ -58,8 +26,6 @@ function localNames(): Set<string> {
|
||||
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<string> {
|
||||
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);
|
||||
}
|
||||
|
||||
@@ -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,
|
||||
|
||||
Reference in New Issue
Block a user