pastilhas
a467000b3d
Two failures on 2026-09-09, one cause each, both found by a 212-track album that would not convert. ── Symlinks ── paths.ts ran realpath FIRST and required the resolved path to be inside WORK_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 leaves av-club able to see almost nothing. It refused every track of a folder the owner had open in the file browser at the time. That is the tell. The file browser decides what the owner may touch and it launches these jobs; its resolveUserPath checks the path as written and never calls realpath. Two confinement rules over the same files means the platform offers a right-click action its own sidecar cannot perform. What the strict rule 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. `..` is now refused rather than normalised, which is what realpath-first actually bought. Normalising is not what the kernel does: for /home/me/Music/.. the string says /home/me while the kernel follows Music to another filesystem first. Refusing removes the divergence instead of picking a side. The narrower claim that remains, 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. ── The token ── requireToken() threw when AV_CLUB_TOKEN was unset. That is right for a service a person starts with a shell and wrong for a sidecar the platform starts: not a safe default, a crash loop nobody sees. It was exactly that — 15 restarts, every proxied request 503, and an error that named the files rather than the missing variable. Generating one loses nothing: authorised() already accepts the platform's X-Officer-User header with no token at all, so no real caller carried this secret. It guards the direct loopback door, and 32 random bytes guard it better than a value copied into a shell profile. Kept 0600 beside the assets so replacing the working tree does not change the service's identity. AV_CLUB_TOKEN still wins when set. There is no unauthenticated mode; this only decides where the token comes from.
av-club
Turning whatever someone uploads into assets a website can actually serve.
People upload photos and videos straight off a phone or a camera: a 12 MB HEIC, a 4K clip in a codec Safari refuses to play, a JPEG carrying the GPS coordinates of the room it was shot in. None of that belongs on a page as-is. This is the thing in between.
It is an HTTP service that exposes as much of sharp, ffmpeg and ffprobe as can be exposed safely, keeping each tool's own vocabulary — sharp operations are named what sharp names them, ffprobe fields come back spelled the way ffprobe spells them. If you know the tool, you know the API.
What it will not let you do is name a file. That single restriction is what makes the rest safe to
open up; see docs/SECURITY.md.
Status
Assets, probing and the full sharp surface work. ffmpeg is designed but not built — that is the next piece.
docs/API.md |
The HTTP surface — start here if you are calling it |
docs/SHARP.md |
Every sharp operation and its bounds. Generated from the validator, so it cannot drift |
docs/SECURITY.md |
The threat model and the invariants. Read before adding an endpoint |
docs/TOOLING.md |
What is installed, and the two things that bite |
docs/PIPELINE.md |
What this is for, and what is still undecided |
Quick start
./scripts/install.sh # system packages + bun deps, then verifies
cp .env.example .env # then set AV_CLUB_TOKEN
bun dev
Verified on Ubuntu 24.04. The installer says so rather than guessing if it finds something else.
# upload something, then resize it
curl -X POST localhost:3020/v1/assets -H "Authorization: Bearer $AV_CLUB_TOKEN" -F file=@photo.jpg
curl -X POST localhost:3020/v1/sharp -H "Authorization: Bearer $AV_CLUB_TOKEN" \
-H 'Content-Type: application/json' -d '{
"input": "as_…",
"pipeline": [{ "rotate": {} }, { "resize": { "width": 1200, "withoutEnlargement": true } }],
"output": { "format": "avif", "options": { "quality": 55 } }
}'
bun run verify checks the tooling; bun run docs regenerates docs/SHARP.md from the validator.
Why this is its own repo
It has system dependencies a web app should not have to assume. ffmpeg, ImageMagick, libvips and
exiftool are a real installation, not an npm install. Keeping them here means a consuming project
can state that it needs this, rather than quietly failing on a machine that happens not to have
ffprobe on its PATH.
It changes on a different clock. Encoder settings, derivative sizes and format choices get revisited as browser support moves. Page templates and database schemas do not.
Nothing about it is specific to one site. Resizing an image and extracting a poster frame are the same problem everywhere, which is why this is not buried inside the project that first needed it.
Its first consumer
fofos/platform — a website with a public site, an admin, and a database. Admins upload media
through the admin; this processes it; the platform stores what comes back.
How that handoff works is not decided yet. The honest options are a library the platform imports,
a CLI it shells out to, or a service it talks to. Each has real consequences for deployment and for
whether processing blocks an admin's upload while they wait. That question is written down in
docs/PIPELINE.md as open, rather than being answered by whatever happens to get built first.
Working agreements
- Commit and push every turn that changes anything — working, broken, or half-finished. The history is the artifact; it is how decisions stay traceable and mistakes stay learnable.
- Docs are live documents, and the code is the source of truth. Docs move with the code in the same commit. A doc contradicting the code is a bug in the doc.
- Direction changes fast, and that is expected. Nothing written here is frozen.