@aglyn/tenant-data-admin 1.0.0-beta.221 → 1.0.0-beta.223

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

@@ -15,18 +15,23 @@ import { _ as _extends } from "@swc/helpers/_/_extends";
  * 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, isSecurityClassLockdownReason, mediaPosterObjectPath, mediaRenditionObjectPath, normalizeHostLockdown, normalizeOrgLockdown, parseMediaRenditions } from "@aglyn/aglyn/server";
+import { BANDWIDTH_CAP_RETRY_AFTER_SECONDS, bandwidthCapApplies, bandwidthCapEngaged, bandwidthCeilingDegradesHost, bandwidthCeilingMonthKey, isLockdownActive, MEDIA_BANDWIDTH_DAY_FIELD, MEDIA_CDN_POSTER_PARAM, MEDIA_CDN_RENDITION_AUTO, MEDIA_CDN_RENDITION_PARAM, MEDIA_CDN_ROUTE, MEDIA_CDN_VERSION_PARAM, MEDIA_POSTER_OBJECT_SUFFIX, MEDIA_VARIANT_ENCODER_VERSION, MEDIA_VARIANT_ENCODER_VERSION_FIELD, isSecurityClassLockdownReason, mediaDisplayObjectPath, mediaPosterObjectPath, mediaVariantEncoderVersionOf, mediaRenditionObjectPath, normalizeHostLockdown, normalizeOrgLockdown, parseMediaCdnVersionToken, 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 { parseSiteIconSpec, SITE_ICON_BACKGROUND_PARAM, SITE_ICON_PARAM, SITE_ICON_VERSION_PARAM } from "@aglyn/aglyn/app-utils/site-icon-set";
 import { analyticsDayExpiresAt } from "./analytics-retention.js";
 import { firebaseAdmin } from "./firebase-admin.js";
+import { recordMediaServe } from "./media-serve-count.js";
 import { getPlatformLockdown } from "./lockdown.js";
+import { engageMediaBandwidthCap, mediaBandwidthEvaluationDue } from "./media-bandwidth-cap.js";
 import { mediaCdnRateLimitRefusal } from "./media-cdn-rate-limit.js";
 import { mediaDeliveryOrgIdFor, mediaDeliveryRedirect } from "./media-delivery.js";
+import { mediaDeliveryCopiesStale, regenerateMediaDeliveryCopies } from "./media-delivery-regeneration.js";
 import { getMediaQuarantine } from "./media-quarantine.js";
 import { verifyMediaAccess } from "./media-signing.js";
 import { mediaStoragePathInScope } from "./media-storage-path.js";
+import { serveMediaCdnIcon } from "./media-cdn-icon.js";
 /**
  * Variant widths generated at upload (AGL-175).
  *
@@ -67,13 +72,19 @@ const SEGMENT = MEDIA_CDN_SEGMENT;
     // 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).
+    // `icon`, `bg` and `v` for the same reason: a site icon (AGL-3484) behind a
+    // stale content pin must stay the icon, not become the full-size original.
     for (const key of [
         'w',
         'poster',
         'r',
         'download',
+        SITE_ICON_PARAM,
+        SITE_ICON_BACKGROUND_PARAM,
+        SITE_ICON_VERSION_PARAM,
         'exp',
-        'sig'
+        'sig',
+        'aud'
     ]){
         const raw = query[key];
         const value = Array.isArray(raw) ? raw[0] : raw;
@@ -141,6 +152,59 @@ const SEGMENT = MEDIA_CDN_SEGMENT;
  * 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 VERSIONED stable URL's policy (AGL-3485): `?v={contentHash}.{encoder}`
+ * on the stable path, answered while the token names the asset's current
+ * bytes and current variants.
+ *
+ * The browser keeps it for a year, `immutable`, which is the whole point: the
+ * 60-second window above made every repeat view of every published image a
+ * conditional request, and Lighthouse reports that policy against each one.
+ * It is safe for the reason the content-hashed form never was in a page
+ * (AGL-2798): the page names this URL only while the token is current, the
+ * composition reads the token off the media document on every render, and a
+ * replace or a regeneration therefore moves the page to a new URL instead of
+ * leaving it on a pinned copy of the old bytes.
+ *
+ * The EDGE keeps the stable URL's hour and its revalidation, deliberately not
+ * a year: the edge is the copy a takedown or a lockdown has to outrun for
+ * every new visitor (`media-takedown-reach.ts`), and an hour is the bound the
+ * product states for it. Other visitors still get the edge's copy within that
+ * hour, which is what `s-maxage` is for. Images only — every other type keeps
+ * the stable policy, for the AGL-1515 reasons above.
+ */ export const MEDIA_CDN_VERSIONED_CACHE_CONTROL = 'public, max-age=31536000, s-maxage=3600, stale-while-revalidate=86400, immutable';
+/**
+ * Whether a versioned request may be answered with
+ * {@link MEDIA_CDN_VERSIONED_CACHE_CONTROL} (AGL-3485).
+ *
+ * Only when everything the token promises is true of what is being served:
+ *
+ * - the token's content hash is the document's CURRENT one. A stale token is
+ *   served the current bytes under the stable URL's short policy — a stale
+ *   page shows the new picture, and nothing pins it;
+ * - the representation is the original or a `?w=` variant. A poster or a
+ *   rendition keeps its own policy;
+ * - for a `?w=` request, the variant itself is what is served. A width the
+ *   asset has no variant for falls back to another representation, and a
+ *   fallback is not something to keep for a year: the variant may be
+ *   generated later;
+ * - and the asset's delivery copies were made by the encoder generation the
+ *   token names, which is the one this code runs. The media document records
+ *   which generation made them (`MEDIA_VARIANT_ENCODER_VERSION_FIELD`, absent
+ *   meaning the first). A page rendered after the encoder moved on names the
+ *   new generation before the asset has been regenerated; answering that
+ *   request with the old encode for a year would hide the regeneration behind
+ *   the very URL that was minted to reach it. Asked of every request, not
+ *   only `?w=`, because the encoder makes what the bare URL serves too.
+ */ export function mediaCdnVersionIsCurrent(options) {
+    const { token, currentHash } = options;
+    if (!token || !currentHash || token.contentHash !== currentHash) return false;
+    if (options.otherRepresentation) return false;
+    if (options.widthRequested && !options.variantServed) return false;
+    const recorded = options.documentEncoderVersion;
+    const generation = typeof recorded === 'number' && Number.isInteger(recorded) && recorded > 0 ? recorded : 1;
+    return token.encoderVersion === MEDIA_VARIANT_ENCODER_VERSION && generation === token.encoderVersion;
+}
 /** 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
@@ -308,16 +372,22 @@ const SEGMENT = MEDIA_CDN_SEGMENT;
  *
  * 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.
+ * is what `hostIndex` returns and so cannot join the batch. The host and
+ * index reads are projected to {@link SUSPENSION_FIELDS} plus the two fields
+ * the bandwidth verdict needs off them: 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. The ORG read is whole since AGL-3474, because the bandwidth
+ * verdict asks the org's plan, and the plan is resolved from more fields than
+ * a projection could promise to keep in step with — a mask missing one would
+ * read a paying org as Free and pause its video. Still one read per scope
+ * per TTL.
  *
  * **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`
+ * (`max-age=60`), and a versioned image URL a published page names for a
+ * year in a browser that already fetched it (AGL-3485); 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
@@ -338,6 +408,12 @@ const SEGMENT = MEDIA_CDN_SEGMENT;
  * stops only new origin fetches (AGL-1615). Bytes already cached anywhere
  * remain out of reach of both.
  */ const MEDIA_CDN_LOCK_TTL_MS = 15000;
+/** The verdict when nothing could be read: serve, the lockdown core's posture. */ const OPEN_SCOPE_VERDICT = {
+    locked: false,
+    bandwidthPaused: false,
+    capApplies: false,
+    orgId: null
+};
 const lockCache = new Map();
 const lockPending = new Map();
 /**
@@ -369,38 +445,65 @@ const lockPending = new Map();
     'suspendedUntilMs'
 ];
 /** Which host owns the asset's scope — the only field read off `hostIndex`. */ const HOST_INDEX_ORG_FIELD = 'orgId';
+/** The site's abuse-ceiling stamp (AGL-2155), read beside its lockdown. */ const HOST_BANDWIDTH_CEILING_FIELD = 'bandwidthCeiling';
 /** 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) {
+/**
+ * The verdict an org document gives: its lockdown and, when it is not locked,
+ * whether its bandwidth stops video and files. `host` is the site's projected
+ * document for a host-library scope, whose abuse ceiling (AGL-2155) pauses the
+ * site's own media as it pauses the site's pages; an org library belongs to
+ * no site, so only the org-wide cap reaches it.
+ */ function orgScopeVerdict(org, orgId, host, nowMs) {
+    var _org_data;
+    if (lockdownStopsMediaDelivery(normalizeOrgLockdown(suspensionCarrier(org)), nowMs)) {
+        return _extends({}, OPEN_SCOPE_VERDICT, {
+            locked: true,
+            orgId
+        });
+    }
+    const billing = (_org_data = org.data()) != null ? _org_data : null;
+    const now = new Date(nowMs);
+    return {
+        locked: false,
+        bandwidthPaused: bandwidthCapEngaged(billing, now) || host !== null && bandwidthCeilingDegradesHost({
+            [HOST_BANDWIDTH_CEILING_FIELD]: host.get(HOST_BANDWIDTH_CEILING_FIELD)
+        }, bandwidthCeilingMonthKey(now), billing),
+        // A missing org document resolves as Free, but there is no org to total
+        // or to stamp, so nothing is evaluated for it.
+        capApplies: billing !== null && bandwidthCapApplies(billing),
+        orgId
+    };
+}
+/** TTL-cached: what the documents covering `scope` say about serving it. */ async function mediaCdnScopeVerdict(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;
+        return cached.verdict;
     }
     let pending = lockPending.get(key);
     if (!pending) {
         pending = (async ()=>{
-            let blocked;
+            let verdict = OPEN_SCOPE_VERDICT;
             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) {
+                if (lockdownStopsMediaDelivery(await getPlatformLockdown(), nowMs)) {
+                    verdict = _extends({}, OPEN_SCOPE_VERDICT, {
+                        locked: true
+                    });
+                } else if (scope.isOrg) {
+                    const firestore = firebaseAdmin.app().firestore();
                     // 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) {
+                    const [org] = await firestore.getAll(firestore.collection('orgs').doc(scope.scopeId));
+                    verdict = orgScopeVerdict(org, scope.scopeId, null, nowMs);
+                } else {
                     // 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.
@@ -410,33 +513,35 @@ const lockPending = new Map();
                     // 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 firestore = firebaseAdmin.app().firestore();
                     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
+                            HOST_INDEX_ORG_FIELD,
+                            HOST_BANDWIDTH_CEILING_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
-                            ]
+                    if (lockdownStopsMediaDelivery(normalizeHostLockdown(suspensionCarrier(host)), nowMs)) {
+                        verdict = _extends({}, OPEN_SCOPE_VERDICT, {
+                            locked: true
                         });
-                        blocked = lockdownStopsMediaDelivery(normalizeOrgLockdown(suspensionCarrier(org)), nowMs);
+                    } else if (typeof orgId === 'string' && orgId) {
+                        const [org] = await firestore.getAll(firestore.collection('orgs').doc(orgId));
+                        verdict = orgScopeVerdict(org, orgId, host, nowMs);
                     }
                 }
             } catch (unused) {
                 // Fail open — the lockdown core's posture (see lockdown.ts): an
-                // unreachable Firestore is an outage, not a lockdown.
-                blocked = false;
+                // unreachable Firestore is an outage, not a lockdown, and it is not a
+                // spent band either.
+                verdict = OPEN_SCOPE_VERDICT;
             }
             lockCache.set(key, {
                 at: Date.now(),
-                blocked
+                verdict
             });
-            return blocked;
+            return verdict;
         })().finally(()=>{
             lockPending.delete(key);
         });
@@ -444,6 +549,9 @@ const lockPending = new Map();
     }
     return pending;
 }
+/** TTL-cached: does any lockdown covering `scope` stop delivery? */ async function mediaCdnScopeLocked(scope) {
+    return (await mediaCdnScopeVerdict(scope)).locked;
+}
 /**
  * THE delivery-policy seam: "may this asset be served at all?" — one
  * question, one function, consulted once per request before any caching
@@ -493,6 +601,39 @@ const lockPending = new Map();
     const normalized = String(raw != null ? raw : '').toLowerCase();
     return normalized === '1' || normalized === 'true';
 }
+/**
+ * The display copy a media document records (AGL-3486), or null when it has
+ * none. Only the type is needed to serve it — the object path is derived — and
+ * a record whose type is not an image is treated as no record: the display
+ * copy is always an image, and serving its object under another type would be
+ * a document field choosing a response's `Content-Type`.
+ */ export function mediaCdnDisplayCopy(value) {
+    if (!value || typeof value !== 'object') return null;
+    const contentType = value.contentType;
+    if (typeof contentType !== 'string' || !/^image\/[a-z0-9.+-]+$/.test(contentType)) {
+        return null;
+    }
+    return {
+        contentType
+    };
+}
+/**
+ * Runs `task` once the response has been sent, through Next's `after()`.
+ * Required when first asked for rather than imported, for the reason
+ * `capture-email-check.ts` gives; false where there is no request to run
+ * after — a spec, a script — and the task is then not run at all.
+ */ function scheduleAfterResponse(task) {
+    try {
+        const loaded = require('next/server');
+        if (typeof (loaded == null ? void 0 : loaded.after) !== 'function') return false;
+        loaded.after(()=>task().catch((error)=>{
+                console.error('[media-cdn] after-response task failed', error);
+            }));
+        return true;
+    } catch (unused) {
+        return false;
+    }
+}
 /**
  * Whether `?poster=1` was asked for (AGL-2743).
  *
@@ -702,6 +843,20 @@ export function parseMediaCdnRange(header, size) {
     }
     res.setHeader('Cache-Control', 'no-store');
 }
+/**
+ * Note `bytes` of counted media against the scope's org on this instance, and
+ * when that makes it due, total the org's month and engage the Free cap
+ * (AGL-3474; see `media-bandwidth-cap.ts`).
+ *
+ * Only for an org whose plan the cap stops and that is not already paused,
+ * both read off the cached scope verdict, so a paying org's delivery reads
+ * nothing for it. Never rejects.
+ */ async function mediaCdnBandwidthEvaluation(scope, bytes) {
+    const verdict = await mediaCdnScopeVerdict(scope);
+    if (!verdict.capApplies || verdict.bandwidthPaused || !verdict.orgId) return;
+    if (!mediaBandwidthEvaluationDue(verdict.orgId, bytes)) return;
+    await engageMediaBandwidthCap(verdict.orgId);
+}
 /**
  * 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
@@ -905,7 +1060,8 @@ export function parseMediaCdnRange(header, size) {
             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 : '')
+                sig: String((_req_query_sig = req.query['sig']) != null ? _req_query_sig : ''),
+                aud: req.query['aud'] === 'team' ? 'team' : undefined
             });
             setCacheControl('private, no-store');
             if (!signed) {
@@ -915,6 +1071,19 @@ export function parseMediaCdnRange(header, size) {
                 return;
             }
         }
+        /*
+     * WHAT COUNTS TOWARD THE BANDWIDTH BAND (AGL-3474).
+     *
+     * Every type the edge never holds, because each such response leaves from
+     * origin. A public image is the exception: it is inside the page weight
+     * the band already measures, and the edge serves most of it. A PRIVATE
+     * image is not — it cannot be placed on a page, and `no-store` sends every
+     * request to origin — so it counts like a file. The one serve that never
+     * counts is the workspace previewing its own private library in the
+     * console: its signature names the team (`aud=team`, inside the HMAC, so
+     * a visitor's link cannot claim it).
+     */ const teamPreview = isPrivate && req.query['aud'] === 'team';
+        const countsTowardBand = (type)=>!teamPreview && (isPrivate || !mediaCdnEdgeCacheable(type));
         /**
      * A stale hash on the immutable form REDIRECTS to the stable URL
      * (AGL-2685). It used to 404.
@@ -953,6 +1122,44 @@ export function parseMediaCdnRange(header, size) {
             res.status(302).end();
             return;
         }
+        /*
+     * A site icon (AGL-3484): one size of the favicon, touch icon or manifest
+     * set, drawn from this asset's bytes. Past every gate above and ahead of
+     * every other representation, which it excludes — see `media-cdn-icon.ts`.
+     */ const iconSpec = parseSiteIconSpec(req.query[SITE_ICON_PARAM]);
+        if (iconSpec) {
+            const iconBase = `${isOrg ? 'orgs' : 'hosts'}/${scopeId}`;
+            const iconFile = firebaseAdmin.app().storage().bucket(process.env['NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET']).file(mediaStoragePathInScope({
+                storagePath: snapshot.get('storagePath'),
+                base: iconBase,
+                mediaId
+            }));
+            await serveMediaCdnIcon({
+                req,
+                res,
+                spec: iconSpec,
+                source: {
+                    contentType: snapshot.get('contentType'),
+                    contentHash: currentHash,
+                    stablePath: `${MEDIA_CDN_ROUTE}/${scopeSegment}/${mediaId}`,
+                    file: iconFile
+                },
+                setCacheControl,
+                cacheControl: {
+                    stable: MEDIA_CDN_STABLE_CACHE_CONTROL,
+                    immutable: MEDIA_CDN_IMMUTABLE_CACHE_CONTROL
+                },
+                rateLimit: ()=>{
+                    var _req_socket;
+                    return mediaCdnRateLimitRefusal({
+                        headers: req.headers,
+                        remoteAddress: (_req_socket = req.socket) == null ? void 0 : _req_socket.remoteAddress,
+                        rateClass: 'image'
+                    });
+                }
+            });
+            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 : [];
         /*
@@ -1031,6 +1238,31 @@ export function parseMediaCdnRange(header, size) {
             res.setHeader('Vary', 'Accept');
         }
         const useVariant = !usePoster && !rendition && Boolean(width) && variants.includes(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']);
+        /*
+     * THE DISPLAY COPY (AGL-3486).
+     *
+     * An image whose original is larger than the delivery edge, carries EXIF,
+     * XMP or IPTC, or leans on an EXIF orientation has a display copy: the
+     * same format, downscaled, upright and stripped. It answers every INLINE
+     * request that is not a variant — the bare URL, and a `?w=` the asset has
+     * no variant for, which used to fall back to the original. That is the
+     * request a link preview, an email client and a CSS background make, and
+     * it used to hand them a 6 MB photo with the GPS position it was taken at.
+     *
+     * `?download=1` still serves the ORIGINAL, byte for byte: Download file is
+     * a promise the library makes, and it is the one request that asks for the
+     * file rather than for a picture of it.
+     */ const display = mediaCdnDisplayCopy(snapshot.get('display'));
+        const useDisplay = !usePoster && !rendition && !useVariant && !download && display !== null;
+        // The generation that made the variant or display copy, in its validator:
+        // a regeneration changes the bytes behind the same URL, and a browser
+        // revalidating the old encode must be sent the new one, not a 304.
+        const encoderVersion = mediaVariantEncoderVersionOf(snapshot.get(MEDIA_VARIANT_ENCODER_VERSION_FIELD));
+        const encoderTag = encoderVersion > 1 ? `-e${encoderVersion}` : '';
         /**
      * The ETag's representation tag, and the cache key's conscience.
      *
@@ -1040,11 +1272,7 @@ export function parseMediaCdnRange(header, size) {
      * 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']);
+     */ const representation = usePoster ? `-poster${usePosterVariant ? `-w${width}` : ''}` : rendition ? `-r${rendition.key}` : useVariant ? `-w${width}${encoderTag}` : useDisplay ? `-d${encoderTag}` : '';
         // Stable URL: revalidate against an ETag so a replaced asset is picked
         // up (a conditional GET returns 304 while the content is unchanged).
         //
@@ -1061,7 +1289,20 @@ export function parseMediaCdnRange(header, size) {
         // 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 VERSIONED request (AGL-3485) whose token is current is the one image
+        // response a browser may keep for a year; see
+        // `MEDIA_CDN_VERSIONED_CACHE_CONTROL`. The hashed path form keeps its own
+        // policy below, so a `?v=` on it is inert.
+        const versionCurrent = !hashed && mediaCdnVersionIsCurrent({
+            token: parseMediaCdnVersionToken(req.query[MEDIA_CDN_VERSION_PARAM]),
+            currentHash,
+            widthRequested: Boolean(width),
+            variantServed: useVariant,
+            otherRepresentation: usePoster || Boolean(rendition),
+            documentEncoderVersion: snapshot.get(MEDIA_VARIANT_ENCODER_VERSION_FIELD)
+        });
+        const stableCacheControlFor = (type)=>mediaCdnEdgeCacheable(type) ? versionCurrent ? MEDIA_CDN_VERSIONED_CACHE_CONTROL : 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
@@ -1071,7 +1312,36 @@ export function parseMediaCdnRange(header, size) {
         // 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');
+        const docServedType = usePoster || useVariant ? 'image/webp' : rendition ? rendition.contentType : useDisplay ? display.contentType : snapshot.get('contentType');
+        /*
+     * THE BANDWIDTH BAND (AGL-3474).
+     *
+     * Video and files count against the org's bandwidth allowance (see
+     * `media-bandwidth.ts`), so they stop where the band stops: when the Free
+     * cap is engaged for the owning org, or the site's abuse ceiling degrades
+     * it — the same two predicates that pause the site's pages, read off the
+     * scope documents the lockdown verdict above already holds. No read is
+     * added.
+     *
+     * Public images keep serving. They are not counted here, a paused site
+     * serves no page that asks for one, and the ones the edge holds would
+     * keep serving from it whatever this said. A private image counts, so it
+     * stops with the band like a file; the console's own preview does not.
+     *
+     * Before the provider redirect, which would otherwise hand a paused org's
+     * film to the provider, and before the 304, which would renew a browser's
+     * copy for another minute. `503` with `Retry-After` and `no-store`, the
+     * shape the paused site's pages answer with: the pause lifts on an
+     * upgrade or at the month's end, and nothing may keep the refusal past
+     * either.
+     */ if (countsTowardBand(docServedType) && (await mediaCdnScopeVerdict(scope)).bandwidthPaused) {
+            res.setHeader('Cache-Control', 'no-store');
+            res.setHeader('Retry-After', String(BANDWIDTH_CAP_RETRY_AFTER_SECONDS));
+            res.status(503).json({
+                error: 'Over the monthly traffic limit'
+            });
+            return;
+        }
         /*
      * VIDEO FROM THE DELIVERY PROVIDER (AGL-2824).
      *
@@ -1093,7 +1363,7 @@ export function parseMediaCdnRange(header, size) {
      * 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');
+     */ const deliveryProvider = usePoster || useVariant || useDisplay || download ? null : mediaDeliveryProvider('deliver');
         if (deliveryProvider) {
             var _scope_contextHostId;
             const delivery = await mediaDeliveryRedirect(_extends({
@@ -1124,26 +1394,72 @@ export function parseMediaCdnRange(header, size) {
                 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.
+                // of the serves left through the provider; the per-asset `bytes` stay
+                // the provider's to measure, because none leave from this route.
+                //
+                // The bandwidth band is not the provider's (AGL-3474): moving a film
+                // off origin must not move it off the meter. A player sends every
+                // range of a sitting to the URL it was redirected to, so this request
+                // is the only one of the sitting that reaches us, and it is counted
+                // at the copy's full size — the most one sitting sends, whatever range
+                // a player opens with.
+                let evaluation = null;
+                let recorded = null;
                 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);
+                    const bandwidthBytes = teamPreview ? 0 : delivery.sizeBytes;
+                    recorded = recordMediaServe({
+                        firestore,
+                        collection: isOrg ? 'orgs' : 'hosts',
+                        scopeId,
+                        mediaId,
+                        bandwidthBytes,
+                        redirect: true
+                    });
+                    evaluation = mediaCdnBandwidthEvaluation(scope, bandwidthBytes);
                 }
                 res.status(302).end();
+                // Awaited after the response, as the evaluation is, so the function
+                // lives until the count is written rather than being frozen with it
+                // in flight.
+                await Promise.all([
+                    recorded,
+                    evaluation
+                ]);
                 return;
             }
         }
+        /*
+     * LAZY REGENERATION (AGL-3486) — see `media-delivery-regeneration.ts`.
+     *
+     * An asset whose delivery copies an older encoder made is answered from
+     * what exists, and regenerated once the response has gone. Scheduled
+     * before the 304 exit, because a browser revalidating its copy is a view
+     * of the asset as much as a download is.
+     */ if (req.method === 'GET' && mediaDeliveryCopiesStale({
+            contentType: snapshot.get('contentType'),
+            cdnPath: snapshot.get('cdnPath'),
+            sizeBytes: snapshot.get('sizeBytes'),
+            width: snapshot.get('width'),
+            [MEDIA_VARIANT_ENCODER_VERSION_FIELD]: snapshot.get(MEDIA_VARIANT_ENCODER_VERSION_FIELD),
+            variantRegeneration: snapshot.get('variantRegeneration')
+        })) {
+            scheduleAfterResponse(async ()=>{
+                const regenerationPath = mediaStoragePathInScope({
+                    storagePath: snapshot.get('storagePath'),
+                    base: `${isOrg ? 'orgs' : 'hosts'}/${scopeId}`,
+                    mediaId,
+                    onRefused: ()=>undefined
+                });
+                const outcome = await regenerateMediaDeliveryCopies({
+                    docRef: snapshot.ref,
+                    bucket: firebaseAdmin.app().storage().bucket(process.env['NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET']),
+                    basePath: regenerationPath
+                });
+                if (outcome === 'failed') {
+                    console.error('[media-cdn] delivery copies could not be regenerated', scopeSegment, mediaId);
+                }
+            });
+        }
         if (!hashed) {
             setCacheControl(stableCacheControlFor(docServedType));
             if (etag) res.setHeader('ETag', etag);
@@ -1181,8 +1497,8 @@ export function parseMediaCdnRange(header, size) {
         // 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);
+        const objectPath = usePoster ? usePosterVariant ? `${basePath}${MEDIA_POSTER_OBJECT_SUFFIX}__w${width}.webp` : mediaPosterObjectPath(basePath) : rendition ? mediaRenditionObjectPath(basePath, rendition) : useVariant ? `${basePath}__w${width}.webp` : useDisplay ? mediaDisplayObjectPath(basePath) : basePath;
+        let 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
@@ -1192,9 +1508,20 @@ export function parseMediaCdnRange(header, size) {
             remoteAddress: (_req_socket = req.socket) == null ? void 0 : _req_socket.remoteAddress,
             rateClass: mediaCdnEdgeCacheable(docServedType) ? 'image' : 'non-image'
         }) : null;
-        const [metadata] = await file.getMetadata().catch(()=>[
+        let [metadata] = await file.getMetadata().catch(()=>[
                 null
             ]);
+        // A display copy the document names but Storage does not hold degrades
+        // to the original — what this URL served before display copies existed —
+        // rather than to a 404 on a live page.
+        let servesDisplay = useDisplay;
+        if (!metadata && useDisplay) {
+            servesDisplay = false;
+            file = bucket.file(basePath);
+            [metadata] = await file.getMetadata().catch(()=>[
+                    null
+                ]);
+        }
         if (!metadata) {
             res.status(404).json({
                 error: 'Not found'
@@ -1214,7 +1541,7 @@ export function parseMediaCdnRange(header, size) {
             });
             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');
+        const servedType = usePoster || useVariant ? 'image/webp' : rendition ? rendition.contentType : servesDisplay && display ? display.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 —
@@ -1308,20 +1635,29 @@ export function parseMediaCdnRange(header, size) {
             return;
         }
         // Delivery volume (AGL-176): per-asset serves/bytes on the AGL-82
-        // analytics day-doc, fire-and-forget. Only cache MISSES reach this
+        // analytics day-doc, awaited after the body rather than ahead of it.
+        // 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).
+        // serves, not user-facing totals.
         // 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.
+        //
+        // The same bytes count against the org's bandwidth band when
+        // `countsTowardBand` says so (above). In this write, so counting costs no
+        // write of its own.
+        const countedBytes = countsTowardBand(servedType) ? servedBytes : 0;
         const day = new Date().toISOString().slice(0, 10);
-        void firestore.collection(isOrg ? 'orgs' : 'hosts').doc(scopeId).collection('analytics').doc(day).set({
+        const recorded = firestore.collection(isOrg ? 'orgs' : 'hosts').doc(scopeId).collection('analytics').doc(day).set(_extends({
             // Retention (AGL-1844): every writer of a day doc stamps the
             // day-anchored expiry the TTL policy sweeps on.
-            expiresAt: analyticsDayExpiresAt(day),
+            expiresAt: analyticsDayExpiresAt(day)
+        }, countedBytes > 0 ? {
+            [MEDIA_BANDWIDTH_DAY_FIELD]: firebaseAdmin.firestore.FieldValue.increment(countedBytes)
+        } : {}, {
             media: {
                 [mediaId]: {
                     serves: firebaseAdmin.firestore.FieldValue.increment(1),
@@ -1332,9 +1668,13 @@ export function parseMediaCdnRange(header, size) {
                     bytes: firebaseAdmin.firestore.FieldValue.increment(servedBytes)
                 }
             }
-        }, {
+        }), {
             merge: true
-        }).catch(()=>undefined);
+        }).catch((error)=>logUncountedServe(scopeSegment, mediaId, error));
+        // Totalled beside the stream rather than ahead of it, and awaited — with
+        // the count above — once the stream ends, so the function lives until
+        // both are done.
+        const evaluation = countedBytes > 0 ? mediaCdnBandwidthEvaluation(scope, countedBytes) : null;
         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
@@ -1346,10 +1686,17 @@ export function parseMediaCdnRange(header, size) {
         // 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);
+        try {
+            await pipeline(file.createReadStream(partial ? {
+                start: range.start,
+                end: range.end
+            } : {}), res);
+        } finally{
+            await Promise.all([
+                recorded,
+                evaluation
+            ]);
+        }
     } catch (error) {
         if (mediaCdnClientWentAway(error, res)) return;
         console.error('serveMediaCdn failed', scopeSegment, mediaId, error);
@@ -1366,5 +1713,12 @@ export function parseMediaCdnRange(header, size) {
         }
     }
 }
+/**
+ * A serve the day doc did not take. The response has already gone, so the
+ * failure is the log's to report rather than the visitor's — but reported,
+ * because a dropped count is bandwidth the band and the invoice never see.
+ */ function logUncountedServe(scopeSegment, mediaId, error) {
+    console.error('[media-cdn] serve not counted', scopeSegment, mediaId, error);
+}
 
 //# sourceMappingURL=serve-media-cdn.js.map