fix: Cloud Run renders reach only public addresses; frame cache folder is private to its user (#7777)

* fix(gcp-cloud-run): render pages cannot reach the service's own dispatch endpoint

The Cloud Run image now sets PRODUCER_RESTRICT_PAGE_NETWORK=true, so a
rendered page reaches only its own project server and public addresses,
not loopback ports or the metadata server. The dispatch endpoint also
refuses any POST that carries an Origin header: browsers send one on every
POST and Cloud Workflows never does.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(engine): the default frame cache folder is private to the user who renders

The default extraction cache sits in the shared temp folder. It is now
created with mode 0700, an existing one owned by the same user is closed
to others (its entries stay, so cache hits carry over), and one that is a
link or belongs to another user is not used: that render runs without the
cache and prints a warning. The animated GIF cache under the same folder
follows the same rule. A folder set with HYPERFRAMES_EXTRACT_CACHE_DIR is
left as it is.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* feat(gcp-cloud-run): a Terraform variable turns the page network restriction off

restrict_page_network (default true) sets PRODUCER_RESTRICT_PAGE_NETWORK on
the service. The package README and docs say what the restriction refuses
and how to turn it off for trusted compositions that need private hosts.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(engine): restore an unset TMPDIR as unset after the cache-root tests

Assigning undefined to process.env stores the string "undefined", so on a
runner with no TMPDIR every later test made its temp folder under ./undefined.

* test(engine): the frame-extractor link test also restores an unset TMPDIR as unset

* chore(engine): raise the packed size budget to 500000

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Michael Wang
2026-11-15 06:34:11 +00:00
committed by GitHub
co-authored by Claude Opus 5.5
parent 8dbbc1d371
commit 55b5147098
15 changed files with 195 additions and 9 deletions
+6
View File
@@ -72,6 +72,12 @@ terraform -chdir=node_modules/@hyperframes/gcp-cloud-run/terraform apply \
Terraform outputs the bucket name, service URL, workflow name, and region needed by the SDK.
### Page network restriction
The service sets `PRODUCER_RESTRICT_PAGE_NETWORK=true`, so a rendered page reaches only its own project files and public internet addresses. Loopback, private, link-local and IPv6 addresses are refused for anything the page loads. An asset on a VPC-only host or behind private DNS is missing from the video. ffmpeg's https inputs may open only https, so an https source that redirects to http, or encrypted HLS, does not load.
Keep it on when you render compositions you did not write. To turn it off, apply the module with `-var restrict_page_network=false`, or set `TF_VAR_restrict_page_network=false` before `hyperframes cloudrun deploy`.
## Using the SDK
```typescript
+5 -1
View File
@@ -300,7 +300,11 @@ export {
} from "./services/videoFrameExtractor.js";
export { qualifyVideoLayer } from "./services/videoLayerPassthrough.js";
export { isSelfOrAncestorHidden } from "./services/mediaHidden.js";
export { directorySizeBytes, gcExtractionCache } from "./services/extractionCache.js";
export {
directorySizeBytes,
gcExtractionCache,
privateCacheRoot,
} from "./services/extractionCache.js";
export {
resolveReferencedStart,
@@ -1,12 +1,14 @@
import { afterEach, beforeEach, describe, expect, it } from "vitest";
import { createHash } from "node:crypto";
import {
chmodSync,
existsSync,
mkdirSync,
mkdtempSync,
readdirSync,
rmSync,
statSync,
symlinkSync,
utimesSync,
writeFileSync,
} from "node:fs";
@@ -24,6 +26,7 @@ import {
lookupCacheEntry,
markCacheEntryComplete,
partialCacheEntryDir,
privateCacheRoot,
publishCacheEntry,
readContentSha256,
readKeyStat,
@@ -31,6 +34,7 @@ import {
touchCacheDir,
type CacheKeyInput,
} from "./extractionCache.js";
import { defaultExtractCacheDir } from "../config.js";
const keyFor = (videoPath: string, overrides: Partial<CacheKeyInput> = {}): CacheKeyInput => {
const stat = readKeyStat(videoPath);
@@ -561,3 +565,53 @@ describe("gcExtractionCache", () => {
expect(existsSync(dependedOnDir)).toBe(true);
});
});
describe.skipIf(process.getuid === undefined)("privateCacheRoot", () => {
const savedTmpdir = process.env.TMPDIR;
let sharedTmp: string;
beforeEach(() => {
sharedTmp = mkdtempSync(join(tmpdir(), "hf-shared-tmp-"));
process.env.TMPDIR = sharedTmp;
});
afterEach(() => {
if (savedTmpdir === undefined) delete process.env.TMPDIR;
else process.env.TMPDIR = savedTmpdir;
rmSync(sharedTmp, { recursive: true, force: true });
});
const uid = () => process.getuid!();
it("creates the default root closed to other users", () => {
const root = defaultExtractCacheDir();
expect(privateCacheRoot(root)).toBe(root);
expect(statSync(root).mode & 0o777).toBe(0o700);
});
it("closes an existing default root of this user and keeps its entries", () => {
const root = defaultExtractCacheDir();
mkdirSync(join(root, "hfcache-entry"), { recursive: true, mode: 0o755 });
chmodSync(root, 0o755);
expect(privateCacheRoot(root)).toBe(root);
expect(statSync(root).mode & 0o777).toBe(0o700);
expect(existsSync(join(root, "hfcache-entry"))).toBe(true);
});
it("refuses a default root owned by another user", () => {
const root = defaultExtractCacheDir();
mkdirSync(root, { mode: 0o777 });
expect(privateCacheRoot(root, uid() + 1)).toBeUndefined();
});
it("refuses a default root that is a link to another directory", () => {
const elsewhere = mkdtempSync(join(sharedTmp, "elsewhere-"));
symlinkSync(elsewhere, defaultExtractCacheDir());
expect(privateCacheRoot(defaultExtractCacheDir())).toBeUndefined();
});
it("leaves a configured root as it is", () => {
const configured = join(sharedTmp, "team-cache");
mkdirSync(configured, { mode: 0o775 });
chmodSync(configured, 0o775);
expect(privateCacheRoot(configured, uid() + 1)).toBe(configured);
expect(statSync(configured).mode & 0o777).toBe(0o775);
});
});
@@ -34,6 +34,7 @@
import { createHash, randomUUID } from "node:crypto";
import {
chmodSync,
createReadStream,
existsSync,
lstatSync,
@@ -46,6 +47,7 @@ import {
} from "node:fs";
import { renameWithRetry } from "@hyperframes/core/rename-retry";
import { join } from "node:path";
import { defaultExtractCacheDir } from "../config.js";
import type { VideoMetadata } from "../utils/ffprobe.js";
import { FRAME_FILENAME_PREFIX, framePathsFromDirectory } from "./extractedFrameIndex.js";
@@ -58,6 +60,19 @@ export const COMPLETE_SENTINEL = ".hf-complete";
/** Marker file stamped after each GC sweep; drives the staleness fallback. */
export const GC_MARKER = ".hf-last-gc";
/**
* `root` when it may hold cache entries, else undefined. The default root sits in the shared temp directory, so it
* is used only as a real directory this user owns, closed to every other user.
*/
export function privateCacheRoot(root: string, uid = process.getuid?.()): string | undefined {
if (uid === undefined || root !== defaultExtractCacheDir()) return root;
mkdirSync(root, { recursive: true, mode: 0o700 });
const stat = lstatSync(root);
if (!stat.isDirectory() || stat.uid !== uid) return undefined;
if ((stat.mode & 0o077) !== 0) chmodSync(root, 0o700);
return root;
}
/**
* Current schema version. Bump it whenever extraction writes different frames for the same key,
* or warm entries keep serving the old frames across a deploy. Each bump's commit says why.
@@ -93,6 +93,7 @@ import {
publishCacheEntry,
readContentSha256,
readKeyStat,
privateCacheRoot,
rehydrateCacheEntry,
touchCacheEntry,
type CacheEntry,
@@ -2468,11 +2469,14 @@ export async function extractAllVideoFrames(
let cacheRootDir: string | undefined;
if (configuredCacheRootDir) {
try {
mkdirSync(configuredCacheRootDir, { recursive: true });
cacheRootDir = configuredCacheRootDir;
cacheRootDir = privateCacheRoot(configuredCacheRootDir);
if (cacheRootDir) mkdirSync(cacheRootDir, { recursive: true });
} catch {
cacheRootDir = undefined;
}
if (!cacheRootDir) {
process.stderr.write(
`[hyperframes:render] WARNING: extraction cache dir ${configuredCacheRootDir} is not writable; caching disabled for this render\n`,
`[hyperframes:render] WARNING: extraction cache dir ${configuredCacheRootDir} is not a writable directory of this user; caching disabled for this render\n`,
);
}
}
@@ -7,6 +7,7 @@ import {
readdirSync,
rmSync,
statSync,
symlinkSync,
utimesSync,
writeFileSync,
} from "node:fs";
@@ -25,6 +26,7 @@ import {
import { extractVideoMetadata } from "../utils/ffprobe.js";
import { runFfmpeg } from "../utils/runFfmpeg.js";
import { COMPLETE_SENTINEL, GC_MARKER, SCHEMA_PREFIX } from "./extractionCache.js";
import { defaultExtractCacheDir } from "../config.js";
// Pass-through, so a test can tell whether extraction ran ffmpeg.
vi.mock("../utils/runFfmpeg.js", async (importOriginal) => {
@@ -631,6 +633,37 @@ describe.skipIf(!HAS_FFMPEG)("extractAllVideoFrames on a VFR source", () => {
}
}, 60_000);
it.skipIf(process.getuid === undefined)(
"disables caching for this render when the default cache dir is a link",
async () => {
const savedTmpdir = process.env.TMPDIR;
const sharedTmp = mkdtempSync(join(tmpdir(), "hf-shared-tmp-"));
process.env.TMPDIR = sharedTmp;
const stderr = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
try {
const elsewhere = mkdtempSync(join(sharedTmp, "elsewhere-"));
symlinkSync(elsewhere, defaultExtractCacheDir());
const SRC = await synthCfrClip("cache-linked-src.mp4", 1);
const result = await extractWithCache(
cfrClipElement("linked", SRC, 1),
"out-cache-linked",
defaultExtractCacheDir(),
);
expect(result.errors).toEqual([]);
expect(result.phaseBreakdown.cacheMisses).toBe(0);
expect(readdirSync(elsewhere)).toEqual([]);
expect(String(stderr.mock.calls[0]?.[0])).toContain("caching disabled for this render");
} finally {
stderr.mockRestore();
if (savedTmpdir === undefined) delete process.env.TMPDIR;
else process.env.TMPDIR = savedTmpdir;
rmSync(sharedTmp, { recursive: true, force: true });
}
},
60_000,
);
it("invalidates the cache when fps changes", async () => {
const CACHE_DIR = mkdtempSync(join(tmpdir(), "hf-extract-cache-test-"));
const SRC = await synthCfrClip("cache-fps-src.mp4", 1);
+3
View File
@@ -211,6 +211,9 @@ RUN bun run --cwd packages/parsers build \
# Cloud Run injects PORT (default 8080). The server reads it.
ENV PORT=8080
# Render pages reach only their own project server and public addresses: not this
# service's port, the metadata server or other loopback and private hosts.
ENV PRODUCER_RESTRICT_PAGE_NETWORK=true
EXPOSE 8080
WORKDIR /app/packages/gcp-cloud-run
+6
View File
@@ -105,6 +105,12 @@ terraform -chdir=node_modules/@hyperframes/gcp-cloud-run/terraform apply \
Terraform outputs `render_bucket_name`, `service_url`, `workflow_name`, and
`region` — pass them straight into the SDK.
### Page network restriction
The service sets `PRODUCER_RESTRICT_PAGE_NETWORK=true`, so a rendered page reaches only its own project files and public internet addresses. Loopback, private, link-local and IPv6 addresses are refused for anything the page loads. An asset on a VPC-only host or behind private DNS is missing from the video. ffmpeg's https inputs may open only https, so an https source that redirects to http, or encrypted HLS, does not load.
Keep it on when you render compositions you did not write. To turn it off, apply the module with `-var restrict_page_network=false`, or set `TF_VAR_restrict_page_network=false` before `hyperframes cloudrun deploy`.
## Using the SDK
```ts
+19
View File
@@ -504,6 +504,25 @@ describe("createApp HTTP mapping", () => {
expect(res.status).toBe(400);
});
it("refuses a browser-sent request before dispatching it", async () => {
let planned = false;
const app = createApp(
depsWith(new FakeGcs(), {
planV2WithPublisher: async () => {
planned = true;
throw new Error("must not run");
},
}),
);
const res = await app.request("/", {
method: "POST",
headers: { "content-type": "text/plain", origin: "http://127.0.0.1:41234" },
body: JSON.stringify(planBody),
});
expect(res.status).toBe(403);
expect(planned).toBe(false);
});
it("healthz returns ok", async () => {
const app = createApp(depsWith(new FakeGcs()));
const res = await app.request("/healthz");
+7
View File
@@ -702,6 +702,13 @@ export function createApp(deps?: HandlerDeps): Hono {
// fallow-ignore-next-line complexity
app.post("/", async (c) => {
const sentByBrowserPage = c.req.header("origin") !== undefined;
if (sentByBrowserPage) {
return c.json(
{ error: "FORBIDDEN", message: "requests from a browser page are refused" },
403,
);
}
let body: CloudRunEvent;
try {
body = (await c.req.json()) as CloudRunEvent;
+6
View File
@@ -105,6 +105,12 @@ resource "google_cloud_run_v2_service" "render" {
value = google_storage_bucket.render.name
}
env {
# Render pages reach only their own project server and public addresses.
name = "PRODUCER_RESTRICT_PAGE_NETWORK"
value = var.restrict_page_network ? "true" : "false"
}
startup_probe {
http_get {
path = "/healthz"
@@ -70,3 +70,19 @@ describe("GCP smoke ownership and protocol safety", () => {
expect(cleanup).toContain("exit 7");
});
});
describe("GCP render image", () => {
it("holds render pages to their project server and public addresses", () => {
expect(dockerfile).toMatch(/^ENV PRODUCER_RESTRICT_PAGE_NETWORK=true$/m);
});
it("lets a deployment turn the restriction off through Terraform, on by default", () => {
const main = readFileSync(join(import.meta.dir, "main.tf"), "utf-8");
const variables = readFileSync(join(import.meta.dir, "variables.tf"), "utf-8");
expect(main).toContain('name = "PRODUCER_RESTRICT_PAGE_NETWORK"');
expect(main).toContain('value = var.restrict_page_network ? "true" : "false"');
expect(variables).toMatch(
/variable "restrict_page_network" \{\s*type\s*= bool[\s\S]*?default\s*= true\s*\}/,
);
});
});
@@ -47,6 +47,12 @@ variable "request_timeout_seconds" {
default = 3600
}
variable "restrict_page_network" {
type = bool
description = "Hold render pages to public addresses: loopback, private, link-local and IPv6 hosts are refused, and ffmpeg https inputs may open only https. Set false only when every composition is trusted and needs VPC-only or private-DNS hosts."
default = true
}
variable "min_instances" {
type = number
description = "Min Cloud Run instances. Default 0 (scale-to-zero) is cheapest but means the first render after idle pays a cold start (image pull + Chrome + bun boot, ~20-30s). Set to 1 to keep one warm if first-render latency matters."
@@ -38,7 +38,7 @@
import { existsSync, writeFileSync } from "node:fs";
import { join, relative } from "node:path";
import { escapesAssetRoot } from "../../../utils/paths.js";
import type { ChromaSubsampling, EngineConfig } from "@hyperframes/engine";
import { privateCacheRoot, type ChromaSubsampling, type EngineConfig } from "@hyperframes/engine";
import { suggestMatchingPreset, type CanvasResolution } from "@hyperframes/core";
import { extractStandaloneEntryFromIndex, isTemplateEntry } from "@hyperframes/core/compiler";
import { readTextFile } from "@hyperframes/parsers/asset-resolution";
@@ -57,6 +57,15 @@ import {
preflightCompositionAssetMediaTypes,
} from "../../assetMediaType.js";
function animatedGifCacheDir(extractCacheDir: string | undefined): string | undefined {
try {
const root = extractCacheDir && privateCacheRoot(extractCacheDir);
return root ? join(root, "animated-gif") : undefined;
} catch {
return undefined;
}
}
export interface CompileStageInput {
projectDir: string;
workDir: string;
@@ -249,9 +258,7 @@ export async function runCompileStage(input: CompileStageInput): Promise<Compile
variables: input.variables,
urlByAbsentLocalPath: input.urlByAbsentLocalPath,
pageMotionBlur: input.pageMotionBlur,
animatedGifCacheDir: cfg.extractCacheDir
? join(cfg.extractCacheDir, "animated-gif")
: undefined,
animatedGifCacheDir: animatedGifCacheDir(cfg.extractCacheDir),
ffmpegProcessTimeout: cfg.ffmpegProcessTimeout,
allowOutsideProjectAssets: job.config.allowOutsideProjectAssets,
});
+1 -1
View File
@@ -12,7 +12,7 @@
"unpacked": 4374000
},
"@hyperframes/engine": {
"packed": 490452,
"packed": 500000,
"unpacked": 1742862
},
"@hyperframes/gcp-cloud-run": {