@aglyn/tenant-data-admin 1.0.0-beta.143

package/src/lib/server/serve-media-cdn.js

@@ -0,0 +1,1370 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { pipeline } from "node:stream/promises";
+import { isLockdownActive, MEDIA_CDN_POSTER_PARAM, MEDIA_CDN_RENDITION_AUTO, MEDIA_CDN_RENDITION_PARAM, MEDIA_CDN_ROUTE, MEDIA_POSTER_OBJECT_SUFFIX, mediaPosterObjectPath, mediaRenditionObjectPath, normalizeHostLockdown, normalizeOrgLockdown, parseMediaRenditions } from "@aglyn/aglyn/server";
+// By path, and out of every barrel: see the module note in `media-cdn-scope`.
+import { MEDIA_CDN_SEGMENT, mediaCdnScopeRefusal, parseMediaCdnScope } from "@aglyn/aglyn/app-utils/media-cdn-scope";
+import { mediaDeliveryProvider } from "@aglyn/aglyn/plugin-manager/media-delivery-provider";
+import { analyticsDayExpiresAt } from "./analytics-retention.js";
+import { firebaseAdmin } from "./firebase-admin.js";
+import { getPlatformLockdown } from "./lockdown.js";
+import { mediaCdnRateLimitRefusal } from "./media-cdn-rate-limit.js";
+import { mediaDeliveryOrgIdFor, mediaDeliveryRedirect } from "./media-delivery.js";
+import { getMediaQuarantine } from "./media-quarantine.js";
+import { verifyMediaAccess } from "./media-signing.js";
+import { mediaStoragePathInScope } from "./media-storage-path.js";
+/**
+ * Variant widths generated at upload (AGL-175).
+ *
+ * Re-exported, not defined: the list now lives in `@aglyn/aglyn`'s media-ref
+ * so the RENDERER can reach it too. `image.tsx` carried its own
+ * `[320, 640, 1280]` literal, so a width added here never reached the srcSet.
+ */ export { MEDIA_CDN_VARIANT_WIDTHS } from "@aglyn/aglyn/server";
+/**
+ * The scope grammar and the refusal this handler enforces (AGL-1043).
+ *
+ * Re-exported, not defined: the pure rule lives in `@aglyn/aglyn`'s
+ * `media-cdn-scope`, so the readers that must reach this handler's verdict —
+ * the composition's video facts and the besigner canvas — call the functions
+ * it calls.
+ */ export { mediaCdnAllows, mediaCdnScopeRefusal, parseMediaCdnScope } from "@aglyn/aglyn/app-utils/media-cdn-scope";
+const SEGMENT = MEDIA_CDN_SEGMENT;
+/**
+ * The query string to carry onto the stable URL when a stale content pin
+ * redirects (AGL-2685).
+ *
+ * REBUILT from the four parameters this handler reads, never forwarded whole.
+ * Two reasons, and the second is the one that matters:
+ *
+ * 1. Everything else is inert here — it would only split the CDN cache key
+ *    for a response that is identical either way.
+ * 2. `Location` is a header, and the value would otherwise be caller-supplied
+ *    text. Node rejects a CR or LF in a header value rather than splitting
+ *    the response, so this is a second lock on a door that is already shut —
+ *    which is the right number of locks for a header built from user input.
+ *
+ * `exp` and `sig` ride along because a private asset's signature covers
+ * (scope, mediaId, exp) and never the hash, so it is still valid at the
+ * target. Dropping them would turn a redirect into a 404 for exactly the
+ * assets whose delivery is most sensitive.
+ */ export function mediaCdnForwardedQuery(query) {
+    const params = new URLSearchParams();
+    // `poster` and `r` join the set for the reason the others are in it: the
+    // redirect must name the SAME representation the caller asked for, or a
+    // stale content pin on a poster URL lands the browser on the master video
+    // (AGL-2743).
+    for (const key of [
+        'w',
+        'poster',
+        'r',
+        'download',
+        'exp',
+        'sig'
+    ]){
+        const raw = query[key];
+        const value = Array.isArray(raw) ? raw[0] : raw;
+        if (value !== undefined && value !== '') params.set(key, String(value));
+    }
+    const encoded = params.toString();
+    return encoded ? `?${encoded}` : '';
+}
+/**
+ * The stable (non-content-hashed) URL's caching contract.
+ *
+ * This was `public, max-age=3600, stale-while-revalidate=86400`, and that
+ * header contradicted the promise the stable URL exists to make. Measured on
+ * production 2026-08-12: Vercel's edge DOES cache this route on a bare
+ * `max-age` (`x-vercel-cache: MISS` then `HIT`, `age` climbing) — so the
+ * saving was never in question. What a browser `max-age` breaks is
+ * *propagation*. `max-age=3600` reaches the client, so a browser holding a
+ * replaced asset will not send a conditional request for a full hour: the
+ * ETag below never gets a chance to answer, and nothing on our side can bust
+ * a browser cache. Every other cacheable route in the repo already uses
+ * `s-maxage` for exactly this reason — see `seo-origin.spec.ts`, "never a
+ * browser `max-age`, which nothing could bust".
+ *
+ * So: a short browser `max-age` that still collapses the burst of repeat
+ * requests within one page view (an image referenced by four `srcSet`
+ * candidates, a tile rendered in a grid and again in a drawer), and the full
+ * hour moved to `s-maxage` where it belongs. Worst stale read is now 60 s of
+ * replaced bytes in one browser rather than an hour, at the cost of one
+ * conditional request per image per minute — answered by the EDGE from its
+ * own copy, so it adds no Storage read and no Firestore read.
+ *
+ * The immutable content-hashed form is untouched: its URL changes with its
+ * bytes, so it can and should be pinned in the browser for a year.
+ *
+ * Since AGL-1515 this policy applies to IMAGE responses only — see
+ * {@link mediaCdnEdgeCacheable}.
+ */ export const MEDIA_CDN_STABLE_CACHE_CONTROL = 'public, max-age=60, s-maxage=3600, stale-while-revalidate=86400';
+/**
+ * The stable URL's policy for types the edge must never hold (AGL-1515):
+ * the same 60-second browser window and the same ETag/304 contract, with
+ * `private` in place of `public, s-maxage` so no shared cache stores a
+ * full body.
+ *
+ * Why the edge must never hold one: Vercel's edge, holding a cached
+ * full-body 200, answers a `Range` request FROM that entry as a
+ * spec-violating hybrid — status 200, a `Content-Range` header, and only
+ * the requested slice as the body (`x-vercel-cache: HIT`; reproduced twice
+ * on production, 2026-08-13). A video player seeking into such an asset
+ * adopts a 100-byte slice as the complete file: silent playback corruption.
+ *
+ * The S4 shape below this constant was built on Vercel's documented
+ * cacheable-response criteria ("Request doesn't contain Range header"),
+ * read as "ranged requests bypass the edge". Production falsified that
+ * reading: the criteria govern what the edge STORES, not what it SERVES. A
+ * ranged request is still matched against the URL-keyed entry a previous
+ * plain GET left behind, and the edge's slicing layer rewrites the body
+ * and adds `Content-Range` without rewriting the stored 200 status.
+ *
+ * `private` is the lever because it is in the same documented criteria
+ * list as an absolute storage preventer ("Response doesn't contain the
+ * `private` … directives"), where `Vary: Range` is undocumented on
+ * Vercel, discouraged by RFC 9110, and untestable anywhere but a
+ * production deploy. What it costs: edge caching for non-image assets
+ * under Vercel's 10 MB cacheable-size cap. Real video mostly sits ABOVE
+ * the cap and was never edge-cached — the mangling reproduced on a 186 KB
+ * asset precisely because small ones are the ones that get cached.
+ */ export const MEDIA_CDN_STABLE_EDGE_BYPASS_CACHE_CONTROL = 'private, max-age=60';
+/** The immutable content-hashed URL's policy for edge-cacheable (image) types. */ export const MEDIA_CDN_IMMUTABLE_CACHE_CONTROL = 'public, max-age=31536000, immutable';
+/**
+ * The immutable URL's policy for edge-bypassing types (AGL-1515): the
+ * browser keeps its year — the URL still changes with the bytes — while
+ * the edge holds nothing it could mangle.
+ */ export const MEDIA_CDN_IMMUTABLE_EDGE_BYPASS_CACHE_CONTROL = 'private, max-age=31536000, immutable';
+/**
+ * Whether a response of this content type may be edge-cached (AGL-1515).
+ *
+ * The split is "types no realistic client ranges into": browsers fetch
+ * images with plain GETs (`<img>`, `srcSet`, save-as — all of them), while
+ * every consumer that seeks or resumes — `<video>`/`<audio>` players, PDF
+ * viewers, download managers — operates on the non-image types. Images stay
+ * on the shared edge policy because they are the DAM grid's hot path (4.3 KB
+ * WebP tiles at volume), and pushing them to origin to fix video would trade
+ * a real regression for a theoretical one.
+ *
+ * Accepted residual, recorded here on purpose: a hand-built `Range` request
+ * against an edge-cached IMAGE can still be answered with the hybrid (that
+ * is exactly the AGL-1515 favicon repro). No browser or player issues one,
+ * and the alternative — `private` on images too — costs the hot path an
+ * edge hit rate it measurably has.
+ *
+ * Unknown or absent types return false: correctness over cache.
+ */ export function mediaCdnEdgeCacheable(contentType) {
+    return String(contentType != null ? contentType : '').split(';')[0].trim().toLowerCase().startsWith('image/');
+}
+/**
+ * The CDN's OWN Content-Security-Policy (AGL-1474).
+ *
+ * An uploaded `image/svg+xml` is a document, not a picture. It passes the
+ * `image/*` allowlist, it is stored under whatever type the client declared,
+ * and this handler serves it `inline` from the console's own origin — and
+ * from every tenant site's, since the same handler mounts in both apps. So
+ * `<script>alert(document.domain)</script>` inside an uploaded logo executed
+ * on `app.aglyn.com` the moment the asset URL was opened top-level, for
+ * anyone with editor rights.
+ *
+ * Nothing already in place stopped it. `X-Content-Type-Options: nosniff`
+ * blocks HTML *mislabelled* as an image; it says nothing about a file
+ * honestly labelled `image/svg+xml`, which browsers render as a scripted
+ * document. And there was no CSP on this response **at all**: since AGL-523
+ * the policy is built per-response in each app's middleware, and both
+ * middlewares' matchers exclude `api` (`apps/console/middleware.ts`,
+ * `apps/tenant/middleware.ts`), so a directly-navigated CDN URL never passed
+ * through the code that sets one.
+ *
+ * That is precisely why the header is set HERE, on the response, rather than
+ * added to a matcher: a route-level header cannot be lost to a matcher edit,
+ * a rewrite, or a new mount of `serveMediaCdn` in a third app. It is also
+ * what makes this the containment rather than the remediation — it covers
+ * every asset already in the bucket, including the SVGs uploaded before the
+ * sanitizer existed, without rewriting a byte.
+ *
+ * **It does not touch `<img src>`, which is how logos and marks are used
+ * across this product.** A browser loading an SVG as an image neither runs
+ * its script nor applies the response's CSP — CSP governs documents and
+ * workers. The policy only becomes live in the case that is the vector: the
+ * asset opened as a top-level document (or framed via `<object>`/`<iframe>`).
+ */ export const MEDIA_CDN_BASE_CSP = "default-src 'none'; script-src 'none'; object-src 'none'; " + "base-uri 'none'; form-action 'none'";
+/**
+ * The policy for a type a browser will treat as an ACTIVE DOCUMENT. Adds
+ * `sandbox` — an opaque origin, so even a hypothetical execution has no
+ * `document.domain`, no cookies and no storage to reach for.
+ *
+ * `style-src 'unsafe-inline'` and the two `data:` allowances are not
+ * concessions to script: with `script-src 'none'` and `sandbox` in force,
+ * nothing in CSS or a data URI can execute. They exist so that opening a
+ * logo's URL directly still shows the logo — `default-src 'none'` alone
+ * would blank an SVG's own `<style>` block and its embedded raster fills,
+ * which is a visible regression on legitimate assets and buys no safety.
+ */ export const MEDIA_CDN_ACTIVE_DOCUMENT_CSP = `${MEDIA_CDN_BASE_CSP}; style-src 'unsafe-inline'; img-src data:; ` + 'font-src data:; sandbox';
+/**
+ * Types a browser parses as a document rather than rendering as an image.
+ *
+ * Keying off the SERVED content type is sound only because this response also
+ * carries `nosniff`: the browser is bound to the label we send, so an SVG
+ * uploaded under a `image/png` label is decoded as a PNG and is inert. Every
+ * type here except SVG is refused by the upload allowlist today; they are
+ * listed anyway because the allowlist has moved before (AGL-1465) and because
+ * a legacy fourth upload route accepted arbitrary types for its whole life
+ * before AGL-1485 deleted it.
+ */ const MEDIA_CDN_ACTIVE_DOCUMENT_TYPES = new Set([
+    'image/svg+xml',
+    'image/svg',
+    'text/html',
+    'application/xhtml+xml',
+    'application/xml',
+    'text/xml',
+    'text/xsl',
+    'application/xslt+xml',
+    'application/mathml+xml'
+]);
+/**
+ * Types this CDN will serve `inline`.
+ *
+ * `?download=1` has always been able to force `attachment`, but it is the
+ * REQUESTER's flag — the safe disposition cannot depend on a caller asking
+ * for it. Anything not on this list is served as a download whatever the
+ * query says, so opening its URL top-level saves a file instead of handing
+ * the type to a renderer on the customer's own domain.
+ *
+ * The list is what a browser has a real inline use for on this route:
+ * pictures, media a player streams, and PDFs, which people expect to open in
+ * a tab. Everything else — the office and text formats, JSON, ZIP, and any
+ * legacy `text/html` still sitting in the bucket from before the allowlist
+ * narrowed — has no inline use case here and every one of them is a document
+ * a browser would happily parse.
+ *
+ * SVG stays INLINE deliberately. AGL-1474 chose the sandboxing CSP over a
+ * forced download precisely so that opening a logo's URL still shows the
+ * logo, and that policy already denies it script, an origin, and everything
+ * it could reach for. Turning it into a download now would take that
+ * decision back without adding to it.
+ */ function servesInline(contentType) {
+    const type = String(contentType != null ? contentType : '').split(';')[0].trim().toLowerCase();
+    return type.startsWith('image/') || type.startsWith('video/') || type.startsWith('audio/') || type === 'application/pdf';
+}
+/** The `Content-Security-Policy` for a response serving `contentType`. */ export function mediaCdnContentSecurityPolicy(contentType) {
+    const type = String(contentType != null ? contentType : '').split(';')[0].trim().toLowerCase();
+    return MEDIA_CDN_ACTIVE_DOCUMENT_TYPES.has(type) ? MEDIA_CDN_ACTIVE_DOCUMENT_CSP : MEDIA_CDN_BASE_CSP;
+}
+/**
+ * Lockdown on the delivery path (AGL-1520).
+ *
+ * A security-locked org's SITE stops within seconds (the tenant middleware
+ * 503s, AGL-1501) — but until this gate existed its public media kept
+ * serving worldwide: to hot-links, to third-party embeds, and to the
+ * infected asset's own URL, which for an "infected host" security lock is
+ * the exact thing the lock was pressed to stop.
+ *
+ * **Which reasons stop delivery — decided per reason, not blanket:**
+ *
+ * - `security` — REFUSE. The point of the lock: the org's content, media
+ *   included, must stop serving.
+ * - `manual` — REFUSE. A staff suspension with no reason code (every
+ *   pre-lockdown `suspendedAt` normalizes to `manual`) is "we turned this
+ *   org off"; content continuing to serve would make the kill partial.
+ * - `maintenance` — SERVE. The maintenance notice surface may itself
+ *   reference org assets (a logo on the notice page), the window is
+ *   temporary and non-adversarial, and blanking every image buys no safety.
+ * - `billing` — SERVE. The AGL-1506 principle: billing-locked orgs keep the
+ *   surfaces that let them come back (members can still reach billing to
+ *   pay). The site already 503s, so whether a hot-linked image serves is
+ *   nearly moot — and refusing would punish e.g. an email-signature logo
+ *   for a payment lapse. Serving is the cheap, reversible answer.
+ *
+ * Scopes are checked INDIVIDUALLY against that matrix rather than through
+ * `resolveLockdown`, on purpose: the resolver answers "which notice does a
+ * visitor see" and returns the WIDEST active scope — so a platform
+ * `maintenance` window would mask a concurrent org `security` lock and the
+ * infected asset would keep serving. Delivery has no notice to pick; the
+ * question is only "does ANY active lockdown demand these bytes stop".
+ */ export function lockdownStopsMediaDelivery(state, nowMs) {
+    if (!state || !isLockdownActive(state, nowMs)) return false;
+    return state.reason === 'security' || state.reason === 'manual';
+}
+/**
+ * **Read cost (AGL-1302):** the verdict inputs are TTL-cached in-process
+ * per CDN scope — one lookup per scope per {@link MEDIA_CDN_LOCK_TTL_MS},
+ * not per asset. A DAM grid firing dozens of requests coalesces into one;
+ * the platform doc rides `getPlatformLockdown`'s existing 15s cache. Same
+ * fail-open posture as the verdict core: an unreachable Firestore is an
+ * outage, not a lockdown, and must not blank every customer image.
+ *
+ * That lookup is one BatchGetDocuments at org scope, and two at host scope
+ * — `hosts` and `hostIndex` batched together, then the owning org, whose id
+ * is what `hostIndex` returns and so cannot join the batch. Every one of
+ * them is projected to {@link SUSPENSION_FIELDS}: the verdict needs three
+ * fields, and the host document is the largest in the product. Measured
+ * against production, projecting the three reads and batching two of them
+ * took the host branch from 3 round trips and 2,964 B to 2 and 34 B.
+ *
+ * **Staleness bound, stated rather than hidden:** a warm origin refuses
+ * within ≤15s of the org-doc write (the platform panic number). What the
+ * origin cannot reach: browsers hold the stable URL up to 60s
+ * (`max-age=60`); Vercel's edge holds image responses up to `s-maxage=3600`
+ * (+ one stale serve while revalidating) — so an already-edge-cached image
+ * URL can serve up to ~1h into a lock; non-image types are `private`
+ * (AGL-1515) and never edge-held. The immutable content-hashed form is
+ * browser-pinned for a year in clients that already fetched it — there is
+ * no per-asset purge API, so that copy is out of reach by design; NEW
+ * fetchers of the same URL refuse at the next origin miss. Compare the
+ * AGL-1501 drill: host pages flip ≤10s; assets lag minutes-to-an-hour at
+ * the caching tiers, which is the accepted trade for a near-zero read cost
+ * on the hottest unauthenticated path.
+ *
+ * **Out of this control's reach entirely:** free-tier raw
+ * `firebasestorage.googleapis.com` URLs — no code of ours runs there.
+ * Stated on AGL-1520, and now answered elsewhere rather than here: a
+ * `security` lock rotates those objects' download tokens
+ * (`media-download-tokens.ts`, AGL-1526), which kills the URL at Google's
+ * edge. That is a SIBLING control, not an extension of this one — it is
+ * `security`-only, it is irreversible for embeds, and like this gate it
+ * stops only new origin fetches (AGL-1615). Bytes already cached anywhere
+ * remain out of reach of both.
+ */ const MEDIA_CDN_LOCK_TTL_MS = 15000;
+const lockCache = new Map();
+const lockPending = new Map();
+/**
+ * Drop the per-scope lock cache. Tests need it between cases; production
+ * convergence is the TTL — the lock is written by the console app and served
+ * by the tenant app, different processes an in-process invalidation can
+ * never reach.
+ */ export function invalidateMediaCdnLockCache() {
+    lockCache.clear();
+    lockPending.clear();
+}
+/**
+ * Every field the delivery verdict reads off a host or org document, and
+ * the projection sent to Firestore — ONE list, because the carrier below is
+ * built from it. A mask that omitted a field the carrier reads would leave
+ * that field `undefined` and silently soften the lock: drop
+ * `suspendedReasonCode` and every lock normalizes to `manual`, which
+ * REFUSES delivery for locks that should serve; drop `suspendedAt` and no
+ * lock is ever seen at all. Neither failure can be introduced here without
+ * changing the one array both sides use.
+ *
+ * `suspendedMode` and `suspendedEnforcement` are deliberately absent:
+ * {@link lockdownStopsMediaDelivery} decides on `reason` and the active
+ * window alone, so a read-only or takedown-class lock stops these bytes on
+ * exactly the same terms as a full one.
+ */ const SUSPENSION_FIELDS = [
+    'suspendedAt',
+    'suspendedReasonCode',
+    'suspendedUntilMs'
+];
+/** Which host owns the asset's scope — the only field read off `hostIndex`. */ const HOST_INDEX_ORG_FIELD = 'orgId';
+/** The `suspended*` field family off a snapshot, for the normalizers. */ const suspensionCarrier = (snapshot)=>Object.fromEntries(SUSPENSION_FIELDS.map((field)=>[
+            field,
+            snapshot.get(field)
+        ]));
+/** TTL-cached: does any lockdown covering `scope` stop delivery? */ async function mediaCdnScopeLocked(scope) {
+    const key = `${scope.isOrg ? 'org' : 'host'}:${scope.scopeId}`;
+    const cached = lockCache.get(key);
+    if (cached && Date.now() - cached.at < MEDIA_CDN_LOCK_TTL_MS) {
+        return cached.blocked;
+    }
+    let pending = lockPending.get(key);
+    if (!pending) {
+        pending = (async ()=>{
+            let blocked;
+            try {
+                const nowMs = Date.now();
+                // Platform first: cached, and a platform security lock is the panic
+                // button — asset delivery is part of what it stops.
+                blocked = lockdownStopsMediaDelivery(await getPlatformLockdown(), nowMs);
+                const firestore = firebaseAdmin.app().firestore();
+                if (!blocked && scope.isOrg) {
+                    // Org forms (`org:{orgId}` and `org:{orgId}:{hostId}`): the org
+                    // doc governs. The context host's own lock is not consulted — a
+                    // suspended HOST's pages 503 already, and which sites may USE an
+                    // org asset is `visibleTo`'s question, not the lock's.
+                    const [org] = await firestore.getAll(firestore.collection('orgs').doc(scope.scopeId), {
+                        fieldMask: [
+                            ...SUSPENSION_FIELDS
+                        ]
+                    });
+                    blocked = lockdownStopsMediaDelivery(normalizeOrgLockdown(suspensionCarrier(org)), nowMs);
+                } else if (!blocked) {
+                    // Host-library form: the host's own lock, and the OWNING org's —
+                    // an org lock never stamps host docs (AGL-1506), so a host-only
+                    // read would silently miss the very lock this issue is about.
+                    //
+                    // One `getAll`, not two parallel gets: `DocumentReference.get()`
+                    // is `getAll([ref])`, so a `Promise.all` of two of them is two
+                    // BatchGetDocuments round trips where the batch is one. The org
+                    // read below cannot join them — its id is what `hostIndex`
+                    // returns — so two is the floor for this branch, not three.
+                    const [host, hostIndex] = await firestore.getAll(firestore.collection('hosts').doc(scope.scopeId), firestore.collection('hostIndex').doc(scope.scopeId), {
+                        fieldMask: [
+                            ...SUSPENSION_FIELDS,
+                            HOST_INDEX_ORG_FIELD
+                        ]
+                    });
+                    blocked = lockdownStopsMediaDelivery(normalizeHostLockdown(suspensionCarrier(host)), nowMs);
+                    const orgId = hostIndex.get(HOST_INDEX_ORG_FIELD);
+                    if (!blocked && typeof orgId === 'string' && orgId) {
+                        const [org] = await firestore.getAll(firestore.collection('orgs').doc(orgId), {
+                            fieldMask: [
+                                ...SUSPENSION_FIELDS
+                            ]
+                        });
+                        blocked = lockdownStopsMediaDelivery(normalizeOrgLockdown(suspensionCarrier(org)), nowMs);
+                    }
+                }
+            } catch (unused) {
+                // Fail open — the lockdown core's posture (see lockdown.ts): an
+                // unreachable Firestore is an outage, not a lockdown.
+                blocked = false;
+            }
+            lockCache.set(key, {
+                at: Date.now(),
+                blocked
+            });
+            return blocked;
+        })().finally(()=>{
+            lockPending.delete(key);
+        });
+        lockPending.set(key, pending);
+    }
+    return pending;
+}
+/**
+ * THE delivery-policy seam: "may this asset be served at all?" — one
+ * question, one function, consulted once per request before any caching
+ * exit. Distinct from `mediaCdnAllows` (which site may use it under this
+ * URL) and from the signature check (may the public fetch it): this asks
+ * whether the platform is willing to serve the bytes to ANYONE.
+ *
+ * Two independent reasons to refuse, both answered here so the handler
+ * keeps ONE refusal path:
+ *
+ * - `'locked'` — a lockdown covering this SCOPE (AGL-1520): the whole org
+ *   or host is off.
+ * - `'quarantined'` — this ASSET is on the deny list (AGL-1512): one
+ *   infected, abusive or DMCA-noticed file is off while everything else in
+ *   the same workspace keeps serving. That proportionality is the point —
+ *   a single bad object should not cost a customer their whole site.
+ *
+ * Order is scope-then-asset because the scope verdict is the cheaper cached
+ * one and the wider fact; the caller does not distinguish them on the wire
+ * (both are the same neutral 410), so the order is a cost decision only.
+ *
+ * Read cost, since this sits on the hottest unauthenticated path: the scope
+ * verdict is one read per SCOPE per 15s, and the quarantine deny list is
+ * one read per PROCESS per 15s for every asset in existence — it is a
+ * single document. Fifty DAM tiles pay two reads between them, not a
+ * hundred.
+ */ export async function mediaCdnServeBlock(scope, asset) {
+    if (await mediaCdnScopeLocked(scope)) return 'locked';
+    const quarantined = await getMediaQuarantine({
+        contentSha256: asset.contentSha256,
+        contentHash: asset.contentHash,
+        scopeSegment: asset.scopeSegment,
+        mediaId: asset.mediaId
+    });
+    return quarantined ? 'quarantined' : null;
+}
+/**
+ * Whether `?download=1` was asked for (AGL-1411). Strictly opt-in: absent,
+ * `0`, `false` or junk all keep the historical `inline`, because the default
+ * is what every `<img src>` in every published site relies on.
+ *
+ * Only `1` and `true` count, rather than "any truthy-looking string". The
+ * query string is part of the CDN cache key, so every accepted spelling is a
+ * separate edge entry for identical bytes; two is enough.
+ */ export function wantsMediaDownload(value) {
+    const raw = Array.isArray(value) ? value[0] : value;
+    const normalized = String(raw != null ? raw : '').toLowerCase();
+    return normalized === '1' || normalized === 'true';
+}
+/**
+ * Whether `?poster=1` was asked for (AGL-2743).
+ *
+ * Deliberately the same two-spelling rule as {@link wantsMediaDownload},
+ * and for the same reason rather than out of symmetry: the query string is
+ * part of the CDN cache key, so every accepted spelling of "yes" is another
+ * edge entry holding identical bytes. A poster is the response most likely
+ * to be requested at volume from a grid, which makes cache-key discipline
+ * worth more here than anywhere else on the route.
+ */ export function mediaCdnWantsPoster(value) {
+    return wantsMediaDownload(value);
+}
+/**
+ * The container every browser has decoded for a decade, and the encoding the
+ * producer always emits (`720p`, H.264 High in MP4). WebM/VP9 is opt-in there
+ * and is the only entry a client has to earn.
+ */ const MEDIA_CDN_BASELINE_RENDITION_TYPE = 'video/mp4';
+/**
+ * What a client said about media types, split into the two answers that
+ * matter: types it NAMED, and types it explicitly refused with `q=0`.
+ *
+ * Wildcards are deliberately dropped rather than expanded. `video/*` and
+ * `*\/*` are a client declining to answer the question, and the browsers that
+ * matter mostly decline: Chrome and Safari send `*\/*` for a media element's
+ * request and only Firefox enumerates containers. Reading `*\/*` as "every
+ * container decodes here" is how a Safari 13 gets handed a WebM.
+ */ function parseAcceptedTypes(header) {
+    const raw = Array.isArray(header) ? header[0] : header;
+    const named = new Set();
+    const refused = new Set();
+    for (const part of String(raw != null ? raw : '').split(',')){
+        const [type, ...params] = part.split(';');
+        const name = type.trim().toLowerCase();
+        if (!name || name.includes('*')) continue;
+        // `q=0` is a refusal in RFC 9110, so it removes an entry rather than
+        // selecting it — the one case where naming a type argues against it.
+        const isRefusal = params.some((param)=>/^\s*q\s*=/i.test(param) && Number(param.split('=')[1]) === 0);
+        if (isRefusal) refused.add(name);
+        else named.add(name);
+    }
+    return {
+        named,
+        refused
+    };
+}
+/**
+ * Which rendition `?r=auto` resolves to, or undefined for "serve the master"
+ * (AGL-2753).
+ *
+ * ## Why the CDN chooses at all
+ *
+ * Because it is the only participant holding the media document when the
+ * bytes are asked for. A page cannot name a rendition — the encodings are
+ * produced out of band, after the placement, and the page is ISR-cached HTML
+ * that neither regenerates when one lands nor varies on a visitor's `Accept`.
+ * The composition does read a placed film's document for its length and
+ * shape (AGL-2807), but that answer is frozen into the cached page. The
+ * alternatives were a node backfill that rewrites published screens nobody
+ * edited, or naming encodings in that same frozen page. This costs neither:
+ * the document is already in hand on this request.
+ *
+ * ## Why the stored order is not simply obeyed
+ *
+ * The producer writes most-efficient-codec first, which is the right order for
+ * `<source>` elements — there the BROWSER picks, using what it actually knows
+ * about its own decoders. A single negotiated URL has no such luxury, so
+ * taking the head of the list would hand a WebM to anything that could not
+ * decode one and turn a saving into a black player.
+ *
+ * So an entry is selected on an EXPLICIT type match, and everything else falls
+ * to the MP4 baseline the producer always emits. A client that names
+ * `video/webm` gets the 30%-smaller file; a client that says `*\/*` gets the
+ * universally decodable one; a client that refused every candidate gets the
+ * master. Every outcome is a video that plays.
+ *
+ * ## Why negotiating here is safe under a cache
+ *
+ * A rendition response is `video/*`, so `mediaCdnEdgeCacheable` is false and
+ * it is served `private` (AGL-1515) — no shared cache stores it, which is the
+ * invariant `serve-media-cdn.video.spec.ts` pins. The only cache that can hold
+ * one is the requesting browser's own, and a browser's `Accept` for media does
+ * not change between the first request and the Range requests that follow it.
+ * That matters more than it looks: negotiation on a RANGEABLE resource that
+ * could flip mid-playback would stitch byte ranges from two different files
+ * together, which is the AGL-1515 corruption reached by a new road.
+ */ export function selectAutoRendition(renditions, acceptHeader) {
+    var _renditions_find;
+    if (renditions.length === 0) return undefined;
+    const { named, refused } = parseAcceptedTypes(acceptHeader);
+    const typeOf = (entry)=>entry.contentType.toLowerCase();
+    return (_renditions_find = renditions.find((entry)=>named.has(typeOf(entry)))) != null ? _renditions_find : renditions.find((entry)=>typeOf(entry) === MEDIA_CDN_BASELINE_RENDITION_TYPE && !refused.has(MEDIA_CDN_BASELINE_RENDITION_TYPE));
+}
+/** Anything that cannot appear literally in an HTTP field-value. */ const NON_ASCII_FIELD_VALUE = /[^\x20-\x7e]/g;
+/** ...and what additionally cannot appear inside a quoted-string. */ const NOT_QUOTED_STRING_SAFE = /["\\]/g;
+/**
+ * The download name for an asset: the stored `fileName`, reduced to its
+ * basename, falling back to the media id (the URL is id-keyed and
+ * extensionless, so without a name a "save as" lands as a nameless blob).
+ */ export function mediaDownloadName(fileName, mediaId) {
+    var _raw_split_pop;
+    const raw = String(fileName != null ? fileName : '').trim();
+    // A stored name can carry a path from whatever uploaded it; only the last
+    // segment is a filename, and `..` must never reach a client's save dialog.
+    const base = (_raw_split_pop = raw.split(/[\\/]/).pop()) != null ? _raw_split_pop : '';
+    // Cap by CODE POINT so a truncation can't split a surrogate pair into a
+    // lone half, which is exactly the kind of thing that later throws in a
+    // header encoder.
+    return Array.from(base).slice(0, 200).join('') || mediaId;
+}
+/**
+ * A `Content-Disposition` value for `name` (AGL-1411).
+ *
+ * A filename is attacker-adjacent data — it is whatever the uploader typed —
+ * and it is being pasted into a header, so a quote or a CRLF in it is a
+ * header-injection vector. The old code stripped `["\\\r\n]` and left
+ * everything else, which is safe against injection but silently mangles the
+ * name and passes non-ASCII through raw: a byte above 0x7e in a header is
+ * either mojibake at the client or, on a stricter encoder than ours, a
+ * throw. So both forms of RFC 6266 §4.1 are emitted:
+ *
+ * - `filename="…"` — ASCII only, every unrepresentable character replaced
+ *   (not dropped) so the extension and the shape of the name survive. This
+ *   is the fallback, and it always exists.
+ * - `filename*=UTF-8''…` — RFC 8187 percent-encoding of the real name, added
+ *   only when the ASCII form actually lost something. Every current browser
+ *   prefers it, so a non-ASCII name arrives intact.
+ */ export function mediaContentDisposition(name, options) {
+    const type = options.download ? 'attachment' : 'inline';
+    const ascii = name.replace(NON_ASCII_FIELD_VALUE, '_').replace(NOT_QUOTED_STRING_SAFE, '_');
+    const header = `${type}; filename="${ascii}"`;
+    if (ascii === name) return header;
+    // `encodeURIComponent` leaves `!'()*` alone, and `'`, `(`, `)` and `*` are
+    // not `attr-char` (RFC 8187 §3.2.1) — a bare `'` in particular would be
+    // read as the charset/language delimiter. Encode them too.
+    const encoded = encodeURIComponent(name).replace(/['()*]/g, (character)=>`%${character.charCodeAt(0).toString(16).toUpperCase().padStart(2, '0')}`);
+    return `${header}; filename*=UTF-8''${encoded}`;
+}
+export function parseMediaCdnRange(header, size) {
+    if (typeof header !== 'string') return null;
+    const unit = /^bytes=(.*)$/i.exec(header.trim());
+    if (!unit) return null;
+    const specs = unit[1].split(',');
+    if (specs.length !== 1) return null;
+    const spec = /^(\d*)-(\d*)$/.exec(specs[0].trim());
+    if (!spec) return null;
+    const [, startRaw, endRaw] = spec;
+    if (!startRaw && !endRaw) return null;
+    if (!startRaw) {
+        // Suffix form `bytes=-N`: the LAST N bytes. `-0` names zero bytes and a
+        // 200 would over-answer it, so it is the one suffix that 416s.
+        const suffix = Number(endRaw);
+        if (!Number.isSafeInteger(suffix)) return null;
+        if (suffix === 0 || size === 0) return 'unsatisfiable';
+        return {
+            start: Math.max(0, size - suffix),
+            end: size - 1
+        };
+    }
+    const start = Number(startRaw);
+    if (!Number.isSafeInteger(start)) return null;
+    const end = endRaw ? Number(endRaw) : size - 1;
+    if (!Number.isSafeInteger(end)) return null;
+    // `bytes=5-2` is a syntax error, not an unsatisfiable range — ignore it.
+    if (endRaw && end < start) return null;
+    if (start >= size) return 'unsatisfiable';
+    return {
+        start,
+        end: Math.min(end, size - 1)
+    };
+}
+/**
+ * Whether a delivery ended early only because its client stopped reading
+ * (AGL-2810).
+ *
+ * A `<video>` element abandons its opening request once it has buffered
+ * enough, and abandons another on every seek, so this is the ordinary way a
+ * streamed response ends early — and it is not a delivery failure, so it is
+ * neither logged nor answered.
+ *
+ * `pipeline` reports it as a premature close, and reports a Storage read that
+ * closed early the same way. The response tells them apart: a client that
+ * canceled destroyed it without an error, while a failed read makes
+ * `pipeline` destroy it WITH the read's error.
+ */ function mediaCdnClientWentAway(error, res) {
+    return (error == null ? void 0 : error.code) === 'ERR_STREAM_PREMATURE_CLOSE' && !res.errored;
+}
+/**
+ * The headers that describe the file, removed from an answer that will not
+ * carry it.
+ *
+ * A failure found after the representation was chosen would otherwise go out
+ * under the file's own headers: a `Content-Length` of the whole object on a
+ * short JSON body leaves the client waiting for bytes that never come, a
+ * `video/mp4` type misdescribes the body outright, and the validator would
+ * attach the file's identity to an error. `no-store` because the answer is
+ * about this request, not the URL.
+ */ function clearMediaCdnRepresentation(res) {
+    for (const header of [
+        'Content-Type',
+        'Content-Length',
+        'Content-Range',
+        'Content-Disposition',
+        'Accept-Ranges',
+        'ETag'
+    ]){
+        res.removeHeader(header);
+    }
+    res.setHeader('Cache-Control', 'no-store');
+}
+/**
+ * CDN media delivery (AGL-175 / AGL-829). Two URL shapes resolve the same
+ * asset by `mediaId`, so delivery never depends on the object's storage
+ * location (folder moves don't change the URL):
+ *
+ * - **Stable** `/api/media/cdn/[scope]/[mediaId]` — always serves the
+ *   asset's CURRENT bytes, so it survives a **replace** too. Revalidated
+ *   with an ETag (the content hash) + `stale-while-revalidate`, so a
+ *   replaced asset propagates without ever breaking references. This is
+ *   the URL the console hands out.
+ * - **Immutable** `/api/media/cdn/[scope]/[mediaId]/[contentHash]` —
+ *   year-long `immutable` cache; bytes are served only while the hash
+ *   matches the current content, and a stale hash 302s to the stable URL
+ *   (AGL-2685). No renderer names this form (AGL-2798): an edge or a browser
+ *   holding an immutable response never asks again, so a replace could not
+ *   reach a page that did. It is answered for the URLs already handed out.
+ *
+ * `?w=[width]` selects a generated WebP variant. `?download=1` swaps the
+ * `Content-Disposition` from `inline` to `attachment` (AGL-1411) — the press
+ * kit hands out links that must SAVE rather than open a tab. Both are read
+ * only after every access gate, so neither can widen what is served; both
+ * are part of the CDN cache key, so neither variant can poison the other.
+ * The same handler mounts in both the tenant and console apps; raw storage
+ * URLs already embedded in screens keep working unchanged.
+ *
+ * Single byte-range requests are honored with a 206 (AGL-1442 S4) — see
+ * {@link parseMediaCdnRange} and the block below `Accept-Ranges` for the
+ * exact semantics. This is the capability whose absence kept video on raw
+ * `firebasestorage.googleapis.com` URLs (S8): a `<video>` seek is a Range
+ * request, and a server that ignores it forces the player to re-download
+ * the whole file.
+ *
+ * The body streams (AGL-2810): each chunk leaves as Storage produces it, so no
+ * file is held whole in function memory. A GET that will read the file is
+ * first counted against its caller (AGL-2812); see
+ * {@link mediaCdnRateLimitRefusal}.
+ */ export async function serveMediaCdn(req, res) {
+    var _ref, _ref1;
+    // AGL-1474, set FIRST so no exit from this handler can be reached without
+    // it — including the refusals, the 304 and the 500. Upgraded below to the
+    // sandboxing form once the served content type is known. `nosniff` is
+    // repeated here rather than left to the app config's `/(.*)` header: the
+    // policy above keys off the declared type, so this response has to carry
+    // the header that makes the declared type binding, on its own.
+    res.setHeader('Content-Security-Policy', MEDIA_CDN_BASE_CSP);
+    res.setHeader('X-Content-Type-Options', 'nosniff');
+    if (req.method !== 'GET' && req.method !== 'HEAD') {
+        res.setHeader('Allow', 'GET, HEAD');
+        res.status(405).end();
+        return;
+    }
+    const path = Array.isArray(req.query['path']) ? req.query['path'] : [];
+    const [scopeSegment, mediaId, hash] = path.map((value)=>String(value != null ? value : ''));
+    const scope = parseMediaCdnScope(scopeSegment);
+    const isOrg = (_ref = scope == null ? void 0 : scope.isOrg) != null ? _ref : false;
+    const scopeId = (_ref1 = scope == null ? void 0 : scope.scopeId) != null ? _ref1 : '';
+    // 3 segments = the immutable content-hashed URL; 2 = the stable URL.
+    const hashed = path.length === 3;
+    if (!scope || path.length !== 2 && path.length !== 3 || !SEGMENT.test(mediaId) || hashed && !SEGMENT.test(hash)) {
+        res.status(400).json({
+            error: 'Bad media path'
+        });
+        return;
+    }
+    try {
+        var _snapshot_get, _snapshot_get1, _req_query_w, _snapshot_get2, _ref2, _ref3, _metadata_contentType, _metadata_size, _metadata_size1;
+        var _req_socket;
+        const firestore = firebaseAdmin.app().firestore();
+        const snapshot = await firestore.collection(isOrg ? 'orgs' : 'hosts').doc(scopeId).collection('media').doc(mediaId).get();
+        const currentHash = String((_snapshot_get = snapshot.get('contentHash')) != null ? _snapshot_get : '');
+        if (!snapshot.exists || snapshot.get('deletedAt')) {
+            res.setHeader('Cache-Control', 'public, max-age=60');
+            res.status(404).json({
+                error: 'Not found'
+            });
+            return;
+        }
+        // Delivery gate — scope lockdown (AGL-1520) and asset quarantine
+        // (AGL-1512). See mediaCdnServeBlock for the reason matrix, the
+        // read-cost accounting and the staleness bound. Three shape decisions,
+        // argued, and all three apply to BOTH refusal kinds:
+        //
+        // **Before the ETag/304 exit**, necessarily: a browser revalidating its
+        // 60s copy during a lock or a quarantine must be refused, not handed a
+        // 304 that renews the copy for another minute.
+        //
+        // **410, not 423, and identical for both kinds.** The 423 body is the
+        // AGL-1506 discipline for authenticated API consumers who deserve
+        // "suspended: billing"; this response answers anonymous `<img>` fetches
+        // nobody parses, and a 423 would confirm to any prober that a lock
+        // exists — which for a security lock is information. It is information
+        // for a quarantine too, and of a worse kind: the existence of a DMCA
+        // notice or a malware finding on a specific file is not something an
+        // anonymous fetcher has standing to learn, and telling quarantine apart
+        // from lockdown on the wire would leak which one it was. So the owning
+        // org learns the reason in the console (`mediaQuarantineNotice`), and
+        // the CDN says only `410 Gone` — neutral, indistinguishable in kind
+        // from a deleted asset, and a hint to well-behaved consumers to drop
+        // the link. (404 would also be neutral, but 410's "permanently gone"
+        // semantics discourage retry loops from embedders.)
+        //
+        // **`no-store`, absolutely** (the AGL-1515 lesson): the refusal is a
+        // function of a TTL'd verdict, not of the URL — a cached refusal would
+        // weld the asset's URL identity to "gone" past the unlock, and edge
+        // entries have no per-asset purge. The 60s negative window the 404s use
+        // is not acceptable here either. For quarantine that argument is
+        // strictly stronger than for lockdown: REVERSIBILITY is the whole
+        // reason quarantine exists instead of deletion, so a cached 410 that
+        // outlived the lift would defeat the feature's only advantage over the
+        // irreversible option. The refusal is also nearly free to re-serve —
+        // the verdict is one Firestore read per process per 15s for the entire
+        // deny list, and the body is a few bytes with no Storage read — so
+        // there is no saving to weigh against it. CSP + nosniff are already on
+        // the response (set first, before any exit).
+        const blockedBy = await mediaCdnServeBlock(scope, {
+            // The strong digest is read for the quarantine key ONLY. It is
+            // deliberately not the ETag and not the immutable URL segment
+            // (AGL-1614): changing either of those would change live URLs and
+            // cache validators for every existing asset, and this change must be
+            // additive to the point of being invisible on the wire.
+            contentSha256: String((_snapshot_get1 = snapshot.get('contentSha256')) != null ? _snapshot_get1 : ''),
+            contentHash: currentHash,
+            scopeSegment,
+            mediaId
+        });
+        if (blockedBy) {
+            res.setHeader('Cache-Control', 'no-store');
+            res.status(410).json({
+                error: 'Gone'
+            });
+            return;
+        }
+        // Scope check (AGL-1043). The bare `org:` form serves ORG-WIDE assets
+        // only; a restricted asset must be requested through the form that
+        // names the site using it, which is when AGL-1045's confirmation already
+        // warns which pages are affected.
+        //
+        // An asset carrying no `visibleTo` is refused here rather than treated as
+        // org-wide: absent is "nobody has said who may see this", not "everybody"
+        // (`app-utils/scope-tokens`). The scope backfill stamps such documents and
+        // the weekly drift detector reports the ones it has not reached, so the
+        // repair is a stamp rather than a wider read.
+        //
+        // 404 rather than 403: whether a restricted asset exists is itself
+        // something the caller has no standing to learn. Short max-age so
+        // re-widening a scope propagates quickly instead of being pinned by a
+        // long-lived negative cache entry.
+        const refusal = mediaCdnScopeRefusal(scope, snapshot.get('visibleTo'));
+        if (refusal) {
+            /**
+       * A `restricted` refusal is the gate WORKING and is deliberately
+       * silent: it is the ordinary consequence of an internal asset's URL
+       * being shared outside the site it belongs to, it can be provoked by
+       * anyone who can guess a scope segment, and a log line per anonymous
+       * request would make this route amplify traffic into the drain.
+       *
+       * The other two cannot be provoked from outside — they are properties
+       * of the document, not of the request — and they are the ones nothing
+       * else says out loud. An asset undeliverable under every URL form
+       * shows up as an image that stopped rendering on a live site, and
+       * until the weekly drift detector runs the only trace it leaves is a
+       * 404 indistinguishable from a deleted asset. Naming it here is what
+       * makes the next occurrence readable from the logs.
+       */ if (refusal !== 'restricted') {
+                console.error('[media-cdn] asset has no site it can be served to', JSON.stringify({
+                    scopeId,
+                    mediaId,
+                    refusal
+                }));
+            }
+            res.setHeader('Cache-Control', 'public, max-age=60');
+            res.status(404).json({
+                error: 'Not found'
+            });
+            return;
+        }
+        /**
+     * Private assets (AGL-1051) leave the public model entirely: no
+     * `cdnPath`, and no bytes without an unexpired signature. This is a
+     * different question from the scope check above — that one asks which
+     * SITE may use the asset, this one asks whether the public may fetch
+     * it at all.
+     *
+     * `no-store`, not a short max-age. Every other response here is safe to
+     * cache because it is the same answer for everyone, but a signed
+     * request is per-caller and time-boxed: letting a shared cache keep
+     * either the denial OR the bytes would outlive the signature and hand
+     * the asset to the next requester on the same URL.
+     *
+     * Which is why the header goes through `setCacheControl` from here on
+     * rather than `res.setHeader` — the private case has to win at EVERY
+     * exit, and remembering that at each of six call sites is precisely
+     * the kind of thing that gets missed when a seventh is added. It
+     * already was: the stale-hash 404 below used to overwrite `no-store`
+     * with `public, max-age=60`.
+     */ const isPrivate = snapshot.get('private') === true;
+        const setCacheControl = (value)=>{
+            res.setHeader('Cache-Control', isPrivate ? 'private, no-store' : value);
+        };
+        if (isPrivate) {
+            var _req_query_exp, _req_query_sig;
+            const signed = verifyMediaAccess(scopeSegment, mediaId, {
+                exp: Number((_req_query_exp = req.query['exp']) != null ? _req_query_exp : 0),
+                sig: String((_req_query_sig = req.query['sig']) != null ? _req_query_sig : '')
+            });
+            setCacheControl('private, no-store');
+            if (!signed) {
+                res.status(404).json({
+                    error: 'Not found'
+                });
+                return;
+            }
+        }
+        /**
+     * A stale hash on the immutable form REDIRECTS to the stable URL
+     * (AGL-2685). It used to 404.
+     *
+     * The invariant the 404 protected is intact and is the reason this is a
+     * redirect rather than a body: **no version of this URL ever serves bytes
+     * that are not the ones its hash names.** A stale one now serves a
+     * pointer to the URL that is allowed to change instead of a dead end.
+     *
+     * What the 404 cost was every copy of this URL breaking on the first
+     * **replace** of its asset. With a redirect, a stale URL that reaches
+     * this handler costs one extra hop and self-heals. It does NOT make the
+     * form safe to publish: an edge or a browser already holding the
+     * immutable response answers from its copy and never reaches this line,
+     * which is why no renderer names this form (AGL-2798).
+     *
+     * **302, not 301.** A hash can become current again — a replace reverted
+     * to the previous bytes restores it — and a permanent redirect is exactly
+     * the thing browsers refuse to forget.
+     *
+     * **The stable URL's own cache policy**, not a shorter one. The redirect
+     * is as re-checkable as the resource it points at, and it is the same
+     * answer for every caller, so there is no reason for the edge to hold it
+     * less well than it holds the target. `setCacheControl` still forces
+     * `private, no-store` for a signed asset.
+     *
+     * The query string is REBUILT from the parameters this handler reads
+     * rather than forwarded: `?w=`, `?download=` and the signature pair are
+     * the whole set, they are already validated by the code below, and
+     * echoing arbitrary caller input into a `Location` header is a habit
+     * worth not having. Dropping an unknown parameter costs a cache-key
+     * split and nothing else.
+     */ if (hashed && currentHash !== hash) {
+            setCacheControl(MEDIA_CDN_STABLE_CACHE_CONTROL);
+            res.setHeader('Location', `${MEDIA_CDN_ROUTE}/${scopeSegment}/${mediaId}${mediaCdnForwardedQuery(req.query)}`);
+            res.status(302).end();
+            return;
+        }
+        const width = Number((_req_query_w = req.query['w']) != null ? _req_query_w : 0);
+        const variants = (_snapshot_get2 = snapshot.get('variants')) != null ? _snapshot_get2 : [];
+        /*
+     * WHICH REPRESENTATION OF THIS ASSET (AGL-2743).
+     *
+     * Three derived forms now sit behind one media id — the image variants
+     * `?w=` has selected since AGL-175, a video's poster still, and its
+     * encoded renditions. They are resolved here, together, because they are
+     * mutually exclusive and because every one of them has to reach the ETag,
+     * the cache tier and the object path in agreement. A second lookup later
+     * in the handler is how a poster ends up cached under the master's
+     * validator.
+     *
+     * Precedence is poster, then rendition, then width, and it is total: a
+     * caller sending `?poster=1&r=720p` gets the poster rather than an error,
+     * because the parameters are a REQUEST for a representation and the only
+     * useful answer to an incoherent one is the safest coherent one.
+     *
+     * ## Falling back to the master is right for a WIDTH and wrong for a POSTER
+     *
+     * `?w=` on an asset with no such variant serves the original, and that has
+     * always been safe because both answers are the same KIND of thing: an
+     * image, larger than asked for. A rendition inherits it for the same
+     * reason — an unknown `?r=` serves the master, which is the same video in
+     * more bytes.
+     *
+     * `?poster=1` cannot. The caller asked for a still and the master is a
+     * film, so the fallback would answer a `<video poster>` with 60 MB of
+     * `video/mp4` — a request for 40 KB satisfied with the entire asset,
+     * which is the precise cost this feature exists to remove, delivered by
+     * the feature itself. So a poster that does not exist is a **404**, and
+     * that is the better answer in the browser too: a `<video>` whose
+     * `poster` 404s behaves exactly like a `<video>` with no `poster`, which
+     * is what every video did before AGL-2742. It also lets a renderer emit
+     * the attribute without first reading the document — the property the
+     * fallback was supposed to buy, bought honestly.
+     */ const poster = snapshot.get('poster');
+        const posterVariants = (_ref2 = poster == null ? void 0 : poster.variants) != null ? _ref2 : [];
+        const wantsPoster = mediaCdnWantsPoster(req.query[MEDIA_CDN_POSTER_PARAM]);
+        if (wantsPoster && !poster) {
+            // See above: a still is not a film, so this is the one representation
+            // that must refuse rather than degrade. `no-store` because the answer
+            // is about a DOCUMENT field that a poster backfill can change at any
+            // time, and a cached 404 would outlive the fix.
+            setCacheControl('private, no-store');
+            res.status(404).json({
+                error: 'No poster'
+            });
+            return;
+        }
+        const usePoster = wantsPoster;
+        const usePosterVariant = usePoster && Boolean(width) && posterVariants.includes(width);
+        const renditionParam = req.query[MEDIA_CDN_RENDITION_PARAM];
+        const renditionKey = String(Array.isArray(renditionParam) ? renditionParam[0] : renditionParam != null ? renditionParam : '');
+        /*
+     * `?r=auto` is the form a PAGE emits (AGL-2753), because a page cannot
+     * know which encodings an asset has — they are produced out of band, long
+     * after the placement. `selectAutoRendition` answers from the document
+     * already read above, so serving the encodings costs no extra read
+     * anywhere and a rendition made today reaches a video placed last month.
+     *
+     * An explicit key stays exact and stays supported: the producer's report
+     * and the specs address one encoding by name, and a debugging request for
+     * `?r=720p-vp9` should get that file or the master, never a negotiation.
+     */ const negotiated = !usePoster && renditionKey === MEDIA_CDN_RENDITION_AUTO;
+        const availableRenditions = usePoster ? [] : parseMediaRenditions(snapshot.get('videoRenditions'));
+        const rendition = usePoster ? undefined : negotiated ? selectAutoRendition(availableRenditions, req.headers['accept']) : availableRenditions.find((entry)=>entry.key === renditionKey);
+        if (negotiated) {
+            // Declared for correctness rather than as the thing keeping this safe.
+            // What keeps it safe is `private` (AGL-1515): a video response is never
+            // held by a shared cache, so there is no entry for a second client's
+            // `Accept` to be answered from. This tells the BROWSER's own cache — and
+            // any intermediary that ignored `private` — that the URL alone does not
+            // identify the bytes. Set before the 304 exit below, because a validator
+            // handed out without it would be reused across representations.
+            res.setHeader('Vary', 'Accept');
+        }
+        const useVariant = !usePoster && !rendition && Boolean(width) && variants.includes(width);
+        /**
+     * The ETag's representation tag, and the cache key's conscience.
+     *
+     * A validator is not scoped to a URL in practice — the reasoning the
+     * `-dl` suffix below was added for — so two representations of one asset
+     * that share a validator can be swapped for each other by any cache that
+     * revalidates. Between an image variant and its original that is a wrong
+     * size; between a poster and its video it is a 40 KB still standing in
+     * for a 40 MB film, or the reverse.
+     */ const representation = usePoster ? `-poster${usePosterVariant ? `-w${width}` : ''}` : rendition ? `-r${rendition.key}` : useVariant ? `-w${width}` : '';
+        // Read only here, past every gate — a refusal above returns before the
+        // parameter is ever looked at, so `?download=1` can never be the reason
+        // a response happens (AGL-1411).
+        const download = wantsMediaDownload(req.query['download']);
+        // Stable URL: revalidate against an ETag so a replaced asset is picked
+        // up (a conditional GET returns 304 while the content is unchanged).
+        //
+        // The disposition is part of the ETag for the same reason the variant
+        // width is. The query string is already part of the CDN cache key, so
+        // the two URLs are separate edge entries — but a validator is not scoped
+        // to a URL in practice: a client holding the inline ETag that revalidates
+        // the download URL would be answered 304 and reuse its stored INLINE
+        // headers, and the file would open in a tab anyway. Same bytes, different
+        // representation, so: different validator.
+        const etag = currentHash ? `"${currentHash}${representation}${download ? '-dl' : ''}"` : null;
+        // AGL-1515: which cache tier may hold this response is a function of the
+        // served type — see mediaCdnEdgeCacheable. Decided here from the DOC's
+        // type (a variant serve is always `image/webp`) because the 304 exit
+        // below runs before the Storage metadata read; re-derived from the
+        // authoritative served type once metadata is in hand.
+        const stableCacheControlFor = (type)=>mediaCdnEdgeCacheable(type) ? MEDIA_CDN_STABLE_CACHE_CONTROL : MEDIA_CDN_STABLE_EDGE_BYPASS_CACHE_CONTROL;
+        // A poster is `image/webp` and therefore edge-cacheable through the rule
+        // that already exists — which is the whole delivery argument for it
+        // (AGL-2743). `mediaCdnEdgeCacheable` is untouched: nothing here relaxes
+        // AGL-1515, because a poster genuinely IS an image and no player ranges
+        // into a `<video poster>`. A RENDITION reports its own `video/*` type and
+        // stays origin-only, deliberately — a small fixed-size rendition is
+        // exactly the size class Vercel's 10 MB cap admits, so edge-caching one
+        // would maximize exposure to the very hybrid AGL-1515 recorded rather
+        // than avoid it.
+        const docServedType = usePoster || useVariant ? 'image/webp' : rendition ? rendition.contentType : snapshot.get('contentType');
+        /*
+     * VIDEO FROM THE DELIVERY PROVIDER (AGL-2824).
+     *
+     * Every gate above has run: the scope, lockdown and quarantine, the
+     * private signature and the stale-pin redirect. With the representation
+     * chosen, a video whose current copy sits at the configured delivery
+     * provider is answered with a `302` to a short-lived signed URL there, and
+     * the provider serves the bytes and their ranges. `mediaDeliveryRedirect`
+     * says null for everything else — an image, a poster, no copy of this
+     * representation made from the current bytes, the release flag off for
+     * the owning org — and the request carries on below exactly as before.
+     *
+     * With no provider configured to deliver, nothing here runs: the check is
+     * synchronous and reads nothing.
+     *
+     * A download stays here, because its disposition is this route's to set.
+     * The redirect is decided before the ETag and the 304: it names a URL
+     * that expires, so it carries no validator and `private, no-store`, and a
+     * private asset's URL expires no later than the signature that reached
+     * it. It is not counted against the caller's delivery budget, which
+     * guards the bytes this route sends; a redirect sends none.
+     */ const deliveryProvider = usePoster || useVariant || download ? null : mediaDeliveryProvider('deliver');
+        if (deliveryProvider) {
+            var _scope_contextHostId;
+            const delivery = await mediaDeliveryRedirect(_extends({
+                provider: deliveryProvider,
+                asset: {
+                    collection: isOrg ? 'orgs' : 'hosts',
+                    scopeId,
+                    mediaId
+                },
+                document: snapshot,
+                rendition,
+                servedType: docServedType,
+                claims: {
+                    scope: scopeSegment,
+                    mediaId,
+                    hostId: isOrg ? (_scope_contextHostId = scope.contextHostId) != null ? _scope_contextHostId : null : scopeId
+                },
+                orgId: ()=>mediaDeliveryOrgIdFor(isOrg ? 'orgs' : 'hosts', scopeId)
+            }, isPrivate ? {
+                notAfterMs: Number(req.query['exp'])
+            } : {})).catch((error)=>{
+                // The provider is an alternative to the path below, never a reason
+                // for this request to fail.
+                console.error('[media-cdn] delivery redirect failed', scopeSegment, mediaId, error);
+                return null;
+            });
+            if (delivery) {
+                res.setHeader('Cache-Control', 'private, no-store');
+                res.setHeader('Location', delivery.location);
+                // A play starts here, so it is counted here. `redirects` says how many
+                // of the serves left through the provider; the bytes are the
+                // provider's to measure, because none leave from this route.
+                if (req.method === 'GET') {
+                    const day = new Date().toISOString().slice(0, 10);
+                    void firestore.collection(isOrg ? 'orgs' : 'hosts').doc(scopeId).collection('analytics').doc(day).set({
+                        expiresAt: analyticsDayExpiresAt(day),
+                        media: {
+                            [mediaId]: {
+                                serves: firebaseAdmin.firestore.FieldValue.increment(1),
+                                redirects: firebaseAdmin.firestore.FieldValue.increment(1)
+                            }
+                        }
+                    }, {
+                        merge: true
+                    }).catch(()=>undefined);
+                }
+                res.status(302).end();
+                return;
+            }
+        }
+        if (!hashed) {
+            setCacheControl(stableCacheControlFor(docServedType));
+            if (etag) res.setHeader('ETag', etag);
+            if (etag && req.headers['if-none-match'] === etag) {
+                res.status(304).end();
+                return;
+            }
+        }
+        const bucket = firebaseAdmin.app().storage().bucket(process.env['NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET']);
+        // Real folders: the doc records its object path; legacy assets fall
+        // back to the flat layout.
+        //
+        // The recorded path is CLIENT DATA and this is an ADMIN-SDK bucket read,
+        // which the Storage rules do not constrain — so it is honoured only when
+        // it is genuinely inside this scope's media prefix (AGL-1881). Without
+        // that check a host or org editor could point their own media document at
+        // any key in the shared bucket and have this route stream it to an
+        // anonymous caller behind a `s-maxage=3600` edge-cached URL, including the
+        // fixed `adminAudit-archive/` and `erasures/` retention prefixes.
+        const basePath = mediaStoragePathInScope({
+            storagePath: snapshot.get('storagePath'),
+            base: `${isOrg ? 'orgs' : 'hosts'}/${scopeId}`,
+            mediaId,
+            onRefused: (candidate)=>{
+                console.error('[media-cdn] out-of-scope storagePath refused', JSON.stringify({
+                    scopeId,
+                    mediaId,
+                    candidate
+                }));
+            }
+        });
+        // Every derived path is built from `basePath`, which `mediaStoragePathInScope`
+        // has already proved is inside this scope's prefix (AGL-1881), plus a
+        // suffix whose grammar admits no separator: the widths are numbers,
+        // and `parseMediaRendition` refuses a key or extension that is not
+        // `[a-z0-9-]`. So no representation can address an object the master
+        // could not.
+        const objectPath = usePoster ? usePosterVariant ? `${basePath}${MEDIA_POSTER_OBJECT_SUFFIX}__w${width}.webp` : mediaPosterObjectPath(basePath) : rendition ? mediaRenditionObjectPath(basePath, rendition) : useVariant ? `${basePath}__w${width}.webp` : basePath;
+        const file = bucket.file(objectPath);
+        // The caller's count (AGL-2812), asked here and nowhere earlier: past every
+        // gate and the 304 exit, where the Storage reads begin. It starts before the
+        // metadata read and is awaited after it, so the two run together. It never
+        // rejects, and answers `null` whenever it could not count.
+        const callerCount = req.method === 'GET' ? mediaCdnRateLimitRefusal({
+            headers: req.headers,
+            remoteAddress: (_req_socket = req.socket) == null ? void 0 : _req_socket.remoteAddress,
+            rateClass: mediaCdnEdgeCacheable(docServedType) ? 'image' : 'non-image'
+        }) : null;
+        const [metadata] = await file.getMetadata().catch(()=>[
+                null
+            ]);
+        if (!metadata) {
+            res.status(404).json({
+                error: 'Not found'
+            });
+            return;
+        }
+        const refused = await callerCount;
+        if (refused) {
+            // The file's validator and cache policy are already set. A refusal is
+            // about this caller rather than the URL, so no cache may keep it: an
+            // edge holding a 429 would refuse every visitor to that image for an
+            // hour.
+            clearMediaCdnRepresentation(res);
+            res.setHeader('Retry-After', String(refused.retryAfterSeconds));
+            res.status(429).json({
+                error: 'Too many requests'
+            });
+            return;
+        }
+        const servedType = usePoster || useVariant ? 'image/webp' : rendition ? rendition.contentType : String((_ref3 = (_metadata_contentType = metadata.contentType) != null ? _metadata_contentType : snapshot.get('contentType')) != null ? _ref3 : 'application/octet-stream');
+        res.setHeader('Content-Type', servedType);
+        // AGL-1474: an SVG (or anything else a browser treats as a document) gets
+        // the sandboxing policy. Everything else keeps the base one set above —
+        // `sandbox` is withheld from raster and PDF responses on purpose, since it
+        // would change how a directly-opened PDF is handled for no security gain.
+        res.setHeader('Content-Security-Policy', mediaCdnContentSecurityPolicy(servedType));
+        // Range support (AGL-1442 S4) — this is what lets video ride this route
+        // at all: a `<video>` seek is a Range request, and before S4 the raw
+        // storage URL was the only server that would answer one.
+        //
+        // `Accept-Ranges` is advertised unconditionally because it is now TRUE
+        // unconditionally — the handler honors a single byte-range for every
+        // asset class. Limiting it to "types that benefit" would only teach a
+        // PDF viewer or a download manager not to ask for something we would
+        // happily serve, and the header is not part of any cache key.
+        //
+        // Caching shape (AGL-1515): S4 read Vercel's cacheable-response
+        // criteria ("Request doesn't contain Range header") as "a cached full
+        // body and a function-served partial can never cross". Production
+        // falsified that: the criteria govern what the edge STORES, not what it
+        // SERVES, and the edge answers a ranged request from an existing cached
+        // full-body 200 as a 200 + Content-Range + sliced-body hybrid. The fix
+        // is upstream of this line — every type a ranged consumer actually uses
+        // is served `private` (see mediaCdnEdgeCacheable), so the entry the
+        // edge would mangle never exists and every ranged request reaches this
+        // function for a real 206. In the browser the 206 rides the same
+        // Cache-Control as its URL class: a 206 under a STRONG validator is
+        // exactly what lets a player reuse the segments it already fetched.
+        res.setHeader('Accept-Ranges', 'bytes');
+        // The authoritative tier decision, now that the served type is known
+        // from Storage metadata rather than inferred from the doc. Overwrites
+        // the header set before the 304 exit iff the two disagree — and the
+        // BODY-serving response is the one the edge could store, so this one
+        // must win.
+        if (!hashed) setCacheControl(stableCacheControlFor(servedType));
+        const size = Number((_metadata_size = metadata.size) != null ? _metadata_size : NaN);
+        // Range applies to GET only (RFC 9110 §14.2); a HEAD answers the full
+        // representation's metadata. And with no known size there is no honest
+        // `Content-Range` to write, so the header is ignored and the full body
+        // served — the degradation every unrecognised shape shares.
+        const parsed = req.method === 'GET' && Number.isFinite(size) && size >= 0 ? parseMediaCdnRange(req.headers['range'], size) : null;
+        // `If-Range`: the client is saying "this range is against version X; if
+        // you hold anything else, send me the whole file". Honoring the range on
+        // a mismatch is how a stale player splices two versions of a video into
+        // one stream — so anything but an exact match with the CURRENT strong
+        // validator (including a date form, and including the no-hash legacy
+        // shape that has no validator at all) collapses to a full 200.
+        const ifRange = req.headers['if-range'];
+        const range = parsed !== null && typeof ifRange === 'string' && ifRange !== etag ? null : parsed;
+        if (range === 'unsatisfiable') {
+            // The refusal is a function of the REQUEST header, not the URL, and
+            // shared caches key on the URL — no cache may keep it.
+            setCacheControl('private, no-store');
+            res.setHeader('Content-Range', `bytes */${size}`);
+            res.status(416).end();
+            return;
+        }
+        const partial = range !== null && typeof range === 'object';
+        const servedBytes = partial ? range.end - range.start + 1 : Number((_metadata_size1 = metadata.size) != null ? _metadata_size1 : 0);
+        if (partial) {
+            res.setHeader('Content-Range', `bytes ${range.start}-${range.end}/${size}`);
+            res.setHeader('Content-Length', String(servedBytes));
+        } else if (metadata.size) {
+            res.setHeader('Content-Length', String(metadata.size));
+        }
+        // Give downloads a real filename+extension (AGL-834): the URL is
+        // mediaId-keyed and extensionless, so without this a "save image" lands
+        // as a name-less blob. `?download=1` makes it an actual download rather
+        // than a tab (AGL-1411).
+        res.setHeader('Content-Disposition', mediaContentDisposition(mediaDownloadName(snapshot.get('fileName'), mediaId), // `?download=1` can force a download; nothing can force an INLINE
+        // render of a type that has no inline use here.
+        {
+            download: download || !servesInline(servedType)
+        }));
+        // `immutable` for a year is the strongest possible caching, and on a
+        // private asset it would be a permanent public copy of a file whose
+        // whole point is that it expires (AGL-1051) — `setCacheControl` holds
+        // that line. The year stays browser-only for non-image types
+        // (AGL-1515): the URL still changes with the bytes, but the edge must
+        // hold no full body it could slice.
+        if (hashed) {
+            setCacheControl(mediaCdnEdgeCacheable(servedType) ? MEDIA_CDN_IMMUTABLE_CACHE_CONTROL : MEDIA_CDN_IMMUTABLE_EDGE_BYPASS_CACHE_CONTROL);
+        }
+        // HEAD returns here, before the delivery counter below (AGL-2811). It
+        // carries a GET's headers and no body, and `servedBytes` is the whole
+        // object for any request without a range. `serves` and `bytes` count
+        // representations that left, which is also why the 304 and 416 exits
+        // above return before this point.
+        if (req.method === 'HEAD') {
+            res.status(200).end();
+            return;
+        }
+        // Delivery volume (AGL-176): per-asset serves/bytes on the AGL-82
+        // analytics day-doc, fire-and-forget. Only cache MISSES reach this
+        // code — edge-cached responses aren't counted, so these are origin
+        // serves, not user-facing totals (billing accuracy is AGL-41's job).
+        // Hot-doc note: a single day-doc caps at ~1 write/sec sustained;
+        // acceptable at current traffic, shard or sample if an asset gets hot.
+        //
+        // Written before the first byte, so `bytes` is what this request asked
+        // the origin to send. A client that abandons the stream receives less;
+        // the figure is the ceiling on what left, not a count of what arrived.
+        const day = new Date().toISOString().slice(0, 10);
+        void firestore.collection(isOrg ? 'orgs' : 'hosts').doc(scopeId).collection('analytics').doc(day).set({
+            // Retention (AGL-1844): every writer of a day doc stamps the
+            // day-anchored expiry the TTL policy sweeps on.
+            expiresAt: analyticsDayExpiresAt(day),
+            media: {
+                [mediaId]: {
+                    serves: firebaseAdmin.firestore.FieldValue.increment(1),
+                    // The bytes that actually leave, not the object's size — a
+                    // seek in a 200 MB video is a few MB of egress, and counting
+                    // the full object per range would overstate delivery by the
+                    // number of seeks (AGL-1442 S4).
+                    bytes: firebaseAdmin.firestore.FieldValue.increment(servedBytes)
+                }
+            }
+        }, {
+            merge: true
+        }).catch(()=>undefined);
+        if (partial) res.status(206);
+        // `start`/`end` are inclusive in `createReadStream`, matching the parsed
+        // range — GCS is asked for exactly the requested bytes and nothing is
+        // over-read from Storage on a partial serve.
+        //
+        // The response streams (AGL-2810): each chunk leaves as Storage produces
+        // it, and the next is read only once the client has taken the last, so a
+        // file is never held in function memory whatever its size. `pipeline`
+        // rather than `pipe` because streaming needs teardown in both directions,
+        // which `pipe` does not give — a failed Storage read must fail the
+        // response, and a client that stops reading must stop the Storage read.
+        await pipeline(file.createReadStream(partial ? {
+            start: range.start,
+            end: range.end
+        } : {}), res);
+    } catch (error) {
+        if (mediaCdnClientWentAway(error, res)) return;
+        console.error('serveMediaCdn failed', scopeSegment, mediaId, error);
+        if (!res.headersSent) {
+            clearMediaCdnRepresentation(res);
+            res.status(500).json({
+                error: 'Delivery failed'
+            });
+        } else {
+            // The status line has already left, so the body is the only place the
+            // failure can surface. A destroyed response is a broken transfer to the
+            // client; ending it would pass a truncated file off as a whole one.
+            res.destroy(error instanceof Error ? error : new Error(String(error)));
+        }
+    }
+}
+
+//# sourceMappingURL=serve-media-cdn.js.map