Files
hyperframes/packages/studio-server/src/helpers/proxyCache.ts
T
Michael WangandClaude Opus 5.5 b8bb491900 fix(studio-server): harden preview paths, cache folders and local servers (#7510)
* fix(studio-server): keep cache writes inside the project and canonicalize preview paths

- The tool's own folders (.hyperframes records, backups, preview documents,
  .thumbnails, .transcode-cache) are no longer written, pruned or emptied
  through a link that points outside the project. Thumbnails are still
  served when their cache folder is a link; they are just not cached.
- The hf-id stamp record and the history id are replaced atomically instead
  of written through an existing link.
- Sub-composition previews and thumbnails use the composition's canonical
  project-relative path, and the path is attribute-encoded in the document.
- Thumbnail requests from another site are refused before any capture.
- Saved GSAP scripts escape a `</script` sequence so the script element
  keeps its contents.

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

* fix(core): refuse a UNC or device path on another root before any disk access

isSafePath now rejects a target whose root is a UNC or device root other than
the project's own before it calls realpath or lstat. Projects on a share keep working.

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

* fix(studio): answer WebMCP clients only from Studio's own page

The polyfill now starts with its tab transport limited to Studio's origin and
its frame transport off, so a page that frames Studio cannot list or call its tools.

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

* fix(inspector): check Host on the per-session preview server

The preview page server applies the inspector API's loopback Host rule, so a
rebound DNS name cannot read the bundled composition or project files.

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

* revert(studio-server): keep writing media proxies through a linked .transcode-cache

Refusing the folder made every proxied video in such a project answer 502.
A linked cache folder now receives copies again; it is still never swept,
so nothing already in the folder it points at is removed.

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

* chore(studio-server): drop a comment the comment ratchet refuses

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

* fix(cli): skip HEIF and GIF preview prep when .hyperframes/prepared-assets is a link

The preview transform wrote converted images into .hyperframes/prepared-assets
through a link, so a project shipping .hyperframes as a link to another folder
had files written there. Such a project now gets its preview with the images
as written in the composition, unconverted, and nothing is written.

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

* fix(studio-server): never sweep a linked .transcode-cache, from Studio or hyperframes clean

The link check moves into cleanupProxyCache, which both Studio's cache
maintenance and `hyperframes clean` call, so neither removes files from the
folder a linked .transcode-cache points at.

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

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-10 20:26:12 +00:00

185 lines
6.4 KiB
TypeScript

import { existsSync, readdirSync, statSync, unlinkSync } from "node:fs";
import { dirname, extname, join } from "node:path";
import { PROXY_STILL_EXTENSION, PROXY_VARIANT_CONFIG } from "./mediaCodecMap.js";
import { isLinkFreeWithinProject } from "./safePath.js";
const DEFAULT_MAX_BYTES = 10 * 1024 * 1024 * 1024;
const DEFAULT_STALE_TEMP_MS = 60 * 60 * 1000;
const DEFAULT_MIN_SWEEP_INTERVAL_MS = 5 * 60 * 1000;
const PROXY_EXTENSIONS: ReadonlySet<string> = new Set([
...Object.values(PROXY_VARIANT_CONFIG).map(({ extension }) => extension),
PROXY_STILL_EXTENSION,
]);
const TRANSCODER_PROXY_NAME = /^[0-9a-f]{64}\.\w+$/;
const TRANSCODER_TEMP_NAME = /^\.tmp-[0-9a-f-]{36}-(?:\.part-[0-9a-f]{64}-\d+|[0-9a-f]{64})\.\w+$/;
const TRANSCODER_PIECE_NAME = /^\.part-([0-9a-f]{64})-\d+(\.\w+)$/;
const STALE_PIECE_MS = 60 * 60 * 1000;
export interface ProxyCacheCleanupOptions {
maxBytes?: number;
maxIdleMs?: number;
staleTempMs?: number;
minSweepIntervalMs?: number;
protectedPaths?: ReadonlySet<string>;
now?: number;
dryRun?: boolean;
}
export interface ProxyCacheCleanupResult {
removed: string[];
bytesBefore: number;
bytesAfter: number;
skipped: boolean;
}
interface CacheEntry {
path: string;
size: number;
modifiedAt: number;
protected: boolean;
}
const lastSweepAt = new Map<string, number>();
function positiveEnvNumber(name: string, fallback: number): number {
const parsed = Number(process.env[name]);
return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
}
function proxyCacheCleanupDefaults(): Required<
Pick<ProxyCacheCleanupOptions, "maxBytes" | "maxIdleMs" | "staleTempMs" | "minSweepIntervalMs">
> {
return {
maxBytes: positiveEnvNumber("HYPERFRAMES_PROXY_CACHE_MAX_BYTES", DEFAULT_MAX_BYTES),
maxIdleMs: positiveEnvNumber("HYPERFRAMES_PROXY_CACHE_MAX_IDLE_DAYS", 30) * 24 * 60 * 60 * 1000,
staleTempMs: positiveEnvNumber("HYPERFRAMES_PROXY_CACHE_STALE_TEMP_MS", DEFAULT_STALE_TEMP_MS),
minSweepIntervalMs: positiveEnvNumber(
"HYPERFRAMES_PROXY_CACHE_SWEEP_INTERVAL_MS",
DEFAULT_MIN_SWEEP_INTERVAL_MS,
),
};
}
function shouldSkipSweep(cacheDir: string, now: number, minSweepIntervalMs: number): boolean {
const previousSweep = lastSweepAt.get(cacheDir);
if (previousSweep !== undefined && now - previousSweep < minSweepIntervalMs) return true;
lastSweepAt.set(cacheDir, now);
return false;
}
function isLeftoverName(name: string): boolean {
return TRANSCODER_TEMP_NAME.test(name) || TRANSCODER_PIECE_NAME.test(name);
}
function leftoverIsDead(
cacheDir: string,
name: string,
modifiedAt: number,
protectedPaths: ReadonlySet<string>,
now: number,
staleTempMs: number,
): boolean {
const piece = TRANSCODER_PIECE_NAME.exec(name);
if (!piece) return now - modifiedAt >= staleTempMs;
const copyIsRunning = protectedPaths.has(join(cacheDir, `${piece[1]}${piece[2]}`));
return !copyIsRunning && now - modifiedAt >= STALE_PIECE_MS;
}
function readCacheInventory(
cacheDir: string,
protectedPaths: ReadonlySet<string>,
now: number,
staleTempMs: number,
): { entries: CacheEntry[]; staleTemps: CacheEntry[] } {
const entries: CacheEntry[] = [];
const staleTemps: CacheEntry[] = [];
for (const dirent of readdirSync(cacheDir, { withFileTypes: true })) {
if (!dirent.isFile()) continue;
const path = join(cacheDir, dirent.name);
const stat = statSync(path);
const entry = {
path,
size: stat.size,
modifiedAt: stat.mtimeMs,
protected: protectedPaths.has(path),
};
if (isLeftoverName(dirent.name)) {
if (leftoverIsDead(cacheDir, dirent.name, stat.mtimeMs, protectedPaths, now, staleTempMs)) {
staleTemps.push(entry);
}
} else if (
TRANSCODER_PROXY_NAME.test(dirent.name) &&
PROXY_EXTENSIONS.has(extname(dirent.name))
) {
entries.push(entry);
}
}
const oldestFirst = (a: CacheEntry, b: CacheEntry): number =>
a.modifiedAt - b.modifiedAt || a.path.localeCompare(b.path);
entries.sort(oldestFirst);
staleTemps.sort(oldestFirst);
return { entries, staleTemps };
}
function evictCacheEntries(
entries: CacheEntry[],
staleTemps: CacheEntry[],
now: number,
maxIdleMs: number,
maxBytes: number,
dryRun: boolean,
): Omit<ProxyCacheCleanupResult, "skipped"> {
const bytesBefore = entries.reduce((total, entry) => total + entry.size, 0);
let bytesAfter = bytesBefore;
const removed: string[] = [];
const remove = (entry: CacheEntry, countsTowardBudget: boolean): void => {
if (!dryRun) unlinkSync(entry.path);
removed.push(entry.path);
if (countsTowardBudget) bytesAfter -= entry.size;
};
for (const entry of staleTemps) remove(entry, false);
const kept: CacheEntry[] = [];
for (const entry of entries) {
if (!entry.protected && now - entry.modifiedAt >= maxIdleMs) remove(entry, true);
else kept.push(entry);
}
for (const entry of kept) {
if (bytesAfter <= maxBytes) break;
if (!entry.protected && existsSync(entry.path)) remove(entry, true);
}
return { removed, bytesBefore, bytesAfter };
}
/**
* Opportunistically bounds a project's transparent-proxy cache. Cleanup is
* synchronous because callers already perform filesystem bookkeeping on the
* preview request path, but rate limiting keeps the directory scan off the
* hot path. Errors intentionally bubble so callers can warn without turning
* a cache-maintenance failure into a preview failure.
*/
export function cleanupProxyCache(
cacheDir: string,
options: ProxyCacheCleanupOptions = {},
): ProxyCacheCleanupResult {
const defaults = proxyCacheCleanupDefaults();
const now = options.now ?? Date.now();
const minSweepIntervalMs = options.minSweepIntervalMs ?? defaults.minSweepIntervalMs;
if (shouldSkipSweep(cacheDir, now, minSweepIntervalMs)) {
return { removed: [], bytesBefore: 0, bytesAfter: 0, skipped: true };
}
if (!existsSync(cacheDir) || !isLinkFreeWithinProject(dirname(cacheDir), cacheDir)) {
return { removed: [], bytesBefore: 0, bytesAfter: 0, skipped: false };
}
const maxBytes = options.maxBytes ?? defaults.maxBytes;
const maxIdleMs = options.maxIdleMs ?? defaults.maxIdleMs;
const staleTempMs = options.staleTempMs ?? defaults.staleTempMs;
const protectedPaths = options.protectedPaths ?? new Set<string>();
const { entries, staleTemps } = readCacheInventory(cacheDir, protectedPaths, now, staleTempMs);
return {
...evictCacheEntries(entries, staleTemps, now, maxIdleMs, maxBytes, options.dryRun ?? false),
skipped: false,
};
}