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
This commit is contained in:
Miguel Ángel
2026-11-17 22:36:38 +00:00
committed by GitHub
parent ce3decb6b5
commit 078e54d008
7 changed files with 172 additions and 5 deletions
@@ -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"), "<html></html>");
const heard: StudioRefusal[] = [];
const app = createStudioApi({ ...stubAdapter(projectDir), onRefusal: (r) => heard.push(r) });
return { app, heard };
}
const write = (
app: ReturnType<typeof createStudioApi>,
name: string,
headers: Record<string, string>,
) =>
app.request(`http://localhost/projects/demo/files/${name}`, {
method: "POST",
headers: { Host: "localhost", "Content-Type": "text/plain", ...headers },
body: "<html>planted</html>",
});
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: "<html>planted</html>",
});
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);
});
});
+41 -3
View File
@@ -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<string> = new Set<StudioRefusalWhy>([
"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,
);
@@ -0,0 +1,10 @@
import type { Hono } from "hono";
const sentAgain = new WeakSet<Request>();
export function fetchAgain(api: Hono, request: Request): Response | Promise<Response> {
sentAgain.add(request);
return api.fetch(request);
}
export const isFetchedAgain = (request: Request) => sentAgain.has(request);
@@ -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);
};
}
+2
View File
@@ -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,
+2 -1
View File
@@ -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<Response | null> {
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;
+16
View File
@@ -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}`;
/**