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

package/src/lib/server/verify-email-cooldown.js

@@ -0,0 +1,114 @@
+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";
+/**
+ * The cooldown on the AUTOMATIC verification send (AGL-2584).
+ *
+ * `/verify-email` asks for a link every time it mounts, so somebody who leaves
+ * the tab and comes back to see whether the mail arrived asks for a second
+ * one. Identity Platform throttles link minting per account, ahead of and
+ * independently of the route's own 5/hour budget, and that collision is what a
+ * returning visitor met: a mail that had genuinely been sent, reported to them
+ * as a send failure.
+ *
+ * Reopening the page is a request to know whether the first mail worked, not a
+ * request for another one — so an automatic send is skipped while a link
+ * minted for this uid is still young. The explicit "Resend verification email"
+ * button does not come through here: someone who says the mail never arrived
+ * is asking deliberately, and that affordance keeps the full per-uid budget.
+ *
+ * ## Why the state is server-side and not a `sentAt` in the browser
+ *
+ * The throttle this avoids is per ACCOUNT, so the memory of "a link was minted
+ * recently" has to be too. A marker held in the browser cannot see a link
+ * minted from a phone, a second browser, or a private window, and clearing
+ * site data erases it — each of which puts the collision straight back. It
+ * would also put the decision on the side of the wire that does not do the
+ * minting, which is where it went wrong the first time.
+ *
+ * ## Why the durable limiter, with a budget of one
+ *
+ * A cooldown *is* a limit of one per window, and the limiter already solves
+ * the parts that are easy to get wrong: it is global rather than per instance
+ * (a per-instance `Map` on Vercel is close to no limit at all, AGL-794), it
+ * hashes the key out of the document id, and it fails soft when Firestore is
+ * unreachable.
+ *
+ * Its window is fixed rather than rolling, so a link minted near a boundary
+ * can be followed by another as soon as the next window opens — the cooldown
+ * holds for somewhere between zero and its full length. Where a window does
+ * end early the outcome is one extra mint, which the route reports as the
+ * throttle it is rather than as a failure.
+ *
+ * ## It may only suppress on evidence, never on silence
+ *
+ * The limiter refuses for two unrelated reasons, and only one of them is a
+ * counted overage. `contended` means the counter could not be read and
+ * written inside its budget, and the budget is spent by any slowness at all —
+ * a cold instance paying for Admin SDK startup and two Firestore round trips
+ * reaches it without another caller in sight, which on a low-traffic
+ * deployment is the ordinary case rather than the rare one.
+ *
+ * That refusal carries no information about whether a link was recently
+ * minted, so it may not be read as one. The asymmetry is the whole argument:
+ * a duplicate mail is a nuisance the route already reports correctly, while a
+ * suppressed FIRST mail is an account that never receives the link it is
+ * waiting for — and because a suppressed send is answered 200, the account
+ * holder is told a mail is on its way that nobody ever sent. A cooldown whose
+ * purpose is politeness does not get to fail that way, so an unanswered gate
+ * sends.
+ */ /**
+ * How long an automatic send suppresses the next one. Long enough to cover the
+ * round trip this exists for — open the mail app, look, come back — and short
+ * enough that someone whose mail was eaten by a spam filter gets a fresh one
+ * from a later visit rather than only from the resend button.
+ */ export const VERIFY_EMAIL_AUTO_SEND_COOLDOWN_MS = 10 * 60 * 1000;
+/**
+ * Asks whether the page's automatic send may mint a link for `uid`.
+ *
+ * Keyed on the uid alone, under its own prefix: the cooldown is one account's
+ * and never another's, and it counts separately from the per-uid hourly budget
+ * so a suppressed automatic send spends nothing a deliberate resend would want.
+ */ export async function consumeVerifyEmailAutoSend(uid, options) {
+    var _ref;
+    const at = (_ref = options == null ? void 0 : options.now) != null ? _ref : Date.now();
+    const result = await consumeRateLimit(`verify-email:auto:${uid}`, _extends({
+        limit: 1,
+        windowMs: VERIFY_EMAIL_AUTO_SEND_COOLDOWN_MS
+    }, (options == null ? void 0 : options.now) === undefined ? {} : {
+        now: options.now
+    }, (options == null ? void 0 : options.firestore) === undefined ? {} : {
+        firestore: options.firestore
+    }));
+    // A refusal the limiter could not count is silence, not evidence of a
+    // recent mail, and this cooldown suppresses only on evidence.
+    if (result.contended) {
+        return {
+            allowed: true,
+            retryAfterSeconds: 0,
+            degraded: result.degraded
+        };
+    }
+    return {
+        allowed: result.allowed,
+        retryAfterSeconds: result.allowed ? 0 : Math.max(1, Math.ceil((result.resetMs - at) / 1000)),
+        degraded: result.degraded
+    };
+}
+export default consumeVerifyEmailAutoSend;
+
+//# sourceMappingURL=verify-email-cooldown.js.map

package/src/lib/server/verify-email-cooldown.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/verify-email-cooldown.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 * The cooldown on the AUTOMATIC verification send (AGL-2584).\n *\n * `/verify-email` asks for a link every time it mounts, so somebody who leaves\n * the tab and comes back to see whether the mail arrived asks for a second\n * one. Identity Platform throttles link minting per account, ahead of and\n * independently of the route's own 5/hour budget, and that collision is what a\n * returning visitor met: a mail that had genuinely been sent, reported to them\n * as a send failure.\n *\n * Reopening the page is a request to know whether the first mail worked, not a\n * request for another one — so an automatic send is skipped while a link\n * minted for this uid is still young. The explicit \"Resend verification email\"\n * button does not come through here: someone who says the mail never arrived\n * is asking deliberately, and that affordance keeps the full per-uid budget.\n *\n * ## Why the state is server-side and not a `sentAt` in the browser\n *\n * The throttle this avoids is per ACCOUNT, so the memory of \"a link was minted\n * recently\" has to be too. A marker held in the browser cannot see a link\n * minted from a phone, a second browser, or a private window, and clearing\n * site data erases it — each of which puts the collision straight back. It\n * would also put the decision on the side of the wire that does not do the\n * minting, which is where it went wrong the first time.\n *\n * ## Why the durable limiter, with a budget of one\n *\n * A cooldown *is* a limit of one per window, and the limiter already solves\n * the parts that are easy to get wrong: it is global rather than per instance\n * (a per-instance `Map` on Vercel is close to no limit at all, AGL-794), it\n * hashes the key out of the document id, and it fails soft when Firestore is\n * unreachable.\n *\n * Its window is fixed rather than rolling, so a link minted near a boundary\n * can be followed by another as soon as the next window opens — the cooldown\n * holds for somewhere between zero and its full length. Where a window does\n * end early the outcome is one extra mint, which the route reports as the\n * throttle it is rather than as a failure.\n *\n * ## It may only suppress on evidence, never on silence\n *\n * The limiter refuses for two unrelated reasons, and only one of them is a\n * counted overage. `contended` means the counter could not be read and\n * written inside its budget, and the budget is spent by any slowness at all —\n * a cold instance paying for Admin SDK startup and two Firestore round trips\n * reaches it without another caller in sight, which on a low-traffic\n * deployment is the ordinary case rather than the rare one.\n *\n * That refusal carries no information about whether a link was recently\n * minted, so it may not be read as one. The asymmetry is the whole argument:\n * a duplicate mail is a nuisance the route already reports correctly, while a\n * suppressed FIRST mail is an account that never receives the link it is\n * waiting for — and because a suppressed send is answered 200, the account\n * holder is told a mail is on its way that nobody ever sent. A cooldown whose\n * purpose is politeness does not get to fail that way, so an unanswered gate\n * sends.\n */\n\n/**\n * How long an automatic send suppresses the next one. Long enough to cover the\n * round trip this exists for — open the mail app, look, come back — and short\n * enough that someone whose mail was eaten by a spam filter gets a fresh one\n * from a later visit rather than only from the resend button.\n */\nexport const VERIFY_EMAIL_AUTO_SEND_COOLDOWN_MS = 10 * 60 * 1000\n\nexport interface VerifyEmailAutoSendResult {\n  /** True when this mount may mint a link. */\n  allowed: boolean\n  /** Seconds until the cooldown lifts; 0 when allowed. */\n  retryAfterSeconds: number\n  /** True when the durable store was unreachable and only a local cap applied. */\n  degraded: boolean\n}\n\nexport interface VerifyEmailAutoSendOptions {\n  now?: number\n  /** Injectable for tests; defaults to the Admin SDK's Firestore. */\n  firestore?: unknown\n}\n\n/**\n * Asks whether the page's automatic send may mint a link for `uid`.\n *\n * Keyed on the uid alone, under its own prefix: the cooldown is one account's\n * and never another's, and it counts separately from the per-uid hourly budget\n * so a suppressed automatic send spends nothing a deliberate resend would want.\n */\nexport async function consumeVerifyEmailAutoSend(\n  uid: string,\n  options?: VerifyEmailAutoSendOptions,\n): Promise<VerifyEmailAutoSendResult> {\n  const at = options?.now ?? Date.now()\n  const result = await consumeRateLimit(`verify-email:auto:${uid}`, {\n    limit: 1,\n    windowMs: VERIFY_EMAIL_AUTO_SEND_COOLDOWN_MS,\n    ...(options?.now === undefined ? {} : { now: options.now }),\n    ...(options?.firestore === undefined\n      ? {}\n      : { firestore: options.firestore }),\n  })\n  // A refusal the limiter could not count is silence, not evidence of a\n  // recent mail, and this cooldown suppresses only on evidence.\n  if (result.contended) {\n    return { allowed: true, retryAfterSeconds: 0, degraded: result.degraded }\n  }\n  return {\n    allowed: result.allowed,\n    retryAfterSeconds: result.allowed\n      ? 0\n      : Math.max(1, Math.ceil((result.resetMs - at) / 1000)),\n    degraded: result.degraded,\n  }\n}\n\nexport default consumeVerifyEmailAutoSend\n"],"names":["consumeRateLimit","VERIFY_EMAIL_AUTO_SEND_COOLDOWN_MS","consumeVerifyEmailAutoSend","uid","options","at","now","Date","result","limit","windowMs","undefined","firestore","contended","allowed","retryAfterSeconds","degraded","Math","max","ceil","resetMs"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,gBAAgB,QAAQ,wBAAoB;AAErD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwDC,GAED;;;;;CAKC,GACD,OAAO,MAAMC,qCAAqC,KAAK,KAAK,KAAI;AAiBhE;;;;;;CAMC,GACD,OAAO,eAAeC,2BACpBC,GAAW,EACXC,OAAoC;;IAEpC,MAAMC,aAAKD,2BAAAA,QAASE,GAAG,mBAAIC,KAAKD,GAAG;IACnC,MAAME,SAAS,MAAMR,iBAAiB,CAAC,kBAAkB,EAAEG,KAAK,EAAE;QAChEM,OAAO;QACPC,UAAUT;OACNG,CAAAA,2BAAAA,QAASE,GAAG,MAAKK,YAAY,CAAC,IAAI;QAAEL,KAAKF,QAAQE,GAAG;IAAC,GACrDF,CAAAA,2BAAAA,QAASQ,SAAS,MAAKD,YACvB,CAAC,IACD;QAAEC,WAAWR,QAAQQ,SAAS;IAAC;IAErC,sEAAsE;IACtE,8DAA8D;IAC9D,IAAIJ,OAAOK,SAAS,EAAE;QACpB,OAAO;YAAEC,SAAS;YAAMC,mBAAmB;YAAGC,UAAUR,OAAOQ,QAAQ;QAAC;IAC1E;IACA,OAAO;QACLF,SAASN,OAAOM,OAAO;QACvBC,mBAAmBP,OAAOM,OAAO,GAC7B,IACAG,KAAKC,GAAG,CAAC,GAAGD,KAAKE,IAAI,CAAC,AAACX,CAAAA,OAAOY,OAAO,GAAGf,EAAC,IAAK;QAClDW,UAAUR,OAAOQ,QAAQ;IAC3B;AACF;AAEA,eAAed,2BAA0B"}

package/src/lib/server/visitor-write-rate-limit.d.ts

@@ -0,0 +1,87 @@
+/**
+ * @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.
+ */
+export interface VisitorWriteRateLimitOptions {
+    /** Dispatcher path, e.g. `commerce/cart`. Decides visitor vs machine. */
+    path: string;
+    /** The site the write targets; `''` when none resolved (still limited). */
+    hostId: string;
+    /** Read for its method and its client-address headers. */
+    request: {
+        method?: string;
+        headers?: {
+            get?: (name: string) => unknown;
+        };
+    };
+    limit?: number;
+    windowMs?: number;
+    nowMs?: number;
+    /** Injectable for tests; defaults to the Admin SDK's Firestore. */
+    firestore?: unknown;
+}
+/**
+ * Counts one visitor write and returns a 429 once the window is spent.
+ *
+ * ## Reads are not limited, and that is a decision rather than an omission
+ *
+ * AGL-1770 scopes this to visitor-facing *writes*, and the cost argument
+ * agrees. `RATE_LIMITING.md`'s standing rule is "`checkRateLimit` for volume,
+ * `consumeRateLimit` for consequence": each durable call is a Firestore
+ * transaction — one read plus one write — which is the right price for a cart
+ * write that itself creates a document, and the wrong price for a GET. The
+ * dispatcher's read paths "leave before any Firestore read" (the lockdown gate
+ * says so), so a durable limiter there would be the ONLY Firestore work in the
+ * request — precisely the analytics-beacon anti-pattern the doc names.
+ *
+ * The residual is real and worth stating: tenant reads are not free (~40
+ * Firestore reads per rendered page). It is a different defect with a
+ * different remedy — caching and the ISR layer, not a per-request
+ * transaction — and it is not this one.
+ *
+ * ## Fail SOFT, inherited from `consumeRateLimit` and re-argued here
+ *
+ * A Firestore outage lets traffic through, flagged `degraded`, rather than
+ * refusing it. CSRF fails closed; this deliberately does not, for three
+ * reasons, the third of which is specific to this limiter:
+ *
+ * 1. **The blast radius of the strict choice is every storefront at once.**
+ *    A Firestore blip that 429s every add-to-cart on every site costs
+ *    merchants sales during an outage they did not cause. The risk it guards
+ *    is unbounded document creation — storage. Lost revenue is the worse of
+ *    the two, and it is the one the merchant notices.
+ * 2. **The fallback still enforces something.** `consumeRateLimit` degrades to
+ *    the in-process limiter at the same ceiling, so the cap becomes
+ *    `limit × warm instances` rather than nothing.
+ * 3. **The store and the thing being protected are the same Firestore.** The
+ *    counter lives in `rateLimits` and the cart document it guards lives in
+ *    `hosts/…/carts` — one database. If the limiter cannot write, the write it
+ *    exists to bound is almost certainly failing too. Failing closed would
+ *    refuse requests that were going to fail anyway, and *additionally* refuse
+ *    the ones that would have succeeded. It buys nothing.
+ *
+ * The degradation stays findable: AGL-1679's recovery marker and AGL-1693's
+ * `/api/health/rate-limits` already cover every `consumeRateLimit` caller, so
+ * this one is watched by construction and needs no record of its own.
+ *
+ * ## What the caller is told
+ *
+ * A bare 429 with `Retry-After`. No `X-RateLimit-*` headers and no `degraded`
+ * flag, following `forms/submit`: this surface is public and unauthenticated,
+ * and both "you have N requests left" and "the global limiter is currently a
+ * per-instance one" are sentences an abuser would spend the window on.
+ */
+export declare function visitorWriteRateLimitRefusal(options: VisitorWriteRateLimitOptions): Promise<Response | null>;
+export default visitorWriteRateLimitRefusal;

package/src/lib/server/visitor-write-rate-limit.js

@@ -0,0 +1,117 @@
+/**
+ * @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 { isMachinePluginApiPath, lockdownIntentForMethod, VISITOR_WRITE_RATE_LIMIT, VISITOR_WRITE_RATE_WINDOW_MS, visitorWriteRateLimitKey } from "@aglyn/aglyn/server";
+import { consumeRateLimit } from "./rate-limit-store.js";
+import { NO_CLIENT_ADDRESS_BUCKET, readClientIp } from "@aglyn/aglyn/app-utils/request-ip";
+/**
+ * The rate-limit refusal a visitor-facing plugin write returns, or null to
+ * proceed (AGL-1770):
+ *
+ *   const limited = await visitorWriteRateLimitRefusal({ path, hostId, request })
+ *   if (limited) return limited
+ *
+ * Sits beside `visitorWriteRefusal` on purpose — same shape, same chokepoint,
+ * same "return it or carry on" contract. The policy (ceiling, window, key,
+ * which paths are exempt) is pure and lives in `@aglyn/aglyn/server`; this is
+ * only the durable half, which needs Firestore.
+ */ /**
+ * The visitor's address, through the shared reader, or the no-address bucket.
+ *
+ * Kept counting rather than skipped when nothing readable arrives: this is a
+ * cost control over unauthenticated writes, and one that stops counting is an
+ * open write endpoint. The key already carries the site, so an unreadable
+ * address shares one budget per SITE and not one across the deployment.
+ */ function clientIp(request) {
+    var _readClientIp;
+    const headers = request == null ? void 0 : request.headers;
+    if (typeof (headers == null ? void 0 : headers.get) !== 'function') return NO_CLIENT_ADDRESS_BUCKET;
+    return (_readClientIp = readClientIp(headers)) != null ? _readClientIp : NO_CLIENT_ADDRESS_BUCKET;
+}
+/**
+ * Counts one visitor write and returns a 429 once the window is spent.
+ *
+ * ## Reads are not limited, and that is a decision rather than an omission
+ *
+ * AGL-1770 scopes this to visitor-facing *writes*, and the cost argument
+ * agrees. `RATE_LIMITING.md`'s standing rule is "`checkRateLimit` for volume,
+ * `consumeRateLimit` for consequence": each durable call is a Firestore
+ * transaction — one read plus one write — which is the right price for a cart
+ * write that itself creates a document, and the wrong price for a GET. The
+ * dispatcher's read paths "leave before any Firestore read" (the lockdown gate
+ * says so), so a durable limiter there would be the ONLY Firestore work in the
+ * request — precisely the analytics-beacon anti-pattern the doc names.
+ *
+ * The residual is real and worth stating: tenant reads are not free (~40
+ * Firestore reads per rendered page). It is a different defect with a
+ * different remedy — caching and the ISR layer, not a per-request
+ * transaction — and it is not this one.
+ *
+ * ## Fail SOFT, inherited from `consumeRateLimit` and re-argued here
+ *
+ * A Firestore outage lets traffic through, flagged `degraded`, rather than
+ * refusing it. CSRF fails closed; this deliberately does not, for three
+ * reasons, the third of which is specific to this limiter:
+ *
+ * 1. **The blast radius of the strict choice is every storefront at once.**
+ *    A Firestore blip that 429s every add-to-cart on every site costs
+ *    merchants sales during an outage they did not cause. The risk it guards
+ *    is unbounded document creation — storage. Lost revenue is the worse of
+ *    the two, and it is the one the merchant notices.
+ * 2. **The fallback still enforces something.** `consumeRateLimit` degrades to
+ *    the in-process limiter at the same ceiling, so the cap becomes
+ *    `limit × warm instances` rather than nothing.
+ * 3. **The store and the thing being protected are the same Firestore.** The
+ *    counter lives in `rateLimits` and the cart document it guards lives in
+ *    `hosts/…/carts` — one database. If the limiter cannot write, the write it
+ *    exists to bound is almost certainly failing too. Failing closed would
+ *    refuse requests that were going to fail anyway, and *additionally* refuse
+ *    the ones that would have succeeded. It buys nothing.
+ *
+ * The degradation stays findable: AGL-1679's recovery marker and AGL-1693's
+ * `/api/health/rate-limits` already cover every `consumeRateLimit` caller, so
+ * this one is watched by construction and needs no record of its own.
+ *
+ * ## What the caller is told
+ *
+ * A bare 429 with `Retry-After`. No `X-RateLimit-*` headers and no `degraded`
+ * flag, following `forms/submit`: this surface is public and unauthenticated,
+ * and both "you have N requests left" and "the global limiter is currently a
+ * per-instance one" are sentences an abuser would spend the window on.
+ */ export async function visitorWriteRateLimitRefusal(options) {
+    var _options_nowMs, _options_limit, _options_windowMs;
+    var _options_request;
+    if (lockdownIntentForMethod((_options_request = options.request) == null ? void 0 : _options_request.method) === 'read') return null;
+    if (isMachinePluginApiPath(options.path)) return null;
+    const nowMs = (_options_nowMs = options.nowMs) != null ? _options_nowMs : Date.now();
+    const rate = await consumeRateLimit(visitorWriteRateLimitKey(options.hostId, clientIp(options.request)), {
+        limit: (_options_limit = options.limit) != null ? _options_limit : VISITOR_WRITE_RATE_LIMIT,
+        windowMs: (_options_windowMs = options.windowMs) != null ? _options_windowMs : VISITOR_WRITE_RATE_WINDOW_MS,
+        now: nowMs,
+        firestore: options.firestore
+    });
+    if (rate.allowed) return null;
+    return Response.json({
+        error: 'Too many requests'
+    }, {
+        status: 429,
+        headers: {
+            'Retry-After': String(Math.max(1, Math.ceil((rate.resetMs - nowMs) / 1000)))
+        }
+    });
+}
+export default visitorWriteRateLimitRefusal;
+
+//# sourceMappingURL=visitor-write-rate-limit.js.map

package/src/lib/server/visitor-write-rate-limit.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/visitor-write-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\nimport {\n  isMachinePluginApiPath,\n  lockdownIntentForMethod,\n  VISITOR_WRITE_RATE_LIMIT,\n  VISITOR_WRITE_RATE_WINDOW_MS,\n  visitorWriteRateLimitKey,\n} from '@aglyn/aglyn/server'\nimport { consumeRateLimit } from './rate-limit-store'\nimport {\n  NO_CLIENT_ADDRESS_BUCKET,\n  readClientIp,\n} from '@aglyn/aglyn/app-utils/request-ip'\n\n/**\n * The rate-limit refusal a visitor-facing plugin write returns, or null to\n * proceed (AGL-1770):\n *\n *   const limited = await visitorWriteRateLimitRefusal({ path, hostId, request })\n *   if (limited) return limited\n *\n * Sits beside `visitorWriteRefusal` on purpose — same shape, same chokepoint,\n * same \"return it or carry on\" contract. The policy (ceiling, window, key,\n * which paths are exempt) is pure and lives in `@aglyn/aglyn/server`; this is\n * only the durable half, which needs Firestore.\n */\n\n/**\n * The visitor's address, through the shared reader, or the no-address bucket.\n *\n * Kept counting rather than skipped when nothing readable arrives: this is a\n * cost control over unauthenticated writes, and one that stops counting is an\n * open write endpoint. The key already carries the site, so an unreadable\n * address shares one budget per SITE and not one across the deployment.\n */\nfunction clientIp(request: { headers?: { get?: (name: string) => unknown } }): string {\n  const headers = request?.headers\n  if (typeof headers?.get !== 'function') return NO_CLIENT_ADDRESS_BUCKET\n  return (\n    readClientIp(headers as { get(name: string): string | null }) ??\n    NO_CLIENT_ADDRESS_BUCKET\n  )\n}\n\nexport interface VisitorWriteRateLimitOptions {\n  /** Dispatcher path, e.g. `commerce/cart`. Decides visitor vs machine. */\n  path: string\n  /** The site the write targets; `''` when none resolved (still limited). */\n  hostId: string\n  /** Read for its method and its client-address headers. */\n  request: { method?: string; headers?: { get?: (name: string) => unknown } }\n  limit?: number\n  windowMs?: number\n  nowMs?: number\n  /** Injectable for tests; defaults to the Admin SDK's Firestore. */\n  firestore?: unknown\n}\n\n/**\n * Counts one visitor write and returns a 429 once the window is spent.\n *\n * ## Reads are not limited, and that is a decision rather than an omission\n *\n * AGL-1770 scopes this to visitor-facing *writes*, and the cost argument\n * agrees. `RATE_LIMITING.md`'s standing rule is \"`checkRateLimit` for volume,\n * `consumeRateLimit` for consequence\": each durable call is a Firestore\n * transaction — one read plus one write — which is the right price for a cart\n * write that itself creates a document, and the wrong price for a GET. The\n * dispatcher's read paths \"leave before any Firestore read\" (the lockdown gate\n * says so), so a durable limiter there would be the ONLY Firestore work in the\n * request — precisely the analytics-beacon anti-pattern the doc names.\n *\n * The residual is real and worth stating: tenant reads are not free (~40\n * Firestore reads per rendered page). It is a different defect with a\n * different remedy — caching and the ISR layer, not a per-request\n * transaction — and it is not this one.\n *\n * ## Fail SOFT, inherited from `consumeRateLimit` and re-argued here\n *\n * A Firestore outage lets traffic through, flagged `degraded`, rather than\n * refusing it. CSRF fails closed; this deliberately does not, for three\n * reasons, the third of which is specific to this limiter:\n *\n * 1. **The blast radius of the strict choice is every storefront at once.**\n *    A Firestore blip that 429s every add-to-cart on every site costs\n *    merchants sales during an outage they did not cause. The risk it guards\n *    is unbounded document creation — storage. Lost revenue is the worse of\n *    the two, and it is the one the merchant notices.\n * 2. **The fallback still enforces something.** `consumeRateLimit` degrades to\n *    the in-process limiter at the same ceiling, so the cap becomes\n *    `limit × warm instances` rather than nothing.\n * 3. **The store and the thing being protected are the same Firestore.** The\n *    counter lives in `rateLimits` and the cart document it guards lives in\n *    `hosts/…/carts` — one database. If the limiter cannot write, the write it\n *    exists to bound is almost certainly failing too. Failing closed would\n *    refuse requests that were going to fail anyway, and *additionally* refuse\n *    the ones that would have succeeded. It buys nothing.\n *\n * The degradation stays findable: AGL-1679's recovery marker and AGL-1693's\n * `/api/health/rate-limits` already cover every `consumeRateLimit` caller, so\n * this one is watched by construction and needs no record of its own.\n *\n * ## What the caller is told\n *\n * A bare 429 with `Retry-After`. No `X-RateLimit-*` headers and no `degraded`\n * flag, following `forms/submit`: this surface is public and unauthenticated,\n * and both \"you have N requests left\" and \"the global limiter is currently a\n * per-instance one\" are sentences an abuser would spend the window on.\n */\nexport async function visitorWriteRateLimitRefusal(\n  options: VisitorWriteRateLimitOptions,\n): Promise<Response | null> {\n  if (lockdownIntentForMethod(options.request?.method) === 'read') return null\n  if (isMachinePluginApiPath(options.path)) return null\n\n  const nowMs = options.nowMs ?? Date.now()\n  const rate = await consumeRateLimit(\n    visitorWriteRateLimitKey(options.hostId, clientIp(options.request)),\n    {\n      limit: options.limit ?? VISITOR_WRITE_RATE_LIMIT,\n      windowMs: options.windowMs ?? VISITOR_WRITE_RATE_WINDOW_MS,\n      now: nowMs,\n      firestore: options.firestore,\n    },\n  )\n  if (rate.allowed) return null\n\n  return Response.json(\n    { error: 'Too many requests' },\n    {\n      status: 429,\n      headers: {\n        'Retry-After': String(\n          Math.max(1, Math.ceil((rate.resetMs - nowMs) / 1000)),\n        ),\n      },\n    },\n  )\n}\n\nexport default visitorWriteRateLimitRefusal\n"],"names":["isMachinePluginApiPath","lockdownIntentForMethod","VISITOR_WRITE_RATE_LIMIT","VISITOR_WRITE_RATE_WINDOW_MS","visitorWriteRateLimitKey","consumeRateLimit","NO_CLIENT_ADDRESS_BUCKET","readClientIp","clientIp","request","headers","get","visitorWriteRateLimitRefusal","options","method","path","nowMs","Date","now","rate","hostId","limit","windowMs","firestore","allowed","Response","json","error","status","String","Math","max","ceil","resetMs"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SACEA,sBAAsB,EACtBC,uBAAuB,EACvBC,wBAAwB,EACxBC,4BAA4B,EAC5BC,wBAAwB,QACnB,sBAAqB;AAC5B,SAASC,gBAAgB,QAAQ,wBAAoB;AACrD,SACEC,wBAAwB,EACxBC,YAAY,QACP,oCAAmC;AAE1C;;;;;;;;;;;CAWC,GAED;;;;;;;CAOC,GACD,SAASC,SAASC,OAA0D;QAIxEF;IAHF,MAAMG,UAAUD,2BAAAA,QAASC,OAAO;IAChC,IAAI,QAAOA,2BAAAA,QAASC,GAAG,MAAK,YAAY,OAAOL;IAC/C,QACEC,gBAAAA,aAAaG,oBAAbH,gBACAD;AAEJ;AAgBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkDC,GACD,OAAO,eAAeM,6BACpBC,OAAqC;QAKvBA,gBAIHA,gBACGA;QARcA;IAA5B,IAAIZ,yBAAwBY,mBAAAA,QAAQJ,OAAO,qBAAfI,iBAAiBC,MAAM,MAAM,QAAQ,OAAO;IACxE,IAAId,uBAAuBa,QAAQE,IAAI,GAAG,OAAO;IAEjD,MAAMC,SAAQH,iBAAAA,QAAQG,KAAK,YAAbH,iBAAiBI,KAAKC,GAAG;IACvC,MAAMC,OAAO,MAAMd,iBACjBD,yBAAyBS,QAAQO,MAAM,EAAEZ,SAASK,QAAQJ,OAAO,IACjE;QACEY,KAAK,GAAER,iBAAAA,QAAQQ,KAAK,YAAbR,iBAAiBX;QACxBoB,QAAQ,GAAET,oBAAAA,QAAQS,QAAQ,YAAhBT,oBAAoBV;QAC9Be,KAAKF;QACLO,WAAWV,QAAQU,SAAS;IAC9B;IAEF,IAAIJ,KAAKK,OAAO,EAAE,OAAO;IAEzB,OAAOC,SAASC,IAAI,CAClB;QAAEC,OAAO;IAAoB,GAC7B;QACEC,QAAQ;QACRlB,SAAS;YACP,eAAemB,OACbC,KAAKC,GAAG,CAAC,GAAGD,KAAKE,IAAI,CAAC,AAACb,CAAAA,KAAKc,OAAO,GAAGjB,KAAI,IAAK;QAEnD;IACF;AAEJ;AAEA,eAAeJ,6BAA4B"}

package/src/lib/server/workspace-domains.d.ts

@@ -0,0 +1,156 @@
+/**
+ * @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.
+ */
+/**
+ * Attach and detach names for the console (AGL-1136).
+ *
+ * Two layers. The bottom one — `attachProjectDomain` / `detachProjectDomain` —
+ * takes a fully-qualified name and is what a custom **console** domain uses
+ * (AGL-1373). The top one is the workspace-subdomain pair below, which is that
+ * primitive with `{slug}.aglyn.com` built for it.
+ *
+ * The hosting vendor is no longer either of them. Registering a name goes
+ * through `domain-provider.ts`, so the same workspace subdomain is created by
+ * Vercel's API on Aglyn's own hosting, by a wildcard record on a Docker
+ * install, or by whatever an operator put behind the webhook driver. What
+ * stays here is everything that is Aglyn's own policy rather than a vendor's:
+ * the slug arithmetic, the upload-CORS reconcile, and the three properties
+ * below.
+ *
+ * AGL-1135 removed the `*.aglyn.com` wildcard, because it meant every
+ * hostname under the domain served a real console sign-in page —
+ * `billing-security-update.aglyn.com` returned 200 with a valid certificate.
+ * Removing it made unregistered names 404, and made **registered** names
+ * something that has to be registered: a slug only resolves if that exact
+ * domain is attached.
+ *
+ * Nothing did that, so every workspace created after AGL-1135 had a subdomain
+ * that 404s. AGL-1115 then made signup provision an org, which turned a latent
+ * gap into one every new account hits.
+ *
+ * ## Three properties, in the order they matter
+ *
+ * 1. **It can never fail an org.** Every entry point swallows its errors and
+ *    returns a verdict instead of throwing. The console is path-routed
+ *    (`app.aglyn.com/{slug}`) and that is the canonical form, so a workspace
+ *    with no subdomain is fully usable — while an org creation that rolled
+ *    back because a DNS API was slow would not be.
+ * 2. **Unconfigured is a no-op, not an error.** With no provider this reports
+ *    `skipped`. A deployment that registers names some other way must not log
+ *    an error per signup forever.
+ * 3. **A rename ADDS without removing.** The old slug keeps a tombstone that
+ *    308s to the new one (AGL-585/236), and a redirect can only run on a
+ *    hostname that still resolves. Detaching the old domain would break the
+ *    very redirect the tombstone exists to serve.
+ */
+import { type DomainAttachOptions, type DomainOutcome, type DomainScope, type ProjectDomainStatus } from './domain-provider';
+import { type UploadCorsRelease, type UploadCorsVerdict } from './upload-cors-reconcile';
+export { domainStateServes, redirectHostname, type ProjectDomainState, type ProjectDomainStatus, type ProjectDomainVerification, } from './domain-provider';
+export type WorkspaceDomainOutcome = DomainOutcome;
+export interface WorkspaceDomainResult {
+    outcome: WorkspaceDomainOutcome;
+    domain: string;
+    detail?: string;
+    /**
+     * Whether a browser at this name can complete a signed direct-to-GCS upload
+     * (AGL-1452).
+     *
+     * Present only when the attach made the name a SERVING origin — a redirect
+     * never becomes one. `permitted: false` carries the exact command a human
+     * must run, so the gap is legible here rather than days later as a large
+     * upload that fails behind a generic snackbar.
+     */
+    uploadCors?: UploadCorsVerdict | null;
+    /**
+     * What a DETACH did about the origin the name leaves behind (AGL-1452).
+     *
+     * The attach half without this one only ever grows the allowlist. A stale
+     * origin is a standing permission to complete a signed upload, held by a host
+     * we no longer serve — and for a white-label console domain, one the customer
+     * still controls.
+     */
+    uploadCorsRelease?: UploadCorsRelease | null;
+}
+export type ProjectDomainOptions = DomainAttachOptions;
+/**
+ * Attach one fully-qualified name to the console.
+ *
+ * Idempotent by contract: a name already registered comes back as
+ * `already-exists`, which is success — the reconcile script and the create
+ * path can both run without coordinating.
+ *
+ * ⚠️ Tolerating `already-exists` is only safe while **every** name this
+ * function is asked to attach is also claimed in Firestore. Without that, a
+ * second org attaches a name someone else already holds, reads it as success,
+ * and gets a console that looks healthy while its visitors are served — or
+ * redirected — somewhere else. That is the AGL-743 shape, and
+ * `console-domains.ts` is where the claim is kept in step.
+ */
+export declare function attachProjectDomain(name: string, options?: ProjectDomainOptions, scope?: DomainScope): Promise<WorkspaceDomainResult>;
+/**
+ * The command still owed after a set of attaches, or null when nothing is
+ * (AGL-1452).
+ *
+ * One remedy rather than a list: every verdict names the same bucket and the
+ * same command, and a caller that has to render five copies of it renders
+ * none.
+ */
+export declare function pendingUploadCorsRemedy(results: WorkspaceDomainResult[]): string | null;
+/** Detach one fully-qualified name from the console. */
+export declare function detachProjectDomain(name: string, scope?: DomainScope): Promise<WorkspaceDomainResult>;
+/**
+ * Attach `{slug}.<workspace domain>` so the workspace subdomain resolves.
+ *
+ * The `!slug` guard is not redundant with the one inside `attachProjectDomain`:
+ * an empty slug still produces the well-formed `.aglyn.com`, and on the detach
+ * side that is a request to delete the apex.
+ */
+export declare function attachWorkspaceDomain(slug: string): Promise<WorkspaceDomainResult>;
+/**
+ * Detach the domain, for org erasure.
+ *
+ * NOT called on rename: the previous slug keeps serving a 308 to the new one,
+ * and a redirect needs a hostname that still resolves.
+ */
+export declare function detachWorkspaceDomain(slug: string): Promise<WorkspaceDomainResult>;
+/**
+ * Whether the workspace-domain integration is configured at all.
+ *
+ * Exposed so a reconcile script can say "not configured" once instead of
+ * reporting every workspace as skipped, which reads like a failure.
+ */
+export declare function workspaceDomainsConfigured(): boolean;
+/**
+ * What a name is ACTUALLY doing, right now.
+ *
+ * `attachProjectDomain` answers "did the registration succeed", which is a
+ * different question and a much weaker one. A domain can be registered and
+ * still serve nothing — ownership unproven, DNS not yet pointed, certificate
+ * not yet issued — and all three return a perfectly successful attach.
+ *
+ * That is the gap this closes (AGL-1913): the site custom-domain wizard
+ * reported `attached: true` off the attach alone, so "certificate is still
+ * issuing" and "this will never work" rendered as the same green chip, and the
+ * only advice the docs could give was to press retry again.
+ *
+ * `scope` picks which app should be answering for the name — `tenant` for a
+ * published site's custom domain, `console` for a workspace subdomain or a
+ * white-label console domain. It was a raw project id before the provider
+ * seam, which only ever meant anything to one vendor.
+ */
+export declare function projectDomainStatus(name: string, options?: {
+    scope?: DomainScope;
+}): Promise<ProjectDomainStatus>;