@velora-cms/server 0.11.0 → 0.12.0

package/dist/media/storage/s3.js

@@ -0,0 +1,134 @@
+import { CreateBucketCommand, DeleteObjectCommand, GetObjectCommand, HeadBucketCommand, HeadObjectCommand, PutObjectCommand, S3Client, } from "@aws-sdk/client-s3";
+import { assertValidStorageKey, MediaNotFoundError } from "./types.js";
+// Defaults match the minio service in docker-compose.yml (same treatment
+// as POSTGRES_TEST_URL), so local dev works with zero required config
+// once resolveMediaStorage (media-service.ts) has already decided s3 is
+// the active driver. Point these at real S3/R2 via .env — see
+// .env.example. These defaults are NOT consulted for driver selection
+// itself — see resolveMediaStorage's doc comment for why that used to be
+// the landmine.
+export function s3ConfigFromEnv(env = process.env) {
+    // Empty string is treated as unset (LOW-8), same convention
+    // resolveMediaStorage's hasAnyS3Var uses — an empty S3_ENDPOINT in a
+    // stray .env line is "nothing configured," not "configured to nothing."
+    const rawEndpoint = env.S3_ENDPOINT;
+    const endpointWasDefaulted = !rawEndpoint;
+    return {
+        endpoint: rawEndpoint || "http://localhost:9000",
+        region: env.S3_REGION || "us-east-1",
+        accessKeyId: env.S3_ACCESS_KEY_ID || "velora",
+        secretAccessKey: env.S3_SECRET_ACCESS_KEY || "velora-secret",
+        bucket: env.S3_BUCKET || "velora-media",
+        endpointWasDefaulted,
+    };
+}
+// Today's S3 wiring (previously inline in media-service.ts), unchanged
+// apart from implementing MediaStorage instead of being called directly.
+export class S3Storage {
+    config;
+    kind = "s3";
+    client;
+    constructor(config) {
+        this.config = config;
+        this.client = new S3Client({
+            endpoint: config.endpoint,
+            region: config.region,
+            credentials: {
+                accessKeyId: config.accessKeyId,
+                secretAccessKey: config.secretAccessKey,
+            },
+            // MinIO and R2 route by path, not by bucket subdomain — and a
+            // localhost endpoint can't do virtual-hosted buckets at all.
+            forcePathStyle: true,
+        });
+    }
+    // Idempotent; safe to call on startup or from tests. Only creates the
+    // bucket when it doesn't exist yet. Must fail LOUDLY and legibly (not
+    // a raw SDK error) when S3 is unreachable — this is the boot check
+    // that used to silently point a stranger's first deploy at a dev-only
+    // MinIO default (S186c §1).
+    async ensureReady() {
+        try {
+            await this.client.send(new HeadBucketCommand({ Bucket: this.config.bucket }));
+            return;
+        }
+        catch {
+            // HeadBucket fails the same way whether the bucket is merely
+            // missing or the endpoint is unreachable — fall through and let
+            // CreateBucketCommand distinguish them: it succeeds if the server
+            // answered but had no bucket yet, and fails the same way HeadBucket
+            // did if nothing is listening at all.
+        }
+        try {
+            await this.client.send(new CreateBucketCommand({ Bucket: this.config.bucket }));
+        }
+        catch (error) {
+            // LOW-9: name the underlying SDK error (its `name`, e.g.
+            // "UnknownEndpoint"/"TimeoutError"/"AccessDenied") rather than just
+            // its message — the name is often the faster diagnostic signal —
+            // and, when S3_ENDPOINT itself was never set, say so explicitly so
+            // a stranger's first deploy doesn't mistake the MinIO dev default
+            // for something they configured.
+            const errorName = error instanceof Error ? error.name : undefined;
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            const defaultedNote = this.config.endpointWasDefaulted
+                ? " (S3_ENDPOINT is unset — defaulted to http://localhost:9000)"
+                : "";
+            throw new Error(`Could not reach S3 media storage at ${this.config.endpoint}${defaultedNote} ` +
+                `(bucket "${this.config.bucket}"): ${errorName ? `${errorName}: ` : ""}${errorMessage}. ` +
+                `Check S3_ENDPOINT and the other S3_* env vars, or set MEDIA_STORAGE=local to use local disk ` +
+                `storage instead.`, { cause: error });
+        }
+    }
+    async put(key, data, mimeType) {
+        assertValidStorageKey(key);
+        await this.client.send(new PutObjectCommand({
+            Bucket: this.config.bucket,
+            Key: key,
+            Body: data,
+            ContentType: mimeType,
+            ContentLength: data.length,
+        }));
+    }
+    async getStream(key) {
+        assertValidStorageKey(key);
+        try {
+            const result = await this.client.send(new GetObjectCommand({ Bucket: this.config.bucket, Key: key }));
+            return { stream: result.Body, size: result.ContentLength };
+        }
+        catch (error) {
+            if (isNotFound(error))
+                throw new MediaNotFoundError(key);
+            throw error;
+        }
+    }
+    async delete(key) {
+        assertValidStorageKey(key);
+        // DeleteObject is already idempotent on S3/MinIO — no existence
+        // check needed to match LocalDiskStorage's contract.
+        await this.client.send(new DeleteObjectCommand({ Bucket: this.config.bucket, Key: key }));
+    }
+    async exists(key) {
+        assertValidStorageKey(key);
+        try {
+            await this.client.send(new HeadObjectCommand({ Bucket: this.config.bucket, Key: key }));
+            return true;
+        }
+        catch (error) {
+            if (isNotFound(error))
+                return false;
+            throw error;
+        }
+    }
+}
+function isNotFound(error) {
+    if (typeof error !== "object" || error === null)
+        return false;
+    const name = "name" in error ? error.name : undefined;
+    if (name === "NoSuchKey" || name === "NotFound")
+        return true;
+    const status = "$metadata" in error
+        ? error.$metadata?.httpStatusCode
+        : undefined;
+    return status === 404;
+}

package/dist/media/storage/types.d.ts

@@ -0,0 +1,21 @@
+import type { Readable } from "node:stream";
+export interface MediaStorage {
+    readonly kind: "local" | "s3";
+    put(key: string, data: Buffer, mimeType: string): Promise<void>;
+    getStream(key: string): Promise<{
+        stream: Readable;
+        size?: number;
+    }>;
+    delete(key: string): Promise<void>;
+    exists(key: string): Promise<boolean>;
+    ensureReady(): Promise<void>;
+}
+export declare class MediaNotFoundError extends Error {
+    readonly key: string;
+    constructor(key: string);
+}
+export declare class MediaInvalidKeyError extends Error {
+    readonly key: string;
+    constructor(key: string);
+}
+export declare function assertValidStorageKey(key: string): void;

package/dist/media/storage/types.js

@@ -0,0 +1,44 @@
+export class MediaNotFoundError extends Error {
+    key;
+    constructor(key) {
+        super(`Media object not found in storage: ${key}`);
+        this.key = key;
+        this.name = "MediaNotFoundError";
+    }
+}
+// Thrown by assertValidStorageKey (below) for any key that isn't a plain,
+// relative, server-generated path fragment. Distinct from
+// MediaNotFoundError: this is "the caller asked for something that could
+// never be a legitimate key," not "no object exists at this key."
+export class MediaInvalidKeyError extends Error {
+    key;
+    constructor(key) {
+        super(`Invalid media storage key: ${JSON.stringify(key)}`);
+        this.key = key;
+        this.name = "MediaInvalidKeyError";
+    }
+}
+const DRIVE_LETTER_RE = /^[A-Za-z]:/;
+// Shared by BOTH drivers (S186c review, HIGH-2): keys are always
+// server-generated (`<uuid>/<sanitized-filename>`, see sanitizeForKey in
+// media-service.ts) and should never contain `.`/`..` segments or be
+// absolute/drive-lettered — but a hostile or buggy caller must be
+// rejected before either driver ever acts on the key, not just when
+// LocalDiskStorage happens to resolve one outside MEDIA_DIR. Hoisted here
+// (rather than duplicated per driver) so S3's key namespace gets the same
+// guarantee even though S3 itself has no filesystem to escape. Must run
+// BEFORE any path resolution (local.ts) or SDK call (s3.ts) — see the
+// contract suite's "hostile keys fail closed" block, which runs the same
+// cases against both drivers.
+export function assertValidStorageKey(key) {
+    if (key.length === 0) {
+        throw new MediaInvalidKeyError(key);
+    }
+    if (key.startsWith("/") || key.startsWith("\\") || DRIVE_LETTER_RE.test(key)) {
+        throw new MediaInvalidKeyError(key);
+    }
+    const segments = key.split(/[/\\]/);
+    if (segments.some((segment) => segment === "." || segment === "..")) {
+        throw new MediaInvalidKeyError(key);
+    }
+}

package/dist/routes/admin-static.d.ts

@@ -2,6 +2,8 @@ import type { FastifyInstance } from "fastify";
 interface AdminDirResolution {
     dir: string | null;
     invalidOverride: string | undefined;
+    fromOverride: boolean;
+    override: string | undefined;
 }
 export declare function resolveAdminDir(): AdminDirResolution;
 export declare function adminStaticRoutes(app: FastifyInstance): Promise<void>;

package/dist/routes/admin-static.js

@@ -4,6 +4,7 @@ import { fileURLToPath } from "node:url";
 import fastifyStatic from "@fastify/static";
 import { ADMIN_RATE_LIMIT, ipOnlyRateLimitConfig } from "../auth/route-rate-limits.js";
 import { isAdminUiEnabled } from "../config/admin-ui.js";
+import { readBundleStamp, serverVersion } from "../admin/sync-admin-bundle.js";
 // A usable admin directory: it must actually be a directory (not a file —
 // @fastify/static@10.1.3 throws "root must be a directory" at registration
 // otherwise, crashing buildApp()) and it must contain the SPA's index.html
@@ -29,8 +30,8 @@ export function resolveAdminDir() {
         // boot.
         const resolved = resolve(override);
         if (isUsableAdminDir(resolved))
-            return { dir: resolved, invalidOverride: undefined };
-        return { dir: null, invalidOverride: override };
+            return { dir: resolved, invalidOverride: undefined, fromOverride: true, override };
+        return { dir: null, invalidOverride: override, fromOverride: false, override };
     }
     const here = dirname(fileURLToPath(import.meta.url)); // dist/routes or src/routes
     const candidates = [
@@ -38,7 +39,7 @@ export function resolveAdminDir() {
         join(here, "..", "..", "..", "..", "apps", "admin-ui", "dist-bundle"),
     ];
     const dir = candidates.find((c) => isUsableAdminDir(c)) ?? null;
-    return { dir, invalidOverride: undefined };
+    return { dir, invalidOverride: undefined, fromOverride: false, override: undefined };
 }
 // Local copies of docs-static.ts's private helpers rather than a shared
 // export: that module deliberately keeps them private, and duplicating
@@ -132,7 +133,7 @@ export async function adminStaticRoutes(app) {
         app.log.info("[admin-static] VELORA_ADMIN=off — the admin SPA is not served");
         return;
     }
-    const { dir: adminDir, invalidOverride } = resolveAdminDir();
+    const { dir: adminDir, invalidOverride, fromOverride, override } = resolveAdminDir();
     // Exact-path redirects. Fastify 5's Reply#redirect signature is
     // (url, code), not (code, url) — verified against this repo's installed
     // fastify@5.8.5 source (lib/reply.js), which differs from older majors.
@@ -181,6 +182,43 @@ export async function adminStaticRoutes(app) {
         index: false,
         decorateReply: false,
     });
+    // S186b drift check: a scaffolded site copies the admin bundle out to
+    // VELORA_ADMIN_DIR (public/velora-admin) instead of serving it straight
+    // from node_modules, so it can go stale after `npm update` bumps the
+    // installed server without a matching `npm run sync-admin`. One clear
+    // warning on mismatch, never a hard failure — a stale admin is better
+    // than none, and the copied files are never touched without the user
+    // asking. Deferred to onReady (rather than run inline here) so it always
+    // fires exactly once per boot, after registration has fully succeeded,
+    // and so tests can attach a logger spy to the returned app before it
+    // runs. Only ever attached for the override path: the packaged/dev
+    // candidates resolveAdminDir() falls back to can't drift the same way,
+    // and default resolution must never read a stamp at all.
+    if (fromOverride) {
+        app.addHook("onReady", async () => {
+            // Review finding M2: this is a cosmetic drift check, not part of
+            // boot proper — nothing in it may ever abort startup. The entire
+            // body is wrapped so a surprise (a stamp file that vanishes between
+            // registration and ready, a permissions error, anything) is logged
+            // at debug and swallowed rather than propagating out of onReady and
+            // failing the boot it's merely commenting on.
+            try {
+                const stamp = readBundleStamp(adminDir);
+                const version = serverVersion();
+                if (stamp && stamp !== version) {
+                    // Review finding M3: `override` was captured by resolveAdminDir()
+                    // above, not re-read from process.env here — it names exactly the
+                    // value that was resolved into adminDir, immune to the env var
+                    // changing between registration and this onReady firing.
+                    app.log.warn(`The admin UI files in ${override} are from ${stamp}, but the server is ` +
+                        `${version} — run "npm run sync-admin" to update them.`);
+                }
+            }
+            catch (err) {
+                app.log.debug({ err }, "[admin-static] admin bundle drift check failed — continuing without it");
+            }
+        });
+    }
     // The SPA entry point, and the fallback that makes client-side routing
     // survive a refresh or a pasted deep link. decorateReply: false means
     // reply.sendFile isn't available here (docs-static.ts reads its 404.html

package/dist/routes/media-public.d.ts

@@ -0,0 +1,6 @@
+import type { FastifyPluginAsync } from "fastify";
+import type { MediaService } from "../media/media-service.js";
+export interface MediaPublicRoutesOptions {
+    mediaService: MediaService;
+}
+export declare const mediaPublicRoutes: FastifyPluginAsync<MediaPublicRoutesOptions>;

package/dist/routes/media-public.js

@@ -0,0 +1,265 @@
+import { isApiKeyHashValid, hashApiKey, KEY_PREFIX } from "../auth/api-keys.js";
+import { ipOnlyRateLimitConfig, MEDIA_RATE_LIMIT } from "../auth/route-rate-limits.js";
+import { verifyMediaToken } from "../media/media-tokens.js";
+import { MediaNotFoundError } from "../media/storage/types.js";
+import { sanitizeForKey } from "../media/media-service.js";
+// GET /media/:id/:filename — the stable, permanent media route (S186c
+// §3). Registered in the FULL app only (app.ts, beside admin-static.ts —
+// NEVER setup-app.ts, which has no MediaService/Prisma to serve from).
+// Deliberately a plain, unvalidated Fastify route rather than a Zod
+// route: this streams bytes (no JSON response schema makes sense) and
+// needs hand-rolled query-param messaging (reserved renditions params
+// named explicitly) that a generic Zod 400 wouldn't produce. Hidden from
+// OpenAPI below, same onRoute idiom as admin-static.ts.
+//
+// One uniform 404 body for every "you don't get these bytes" case —
+// unknown id, filename mismatch, and EVERY private-item auth failure
+// (no session/key/token at all, an expired token, a tampered token, a
+// token minted for a different id). This is the load-bearing S186c §3
+// "no existence oracle" rule: distinguishing "this id doesn't exist" from
+// "this id exists but you're not allowed to see it" would let a caller
+// probe the media library's private ids by watching which ones 404
+// differently. See the spec's own wording: "Otherwise 401/404 (same body
+// for missing and unauthorized-private)" — resolved here as ALWAYS 404,
+// with the identical body, never a 401 (a 401 with a distinct body/status
+// from the missing-id 404 would reopen exactly the oracle the spec is
+// closing).
+const NOT_FOUND_BODY = { message: "No media file found" };
+function sendNotFound(reply) {
+    return reply.code(404).send(NOT_FOUND_BODY);
+}
+// S186c Task 3 fix wave, H1 (probe-verified stored XSS): the upload's
+// mimeType is CLIENT-SUPPLIED at upload time (media.ts's multipart handler
+// trusts whatever the browser/curl sent) and was being replayed here
+// inline with no defenses — an uploaded text/html file executed on the
+// CMS's own origin, the same origin that hosts /velora (the admin SPA) and
+// answers /api/auth's refresh-cookie flow. Two independent layers:
+//
+//  1. X-Content-Type-Options: nosniff on EVERY response from this route
+//     (set via an onSend hook below, not per-branch, so it also covers the
+//     400/404 error replies) — belt-and-braces even though layer 2 already
+//     forces a safe Content-Type for anything not on the allowlist; it's
+//     what stops a browser from sniffing past a CORRECTLY-labeled but
+//     unusual type on the inline branch.
+//  2. An INERT-INLINE allowlist, gating `Content-Disposition: inline`
+//     itself: only types that cannot carry an active script payload when
+//     rendered BY THE BROWSER get served inline. Same idea, same list
+//     shape, as the precedent allowlist at
+//     plugins/blog/starter/src/pages/og-image/[id].ts:16 (raster images
+//     only, for its narrower og:image use case) — extended here
+//     deliberately for this route's broader job (it serves every media
+//     type the library holds, not just images meant to decode as
+//     <img>/<meta property="og:image">): the video/audio/pdf/plain-text
+//     additions are all formats a browser can render or play but never
+//     execute script from when navigated to directly. Every fetch, decode,
+//     and paint model reviewed:
+//       - image/*: raster decode into a bitmap, no script execution path.
+//       - video/mp4, video/webm, audio/mpeg, audio/ogg, audio/wav: decoded
+//         by the media pipeline (frames/samples), never parsed as
+//         markup/script.
+//       - application/pdf: Chrome/Firefox's built-in PDF VIEWER renders
+//         it in an isolated context; it is not treated as same-origin
+//         HTML. (A crafted PDF opened in a vulnerable native reader is a
+//         reader-software risk, not a same-origin-script risk this route
+//         can create or prevent.)
+//       - text/plain: browsers render it as literal, unescaped text —
+//         never parsed as HTML/script, by spec.
+//     Everything else — notably text/html, image/svg+xml (SVG can embed
+//     <script>), application/xhtml+xml, and text/xml (XML+XSLT can
+//     execute) — falls through to the ELSE branch below: forced
+//     Content-Disposition: attachment (browser downloads it, never
+//     renders it inline on this origin) AND Content-Type forced to
+//     application/octet-stream (defense-in-depth against a client that
+//     ignores Content-Disposition and tries to render the body anyway).
+const INERT_INLINE_MIME_TYPES = new Set([
+    "image/png",
+    "image/jpeg",
+    "image/gif",
+    "image/webp",
+    "image/avif",
+    "video/mp4",
+    "video/webm",
+    "audio/mpeg",
+    "audio/ogg",
+    "audio/wav",
+    "application/pdf",
+    "text/plain",
+]);
+// Content-Disposition's filename param is a quoted string — CR/LF or a
+// bare `"` in it would let a crafted upload filename inject a second
+// header/directive. Reuses media-service.ts's own storage-key sanitizer
+// (already the one source of truth for "what's safe to put in a header
+// built from an uploaded filename") rather than a second, potentially
+// drifting allowlist.
+function sanitizedAttachmentFilename(filename) {
+    return sanitizeForKey(filename);
+}
+// Renditions are reserved, not built (S186c §4) — these query params are
+// claimed now so a future rendition implementation isn't a silent
+// behavior change for anyone hitting them today. Named explicitly in the
+// 400 body (rather than folded into "unknown query parameter") so a
+// caller who read the docs and tried `?w=400` early gets told WHY, not a
+// generic-looking validation error.
+const RESERVED_RENDITION_KEYS = new Set(["preset", "w"]);
+// Every other query param this route accepts.
+const ALLOWED_QUERY_KEYS = new Set(["token"]);
+// Silent, non-replying session check — request.jwtVerify() throws on a
+// missing/invalid/expired cookie or bearer JWT, which requireAuth (S162)
+// turns into an immediate 401 reply. This route can't use requireAuth
+// directly: session is only ONE of three ways in (session OR read-scope
+// API key OR ?token=), so a failed check here must fall through to the
+// next check, not reply.
+async function hasAdminSession(request) {
+    try {
+        await request.jwtVerify();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// Silent, non-replying API-key check — the read-scope idiom
+// (requireApiKeyScope("read") never rejects; ANY live key clears "read",
+// same as this) applied without the reply-on-failure side effect
+// requireApiKey has, for the same OR-chain reason as hasAdminSession
+// above. Deliberately does not distinguish "no header" from "bad key"
+// from "revoked key" — same UNAUTHORIZED_MESSAGE-style uniformity
+// auth/api-keys.ts's own 401 already applies, just without the reply
+// (this route never 401s at all — see the ALWAYS-404 note at the top of
+// this file).
+//
+// L2 fix wave: pre-checks the `vk_` prefix (same shape as
+// auth/api-keys.ts:66's requireApiKey) BEFORE hashing/querying — a
+// presented Bearer value that doesn't even look like one of our keys is
+// rejected on a string comparison instead of spending a SHA-256 + a DB
+// round trip on it. Purely a cost/DoS-surface optimization: the query
+// path below is already correct and would reject the same inputs, just
+// slower.
+async function hasReadApiKey(request) {
+    const header = request.headers.authorization;
+    if (!header?.startsWith("Bearer "))
+        return false;
+    const key = header.slice("Bearer ".length).trim();
+    if (!key.startsWith(KEY_PREFIX))
+        return false;
+    return isApiKeyHashValid(hashApiKey(key));
+}
+export const mediaPublicRoutes = async (app, opts) => {
+    const { mediaService } = opts;
+    // Own rate lane (route-rate-limits.ts's MEDIA_RATE_LIMIT), plugin-level
+    // — same ipOnlyRateLimitConfig()-spread-then-override idiom
+    // admin-static.ts uses for ADMIN_RATE_LIMIT, and for the identical
+    // reason: this route serves anonymous/public-bandwidth traffic that
+    // can't bucket on the three-lane jwt:/apiKey: rateLimitConfig (a
+    // public image request usually carries neither).
+    await app.register(import("@fastify/rate-limit"), {
+        ...ipOnlyRateLimitConfig(),
+        max: MEDIA_RATE_LIMIT.max(),
+        timeWindow: MEDIA_RATE_LIMIT.timeWindow(),
+    });
+    // Static-bytes surface, not a Zod-validated JSON API — same "hide from
+    // Swagger" reasoning admin-static.ts documents at length. Scoped to
+    // this encapsulated child, so it can only ever match this route.
+    app.addHook("onRoute", (routeOptions) => {
+        routeOptions.schema = { ...routeOptions.schema, hide: true };
+    });
+    // H1: nosniff on EVERY response this plugin sends — an onSend hook
+    // rather than a per-branch reply.header() call, so it also covers the
+    // 400 (unknown/reserved query param) and 404 replies, not just the
+    // 200 byte-serving path. Scoped to this encapsulated child (same as the
+    // onRoute hook above), so it can never leak onto an unrelated route.
+    app.addHook("onSend", async (_request, reply) => {
+        reply.header("X-Content-Type-Options", "nosniff");
+    });
+    app.get("/media/:id/:filename", async (request, reply) => {
+        const { id, filename } = request.params;
+        const query = request.query;
+        const queryKeys = Object.keys(query);
+        // Reserved-renditions params are checked (and named) before the
+        // generic unknown-param check, so `?preset=thumb` gets the
+        // renditions-specific message even though it would also fail the
+        // generic check.
+        const reservedHit = queryKeys.filter((key) => RESERVED_RENDITION_KEYS.has(key));
+        if (reservedHit.length > 0) {
+            return reply.code(400).send({
+                message: `Query parameter(s) ${reservedHit.join(", ")} are reserved for future rendition support ` +
+                    "(S186c §4) and not implemented yet.",
+            });
+        }
+        const unknownKeys = queryKeys.filter((key) => !ALLOWED_QUERY_KEYS.has(key));
+        if (unknownKeys.length > 0) {
+            return reply.code(400).send({ message: `Unknown query parameter(s): ${unknownKeys.join(", ")}` });
+        }
+        const media = await mediaService.getById(id);
+        // Filename is cosmetic-but-verified (S186c §3): a correct id with the
+        // WRONG filename 404s just like an unknown id — no enumeration of a
+        // renamed/previous filename for a real item.
+        if (!media || media.filename !== filename) {
+            return sendNotFound(reply);
+        }
+        if (media.visibility === "private") {
+            const token = typeof query.token === "string" ? query.token : undefined;
+            const authorized = (await hasAdminSession(request)) ||
+                (await hasReadApiKey(request)) ||
+                (token !== undefined && verifyMediaToken(id, token));
+            if (!authorized) {
+                return sendNotFound(reply);
+            }
+        }
+        try {
+            const { stream, size } = await mediaService.getStream(id);
+            if (media.visibility === "public") {
+                // Keys are content-addressed by upload id (S186c §3) — a replaced
+                // file gets a new id, so this can be cached forever.
+                //
+                // M1 (undocumented limitation, now documented): flipping an item
+                // PRIVATE after this header has already gone out does not reach
+                // into every browser cache/CDN edge that already stored a copy
+                // under this immutable header — a 1-year `max-age=31536000,
+                // immutable` copy already sitting in some cache can keep serving
+                // that response to whoever holds it, without ever re-asking this
+                // server, for up to a year after the flip. The `visibility`
+                // check above governs new requests only. There is no cache-
+                // invalidation mechanism here (no CDN purge API call, no cache-
+                // busting URL change on flip — the URL is deliberately stable
+                // across a visibility flip, S186c §2) and adding one is out of
+                // scope for this fix; this comment exists so the tradeoff is
+                // findable, not silent. See docs/security/threat-model.md and
+                // the admin media UI's `mediaLibrary.privateHelp` copy for the
+                // operator-facing version of this same caveat.
+                reply.header("Cache-Control", "public, max-age=31536000, immutable");
+            }
+            else {
+                // Never let a shared/CDN cache retain a private object under a
+                // URL that a later visitor (anonymous, or holding a DIFFERENT
+                // token) could replay.
+                reply.header("Cache-Control", "private, no-store");
+            }
+            // H1: gate Content-Disposition: inline on the INERT_INLINE_MIME_TYPES
+            // allowlist above, not on the raw client-supplied mimeType — see that
+            // constant's doc comment for the full reasoning. Anything not on the
+            // allowlist is forced to download as an opaque octet-stream instead
+            // of ever being rendered by the browser on this origin.
+            if (INERT_INLINE_MIME_TYPES.has(media.mimeType)) {
+                reply.header("Content-Disposition", "inline");
+                reply.type(media.mimeType);
+            }
+            else {
+                reply.header("Content-Disposition", `attachment; filename="${sanitizedAttachmentFilename(media.filename)}"`);
+                reply.type("application/octet-stream");
+            }
+            if (size !== undefined)
+                reply.header("Content-Length", size);
+            return reply.send(stream);
+        }
+        catch (error) {
+            // The metadata row exists but the underlying object is gone (a
+            // storage-level inconsistency) — still "no bytes for you," same
+            // body as every other miss on this route, not a 500.
+            if (error instanceof MediaNotFoundError) {
+                return sendNotFound(reply);
+            }
+            throw error;
+        }
+    });
+};

package/dist/routes/media.d.ts

@@ -1,5 +1,6 @@
 import type { FastifyPluginAsyncZod } from "fastify-type-provider-zod";
-import type { MediaService } from "../media/media-service.js";
+import { type MediaService } from "../media/media-service.js";
+export declare function invalidUploadFilenameReason(filename: string): string | null;
 export interface MediaRoutesOptions {
     mediaService: MediaService;
 }