av-club/docs/SECURITY.md

# Security model

av-club exposes ffmpeg, sharp and exiftool over HTTP. Done naively that is a remote shell. This
document is the set of invariants that make it not one, and the reasoning for each — so that a future
change can be checked against the reasoning rather than against a vibe.

**Read this before adding an endpoint, an option, or a filter.**

## The one invariant, as revised on 2026-09-09

> **The caller may name a path. `sidecar/paths.ts` is the ONLY thing that decides whether it is one
> this service will touch, and every path a caller NAMES is inside `WORK_ROOT`. A symlink the owner
> put inside the root may lead out of it.**

Read the section below for what it replaced and why, because the change is not a relaxation of the
threat model — it is a correction to a rule that had stopped describing what av-club is for.

### What it used to say, and why it changed

> **The caller never supplies a path, a URL, or a protocol. Not for input, not for output, not
> inside a filter argument, not anywhere.**

Every dangerous thing these tools can do is reached through a path or a URL. Remove the caller's
ability to name one and the entire class disappears, which is what makes it safe to expose almost
every *other* option these tools have.

Concretely: input is an **opaque asset id** issued by av-club for a file av-club received. Output is
a path av-club chooses. Both are resolved server-side into paths under a job directory. Anything that
looks like a path in a caller-supplied value is rejected, not sanitised.

That was the right invariant for an upload service. av-club is not one. Both of its real consumers
already have the file on disk — a right-click in the file browser on `~/Movies/thing.mkv`, and a
commander watching a folder for uploads — and obeying the old rule meant copying gigabytes in and
gigabytes back out to convert a file that never moved. A rule that expensive gets worked around, and
the workaround is where the actual hole would have been.

So it is now narrower and says what it was always FOR. Nothing else moved:

- argv arrays, never a shell — unchanged
- `-protocol_whitelist file` — unchanged, and now doing more work than before
- filters allowlisted by name, file-bearing parameters stripped — unchanged
- bounded work, timeouts, concurrency — unchanged

What is gone is only the claim that a path never appears. What replaced it is one module, small enough
to read in a minute, that every path goes through:

- **absolute**, because a relative path resolves against a cwd the caller cannot see
- **no `..` segment**, refused rather than normalised. Normalising is not what the kernel does: for
  `/home/me/Music/..` the string says `/home/me`, while the kernel follows `Music` to another disk
  first and says something else entirely. Refusing removes the divergence rather than picking a side
- **inside the root as written**, 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 checked the same way, and it must already exist — creating
  directories toward an output is a side effect nobody asked for
- errors never distinguish "outside the root" from "does not exist", which would make this an oracle
  for what exists elsewhere on the disk

**Symlinks leave the root, deliberately, changed 2026-09-09.** `realpath` used to run FIRST and the
resolved path had to be inside the root, so a link in the owner's home pointing at another disk was
refused. On a machine whose home is BUILT from such links — `~/Music`, `~/Movies`, `~/Torrents` each
pointing at a mount — that rule left av-club able to see almost nothing. It refused all 212 tracks of
an album the owner had open in the file browser at the time.

The file browser is the component that decides what the owner may touch, and it launches these jobs;
its `resolveUserPath` checks the path as written and never calls `realpath`. Two different rules over
the same files means the platform offers a right-click action its own sidecar cannot perform.

What that strictness was worth is smaller than it looks: this process runs AS the owner, so it reads
nothing the owner cannot already read, and a link out of home reaches only more of the owner's disks.
`realpath`-first was never the privilege boundary — the OS is. The claim that remains true, and is the
one to defend: **a caller cannot NAME a path outside the root; they can only follow a link the owner
put inside it.**

Verified 2026-08-29 against the running service: `..` traversal, an absolute path outside the root, a
write outside the root, and a relative path are all refused; nothing was written outside the root. The
two symlink cases in that list — a link into `/etc`, and a write through a symlinked directory — are
now permitted by design, per the paragraph above.

### What that invariant is defending against

These all work by default, which is why "just pass the flags through" is not an option:

| Attack | How |
|---|---|
| Read any file the process can | `-i /etc/passwd`, then download the "converted" output |
| Read a file the input filter never sees | `-f lavfi -i "movie=/home/user/.ssh/id_ed25519"` |
| Read arbitrary paths via a demuxer | `-f concat -i list.txt` with a caller-controlled list |
| SSRF into the private network | ffmpeg speaks `http:` — cloud metadata endpoints, internal services |
| Write anywhere the process can | the output path is just an argument: `~/.ssh/authorized_keys` |
| Load arbitrary native code | `frei0r`, `ladspa`, `lv2` filters load plugins by name from disk |

Note the second row especially. A guard that only inspected `-i` would pass it, because the read
happens inside the filter graph. **This is why the rule is about values, not about which flag they
arrived in.**

## Layer 1 — no shell, ever

Processes are spawned with an **argv array**, never a command string. There is no shell to quote for,
so shell metacharacters are inert data rather than a parsing problem.

Anything that builds a command by string concatenation is a bug regardless of how well it escapes.

## Layer 2 — the caller names nothing

| | |
|---|---|
| **Input** | An asset id (opaque, server-issued) or a multipart upload. Never a path or URL. |
| **Output** | av-club picks the filename and directory. The caller picks the *format*, not where it lands. |
| **Working dir** | One temp directory per job, removed when the job ends. |

Asset ids are validated against a strict pattern before they are used to build a path, and the
resolved path is checked to still be inside the store afterwards. Two checks, because the first is
about intent and the second is about what actually happened.

## Layer 3 — ffmpeg runs with protocols disabled

```
-protocol_whitelist file    (nothing else — no http, no concat, no subfile, no data)
-f <explicit>               inputs are demuxed as what we probed them to be, not auto-detected
-nostdin                    ffmpeg never waits on stdin
```

`-protocol_whitelist file` alone kills SSRF and the `concat:`/`subfile:` tricks outright. It is not
a mitigation for a path leak — Layer 2 is — it is the second lock.

## Layer 4 — filters are allowlisted by name, and their arguments are checked

ffmpeg's filter graph is a language. Most of it is arithmetic on pixels and samples and is safe.
A small, specific part of it touches the filesystem or loads code.

**Never allowed** — these read files or load native code, by design:

`movie`, `amovie`, `subtitles`, `ass`, `frei0r`, `frei0r_src`, `ladspa`, `lv2`, `sendcmd`,
`asendcmd`, `vidstabtransform`, `libvmaf`, `openclsrc`

**Allowed, but with file-bearing parameters stripped**: `drawtext` is genuinely useful and carries
`textfile=` and `fontfile=`. The filter is permitted; those two parameters are rejected. Text comes
as a literal, fonts come from a fixed server-side set referenced by name.

The list is a **default-deny allowlist**, not a blocklist. A filter nobody has classified is
refused. A blocklist would silently admit whatever the next ffmpeg release adds.

## Layer 5 — bounded work

Unbounded is a denial of service even when it is not a breach.

| Bound | Why |
|---|---|
| Upload size cap | Multipart bodies are buffered; an unbounded one is an OOM |
| Wall-clock timeout per job, process killed on expiry | A crafted file can make an encoder run effectively forever |
| Output dimension cap | `resize(50000, 50000)` is an allocation, not an image |
| `limitInputPixels` on sharp | Decompression bombs: a 1 KB PNG that expands to 40 GB |
| Concurrency cap | ffmpeg will use every core it is given; two callers should not be able to take the box down |
| Job directory removed on completion **and** on failure | Otherwise disk fills with the failures |

## Layer 6 — the untrusted-parser problem, stated honestly

Everything above constrains what a caller may *ask for*. None of it helps with the fact that
**ffmpeg and libvips are large C/C++ codebases parsing hostile binary input**, which is a
memory-safety attack surface with a long CVE history — ImageTragick (CVE-2016-3714) and exiftool's
DjVu RCE (CVE-2021-22204) are the famous ones, and they are not the last.

The honest mitigation is process isolation, and it is a *deployment* property rather than a code one:

- run the service as a dedicated unprivileged user that owns nothing else
- no network egress from the process (with protocols disabled it has no reason to make one)
- read-only filesystem apart from the job directory
- ideally a container or `bubblewrap`/`nsjail` sandbox per job

**Status: not implemented yet.** It is written down here because it is the difference between "a
bug in ffmpeg is a crash" and "a bug in ffmpeg is our whole machine", and because the thing most
likely to happen otherwise is that it is never considered at all.

## exiftool is treated differently

exiftool is a Perl program with a plugin architecture and a history of code execution from
**parsing** — not from its arguments. It is therefore used narrowly:

- **reading only**, with a fixed argument list, never caller-supplied options
- never `-@` (argfile), never `-config`, never a user-supplied `-if` expression
- stripping metadata is done by **sharp's re-encode**, not by exiftool

Sharp drops EXIF by default on re-encode, which is verified on every `scripts/verify.sh` run. That
is a smaller, better-understood surface than asking exiftool to rewrite a file in place.

## Authentication

The service is not public and has no anonymous surface. Every endpoint requires a bearer token
issued out of band. This is deliberately dull — it is an internal service between two things we
operate, not a product.

**Even so, it must not be reachable from the internet.** Auth is the second lock; the first is not
listening on a public interface.

## Reviewing a change against this document

- Does the caller name a path, a URL, or a protocol anywhere in the new surface? → **no**
- Is a new ffmpeg filter classified in the allowlist, with a reason? → **required**
- Is the new option's value constrained by type and range, or is it a free string? → **constrain it**
- Can it produce unbounded work — time, memory, pixels, files? → **bound it**
- Is a command being built as a string? → **it must not be**