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

package/src/lib/server/membership-recover-throttle.js

@@ -0,0 +1,231 @@
+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.
+ */ import { consumeRateLimit } from "./rate-limit-store.js";
+/**
+ * Throttle for the UNAUTHENTICATED site-member password-recovery endpoint
+ * (AGL-1966).
+ *
+ * ## The shape being closed
+ *
+ * Two unauthenticated tenant plugin endpoints compose into a mail relay on
+ * `aglyn.com`'s sending domain: `membership/register` puts an arbitrary
+ * address into `hosts/{hostId}/siteMembers` (member accounts are unlimited on
+ * every plan, AGL-889, so nothing there refuses), and `membership/recover`
+ * mails a reset link to any address that has such a row. Register N addresses,
+ * call recover N times, and every one is a real message we sent, carrying an
+ * attacker-chosen site name in the subject.
+ *
+ * The only thing in the way was the dispatcher's `visitorWriteRateLimitRefusal`
+ * — 120 writes/60s per (site, IP), a bucket register and recover SHARE. That
+ * ceiling is sized for a shopper editing cart quantities; measured as mail it
+ * is ~86k messages a day from one address.
+ *
+ * The damage is not the Resend bill. It is the sending reputation of
+ * `aglyn.com`, which is shared by every customer's transactional mail, and
+ * which cannot be bought back after the fact.
+ *
+ * ## Why this is a separate module from `password-reset-throttle.ts`
+ *
+ * That one guards ADMIN-initiated resets, and says so at length: every caller
+ * is already authenticated as staff, an org admin or a site admin, "so this is
+ * **not** the enumeration defense that guards the public `membership/recover`
+ * endpoint — nobody reaches here without already knowing the account exists."
+ * This is that defense. The caps differ (there is no actor to key on here, and
+ * an IP is not an actor), and the refusal contract differs — see below, it is
+ * the part that is easy to get wrong.
+ *
+ * It lives at this layer, beside its sibling, for the reason that one gives:
+ * the commerce plugin cannot import the console's API helpers, and a number
+ * duplicated in two places drifts.
+ *
+ * ## Two kinds of cap, because they have two different refusals
+ *
+ * This is the load-bearing distinction in the module, and it exists entirely
+ * to keep the endpoint from becoming an existence oracle.
+ *
+ * **Attempt caps** ({@link consumeMembershipRecoverAttempt}) — per recipient
+ * and per IP. Consumed BEFORE the member lookup, so a request for an address
+ * that is a member and a request for one that is not spend exactly the same
+ * budget and get exactly the same answer. Their refusal may therefore be a
+ * visible `429`: it says nothing about whether the address exists, because the
+ * counter that produced it counts both alike. Consuming these *after* the
+ * lookup, or only on the send path, would be the bug — the 429 would then
+ * appear only for real members and the endpoint's whole silent-success
+ * contract would be undone by its own rate limiter.
+ *
+ * **The send cap** ({@link consumeMembershipRecoverSend}) — per host, per day.
+ * Consumed only when a message is actually about to go out, because it is a
+ * ceiling on OUTBOUND MAIL rather than on requests. That means it is only ever
+ * reached on the member-exists branch, so its refusal must NOT be visible: the
+ * caller takes the same silent `200 {ok:true}` exit as an unknown address. The
+ * cost of that is a real member who gets no mail and no error during an
+ * attack on their site — collateral that is accepted deliberately, and sized
+ * for below.
+ *
+ * ## Backed by the durable limiter, not a `Map`
+ *
+ * `membership-recover.ts` previously carried a per-instance `Map` keyed on
+ * IP+email. On Vercel that is close to no limit at all — it resets on every
+ * cold start and each concurrent instance keeps its own, so the effective cap
+ * is `limit × instances` and an attacker widens it by going wider (AGL-794).
+ * A mail send is exactly the "consequence, not volume" case that
+ * `RATE_LIMITING.md` says to spend a Firestore transaction on.
+ *
+ * ### Contention fails CLOSED here, and that is correct (AGL-2404)
+ *
+ * `consumeRateLimit` refuses with `contended: true` when one key is hot, and
+ * only degrades when the store itself is unreachable. Both postures land well
+ * on this surface. The attempt keys are per recipient and per IP, so a
+ * legitimate visitor essentially never races themselves — concurrency on one
+ * of these keys is the attack. And the send key is per host per day, which is
+ * one document: a busy site's genuine recover traffic is a handful of requests
+ * an hour, so contention there is likewise a flood rather than a Tuesday.
+ */ /**
+ * Reset mails per recipient address, per hour, across every site.
+ *
+ * Matches `RESET_SENDS_PER_RECIPIENT` deliberately: a reset link is valid for
+ * an hour anyway, so a second and third are only useful if the first was lost,
+ * and one number for "how many resets may one mailbox receive in an hour" is
+ * easier to defend than two.
+ *
+ * NOT keyed by host. A per-(host, address) cap would let an attacker who
+ * controls several sites — which a free org can create — multiply one
+ * mailbox's mail by the number of sites, and the person being carpet-bombed
+ * does not care which of our customers' sites the mail claims to come from.
+ */ export const RECOVER_SENDS_PER_RECIPIENT = 3;
+/**
+ * Recovery attempts per client IP, per hour, across every site and address.
+ *
+ * Sized against the human behaviour, not the attack: a person who has
+ * forgotten a password tries it on one or two sites, mistypes the address
+ * once, and stops. Ten is already several times that. A household or office
+ * NAT sharing one address would need ten genuine forgotten passwords in one
+ * hour to notice this.
+ *
+ * This is the cap that actually prices enumeration. The per-recipient cap
+ * alone does nothing against the register-then-recover composition, because
+ * every address in that attack is fresh and none of them has a count.
+ */ export const RECOVER_ATTEMPTS_PER_IP = 10;
+/** Both attempt caps use a one-hour fixed window, like their sibling. */ export const RECOVER_ATTEMPT_WINDOW_MS = 60 * 60 * 1000;
+/**
+ * Recovery mails one SITE may emit per day.
+ *
+ * An abuse ceiling, not a usage limit, and it is set where it is because of
+ * the collateral described above: it must sit far enough above any real site's
+ * genuine volume that reaching it is evidence of an attack. A storefront with
+ * ten thousand members sees single-digit resets a day; two hundred is more
+ * than an order of magnitude of headroom.
+ *
+ * What it buys, given the dispatcher's 120/min already upstream: it converts
+ * "~86k messages a day per site from one IP" into 200, and — because it is
+ * keyed on the site rather than on the caller — it holds no matter how many
+ * IPs the caller brings. That is the property the compound visitor-write key
+ * explicitly cannot have, and the reason this cap is per host alone.
+ */ export const RECOVER_SENDS_PER_HOST_PER_DAY = 200;
+/** Fixed 24h window for the send cap. */ export const RECOVER_SEND_WINDOW_MS = 24 * 60 * 60 * 1000;
+/**
+ * How new a member row may be and still be worth a reset mail.
+ *
+ * The register-then-recover composition is the whole attack, and no real
+ * person needs a password reset in the first ten minutes of having chosen the
+ * password. This is the cheapest control on the list and the only one that
+ * refuses the composition itself rather than rationing it.
+ *
+ * Enforced by the handler (it needs the member document); the constant lives
+ * here so the policy is in one place.
+ */ export const RECOVER_MIN_MEMBER_AGE_MS = 10 * 60 * 1000;
+function refusal(limited, resetMs, at, rate) {
+    return {
+        allowed: false,
+        retryAfterSeconds: Math.max(1, Math.ceil((resetMs - at) / 1000)),
+        limited,
+        degraded: rate.degraded,
+        contended: rate.contended
+    };
+}
+/**
+ * Counts one recovery ATTEMPT against the per-recipient and per-IP caps.
+ *
+ * Call before deciding whether the address is a member — see the module note
+ * on why the ordering is the control and not an implementation detail.
+ *
+ * The recipient cap is checked first and short-circuits, matching
+ * `consumePasswordResetSend`: one address being hammered must not also spend
+ * the IP budget that a person sharing that NAT is relying on.
+ *
+ * The email is passed through to the key in the clear on purpose —
+ * `consumeRateLimit` hashes every key into the document id precisely so that
+ * caller-held identifiers do not sit in plaintext ids or index exports.
+ */ export async function consumeMembershipRecoverAttempt(options) {
+    const { email, ip, now, firestore } = options;
+    const shared = _extends({
+        windowMs: RECOVER_ATTEMPT_WINDOW_MS
+    }, now === undefined ? {} : {
+        now
+    }, firestore === undefined ? {} : {
+        firestore
+    });
+    const at = now != null ? now : Date.now();
+    const recipient = await consumeRateLimit(`recover:to:${email}`, _extends({}, shared, {
+        limit: RECOVER_SENDS_PER_RECIPIENT
+    }));
+    if (!recipient.allowed) {
+        return refusal('recipient', recipient.resetMs, at, recipient);
+    }
+    const source = ip ? await consumeRateLimit(`recover:ip:${ip}`, _extends({}, shared, {
+        limit: RECOVER_ATTEMPTS_PER_IP
+    })) : null;
+    if (source && !source.allowed) {
+        return refusal('ip', source.resetMs, at, source);
+    }
+    return {
+        allowed: true,
+        retryAfterSeconds: 0,
+        limited: null,
+        degraded: recipient.degraded || Boolean(source == null ? void 0 : source.degraded),
+        contended: false
+    };
+}
+/**
+ * Counts one recovery mail against the per-site daily ceiling.
+ *
+ * Call immediately before sending, and treat a refusal as the silent-success
+ * exit — never as a visible error. A visible one would fire only for addresses
+ * that really are members, which is the oracle the endpoint exists to avoid.
+ */ export async function consumeMembershipRecoverSend(options) {
+    const { hostId, now, firestore } = options;
+    const at = now != null ? now : Date.now();
+    const rate = await consumeRateLimit(`recover:host:${hostId}`, _extends({
+        limit: RECOVER_SENDS_PER_HOST_PER_DAY,
+        windowMs: RECOVER_SEND_WINDOW_MS
+    }, now === undefined ? {} : {
+        now
+    }, firestore === undefined ? {} : {
+        firestore
+    }));
+    if (!rate.allowed) return refusal('host', rate.resetMs, at, rate);
+    return {
+        allowed: true,
+        retryAfterSeconds: 0,
+        limited: null,
+        degraded: rate.degraded,
+        contended: false
+    };
+}
+export default consumeMembershipRecoverAttempt;
+
+//# sourceMappingURL=membership-recover-throttle.js.map

package/src/lib/server/membership-recover-throttle.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/membership-recover-throttle.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 { consumeRateLimit } from './rate-limit-store'\n\n/**\n * Throttle for the UNAUTHENTICATED site-member password-recovery endpoint\n * (AGL-1966).\n *\n * ## The shape being closed\n *\n * Two unauthenticated tenant plugin endpoints compose into a mail relay on\n * `aglyn.com`'s sending domain: `membership/register` puts an arbitrary\n * address into `hosts/{hostId}/siteMembers` (member accounts are unlimited on\n * every plan, AGL-889, so nothing there refuses), and `membership/recover`\n * mails a reset link to any address that has such a row. Register N addresses,\n * call recover N times, and every one is a real message we sent, carrying an\n * attacker-chosen site name in the subject.\n *\n * The only thing in the way was the dispatcher's `visitorWriteRateLimitRefusal`\n * — 120 writes/60s per (site, IP), a bucket register and recover SHARE. That\n * ceiling is sized for a shopper editing cart quantities; measured as mail it\n * is ~86k messages a day from one address.\n *\n * The damage is not the Resend bill. It is the sending reputation of\n * `aglyn.com`, which is shared by every customer's transactional mail, and\n * which cannot be bought back after the fact.\n *\n * ## Why this is a separate module from `password-reset-throttle.ts`\n *\n * That one guards ADMIN-initiated resets, and says so at length: every caller\n * is already authenticated as staff, an org admin or a site admin, \"so this is\n * **not** the enumeration defense that guards the public `membership/recover`\n * endpoint — nobody reaches here without already knowing the account exists.\"\n * This is that defense. The caps differ (there is no actor to key on here, and\n * an IP is not an actor), and the refusal contract differs — see below, it is\n * the part that is easy to get wrong.\n *\n * It lives at this layer, beside its sibling, for the reason that one gives:\n * the commerce plugin cannot import the console's API helpers, and a number\n * duplicated in two places drifts.\n *\n * ## Two kinds of cap, because they have two different refusals\n *\n * This is the load-bearing distinction in the module, and it exists entirely\n * to keep the endpoint from becoming an existence oracle.\n *\n * **Attempt caps** ({@link consumeMembershipRecoverAttempt}) — per recipient\n * and per IP. Consumed BEFORE the member lookup, so a request for an address\n * that is a member and a request for one that is not spend exactly the same\n * budget and get exactly the same answer. Their refusal may therefore be a\n * visible `429`: it says nothing about whether the address exists, because the\n * counter that produced it counts both alike. Consuming these *after* the\n * lookup, or only on the send path, would be the bug — the 429 would then\n * appear only for real members and the endpoint's whole silent-success\n * contract would be undone by its own rate limiter.\n *\n * **The send cap** ({@link consumeMembershipRecoverSend}) — per host, per day.\n * Consumed only when a message is actually about to go out, because it is a\n * ceiling on OUTBOUND MAIL rather than on requests. That means it is only ever\n * reached on the member-exists branch, so its refusal must NOT be visible: the\n * caller takes the same silent `200 {ok:true}` exit as an unknown address. The\n * cost of that is a real member who gets no mail and no error during an\n * attack on their site — collateral that is accepted deliberately, and sized\n * for below.\n *\n * ## Backed by the durable limiter, not a `Map`\n *\n * `membership-recover.ts` previously carried a per-instance `Map` keyed on\n * IP+email. On Vercel that is close to no limit at all — it resets on every\n * cold start and each concurrent instance keeps its own, so the effective cap\n * is `limit × instances` and an attacker widens it by going wider (AGL-794).\n * A mail send is exactly the \"consequence, not volume\" case that\n * `RATE_LIMITING.md` says to spend a Firestore transaction on.\n *\n * ### Contention fails CLOSED here, and that is correct (AGL-2404)\n *\n * `consumeRateLimit` refuses with `contended: true` when one key is hot, and\n * only degrades when the store itself is unreachable. Both postures land well\n * on this surface. The attempt keys are per recipient and per IP, so a\n * legitimate visitor essentially never races themselves — concurrency on one\n * of these keys is the attack. And the send key is per host per day, which is\n * one document: a busy site's genuine recover traffic is a handful of requests\n * an hour, so contention there is likewise a flood rather than a Tuesday.\n */\n\n/**\n * Reset mails per recipient address, per hour, across every site.\n *\n * Matches `RESET_SENDS_PER_RECIPIENT` deliberately: a reset link is valid for\n * an hour anyway, so a second and third are only useful if the first was lost,\n * and one number for \"how many resets may one mailbox receive in an hour\" is\n * easier to defend than two.\n *\n * NOT keyed by host. A per-(host, address) cap would let an attacker who\n * controls several sites — which a free org can create — multiply one\n * mailbox's mail by the number of sites, and the person being carpet-bombed\n * does not care which of our customers' sites the mail claims to come from.\n */\nexport const RECOVER_SENDS_PER_RECIPIENT = 3\n\n/**\n * Recovery attempts per client IP, per hour, across every site and address.\n *\n * Sized against the human behaviour, not the attack: a person who has\n * forgotten a password tries it on one or two sites, mistypes the address\n * once, and stops. Ten is already several times that. A household or office\n * NAT sharing one address would need ten genuine forgotten passwords in one\n * hour to notice this.\n *\n * This is the cap that actually prices enumeration. The per-recipient cap\n * alone does nothing against the register-then-recover composition, because\n * every address in that attack is fresh and none of them has a count.\n */\nexport const RECOVER_ATTEMPTS_PER_IP = 10\n\n/** Both attempt caps use a one-hour fixed window, like their sibling. */\nexport const RECOVER_ATTEMPT_WINDOW_MS = 60 * 60 * 1000\n\n/**\n * Recovery mails one SITE may emit per day.\n *\n * An abuse ceiling, not a usage limit, and it is set where it is because of\n * the collateral described above: it must sit far enough above any real site's\n * genuine volume that reaching it is evidence of an attack. A storefront with\n * ten thousand members sees single-digit resets a day; two hundred is more\n * than an order of magnitude of headroom.\n *\n * What it buys, given the dispatcher's 120/min already upstream: it converts\n * \"~86k messages a day per site from one IP\" into 200, and — because it is\n * keyed on the site rather than on the caller — it holds no matter how many\n * IPs the caller brings. That is the property the compound visitor-write key\n * explicitly cannot have, and the reason this cap is per host alone.\n */\nexport const RECOVER_SENDS_PER_HOST_PER_DAY = 200\n\n/** Fixed 24h window for the send cap. */\nexport const RECOVER_SEND_WINDOW_MS = 24 * 60 * 60 * 1000\n\n/**\n * How new a member row may be and still be worth a reset mail.\n *\n * The register-then-recover composition is the whole attack, and no real\n * person needs a password reset in the first ten minutes of having chosen the\n * password. This is the cheapest control on the list and the only one that\n * refuses the composition itself rather than rationing it.\n *\n * Enforced by the handler (it needs the member document); the constant lives\n * here so the policy is in one place.\n */\nexport const RECOVER_MIN_MEMBER_AGE_MS = 10 * 60 * 1000\n\nexport interface MembershipRecoverThrottleResult {\n  allowed: boolean\n  /** Seconds until the exhausted window rolls over; 0 when allowed. */\n  retryAfterSeconds: number\n  /** Which cap refused, for logs. Never told to the caller. */\n  limited: 'recipient' | 'ip' | 'host' | null\n  /** True when the durable store was unreachable and only a local cap applied. */\n  degraded: boolean\n  /** True when the key was contended and the request was refused on that basis. */\n  contended: boolean\n}\n\nexport interface MembershipRecoverAttemptOptions {\n  /** The address the recovery was requested for, normalized by the caller. */\n  email: string\n  /**\n   * The caller's address from `readClientIp`, or `null` when nothing readable\n   * named one — in which case the per-source cap is SKIPPED rather than shared.\n   * One `recover:ip:unknown` budget would spend every site's recovery\n   * allowance on behalf of whoever tried first; the per-recipient cap above is\n   * the half that stops mailbombing one person and needs no address.\n   */\n  ip: string | null\n  now?: number\n  /** Injectable for tests; defaults to the Admin SDK's Firestore. */\n  firestore?: unknown\n}\n\nfunction refusal(\n  limited: 'recipient' | 'ip' | 'host',\n  resetMs: number,\n  at: number,\n  rate: { degraded: boolean; contended: boolean },\n): MembershipRecoverThrottleResult {\n  return {\n    allowed: false,\n    retryAfterSeconds: Math.max(1, Math.ceil((resetMs - at) / 1000)),\n    limited,\n    degraded: rate.degraded,\n    contended: rate.contended,\n  }\n}\n\n/**\n * Counts one recovery ATTEMPT against the per-recipient and per-IP caps.\n *\n * Call before deciding whether the address is a member — see the module note\n * on why the ordering is the control and not an implementation detail.\n *\n * The recipient cap is checked first and short-circuits, matching\n * `consumePasswordResetSend`: one address being hammered must not also spend\n * the IP budget that a person sharing that NAT is relying on.\n *\n * The email is passed through to the key in the clear on purpose —\n * `consumeRateLimit` hashes every key into the document id precisely so that\n * caller-held identifiers do not sit in plaintext ids or index exports.\n */\nexport async function consumeMembershipRecoverAttempt(\n  options: MembershipRecoverAttemptOptions,\n): Promise<MembershipRecoverThrottleResult> {\n  const { email, ip, now, firestore } = options\n  const shared = {\n    windowMs: RECOVER_ATTEMPT_WINDOW_MS,\n    ...(now === undefined ? {} : { now }),\n    ...(firestore === undefined ? {} : { firestore }),\n  }\n  const at = now ?? Date.now()\n\n  const recipient = await consumeRateLimit(`recover:to:${email}`, {\n    ...shared,\n    limit: RECOVER_SENDS_PER_RECIPIENT,\n  })\n  if (!recipient.allowed) {\n    return refusal('recipient', recipient.resetMs, at, recipient)\n  }\n\n  const source = ip\n    ? await consumeRateLimit(`recover:ip:${ip}`, {\n        ...shared,\n        limit: RECOVER_ATTEMPTS_PER_IP,\n      })\n    : null\n  if (source && !source.allowed) {\n    return refusal('ip', source.resetMs, at, source)\n  }\n\n  return {\n    allowed: true,\n    retryAfterSeconds: 0,\n    limited: null,\n    degraded: recipient.degraded || Boolean(source?.degraded),\n    contended: false,\n  }\n}\n\nexport interface MembershipRecoverSendOptions {\n  hostId: string\n  now?: number\n  firestore?: unknown\n}\n\n/**\n * Counts one recovery mail against the per-site daily ceiling.\n *\n * Call immediately before sending, and treat a refusal as the silent-success\n * exit — never as a visible error. A visible one would fire only for addresses\n * that really are members, which is the oracle the endpoint exists to avoid.\n */\nexport async function consumeMembershipRecoverSend(\n  options: MembershipRecoverSendOptions,\n): Promise<MembershipRecoverThrottleResult> {\n  const { hostId, now, firestore } = options\n  const at = now ?? Date.now()\n  const rate = await consumeRateLimit(`recover:host:${hostId}`, {\n    limit: RECOVER_SENDS_PER_HOST_PER_DAY,\n    windowMs: RECOVER_SEND_WINDOW_MS,\n    ...(now === undefined ? {} : { now }),\n    ...(firestore === undefined ? {} : { firestore }),\n  })\n  if (!rate.allowed) return refusal('host', rate.resetMs, at, rate)\n  return {\n    allowed: true,\n    retryAfterSeconds: 0,\n    limited: null,\n    degraded: rate.degraded,\n    contended: false,\n  }\n}\n\nexport default consumeMembershipRecoverAttempt\n"],"names":["consumeRateLimit","RECOVER_SENDS_PER_RECIPIENT","RECOVER_ATTEMPTS_PER_IP","RECOVER_ATTEMPT_WINDOW_MS","RECOVER_SENDS_PER_HOST_PER_DAY","RECOVER_SEND_WINDOW_MS","RECOVER_MIN_MEMBER_AGE_MS","refusal","limited","resetMs","at","rate","allowed","retryAfterSeconds","Math","max","ceil","degraded","contended","consumeMembershipRecoverAttempt","options","email","ip","now","firestore","shared","windowMs","undefined","Date","recipient","limit","source","Boolean","consumeMembershipRecoverSend","hostId"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,gBAAgB,QAAQ,wBAAoB;AAErD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+EC,GAED;;;;;;;;;;;;CAYC,GACD,OAAO,MAAMC,8BAA8B,EAAC;AAE5C;;;;;;;;;;;;CAYC,GACD,OAAO,MAAMC,0BAA0B,GAAE;AAEzC,uEAAuE,GACvE,OAAO,MAAMC,4BAA4B,KAAK,KAAK,KAAI;AAEvD;;;;;;;;;;;;;;CAcC,GACD,OAAO,MAAMC,iCAAiC,IAAG;AAEjD,uCAAuC,GACvC,OAAO,MAAMC,yBAAyB,KAAK,KAAK,KAAK,KAAI;AAEzD;;;;;;;;;;CAUC,GACD,OAAO,MAAMC,4BAA4B,KAAK,KAAK,KAAI;AA8BvD,SAASC,QACPC,OAAoC,EACpCC,OAAe,EACfC,EAAU,EACVC,IAA+C;IAE/C,OAAO;QACLC,SAAS;QACTC,mBAAmBC,KAAKC,GAAG,CAAC,GAAGD,KAAKE,IAAI,CAAC,AAACP,CAAAA,UAAUC,EAAC,IAAK;QAC1DF;QACAS,UAAUN,KAAKM,QAAQ;QACvBC,WAAWP,KAAKO,SAAS;IAC3B;AACF;AAEA;;;;;;;;;;;;;CAaC,GACD,OAAO,eAAeC,gCACpBC,OAAwC;IAExC,MAAM,EAAEC,KAAK,EAAEC,EAAE,EAAEC,GAAG,EAAEC,SAAS,EAAE,GAAGJ;IACtC,MAAMK,SAAS;QACbC,UAAUvB;OACNoB,QAAQI,YAAY,CAAC,IAAI;QAAEJ;IAAI,GAC/BC,cAAcG,YAAY,CAAC,IAAI;QAAEH;IAAU;IAEjD,MAAMd,KAAKa,cAAAA,MAAOK,KAAKL,GAAG;IAE1B,MAAMM,YAAY,MAAM7B,iBAAiB,CAAC,WAAW,EAAEqB,OAAO,EAAE,aAC3DI;QACHK,OAAO7B;;IAET,IAAI,CAAC4B,UAAUjB,OAAO,EAAE;QACtB,OAAOL,QAAQ,aAAasB,UAAUpB,OAAO,EAAEC,IAAImB;IACrD;IAEA,MAAME,SAAST,KACX,MAAMtB,iBAAiB,CAAC,WAAW,EAAEsB,IAAI,EAAE,aACtCG;QACHK,OAAO5B;UAET;IACJ,IAAI6B,UAAU,CAACA,OAAOnB,OAAO,EAAE;QAC7B,OAAOL,QAAQ,MAAMwB,OAAOtB,OAAO,EAAEC,IAAIqB;IAC3C;IAEA,OAAO;QACLnB,SAAS;QACTC,mBAAmB;QACnBL,SAAS;QACTS,UAAUY,UAAUZ,QAAQ,IAAIe,QAAQD,0BAAAA,OAAQd,QAAQ;QACxDC,WAAW;IACb;AACF;AAQA;;;;;;CAMC,GACD,OAAO,eAAee,6BACpBb,OAAqC;IAErC,MAAM,EAAEc,MAAM,EAAEX,GAAG,EAAEC,SAAS,EAAE,GAAGJ;IACnC,MAAMV,KAAKa,cAAAA,MAAOK,KAAKL,GAAG;IAC1B,MAAMZ,OAAO,MAAMX,iBAAiB,CAAC,aAAa,EAAEkC,QAAQ,EAAE;QAC5DJ,OAAO1B;QACPsB,UAAUrB;OACNkB,QAAQI,YAAY,CAAC,IAAI;QAAEJ;IAAI,GAC/BC,cAAcG,YAAY,CAAC,IAAI;QAAEH;IAAU;IAEjD,IAAI,CAACb,KAAKC,OAAO,EAAE,OAAOL,QAAQ,QAAQI,KAAKF,OAAO,EAAEC,IAAIC;IAC5D,OAAO;QACLC,SAAS;QACTC,mBAAmB;QACnBL,SAAS;QACTS,UAAUN,KAAKM,QAAQ;QACvBC,WAAW;IACb;AACF;AAEA,eAAeC,gCAA+B"}

package/src/lib/server/notifications.d.ts

@@ -0,0 +1,55 @@
+/**
+ * @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 AglynNotification } from '@aglyn/aglyn/server';
+export type NotificationPayload = Omit<AglynNotification, '$id' | 'createdAt' | 'readAt'>;
+/**
+ * Notification fan-out (AGL-259): batch-writes one doc per recipient at
+ * `users/{uid}/notifications`. Never throws — a notification miss must
+ * not break the mutation that emitted it.
+ */
+export declare function notifyUsers(uids: Iterable<string>, payload: NotificationPayload): Promise<void>;
+/**
+ * Notifies every staff-claim holder (AGL-850) — the support-desk audience.
+ * Staff are not org members, so `notifyOrgAdmins`/`notifyHostManagers` never
+ * reach them; this enumerates the `staff` custom claim instead. The docs land
+ * at `users/{uid}/notifications`, which the console notifications menu already
+ * renders, so no separate staff inbox is needed. Never throws.
+ */
+export declare function notifyStaff(payload: NotificationPayload): Promise<void>;
+/** Notifies the org's owner + admins (billing, membership, org events). */
+export declare function notifyOrgAdmins(orgId: string, payload: NotificationPayload): Promise<void>;
+/**
+ * Notifies everyone who manages a host (admin/editor in the host doc's
+ * `memberRoles` projection) — the audience for form submissions and
+ * bookings on that site.
+ *
+ * The OWNING ORG travels with the notification (AGL-1773). Host links are
+ * stored in the legacy `/{hostDocId}/rest` shape and rewritten to
+ * `/{orgSlug}/hosts/{subdomain}/rest` when they are FOLLOWED
+ * (`normalizeNotificationLink`, AGL-644) — a rewrite that needs an org slug.
+ * With no `orgId` on the doc the console had nothing to key on and fell back
+ * to whichever org the reader happens to have OPEN, so a manager who belongs
+ * to more than one workspace was routed to `/{other-org}/hosts/{subdomain}/…`
+ * and got a designed 404: `HostGuard` only resolves subdomains belonging to
+ * the current org. `notifyOrgAdmins` has always stamped it; the host fan-out
+ * — every form submission, booking, order and stock alert — never did.
+ *
+ * The host doc already carries `orgId` (AGL-233), so this costs no extra
+ * read. Spread conditionally: the field is optional on the host model and
+ * Firestore rejects `undefined`.
+ */
+export declare function notifyHostManagers(hostId: string, payload: NotificationPayload): Promise<void>;

package/src/lib/server/notifications.js

@@ -0,0 +1,134 @@
+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.
+ */ import { notificationMuted } from "@aglyn/aglyn/server";
+import { FieldValue } from "firebase-admin/firestore";
+import { listStaffUidsAcrossPools } from "./auth-pools.js";
+import firebaseAdmin from "./firebase-admin.js";
+import { listOrgMembers } from "./organizations.js";
+const firestore = ()=>firebaseAdmin.app().firestore();
+/**
+ * Notification fan-out (AGL-259): batch-writes one doc per recipient at
+ * `users/{uid}/notifications`. Never throws — a notification miss must
+ * not break the mutation that emitted it.
+ */ export async function notifyUsers(uids, payload) {
+    try {
+        const db = firestore();
+        const targets = [
+            ...new Set(uids)
+        ].filter(Boolean).slice(0, 400);
+        if (!targets.length) return;
+        // Per-user category mutes (AGL-267): one getAll over the user docs.
+        const userDocs = await db.getAll(...targets.map((uid)=>db.collection('users').doc(uid)));
+        const batch = db.batch();
+        let count = 0;
+        for (const userDoc of userDocs){
+            const prefs = userDoc.get('notificationPrefs');
+            if (notificationMuted(prefs, payload.type)) continue;
+            batch.set(db.collection('users').doc(userDoc.id).collection('notifications').doc(), _extends({}, payload, {
+                createdAt: FieldValue.serverTimestamp()
+            }));
+            count += 1;
+        }
+        if (count > 0) await batch.commit();
+    } catch (error) {
+        console.error('notification fan-out failed', error);
+    }
+}
+// Staff are identified by a Firebase Auth custom claim (`staff`), which is not
+// a Firestore query — so the roster comes from paginating the auth users. A
+// burst of ticket activity shouldn't rescan every time, so the (small) result
+// is cached briefly. Fails soft to an empty list.
+let staffUidCache = null;
+const STAFF_CACHE_MS = 60000;
+async function listStaffUids() {
+    const now = Date.now();
+    if (staffUidCache && now - staffUidCache.at < STAFF_CACHE_MS) {
+        return staffUidCache.uids;
+    }
+    // Across ALL auth pools (AGL-1122). This scanned only the project pool, so
+    // a staff member who signs in through enterprise SSO — whose account lives
+    // in a GCIP tenant pool — was never in the fan-out. Nothing errored; the
+    // notification simply never arrived, which is the worst shape a miss can
+    // take on an alerting path.
+    const uids = await listStaffUidsAcrossPools();
+    staffUidCache = {
+        uids,
+        at: now
+    };
+    return uids;
+}
+/**
+ * Notifies every staff-claim holder (AGL-850) — the support-desk audience.
+ * Staff are not org members, so `notifyOrgAdmins`/`notifyHostManagers` never
+ * reach them; this enumerates the `staff` custom claim instead. The docs land
+ * at `users/{uid}/notifications`, which the console notifications menu already
+ * renders, so no separate staff inbox is needed. Never throws.
+ */ export async function notifyStaff(payload) {
+    try {
+        await notifyUsers(await listStaffUids(), payload);
+    } catch (error) {
+        console.error('staff notification failed', error);
+    }
+}
+/** Notifies the org's owner + admins (billing, membership, org events). */ export async function notifyOrgAdmins(orgId, payload) {
+    try {
+        const members = await listOrgMembers(orgId);
+        const admins = members.filter((member)=>member.role === 'owner' || member.role === 'admin').map((member)=>member.$id);
+        await notifyUsers(admins, _extends({}, payload, {
+            orgId
+        }));
+    } catch (error) {
+        console.error('org admin notification failed', error);
+    }
+}
+/**
+ * Notifies everyone who manages a host (admin/editor in the host doc's
+ * `memberRoles` projection) — the audience for form submissions and
+ * bookings on that site.
+ *
+ * The OWNING ORG travels with the notification (AGL-1773). Host links are
+ * stored in the legacy `/{hostDocId}/rest` shape and rewritten to
+ * `/{orgSlug}/hosts/{subdomain}/rest` when they are FOLLOWED
+ * (`normalizeNotificationLink`, AGL-644) — a rewrite that needs an org slug.
+ * With no `orgId` on the doc the console had nothing to key on and fell back
+ * to whichever org the reader happens to have OPEN, so a manager who belongs
+ * to more than one workspace was routed to `/{other-org}/hosts/{subdomain}/…`
+ * and got a designed 404: `HostGuard` only resolves subdomains belonging to
+ * the current org. `notifyOrgAdmins` has always stamped it; the host fan-out
+ * — every form submission, booking, order and stock alert — never did.
+ *
+ * The host doc already carries `orgId` (AGL-233), so this costs no extra
+ * read. Spread conditionally: the field is optional on the host model and
+ * Firestore rejects `undefined`.
+ */ export async function notifyHostManagers(hostId, payload) {
+    try {
+        var _host_get, _payload_orgId;
+        const host = await firestore().collection('hosts').doc(hostId).get();
+        const memberRoles = (_host_get = host.get('memberRoles')) != null ? _host_get : {};
+        const managers = Object.entries(memberRoles).filter(([, role])=>role === 'admin' || role === 'editor').map(([uid])=>uid);
+        const orgId = (_payload_orgId = payload.orgId) != null ? _payload_orgId : host.get('orgId');
+        await notifyUsers(managers, _extends({}, payload, {
+            hostId
+        }, orgId ? {
+            orgId
+        } : {}));
+    } catch (error) {
+        console.error('host manager notification failed', error);
+    }
+}
+
+//# sourceMappingURL=notifications.js.map

package/src/lib/server/notifications.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/notifications.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 { notificationMuted, type AglynNotification } from '@aglyn/aglyn/server'\nimport { FieldValue } from 'firebase-admin/firestore'\nimport { listStaffUidsAcrossPools } from './auth-pools'\nimport firebaseAdmin from './firebase-admin'\nimport { listOrgMembers } from './organizations'\n\nconst firestore = () => firebaseAdmin.app().firestore()\n\nexport type NotificationPayload = Omit<\n  AglynNotification,\n  '$id' | 'createdAt' | 'readAt'\n>\n\n/**\n * Notification fan-out (AGL-259): batch-writes one doc per recipient at\n * `users/{uid}/notifications`. Never throws — a notification miss must\n * not break the mutation that emitted it.\n */\nexport async function notifyUsers(\n  uids: Iterable<string>,\n  payload: NotificationPayload,\n): Promise<void> {\n  try {\n    const db = firestore()\n    const targets = [...new Set(uids)].filter(Boolean).slice(0, 400)\n    if (!targets.length) return\n    // Per-user category mutes (AGL-267): one getAll over the user docs.\n    const userDocs = await db.getAll(\n      ...targets.map((uid) => db.collection('users').doc(uid)),\n    )\n    const batch = db.batch()\n    let count = 0\n    for (const userDoc of userDocs) {\n      const prefs = userDoc.get('notificationPrefs') as\n        | Record<string, boolean>\n        | undefined\n      if (notificationMuted(prefs, payload.type)) continue\n      batch.set(\n        db\n          .collection('users')\n          .doc(userDoc.id)\n          .collection('notifications')\n          .doc(),\n        { ...payload, createdAt: FieldValue.serverTimestamp() },\n      )\n      count += 1\n    }\n    if (count > 0) await batch.commit()\n  } catch (error) {\n    console.error('notification fan-out failed', error)\n  }\n}\n\n// Staff are identified by a Firebase Auth custom claim (`staff`), which is not\n// a Firestore query — so the roster comes from paginating the auth users. A\n// burst of ticket activity shouldn't rescan every time, so the (small) result\n// is cached briefly. Fails soft to an empty list.\nlet staffUidCache: { uids: string[]; at: number } | null = null\nconst STAFF_CACHE_MS = 60_000\n\nasync function listStaffUids(): Promise<string[]> {\n  const now = Date.now()\n  if (staffUidCache && now - staffUidCache.at < STAFF_CACHE_MS) {\n    return staffUidCache.uids\n  }\n  // Across ALL auth pools (AGL-1122). This scanned only the project pool, so\n  // a staff member who signs in through enterprise SSO — whose account lives\n  // in a GCIP tenant pool — was never in the fan-out. Nothing errored; the\n  // notification simply never arrived, which is the worst shape a miss can\n  // take on an alerting path.\n  const uids = await listStaffUidsAcrossPools()\n  staffUidCache = { uids, at: now }\n  return uids\n}\n\n/**\n * Notifies every staff-claim holder (AGL-850) — the support-desk audience.\n * Staff are not org members, so `notifyOrgAdmins`/`notifyHostManagers` never\n * reach them; this enumerates the `staff` custom claim instead. The docs land\n * at `users/{uid}/notifications`, which the console notifications menu already\n * renders, so no separate staff inbox is needed. Never throws.\n */\nexport async function notifyStaff(payload: NotificationPayload): Promise<void> {\n  try {\n    await notifyUsers(await listStaffUids(), payload)\n  } catch (error) {\n    console.error('staff notification failed', error)\n  }\n}\n\n/** Notifies the org's owner + admins (billing, membership, org events). */\nexport async function notifyOrgAdmins(\n  orgId: string,\n  payload: NotificationPayload,\n): Promise<void> {\n  try {\n    const members = await listOrgMembers(orgId)\n    const admins = members\n      .filter((member) => member.role === 'owner' || member.role === 'admin')\n      .map((member) => member.$id)\n    await notifyUsers(admins, { ...payload, orgId })\n  } catch (error) {\n    console.error('org admin notification failed', error)\n  }\n}\n\n/**\n * Notifies everyone who manages a host (admin/editor in the host doc's\n * `memberRoles` projection) — the audience for form submissions and\n * bookings on that site.\n *\n * The OWNING ORG travels with the notification (AGL-1773). Host links are\n * stored in the legacy `/{hostDocId}/rest` shape and rewritten to\n * `/{orgSlug}/hosts/{subdomain}/rest` when they are FOLLOWED\n * (`normalizeNotificationLink`, AGL-644) — a rewrite that needs an org slug.\n * With no `orgId` on the doc the console had nothing to key on and fell back\n * to whichever org the reader happens to have OPEN, so a manager who belongs\n * to more than one workspace was routed to `/{other-org}/hosts/{subdomain}/…`\n * and got a designed 404: `HostGuard` only resolves subdomains belonging to\n * the current org. `notifyOrgAdmins` has always stamped it; the host fan-out\n * — every form submission, booking, order and stock alert — never did.\n *\n * The host doc already carries `orgId` (AGL-233), so this costs no extra\n * read. Spread conditionally: the field is optional on the host model and\n * Firestore rejects `undefined`.\n */\nexport async function notifyHostManagers(\n  hostId: string,\n  payload: NotificationPayload,\n): Promise<void> {\n  try {\n    const host = await firestore().collection('hosts').doc(hostId).get()\n    const memberRoles =\n      (host.get('memberRoles') as Record<string, string> | undefined) ?? {}\n    const managers = Object.entries(memberRoles)\n      .filter(([, role]) => role === 'admin' || role === 'editor')\n      .map(([uid]) => uid)\n    const orgId = payload.orgId ?? (host.get('orgId') as string | undefined)\n    await notifyUsers(managers, {\n      ...payload,\n      hostId,\n      ...(orgId ? { orgId } : {}),\n    })\n  } catch (error) {\n    console.error('host manager notification failed', error)\n  }\n}\n"],"names":["notificationMuted","FieldValue","listStaffUidsAcrossPools","firebaseAdmin","listOrgMembers","firestore","app","notifyUsers","uids","payload","db","targets","Set","filter","Boolean","slice","length","userDocs","getAll","map","uid","collection","doc","batch","count","userDoc","prefs","get","type","set","id","createdAt","serverTimestamp","commit","error","console","staffUidCache","STAFF_CACHE_MS","listStaffUids","now","Date","at","notifyStaff","notifyOrgAdmins","orgId","members","admins","member","role","$id","notifyHostManagers","hostId","host","memberRoles","managers","Object","entries"],"mappings":"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"}

package/src/lib/server/org-billing.d.ts

@@ -0,0 +1,97 @@
+/**
+ * @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 { hasInlineOrgBilling, type OrgBillingDoc, type OrgInlineBilling } from '@aglyn/aglyn/server';
+/** `orgs/{orgId}/billing/stripe`. */
+export declare function orgBillingRef(orgId: string): FirebaseFirestore.DocumentReference<FirebaseFirestore.DocumentData, FirebaseFirestore.DocumentData>;
+/**
+ * Reads an org's commercial keys, falling back to the org doc.
+ *
+ * The fallback is what makes the migration safe to land in pieces: a reader
+ * repointed here keeps working against an org that has not been backfilled
+ * yet, and keeps working if the backfill missed one. It stops being reachable
+ * only when the inline fields are finally deleted from the org doc — which is
+ * the LAST step, taken once production has been observed reading from the new
+ * location.
+ *
+ * Without it, the failure mode is silent and expensive: a missing billing doc
+ * reads as `undefined`, which every caller downstream interprets as "no
+ * subscription", i.e. a paying workspace rendered as Free.
+ */
+export declare function readOrgBilling(orgId: string): Promise<OrgBillingDoc>;
+/**
+ * Which Stripe MODES this org has a stored customer for (AGL-2486, follow-up).
+ *
+ * `readOrgBilling` answering `stripeCustomerId: null` has two completely
+ * different meanings — "this workspace has never been billed" and "this
+ * workspace's customer lives in the other Stripe world and THIS deployment
+ * cannot see it" — and every surface downstream rendered them as the same
+ * sentence, "No invoices yet." That is the swallowed-query-as-measured-zero
+ * shape: nothing looks wrong, and the wrong reading is the reassuring one.
+ *
+ * The fix is NOT to fall back to the other mode's id — that fallback is the
+ * original bug, and it stays deleted. It is to let a caller say which of the
+ * two silences it is looking at.
+ *
+ * Returns BOOLEANS, never ids. A test-mode surface asking this question must
+ * not come away holding a live `cus_…`: it would have no legitimate use for
+ * one, and putting it in a JSON response would publish a live customer id to
+ * every browser on a test deployment.
+ */
+export declare function readOrgBillingCustomerModes(orgId: string): Promise<{
+    live: boolean;
+    test: boolean;
+}>;
+/**
+ * Writes the commercial keys to the billing doc, and onto the org doc the
+ * entitlement inputs that stay there.
+ *
+ * Three writes, one batch:
+ *
+ * 1. the billing doc itself, `merge: true` to match what the org-doc write did;
+ * 2. the org doc, merged, with what entitlement resolution reads there:
+ *    `billingStatus`, so the AGL-275 dunning banner keeps working for
+ *    non-managers who can no longer read `subscription`; and `seatAddons`,
+ *    which never moved (`ORG_BILLING_MOVED_KEYS`), whenever the patch carries
+ *    the add-on quantities;
+ * 3. the `stripeCustomers` reverse index, so the webhook can still resolve an
+ *    org from a Stripe customer id without a query.
+ *
+ * `writeInline` mirrored the keys back onto the org doc as well. It was on
+ * during the migration so a rollback lost nothing, and is now OFF: writing them
+ * inline is what the whole issue exists to stop, and leaving it on would let the
+ * next Stripe webhook silently re-add the fields minutes after they were
+ * deleted, re-opening the exposure with nothing to show for it.
+ *
+ * The option survives for a deliberate one-off rollback, and nothing passes it.
+ *
+ * The READ fallback in `readOrgBilling` deliberately stays. It costs one get on
+ * a doc that no longer exists, and it is the only thing standing between an org
+ * the backfill somehow missed and a paying workspace rendering as Free.
+ */
+export declare function writeOrgBilling(orgId: string, patch: Partial<OrgBillingDoc> & Pick<OrgInlineBilling, 'seatAddons'>, options?: {
+    writeInline?: boolean;
+}): Promise<void>;
+/**
+ * Resolves an org id from a Stripe customer id.
+ *
+ * Prefers the reverse index; falls back to the legacy `where('stripeCustomerId')`
+ * query on `orgs` for customers whose index entry has not been written yet.
+ * The fallback disappears with the inline fields.
+ */
+export declare function findOrgIdByStripeCustomer(customerId: string): Promise<string | null>;
+/** Re-exported so callers do not need a second import to test migration state. */
+export { hasInlineOrgBilling };