@aglyn/aglyn 1.0.0-beta.143

package/src/lib/app-utils/plugin-api-rate-limit.js

@@ -0,0 +1,270 @@
+/**
+ * @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.
+ */ /**
+ * Policy for the tenant plugin-API dispatcher's visitor-write rate limit
+ * (AGL-1770). Pure and dependency-free so it is unit-testable without a route
+ * harness — the durable half lives in `@aglyn/tenant-data-admin` beside
+ * `visitorWriteRefusal`, exactly like the lockdown split.
+ *
+ * ## What this bounds
+ *
+ * `apps/tenant/app/api/[...pluginApi]/route.ts` dispatches every plugin's
+ * visitor-facing handler and, before this, applied no rate limit of any kind.
+ * The gates it did have each refuse something narrower: per-site enablement is
+ * skipped by an unresolvable `hostId`, the release gate only checks that the
+ * plugin is on, and `visitorWriteRefusal` refuses only a paused or suspended
+ * site. None of them bounds volume from a working, enabled site — which is
+ * every live merchant.
+ *
+ * AGL-1769 closed the *shape* of the unauthenticated cart write (the caller
+ * chose the document path) and was explicit that it did not bound the
+ * *quantity*: "id control never multiplied volume; it bought shape". This is
+ * the other half. The cost of the unbounded half lands in the merchant's own
+ * Firestore — document count and storage on a tenant who did nothing wrong.
+ */ /**
+ * 120 writes per minute per (site, client IP).
+ *
+ * Deliberately generous, and the reasoning matters more than the number: a
+ * limit that trips on genuine use is worse than no limit, because it gets
+ * raised until it means nothing. Measured against what the storefront actually
+ * emits:
+ *
+ * - `cart.tsx:214` puts the line-quantity `TextField`'s `onChange` straight
+ *   onto a POST with no debounce, so *typing* `100` into a quantity box is
+ *   three cart writes. Editing a few lines is a genuine ten-to-twenty-write
+ *   burst in a couple of seconds.
+ * - `experiments/track` is an A/B beacon: one exposure write per experiment
+ *   per page view, so a visitor clicking through pages at ~1/s with two live
+ *   experiments sustains ~2 writes/s legitimately.
+ * - Every visitor write on a site shares ONE budget (see the key below), so
+ *   these add rather than each getting their own headroom.
+ *
+ * What a tighter number would actually buy is small. At 120/min a single
+ * source can still mint ~172k documents a day against one site; at 30/min it
+ * is ~43k. Neither is "safe" in absolute terms — what the cap buys is turning
+ * a one-line flood script from *millions* per day into something that needs a
+ * distributed botnet to stay interesting, and turning an incident from
+ * instantaneous into detectable. That property is bought at 120 as well as at
+ * 30, and 30 would refuse real shoppers.
+ *
+ * 120/60s is also `DEFAULT_RATE_LIMIT` / `DEFAULT_RATE_WINDOW_MS` — the same
+ * pair the public REST API enforces — so this adds no bespoke number.
+ */ export const VISITOR_WRITE_RATE_LIMIT = 120;
+/**
+ * Fixed 60s window, matching every other limiter in the codebase rather than
+ * improving on it. A fixed window admits up to 2× the cap across a boundary;
+ * consistency with the shared bucket ids, the degradation markers and
+ * `/api/health/rate-limits` is worth more here than closing that.
+ */ export const VISITOR_WRITE_RATE_WINDOW_MS = 60000;
+/**
+ * Machine-caller paths on EITHER plugin-API surface: neither dispatcher rate
+ * limits these.
+ *
+ * The membership rule, so this list is decidable rather than a taste call: the
+ * caller proves a shared secret, a webhook signature or a console session that
+ * a visitor has no way to obtain, and its request volume is set by campaign
+ * size or cron schedule rather than by human behaviour. A 120/min cap does not
+ * merely inconvenience these — Resend delivering open/click webhooks for one
+ * 50k-recipient campaign arrives from a handful of IPs for a single host and
+ * would be shredded by any shopper-sized ceiling.
+ *
+ * ### Why a path list is right here when the dispatcher argues against them
+ *
+ * The lockdown gate two lines below is keyed by METHOD precisely to avoid a
+ * path list, "for the same reason `useSiteFetch` draws the Preview boundary
+ * that way: a per-path list means thirteen handlers each remembering and the
+ * fourteenth silently not."
+ *
+ * That argument turns on POLARITY, and this list has the opposite one. The
+ * lockdown list would have enumerated what to *protect*, so a forgotten entry
+ * is silently unprotected — the failure you never find. This enumerates what
+ * to *exempt*, so the default is limited: a new visitor endpoint added
+ * tomorrow is covered by doing nothing, and a forgotten machine endpoint
+ * fails loudly and recoverably as 429s with `Retry-After` on a caller that
+ * retries. Safe default, noisy mistake.
+ *
+ * Each entry, with the credential that makes it a machine caller:
+ *
+ * - `email/events` — Resend's webhook; `verifySvix` over `svix-id`/
+ *   `svix-timestamp`/`svix-signature` against `RESEND_WEBHOOK_SECRET`.
+ * - `campaigns/send` — a Firebase ID token with a host member role, or
+ *   `CRON_SECRET` for the scheduled-send path.
+ * - `bookings/reminders` — `x-cron-secret` against `CRON_SECRET`; refuses
+ *   outright when it is unset.
+ * - `hooks/…` — the merchant's per-hook secret in `x-aglyn-secret`, compared
+ *   with `timingSafeEqual`. It already carries its own 30/min per-hook
+ *   limiter, so exempting it here removes nothing.
+ *
+ * The four below are registered on the CONSOLE surface only, and each is a
+ * chunked cron sweep rather than a single beat — `sweepConsoleCron` follows
+ * `nextCursor` up to `CRON_SWEEP_MAX_CHUNKS` (50) POSTs per route per run,
+ * from one Cloud Functions address, and the key below carries no path. Three
+ * such routes on one beat is 150 requests in a minute against a single
+ * bucket, so this exemption is load-bearing and not decorative:
+ *
+ * - `campaigns/process-scheduled` — `x-cron-secret` against `CRON_SECRET`;
+ *   refuses outright when it is unset.
+ * - `lists/materialize` — the same header, the same refusal.
+ * - `commerce/process-abandoned` — the same header, the same refusal.
+ * - `commerce/process-restock` — the same header, the same refusal.
+ *
+ * Note what is deliberately NOT exempt: presence of an `authorization` or
+ * `svix-signature` HEADER. Header presence is not a credential — the
+ * dispatcher cannot verify signatures it does not own, so exempting on the
+ * header would let any caller skip the limiter by attaching a garbage one to
+ * a cart POST.
+ *
+ * Nor is `commerce/supplier-update`, whose HMAC token makes it a machine
+ * caller but whose volume is set by a supplier's own system rather than by a
+ * schedule. It fails the second half of the membership rule, and the polarity
+ * above says which way to resolve a borderline case: leave it limited, where
+ * a mistake is a recoverable 429.
+ */ const MACHINE_API_PATHS = new Set([
+    'email/events',
+    'campaigns/send',
+    'bookings/reminders',
+    'campaigns/process-scheduled',
+    'lists/materialize',
+    'commerce/process-abandoned',
+    'commerce/process-restock'
+]);
+/** Prefixes whose whole subtree is a machine surface (`hooks/{host}/{hook}`). */ const MACHINE_API_PREFIXES = [
+    'hooks/'
+];
+/** Leading/trailing slashes stripped, matching `normalizeApiPath`. */ function normalize(path) {
+    return String(path != null ? path : '').replace(/^\/+|\/+$/g, '');
+}
+/**
+ * Is this dispatcher path a credentialed machine surface (exempt), rather
+ * than a visitor one (limited)? Unknown paths are visitor by default.
+ */ export function isMachinePluginApiPath(path) {
+    const normalized = normalize(path);
+    if (MACHINE_API_PATHS.has(normalized)) return true;
+    return MACHINE_API_PREFIXES.some((prefix)=>normalized.startsWith(prefix));
+}
+/**
+ * The limiter key: one bucket per (site, client IP).
+ *
+ * ## Why compound, and why NOT a second limiter in either direction
+ *
+ * **Per-site alone is rejected.** A single attacker would consume the whole
+ * merchant's allowance and every real shopper would then be refused — an
+ * attacker-triggered denial of service against the victim, cheaper to mount
+ * than the flood it replaces and costing the merchant *sales* rather than
+ * storage. That is strictly worse than the growth it guards.
+ *
+ * **Per-IP alone is rejected.** Trivially distributed, and it would let one
+ * merchant's traffic spend another's budget.
+ *
+ * **Compound is what "per-host and per-IP together" should mean here.** Each
+ * source is bounded on each site, and no source can affect another's budget,
+ * so the ceiling a site is exposed to is (distinct source IPs) × 120/min —
+ * the same shape legitimate traffic has. What it does not stop is a genuine
+ * botnet, and that is stated rather than papered over: bounding *that* needs
+ * an edge WAF, not an application limiter, and every application-level scheme
+ * that would catch it (a site-wide ceiling) reintroduces the self-DoS above.
+ *
+ * **A second, platform-wide per-IP limiter was considered and dropped.** It
+ * would bound one source sweeping many merchants, but costs a second
+ * Firestore transaction on every storefront write — tripling the ops on a
+ * legitimate add-to-cart — to bound an attack that the compound key already
+ * prices at one full budget per merchant. One transaction per visitor write
+ * is the established cost here (`forms/submit`, `protection/unlock`); two
+ * would be novel and is not paid for by what it buys.
+ *
+ * The path is **not** in the key, on purpose: one shared budget per (site,
+ * IP) across cart, reviews, newsletter, bookings and beacons. Keying per path
+ * would let a caller multiply its allowance by cycling endpoints, which is
+ * free to do and defeats the point.
+ *
+ * `hostId` is frequently `''` — the dispatcher only resolves one from the
+ * query or a JSON body, and a handler that self-gates may supply none. It is
+ * kept in the key rather than skipped: AGL-1769 named "an unresolvable
+ * `hostId` skips the gate" as an existing hole, and a limiter that a caller
+ * turns off by declining to name a site is not a limiter. Host-less writes
+ * simply share one bucket per IP.
+ */ export function visitorWriteRateLimitKey(hostId, ip) {
+    return `pluginwrite:${hostId || '-'}:${ip || 'unknown'}`;
+}
+/**
+ * Policy for the CONSOLE plugin-API dispatcher's write rate limit.
+ *
+ * `apps/console/app/api/[...pluginApi]/route.ts` dispatches every plugin's
+ * console-facing handler — the marketplace installs and publishes, `ai/assist`,
+ * gift cards, POS orders, refunds, the email list previews and the suppression
+ * writes — and it carries no limiter of any kind. Its gates each refuse
+ * something narrower: per-site enablement needs a resolvable `hostId`, the
+ * release flag only asks whether the plugin is on, and lockdown only refuses
+ * during an incident. None of them bounds volume from an ordinary signed-in
+ * operator, which is every request the surface serves.
+ *
+ * The exposure is not the same one the visitor limiter closes. These handlers
+ * are authenticated, so nobody is minting documents anonymously; what they do
+ * instead is spend REAL money per call — a contact scan with a read budget, a
+ * bundle download and verify, a model call to a paid vendor — on a surface
+ * where a stuck retry loop in one console tab is indistinguishable from abuse.
+ */ /**
+ * 120 requests per minute per console subject.
+ *
+ * `DEFAULT_RATE_LIMIT` / `DEFAULT_RATE_WINDOW_MS` again, and the same pair the
+ * visitor limiter and the public REST API use, so this introduces no bespoke
+ * number to reason about. It is far above a person pressing buttons: the
+ * costly routes on this surface are one-per-click, and the console's own
+ * page-load traffic reaches Firestore through the client SDK rather than
+ * through this dispatcher.
+ *
+ * Deliberately not tighter even though each call here costs more than a cart
+ * write. A limit that trips on genuine use gets raised until it means nothing,
+ * and the per-call cost is the wrong lever for that anyway — an entitlement or
+ * a quota bounds spend per org over a month, where this bounds a runaway loop
+ * over a minute. Two different jobs; this one only has to make the loop stop.
+ */ export const CONSOLE_API_RATE_LIMIT = 120;
+/** Fixed 60s window, matching every other limiter in the codebase. */ export const CONSOLE_API_RATE_WINDOW_MS = 60000;
+/**
+ * The limiter key: one bucket per authenticated subject.
+ *
+ * ## Why this is NOT the visitor key
+ *
+ * `visitorWriteRateLimitKey` is compound because its surface is
+ * unauthenticated, and both halves of that argument are answers to anonymity.
+ * Per-site alone was rejected there because one attacker would spend a whole
+ * merchant's allowance and refuse real shoppers — an attacker-triggered denial
+ * of service against the victim. On the console the subject is a verified
+ * `uid`, so a caller can only ever refuse ITSELF: the self-DoS the compound key
+ * exists to prevent cannot be aimed at anyone else, and the isolation it buys
+ * is already bought by the identity.
+ *
+ * `hostId` is therefore left OUT rather than added, which is the opposite of
+ * the visitor key and for the reason the visitor key leaves the PATH out: an
+ * operator with fifty sites would otherwise hold fifty budgets and could
+ * multiply its allowance by cycling a field it controls. One person is one
+ * budget across every site they can reach.
+ *
+ * ## The unauthenticated fallback
+ *
+ * A caller whose bearer token did not decode — a plugin key, a POS device, an
+ * anonymous probe — has no `uid`, and its client address stands in. That
+ * bucket is shared by every such caller behind one address, which is the
+ * conservative direction: an unidentified caller on an authenticated surface
+ * should not get a private allowance for declining to identify itself. Keeping
+ * it counted at all is the point. A limiter a caller switches off by sending
+ * no credential is not a limiter, and this surface's whole exposure is what
+ * runs BEFORE a handler decides who is asking.
+ */ export function consoleApiRateLimitKey(subject) {
+    return `consoleapi:${subject || 'unknown'}`;
+}
+
+//# sourceMappingURL=plugin-api-rate-limit.js.map

package/src/lib/app-utils/plugin-api-rate-limit.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/plugin-api-rate-limit.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 * Policy for the tenant plugin-API dispatcher's visitor-write rate limit\n * (AGL-1770). Pure and dependency-free so it is unit-testable without a route\n * harness — the durable half lives in `@aglyn/tenant-data-admin` beside\n * `visitorWriteRefusal`, exactly like the lockdown split.\n *\n * ## What this bounds\n *\n * `apps/tenant/app/api/[...pluginApi]/route.ts` dispatches every plugin's\n * visitor-facing handler and, before this, applied no rate limit of any kind.\n * The gates it did have each refuse something narrower: per-site enablement is\n * skipped by an unresolvable `hostId`, the release gate only checks that the\n * plugin is on, and `visitorWriteRefusal` refuses only a paused or suspended\n * site. None of them bounds volume from a working, enabled site — which is\n * every live merchant.\n *\n * AGL-1769 closed the *shape* of the unauthenticated cart write (the caller\n * chose the document path) and was explicit that it did not bound the\n * *quantity*: \"id control never multiplied volume; it bought shape\". This is\n * the other half. The cost of the unbounded half lands in the merchant's own\n * Firestore — document count and storage on a tenant who did nothing wrong.\n */\n\n/**\n * 120 writes per minute per (site, client IP).\n *\n * Deliberately generous, and the reasoning matters more than the number: a\n * limit that trips on genuine use is worse than no limit, because it gets\n * raised until it means nothing. Measured against what the storefront actually\n * emits:\n *\n * - `cart.tsx:214` puts the line-quantity `TextField`'s `onChange` straight\n *   onto a POST with no debounce, so *typing* `100` into a quantity box is\n *   three cart writes. Editing a few lines is a genuine ten-to-twenty-write\n *   burst in a couple of seconds.\n * - `experiments/track` is an A/B beacon: one exposure write per experiment\n *   per page view, so a visitor clicking through pages at ~1/s with two live\n *   experiments sustains ~2 writes/s legitimately.\n * - Every visitor write on a site shares ONE budget (see the key below), so\n *   these add rather than each getting their own headroom.\n *\n * What a tighter number would actually buy is small. At 120/min a single\n * source can still mint ~172k documents a day against one site; at 30/min it\n * is ~43k. Neither is \"safe\" in absolute terms — what the cap buys is turning\n * a one-line flood script from *millions* per day into something that needs a\n * distributed botnet to stay interesting, and turning an incident from\n * instantaneous into detectable. That property is bought at 120 as well as at\n * 30, and 30 would refuse real shoppers.\n *\n * 120/60s is also `DEFAULT_RATE_LIMIT` / `DEFAULT_RATE_WINDOW_MS` — the same\n * pair the public REST API enforces — so this adds no bespoke number.\n */\nexport const VISITOR_WRITE_RATE_LIMIT = 120\n\n/**\n * Fixed 60s window, matching every other limiter in the codebase rather than\n * improving on it. A fixed window admits up to 2× the cap across a boundary;\n * consistency with the shared bucket ids, the degradation markers and\n * `/api/health/rate-limits` is worth more here than closing that.\n */\nexport const VISITOR_WRITE_RATE_WINDOW_MS = 60_000\n\n/**\n * Machine-caller paths on EITHER plugin-API surface: neither dispatcher rate\n * limits these.\n *\n * The membership rule, so this list is decidable rather than a taste call: the\n * caller proves a shared secret, a webhook signature or a console session that\n * a visitor has no way to obtain, and its request volume is set by campaign\n * size or cron schedule rather than by human behaviour. A 120/min cap does not\n * merely inconvenience these — Resend delivering open/click webhooks for one\n * 50k-recipient campaign arrives from a handful of IPs for a single host and\n * would be shredded by any shopper-sized ceiling.\n *\n * ### Why a path list is right here when the dispatcher argues against them\n *\n * The lockdown gate two lines below is keyed by METHOD precisely to avoid a\n * path list, \"for the same reason `useSiteFetch` draws the Preview boundary\n * that way: a per-path list means thirteen handlers each remembering and the\n * fourteenth silently not.\"\n *\n * That argument turns on POLARITY, and this list has the opposite one. The\n * lockdown list would have enumerated what to *protect*, so a forgotten entry\n * is silently unprotected — the failure you never find. This enumerates what\n * to *exempt*, so the default is limited: a new visitor endpoint added\n * tomorrow is covered by doing nothing, and a forgotten machine endpoint\n * fails loudly and recoverably as 429s with `Retry-After` on a caller that\n * retries. Safe default, noisy mistake.\n *\n * Each entry, with the credential that makes it a machine caller:\n *\n * - `email/events` — Resend's webhook; `verifySvix` over `svix-id`/\n *   `svix-timestamp`/`svix-signature` against `RESEND_WEBHOOK_SECRET`.\n * - `campaigns/send` — a Firebase ID token with a host member role, or\n *   `CRON_SECRET` for the scheduled-send path.\n * - `bookings/reminders` — `x-cron-secret` against `CRON_SECRET`; refuses\n *   outright when it is unset.\n * - `hooks/…` — the merchant's per-hook secret in `x-aglyn-secret`, compared\n *   with `timingSafeEqual`. It already carries its own 30/min per-hook\n *   limiter, so exempting it here removes nothing.\n *\n * The four below are registered on the CONSOLE surface only, and each is a\n * chunked cron sweep rather than a single beat — `sweepConsoleCron` follows\n * `nextCursor` up to `CRON_SWEEP_MAX_CHUNKS` (50) POSTs per route per run,\n * from one Cloud Functions address, and the key below carries no path. Three\n * such routes on one beat is 150 requests in a minute against a single\n * bucket, so this exemption is load-bearing and not decorative:\n *\n * - `campaigns/process-scheduled` — `x-cron-secret` against `CRON_SECRET`;\n *   refuses outright when it is unset.\n * - `lists/materialize` — the same header, the same refusal.\n * - `commerce/process-abandoned` — the same header, the same refusal.\n * - `commerce/process-restock` — the same header, the same refusal.\n *\n * Note what is deliberately NOT exempt: presence of an `authorization` or\n * `svix-signature` HEADER. Header presence is not a credential — the\n * dispatcher cannot verify signatures it does not own, so exempting on the\n * header would let any caller skip the limiter by attaching a garbage one to\n * a cart POST.\n *\n * Nor is `commerce/supplier-update`, whose HMAC token makes it a machine\n * caller but whose volume is set by a supplier's own system rather than by a\n * schedule. It fails the second half of the membership rule, and the polarity\n * above says which way to resolve a borderline case: leave it limited, where\n * a mistake is a recoverable 429.\n */\nconst MACHINE_API_PATHS: ReadonlySet<string> = new Set([\n  'email/events',\n  'campaigns/send',\n  'bookings/reminders',\n  'campaigns/process-scheduled',\n  'lists/materialize',\n  'commerce/process-abandoned',\n  'commerce/process-restock',\n])\n\n/** Prefixes whose whole subtree is a machine surface (`hooks/{host}/{hook}`). */\nconst MACHINE_API_PREFIXES: readonly string[] = ['hooks/']\n\n/** Leading/trailing slashes stripped, matching `normalizeApiPath`. */\nfunction normalize(path: string): string {\n  return String(path ?? '').replace(/^\\/+|\\/+$/g, '')\n}\n\n/**\n * Is this dispatcher path a credentialed machine surface (exempt), rather\n * than a visitor one (limited)? Unknown paths are visitor by default.\n */\nexport function isMachinePluginApiPath(path: string): boolean {\n  const normalized = normalize(path)\n  if (MACHINE_API_PATHS.has(normalized)) return true\n  return MACHINE_API_PREFIXES.some((prefix) => normalized.startsWith(prefix))\n}\n\n/**\n * The limiter key: one bucket per (site, client IP).\n *\n * ## Why compound, and why NOT a second limiter in either direction\n *\n * **Per-site alone is rejected.** A single attacker would consume the whole\n * merchant's allowance and every real shopper would then be refused — an\n * attacker-triggered denial of service against the victim, cheaper to mount\n * than the flood it replaces and costing the merchant *sales* rather than\n * storage. That is strictly worse than the growth it guards.\n *\n * **Per-IP alone is rejected.** Trivially distributed, and it would let one\n * merchant's traffic spend another's budget.\n *\n * **Compound is what \"per-host and per-IP together\" should mean here.** Each\n * source is bounded on each site, and no source can affect another's budget,\n * so the ceiling a site is exposed to is (distinct source IPs) × 120/min —\n * the same shape legitimate traffic has. What it does not stop is a genuine\n * botnet, and that is stated rather than papered over: bounding *that* needs\n * an edge WAF, not an application limiter, and every application-level scheme\n * that would catch it (a site-wide ceiling) reintroduces the self-DoS above.\n *\n * **A second, platform-wide per-IP limiter was considered and dropped.** It\n * would bound one source sweeping many merchants, but costs a second\n * Firestore transaction on every storefront write — tripling the ops on a\n * legitimate add-to-cart — to bound an attack that the compound key already\n * prices at one full budget per merchant. One transaction per visitor write\n * is the established cost here (`forms/submit`, `protection/unlock`); two\n * would be novel and is not paid for by what it buys.\n *\n * The path is **not** in the key, on purpose: one shared budget per (site,\n * IP) across cart, reviews, newsletter, bookings and beacons. Keying per path\n * would let a caller multiply its allowance by cycling endpoints, which is\n * free to do and defeats the point.\n *\n * `hostId` is frequently `''` — the dispatcher only resolves one from the\n * query or a JSON body, and a handler that self-gates may supply none. It is\n * kept in the key rather than skipped: AGL-1769 named \"an unresolvable\n * `hostId` skips the gate\" as an existing hole, and a limiter that a caller\n * turns off by declining to name a site is not a limiter. Host-less writes\n * simply share one bucket per IP.\n */\nexport function visitorWriteRateLimitKey(hostId: string, ip: string): string {\n  return `pluginwrite:${hostId || '-'}:${ip || 'unknown'}`\n}\n\n/**\n * Policy for the CONSOLE plugin-API dispatcher's write rate limit.\n *\n * `apps/console/app/api/[...pluginApi]/route.ts` dispatches every plugin's\n * console-facing handler — the marketplace installs and publishes, `ai/assist`,\n * gift cards, POS orders, refunds, the email list previews and the suppression\n * writes — and it carries no limiter of any kind. Its gates each refuse\n * something narrower: per-site enablement needs a resolvable `hostId`, the\n * release flag only asks whether the plugin is on, and lockdown only refuses\n * during an incident. None of them bounds volume from an ordinary signed-in\n * operator, which is every request the surface serves.\n *\n * The exposure is not the same one the visitor limiter closes. These handlers\n * are authenticated, so nobody is minting documents anonymously; what they do\n * instead is spend REAL money per call — a contact scan with a read budget, a\n * bundle download and verify, a model call to a paid vendor — on a surface\n * where a stuck retry loop in one console tab is indistinguishable from abuse.\n */\n\n/**\n * 120 requests per minute per console subject.\n *\n * `DEFAULT_RATE_LIMIT` / `DEFAULT_RATE_WINDOW_MS` again, and the same pair the\n * visitor limiter and the public REST API use, so this introduces no bespoke\n * number to reason about. It is far above a person pressing buttons: the\n * costly routes on this surface are one-per-click, and the console's own\n * page-load traffic reaches Firestore through the client SDK rather than\n * through this dispatcher.\n *\n * Deliberately not tighter even though each call here costs more than a cart\n * write. A limit that trips on genuine use gets raised until it means nothing,\n * and the per-call cost is the wrong lever for that anyway — an entitlement or\n * a quota bounds spend per org over a month, where this bounds a runaway loop\n * over a minute. Two different jobs; this one only has to make the loop stop.\n */\nexport const CONSOLE_API_RATE_LIMIT = 120\n\n/** Fixed 60s window, matching every other limiter in the codebase. */\nexport const CONSOLE_API_RATE_WINDOW_MS = 60_000\n\n/**\n * The limiter key: one bucket per authenticated subject.\n *\n * ## Why this is NOT the visitor key\n *\n * `visitorWriteRateLimitKey` is compound because its surface is\n * unauthenticated, and both halves of that argument are answers to anonymity.\n * Per-site alone was rejected there because one attacker would spend a whole\n * merchant's allowance and refuse real shoppers — an attacker-triggered denial\n * of service against the victim. On the console the subject is a verified\n * `uid`, so a caller can only ever refuse ITSELF: the self-DoS the compound key\n * exists to prevent cannot be aimed at anyone else, and the isolation it buys\n * is already bought by the identity.\n *\n * `hostId` is therefore left OUT rather than added, which is the opposite of\n * the visitor key and for the reason the visitor key leaves the PATH out: an\n * operator with fifty sites would otherwise hold fifty budgets and could\n * multiply its allowance by cycling a field it controls. One person is one\n * budget across every site they can reach.\n *\n * ## The unauthenticated fallback\n *\n * A caller whose bearer token did not decode — a plugin key, a POS device, an\n * anonymous probe — has no `uid`, and its client address stands in. That\n * bucket is shared by every such caller behind one address, which is the\n * conservative direction: an unidentified caller on an authenticated surface\n * should not get a private allowance for declining to identify itself. Keeping\n * it counted at all is the point. A limiter a caller switches off by sending\n * no credential is not a limiter, and this surface's whole exposure is what\n * runs BEFORE a handler decides who is asking.\n */\nexport function consoleApiRateLimitKey(subject: string): string {\n  return `consoleapi:${subject || 'unknown'}`\n}\n"],"names":["VISITOR_WRITE_RATE_LIMIT","VISITOR_WRITE_RATE_WINDOW_MS","MACHINE_API_PATHS","Set","MACHINE_API_PREFIXES","normalize","path","String","replace","isMachinePluginApiPath","normalized","has","some","prefix","startsWith","visitorWriteRateLimitKey","hostId","ip","CONSOLE_API_RATE_LIMIT","CONSOLE_API_RATE_WINDOW_MS","consoleApiRateLimitKey","subject"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;CAqBC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4BC,GACD,OAAO,MAAMA,2BAA2B,IAAG;AAE3C;;;;;CAKC,GACD,OAAO,MAAMC,+BAA+B,MAAM;AAElD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+DC,GACD,MAAMC,oBAAyC,IAAIC,IAAI;IACrD;IACA;IACA;IACA;IACA;IACA;IACA;CACD;AAED,+EAA+E,GAC/E,MAAMC,uBAA0C;IAAC;CAAS;AAE1D,oEAAoE,GACpE,SAASC,UAAUC,IAAY;IAC7B,OAAOC,OAAOD,eAAAA,OAAQ,IAAIE,OAAO,CAAC,cAAc;AAClD;AAEA;;;CAGC,GACD,OAAO,SAASC,uBAAuBH,IAAY;IACjD,MAAMI,aAAaL,UAAUC;IAC7B,IAAIJ,kBAAkBS,GAAG,CAACD,aAAa,OAAO;IAC9C,OAAON,qBAAqBQ,IAAI,CAAC,CAACC,SAAWH,WAAWI,UAAU,CAACD;AACrE;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyCC,GACD,OAAO,SAASE,yBAAyBC,MAAc,EAAEC,EAAU;IACjE,OAAO,CAAC,YAAY,EAAED,UAAU,IAAI,CAAC,EAAEC,MAAM,WAAW;AAC1D;AAEA;;;;;;;;;;;;;;;;;CAiBC,GAED;;;;;;;;;;;;;;;CAeC,GACD,OAAO,MAAMC,yBAAyB,IAAG;AAEzC,oEAAoE,GACpE,OAAO,MAAMC,6BAA6B,MAAM;AAEhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8BC,GACD,OAAO,SAASC,uBAAuBC,OAAe;IACpD,OAAO,CAAC,WAAW,EAAEA,WAAW,WAAW;AAC7C"}

package/src/lib/app-utils/plugin-artifact-path.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @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.
+ */
+/**
+ * Where a plugin build's bundle lives in the artifacts bucket.
+ *
+ * Its own module because a published page's client bundle reads this one
+ * function — `realm-plugins.ts` builds a trusted-realm bundle URL from it —
+ * while `plugin-manifest.ts` around it is the marketplace's publishing and
+ * revocation logic: manifest validation, offered and installable versions,
+ * revocation state, prop and element resolution. None of that runs on a
+ * customer site, and a bundler cannot drop it around a single named import.
+ */
+/**
+ * Content-addressed artifact object path in the isolated artifacts bucket.
+ * Immutable per `{listingId}/{version}/{sha256}` — a new build is a new
+ * path, so a consumer's pinned install can never be swapped underneath it.
+ */
+export declare function pluginArtifactPath(listingId: string, version: string, sha256: string): string;

package/src/lib/app-utils/plugin-artifact-path.js

@@ -0,0 +1,33 @@
+/**
+ * @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.
+ */ /**
+ * Where a plugin build's bundle lives in the artifacts bucket.
+ *
+ * Its own module because a published page's client bundle reads this one
+ * function — `realm-plugins.ts` builds a trusted-realm bundle URL from it —
+ * while `plugin-manifest.ts` around it is the marketplace's publishing and
+ * revocation logic: manifest validation, offered and installable versions,
+ * revocation state, prop and element resolution. None of that runs on a
+ * customer site, and a bundler cannot drop it around a single named import.
+ */ /**
+ * Content-addressed artifact object path in the isolated artifacts bucket.
+ * Immutable per `{listingId}/{version}/{sha256}` — a new build is a new
+ * path, so a consumer's pinned install can never be swapped underneath it.
+ */ export function pluginArtifactPath(listingId, version, sha256) {
+    return `artifacts/${listingId}/${version}/${sha256}.bundle`;
+}
+
+//# sourceMappingURL=plugin-artifact-path.js.map

package/src/lib/app-utils/plugin-artifact-path.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/plugin-artifact-path.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 * Where a plugin build's bundle lives in the artifacts bucket.\n *\n * Its own module because a published page's client bundle reads this one\n * function — `realm-plugins.ts` builds a trusted-realm bundle URL from it —\n * while `plugin-manifest.ts` around it is the marketplace's publishing and\n * revocation logic: manifest validation, offered and installable versions,\n * revocation state, prop and element resolution. None of that runs on a\n * customer site, and a bundler cannot drop it around a single named import.\n */\n\n/**\n * Content-addressed artifact object path in the isolated artifacts bucket.\n * Immutable per `{listingId}/{version}/{sha256}` — a new build is a new\n * path, so a consumer's pinned install can never be swapped underneath it.\n */\nexport function pluginArtifactPath(\n  listingId: string,\n  version: string,\n  sha256: string,\n): string {\n  return `artifacts/${listingId}/${version}/${sha256}.bundle`\n}\n"],"names":["pluginArtifactPath","listingId","version","sha256"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;CASC,GAED;;;;CAIC,GACD,OAAO,SAASA,mBACdC,SAAiB,EACjBC,OAAe,EACfC,MAAc;IAEd,OAAO,CAAC,UAAU,EAAEF,UAAU,CAAC,EAAEC,QAAQ,CAAC,EAAEC,OAAO,OAAO,CAAC;AAC7D"}

package/src/lib/app-utils/plugin-bundle-checks.d.ts

@@ -0,0 +1,148 @@
+/**
+ * @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 { PluginContributions } from '../plugin-manager/plugin-contributions';
+/** The areas the verifier reports on, in the order a reviewer reads them. */
+export type BundleCheckId = 'parse' | 'entry' | 'self-contained' | 'size' | 'code-execution' | 'globals' | 'storage' | 'dynamic-import' | 'network' | 'obfuscation' | 'contributions';
+export interface BundleCheckProblem {
+    level: 'error' | 'warning';
+    message: string;
+    /**
+     * Which check produced this. Optional so a verdict stored by an older
+     * checker still reads — those findings render on their own rather than
+     * under a check row.
+     */
+    check?: BundleCheckId;
+}
+/**
+ * `unknown` is the one that earns its keep (AGL-1087). A check that could
+ * not run — the network diff with no manifest supplied, everything at all
+ * when the parse failed — must not render as green, or the page tells a
+ * reviewer something was verified when nothing looked at it.
+ */
+export type BundleCheckStatus = 'pass' | 'fail' | 'question' | 'unknown';
+export interface BundleCheckSummary {
+    id: BundleCheckId;
+    /** Reviewer-facing name of the area. */
+    label: string;
+    status: BundleCheckStatus;
+    /** What the check actually saw, when that is worth stating on its own. */
+    detail?: string;
+}
+export interface BundleCheckResult {
+    ok: boolean;
+    problems: BundleCheckProblem[];
+    /** Every area, including the ones that found nothing (AGL-1087). */
+    checks: BundleCheckSummary[];
+    /** Which entry exports the source declares. */
+    exports: {
+        register: boolean;
+        registerApi: boolean;
+    };
+    /** What `register()` visibly registers (AGL-3116). */
+    contributions: DetectedContributions;
+}
+/**
+ * What a bundle's `register()` visibly registers (AGL-3116): the declaration
+ * its registration calls imply, read from the tree.
+ */
+export interface DetectedContributions {
+    contributes: PluginContributions;
+    /**
+     * Registrations the checker saw and could not read — an argument built at
+     * runtime. What they contribute is unknown, so a declaration cannot be
+     * checked against them and a reviewer has to read them.
+     */
+    unresolved: string[];
+}
+export declare const MAX_PLUGIN_BUNDLE_BYTES = 1000000;
+/**
+ * Stamped onto a cached verdict (AGL-962) so a stored result outlives only
+ * the checker that produced it.
+ *
+ * `checkPluginBundle` is pure over immutable, content-addressed bytes, so a
+ * verdict for a given sha256 never changes — but the CHECKS do. **Bump this
+ * whenever a rule is added, removed or loosened**, and every stored verdict
+ * from the old checker is ignored and recomputed on next read. Forgetting to
+ * bump means a reviewer sees a verdict from a checker that no longer exists,
+ * which is the failure mode re-running the verifier was meant to prevent.
+ *
+ * 2 — AST analysis replaces the regex scan (AGL-964).
+ * 3 — per-check summary added to the verdict (AGL-1087).
+ * 4 — calls through an alias are resolved (AGL-1090).
+ * 5 — URLs held in a constant are resolved (AGL-1093).
+ * 6 — registrations are compared with the declared contributions (AGL-3116).
+ */
+export declare const PLUGIN_VERIFIER_VERSION = 6;
+/** A verdict as stored on a `pluginVersions` doc (AGL-962). */
+export interface StoredBundleVerdict {
+    ok?: boolean;
+    problems?: BundleCheckProblem[];
+    /** Present from verifier 3 on (AGL-1087). */
+    checks?: BundleCheckSummary[];
+    sha256?: string;
+    verifierVersion?: number;
+}
+/**
+ * Whether a stored verdict may be served instead of re-running the checks.
+ *
+ * Fails closed on every mismatch: no verdict, a verdict for different bytes
+ * (a republished version keeps its version string but changes sha), or a
+ * verdict from a checker that has since changed. Any of those means
+ * download-and-recompute, which costs one page view rather than showing a
+ * reviewer a verdict that was never true of the bundle in front of them.
+ */
+export declare function isStoredVerdictCurrent(stored: StoredBundleVerdict | null | undefined, sha256: string): boolean;
+interface CheckOptions {
+    maxBytes?: number;
+    /**
+     * The origins the manifest declares under `capabilities.network`. A
+     * network call the manifest does not account for is the single most
+     * useful signal the tree makes available — and the per-manifest CSP
+     * would block it at runtime anyway, so the bundle and its manifest
+     * disagreeing is a bug the publisher wants to hear about at publish
+     * time, not a mystery in production. Undefined = "not supplied", which
+     * downgrades those findings to warnings, because a checker that was
+     * never told what was declared cannot claim anything was undeclared.
+     */
+    declaredNetwork?: string[];
+    /**
+     * The manifest's `contributes` block (AGL-3116): `null` when the manifest
+     * declares none, `undefined` when no manifest was supplied — which leaves
+     * the comparison `unknown`, as the network diff is without its manifest.
+     */
+    declaredContributions?: PluginContributions | null;
+    /**
+     * Refuse a bundle that registers something while its manifest declares no
+     * contributions at all. Set where a NEW version is judged — the publish
+     * pipeline and the local verifier that mirrors it. The review page and the
+     * re-verification sweep judge versions published before the contract,
+     * which load under its default, and a rule they were never held to must
+     * not turn them red after the fact.
+     */
+    requireContributions?: boolean;
+}
+/**
+ * Run the checks over a bundle. NEVER throws (AGL-1094).
+ *
+ * The publish route calls this directly, so an unexpected failure in here
+ * used to mean a 500 and no explanation for the publisher — and in the review
+ * sweep it looked exactly like a missing artifact, which sent the
+ * investigation to the storage bucket instead of to this file. A checker that
+ * cannot analyse a bundle has an answer: say so, in the verdict, as an error.
+ */
+export declare function checkPluginBundle(source: string, options?: CheckOptions): BundleCheckResult;
+export {};