From 078e54d0089f57c9513dbcb5d07ea092f7be907b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Miguel=20=C3=81ngel?= Date: Tue, 17 Nov 2026 22:36:38 +0000 Subject: [PATCH] feat(studio-server): let a host count the requests the API refuses with 403 (#8049) * feat(studio-server): let a host count the requests the API refuses with 403 * fix(studio-server): a refusal names the endpoint asked for, not the middleware that refused it * style(studio-server): refusal reports carry their meaning in names, not comments * fix(studio-server): a refusal the API sends through itself again is counted once * fix(studio-server): a request sent through the API again is known before a middleware swaps it --- .../src/createStudioApi.refusals.test.ts | 99 +++++++++++++++++++ packages/studio-server/src/createStudioApi.ts | 44 ++++++++- .../studio-server/src/helpers/fetchAgain.ts | 10 ++ .../src/helpers/opaqueFrameLoads.ts | 3 +- packages/studio-server/src/index.ts | 2 + packages/studio-server/src/routes/files.ts | 3 +- packages/studio-server/src/types.ts | 16 +++ 7 files changed, 172 insertions(+), 5 deletions(-) create mode 100644 packages/studio-server/src/createStudioApi.refusals.test.ts create mode 100644 packages/studio-server/src/helpers/fetchAgain.ts diff --git a/packages/studio-server/src/createStudioApi.refusals.test.ts b/packages/studio-server/src/createStudioApi.refusals.test.ts new file mode 100644 index 0000000000..1288c23f95 --- /dev/null +++ b/packages/studio-server/src/createStudioApi.refusals.test.ts @@ -0,0 +1,99 @@ +// @vitest-environment node +// Node environment: happy-dom's fetch drops the Origin and Sec-Fetch-Site headers these refusals turn on. +import { afterEach, describe, expect, it } from "vitest"; +import { mkdtempSync, rmSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { createStudioApi } from "./createStudioApi"; +import { stubAdapter } from "./routes/stubAdapter.test-helpers"; +import type { StudioRefusal } from "./types"; + +const tempDirs: string[] = []; +afterEach(() => { + for (const dir of tempDirs.splice(0)) rmSync(dir, { recursive: true, force: true }); +}); + +function createApp() { + const projectDir = mkdtempSync(join(tmpdir(), "hf-refusals-")); + tempDirs.push(projectDir); + writeFileSync(join(projectDir, "index.html"), ""); + const heard: StudioRefusal[] = []; + const app = createStudioApi({ ...stubAdapter(projectDir), onRefusal: (r) => heard.push(r) }); + return { app, heard }; +} + +const write = ( + app: ReturnType, + name: string, + headers: Record, +) => + app.request(`http://localhost/projects/demo/files/${name}`, { + method: "POST", + headers: { Host: "localhost", "Content-Type": "text/plain", ...headers }, + body: "planted", + }); + +describe("createStudioApi refusal reports", () => { + it("names a cross-origin write by its route and reason, never the file it named", async () => { + const { app, heard } = createApp(); + const res = await write(app, "planted-secret.html", { Origin: "http://evil.example:9999" }); + expect(res.status).toBe(403); + expect(heard).toHaveLength(1); + expect(heard[0]?.why).toBe("cross_origin_write"); + expect(heard.map((r) => r.route)).toEqual(["/projects/:id/files/*"]); + expect(Object.keys(heard[0] ?? {}).sort()).toEqual(["route", "why"]); + expect(JSON.stringify(heard)).not.toMatch(/planted|evil/); + }); + + it("counts a refusal through a frame-token preview path once, not once per pass through the API", async () => { + const { app, heard } = createApp(); + const minted = await app.request("http://localhost/projects/demo/frame-token", { + headers: { Host: "localhost", "sec-fetch-site": "same-origin" }, + }); + const { token } = (await minted.json()) as { token: string }; + const res = await app.request(`http://localhost/projects/demo/preview/~${token}/index.html`, { + method: "POST", + headers: { Host: "localhost", Origin: "null", "Content-Type": "text/plain" }, + body: "planted", + }); + expect(res.status).toBe(403); + expect(heard).toHaveLength(1); + expect(heard[0]?.why).toBe("cross_origin_write"); + }); + + it("carries the file routes' own why code for a protected path", async () => { + const { app, heard } = createApp(); + const res = await write(app, "node_modules/x.js", { Origin: "http://localhost" }); + expect(res.status).toBe(403); + expect(heard.map((r) => r.why)).toEqual(["protected_path"]); + expect(heard.map((r) => r.route)).toEqual(["/projects/:id/files/*"]); + }); + + it("reports a read another site asked for", async () => { + const { app, heard } = createApp(); + const res = await app.request("http://localhost/projects/demo/lint", { + headers: { Host: "localhost", "Sec-Fetch-Site": "cross-site" }, + }); + expect(res.status).toBe(403); + expect(heard.map((r) => r.why)).toEqual(["another_site"]); + expect(heard.map((r) => r.route)).toEqual(["/projects/:id/lint"]); + }); + + it("hears nothing for an allowed request", async () => { + const { app, heard } = createApp(); + expect((await write(app, "ok.html", { Origin: "http://localhost" })).status).toBe(201); + expect(heard).toEqual([]); + }); + + it("a host counter that throws does not change the answer", async () => { + const projectDir = mkdtempSync(join(tmpdir(), "hf-refusals-")); + tempDirs.push(projectDir); + const app = createStudioApi({ + ...stubAdapter(projectDir), + onRefusal: () => { + throw new Error("counter down"); + }, + }); + expect((await write(app, "x.html", { Origin: "http://evil.example" })).status).toBe(403); + }); +}); diff --git a/packages/studio-server/src/createStudioApi.ts b/packages/studio-server/src/createStudioApi.ts index 4eba59a5c1..fcdb70e1aa 100644 --- a/packages/studio-server/src/createStudioApi.ts +++ b/packages/studio-server/src/createStudioApi.ts @@ -1,7 +1,8 @@ import { Hono, type Context, type Next } from "hono"; +import { routePath } from "hono/route"; import { injectTagsAtHeadStart } from "@hyperframes/core/compiler/html-document"; import { PREVIEW_FOR_ANOTHER_SITE_META } from "@hyperframes/core/studio-preview-mark"; -import type { StudioApiAdapter } from "./types.js"; +import type { StudioApiAdapter, StudioRefusal, StudioRefusalWhy } from "./types.js"; import { registerProjectRoutes } from "./routes/projects.js"; import { registerFileRoutes } from "./routes/files.js"; import { @@ -42,6 +43,7 @@ import { loadedThroughFrameToken, serveTokenPreviewPaths, } from "./helpers/opaqueFrameLoads.js"; +import { isFetchedAgain } from "./helpers/fetchAgain.js"; async function answerRefusedFrameWithPage(c: Context, next: Next) { await next(); @@ -112,7 +114,10 @@ async function refuseProxyWorkForAnotherSite(c: Context, next: Next) { const refuseForAnotherSite = (what: string) => async (c: Context, next: Next) => { if (fromAnotherSite(c)) - return c.json({ error: `forbidden: ${what} requested by another site` }, 403); + return c.json( + { error: `forbidden: ${what} requested by another site`, why: "another_site" }, + 403, + ); return next(); }; @@ -132,6 +137,36 @@ function urlScheme(url: string): string | undefined { } } +const REFUSAL_WHYS: ReadonlySet = new Set([ + "nul", + "outside_project", + "protected_path", + "another_site", + "cross_origin_write", +]); + +const ENDPOINT_ASKED_FOR = -1; + +const reportRefusals = + (onRefusal: (refusal: StudioRefusal) => void) => async (c: Context, next: Next) => { + const fetchedAgain = isFetchedAgain(c.req.raw); + await next(); + if (c.res.status !== 403 || fetchedAgain) return; + const body: unknown = await c.res + .clone() + .json() + .catch(() => null); + const why = body && typeof body === "object" ? (body as { why?: unknown }).why : undefined; + try { + onRefusal({ + route: routePath(c, ENDPOINT_ASKED_FOR), + why: typeof why === "string" && REFUSAL_WHYS.has(why) ? (why as StudioRefusalWhy) : "other", + }); + } catch { + return; + } + }; + export interface StudioApiOptions extends CaptureSandboxOption { allowedHosts?: readonly string[]; subCompositionDeadlineMs?: number; @@ -139,6 +174,7 @@ export interface StudioApiOptions extends CaptureSandboxOption { export function createStudioApi(adapter: StudioApiAdapter, options: StudioApiOptions = {}): Hono { const api = new Hono(); + if (adapter.onRefusal) api.use(reportRefusals(adapter.onRefusal)); api.use(refuseServiceWorkerScripts); const sandboxThumbnailCaptures = options.sandboxThumbnailCaptures ?? false; const frameTokens = createFrameTokens(); @@ -156,7 +192,8 @@ export function createStudioApi(adapter: StudioApiAdapter, options: StudioApiOpt sandboxPreviewForAnotherSiteOrCapture(sandboxThumbnailCaptures), ); api.get("/projects/:id/frame-token", async (c) => { - if (fromAnotherSite(c)) return c.json({ error: "forbidden: requested by another site" }, 403); + if (fromAnotherSite(c)) + return c.json({ error: "forbidden: requested by another site", why: "another_site" }, 403); const projectId = await resolveProjectId(c.req.param("id")); if (!projectId) return c.json({ error: "not found" }, 404); return c.json({ token: frameTokens.tokenFor(projectId) }, 200, { "Cache-Control": "no-store" }); @@ -194,6 +231,7 @@ export function createStudioApi(adapter: StudioApiAdapter, options: StudioApiOpt `forbidden: writes from host "${refusedHost}" are not allowed. ` + `Set ${PREVIEW_ALLOWED_HOSTS_ENV}=${refusedHost} to allow it ` + `(comma separated for several hosts).`, + why: "cross_origin_write", }, 403, ); diff --git a/packages/studio-server/src/helpers/fetchAgain.ts b/packages/studio-server/src/helpers/fetchAgain.ts new file mode 100644 index 0000000000..7666a9b459 --- /dev/null +++ b/packages/studio-server/src/helpers/fetchAgain.ts @@ -0,0 +1,10 @@ +import type { Hono } from "hono"; + +const sentAgain = new WeakSet(); + +export function fetchAgain(api: Hono, request: Request): Response | Promise { + sentAgain.add(request); + return api.fetch(request); +} + +export const isFetchedAgain = (request: Request) => sentAgain.has(request); diff --git a/packages/studio-server/src/helpers/opaqueFrameLoads.ts b/packages/studio-server/src/helpers/opaqueFrameLoads.ts index 1a6b797221..712a3fa388 100644 --- a/packages/studio-server/src/helpers/opaqueFrameLoads.ts +++ b/packages/studio-server/src/helpers/opaqueFrameLoads.ts @@ -1,6 +1,7 @@ import { createHmac, randomBytes, timingSafeEqual } from "node:crypto"; import type { Context, Hono, Next } from "hono"; import { getMimeType } from "./mime.js"; +import { fetchAgain } from "./fetchAgain.js"; import { isProxyWait, PREVIEW_EXPOSED_HEADERS, @@ -112,7 +113,7 @@ export function serveTokenPreviewPaths( return new Response(null, { status: 204, headers: PROXY_PREFLIGHT_ANSWER }); const req = new Request(url, { method: c.req.method, headers: c.req.raw.headers }); frameTokenLoads.add(req); - const res = await api.fetch(req); + const res = await fetchAgain(api, req); return underToken(res, tokenPathHeaders(c, res, url.pathname), projectId, token); }; } diff --git a/packages/studio-server/src/index.ts b/packages/studio-server/src/index.ts index 2dc7f03832..f3d54f643f 100644 --- a/packages/studio-server/src/index.ts +++ b/packages/studio-server/src/index.ts @@ -21,6 +21,8 @@ export { cleanupProxyCache } from "./helpers/proxyCache.js"; export { CACHE_DIR_NAME as PROXY_CACHE_DIR_NAME } from "./helpers/proxyTranscoder.js"; export type { StudioApiAdapter, + StudioRefusal, + StudioRefusalWhy, ResolvedProject, RenderJobState, MediaProcessingJobState, diff --git a/packages/studio-server/src/routes/files.ts b/packages/studio-server/src/routes/files.ts index e3d019c95a..011842acd0 100644 --- a/packages/studio-server/src/routes/files.ts +++ b/packages/studio-server/src/routes/files.ts @@ -123,6 +123,7 @@ import { hasCompositionOutsideTemplates, insertBeforeCloseTag, } from "@hyperframes/core/compiler/html-document"; +import { fetchAgain } from "../helpers/fetchAgain.js"; // ── Server cutover flag ───────────────────────────────────────────────────── @@ -2826,7 +2827,7 @@ function keptForReplay(request: Request): () => Request { async function sendAgainOnceFree(api: Hono, replay: () => Request): Promise { for (const ms of HELD_EDIT_WAITS) { await new Promise((resolve) => setTimeout(resolve, ms)); - const again = await api.fetch(replay()); + const again = await fetchAgain(api, replay()); if (!again.headers.has(HELD)) return again; } return null; diff --git a/packages/studio-server/src/types.ts b/packages/studio-server/src/types.ts index b5c453b7e4..fa5eace90b 100644 --- a/packages/studio-server/src/types.ts +++ b/packages/studio-server/src/types.ts @@ -97,6 +97,19 @@ export interface StudioSelectionResponse { updatedAt: string | null; } +export type StudioRefusalWhy = + | "nul" + | "outside_project" + | "protected_path" + | "another_site" + | "cross_origin_write" + | "other"; + +export interface StudioRefusal { + route: string; + why: StudioRefusalWhy; +} + /** * Adapter interface — injected by each consumer to handle host-specific behavior. * The shared API module calls these methods; each host (vite dev, CLI embedded) @@ -146,6 +159,9 @@ export interface StudioApiAdapter { /** URL to the hyperframe runtime JS (injected into preview HTML). */ runtimeUrl: string; + /** Hears each 403 as the endpoint's route pattern and the server's reason code (`other` if none); never a path. */ + onRefusal?: (refusal: StudioRefusal) => void; + gsapLocalRoot?: `/${string}`; /**