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

package/src/lib/server/csp-aggregate.js

@@ -0,0 +1,276 @@
+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.
+ */ /**
+ * Durable CSP-violation aggregates (AGL-1799).
+ *
+ * The collectors were delivering reports into a sink that forgets: the Vercel
+ * runtime log retains ~60 minutes and there is no log drain, so AGL-1702's
+ * "a week of signed-in traffic" and AGL-1726's "a business week of visitor
+ * traffic" were gated on evidence that structurally could not exist. This
+ * module is the durable half — the log lines stay exactly as they were (they
+ * are still the right tool for the last hour), and every accepted violation
+ * ALSO compounds into a Firestore counter that holds for the retention window.
+ *
+ * ## Shape: counters, never report bodies
+ *
+ * One document per (UTC day x app x directive x disposition x blocked origin),
+ * with `FieldValue.increment` — NOT one document per report. AGL-523 made a
+ * deliberate choice not to write report bodies to Firestore from an
+ * unauthenticated route, and AGL-1799 argued the distinction explicitly: "a
+ * counter with a bounded key space is a different proposition from storing
+ * report bodies". The bound is what this module is careful about, because
+ * every key ingredient except the day is attacker-influenced:
+ *
+ *  - the DIRECTIVE is normalized into a closed set (a real browser can only
+ *    ever send a spec directive; anything else lands in `other` rather than
+ *    minting a document per invented directive);
+ *  - the ORIGIN is reduced to the host of `blocked-uri` (or its bare keyword
+ *    — `inline`, `eval`, `data`), sanitized to a fixed character set, and
+ *    capped: at most {@link MAX_DISTINCT_ORIGINS_PER_DAY} distinct origins per
+ *    (day x app x directive) may mint documents per instance per day. Beyond
+ *    that, new origins are dropped while known ones keep counting — a flood
+ *    of unique URLs (the AGL-1769 lesson: never let request content mint
+ *    unbounded documents) saturates the cap instead of the collection;
+ *  - WRITES are budgeted per instance per minute, so a POST flood cannot turn
+ *    an unauthenticated beacon into a Firestore write bill even against
+ *    already-minted documents.
+ *
+ * Every cap here is per instance, like the tenant collector's `keyStore`: the
+ * fleet-wide worst case is (instances x cap), which is bounded and small,
+ * and an instance recycle merely re-counts an origin against a fresh cap —
+ * the merge write is idempotent about which document it lands in.
+ *
+ * ## Ids are attacker-derived, so they go through `isDocumentId`
+ *
+ * Key parts are sanitized to `[a-z0-9.:_-]` and joined with `|`, then the
+ * whole id is checked with {@link isDocumentId} (the AGL-1771 predicate —
+ * imported from its leaf, `./document-id`, which imports nothing). Belt and
+ * braces: the sanitizer already removes `/` and the joiner makes a reserved
+ * `__x__` form impossible, but the predicate is the contract and it is
+ * cheaper to check than to argue.
+ *
+ * ## Retention is TTL, not a sweep
+ *
+ * `expiresAt` (a Timestamp — TTL refuses numbers) is set
+ * {@link CSP_AGGREGATE_RETENTION_DAYS} days past the day bucket. The TTL
+ * policy is a gcloud action plus a `fieldOverrides` entry in
+ * `cloud/firebase-firestore.indexes.json` — see
+ * docs/FIRESTORE_MANUAL_CONFIG.md (AGL-1793): the entry ships with this
+ * module and the gcloud enable is owed at deploy time.
+ *
+ * ## Fail-soft, like everything on this path
+ *
+ * A collector must never turn an observed problem into a served one. Every
+ * failure here — no credential, Firestore down, a hostile id that survives
+ * sanitization — drops the aggregate (one `console.error` line, tagged) and
+ * returns. The log lines the collectors already emit are unaffected.
+ *
+ * No client ever reads or writes this collection: there is no rules `match`
+ * for it, and Firestore denies what nothing matches, so the Admin SDK is the
+ * only path in. The staff read-back is `/api/admin/csp-reports` on the
+ * console.
+ */ import { FieldValue } from "firebase-admin/firestore";
+import { isDocumentId } from "./document-id.js";
+/** Top-level collection of counter documents. Server-only; no rules match. */ export const CSP_AGGREGATE_COLLECTION = 'cspViolationDaily';
+/**
+ * Long enough that "a week of traffic" (AGL-1702 condition 1, AGL-1726
+ * condition 3) is readable with room to be read late, short enough that the
+ * collection stays a working set rather than an archive.
+ */ export const CSP_AGGREGATE_RETENTION_DAYS = 60;
+/**
+ * Distinct blocked origins that may mint documents per (day x app x
+ * directive), per instance. A legitimate policy violates against a handful of
+ * hosts; thirty is generous headroom for a real regression while keeping a
+ * flood of attacker-invented origins from minting unbounded documents.
+ */ export const MAX_DISTINCT_ORIGINS_PER_DAY = 30;
+/**
+ * Aggregate writes allowed per instance per minute. Distinct-origin capping
+ * bounds document COUNT; this bounds write OPS, which are billed even when
+ * they land on existing documents. Sized far above what real browsers on one
+ * instance produce and far below what makes a flood expensive.
+ */ const WRITE_BUDGET_PER_MINUTE = 120;
+/**
+ * The directives a browser can actually report, per the CSP3 registry. An
+ * unrecognized directive is a non-browser caller (or a future spec revision)
+ * and shares one bucket rather than minting its own key space.
+ */ const KNOWN_DIRECTIVES = new Set([
+    'base-uri',
+    'block-all-mixed-content',
+    'child-src',
+    'connect-src',
+    'default-src',
+    'font-src',
+    'form-action',
+    'frame-ancestors',
+    'frame-src',
+    'img-src',
+    'manifest-src',
+    'media-src',
+    'object-src',
+    'prefetch-src',
+    'script-src',
+    'script-src-attr',
+    'script-src-elem',
+    'style-src',
+    'style-src-attr',
+    'style-src-elem',
+    'upgrade-insecure-requests',
+    'worker-src'
+]);
+/**
+ * Per-instance mint tracker: (day|app|directive) to the origin|disposition
+ * pairs that have been allowed to mint documents. Cleared wholesale at the
+ * cap, like the tenant collector's `keyStore`: the failure mode of clearing
+ * is a brief widening of the mint cap, strictly better than an unbounded map
+ * fed by attacker-chosen keys.
+ */ const mintTracker = new Map();
+const MAX_TRACKED_GROUPS = 512;
+/** Per-instance write budget window. */ let budgetWindowStartMs = 0;
+let budgetUsed = 0;
+/** Test seam: module-scope state would otherwise leak across cases. */ export function resetCspAggregateStateForTests() {
+    mintTracker.clear();
+    budgetWindowStartMs = 0;
+    budgetUsed = 0;
+}
+/** One id/field component: lowercase, fixed charset, never empty. */ function sanitizePart(value, max) {
+    const cleaned = value.toLowerCase().replace(/[^a-z0-9.:_-]+/g, '-').slice(0, max);
+    return cleaned || 'unknown';
+}
+/**
+ * `blocked-uri` reduced to the coarsest thing worth counting: the HOST for a
+ * URL, the bare keyword (`inline`, `eval`, `data`, ...) otherwise. Paths are
+ * deliberately dropped — twelve chunk URLs off one CDN are one origin-level
+ * fact (the AGL-1779 shape), and a path would both explode the key space and
+ * hand the id to whoever controls the URL.
+ */ export function cspBlockedOrigin(blockedUri) {
+    if (!blockedUri) return 'none';
+    try {
+        return sanitizePart(new URL(blockedUri).host, 120);
+    } catch (unused) {
+        return sanitizePart(blockedUri, 40);
+    }
+}
+/** UTC day bucket, `YYYY-MM-DD`. */ export function cspAggregateDay(nowMs) {
+    return new Date(nowMs).toISOString().slice(0, 10);
+}
+function normalizeDirective(directive) {
+    return KNOWN_DIRECTIVES.has(directive) ? directive : 'other';
+}
+/**
+ * Compound `violations` into the daily counters. Never throws; returns how
+ * many documents were written (0 on any failure, budget exhaustion included).
+ */ export async function recordCspViolations(violations, options) {
+    try {
+        var _options_now, _options_firestore;
+        if (!violations.length) return 0;
+        const now = (_options_now = options.now) != null ? _options_now : Date.now();
+        const day = cspAggregateDay(now);
+        const dayStartMs = Date.parse(`${day}T00:00:00.000Z`);
+        // Group first: N occurrences of one key in a batch are ONE write carrying
+        // increment(N), so a page that repeats itself costs one op, not N.
+        const grouped = new Map();
+        for (const violation of violations){
+            const directive = normalizeDirective(violation.effectiveDirective);
+            const origin = cspBlockedOrigin(violation.blockedUri);
+            const disposition = sanitizePart(violation.disposition || 'report', 16);
+            const id = [
+                day,
+                options.app,
+                sanitizePart(directive, 64),
+                disposition,
+                origin
+            ].join('|');
+            // Belt and braces — the AGL-1771 contract for anything handed to
+            // `.doc()`. The sanitizer above should make this unreachable.
+            if (!isDocumentId(id)) continue;
+            const existing = grouped.get(id);
+            if (existing) {
+                existing.n += 1;
+                continue;
+            }
+            // Distinct-origin cap, per (day x app x directive). Known pairs keep
+            // counting; new pairs beyond the cap are dropped — bounded documents
+            // is the property, not perfect counts.
+            const groupKey = `${day}|${options.app}|${directive}`;
+            if (mintTracker.size > MAX_TRACKED_GROUPS) mintTracker.clear();
+            let minted = mintTracker.get(groupKey);
+            if (!minted) {
+                minted = new Set();
+                mintTracker.set(groupKey, minted);
+            }
+            const pair = `${disposition}|${origin}`;
+            if (!minted.has(pair)) {
+                if (minted.size >= MAX_DISTINCT_ORIGINS_PER_DAY) continue;
+                minted.add(pair);
+            }
+            grouped.set(id, {
+                n: 1,
+                directive,
+                origin,
+                violation
+            });
+        }
+        if (!grouped.size) return 0;
+        // Write budget: fixed one-minute window per instance.
+        if (now - budgetWindowStartMs >= 60000) {
+            budgetWindowStartMs = now;
+            budgetUsed = 0;
+        }
+        const room = WRITE_BUDGET_PER_MINUTE - budgetUsed;
+        if (room <= 0) return 0;
+        const entries = [
+            ...grouped.entries()
+        ].slice(0, room);
+        budgetUsed += entries.length;
+        const firestore = (_options_firestore = options.firestore) != null ? _options_firestore : // Lazily resolved so this module stays inert at load: route specs and
+        // this module's own spec inject a fake, and nothing initializes
+        // firebase-admin just by importing the barrel.
+        (await import("./firebase-admin.js")).firebaseAdmin.app().firestore();
+        await Promise.all(entries.map(([id, { n, directive, origin, violation }])=>firestore.collection(CSP_AGGREGATE_COLLECTION).doc(id).set(_extends({
+                day,
+                app: options.app,
+                directive,
+                origin,
+                disposition: sanitizePart(violation.disposition || 'report', 16),
+                count: FieldValue.increment(n),
+                lastSeenMs: now,
+                // Samples, not keys: enough to find the surface, no power to
+                // mint documents. Already clamped by the parser; clamped again
+                // because this module's contract should not depend on that.
+                lastPath: violation.documentPath.slice(0, 200)
+            }, options.site ? {
+                lastSite: options.site.slice(0, 253)
+            } : {}, {
+                // Timestamp-typed via Date — Firestore TTL refuses numbers.
+                expiresAt: new Date(dayStartMs + CSP_AGGREGATE_RETENTION_DAYS * 86400000)
+            }), {
+                merge: true
+            })));
+        return entries.length;
+    } catch (error) {
+        // Fail-soft: the aggregate is an observer, and `console.error` rather
+        // than `console.warn` on purpose — the collectors' own log lines are
+        // warns, and their specs count warns.
+        console.error(JSON.stringify({
+            tag: 'AGL-1799:csp-aggregate',
+            error: String(error).slice(0, 200)
+        }));
+        return 0;
+    }
+}
+
+//# sourceMappingURL=csp-aggregate.js.map

package/src/lib/server/csp-aggregate.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/csp-aggregate.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 * Durable CSP-violation aggregates (AGL-1799).\n *\n * The collectors were delivering reports into a sink that forgets: the Vercel\n * runtime log retains ~60 minutes and there is no log drain, so AGL-1702's\n * \"a week of signed-in traffic\" and AGL-1726's \"a business week of visitor\n * traffic\" were gated on evidence that structurally could not exist. This\n * module is the durable half — the log lines stay exactly as they were (they\n * are still the right tool for the last hour), and every accepted violation\n * ALSO compounds into a Firestore counter that holds for the retention window.\n *\n * ## Shape: counters, never report bodies\n *\n * One document per (UTC day x app x directive x disposition x blocked origin),\n * with `FieldValue.increment` — NOT one document per report. AGL-523 made a\n * deliberate choice not to write report bodies to Firestore from an\n * unauthenticated route, and AGL-1799 argued the distinction explicitly: \"a\n * counter with a bounded key space is a different proposition from storing\n * report bodies\". The bound is what this module is careful about, because\n * every key ingredient except the day is attacker-influenced:\n *\n *  - the DIRECTIVE is normalized into a closed set (a real browser can only\n *    ever send a spec directive; anything else lands in `other` rather than\n *    minting a document per invented directive);\n *  - the ORIGIN is reduced to the host of `blocked-uri` (or its bare keyword\n *    — `inline`, `eval`, `data`), sanitized to a fixed character set, and\n *    capped: at most {@link MAX_DISTINCT_ORIGINS_PER_DAY} distinct origins per\n *    (day x app x directive) may mint documents per instance per day. Beyond\n *    that, new origins are dropped while known ones keep counting — a flood\n *    of unique URLs (the AGL-1769 lesson: never let request content mint\n *    unbounded documents) saturates the cap instead of the collection;\n *  - WRITES are budgeted per instance per minute, so a POST flood cannot turn\n *    an unauthenticated beacon into a Firestore write bill even against\n *    already-minted documents.\n *\n * Every cap here is per instance, like the tenant collector's `keyStore`: the\n * fleet-wide worst case is (instances x cap), which is bounded and small,\n * and an instance recycle merely re-counts an origin against a fresh cap —\n * the merge write is idempotent about which document it lands in.\n *\n * ## Ids are attacker-derived, so they go through `isDocumentId`\n *\n * Key parts are sanitized to `[a-z0-9.:_-]` and joined with `|`, then the\n * whole id is checked with {@link isDocumentId} (the AGL-1771 predicate —\n * imported from its leaf, `./document-id`, which imports nothing). Belt and\n * braces: the sanitizer already removes `/` and the joiner makes a reserved\n * `__x__` form impossible, but the predicate is the contract and it is\n * cheaper to check than to argue.\n *\n * ## Retention is TTL, not a sweep\n *\n * `expiresAt` (a Timestamp — TTL refuses numbers) is set\n * {@link CSP_AGGREGATE_RETENTION_DAYS} days past the day bucket. The TTL\n * policy is a gcloud action plus a `fieldOverrides` entry in\n * `cloud/firebase-firestore.indexes.json` — see\n * docs/FIRESTORE_MANUAL_CONFIG.md (AGL-1793): the entry ships with this\n * module and the gcloud enable is owed at deploy time.\n *\n * ## Fail-soft, like everything on this path\n *\n * A collector must never turn an observed problem into a served one. Every\n * failure here — no credential, Firestore down, a hostile id that survives\n * sanitization — drops the aggregate (one `console.error` line, tagged) and\n * returns. The log lines the collectors already emit are unaffected.\n *\n * No client ever reads or writes this collection: there is no rules `match`\n * for it, and Firestore denies what nothing matches, so the Admin SDK is the\n * only path in. The staff read-back is `/api/admin/csp-reports` on the\n * console.\n */\n\nimport { FieldValue } from 'firebase-admin/firestore'\nimport type { CspViolation } from '@aglyn/aglyn/app-utils/csp-report'\nimport { isDocumentId } from './document-id'\n\n/** Top-level collection of counter documents. Server-only; no rules match. */\nexport const CSP_AGGREGATE_COLLECTION = 'cspViolationDaily'\n\n/**\n * Long enough that \"a week of traffic\" (AGL-1702 condition 1, AGL-1726\n * condition 3) is readable with room to be read late, short enough that the\n * collection stays a working set rather than an archive.\n */\nexport const CSP_AGGREGATE_RETENTION_DAYS = 60\n\n/**\n * Distinct blocked origins that may mint documents per (day x app x\n * directive), per instance. A legitimate policy violates against a handful of\n * hosts; thirty is generous headroom for a real regression while keeping a\n * flood of attacker-invented origins from minting unbounded documents.\n */\nexport const MAX_DISTINCT_ORIGINS_PER_DAY = 30\n\n/**\n * Aggregate writes allowed per instance per minute. Distinct-origin capping\n * bounds document COUNT; this bounds write OPS, which are billed even when\n * they land on existing documents. Sized far above what real browsers on one\n * instance produce and far below what makes a flood expensive.\n */\nconst WRITE_BUDGET_PER_MINUTE = 120\n\n/**\n * The directives a browser can actually report, per the CSP3 registry. An\n * unrecognized directive is a non-browser caller (or a future spec revision)\n * and shares one bucket rather than minting its own key space.\n */\nconst KNOWN_DIRECTIVES = new Set([\n  'base-uri',\n  'block-all-mixed-content',\n  'child-src',\n  'connect-src',\n  'default-src',\n  'font-src',\n  'form-action',\n  'frame-ancestors',\n  'frame-src',\n  'img-src',\n  'manifest-src',\n  'media-src',\n  'object-src',\n  'prefetch-src',\n  'script-src',\n  'script-src-attr',\n  'script-src-elem',\n  'style-src',\n  'style-src-attr',\n  'style-src-elem',\n  'upgrade-insecure-requests',\n  'worker-src',\n])\n\n/**\n * Per-instance mint tracker: (day|app|directive) to the origin|disposition\n * pairs that have been allowed to mint documents. Cleared wholesale at the\n * cap, like the tenant collector's `keyStore`: the failure mode of clearing\n * is a brief widening of the mint cap, strictly better than an unbounded map\n * fed by attacker-chosen keys.\n */\nconst mintTracker = new Map<string, Set<string>>()\nconst MAX_TRACKED_GROUPS = 512\n\n/** Per-instance write budget window. */\nlet budgetWindowStartMs = 0\nlet budgetUsed = 0\n\n/** Test seam: module-scope state would otherwise leak across cases. */\nexport function resetCspAggregateStateForTests(): void {\n  mintTracker.clear()\n  budgetWindowStartMs = 0\n  budgetUsed = 0\n}\n\n/** One id/field component: lowercase, fixed charset, never empty. */\nfunction sanitizePart(value: string, max: number): string {\n  const cleaned = value\n    .toLowerCase()\n    .replace(/[^a-z0-9.:_-]+/g, '-')\n    .slice(0, max)\n  return cleaned || 'unknown'\n}\n\n/**\n * `blocked-uri` reduced to the coarsest thing worth counting: the HOST for a\n * URL, the bare keyword (`inline`, `eval`, `data`, ...) otherwise. Paths are\n * deliberately dropped — twelve chunk URLs off one CDN are one origin-level\n * fact (the AGL-1779 shape), and a path would both explode the key space and\n * hand the id to whoever controls the URL.\n */\nexport function cspBlockedOrigin(blockedUri: string): string {\n  if (!blockedUri) return 'none'\n  try {\n    return sanitizePart(new URL(blockedUri).host, 120)\n  } catch {\n    return sanitizePart(blockedUri, 40)\n  }\n}\n\n/** UTC day bucket, `YYYY-MM-DD`. */\nexport function cspAggregateDay(nowMs: number): string {\n  return new Date(nowMs).toISOString().slice(0, 10)\n}\n\nfunction normalizeDirective(directive: string): string {\n  return KNOWN_DIRECTIVES.has(directive) ? directive : 'other'\n}\n\nexport interface RecordCspViolationsOptions {\n  /** Which collector this came through — part of the counter key. */\n  app: 'console' | 'tenant'\n  /**\n   * The reporting site (tenant only), REQUEST-derived and already clamped by\n   * the caller. Stored as a sample field, never in the id: distinct sites\n   * must not multiply the key space.\n   */\n  site?: string\n  now?: number\n  /** Injectable for tests; defaults to the Admin SDK's Firestore. */\n  firestore?: any\n}\n\n/**\n * Compound `violations` into the daily counters. Never throws; returns how\n * many documents were written (0 on any failure, budget exhaustion included).\n */\nexport async function recordCspViolations(\n  violations: readonly CspViolation[],\n  options: RecordCspViolationsOptions,\n): Promise<number> {\n  try {\n    if (!violations.length) return 0\n    const now = options.now ?? Date.now()\n    const day = cspAggregateDay(now)\n    const dayStartMs = Date.parse(`${day}T00:00:00.000Z`)\n\n    // Group first: N occurrences of one key in a batch are ONE write carrying\n    // increment(N), so a page that repeats itself costs one op, not N.\n    const grouped = new Map<\n      string,\n      { n: number; directive: string; origin: string; violation: CspViolation }\n    >()\n    for (const violation of violations) {\n      const directive = normalizeDirective(violation.effectiveDirective)\n      const origin = cspBlockedOrigin(violation.blockedUri)\n      const disposition = sanitizePart(violation.disposition || 'report', 16)\n      const id = [\n        day,\n        options.app,\n        sanitizePart(directive, 64),\n        disposition,\n        origin,\n      ].join('|')\n      // Belt and braces — the AGL-1771 contract for anything handed to\n      // `.doc()`. The sanitizer above should make this unreachable.\n      if (!isDocumentId(id)) continue\n\n      const existing = grouped.get(id)\n      if (existing) {\n        existing.n += 1\n        continue\n      }\n\n      // Distinct-origin cap, per (day x app x directive). Known pairs keep\n      // counting; new pairs beyond the cap are dropped — bounded documents\n      // is the property, not perfect counts.\n      const groupKey = `${day}|${options.app}|${directive}`\n      if (mintTracker.size > MAX_TRACKED_GROUPS) mintTracker.clear()\n      let minted = mintTracker.get(groupKey)\n      if (!minted) {\n        minted = new Set()\n        mintTracker.set(groupKey, minted)\n      }\n      const pair = `${disposition}|${origin}`\n      if (!minted.has(pair)) {\n        if (minted.size >= MAX_DISTINCT_ORIGINS_PER_DAY) continue\n        minted.add(pair)\n      }\n\n      grouped.set(id, { n: 1, directive, origin, violation })\n    }\n    if (!grouped.size) return 0\n\n    // Write budget: fixed one-minute window per instance.\n    if (now - budgetWindowStartMs >= 60_000) {\n      budgetWindowStartMs = now\n      budgetUsed = 0\n    }\n    const room = WRITE_BUDGET_PER_MINUTE - budgetUsed\n    if (room <= 0) return 0\n    const entries = [...grouped.entries()].slice(0, room)\n    budgetUsed += entries.length\n\n    const firestore =\n      options.firestore ??\n      // Lazily resolved so this module stays inert at load: route specs and\n      // this module's own spec inject a fake, and nothing initializes\n      // firebase-admin just by importing the barrel.\n      (await import('./firebase-admin')).firebaseAdmin.app().firestore()\n\n    await Promise.all(\n      entries.map(([id, { n, directive, origin, violation }]) =>\n        firestore\n          .collection(CSP_AGGREGATE_COLLECTION)\n          .doc(id)\n          .set(\n            {\n              day,\n              app: options.app,\n              directive,\n              origin,\n              disposition: sanitizePart(violation.disposition || 'report', 16),\n              count: FieldValue.increment(n),\n              lastSeenMs: now,\n              // Samples, not keys: enough to find the surface, no power to\n              // mint documents. Already clamped by the parser; clamped again\n              // because this module's contract should not depend on that.\n              lastPath: violation.documentPath.slice(0, 200),\n              ...(options.site ? { lastSite: options.site.slice(0, 253) } : {}),\n              // Timestamp-typed via Date — Firestore TTL refuses numbers.\n              expiresAt: new Date(\n                dayStartMs + CSP_AGGREGATE_RETENTION_DAYS * 86_400_000,\n              ),\n            },\n            { merge: true },\n          ),\n      ),\n    )\n    return entries.length\n  } catch (error) {\n    // Fail-soft: the aggregate is an observer, and `console.error` rather\n    // than `console.warn` on purpose — the collectors' own log lines are\n    // warns, and their specs count warns.\n    console.error(\n      JSON.stringify({\n        tag: 'AGL-1799:csp-aggregate',\n        error: String(error).slice(0, 200),\n      }),\n    )\n    return 0\n  }\n}\n"],"names":["FieldValue","isDocumentId","CSP_AGGREGATE_COLLECTION","CSP_AGGREGATE_RETENTION_DAYS","MAX_DISTINCT_ORIGINS_PER_DAY","WRITE_BUDGET_PER_MINUTE","KNOWN_DIRECTIVES","Set","mintTracker","Map","MAX_TRACKED_GROUPS","budgetWindowStartMs","budgetUsed","resetCspAggregateStateForTests","clear","sanitizePart","value","max","cleaned","toLowerCase","replace","slice","cspBlockedOrigin","blockedUri","URL","host","cspAggregateDay","nowMs","Date","toISOString","normalizeDirective","directive","has","recordCspViolations","violations","options","length","now","day","dayStartMs","parse","grouped","violation","effectiveDirective","origin","disposition","id","app","join","existing","get","n","groupKey","size","minted","set","pair","add","room","entries","firestore","firebaseAdmin","Promise","all","map","collection","doc","count","increment","lastSeenMs","lastPath","documentPath","site","lastSite","expiresAt","merge","error","console","JSON","stringify","tag","String"],"mappings":"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"}

package/src/lib/server/data-storage-gate.d.ts

@@ -0,0 +1,66 @@
+/**
+ * @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.
+ */
+/**
+ * `dataStorageMbPerOrg`, answered once for every path that writes dataset
+ * bytes (AGL-2253).
+ *
+ * AGL-2163 wired `checkDataStorageQuota().allowed` into `/api/orgs/datasets`
+ * and stopped there, so the console route refused what the REST API and the
+ * public form path went on accepting. The measurement and the shape logic
+ * lived inside that route file, which is exactly why the other two writers
+ * never got it — a gate that only one caller can reach is a gate the next
+ * caller is guaranteed to miss.
+ *
+ * The VERDICT lives here; the REFUSAL does not. `/api/orgs/datasets` answers
+ * a console `{ error }` 403, `/v1` answers an `ApiErrors.planRequired` body
+ * with a machine-readable `code`, and the tenant form path answers nothing at
+ * all — it drops the dataset row and still accepts the submission. Three
+ * correct, incompatible renderings of one decision.
+ *
+ * ## What it costs a paying customer: NOTHING
+ *
+ * Every plan with an `extraDataGbMonthlyUsd` rate resolves to
+ * `'never-blocks'` — the overage bills, exactly as `checkDataStorageQuota`'s
+ * docblock promises — so the metered case returns `null` without a single
+ * read and with no possibility of a refusal. Only the other two shapes cost
+ * anything, and one of them costs no read either.
+ */
+export interface DataStorageRefusal {
+    /** The included band the write would exceed, MB. */
+    includedMb: number;
+    /**
+     * `'always'` — the band is zero and the plan meters nothing, so no
+     * measurement could change the answer and none was taken.
+     * `'measured'` — a finite non-zero band on a plan with no rate, decided
+     * against the monthly rollup.
+     */
+    basis: 'always' | 'measured';
+}
+/**
+ * Null when the write may proceed; a refusal when dataset bytes are not
+ * included on this org's plan.
+ *
+ * The `'measure'` shape reads `orgs/{orgId}/usage/{YYYY-MM}.dataStorageMb`
+ * rather than re-summing the org's datasets: `report-usage`'s
+ * `orgDatasetBytes` is O(datasets) reads with two aggregate queries EACH,
+ * which is not a per-record-write cost. The reading is therefore up to a
+ * month stale, and that is stated rather than hidden — it can only ever
+ * UNDER-refuse, never refuse a write it should have allowed. The only orgs
+ * that shape can reach are ones staff configured by hand
+ * (`entitlementOverrides.dataStorageMbPerOrg` on a plan that meters nothing).
+ */
+export declare function dataStorageRefusal(org: unknown, orgRef: FirebaseFirestore.DocumentReference, now?: Date): Promise<DataStorageRefusal | null>;

package/src/lib/server/data-storage-gate.js

@@ -0,0 +1,48 @@
+/**
+ * @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 { checkDataStorageQuota, dataStorageEnforcementShape } from "@aglyn/aglyn/server";
+/**
+ * Null when the write may proceed; a refusal when dataset bytes are not
+ * included on this org's plan.
+ *
+ * The `'measure'` shape reads `orgs/{orgId}/usage/{YYYY-MM}.dataStorageMb`
+ * rather than re-summing the org's datasets: `report-usage`'s
+ * `orgDatasetBytes` is O(datasets) reads with two aggregate queries EACH,
+ * which is not a per-record-write cost. The reading is therefore up to a
+ * month stale, and that is stated rather than hidden — it can only ever
+ * UNDER-refuse, never refuse a write it should have allowed. The only orgs
+ * that shape can reach are ones staff configured by hand
+ * (`entitlementOverrides.dataStorageMbPerOrg` on a plan that meters nothing).
+ */ export async function dataStorageRefusal(org, orgRef, now = new Date()) {
+    var _usage_get;
+    const shape = dataStorageEnforcementShape(org);
+    if (shape === 'never-blocks') return null;
+    if (shape === 'always-blocks') {
+        return {
+            includedMb: checkDataStorageQuota(org, 0).includedMb,
+            basis: 'always'
+        };
+    }
+    const usage = await orgRef.collection('usage').doc(now.toISOString().slice(0, 7)).get();
+    const quota = checkDataStorageQuota(org, Number((_usage_get = usage.get('dataStorageMb')) != null ? _usage_get : 0));
+    if (quota.allowed) return null;
+    return {
+        includedMb: quota.includedMb,
+        basis: 'measured'
+    };
+}
+
+//# sourceMappingURL=data-storage-gate.js.map

package/src/lib/server/data-storage-gate.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/data-storage-gate.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  checkDataStorageQuota,\n  dataStorageEnforcementShape,\n} from '@aglyn/aglyn/server'\n\n/**\n * `dataStorageMbPerOrg`, answered once for every path that writes dataset\n * bytes (AGL-2253).\n *\n * AGL-2163 wired `checkDataStorageQuota().allowed` into `/api/orgs/datasets`\n * and stopped there, so the console route refused what the REST API and the\n * public form path went on accepting. The measurement and the shape logic\n * lived inside that route file, which is exactly why the other two writers\n * never got it — a gate that only one caller can reach is a gate the next\n * caller is guaranteed to miss.\n *\n * The VERDICT lives here; the REFUSAL does not. `/api/orgs/datasets` answers\n * a console `{ error }` 403, `/v1` answers an `ApiErrors.planRequired` body\n * with a machine-readable `code`, and the tenant form path answers nothing at\n * all — it drops the dataset row and still accepts the submission. Three\n * correct, incompatible renderings of one decision.\n *\n * ## What it costs a paying customer: NOTHING\n *\n * Every plan with an `extraDataGbMonthlyUsd` rate resolves to\n * `'never-blocks'` — the overage bills, exactly as `checkDataStorageQuota`'s\n * docblock promises — so the metered case returns `null` without a single\n * read and with no possibility of a refusal. Only the other two shapes cost\n * anything, and one of them costs no read either.\n */\nexport interface DataStorageRefusal {\n  /** The included band the write would exceed, MB. */\n  includedMb: number\n  /**\n   * `'always'` — the band is zero and the plan meters nothing, so no\n   * measurement could change the answer and none was taken.\n   * `'measured'` — a finite non-zero band on a plan with no rate, decided\n   * against the monthly rollup.\n   */\n  basis: 'always' | 'measured'\n}\n\n/**\n * Null when the write may proceed; a refusal when dataset bytes are not\n * included on this org's plan.\n *\n * The `'measure'` shape reads `orgs/{orgId}/usage/{YYYY-MM}.dataStorageMb`\n * rather than re-summing the org's datasets: `report-usage`'s\n * `orgDatasetBytes` is O(datasets) reads with two aggregate queries EACH,\n * which is not a per-record-write cost. The reading is therefore up to a\n * month stale, and that is stated rather than hidden — it can only ever\n * UNDER-refuse, never refuse a write it should have allowed. The only orgs\n * that shape can reach are ones staff configured by hand\n * (`entitlementOverrides.dataStorageMbPerOrg` on a plan that meters nothing).\n */\nexport async function dataStorageRefusal(\n  org: unknown,\n  orgRef: FirebaseFirestore.DocumentReference,\n  now: Date = new Date(),\n): Promise<DataStorageRefusal | null> {\n  const shape = dataStorageEnforcementShape(org as never)\n  if (shape === 'never-blocks') return null\n  if (shape === 'always-blocks') {\n    return {\n      includedMb: checkDataStorageQuota(org as never, 0).includedMb,\n      basis: 'always',\n    }\n  }\n  const usage = await orgRef\n    .collection('usage')\n    .doc(now.toISOString().slice(0, 7))\n    .get()\n  const quota = checkDataStorageQuota(\n    org as never,\n    Number(usage.get('dataStorageMb') ?? 0),\n  )\n  if (quota.allowed) return null\n  return { includedMb: quota.includedMb, basis: 'measured' }\n}\n"],"names":["checkDataStorageQuota","dataStorageEnforcementShape","dataStorageRefusal","org","orgRef","now","Date","usage","shape","includedMb","basis","collection","doc","toISOString","slice","get","quota","Number","allowed"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SACEA,qBAAqB,EACrBC,2BAA2B,QACtB,sBAAqB;AAuC5B;;;;;;;;;;;;CAYC,GACD,OAAO,eAAeC,mBACpBC,GAAY,EACZC,MAA2C,EAC3CC,MAAY,IAAIC,MAAM;QAgBbC;IAdT,MAAMC,QAAQP,4BAA4BE;IAC1C,IAAIK,UAAU,gBAAgB,OAAO;IACrC,IAAIA,UAAU,iBAAiB;QAC7B,OAAO;YACLC,YAAYT,sBAAsBG,KAAc,GAAGM,UAAU;YAC7DC,OAAO;QACT;IACF;IACA,MAAMH,QAAQ,MAAMH,OACjBO,UAAU,CAAC,SACXC,GAAG,CAACP,IAAIQ,WAAW,GAAGC,KAAK,CAAC,GAAG,IAC/BC,GAAG;IACN,MAAMC,QAAQhB,sBACZG,KACAc,QAAOV,aAAAA,MAAMQ,GAAG,CAAC,4BAAVR,aAA8B;IAEvC,IAAIS,MAAME,OAAO,EAAE,OAAO;IAC1B,OAAO;QAAET,YAAYO,MAAMP,UAAU;QAAEC,OAAO;IAAW;AAC3D"}

package/src/lib/server/dataset-live-pages.d.ts

@@ -0,0 +1,179 @@
+/**
+ * @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 { Firestore } from 'firebase-admin/firestore';
+import { type UsageSources } from './live-page-usage';
+/**
+ * How many documents per collection the per-site scan reads.
+ *
+ * The console's publish scan uses the same number for the same reason
+ * (AGL-1161): this decides which caches get dropped, so a prefix scan would
+ * report a refreshed site and leave real pages serving the old rows. Bounded
+ * all the same, and when the bound bites it is SAID rather than absorbed.
+ */
+export declare const DATASET_SCAN_LIMIT = 2000;
+/**
+ * How many sites one record write fans out to.
+ *
+ * `MAX_SCOPE_HOSTS` is the ceiling on a NAMED selection, so only an org-wide
+ * dataset can reach this — an org with more sites than this pays a scan per
+ * site on every write otherwise, which is a cost the person writing one row
+ * did not ask for. Sites past the cap keep the TTL they had before this
+ * existed, and the shortfall is returned and logged rather than swallowed.
+ */
+export declare const MAX_DATASET_FANOUT_HOSTS = 30;
+/**
+ * How long one site-and-dataset pair waits before announcing again.
+ *
+ * A 1,000-row import is one announce because the importer announces after its
+ * loop, not per row. This covers the other burst — many small writes arriving
+ * separately, a form under load or an automation fanning out — where each one
+ * would otherwise pay a full scan per site and hand the tenant the same path
+ * list again.
+ *
+ * Leading edge, so the FIRST write of a burst refreshes immediately; what is
+ * skipped is a repeat inside the window, and the next write after it announces
+ * again. The cost of the skip is bounded by the window: a row written during
+ * one is visible no later than the next announce.
+ */
+export declare const DATASET_ANNOUNCE_WINDOW_MS = 2000;
+/** Test seam: the window is process-wide state, so a spec has to reset it. */
+export declare function resetDatasetAnnounceThrottle(): void;
+/** One site's share of a dataset change. */
+export interface DatasetLivePageTarget {
+    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`) that repeat over the dataset. */
+    paths: string[];
+    /** The site held more documents than the scan read, so `paths` is partial. */
+    truncated: boolean;
+}
+export interface DatasetLivePageScope {
+    targets: DatasetLivePageTarget[];
+    /**
+     * Sites the fan-out cap left out. Zero in the ordinary case, and reported
+     * rather than logged because a caller that says "refreshed" while some sites
+     * were skipped is the failure this whole arc exists to remove.
+     */
+    hostsDropped: number;
+    /**
+     * Why there is nothing to announce, or `'ok'`.
+     *
+     * `'not-rendered'` is a success: a dataset no page repeats over has no live
+     * page to refresh. It is kept apart from `'error'` for the same reason the
+     * revalidate route keeps `not-routed` apart from a refusal — one means there
+     * was nothing to do, the other means something was left stale.
+     */
+    reason: 'ok' | 'no-dataset' | 'no-sites' | 'not-rendered' | 'error';
+}
+/**
+ * Every live screen whose rendered output repeats over the dataset, however
+ * indirectly.
+ *
+ * The same three-bucket closure a placed form's pages are found by, for the
+ * same reason: a binding is found by SEARCHING node trees rather than by
+ * matching a pointer, so it can sit on the screen, in the chrome of the layout
+ * the screen renders inside, or inside a reusable component a third component
+ * nests. After the first level the fan-out is identical, so it is delegated
+ * rather than restated.
+ *
+ * Pure, and separate from the Firestore read, so the closure is testable
+ * without a database.
+ */
+export declare function screenIdsRepeatingDataset(keys: ReadonlySet<string>, sources: UsageSources): string[];
+/**
+ * Every live page a change to this dataset's records makes stale, per site.
+ *
+ * Reads only; announcing is the caller's, because the two runtimes announce
+ * differently — the console posts to the tenant over the shared secret, and
+ * the tenant drops its own caches in process. Splitting it here is what lets
+ * both use one answer to the question of WHICH pages.
+ *
+ * Never throws. A scope that could not be computed is a scope of nothing, and
+ * the TTL underneath is unaffected.
+ */
+export declare function datasetLivePageScope(options: {
+    firestore: Firestore;
+    orgId: string;
+    datasetId: string;
+}): Promise<DatasetLivePageScope>;
+/**
+ * How one runtime drops a site's cached pages.
+ *
+ * The generic seam, registered by the deployment that owns the caches. The
+ * tenant registers an in-process drop at boot; the console announces over the
+ * shared secret and passes its own dropper at the call site. Core names
+ * neither, exactly as it names no repeat source.
+ *
+ * Returns whether the drop landed. It must never throw: everything above it
+ * has already been written.
+ */
+export type LivePageDropper = (target: DatasetLivePageTarget) => 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;
+export interface DatasetAnnounceResult {
+    /** Sites whose cached pages were dropped. */
+    sitesRefreshed: number;
+    /** Pages named across those sites. */
+    pathsRefreshed: number;
+    /** Sites the drop was attempted on and refused. */
+    sitesRefused: number;
+    /** Sites past the fan-out cap, and sites whose scan was truncated. */
+    hostsDropped: number;
+    scanTruncated: boolean;
+    /** `'throttled'` when a drop for this pair already went out just now. */
+    reason: DatasetLivePageScope['reason'] | 'throttled' | 'no-dropper';
+}
+/**
+ * Refresh every live page that shows this dataset's records.
+ *
+ * The one call a write path makes. BEST EFFORT, ALWAYS: it never throws and
+ * never rejects, so a caller can `await` it inside the try that already guards
+ * the write without any chance of turning a stored record into a failed one.
+ *
+ * `drop` overrides the registered dropper for callers that hold their own —
+ * the console, whose announce is an authenticated request rather than a local
+ * cache call.
+ */
+export declare function announceDatasetRecordChange(options: {
+    firestore: Firestore;
+    orgId: string;
+    datasetId: string;
+    drop?: LivePageDropper;
+}): Promise<DatasetAnnounceResult>;
+/**
+ * One sentence for a refresh that did not cover every page, or `null` when it
+ * did.
+ *
+ * Beside the call rather than at each surface, so the console cannot word this
+ * differently in two places — the same reason `describeRevalidateShortfall`
+ * lives beside `revalidateLivePages`. `lead` names the act that succeeded,
+ * because only that word differs between surfaces: a record is SAVED, and
+ * telling someone who fixed a typo that they published it is a worse error
+ * than the staleness the sentence is about.
+ */
+export declare function describeDatasetAnnounceShortfall(result: DatasetAnnounceResult | null, lead?: string): string | null;
+export default announceDatasetRecordChange;