pastilhasandClaude Opus 5
bd8b7b9ad4
adds a path mode to /v1/ffmpeg:
{ input: "as_…" } → stored as a new asset, 201
{ inputPath: "/…", outputPath: "/…" } → written where you said, 200 { path, bytes }
THIS REVISES THE INVARIANT IN docs/SECURITY.md, deliberately, and that document now
says so at the top rather than being quietly contradicted by the code.
it used to read "the caller never supplies a path, for input or output". that was
right for an upload service and av-club is not one: both of its real consumers —
a right-click on ~/Movies/thing.mkv, and a commander watching an upload folder —
already have the file, and obeying the rule meant copying gigabytes in and back out
to convert something that never moved. a rule that expensive gets worked around,
and the workaround is where the hole would have been.
so it is narrower now and says what it was always for. argv never a shell,
-protocol_whitelist file, filters allowlisted, work bounded — all unchanged. what
is gone is only the claim that a path never appears, replaced by one small module
every path goes through:
absolute (a relative path resolves against a cwd the caller cannot see)
realpath FIRST, then check — checking the path as written and opening the
resolved one is the classic way this fails
inside as `root` or `root + sep`, never a bare startsWith, which accepts
/home/user-backup for a root of /home/user
for an output the PARENT is resolved, and must already exist
errors never say which of "outside" or "missing" it was, or this becomes an
oracle for what exists elsewhere on the disk
VERIFIED against the running service, not reasoned about: `..` traversal, an
absolute path outside the root, a write outside the root, a relative path, a
symlink pointing into /etc, and a write THROUGH a symlinked directory — all
refused, nothing written outside the root.
the output is moved into place at the END. ffmpeg encodes into a temp dir, so a job
killed by the timeout or a restart leaves the caller's directory as it was. pointing
ffmpeg at the destination would leave a truncated file where a good one might have
been — and a task that then deleted its source would have destroyed something.
rename first, copy on EXDEV, which is the normal case rather than the error one
since tmp is often tmpfs.
docs/API.md said this endpoint was "designed, not yet built" while it was routed and
working. that is fixed too: it was read as a gap and nearly rebuilt.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
103 lines
4.6 KiB
TypeScript
103 lines
4.6 KiB
TypeScript
import { resolve } from "node:path";
|
||
|
||
/**
|
||
* Configuration, read once at boot.
|
||
*
|
||
* Every limit here exists because its absence is a denial of service — see docs/SECURITY.md,
|
||
* "Layer 5 — bounded work". They are configurable so a deployment can tighten them, not so a
|
||
* deployment can remove them: each has a floor enforced below.
|
||
*/
|
||
|
||
function num(key: string, fallback: number, min: number): number {
|
||
const raw = process.env[key];
|
||
if (raw === undefined) return fallback;
|
||
|
||
const value = Number(raw);
|
||
if (!Number.isFinite(value)) {
|
||
throw new Error(`${key} must be a number, got ${JSON.stringify(raw)}`);
|
||
}
|
||
if (value < min) {
|
||
throw new Error(`${key} must be at least ${min}, got ${value}`);
|
||
}
|
||
return value;
|
||
}
|
||
|
||
/**
|
||
* The port to listen on. **0 means "any free one", and that is the default.**
|
||
*
|
||
* A plugin sidecar does not choose a number. It binds whatever is free and REPORTS it to the platform,
|
||
* which is how every other sidecar here works and why none of them can collide. av-club asserted 3020
|
||
* because it began life as a standalone service, and on 2026-08-28 that assumption cost a deploy: a
|
||
* stale copy of the pre-plugin code was still holding 3020 on fofos, so the plugin's sidecar died on
|
||
* EADDRINUSE in a restart loop.
|
||
*
|
||
* `AV_CLUB_PORT` still works and still pins the port. That is for running this outside Officer — the
|
||
* standalone mode fofos/platform was written against — where something on the other side has to know
|
||
* where to find it. Inside Officer nothing should set it.
|
||
*/
|
||
export const PORT = num("AV_CLUB_PORT", 0, 0);
|
||
|
||
/**
|
||
* Where assets live. Outside the repo by default, and deliberately not under any directory a deploy
|
||
* would replace — losing every stored asset because the working tree was refreshed is the kind of
|
||
* failure that is only noticed later, by which point the originals are gone.
|
||
*/
|
||
export const ASSETS_DIR = resolve(process.env.AV_CLUB_ASSETS_DIR ?? `${process.env.HOME}/.local/share/av-club/assets`);
|
||
|
||
/** Multipart bodies are buffered whole. Without a cap, one request is an out-of-memory. */
|
||
/**
|
||
* The only part of the filesystem this service will read from or write to when a caller names a path.
|
||
*
|
||
* Defaults to the owner's home, which is where every consumer's files already are — the file browser
|
||
* runs there, and so does the commander watching an upload folder. Narrow it with the env var on a
|
||
* machine where av-club should only see one project.
|
||
*
|
||
* `/` is refused outright rather than treated as "no limit": a root that permits everything is a
|
||
* configuration mistake that would look like it was working.
|
||
*/
|
||
export const WORK_ROOT = (() => {
|
||
const root = resolve(process.env.AV_CLUB_WORK_ROOT ?? process.env.HOME ?? "");
|
||
if (!root || root === "/") {
|
||
throw new Error("AV_CLUB_WORK_ROOT (or HOME) must be a real directory, and may not be /");
|
||
}
|
||
return root;
|
||
})();
|
||
|
||
export const MAX_UPLOAD_BYTES = num("AV_CLUB_MAX_UPLOAD_BYTES", 512 * 1024 * 1024, 1024);
|
||
|
||
/** A crafted file can make an encoder run effectively forever. The process is killed at this point. */
|
||
export const JOB_TIMEOUT_MS = num("AV_CLUB_JOB_TIMEOUT_MS", 120_000, 1_000);
|
||
|
||
/**
|
||
* Decompression bombs: a 1 KB PNG can expand to tens of gigabytes. This is sharp's own
|
||
* `limitInputPixels`, defaulted to its documented default (0x3FFF × 0x3FFF) rather than to `false`.
|
||
*/
|
||
export const MAX_INPUT_PIXELS = num("AV_CLUB_MAX_INPUT_PIXELS", 0x3fff * 0x3fff, 1);
|
||
|
||
/** `resize(50000, 50000)` is an allocation request, not an image. */
|
||
export const MAX_OUTPUT_DIMENSION = num("AV_CLUB_MAX_OUTPUT_DIMENSION", 16_383, 1);
|
||
|
||
/** ffmpeg will take every core it is given. Two callers should not be able to take the box down. */
|
||
export const MAX_CONCURRENT_JOBS = num("AV_CLUB_MAX_CONCURRENT_JOBS", 2, 1);
|
||
|
||
/**
|
||
* The bearer token every request must carry.
|
||
*
|
||
* A FUNCTION, not a constant evaluated at import. The limits above are plain data that anything may
|
||
* read — the doc generator imports the sharp vocabulary, which imports MAX_OUTPUT_DIMENSION from
|
||
* here — and a module-scope throw meant that generating documentation required a production secret.
|
||
*
|
||
* The check itself still happens at boot: server.ts calls this before it listens, so a missing token
|
||
* is a refusal to start rather than a service that quietly accepts everyone. There is no
|
||
* "unauthenticated by default" mode; this process runs decoders over untrusted bytes.
|
||
*/
|
||
export function requireToken(): string {
|
||
const value = process.env.AV_CLUB_TOKEN;
|
||
if (!value || value.length < 16) {
|
||
throw new Error(
|
||
"AV_CLUB_TOKEN must be set and at least 16 characters. Generate one with: openssl rand -hex 32",
|
||
);
|
||
}
|
||
return value;
|
||
}
|