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

package/src/lib/server/leaving-notice.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/leaving-notice.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\n/*==========================================\n * THE \"YOU'RE LEAVING THIS SITE\" NOTICE, SERVER HALF (AGL-3452).\n *\n * Who gets it, which hosts are exempt, and the signature that keeps the\n * notice route from becoming an open redirect. The client half — rewriting\n * an href, the click interceptor — is `@aglyn/aglyn/app-utils/leaving-notice`.\n *\n * ## Who\n *\n * A site whose workspace is on the FREE plan (the effective plan, so a dead\n * subscription counts as free, as it does for every entitlement) and in its\n * first {@link LEAVING_NOTICE_DAYS} days — the same window, read through the\n * same `isYoungWorkspaceAge`, as the soft phishing rules. Paid and older\n * workspaces are untouched, and a workspace whose creation date cannot be\n * read is an existing customer, never a new one.\n *\n * ## Why signed\n *\n * The notice lives on the site's own host and its Continue button goes\n * wherever `?to=` says. Unsigned, any site's notice would be a page that\n * vouches for any address anyone puts in a link — the hop this feature exists\n * to remove. So the server signs each outside address it finds on a page it\n * renders, bound to that site, and the route shows a Continue button only for\n * an address whose signature checks out. Everything else is refused.\n *\n * The signature carries no expiry on purpose. The route never redirects on\n * its own, so a signature that outlives its page buys nothing but one more\n * view of the same warning — while an expiring one would break the links an\n * ISR-cached page is still serving the moment the window closes.\n *=========================================*/\n\nimport { createHmac } from 'crypto'\nimport { DOCS_BASE_URL } from '@aglyn/aglyn/app-utils/docs-help'\nimport {\n  type LeavingNoticeConfig,\n  leavingDestination,\n  normalizeLeavingDestination,\n} from '@aglyn/aglyn/app-utils/leaving-notice'\nimport { resolveEffectivePlan } from '@aglyn/aglyn/app-utils/plan-entitlements'\nimport {\n  PLATFORM_HOME_URL,\n  PLATFORM_SUPPORT_URL,\n  platformConsoleOrigin,\n} from '@aglyn/aglyn/app-utils/platform-brand'\nimport {\n  type SiteReturnHost,\n  siteOwnHosts,\n} from '@aglyn/aglyn/app-utils/site-return-url'\nimport { TENANT_APEX } from '@aglyn/aglyn/app-utils/tenant-apex'\nimport {\n  isYoungWorkspaceAge,\n  OUTBOUND_REVIEW_YOUNG_DAYS,\n  registrableDomain,\n} from '@aglyn/shared-util-email/outbound-phishing-screen'\nimport { tokenSigningSecret } from './media-signing'\nimport { orgAgeDays, orgCreatedMs } from './org-age'\nimport { safeEqual } from './safe-equal'\n\n/** How long a new free workspace's sites carry the notice. */\nexport const LEAVING_NOTICE_DAYS = OUTBOUND_REVIEW_YOUNG_DAYS\n\nconst DAY_MS = 86_400_000\n\n/**\n * The most outside addresses one page is signed for. A page with more is a\n * link farm, and the ones past the cap still go through the notice — which\n * refuses them — rather than around it.\n */\nexport const LEAVING_NOTICE_MAX_DESTINATIONS = 500\n\n/** Deepest a page payload is walked; composed node maps sit far above it. */\nconst MAX_WALK_DEPTH = 64\n\n/** Longest string scanned for embedded addresses (a long entry body). */\nconst MAX_SCANNED_STRING = 200_000\n\n/**\n * When a workspace's notice window closes (epoch ms), or `null` when its\n * sites carry no notice: a paid plan, a workspace past its first\n * {@link LEAVING_NOTICE_DAYS} days, or one whose creation date is unreadable.\n *\n * Takes the org as loaded anywhere — a live document, or the render cache's\n * JSON copy, whose `createdAt` has lost its methods (`orgCreatedMs`).\n */\nexport function leavingNoticeEndsAt(\n  org: unknown,\n  nowMs: number = Date.now(),\n): number | null {\n  if (!org || typeof org !== 'object') return null\n  if (resolveEffectivePlan(org as never) !== 'free') return null\n  const createdAt = (org as { createdAt?: unknown }).createdAt\n  if (!isYoungWorkspaceAge(orgAgeDays(createdAt, nowMs))) return null\n  const createdMs = orgCreatedMs(createdAt)\n  return createdMs === null ? null : createdMs + LEAVING_NOTICE_DAYS * DAY_MS\n}\n\nfunction hostnameOf(raw: string | null | undefined): string | null {\n  if (!raw) return null\n  try {\n    const url = new URL(raw)\n    if (url.protocol !== 'http:' && url.protocol !== 'https:') return null\n    return url.hostname.toLowerCase() || null\n  } catch {\n    return null\n  }\n}\n\n/**\n * The hosts a link may reach without the notice: the site's own (its\n * subdomain, its custom domain and `www.` of it) and the platform's own — the\n * marketing site, console, support and docs, each with every name under its\n * registrable domain, plus the bare tenant apex.\n *\n * Other sites on the tenant apex are NOT exempt. They are other customers'\n * sites, and a chain of two new free sites is the same hop as one.\n */\nexport function leavingNoticeHosts(\n  site: SiteReturnHost | null | undefined,\n): string[] {\n  const hosts = new Set<string>(siteOwnHosts(site))\n  const apex = TENANT_APEX.toLowerCase()\n  hosts.add(apex)\n  const apexRegistrable = registrableDomain(apex)\n  for (const raw of [\n    PLATFORM_HOME_URL,\n    platformConsoleOrigin(),\n    PLATFORM_SUPPORT_URL,\n    DOCS_BASE_URL,\n  ]) {\n    const hostname = hostnameOf(raw)\n    if (!hostname) continue\n    hosts.add(hostname)\n    const registrable = registrableDomain(hostname)\n    // A platform name under the tenant apex itself must not exempt the apex:\n    // that would exempt every customer's site with it.\n    if (registrable.includes('.') && registrable !== apexRegistrable) {\n      hosts.add(`.${registrable}`)\n    }\n  }\n  return [...hosts]\n}\n\n/** An address as it appears in text: scheme, then anything a URL may hold. */\nconst EMBEDDED_URL = /https?:\\/\\/[^\\s\"'<>()[\\]{}\\\\^`|]+/gi\n\n/** Characters prose puts after an address that the address does not own. */\nconst TRAILING_PROSE = /[.,;:!?'\"*_~]+$/\n\n/** A whole value shaped like an absolute or protocol-relative address. */\nconst ADDRESS_SHAPE = /^\\s*(?:https?:|[\\\\/]{2})/i\n\n/**\n * Every outside address a rendered page could link to: each string in the\n * payload that is one, and each one embedded in a string (Markdown, rich\n * text HTML, a plain sentence). Over-collecting is harmless — a signature\n * nobody follows is never read — and under-collecting only sends a link to a\n * refusal, never around the notice.\n *\n * Returned normalized, the spelling the client looks signatures up by.\n */\nexport function collectLeavingDestinations(\n  value: unknown,\n  hosts: readonly string[],\n  limit: number = LEAVING_NOTICE_MAX_DESTINATIONS,\n): string[] {\n  const found = new Set<string>()\n  const consider = (candidate: string) => {\n    if (found.size >= limit) return\n    const destination = leavingDestination(candidate, hosts)\n    if (destination) found.add(destination)\n  }\n  const scan = (text: string) => {\n    if (ADDRESS_SHAPE.test(text)) consider(text)\n    if (!text.includes('http')) return\n    const scanned =\n      text.length > MAX_SCANNED_STRING ? text.slice(0, MAX_SCANNED_STRING) : text\n    for (const match of scanned.matchAll(EMBEDDED_URL)) {\n      const raw = match[0]\n      consider(raw)\n      const trimmed = raw.replace(TRAILING_PROSE, '')\n      if (trimmed !== raw) consider(trimmed)\n      // An href inside stored HTML is entity-encoded; the DOM decodes it.\n      if (trimmed.includes('&amp;')) consider(trimmed.replace(/&amp;/g, '&'))\n    }\n  }\n  const walk = (node: unknown, depth: number) => {\n    if (found.size >= limit || depth > MAX_WALK_DEPTH) return\n    if (typeof node === 'string') {\n      scan(node)\n    } else if (Array.isArray(node)) {\n      for (const item of node) walk(item, depth + 1)\n    } else if (node && typeof node === 'object') {\n      for (const item of Object.values(node)) walk(item, depth + 1)\n    }\n  }\n  walk(value, 0)\n  return [...found]\n}\n\nfunction leavingSignature(hostId: string, destination: string): string {\n  return createHmac('sha256', tokenSigningSecret())\n    .update(`leaving-notice:v1:${hostId}:${destination}`)\n    .digest('base64url')\n}\n\n/**\n * The signature for one destination on one site. Throws when the deployment\n * has no signing secret, like every signer of it.\n */\nexport function signLeavingDestination(\n  hostId: string,\n  destination: string,\n): string {\n  const normalized = normalizeLeavingDestination(destination)\n  if (!hostId || !normalized) {\n    throw new Error('A leaving-notice signature needs a site and an address')\n  }\n  return leavingSignature(hostId, normalized)\n}\n\n/**\n * Whether `signature` was issued for `destination` on this site. False for\n * anything else — another site's signature, an edited address, a missing\n * secret (fail closed).\n */\nexport function verifyLeavingDestination(\n  hostId: string,\n  destination: unknown,\n  signature: unknown,\n): boolean {\n  if (!hostId || typeof signature !== 'string' || signature.length > 128) {\n    return false\n  }\n  const normalized = normalizeLeavingDestination(destination)\n  if (!normalized) return false\n  let expected: string\n  try {\n    expected = leavingSignature(hostId, normalized)\n  } catch {\n    return false\n  }\n  return safeEqual(signature, expected)\n}\n\n/** Signs a page's destinations for one site. */\nexport function signLeavingDestinations(\n  hostId: string,\n  destinations: readonly string[],\n): Record<string, string> {\n  const sigs: Record<string, string> = {}\n  for (const destination of destinations) {\n    sigs[destination] = leavingSignature(hostId, destination)\n  }\n  return sigs\n}\n\n/** Whether this deployment can sign at all. */\nfunction canSign(): boolean {\n  try {\n    tokenSigningSecret()\n    return true\n  } catch {\n    return false\n  }\n}\n\n/**\n * What a published page of this site carries, or `null` when the site is not\n * in its window.\n *\n * `content` is everything the page renders from — its props, its nodes —\n * walked for outside addresses to sign.\n *\n * A deployment with no signing secret gets no notice, loudly. The route\n * could verify nothing there and would refuse every link on every new free\n * site; an outage of every outbound link is not a safer failure than the\n * links working as they did before this existed.\n */\nexport function leavingNoticeConfig(options: {\n  hostId: string | null | undefined\n  site: SiteReturnHost | null | undefined\n  org: unknown\n  content?: unknown\n  nowMs?: number\n}): LeavingNoticeConfig | null {\n  const { hostId, site, org, content } = options\n  if (!hostId || !site) return null\n  const until = leavingNoticeEndsAt(org, options.nowMs)\n  if (until === null) return null\n  if (!canSign()) {\n    console.error(\n      '[leaving-notice] TOKEN_SIGNING_SECRET is not configured; the notice is off',\n    )\n    return null\n  }\n  const hosts = leavingNoticeHosts(site)\n  return {\n    until,\n    hosts,\n    sigs: signLeavingDestinations(\n      hostId,\n      collectLeavingDestinations(content, hosts),\n    ),\n  }\n}\n\n/**\n * Only the signatures, for a payload that arrives after its page — a gated\n * screen's nodes (`enrichGatedScreenPage`). `null` outside the window.\n */\nexport function leavingNoticeSignatures(options: {\n  hostId: string | null | undefined\n  site: SiteReturnHost | null | undefined\n  org: unknown\n  content: unknown\n  nowMs?: number\n}): Record<string, string> | null {\n  const config = leavingNoticeConfig(options)\n  return config && Object.keys(config.sigs).length ? config.sigs : null\n}\n"],"names":["createHmac","DOCS_BASE_URL","leavingDestination","normalizeLeavingDestination","resolveEffectivePlan","PLATFORM_HOME_URL","PLATFORM_SUPPORT_URL","platformConsoleOrigin","siteOwnHosts","TENANT_APEX","isYoungWorkspaceAge","OUTBOUND_REVIEW_YOUNG_DAYS","registrableDomain","tokenSigningSecret","orgAgeDays","orgCreatedMs","safeEqual","LEAVING_NOTICE_DAYS","DAY_MS","LEAVING_NOTICE_MAX_DESTINATIONS","MAX_WALK_DEPTH","MAX_SCANNED_STRING","leavingNoticeEndsAt","org","nowMs","Date","now","createdAt","createdMs","hostnameOf","raw","url","URL","protocol","hostname","toLowerCase","leavingNoticeHosts","site","hosts","Set","apex","add","apexRegistrable","registrable","includes","EMBEDDED_URL","TRAILING_PROSE","ADDRESS_SHAPE","collectLeavingDestinations","value","limit","found","consider","candidate","size","destination","scan","text","test","scanned","length","slice","match","matchAll","trimmed","replace","walk","node","depth","Array","isArray","item","Object","values","leavingSignature","hostId","update","digest","signLeavingDestination","normalized","Error","verifyLeavingDestination","signature","expected","signLeavingDestinations","destinations","sigs","canSign","leavingNoticeConfig","options","content","until","console","error","leavingNoticeSignatures","config","keys"],"mappings":"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"}

package/src/lib/server/link-reputation-review.d.ts

@@ -0,0 +1,58 @@
+/**
+ * @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.
+ */
+/** What one chunk of the re-check did. */
+export interface LivePageLinkRecheck {
+    /** Sites this chunk walked. */
+    sites: number;
+    /** Live pages with foreign links among them. */
+    pages: number;
+    /** Distinct foreign hosts looked up. */
+    hosts: number;
+    /** Distinct addresses looked up on them — none unless the lookup is in `'url'` mode. */
+    addresses: number;
+    /** Of the hosts and addresses, how many Web Risk lists. */
+    listed: number;
+    /** Hosts and addresses nobody could answer for: not evidence, looked up again next time. */
+    unknown: number;
+    /** Pages sent back through the review with a listed host. */
+    reviewed: number;
+    /** Of those, how many the review held (or found already rejected). */
+    held: number;
+    /** The sites a hold was placed on, whose cached pages need dropping. */
+    heldHostIds: string[];
+    /** Addresses' stored answers deleted a day after they expired (first chunk of a walk only). */
+    reapedAddressVerdicts: number;
+    nextCursor: string | null;
+    done: boolean;
+}
+/** Sites walked per chunk. */
+export declare const LINK_RECHECK_SITES_PER_CHUNK = 200;
+/**
+ * Re-check the foreign hosts of every live page, a chunk of sites at a time
+ * (`cursor` resumes after the last site of the previous chunk). A site that
+ * is locked is skipped: nothing of it serves. A page with a newly listed host
+ * goes back through {@link reviewHostedPage} with that listing as an extra
+ * signal, so what a hold does is decided in one place.
+ */
+export declare function recheckLivePageLinks(options?: {
+    cursor?: string | null;
+    sitesPerChunk?: number;
+    nowMs?: number;
+    firestore?: FirebaseFirestore.Firestore;
+    /** Walk and count only: no lookup, no review. */
+    dryRun?: boolean;
+}): Promise<LivePageLinkRecheck>;

package/src/lib/server/link-reputation-review.js

@@ -0,0 +1,185 @@
+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.
+ */ /*==========================================
+ * THE DAILY LINK RE-CHECK (AGL-3451).
+ *
+ * The page review (`hosted-page-review.ts`), the redirect review and the send
+ * seam look up every foreign host a page, a redirect or a message points at
+ * as it goes out. What is already live is not re-reviewed until somebody
+ * publishes it again — and a harvester is often listed only after the page
+ * linking to it went up.
+ *
+ * So {@link recheckLivePageLinks} walks every live page's foreign hosts, as
+ * the review noted them beside the version it served
+ * (`pageReviews/{screenId}.foreignHosts`), looks them up again — and, in
+ * `'url'` mode (AGL-3459), the addresses on them noted beside the hosts
+ * (`foreignLinks`, never a query string) — and sends each page with a newly
+ * listed host or address back through `reviewHostedPage` with the listing as
+ * an extra signal — the same path, so it is held or flagged, its row filed,
+ * and a young workspace's security hold requested (AGL-3450), exactly as at
+ * render. The console's `/api/admin/web-risk-recheck` runs it a chunk of
+ * sites at a time; its first chunk of a walk also deletes the addresses'
+ * stored answers that expired a day ago.
+ *=========================================*/ import { MAX_REPUTATION_HOSTS_PER_LOOKUP, MAX_REPUTATION_URLS_PER_LOOKUP, normalizeReputationLink, webRiskSignals } from "@aglyn/shared-util-email/link-reputation";
+import { FieldPath } from "firebase-admin/firestore";
+import firebaseAdmin from "./firebase-admin.js";
+import { PAGE_REVIEW_SUBCOLLECTION, reviewHostedPage } from "./hosted-page-review.js";
+import { lookupLinkReputation, reapExpiredWebRiskUrlVerdicts, webRiskLookupMode } from "./web-risk.js";
+/** Sites walked per chunk. */ export const LINK_RECHECK_SITES_PER_CHUNK = 200;
+/** Sites whose page notes are read at once. */ const SITE_READ_CONCURRENCY = 20;
+/** The budget of each group of hosts looked up within a chunk. */ const RECHECK_DEADLINE_MS = 15000;
+/**
+ * Re-check the foreign hosts of every live page, a chunk of sites at a time
+ * (`cursor` resumes after the last site of the previous chunk). A site that
+ * is locked is skipped: nothing of it serves. A page with a newly listed host
+ * goes back through {@link reviewHostedPage} with that listing as an extra
+ * signal, so what a hold does is decided in one place.
+ */ export async function recheckLivePageLinks(options = {}) {
+    var _options_firestore, _options_nowMs, _options_sitesPerChunk, _ref;
+    const firestore = (_options_firestore = options.firestore) != null ? _options_firestore : firebaseAdmin.app().firestore();
+    const nowMs = (_options_nowMs = options.nowMs) != null ? _options_nowMs : Date.now();
+    const limit = (_options_sitesPerChunk = options.sitesPerChunk) != null ? _options_sitesPerChunk : LINK_RECHECK_SITES_PER_CHUNK;
+    let query = firestore.collection('hosts').orderBy(FieldPath.documentId()).select('suspendedAt').limit(limit);
+    if (options.cursor) query = query.startAfter(options.cursor);
+    const sites = await query.get();
+    const pages = [];
+    const live = sites.docs.filter((site)=>site.get('suspendedAt') == null);
+    for(let at = 0; at < live.length; at += SITE_READ_CONCURRENCY){
+        const batch = live.slice(at, at + SITE_READ_CONCURRENCY);
+        const notes = await Promise.all(batch.map((site)=>site.ref.collection(PAGE_REVIEW_SUBCOLLECTION).where('foreignHostCount', '>', 0).limit(500).get().then((reviews)=>({
+                    site,
+                    reviews
+                }))));
+        for (const { site, reviews } of notes){
+            for (const review of reviews.docs){
+                const versionId = review.get('servedVersionId');
+                const hosts = review.get('foreignHosts');
+                const links = review.get('foreignLinks');
+                if (typeof versionId !== 'string' || !versionId || !Array.isArray(hosts)) continue;
+                pages.push({
+                    hostId: site.id,
+                    screenId: review.id,
+                    versionId,
+                    hosts: hosts.filter((host)=>typeof host === 'string'),
+                    links: Array.isArray(links) ? links.filter((link)=>typeof link === 'string') : []
+                });
+            }
+        }
+    }
+    const distinct = [
+        ...new Set(pages.flatMap((page)=>page.hosts))
+    ];
+    const last = sites.docs[sites.docs.length - 1];
+    const chunk = {
+        sites: sites.size,
+        pages: pages.length,
+        hosts: distinct.length,
+        nextCursor: sites.size < limit ? null : (_ref = last == null ? void 0 : last.id) != null ? _ref : null,
+        done: sites.size < limit
+    };
+    if (options.dryRun) {
+        return _extends({}, chunk, {
+            addresses: 0,
+            listed: 0,
+            unknown: 0,
+            reviewed: 0,
+            held: 0,
+            heldHostIds: [],
+            reapedAddressVerdicts: 0
+        });
+    }
+    // Once a walk, before its first chunk: addresses' answers long expired.
+    const reapedAddressVerdicts = options.cursor ? 0 : await reapExpiredWebRiskUrlVerdicts({
+        nowMs,
+        firestore
+    });
+    // The addresses go with their hosts, and only in 'url' mode.
+    const mode = await webRiskLookupMode(nowMs);
+    const addressHost = new Map();
+    if (mode === 'url') {
+        for (const link of new Set(pages.flatMap((page)=>page.links))){
+            var _normalizeReputationLink;
+            const host = (_normalizeReputationLink = normalizeReputationLink(link)) == null ? void 0 : _normalizeReputationLink.host;
+            if (host) addressHost.set(link, host);
+        }
+    }
+    // Keyed by host for a host's listing, by address for an address's: an
+    // address always holds `://`, a host never does.
+    const listed = new Map();
+    const unknown = new Set();
+    for(let at = 0; at < distinct.length; at += MAX_REPUTATION_HOSTS_PER_LOOKUP){
+        const group = distinct.slice(at, at + MAX_REPUTATION_HOSTS_PER_LOOKUP);
+        const inGroup = new Set(group);
+        const urls = [
+            ...addressHost
+        ].filter(([, host])=>inGroup.has(host)).map(([url])=>url);
+        // A later slice of addresses finds the group's answered hosts in memory.
+        let offset = 0;
+        do {
+            var _hit_url;
+            const answer = await lookupLinkReputation(group, {
+                urls: urls.slice(offset, offset + MAX_REPUTATION_URLS_PER_LOOKUP),
+                deadlineMs: RECHECK_DEADLINE_MS,
+                nowMs
+            });
+            for (const hit of answer.hits)listed.set((_hit_url = hit.url) != null ? _hit_url : hit.host, hit);
+            for (const key of answer.unknown)unknown.add(key);
+            offset += MAX_REPUTATION_URLS_PER_LOOKUP;
+        }while (offset < urls.length)
+    }
+    let reviewed = 0;
+    let held = 0;
+    const heldHostIds = new Set();
+    for (const page of pages){
+        const hits = [
+            ...page.hosts,
+            ...page.links
+        ].map((key)=>listed.get(key)).filter(Boolean);
+        if (!hits.length) continue;
+        reviewed += 1;
+        try {
+            const outcome = await reviewHostedPage({
+                hostId: page.hostId,
+                screenId: page.screenId,
+                versionId: page.versionId,
+                // The page itself is not composed here: the listing is the finding.
+                nodes: {},
+                extraSignals: webRiskSignals(hits),
+                nowMs
+            });
+            if (outcome.outcome !== 'serve') {
+                held += 1;
+                heldHostIds.add(page.hostId);
+            }
+        } catch (error) {
+            console.error('[link-reputation] a live page could not be re-reviewed', page.hostId, page.screenId, error);
+        }
+    }
+    return _extends({}, chunk, {
+        addresses: addressHost.size,
+        listed: listed.size,
+        unknown: unknown.size,
+        reviewed,
+        held,
+        heldHostIds: [
+            ...heldHostIds
+        ],
+        reapedAddressVerdicts
+    });
+}
+
+//# sourceMappingURL=link-reputation-review.js.map

package/src/lib/server/link-reputation-review.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/link-reputation-review.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\n/*==========================================\n * THE DAILY LINK RE-CHECK (AGL-3451).\n *\n * The page review (`hosted-page-review.ts`), the redirect review and the send\n * seam look up every foreign host a page, a redirect or a message points at\n * as it goes out. What is already live is not re-reviewed until somebody\n * publishes it again — and a harvester is often listed only after the page\n * linking to it went up.\n *\n * So {@link recheckLivePageLinks} walks every live page's foreign hosts, as\n * the review noted them beside the version it served\n * (`pageReviews/{screenId}.foreignHosts`), looks them up again — and, in\n * `'url'` mode (AGL-3459), the addresses on them noted beside the hosts\n * (`foreignLinks`, never a query string) — and sends each page with a newly\n * listed host or address back through `reviewHostedPage` with the listing as\n * an extra signal — the same path, so it is held or flagged, its row filed,\n * and a young workspace's security hold requested (AGL-3450), exactly as at\n * render. The console's `/api/admin/web-risk-recheck` runs it a chunk of\n * sites at a time; its first chunk of a walk also deletes the addresses'\n * stored answers that expired a day ago.\n *=========================================*/\n\nimport {\n  type HostReputationHit,\n  MAX_REPUTATION_HOSTS_PER_LOOKUP,\n  MAX_REPUTATION_URLS_PER_LOOKUP,\n  normalizeReputationLink,\n  webRiskSignals,\n} from '@aglyn/shared-util-email/link-reputation'\nimport { FieldPath } from 'firebase-admin/firestore'\nimport firebaseAdmin from './firebase-admin'\nimport { PAGE_REVIEW_SUBCOLLECTION, reviewHostedPage } from './hosted-page-review'\nimport { lookupLinkReputation, reapExpiredWebRiskUrlVerdicts, webRiskLookupMode } from './web-risk'\n\n/** One live page whose foreign hosts the review noted. */\ninterface LivePageLinks {\n  hostId: string\n  screenId: string\n  versionId: string\n  hosts: string[]\n  /** The addresses on those hosts the review noted (AGL-3459); empty before it did. */\n  links: string[]\n}\n\n/** What one chunk of the re-check did. */\nexport interface LivePageLinkRecheck {\n  /** Sites this chunk walked. */\n  sites: number\n  /** Live pages with foreign links among them. */\n  pages: number\n  /** Distinct foreign hosts looked up. */\n  hosts: number\n  /** Distinct addresses looked up on them — none unless the lookup is in `'url'` mode. */\n  addresses: number\n  /** Of the hosts and addresses, how many Web Risk lists. */\n  listed: number\n  /** Hosts and addresses nobody could answer for: not evidence, looked up again next time. */\n  unknown: number\n  /** Pages sent back through the review with a listed host. */\n  reviewed: number\n  /** Of those, how many the review held (or found already rejected). */\n  held: number\n  /** The sites a hold was placed on, whose cached pages need dropping. */\n  heldHostIds: string[]\n  /** Addresses' stored answers deleted a day after they expired (first chunk of a walk only). */\n  reapedAddressVerdicts: number\n  nextCursor: string | null\n  done: boolean\n}\n\n/** Sites walked per chunk. */\nexport const LINK_RECHECK_SITES_PER_CHUNK = 200\n/** Sites whose page notes are read at once. */\nconst SITE_READ_CONCURRENCY = 20\n/** The budget of each group of hosts looked up within a chunk. */\nconst RECHECK_DEADLINE_MS = 15_000\n\n/**\n * Re-check the foreign hosts of every live page, a chunk of sites at a time\n * (`cursor` resumes after the last site of the previous chunk). A site that\n * is locked is skipped: nothing of it serves. A page with a newly listed host\n * goes back through {@link reviewHostedPage} with that listing as an extra\n * signal, so what a hold does is decided in one place.\n */\nexport async function recheckLivePageLinks(\n  options: {\n    cursor?: string | null\n    sitesPerChunk?: number\n    nowMs?: number\n    firestore?: FirebaseFirestore.Firestore\n    /** Walk and count only: no lookup, no review. */\n    dryRun?: boolean\n  } = {},\n): Promise<LivePageLinkRecheck> {\n  const firestore = options.firestore ?? firebaseAdmin.app().firestore()\n  const nowMs = options.nowMs ?? Date.now()\n  const limit = options.sitesPerChunk ?? LINK_RECHECK_SITES_PER_CHUNK\n  let query = firestore\n    .collection('hosts')\n    .orderBy(FieldPath.documentId())\n    .select('suspendedAt')\n    .limit(limit)\n  if (options.cursor) query = query.startAfter(options.cursor)\n  const sites = await query.get()\n\n  const pages: LivePageLinks[] = []\n  const live = sites.docs.filter((site) => site.get('suspendedAt') == null)\n  for (let at = 0; at < live.length; at += SITE_READ_CONCURRENCY) {\n    const batch = live.slice(at, at + SITE_READ_CONCURRENCY)\n    const notes = await Promise.all(\n      batch.map((site) =>\n        site.ref\n          .collection(PAGE_REVIEW_SUBCOLLECTION)\n          .where('foreignHostCount', '>', 0)\n          .limit(500)\n          .get()\n          .then((reviews) => ({ site, reviews })),\n      ),\n    )\n    for (const { site, reviews } of notes) {\n      for (const review of reviews.docs) {\n        const versionId = review.get('servedVersionId')\n        const hosts = review.get('foreignHosts')\n        const links = review.get('foreignLinks')\n        if (typeof versionId !== 'string' || !versionId || !Array.isArray(hosts)) continue\n        pages.push({\n          hostId: site.id,\n          screenId: review.id,\n          versionId,\n          hosts: hosts.filter((host): host is string => typeof host === 'string'),\n          links: Array.isArray(links) ? links.filter((link): link is string => typeof link === 'string') : [],\n        })\n      }\n    }\n  }\n\n  const distinct = [...new Set(pages.flatMap((page) => page.hosts))]\n  const last = sites.docs[sites.docs.length - 1]\n  const chunk = {\n    sites: sites.size,\n    pages: pages.length,\n    hosts: distinct.length,\n    nextCursor: sites.size < limit ? null : (last?.id ?? null),\n    done: sites.size < limit,\n  }\n  if (options.dryRun) {\n    return {\n      ...chunk,\n      addresses: 0,\n      listed: 0,\n      unknown: 0,\n      reviewed: 0,\n      held: 0,\n      heldHostIds: [],\n      reapedAddressVerdicts: 0,\n    }\n  }\n  // Once a walk, before its first chunk: addresses' answers long expired.\n  const reapedAddressVerdicts = options.cursor\n    ? 0\n    : await reapExpiredWebRiskUrlVerdicts({ nowMs, firestore })\n\n  // The addresses go with their hosts, and only in 'url' mode.\n  const mode = await webRiskLookupMode(nowMs)\n  const addressHost = new Map<string, string>()\n  if (mode === 'url') {\n    for (const link of new Set(pages.flatMap((page) => page.links))) {\n      const host = normalizeReputationLink(link)?.host\n      if (host) addressHost.set(link, host)\n    }\n  }\n  // Keyed by host for a host's listing, by address for an address's: an\n  // address always holds `://`, a host never does.\n  const listed = new Map<string, HostReputationHit>()\n  const unknown = new Set<string>()\n  for (let at = 0; at < distinct.length; at += MAX_REPUTATION_HOSTS_PER_LOOKUP) {\n    const group = distinct.slice(at, at + MAX_REPUTATION_HOSTS_PER_LOOKUP)\n    const inGroup = new Set(group)\n    const urls = [...addressHost].filter(([, host]) => inGroup.has(host)).map(([url]) => url)\n    // A later slice of addresses finds the group's answered hosts in memory.\n    let offset = 0\n    do {\n      const answer = await lookupLinkReputation(group, {\n        urls: urls.slice(offset, offset + MAX_REPUTATION_URLS_PER_LOOKUP),\n        deadlineMs: RECHECK_DEADLINE_MS,\n        nowMs,\n      })\n      for (const hit of answer.hits) listed.set(hit.url ?? hit.host, hit)\n      for (const key of answer.unknown) unknown.add(key)\n      offset += MAX_REPUTATION_URLS_PER_LOOKUP\n    } while (offset < urls.length)\n  }\n\n  let reviewed = 0\n  let held = 0\n  const heldHostIds = new Set<string>()\n  for (const page of pages) {\n    const hits = [...page.hosts, ...page.links]\n      .map((key) => listed.get(key))\n      .filter(Boolean) as HostReputationHit[]\n    if (!hits.length) continue\n    reviewed += 1\n    try {\n      const outcome = await reviewHostedPage({\n        hostId: page.hostId,\n        screenId: page.screenId,\n        versionId: page.versionId,\n        // The page itself is not composed here: the listing is the finding.\n        nodes: {},\n        extraSignals: webRiskSignals(hits),\n        nowMs,\n      })\n      if (outcome.outcome !== 'serve') {\n        held += 1\n        heldHostIds.add(page.hostId)\n      }\n    } catch (error) {\n      console.error('[link-reputation] a live page could not be re-reviewed', page.hostId, page.screenId, error)\n    }\n  }\n\n  return {\n    ...chunk,\n    addresses: addressHost.size,\n    listed: listed.size,\n    unknown: unknown.size,\n    reviewed,\n    held,\n    heldHostIds: [...heldHostIds],\n    reapedAddressVerdicts,\n  }\n}\n"],"names":["MAX_REPUTATION_HOSTS_PER_LOOKUP","MAX_REPUTATION_URLS_PER_LOOKUP","normalizeReputationLink","webRiskSignals","FieldPath","firebaseAdmin","PAGE_REVIEW_SUBCOLLECTION","reviewHostedPage","lookupLinkReputation","reapExpiredWebRiskUrlVerdicts","webRiskLookupMode","LINK_RECHECK_SITES_PER_CHUNK","SITE_READ_CONCURRENCY","RECHECK_DEADLINE_MS","recheckLivePageLinks","options","firestore","app","nowMs","Date","now","limit","sitesPerChunk","query","collection","orderBy","documentId","select","cursor","startAfter","sites","get","pages","live","docs","filter","site","at","length","batch","slice","notes","Promise","all","map","ref","where","then","reviews","review","versionId","hosts","links","Array","isArray","push","hostId","id","screenId","host","link","distinct","Set","flatMap","page","last","chunk","size","nextCursor","done","dryRun","addresses","listed","unknown","reviewed","held","heldHostIds","reapedAddressVerdicts","mode","addressHost","Map","set","group","inGroup","urls","has","url","offset","hit","answer","deadlineMs","hits","key","add","Boolean","outcome","nodes","extraSignals","error","console"],"mappings":"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"}

package/src/lib/server/live-page-drops.d.ts

@@ -0,0 +1,67 @@
+/**
+ * @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.
+ */
+/**
+ * HOW THIS PROCESS DROPS ONE SITE'S CACHED PAGES, for a write that worked out
+ * which of them it made stale (AGL-3113, AGL-3080).
+ *
+ * A record write — a dataset row, a collection entry — refreshes the pages
+ * that show it, and nothing else. Working out WHICH pages is the writer's: the
+ * data plugin walks the pages that repeat over a dataset, the collection scan
+ * the pages that list an entry. HOW a page is dropped is the runtime's, and
+ * the two runtimes do it differently: the tenant drops its own caches in
+ * process, and the console announces over the shared secret and passes its own
+ * dropper at the call site. So the deployment that owns the caches registers
+ * the dropper here, and a writer reads it; neither names the other.
+ *
+ * ## One per process, on `globalThis`
+ *
+ * The tenant registers from `instrumentation.ts`, by name, at boot. Next
+ * compiles that file apart from the routes, so a dropper held in a module
+ * `let` was set in the boot's copy of this module and read as missing by
+ * every route's copy — a form submission or an automation step that wrote a
+ * row logged `no-live-page-dropper` and left the pages stale for the rest of
+ * their window (AGL-3412 was the same split for the plugin services). Keyed on
+ * `globalThis` under `Symbol.for`, every copy in a realm reads the one slot.
+ */
+/** One site's share of a change: the pages on it that must be dropped. */
+export interface LivePageTarget {
+    hostId: string;
+    /** The tenant keys its cache on this, never on `hostId`. */
+    subdomain: string;
+    /** The attached custom domain, whose pages live under a second cache key. */
+    cname?: string;
+    /** Site-absolute addresses (`/`, `/team`) the change makes stale. */
+    paths: string[];
+    /** The site held more documents than the scan read, so `paths` is partial. */
+    truncated: boolean;
+}
+/**
+ * Drops one site's cached pages. Returns whether the drop landed. It must
+ * never throw: everything above it has already been written.
+ */
+export type LivePageDropper = (target: LivePageTarget) => Promise<boolean>;
+/**
+ * Registers the dropper for this process, replacing any previous one. Returns
+ * the unregister, which removes it only if it is still the one registered.
+ *
+ * Called from a function the platform calls BY NAME at boot, never from a
+ * module's top level: a bundler deletes a module imported only for its side
+ * effect when its package says it has none (AGL-3025).
+ */
+export declare function registerLivePageDropper(drop: LivePageDropper): () => void;
+/** The dropper this process registered, or `undefined` when none did. */
+export declare function registeredLivePageDropper(): LivePageDropper | undefined;

package/src/lib/server/live-page-drops.js

@@ -0,0 +1,57 @@
+/**
+ * @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.
+ */ /**
+ * HOW THIS PROCESS DROPS ONE SITE'S CACHED PAGES, for a write that worked out
+ * which of them it made stale (AGL-3113, AGL-3080).
+ *
+ * A record write — a dataset row, a collection entry — refreshes the pages
+ * that show it, and nothing else. Working out WHICH pages is the writer's: the
+ * data plugin walks the pages that repeat over a dataset, the collection scan
+ * the pages that list an entry. HOW a page is dropped is the runtime's, and
+ * the two runtimes do it differently: the tenant drops its own caches in
+ * process, and the console announces over the shared secret and passes its own
+ * dropper at the call site. So the deployment that owns the caches registers
+ * the dropper here, and a writer reads it; neither names the other.
+ *
+ * ## One per process, on `globalThis`
+ *
+ * The tenant registers from `instrumentation.ts`, by name, at boot. Next
+ * compiles that file apart from the routes, so a dropper held in a module
+ * `let` was set in the boot's copy of this module and read as missing by
+ * every route's copy — a form submission or an automation step that wrote a
+ * row logged `no-live-page-dropper` and left the pages stale for the rest of
+ * their window (AGL-3412 was the same split for the plugin services). Keyed on
+ * `globalThis` under `Symbol.for`, every copy in a realm reads the one slot.
+ */ /** One site's share of a change: the pages on it that must be dropped. */ const DROPPER_KEY = Symbol.for('@aglyn/tenant-data-admin:live-page-dropper');
+const globalScope = globalThis;
+/**
+ * Registers the dropper for this process, replacing any previous one. Returns
+ * the unregister, which removes it only if it is still the one registered.
+ *
+ * Called from a function the platform calls BY NAME at boot, never from a
+ * module's top level: a bundler deletes a module imported only for its side
+ * effect when its package says it has none (AGL-3025).
+ */ export function registerLivePageDropper(drop) {
+    globalScope[DROPPER_KEY] = drop;
+    return ()=>{
+        if (globalScope[DROPPER_KEY] === drop) delete globalScope[DROPPER_KEY];
+    };
+}
+/** The dropper this process registered, or `undefined` when none did. */ export function registeredLivePageDropper() {
+    return globalScope[DROPPER_KEY];
+}
+
+//# sourceMappingURL=live-page-drops.js.map

package/src/lib/server/live-page-drops.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/live-page-drops.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\n/**\n * HOW THIS PROCESS DROPS ONE SITE'S CACHED PAGES, for a write that worked out\n * which of them it made stale (AGL-3113, AGL-3080).\n *\n * A record write — a dataset row, a collection entry — refreshes the pages\n * that show it, and nothing else. Working out WHICH pages is the writer's: the\n * data plugin walks the pages that repeat over a dataset, the collection scan\n * the pages that list an entry. HOW a page is dropped is the runtime's, and\n * the two runtimes do it differently: the tenant drops its own caches in\n * process, and the console announces over the shared secret and passes its own\n * dropper at the call site. So the deployment that owns the caches registers\n * the dropper here, and a writer reads it; neither names the other.\n *\n * ## One per process, on `globalThis`\n *\n * The tenant registers from `instrumentation.ts`, by name, at boot. Next\n * compiles that file apart from the routes, so a dropper held in a module\n * `let` was set in the boot's copy of this module and read as missing by\n * every route's copy — a form submission or an automation step that wrote a\n * row logged `no-live-page-dropper` and left the pages stale for the rest of\n * their window (AGL-3412 was the same split for the plugin services). Keyed on\n * `globalThis` under `Symbol.for`, every copy in a realm reads the one slot.\n */\n\n/** One site's share of a change: the pages on it that must be dropped. */\nexport interface LivePageTarget {\n  hostId: string\n  /** The tenant keys its cache on this, never on `hostId`. */\n  subdomain: string\n  /** The attached custom domain, whose pages live under a second cache key. */\n  cname?: string\n  /** Site-absolute addresses (`/`, `/team`) the change makes stale. */\n  paths: string[]\n  /** The site held more documents than the scan read, so `paths` is partial. */\n  truncated: boolean\n}\n\n/**\n * Drops one site's cached pages. Returns whether the drop landed. It must\n * never throw: everything above it has already been written.\n */\nexport type LivePageDropper = (target: LivePageTarget) => Promise<boolean>\n\nconst DROPPER_KEY = Symbol.for('@aglyn/tenant-data-admin:live-page-dropper')\n\nconst globalScope = globalThis as typeof globalThis & {\n  [DROPPER_KEY]?: LivePageDropper\n}\n\n/**\n * Registers the dropper for this process, replacing any previous one. Returns\n * the unregister, which removes it only if it is still the one registered.\n *\n * Called from a function the platform calls BY NAME at boot, never from a\n * module's top level: a bundler deletes a module imported only for its side\n * effect when its package says it has none (AGL-3025).\n */\nexport function registerLivePageDropper(drop: LivePageDropper): () => void {\n  globalScope[DROPPER_KEY] = drop\n  return () => {\n    if (globalScope[DROPPER_KEY] === drop) delete globalScope[DROPPER_KEY]\n  }\n}\n\n/** The dropper this process registered, or `undefined` when none did. */\nexport function registeredLivePageDropper(): LivePageDropper | undefined {\n  return globalScope[DROPPER_KEY]\n}\n"],"names":["DROPPER_KEY","Symbol","for","globalScope","globalThis","registerLivePageDropper","drop","registeredLivePageDropper"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;CAsBC,GAED,wEAAwE,GAmBxE,MAAMA,cAAcC,OAAOC,GAAG,CAAC;AAE/B,MAAMC,cAAcC;AAIpB;;;;;;;CAOC,GACD,OAAO,SAASC,wBAAwBC,IAAqB;IAC3DH,WAAW,CAACH,YAAY,GAAGM;IAC3B,OAAO;QACL,IAAIH,WAAW,CAACH,YAAY,KAAKM,MAAM,OAAOH,WAAW,CAACH,YAAY;IACxE;AACF;AAEA,uEAAuE,GACvE,OAAO,SAASO;IACd,OAAOJ,WAAW,CAACH,YAAY;AACjC"}

package/src/lib/server/media-bandwidth-cap.d.ts

@@ -0,0 +1,78 @@
+/**
+ * @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.
+ */
+/**
+ * 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 declare const MEDIA_BANDWIDTH_EVALUATE_EVERY_BYTES: number;
+/** Drop the per-instance state. Tests need it between cases. */
+export declare function invalidateMediaBandwidthCapState(): void;
+/**
+ * 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 declare function mediaBandwidthEvaluationDue(orgId: string, bytes: number, now?: Date): boolean;
+/**
+ * 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 declare function engageMediaBandwidthCap(orgId: string, now?: Date): Promise<boolean>;