@aglyn/tenant-data-admin 1.0.0-beta.220 → 1.0.0-beta.222

package/src/lib/server/media-bandwidth-cap.js

@@ -0,0 +1,180 @@
+/**
+ * @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 { analyticsBandwidthReading, bandwidthCapApplies, bandwidthCapMonthKey, bandwidthCapShouldEngage, bandwidthGbFromPageViews, ORIGIN_MEDIA_BANDWIDTH_WEIGHT, pageViewsFromBandwidthGb, resolveOrgEntitlements } from "@aglyn/aglyn/server";
+import { firebaseAdmin } from "./firebase-admin.js";
+import { notifyHostManagers } from "./notifications.js";
+/**
+ * The Free cap, engaged by the media CDN (AGL-3474).
+ *
+ * The cap's marker (`orgs/{id}.bandwidthCap`) had two writers, and both are
+ * driven by PAGES: the analytics beacon, on a sample of page views, and the
+ * daily usage sweep. Video and files count against the same band now, but a
+ * film or a PDF linked from somewhere else is served with no page view at
+ * all — so a Free org whose traffic is its media would cross its band and
+ * keep serving until the next morning's sweep. A day of one popular clip is
+ * hundreds of gigabytes.
+ *
+ * So the CDN is a third writer, on the same terms as the other two: the same
+ * `bandwidthCapShouldEngage` predicate, the same marker fields, the same UTC
+ * month key, and a write only when the marker does not already name this
+ * month. A reader cannot tell which writer stamped a marker.
+ *
+ * ## The month it totals
+ *
+ * Org-wide, because the band is: every site's page views and counted media,
+ * plus the org library's media, read from the same analytics day documents
+ * the invoice reads, through the same {@link analyticsBandwidthReading}.
+ *
+ * ## What it costs
+ *
+ * Nothing for a paying org: the CDN asks only for an org whose plan the cap
+ * stops (`bandwidthCapApplies`, decided off the org document its delivery
+ * verdict already holds). For those, one evaluation per
+ * {@link MEDIA_BANDWIDTH_EVALUATE_EVERY_BYTES} an instance serves — the org
+ * document, its site ids and the month's day documents, a few dozen reads
+ * against about three cents of delivery.
+ *
+ * ## The slop, stated
+ *
+ * Each instance evaluates on its first counted request for an org and then
+ * once per {@link MEDIA_BANDWIDTH_EVALUATE_EVERY_BYTES}, so the cap engages at
+ * most that much per instance past the band, and the CDN's own verdict cache
+ * takes up to fifteen seconds to see the marker. The beacon's slop is the
+ * same shape, measured in views.
+ */ /** How many counted bytes an instance serves an org between evaluations. */ export const MEDIA_BANDWIDTH_EVALUATE_EVERY_BYTES = 32 * 1024 * 1024;
+/** Sites totalled per org. The cap is for Free, which has one. */ const MEDIA_BANDWIDTH_MAX_HOSTS = 100;
+/** Bound on the per-instance maps, whose keys come from served requests. */ const MAX_TRACKED_ORGS = 5000;
+/** Counted bytes since an org's last evaluation, on this instance. */ const bytesSinceEvaluation = new Map();
+/** Orgs this instance has seen engaged, by the month they were engaged for. */ const engagedOrgs = new Map();
+/** Drop the per-instance state. Tests need it between cases. */ export function invalidateMediaBandwidthCapState() {
+    bytesSinceEvaluation.clear();
+    engagedOrgs.clear();
+}
+/**
+ * Note `bytes` counted for `orgId`, and say whether this instance should now
+ * total the org's month.
+ *
+ * Due on the first counted request an instance sees for the org — a cold
+ * instance under a spike evaluates at once, which is when it matters — and
+ * then each time another {@link MEDIA_BANDWIDTH_EVALUATE_EVERY_BYTES} has
+ * gone out. Never due again in a month this instance has seen it engaged.
+ */ export function mediaBandwidthEvaluationDue(orgId, bytes, now = new Date()) {
+    if (!orgId || !(bytes > 0)) return false;
+    if (engagedOrgs.get(orgId) === bandwidthCapMonthKey(now)) return false;
+    if (bytesSinceEvaluation.size > MAX_TRACKED_ORGS) bytesSinceEvaluation.clear();
+    const since = bytesSinceEvaluation.get(orgId);
+    if (since === undefined || since + bytes >= MEDIA_BANDWIDTH_EVALUATE_EVERY_BYTES) {
+        bytesSinceEvaluation.set(orgId, 0);
+        return true;
+    }
+    bytesSinceEvaluation.set(orgId, since + bytes);
+    return false;
+}
+/** `YYYY-MM` as the day it rolls over, the way a notice prints it. */ function monthRolloverLabel(month) {
+    const [year, monthIndex] = month.split('-').map(Number);
+    return new Date(Date.UTC(year, monthIndex, 1)).toLocaleDateString('en-US', {
+        month: 'long',
+        day: 'numeric',
+        timeZone: 'UTC'
+    });
+}
+/**
+ * Total `orgId`'s month and engage the cap if it is past the band. Answers
+ * whether THIS call engaged it.
+ *
+ * Best-effort, like the beacon's writer: it runs beside a delivery that has
+ * already been decided, and a failure here is logged and costs the request
+ * nothing.
+ */ export async function engageMediaBandwidthCap(orgId, now = new Date()) {
+    const month = bandwidthCapMonthKey(now);
+    if (!orgId || engagedOrgs.get(orgId) === month) return false;
+    try {
+        var _orgSnapshot_data;
+        var _org_bandwidthCap;
+        const firestore = firebaseAdmin.app().firestore();
+        const orgRef = firestore.collection('orgs').doc(orgId);
+        const orgSnapshot = await orgRef.get();
+        if (!orgSnapshot.exists) return false;
+        const org = (_orgSnapshot_data = orgSnapshot.data()) != null ? _orgSnapshot_data : {};
+        if (!bandwidthCapApplies(org)) return false;
+        if (((_org_bandwidthCap = org.bandwidthCap) == null ? void 0 : _org_bandwidthCap.month) === month) {
+            rememberEngaged(orgId, month);
+            return false;
+        }
+        const documentId = firebaseAdmin.firestore.FieldPath.documentId();
+        // The query `report-usage` and the beacon run, per scope: a cap that
+        // counted a different month from the invoice would refuse traffic nobody
+        // was charged for.
+        const monthOf = (ref)=>ref.collection('analytics').where(documentId, '>=', `${month}-01`).where(documentId, '<=', `${month}-31`).get();
+        const hosts = await firestore.collection('hosts').where('orgId', '==', orgId).select().limit(MEDIA_BANDWIDTH_MAX_HOSTS).get();
+        const months = await Promise.all([
+            monthOf(orgRef),
+            ...hosts.docs.map((host)=>monthOf(host.ref))
+        ]);
+        const reading = analyticsBandwidthReading(months.flatMap((days)=>days.docs));
+        const includedBandwidthGb = resolveOrgEntitlements(org).bandwidthGb;
+        if (!bandwidthCapShouldEngage({
+            org,
+            usedBandwidthGb: bandwidthGbFromPageViews(reading.meteredPageViews),
+            includedBandwidthGb
+        })) {
+            return false;
+        }
+        // Stamped inside a transaction that re-reads the marker, so two instances
+        // crossing the band together stamp it, and tell the owner, once.
+        const stamped = await firestore.runTransaction(async (transaction)=>{
+            var _current_get;
+            const current = await transaction.get(orgRef);
+            if (((_current_get = current.get('bandwidthCap')) == null ? void 0 : _current_get.month) === month) return false;
+            // `merge: true`: one field on a document that carries the plan, the
+            // subscription and the sites. A set without it would delete the org.
+            transaction.set(orgRef, {
+                bandwidthCap: {
+                    month,
+                    engagedAt: now.getTime(),
+                    pageViews: Math.round(reading.meteredPageViews),
+                    includedPageViews: Math.round(pageViewsFromBandwidthGb(includedBandwidthGb))
+                }
+            }, {
+                merge: true
+            });
+            return true;
+        });
+        rememberEngaged(orgId, month);
+        if (!stamped) return false;
+        const included = includedBandwidthGb.toLocaleString('en-US', {
+            maximumFractionDigits: 2
+        });
+        // Every site's managers, because the cap pauses every site in the org.
+        // `{site}` is filled by `notifyHostManagers` from the host it reads.
+        await Promise.all(hosts.docs.map((host)=>notifyHostManagers(host.id, {
+                type: 'system.bandwidthCapEngaged',
+                title: '{site} paused — monthly traffic limit reached',
+                body: `{site} has used the ${included} GB of traffic its plan includes ` + 'this month. Video, audio and files served from your media library ' + `count ${ORIGIN_MEDIA_BANDWIDTH_WEIGHT}× toward it, as well as page ` + 'views, so visitors see a temporary notice instead of its pages, ' + 'and its video and files do not load, ' + `until ${monthRolloverLabel(month)}. Nothing is charged for the ` + 'extra traffic. The site comes back on its own then, or as soon as ' + 'you upgrade in Billing.',
+                link: `/${host.id}`
+            })));
+        return true;
+    } catch (error) {
+        console.error('[media-cdn] bandwidth cap evaluation failed', orgId, error);
+        return false;
+    }
+}
+function rememberEngaged(orgId, month) {
+    if (engagedOrgs.size > MAX_TRACKED_ORGS) engagedOrgs.clear();
+    engagedOrgs.set(orgId, month);
+}
+
+//# sourceMappingURL=media-bandwidth-cap.js.map

package/src/lib/server/media-bandwidth-cap.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/media-bandwidth-cap.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport {\n  type AglynOrgBilling,\n  analyticsBandwidthReading,\n  bandwidthCapApplies,\n  bandwidthCapMonthKey,\n  bandwidthCapShouldEngage,\n  bandwidthGbFromPageViews,\n  ORIGIN_MEDIA_BANDWIDTH_WEIGHT,\n  pageViewsFromBandwidthGb,\n  resolveOrgEntitlements,\n} from '@aglyn/aglyn/server'\nimport { firebaseAdmin } from './firebase-admin'\nimport { notifyHostManagers } from './notifications'\n\n/**\n * The Free cap, engaged by the media CDN (AGL-3474).\n *\n * The cap's marker (`orgs/{id}.bandwidthCap`) had two writers, and both are\n * driven by PAGES: the analytics beacon, on a sample of page views, and the\n * daily usage sweep. Video and files count against the same band now, but a\n * film or a PDF linked from somewhere else is served with no page view at\n * all — so a Free org whose traffic is its media would cross its band and\n * keep serving until the next morning's sweep. A day of one popular clip is\n * hundreds of gigabytes.\n *\n * So the CDN is a third writer, on the same terms as the other two: the same\n * `bandwidthCapShouldEngage` predicate, the same marker fields, the same UTC\n * month key, and a write only when the marker does not already name this\n * month. A reader cannot tell which writer stamped a marker.\n *\n * ## The month it totals\n *\n * Org-wide, because the band is: every site's page views and counted media,\n * plus the org library's media, read from the same analytics day documents\n * the invoice reads, through the same {@link analyticsBandwidthReading}.\n *\n * ## What it costs\n *\n * Nothing for a paying org: the CDN asks only for an org whose plan the cap\n * stops (`bandwidthCapApplies`, decided off the org document its delivery\n * verdict already holds). For those, one evaluation per\n * {@link MEDIA_BANDWIDTH_EVALUATE_EVERY_BYTES} an instance serves — the org\n * document, its site ids and the month's day documents, a few dozen reads\n * against about three cents of delivery.\n *\n * ## The slop, stated\n *\n * Each instance evaluates on its first counted request for an org and then\n * once per {@link MEDIA_BANDWIDTH_EVALUATE_EVERY_BYTES}, so the cap engages at\n * most that much per instance past the band, and the CDN's own verdict cache\n * takes up to fifteen seconds to see the marker. The beacon's slop is the\n * same shape, measured in views.\n */\n\n/** How many counted bytes an instance serves an org between evaluations. */\nexport const MEDIA_BANDWIDTH_EVALUATE_EVERY_BYTES = 32 * 1024 * 1024\n\n/** Sites totalled per org. The cap is for Free, which has one. */\nconst MEDIA_BANDWIDTH_MAX_HOSTS = 100\n\n/** Bound on the per-instance maps, whose keys come from served requests. */\nconst MAX_TRACKED_ORGS = 5_000\n\n/** Counted bytes since an org's last evaluation, on this instance. */\nconst bytesSinceEvaluation = new Map<string, number>()\n\n/** Orgs this instance has seen engaged, by the month they were engaged for. */\nconst engagedOrgs = new Map<string, string>()\n\n/** Drop the per-instance state. Tests need it between cases. */\nexport function invalidateMediaBandwidthCapState(): void {\n  bytesSinceEvaluation.clear()\n  engagedOrgs.clear()\n}\n\n/**\n * Note `bytes` counted for `orgId`, and say whether this instance should now\n * total the org's month.\n *\n * Due on the first counted request an instance sees for the org — a cold\n * instance under a spike evaluates at once, which is when it matters — and\n * then each time another {@link MEDIA_BANDWIDTH_EVALUATE_EVERY_BYTES} has\n * gone out. Never due again in a month this instance has seen it engaged.\n */\nexport function mediaBandwidthEvaluationDue(\n  orgId: string,\n  bytes: number,\n  now: Date = new Date(),\n): boolean {\n  if (!orgId || !(bytes > 0)) return false\n  if (engagedOrgs.get(orgId) === bandwidthCapMonthKey(now)) return false\n  if (bytesSinceEvaluation.size > MAX_TRACKED_ORGS) bytesSinceEvaluation.clear()\n  const since = bytesSinceEvaluation.get(orgId)\n  if (since === undefined || since + bytes >= MEDIA_BANDWIDTH_EVALUATE_EVERY_BYTES) {\n    bytesSinceEvaluation.set(orgId, 0)\n    return true\n  }\n  bytesSinceEvaluation.set(orgId, since + bytes)\n  return false\n}\n\n/** `YYYY-MM` as the day it rolls over, the way a notice prints it. */\nfunction monthRolloverLabel(month: string): string {\n  const [year, monthIndex] = month.split('-').map(Number)\n  return new Date(Date.UTC(year, monthIndex, 1)).toLocaleDateString('en-US', {\n    month: 'long',\n    day: 'numeric',\n    timeZone: 'UTC',\n  })\n}\n\n/**\n * Total `orgId`'s month and engage the cap if it is past the band. Answers\n * whether THIS call engaged it.\n *\n * Best-effort, like the beacon's writer: it runs beside a delivery that has\n * already been decided, and a failure here is logged and costs the request\n * nothing.\n */\nexport async function engageMediaBandwidthCap(\n  orgId: string,\n  now: Date = new Date(),\n): Promise<boolean> {\n  const month = bandwidthCapMonthKey(now)\n  if (!orgId || engagedOrgs.get(orgId) === month) return false\n  try {\n    const firestore = firebaseAdmin.app().firestore()\n    const orgRef = firestore.collection('orgs').doc(orgId)\n    const orgSnapshot = await orgRef.get()\n    if (!orgSnapshot.exists) return false\n    const org = (orgSnapshot.data() ?? {}) as Partial<AglynOrgBilling>\n    if (!bandwidthCapApplies(org)) return false\n    if (org.bandwidthCap?.month === month) {\n      rememberEngaged(orgId, month)\n      return false\n    }\n    const documentId = firebaseAdmin.firestore.FieldPath.documentId()\n    // The query `report-usage` and the beacon run, per scope: a cap that\n    // counted a different month from the invoice would refuse traffic nobody\n    // was charged for.\n    const monthOf = (ref: FirebaseFirestore.DocumentReference) =>\n      ref\n        .collection('analytics')\n        .where(documentId, '>=', `${month}-01`)\n        .where(documentId, '<=', `${month}-31`)\n        .get()\n    const hosts = await firestore\n      .collection('hosts')\n      .where('orgId', '==', orgId)\n      .select()\n      .limit(MEDIA_BANDWIDTH_MAX_HOSTS)\n      .get()\n    const months = await Promise.all([\n      monthOf(orgRef),\n      ...hosts.docs.map((host) => monthOf(host.ref)),\n    ])\n    const reading = analyticsBandwidthReading(months.flatMap((days) => days.docs))\n    const includedBandwidthGb = resolveOrgEntitlements(org).bandwidthGb\n    if (\n      !bandwidthCapShouldEngage({\n        org,\n        usedBandwidthGb: bandwidthGbFromPageViews(reading.meteredPageViews),\n        includedBandwidthGb,\n      })\n    ) {\n      return false\n    }\n    // Stamped inside a transaction that re-reads the marker, so two instances\n    // crossing the band together stamp it, and tell the owner, once.\n    const stamped = await firestore.runTransaction(async (transaction) => {\n      const current = await transaction.get(orgRef)\n      if (current.get('bandwidthCap')?.month === month) return false\n      // `merge: true`: one field on a document that carries the plan, the\n      // subscription and the sites. A set without it would delete the org.\n      transaction.set(\n        orgRef,\n        {\n          bandwidthCap: {\n            month,\n            engagedAt: now.getTime(),\n            pageViews: Math.round(reading.meteredPageViews),\n            includedPageViews: Math.round(\n              pageViewsFromBandwidthGb(includedBandwidthGb),\n            ),\n          },\n        },\n        { merge: true },\n      )\n      return true\n    })\n    rememberEngaged(orgId, month)\n    if (!stamped) return false\n    const included = includedBandwidthGb.toLocaleString('en-US', {\n      maximumFractionDigits: 2,\n    })\n    // Every site's managers, because the cap pauses every site in the org.\n    // `{site}` is filled by `notifyHostManagers` from the host it reads.\n    await Promise.all(\n      hosts.docs.map((host) =>\n        notifyHostManagers(host.id, {\n          type: 'system.bandwidthCapEngaged',\n          title: '{site} paused — monthly traffic limit reached',\n          body:\n            `{site} has used the ${included} GB of traffic its plan includes ` +\n            'this month. Video, audio and files served from your media library ' +\n            `count ${ORIGIN_MEDIA_BANDWIDTH_WEIGHT}× toward it, as well as page ` +\n            'views, so visitors see a temporary notice instead of its pages, ' +\n            'and its video and files do not load, ' +\n            `until ${monthRolloverLabel(month)}. Nothing is charged for the ` +\n            'extra traffic. The site comes back on its own then, or as soon as ' +\n            'you upgrade in Billing.',\n          link: `/${host.id}`,\n        }),\n      ),\n    )\n    return true\n  } catch (error) {\n    console.error('[media-cdn] bandwidth cap evaluation failed', orgId, error)\n    return false\n  }\n}\n\nfunction rememberEngaged(orgId: string, month: string): void {\n  if (engagedOrgs.size > MAX_TRACKED_ORGS) engagedOrgs.clear()\n  engagedOrgs.set(orgId, month)\n}\n"],"names":["analyticsBandwidthReading","bandwidthCapApplies","bandwidthCapMonthKey","bandwidthCapShouldEngage","bandwidthGbFromPageViews","ORIGIN_MEDIA_BANDWIDTH_WEIGHT","pageViewsFromBandwidthGb","resolveOrgEntitlements","firebaseAdmin","notifyHostManagers","MEDIA_BANDWIDTH_EVALUATE_EVERY_BYTES","MEDIA_BANDWIDTH_MAX_HOSTS","MAX_TRACKED_ORGS","bytesSinceEvaluation","Map","engagedOrgs","invalidateMediaBandwidthCapState","clear","mediaBandwidthEvaluationDue","orgId","bytes","now","Date","get","size","since","undefined","set","monthRolloverLabel","month","year","monthIndex","split","map","Number","UTC","toLocaleDateString","day","timeZone","engageMediaBandwidthCap","orgSnapshot","org","firestore","app","orgRef","collection","doc","exists","data","bandwidthCap","rememberEngaged","documentId","FieldPath","monthOf","ref","where","hosts","select","limit","months","Promise","all","docs","host","reading","flatMap","days","includedBandwidthGb","bandwidthGb","usedBandwidthGb","meteredPageViews","stamped","runTransaction","transaction","current","engagedAt","getTime","pageViews","Math","round","includedPageViews","merge","included","toLocaleString","maximumFractionDigits","id","type","title","body","link","error","console"],"mappings":"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"}

package/src/lib/server/media-cdn-icon.d.ts

@@ -0,0 +1,77 @@
+/**
+ * @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 { type SiteIconSpec } from '@aglyn/aglyn/app-utils/site-icon-set';
+import type { NextApiRequest, NextApiResponse } from 'next';
+import type { MediaCdnRateLimitRefusal } from './media-cdn-rate-limit';
+/**
+ * The `?icon=` representation of a media CDN URL (AGL-3484): one icon of a
+ * site's derived set, drawn from the asset's current bytes.
+ *
+ * `serveMediaCdn` calls this only after every gate it applies to the bytes —
+ * scope, lockdown, quarantine, the private signature and the stale-pin
+ * redirect — so an icon is served exactly where its source would be.
+ *
+ * ## Derived once, cached by version
+ *
+ * The URL a page names carries `v`, the asset's `contentHash`. While `v` is
+ * current the icon is drawn once and held for a year by the edge and the
+ * browser (`immutable`): the same URL can never need different bytes, because
+ * a DAM Replace changes the hash and so the URL the next render names. A
+ * stale `v` 302s to the current one under the stable URL's revalidated policy,
+ * which is how a page rendered before a Replace reaches the new icon. A URL
+ * with no `v` (the source's hash is unknown) is served under the stable
+ * policy with an ETag keyed on the hash, exactly as the asset itself is.
+ *
+ * ## Anything the renderer cannot draw falls back to the original
+ *
+ * A non-image, an ICO (which `sharp` cannot decode), a source over the
+ * variant generator's fetch ceiling, or a file that fails to decode: each
+ * 302s to the asset's plain URL. A favicon link must never be the reason a
+ * tab shows nothing.
+ */
+/** The fields of a stored asset this representation reads. */
+export interface MediaCdnIconSource {
+    /** The media document's `contentType`. */
+    contentType: unknown;
+    /** The media document's `contentHash`; `''` for a legacy asset. */
+    contentHash: string;
+    /** `/api/media/cdn/{scope}/{mediaId}` — the asset's stable URL. */
+    stablePath: string;
+    /** The Storage object, as far as this reads it. */
+    file: {
+        getMetadata(): Promise<[{
+            size?: string | number;
+        } | null | undefined]>;
+        download(): Promise<[Buffer]>;
+    };
+}
+/** The `ETag` of one derived icon: the source's hash plus the representation. */
+export declare function mediaCdnIconEtag(contentHash: string, spec: SiteIconSpec, background: string | undefined): string | null;
+export declare function serveMediaCdnIcon(options: {
+    req: NextApiRequest;
+    res: NextApiResponse;
+    spec: SiteIconSpec;
+    source: MediaCdnIconSource;
+    /** Forces `private, no-store` on a signed asset, as the handler's does. */
+    setCacheControl: (value: string) => void;
+    cacheControl: {
+        stable: string;
+        immutable: string;
+    };
+    /** The caller's delivery count; `null` means serve. */
+    rateLimit: () => Promise<MediaCdnRateLimitRefusal | null>;
+}): Promise<void>;

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

@@ -0,0 +1,140 @@
+/**
+ * @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 { formatSiteIconSpec, normalizeSiteIconBackground, SITE_ICON_BACKGROUND_PARAM, SITE_ICON_PARAM, SITE_ICON_VERSION_PARAM, siteIconSourceTypeDerivable, siteIconUsesBackground, DEFAULT_SITE_ICON_BACKGROUND } from "@aglyn/aglyn/app-utils/site-icon-set";
+import { MEDIA_VARIANT_SOURCE_MAX_BYTES } from "./media-variants.js";
+import { renderSiteIcon } from "./site-icon-render.js";
+const firstValue = (value)=>{
+    const raw = Array.isArray(value) ? value[0] : value;
+    return typeof raw === 'string' && raw !== '' ? raw : undefined;
+};
+/**
+ * The query this representation names, rebuilt from the parameters it reads —
+ * never forwarded whole, for `mediaCdnForwardedQuery`'s reasons. `exp`/`sig`
+ * ride along so a signed asset's redirect still serves.
+ */ function iconQuery(query, pairs) {
+    const params = new URLSearchParams();
+    for (const [key, value] of pairs)if (value) params.set(key, value);
+    for (const key of [
+        'exp',
+        'sig'
+    ]){
+        const value = firstValue(query[key]);
+        if (value) params.set(key, value);
+    }
+    const encoded = params.toString();
+    return encoded ? `?${encoded}` : '';
+}
+/** The `ETag` of one derived icon: the source's hash plus the representation. */ export function mediaCdnIconEtag(contentHash, spec, background) {
+    if (!contentHash) return null;
+    const plate = background ? `-${background}` : '';
+    return `"${contentHash}-icon-${formatSiteIconSpec(spec)}${plate}"`;
+}
+export async function serveMediaCdnIcon(options) {
+    var _normalizeSiteIconBackground, _firstValue, _metadata_size;
+    const { req, res, spec, source, setCacheControl, cacheControl } = options;
+    const background = siteIconUsesBackground(spec) ? (_normalizeSiteIconBackground = normalizeSiteIconBackground(`#${(_firstValue = firstValue(req.query[SITE_ICON_BACKGROUND_PARAM])) != null ? _firstValue : ''}`)) != null ? _normalizeSiteIconBackground : DEFAULT_SITE_ICON_BACKGROUND : undefined;
+    const version = firstValue(req.query[SITE_ICON_VERSION_PARAM]);
+    const { contentHash } = source;
+    const original = (cache)=>{
+        res.removeHeader('ETag');
+        setCacheControl(cache);
+        res.setHeader('Location', `${source.stablePath}${iconQuery(req.query, [])}`);
+        res.status(302).end();
+    };
+    if (!siteIconSourceTypeDerivable(source.contentType)) {
+        original(cacheControl.stable);
+        return;
+    }
+    if (version && contentHash && version !== contentHash) {
+        setCacheControl(cacheControl.stable);
+        res.setHeader('Location', `${source.stablePath}${iconQuery(req.query, [
+            [
+                SITE_ICON_PARAM,
+                formatSiteIconSpec(spec)
+            ],
+            [
+                SITE_ICON_BACKGROUND_PARAM,
+                background
+            ],
+            [
+                SITE_ICON_VERSION_PARAM,
+                contentHash
+            ]
+        ])}`);
+        res.status(302).end();
+        return;
+    }
+    const etag = mediaCdnIconEtag(contentHash, spec, background);
+    setCacheControl(version && version === contentHash ? cacheControl.immutable : cacheControl.stable);
+    if (etag) {
+        res.setHeader('ETag', etag);
+        if (req.headers['if-none-match'] === etag) {
+            res.status(304).end();
+            return;
+        }
+    }
+    const counted = req.method === 'GET' ? options.rateLimit() : null;
+    const [metadata] = await source.file.getMetadata().catch(()=>[
+            null
+        ]);
+    if (!metadata) {
+        res.removeHeader('ETag');
+        setCacheControl('public, max-age=60');
+        res.status(404).json({
+            error: 'Not found'
+        });
+        return;
+    }
+    if (Number((_metadata_size = metadata.size) != null ? _metadata_size : 0) > MEDIA_VARIANT_SOURCE_MAX_BYTES) {
+        original(cacheControl.stable);
+        return;
+    }
+    const refused = await counted;
+    if (refused) {
+        res.removeHeader('ETag');
+        res.setHeader('Cache-Control', 'no-store');
+        res.setHeader('Retry-After', String(refused.retryAfterSeconds));
+        res.status(429).json({
+            error: 'Too many requests'
+        });
+        return;
+    }
+    let icon;
+    try {
+        const [bytes] = await source.file.download();
+        icon = await renderSiteIcon({
+            source: bytes,
+            spec,
+            background
+        });
+    } catch (error) {
+        // A file that will not decode is a property of the upload, not of the
+        // request, but it is not cached either: a Replace must be able to fix it.
+        console.error('[media-cdn] site icon render failed', source.stablePath, error);
+        original('no-store');
+        return;
+    }
+    res.setHeader('Content-Type', icon.contentType);
+    res.setHeader('Content-Length', String(icon.body.length));
+    res.setHeader('Content-Disposition', `inline; filename="icon-${formatSiteIconSpec(spec)}.${spec.plate === 'ico' ? 'ico' : 'png'}"`);
+    if (req.method === 'HEAD') {
+        res.status(200).end();
+        return;
+    }
+    res.status(200).end(icon.body);
+}
+
+//# sourceMappingURL=media-cdn-icon.js.map

package/src/lib/server/media-cdn-icon.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/media-cdn-icon.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport {\n  formatSiteIconSpec,\n  normalizeSiteIconBackground,\n  SITE_ICON_BACKGROUND_PARAM,\n  SITE_ICON_PARAM,\n  SITE_ICON_VERSION_PARAM,\n  siteIconSourceTypeDerivable,\n  siteIconUsesBackground,\n  DEFAULT_SITE_ICON_BACKGROUND,\n  type SiteIconSpec,\n} from '@aglyn/aglyn/app-utils/site-icon-set'\nimport type { NextApiRequest, NextApiResponse } from 'next'\n\nimport type { MediaCdnRateLimitRefusal } from './media-cdn-rate-limit'\nimport { MEDIA_VARIANT_SOURCE_MAX_BYTES } from './media-variants'\nimport { renderSiteIcon } from './site-icon-render'\n\n/**\n * The `?icon=` representation of a media CDN URL (AGL-3484): one icon of a\n * site's derived set, drawn from the asset's current bytes.\n *\n * `serveMediaCdn` calls this only after every gate it applies to the bytes —\n * scope, lockdown, quarantine, the private signature and the stale-pin\n * redirect — so an icon is served exactly where its source would be.\n *\n * ## Derived once, cached by version\n *\n * The URL a page names carries `v`, the asset's `contentHash`. While `v` is\n * current the icon is drawn once and held for a year by the edge and the\n * browser (`immutable`): the same URL can never need different bytes, because\n * a DAM Replace changes the hash and so the URL the next render names. A\n * stale `v` 302s to the current one under the stable URL's revalidated policy,\n * which is how a page rendered before a Replace reaches the new icon. A URL\n * with no `v` (the source's hash is unknown) is served under the stable\n * policy with an ETag keyed on the hash, exactly as the asset itself is.\n *\n * ## Anything the renderer cannot draw falls back to the original\n *\n * A non-image, an ICO (which `sharp` cannot decode), a source over the\n * variant generator's fetch ceiling, or a file that fails to decode: each\n * 302s to the asset's plain URL. A favicon link must never be the reason a\n * tab shows nothing.\n */\n\n/** The fields of a stored asset this representation reads. */\nexport interface MediaCdnIconSource {\n  /** The media document's `contentType`. */\n  contentType: unknown\n  /** The media document's `contentHash`; `''` for a legacy asset. */\n  contentHash: string\n  /** `/api/media/cdn/{scope}/{mediaId}` — the asset's stable URL. */\n  stablePath: string\n  /** The Storage object, as far as this reads it. */\n  file: {\n    getMetadata(): Promise<[{ size?: string | number } | null | undefined]>\n    download(): Promise<[Buffer]>\n  }\n}\n\nconst firstValue = (value: unknown): string | undefined => {\n  const raw = Array.isArray(value) ? value[0] : value\n  return typeof raw === 'string' && raw !== '' ? raw : undefined\n}\n\n/**\n * The query this representation names, rebuilt from the parameters it reads —\n * never forwarded whole, for `mediaCdnForwardedQuery`'s reasons. `exp`/`sig`\n * ride along so a signed asset's redirect still serves.\n */\nfunction iconQuery(\n  query: NextApiRequest['query'],\n  pairs: Array<[string, string | undefined]>,\n): string {\n  const params = new URLSearchParams()\n  for (const [key, value] of pairs) if (value) params.set(key, value)\n  for (const key of ['exp', 'sig']) {\n    const value = firstValue(query[key])\n    if (value) params.set(key, value)\n  }\n  const encoded = params.toString()\n  return encoded ? `?${encoded}` : ''\n}\n\n/** The `ETag` of one derived icon: the source's hash plus the representation. */\nexport function mediaCdnIconEtag(\n  contentHash: string,\n  spec: SiteIconSpec,\n  background: string | undefined,\n): string | null {\n  if (!contentHash) return null\n  const plate = background ? `-${background}` : ''\n  return `\"${contentHash}-icon-${formatSiteIconSpec(spec)}${plate}\"`\n}\n\nexport async function serveMediaCdnIcon(options: {\n  req: NextApiRequest\n  res: NextApiResponse\n  spec: SiteIconSpec\n  source: MediaCdnIconSource\n  /** Forces `private, no-store` on a signed asset, as the handler's does. */\n  setCacheControl: (value: string) => void\n  cacheControl: { stable: string; immutable: string }\n  /** The caller's delivery count; `null` means serve. */\n  rateLimit: () => Promise<MediaCdnRateLimitRefusal | null>\n}): Promise<void> {\n  const { req, res, spec, source, setCacheControl, cacheControl } = options\n  const background = siteIconUsesBackground(spec)\n    ? (normalizeSiteIconBackground(\n        `#${firstValue(req.query[SITE_ICON_BACKGROUND_PARAM]) ?? ''}`,\n      ) ?? DEFAULT_SITE_ICON_BACKGROUND)\n    : undefined\n  const version = firstValue(req.query[SITE_ICON_VERSION_PARAM])\n  const { contentHash } = source\n\n  const original = (cache: string) => {\n    res.removeHeader('ETag')\n    setCacheControl(cache)\n    res.setHeader('Location', `${source.stablePath}${iconQuery(req.query, [])}`)\n    res.status(302).end()\n  }\n\n  if (!siteIconSourceTypeDerivable(source.contentType)) {\n    original(cacheControl.stable)\n    return\n  }\n  if (version && contentHash && version !== contentHash) {\n    setCacheControl(cacheControl.stable)\n    res.setHeader(\n      'Location',\n      `${source.stablePath}${iconQuery(req.query, [\n        [SITE_ICON_PARAM, formatSiteIconSpec(spec)],\n        [SITE_ICON_BACKGROUND_PARAM, background],\n        [SITE_ICON_VERSION_PARAM, contentHash],\n      ])}`,\n    )\n    res.status(302).end()\n    return\n  }\n\n  const etag = mediaCdnIconEtag(contentHash, spec, background)\n  setCacheControl(\n    version && version === contentHash\n      ? cacheControl.immutable\n      : cacheControl.stable,\n  )\n  if (etag) {\n    res.setHeader('ETag', etag)\n    if (req.headers['if-none-match'] === etag) {\n      res.status(304).end()\n      return\n    }\n  }\n\n  const counted = req.method === 'GET' ? options.rateLimit() : null\n  const [metadata] = await source.file.getMetadata().catch(() => [null])\n  if (!metadata) {\n    res.removeHeader('ETag')\n    setCacheControl('public, max-age=60')\n    res.status(404).json({ error: 'Not found' })\n    return\n  }\n  if (Number(metadata.size ?? 0) > MEDIA_VARIANT_SOURCE_MAX_BYTES) {\n    original(cacheControl.stable)\n    return\n  }\n  const refused = await counted\n  if (refused) {\n    res.removeHeader('ETag')\n    res.setHeader('Cache-Control', 'no-store')\n    res.setHeader('Retry-After', String(refused.retryAfterSeconds))\n    res.status(429).json({ error: 'Too many requests' })\n    return\n  }\n\n  let icon: { body: Buffer; contentType: string }\n  try {\n    const [bytes] = await source.file.download()\n    icon = await renderSiteIcon({ source: bytes, spec, background })\n  } catch (error) {\n    // A file that will not decode is a property of the upload, not of the\n    // request, but it is not cached either: a Replace must be able to fix it.\n    console.error('[media-cdn] site icon render failed', source.stablePath, error)\n    original('no-store')\n    return\n  }\n\n  res.setHeader('Content-Type', icon.contentType)\n  res.setHeader('Content-Length', String(icon.body.length))\n  res.setHeader(\n    'Content-Disposition',\n    `inline; filename=\"icon-${formatSiteIconSpec(spec)}.${\n      spec.plate === 'ico' ? 'ico' : 'png'\n    }\"`,\n  )\n  if (req.method === 'HEAD') {\n    res.status(200).end()\n    return\n  }\n  res.status(200).end(icon.body)\n}\n"],"names":["formatSiteIconSpec","normalizeSiteIconBackground","SITE_ICON_BACKGROUND_PARAM","SITE_ICON_PARAM","SITE_ICON_VERSION_PARAM","siteIconSourceTypeDerivable","siteIconUsesBackground","DEFAULT_SITE_ICON_BACKGROUND","MEDIA_VARIANT_SOURCE_MAX_BYTES","renderSiteIcon","firstValue","value","raw","Array","isArray","undefined","iconQuery","query","pairs","params","URLSearchParams","key","set","encoded","toString","mediaCdnIconEtag","contentHash","spec","background","plate","serveMediaCdnIcon","options","metadata","req","res","source","setCacheControl","cacheControl","version","original","cache","removeHeader","setHeader","stablePath","status","end","contentType","stable","etag","immutable","headers","counted","method","rateLimit","file","getMetadata","catch","json","error","Number","size","refused","String","retryAfterSeconds","icon","bytes","download","console","body","length"],"mappings":"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"}

package/src/lib/server/media-delivery-regeneration.d.ts

@@ -0,0 +1,132 @@
+/**
+ * @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 { MEDIA_VARIANT_ENCODER_VERSION_FIELD } from '@aglyn/aglyn/app-utils/media-ref';
+/**
+ * Lazy regeneration of an asset's delivery copies (AGL-3486).
+ *
+ * A change to the encoder — its quality, the width ladder, the display copy —
+ * has to reach every asset already in every library, and the obvious tool is
+ * a backfill script: a pass over the corpus that somebody has to remember to
+ * run, against production, after each deploy that changes the encoder. The
+ * last one (`backfill-media-variants.mjs`) was written, documented as
+ * outstanding and never converged.
+ *
+ * So the CDN converges the corpus itself. A media document records the
+ * encoder generation that made its copies
+ * (`MEDIA_VARIANT_ENCODER_VERSION_FIELD`); a request that finds it older than
+ * `MEDIA_VARIANT_ENCODER_VERSION` is SERVED what exists — an old variant, or
+ * the original — and the asset is regenerated after the response. Every asset
+ * a visitor actually sees reaches the new encoder on its first view; one
+ * nobody requests costs nothing. An asset that never got variants at all,
+ * which is what the old backfill was for, is simply an asset at generation 1.
+ *
+ * ## Why after the response, and not inside it
+ *
+ * Regenerating means fetching the original (up to 15 MB) and making up to ten
+ * WebP encodes and a display copy: about two seconds for a large photo. A
+ * visitor should not wait for that, and nothing about the old bytes is wrong —
+ * only heavier — so the request is answered from what exists and the work
+ * runs in `after()`.
+ *
+ * ## One regeneration per asset, not one per visitor
+ *
+ * A popular image is requested many times before its first regeneration
+ * finishes. The first request takes a lease on the document in a transaction
+ * (`variantRegeneration.startedAtMs`); every other request in the lease window
+ * sees it on the snapshot it already read and schedules nothing, so the lease
+ * costs one transaction per asset, not one per request. A failure records the
+ * generation it failed at, so a source `sharp` cannot decode is tried once per
+ * encoder generation rather than once per minute forever.
+ */
+/** How long a regeneration's lease keeps others from starting one. */
+export declare const MEDIA_REGENERATION_LEASE_MS: number;
+/** The document field holding the lease and any failure. */
+export declare const MEDIA_REGENERATION_FIELD = "variantRegeneration";
+export interface MediaRegenerationState {
+    /** When the current (or last) regeneration took its lease. */
+    startedAtMs?: number;
+    /** The encoder generation a regeneration last FAILED at. */
+    failedVersion?: number;
+    /** Why, kept short — the same contract as `variantsError`. */
+    error?: string;
+}
+/** The fields of a media document this decision reads, among any others. */
+export interface MediaRegenerationFacts {
+    [field: string]: unknown;
+    contentType?: unknown;
+    cdnPath?: unknown;
+    sizeBytes?: unknown;
+    width?: unknown;
+    [MEDIA_VARIANT_ENCODER_VERSION_FIELD]?: unknown;
+    [MEDIA_REGENERATION_FIELD]?: unknown;
+}
+/**
+ * Whether this asset's delivery copies should be regenerated now.
+ *
+ * Pure, and decided from the snapshot the CDN already holds, so a request
+ * that does not need to regenerate reads nothing more.
+ *
+ * - Only assets the generator would have worked on at upload: an image with a
+ *   CDN path (the `mediaCdn` entitlement and a public asset, the same gate the
+ *   upload routes apply), of a type that has variants or a display copy, no
+ *   larger than the generator will fetch back.
+ * - Only when the recorded generation is older than the current one.
+ * - Not while another regeneration holds the lease, and not again at a
+ *   generation that already failed.
+ */
+export declare function mediaDeliveryCopiesStale(facts: MediaRegenerationFacts, nowMs?: number): boolean;
+/** The slice of a Storage bucket this needs. */
+export interface MediaRegenerationBucket {
+    file(path: string): {
+        download(): Promise<[Buffer]>;
+        save(bytes: Buffer, options: {
+            contentType: string;
+            metadata: {
+                cacheControl: string;
+            };
+        }): Promise<unknown>;
+        delete(): Promise<unknown>;
+    };
+}
+export type MediaRegenerationResult = 'regenerated' | 'not-stale' | 'changed' | 'failed';
+/**
+ * Regenerate one asset's delivery copies with the current encoder.
+ *
+ * `basePath` is the original's object path as the CDN resolved it — already
+ * proved to be inside the asset's own scope (AGL-1881) — and every object this
+ * writes or deletes is derived from it.
+ *
+ * Ordering, and why:
+ *
+ * 1. **Lease**, in a transaction that re-reads the document: two requests that
+ *    both saw it stale cannot both start.
+ * 2. **Generate and save** the new copies. Their paths are the old ones, so a
+ *    request in this window may receive new bytes under an old validator —
+ *    harmless, both are the same picture.
+ * 3. **Record**, in a transaction that refuses when the content hash moved: a
+ *    replace during the work owns the document, and copies of the bytes it
+ *    replaced must not be recorded over it.
+ * 4. **Delete** what the new set no longer names — a width the new encoder
+ *    skipped, a display copy the new rules do not need — only once the
+ *    document stops naming them, so the CDN never points at a deleted object.
+ */
+export declare function regenerateMediaDeliveryCopies(options: {
+    docRef: FirebaseFirestore.DocumentReference;
+    bucket: MediaRegenerationBucket;
+    basePath: string;
+    nowMs?: number;
+}): Promise<MediaRegenerationResult>;