@aglyn/aglyn 1.0.0-beta.143

package/src/lib/app-utils/plugin-api-cross-origin.d.ts

@@ -0,0 +1,61 @@
+/**
+ * @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.
+ */
+/**
+ * 403, not 401.
+ *
+ * The caller's credential is fine — that is the whole problem. What is
+ * refused is the ORIGIN it came from, and no re-authentication would change
+ * the answer, so `401 Unauthorized` (which invites a retry with credentials)
+ * would be a lie. Matches how the lockdown gate reasons about 423.
+ */
+export declare const CROSS_ORIGIN_REFUSED_STATUS = 403;
+export interface CrossOriginWriteOptions {
+    /** Dispatcher path, e.g. `commerce/cart`. Decides visitor vs machine. */
+    path: string;
+    /** Read for its method, `origin`, `x-forwarded-host` and `host`. */
+    request: {
+        method?: string;
+        headers?: {
+            get?: (name: string) => unknown;
+        };
+    };
+}
+/**
+ * Is this a state-changing plugin-API request from another origin?
+ *
+ * Exported separately from the refusal so the decision can be asserted
+ * directly in tests and reused by the console dispatcher without either
+ * inheriting a `Response` shape it may not want.
+ */
+export declare function isCrossOriginPluginWrite(options: CrossOriginWriteOptions): boolean;
+/**
+ * The refusal a cross-origin plugin write returns, or null to proceed:
+ *
+ *   const foreign = crossOriginPluginWriteRefusal({ path, request })
+ *   if (foreign) return foreign
+ *
+ * Same "return it or carry on" contract as `visitorWriteRefusal` and
+ * `visitorWriteRateLimitRefusal`, so the dispatcher reads as one list of
+ * gates rather than three shapes.
+ *
+ * The body names the reason. Unlike the rate limiter — which is deliberately
+ * mute because it faces abusers and every detail is a hint — this refusal is
+ * one a legitimate integrator can hit by calling from the wrong host, and a
+ * bare 403 would cost them an afternoon. It discloses nothing an attacker did
+ * not already know, having chosen the origin themselves.
+ */
+export declare function crossOriginPluginWriteRefusal(options: CrossOriginWriteOptions): Response | null;

package/src/lib/app-utils/plugin-api-cross-origin.js

@@ -0,0 +1,202 @@
+/**
+ * @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.
+ */ /**
+ * Same-origin policy for visitor-facing plugin-API WRITES (AGL-1880).
+ *
+ * Pure and dependency-free, beside `plugin-api-rate-limit` and for the same
+ * reason: the dispatcher gate is one line, and the reasoning it encodes is
+ * unit-testable without a route harness.
+ *
+ * ## The hole this closes
+ *
+ * The standing claim — recorded on 2026-07-24 when CSRF was considered and
+ * deliberately NOT added — was that CSRF is *structurally impossible* here
+ * because every API route authorizes with `Authorization: Bearer <idToken>`,
+ * which a browser never attaches on its own. That claim was audited against
+ * the tree on 2026-08-19 and it holds for all 140 console routes. It does not
+ * hold for the tenant plugin-API dispatcher, and the exception was never an
+ * exception anyone wrote down:
+ *
+ * - `libs/plugins/commerce/**` handlers authorize by COOKIE, not Bearer —
+ *   `aglyn_member_{hostId}` for `membership/account`, `membership/wishlist`,
+ *   `membership/logout`, `commerce/stream`, `commerce/subscription-portal`,
+ *   and `aglyn_cart_{hostId}` for `commerce/cart`, `commerce/cart-checkout`.
+ * - Several of those MUTATE: `membership/account` writes `displayName` and
+ *   the address book, `membership/wishlist` writes the wishlist,
+ *   `commerce/cart` writes cart lines.
+ * - `api-adapter` parses `application/x-www-form-urlencoded` into `req.body`,
+ *   and the handlers read `hostId` from `req.body`. That content type is a
+ *   CORS-*simple* request, so a cross-origin HTML form POST reaches the
+ *   handler with **no preflight** to refuse it.
+ *
+ * ## Why `SameSite=Lax` is not already the answer
+ *
+ * It is the only thing standing there today, and it stops the ordinary case:
+ * a POST from an unrelated site is cross-SITE, so the cookie is withheld.
+ *
+ * It does not stop the case this platform creates. Every published tenant
+ * lives under `*.aglyn.app`, and sibling subdomains of one registrable domain
+ * are same-SITE. `SameSite` is not `SameOrigin`. So a form POST from
+ * `evil.aglyn.app` to `victim.aglyn.app/api/membership/account` carries
+ * `aglyn_member_victim` in full, and the tenant who authored `evil` is an
+ * ordinary customer who signed up. The cookie flag is doing exactly what it
+ * documents; it is simply the wrong boundary for a multi-tenant apex.
+ *
+ * ## The rule
+ *
+ * A state-changing plugin-API request must be same-ORIGIN. Reads are
+ * untouched — a cross-origin GET carries no authority a cross-origin
+ * `<img>`/`<script>` did not already have, and the console's preview surface
+ * reads these paths legitimately.
+ *
+ * An ABSENT `Origin` header is allowed, and that is the one judgement call
+ * worth stating plainly. CSRF is an attack a browser is tricked into
+ * performing, and a browser always sends `Origin` on a cross-origin request
+ * — including the form POST above, and including every no-preflight simple
+ * request. Absence therefore means a non-browser caller: `curl`, a webhook,
+ * the server-to-server `commerce/supplier-update` hop. Refusing those would
+ * break real integrations to defend against a client that, by definition,
+ * chooses its own headers and would simply omit the one we demanded. Header
+ * presence is not a credential — the same reasoning `plugin-api-rate-limit`
+ * uses to refuse to exempt on `authorization` being present.
+ *
+ * A literal `Origin: null` is NOT allowed through ON ITS OWN. It is an opaque
+ * origin — a sandboxed iframe, or a POST that arrived via a redirect — and it
+ * is precisely the shape an attacker reaches for once a plain cross-origin
+ * POST is refused. `null` is never same-origin with anything, so it fails the
+ * comparison rather than needing a special case; the constant exists so the
+ * intent is legible.
+ *
+ * ## ⚠️ `Sec-Fetch-Site`, and the same-origin form this rule used to refuse
+ *
+ * `Origin: null` is not only an attacker's shape. A page served with
+ * `Referrer-Policy: no-referrer` sends `Origin: null` on its OWN top-level
+ * form POST — the referrer policy governs the Origin header on a navigation,
+ * so a form submitting to the very page that rendered it arrives opaque.
+ *
+ * That is not a hypothetical. Every recipient-facing email page —
+ * `email/preferences`, `email/unsubscribe`, `email/resubscribe` — sets
+ * `no-referrer` deliberately, so a signed opt-out URL cannot leak through a
+ * `Referer` header. The result was that the preference centre's own "Save my
+ * preferences" button was refused 403 as cross-site, while a `fetch()` from
+ * the same document succeeded: a recipient could open the page, untick a
+ * topic, press Save, and be shown a JSON error while nothing was written.
+ * The privacy hardening had disabled the control it was protecting.
+ *
+ * `Sec-Fetch-Site` is the discriminator, and it is the right one because the
+ * BROWSER computes it and page script cannot set it. `same-origin` and
+ * `none` (a user typing the URL or opening a bookmark) are both statements
+ * that this did not come from another site, and they are trustworthy in a way
+ * the Origin header — deliberately blanked by our own policy — no longer is
+ * here. It is consulted only to ALLOW: a `cross-site` or `same-site` value
+ * falls through to the origin comparison exactly as before, so nothing an
+ * attacker can send gets a new way in. A caller that omits the header is
+ * unchanged too, which keeps the non-browser allowance above intact.
+ */ import { lockdownIntentForMethod } from "./lockdown.js";
+import { isMachinePluginApiPath } from "./plugin-api-rate-limit.js";
+/**
+ * 403, not 401.
+ *
+ * The caller's credential is fine — that is the whole problem. What is
+ * refused is the ORIGIN it came from, and no re-authentication would change
+ * the answer, so `401 Unauthorized` (which invites a retry with credentials)
+ * would be a lie. Matches how the lockdown gate reasons about 423.
+ */ export const CROSS_ORIGIN_REFUSED_STATUS = 403;
+/** The opaque origin. Never same-origin with anything, including itself. */ const OPAQUE_ORIGIN = 'null';
+/** Host of an `Origin` header value, or `''` when it is absent/unparsable. */ function originHost(origin) {
+    const raw = String(origin != null ? origin : '').trim();
+    if (!raw || raw === OPAQUE_ORIGIN) return '';
+    try {
+        return new URL(raw).host.toLowerCase();
+    } catch (unused) {
+        return '';
+    }
+}
+/**
+ * The host this request was actually addressed to.
+ *
+ * `x-forwarded-host` first: behind Vercel that is the public hostname the
+ * visitor typed, while `host` can be the internal one. Falls back to `host`
+ * so the function is still correct off-platform (self-host, local dev), which
+ * `deployment-shape` makes a supported case rather than a hypothetical.
+ */ function requestHost(headers) {
+    var _ref, _ref1;
+    var _String_split_, _headers_get, _headers_get1;
+    const forwarded = (_String_split_ = String((_ref = headers == null ? void 0 : (_headers_get = headers.get) == null ? void 0 : _headers_get.call(headers, 'x-forwarded-host')) != null ? _ref : '').split(',')[0]) == null ? void 0 : _String_split_.trim();
+    const host = forwarded || String((_ref1 = headers == null ? void 0 : (_headers_get1 = headers.get) == null ? void 0 : _headers_get1.call(headers, 'host')) != null ? _ref1 : '').trim();
+    return host.toLowerCase();
+}
+/**
+ * Is this a state-changing plugin-API request from another origin?
+ *
+ * Exported separately from the refusal so the decision can be asserted
+ * directly in tests and reused by the console dispatcher without either
+ * inheriting a `Response` shape it may not want.
+ */ export function isCrossOriginPluginWrite(options) {
+    var _ref, _ref1;
+    var _options_request, _options_request1, _headers_get, _headers_get1;
+    if (lockdownIntentForMethod(options == null ? void 0 : (_options_request = options.request) == null ? void 0 : _options_request.method) === 'read') return false;
+    if (isMachinePluginApiPath(options == null ? void 0 : options.path)) return false;
+    const headers = (_ref = options == null ? void 0 : (_options_request1 = options.request) == null ? void 0 : _options_request1.headers) != null ? _ref : {};
+    /*
+   * The browser's own statement about where this came from, trusted before
+   * the Origin header because our own `no-referrer` policy blanks that one.
+   * ALLOW-only: any other value falls through to the comparison below.
+   */ const site = String((_ref1 = headers == null ? void 0 : (_headers_get = headers.get) == null ? void 0 : _headers_get.call(headers, 'sec-fetch-site')) != null ? _ref1 : '').trim().toLowerCase();
+    if (site === 'same-origin' || site === 'none') return false;
+    const origin = headers == null ? void 0 : (_headers_get1 = headers.get) == null ? void 0 : _headers_get1.call(headers, 'origin');
+    // Absent Origin: a non-browser caller. See the module note — this is the
+    // deliberate allowance, not an oversight.
+    if (origin === null || origin === undefined || String(origin).trim() === '') {
+        return false;
+    }
+    const from = originHost(String(origin));
+    const to = requestHost(headers);
+    // An unparsable or opaque Origin yields `''`, which can never equal a real
+    // host, so it lands here as cross-origin — the intended outcome.
+    if (!to) {
+        // No host to compare against. Refusing every write on a malformed request
+        // would be a worse failure than the one being prevented, and a request
+        // with no Host reached no tenant site to begin with.
+        return false;
+    }
+    return from !== to;
+}
+/**
+ * The refusal a cross-origin plugin write returns, or null to proceed:
+ *
+ *   const foreign = crossOriginPluginWriteRefusal({ path, request })
+ *   if (foreign) return foreign
+ *
+ * Same "return it or carry on" contract as `visitorWriteRefusal` and
+ * `visitorWriteRateLimitRefusal`, so the dispatcher reads as one list of
+ * gates rather than three shapes.
+ *
+ * The body names the reason. Unlike the rate limiter — which is deliberately
+ * mute because it faces abusers and every detail is a hint — this refusal is
+ * one a legitimate integrator can hit by calling from the wrong host, and a
+ * bare 403 would cost them an afternoon. It discloses nothing an attacker did
+ * not already know, having chosen the origin themselves.
+ */ export function crossOriginPluginWriteRefusal(options) {
+    if (!isCrossOriginPluginWrite(options)) return null;
+    return Response.json({
+        error: 'Cross-origin writes are not allowed.'
+    }, {
+        status: CROSS_ORIGIN_REFUSED_STATUS
+    });
+}
+
+//# sourceMappingURL=plugin-api-cross-origin.js.map

package/src/lib/app-utils/plugin-api-cross-origin.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/plugin-api-cross-origin.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 * Same-origin policy for visitor-facing plugin-API WRITES (AGL-1880).\n *\n * Pure and dependency-free, beside `plugin-api-rate-limit` and for the same\n * reason: the dispatcher gate is one line, and the reasoning it encodes is\n * unit-testable without a route harness.\n *\n * ## The hole this closes\n *\n * The standing claim — recorded on 2026-07-24 when CSRF was considered and\n * deliberately NOT added — was that CSRF is *structurally impossible* here\n * because every API route authorizes with `Authorization: Bearer <idToken>`,\n * which a browser never attaches on its own. That claim was audited against\n * the tree on 2026-08-19 and it holds for all 140 console routes. It does not\n * hold for the tenant plugin-API dispatcher, and the exception was never an\n * exception anyone wrote down:\n *\n * - `libs/plugins/commerce/**` handlers authorize by COOKIE, not Bearer —\n *   `aglyn_member_{hostId}` for `membership/account`, `membership/wishlist`,\n *   `membership/logout`, `commerce/stream`, `commerce/subscription-portal`,\n *   and `aglyn_cart_{hostId}` for `commerce/cart`, `commerce/cart-checkout`.\n * - Several of those MUTATE: `membership/account` writes `displayName` and\n *   the address book, `membership/wishlist` writes the wishlist,\n *   `commerce/cart` writes cart lines.\n * - `api-adapter` parses `application/x-www-form-urlencoded` into `req.body`,\n *   and the handlers read `hostId` from `req.body`. That content type is a\n *   CORS-*simple* request, so a cross-origin HTML form POST reaches the\n *   handler with **no preflight** to refuse it.\n *\n * ## Why `SameSite=Lax` is not already the answer\n *\n * It is the only thing standing there today, and it stops the ordinary case:\n * a POST from an unrelated site is cross-SITE, so the cookie is withheld.\n *\n * It does not stop the case this platform creates. Every published tenant\n * lives under `*.aglyn.app`, and sibling subdomains of one registrable domain\n * are same-SITE. `SameSite` is not `SameOrigin`. So a form POST from\n * `evil.aglyn.app` to `victim.aglyn.app/api/membership/account` carries\n * `aglyn_member_victim` in full, and the tenant who authored `evil` is an\n * ordinary customer who signed up. The cookie flag is doing exactly what it\n * documents; it is simply the wrong boundary for a multi-tenant apex.\n *\n * ## The rule\n *\n * A state-changing plugin-API request must be same-ORIGIN. Reads are\n * untouched — a cross-origin GET carries no authority a cross-origin\n * `<img>`/`<script>` did not already have, and the console's preview surface\n * reads these paths legitimately.\n *\n * An ABSENT `Origin` header is allowed, and that is the one judgement call\n * worth stating plainly. CSRF is an attack a browser is tricked into\n * performing, and a browser always sends `Origin` on a cross-origin request\n * — including the form POST above, and including every no-preflight simple\n * request. Absence therefore means a non-browser caller: `curl`, a webhook,\n * the server-to-server `commerce/supplier-update` hop. Refusing those would\n * break real integrations to defend against a client that, by definition,\n * chooses its own headers and would simply omit the one we demanded. Header\n * presence is not a credential — the same reasoning `plugin-api-rate-limit`\n * uses to refuse to exempt on `authorization` being present.\n *\n * A literal `Origin: null` is NOT allowed through ON ITS OWN. It is an opaque\n * origin — a sandboxed iframe, or a POST that arrived via a redirect — and it\n * is precisely the shape an attacker reaches for once a plain cross-origin\n * POST is refused. `null` is never same-origin with anything, so it fails the\n * comparison rather than needing a special case; the constant exists so the\n * intent is legible.\n *\n * ## ⚠️ `Sec-Fetch-Site`, and the same-origin form this rule used to refuse\n *\n * `Origin: null` is not only an attacker's shape. A page served with\n * `Referrer-Policy: no-referrer` sends `Origin: null` on its OWN top-level\n * form POST — the referrer policy governs the Origin header on a navigation,\n * so a form submitting to the very page that rendered it arrives opaque.\n *\n * That is not a hypothetical. Every recipient-facing email page —\n * `email/preferences`, `email/unsubscribe`, `email/resubscribe` — sets\n * `no-referrer` deliberately, so a signed opt-out URL cannot leak through a\n * `Referer` header. The result was that the preference centre's own \"Save my\n * preferences\" button was refused 403 as cross-site, while a `fetch()` from\n * the same document succeeded: a recipient could open the page, untick a\n * topic, press Save, and be shown a JSON error while nothing was written.\n * The privacy hardening had disabled the control it was protecting.\n *\n * `Sec-Fetch-Site` is the discriminator, and it is the right one because the\n * BROWSER computes it and page script cannot set it. `same-origin` and\n * `none` (a user typing the URL or opening a bookmark) are both statements\n * that this did not come from another site, and they are trustworthy in a way\n * the Origin header — deliberately blanked by our own policy — no longer is\n * here. It is consulted only to ALLOW: a `cross-site` or `same-site` value\n * falls through to the origin comparison exactly as before, so nothing an\n * attacker can send gets a new way in. A caller that omits the header is\n * unchanged too, which keeps the non-browser allowance above intact.\n */\n\nimport { lockdownIntentForMethod } from './lockdown'\nimport { isMachinePluginApiPath } from './plugin-api-rate-limit'\n\n/**\n * 403, not 401.\n *\n * The caller's credential is fine — that is the whole problem. What is\n * refused is the ORIGIN it came from, and no re-authentication would change\n * the answer, so `401 Unauthorized` (which invites a retry with credentials)\n * would be a lie. Matches how the lockdown gate reasons about 423.\n */\nexport const CROSS_ORIGIN_REFUSED_STATUS = 403\n\n/** The opaque origin. Never same-origin with anything, including itself. */\nconst OPAQUE_ORIGIN = 'null'\n\n/** Host of an `Origin` header value, or `''` when it is absent/unparsable. */\nfunction originHost(origin: string | null | undefined): string {\n  const raw = String(origin ?? '').trim()\n  if (!raw || raw === OPAQUE_ORIGIN) return ''\n  try {\n    return new URL(raw).host.toLowerCase()\n  } catch {\n    return ''\n  }\n}\n\n/**\n * The host this request was actually addressed to.\n *\n * `x-forwarded-host` first: behind Vercel that is the public hostname the\n * visitor typed, while `host` can be the internal one. Falls back to `host`\n * so the function is still correct off-platform (self-host, local dev), which\n * `deployment-shape` makes a supported case rather than a hypothetical.\n */\nfunction requestHost(headers: {\n  get?: (name: string) => unknown\n}): string {\n  const forwarded = String(headers?.get?.('x-forwarded-host') ?? '')\n    .split(',')[0]\n    ?.trim()\n  const host = forwarded || String(headers?.get?.('host') ?? '').trim()\n  return host.toLowerCase()\n}\n\nexport interface CrossOriginWriteOptions {\n  /** Dispatcher path, e.g. `commerce/cart`. Decides visitor vs machine. */\n  path: string\n  /** Read for its method, `origin`, `x-forwarded-host` and `host`. */\n  request: { method?: string; headers?: { get?: (name: string) => unknown } }\n}\n\n/**\n * Is this a state-changing plugin-API request from another origin?\n *\n * Exported separately from the refusal so the decision can be asserted\n * directly in tests and reused by the console dispatcher without either\n * inheriting a `Response` shape it may not want.\n */\nexport function isCrossOriginPluginWrite(\n  options: CrossOriginWriteOptions,\n): boolean {\n  if (lockdownIntentForMethod(options?.request?.method) === 'read') return false\n  if (isMachinePluginApiPath(options?.path)) return false\n\n  const headers = options?.request?.headers ?? {}\n\n  /*\n   * The browser's own statement about where this came from, trusted before\n   * the Origin header because our own `no-referrer` policy blanks that one.\n   * ALLOW-only: any other value falls through to the comparison below.\n   */\n  const site = String(headers?.get?.('sec-fetch-site') ?? '')\n    .trim()\n    .toLowerCase()\n  if (site === 'same-origin' || site === 'none') return false\n\n  const origin = headers?.get?.('origin')\n  // Absent Origin: a non-browser caller. See the module note — this is the\n  // deliberate allowance, not an oversight.\n  if (origin === null || origin === undefined || String(origin).trim() === '') {\n    return false\n  }\n\n  const from = originHost(String(origin))\n  const to = requestHost(headers)\n  // An unparsable or opaque Origin yields `''`, which can never equal a real\n  // host, so it lands here as cross-origin — the intended outcome.\n  if (!to) {\n    // No host to compare against. Refusing every write on a malformed request\n    // would be a worse failure than the one being prevented, and a request\n    // with no Host reached no tenant site to begin with.\n    return false\n  }\n  return from !== to\n}\n\n/**\n * The refusal a cross-origin plugin write returns, or null to proceed:\n *\n *   const foreign = crossOriginPluginWriteRefusal({ path, request })\n *   if (foreign) return foreign\n *\n * Same \"return it or carry on\" contract as `visitorWriteRefusal` and\n * `visitorWriteRateLimitRefusal`, so the dispatcher reads as one list of\n * gates rather than three shapes.\n *\n * The body names the reason. Unlike the rate limiter — which is deliberately\n * mute because it faces abusers and every detail is a hint — this refusal is\n * one a legitimate integrator can hit by calling from the wrong host, and a\n * bare 403 would cost them an afternoon. It discloses nothing an attacker did\n * not already know, having chosen the origin themselves.\n */\nexport function crossOriginPluginWriteRefusal(\n  options: CrossOriginWriteOptions,\n): Response | null {\n  if (!isCrossOriginPluginWrite(options)) return null\n  return Response.json(\n    { error: 'Cross-origin writes are not allowed.' },\n    { status: CROSS_ORIGIN_REFUSED_STATUS },\n  )\n}\n"],"names":["lockdownIntentForMethod","isMachinePluginApiPath","CROSS_ORIGIN_REFUSED_STATUS","OPAQUE_ORIGIN","originHost","origin","raw","String","trim","URL","host","toLowerCase","requestHost","headers","forwarded","get","split","isCrossOriginPluginWrite","options","request","method","path","site","undefined","from","to","crossOriginPluginWriteRefusal","Response","json","error","status"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4FC,GAED,SAASA,uBAAuB,QAAQ,gBAAY;AACpD,SAASC,sBAAsB,QAAQ,6BAAyB;AAEhE;;;;;;;CAOC,GACD,OAAO,MAAMC,8BAA8B,IAAG;AAE9C,0EAA0E,GAC1E,MAAMC,gBAAgB;AAEtB,4EAA4E,GAC5E,SAASC,WAAWC,MAAiC;IACnD,MAAMC,MAAMC,OAAOF,iBAAAA,SAAU,IAAIG,IAAI;IACrC,IAAI,CAACF,OAAOA,QAAQH,eAAe,OAAO;IAC1C,IAAI;QACF,OAAO,IAAIM,IAAIH,KAAKI,IAAI,CAACC,WAAW;IACtC,EAAE,eAAM;QACN,OAAO;IACT;AACF;AAEA;;;;;;;CAOC,GACD,SAASC,YAAYC,OAEpB;;QACmBN,gBAAOM,cAGQA;IAHjC,MAAMC,aAAYP,iBAAAA,eAAOM,4BAAAA,eAAAA,QAASE,GAAG,qBAAZF,kBAAAA,SAAe,sCAAuB,IAC5DG,KAAK,CAAC,IAAI,CAAC,EAAE,qBADET,eAEdC,IAAI;IACR,MAAME,OAAOI,aAAaP,gBAAOM,4BAAAA,gBAAAA,QAASE,GAAG,qBAAZF,mBAAAA,SAAe,2BAAW,IAAIL,IAAI;IACnE,OAAOE,KAAKC,WAAW;AACzB;AASA;;;;;;CAMC,GACD,OAAO,SAASM,yBACdC,OAAgC;;QAEJA,kBAGZA,mBAOIL,cAKLA;IAff,IAAIb,wBAAwBkB,4BAAAA,mBAAAA,QAASC,OAAO,qBAAhBD,iBAAkBE,MAAM,MAAM,QAAQ,OAAO;IACzE,IAAInB,uBAAuBiB,2BAAAA,QAASG,IAAI,GAAG,OAAO;IAElD,MAAMR,kBAAUK,4BAAAA,oBAAAA,QAASC,OAAO,qBAAhBD,kBAAkBL,OAAO,mBAAI,CAAC;IAE9C;;;;GAIC,GACD,MAAMS,OAAOf,gBAAOM,4BAAAA,eAAAA,QAASE,GAAG,qBAAZF,kBAAAA,SAAe,qCAAqB,IACrDL,IAAI,GACJG,WAAW;IACd,IAAIW,SAAS,iBAAiBA,SAAS,QAAQ,OAAO;IAEtD,MAAMjB,SAASQ,4BAAAA,gBAAAA,QAASE,GAAG,qBAAZF,mBAAAA,SAAe;IAC9B,yEAAyE;IACzE,0CAA0C;IAC1C,IAAIR,WAAW,QAAQA,WAAWkB,aAAahB,OAAOF,QAAQG,IAAI,OAAO,IAAI;QAC3E,OAAO;IACT;IAEA,MAAMgB,OAAOpB,WAAWG,OAAOF;IAC/B,MAAMoB,KAAKb,YAAYC;IACvB,2EAA2E;IAC3E,iEAAiE;IACjE,IAAI,CAACY,IAAI;QACP,0EAA0E;QAC1E,uEAAuE;QACvE,qDAAqD;QACrD,OAAO;IACT;IACA,OAAOD,SAASC;AAClB;AAEA;;;;;;;;;;;;;;;CAeC,GACD,OAAO,SAASC,8BACdR,OAAgC;IAEhC,IAAI,CAACD,yBAAyBC,UAAU,OAAO;IAC/C,OAAOS,SAASC,IAAI,CAClB;QAAEC,OAAO;IAAuC,GAChD;QAAEC,QAAQ5B;IAA4B;AAE1C"}

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

@@ -0,0 +1,192 @@
+/**
+ * @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 declare 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 declare const VISITOR_WRITE_RATE_WINDOW_MS = 60000;
+/**
+ * Is this dispatcher path a credentialed machine surface (exempt), rather
+ * than a visitor one (limited)? Unknown paths are visitor by default.
+ */
+export declare function isMachinePluginApiPath(path: string): boolean;
+/**
+ * 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 declare function visitorWriteRateLimitKey(hostId: string, ip: string): string;
+/**
+ * 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 declare const CONSOLE_API_RATE_LIMIT = 120;
+/** Fixed 60s window, matching every other limiter in the codebase. */
+export declare 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 declare function consoleApiRateLimitKey(subject: string): string;