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

package/src/lib/server/rate-limit-store.js

@@ -0,0 +1,1220 @@
+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 { deploymentRegion } from "@aglyn/aglyn/app-utils/deployment-shape";
+import { createHash } from "crypto";
+// The atomic counter primitive for the AGL-1921 server-error markers below.
+// Commutative server-side, so instances converging on one minute's document
+// neither contend nor retry — see `flushServerErrors`.
+import { FieldValue } from "firebase-admin/firestore";
+import { firebaseAdmin } from "./firebase-admin.js";
+import { checkRateLimit, DEFAULT_RATE_LIMIT, DEFAULT_RATE_WINDOW_MS } from "./api-http.js";
+/**
+ * Durable, cross-instance rate limiting (AGL-794).
+ *
+ * Every limiter in the codebase was a per-instance `Map`, each carrying its
+ * own "best-effort, serverless instances are ephemeral" caveat. On Vercel that
+ * is close to no limit at all: the counter resets on every cold start and each
+ * concurrent instance keeps its own, so the effective cap is roughly
+ * `limit × instances` and an attacker can widen it just by going wider. That
+ * is tolerable for blunting accidental bursts; it is not a brute-force
+ * defense.
+ *
+ * This backs the same fixed-window shape with a Firestore counter, so the cap
+ * is global. `api-http.ts` deliberately stays pure — it has no imports and is
+ * unit-tested directly — so the storage-backed variant lives here instead of
+ * being bolted onto it.
+ *
+ * **Cost is the reason this isn't the default everywhere.** Each call is a
+ * transaction (one read + one write). That is the right trade for a password
+ * unlock attempt; it is the wrong trade for an analytics beacon, which can
+ * fire on every page view. Use `checkRateLimit` for volume, this for
+ * consequence.
+ */ /** Collection holding one document per (key, window). Server-writes only. */ export const RATE_LIMIT_COLLECTION = 'rateLimits';
+/**
+ * Document-id prefix for degradation markers (AGL-1679).
+ *
+ * `degraded: true` used to exist only in a `console.error`, which means a
+ * Firestore blip silently dropped every durable limiter — auth, password
+ * reset, and now the public REST API's per-key quota — back to a per-instance
+ * cap for as long as it lasted, and nobody found out. Fail-soft is only a
+ * defensible choice if someone can tell that it fired.
+ *
+ * This is deliberately not an alerting stack. It is the cheapest thing that
+ * makes a degraded window answerable after the fact: when an episode ends,
+ * the instance writes one summary document into the SAME collection, so it
+ * inherits the deny-all rule and the `expiresAt` TTL policy that already
+ * exist rather than needing a new collection, a rules deploy and a second TTL
+ * policy. Ids are minute-bucketed so concurrent instances converge on a
+ * handful of documents:
+ *
+ * ```
+ * rateLimits/degraded_1755100800000
+ * ```
+ *
+ * Written on RECOVERY, never during the outage — the store is unreachable
+ * exactly when the episode is happening, so a marker written then would be
+ * the one write guaranteed to fail.
+ */ export const DEGRADATION_DOC_PREFIX = 'degraded_';
+/** Marker id granularity, and the log re-notice interval for a long episode. */ const DEGRADATION_BUCKET_MS = 60000;
+/** How long a marker survives the TTL sweep — long enough to look back. */ const DEGRADATION_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
+/**
+ * The episode currently in progress on THIS instance, or null when healthy.
+ * Module-scoped on purpose: it is a per-instance observation being reported,
+ * and there is nowhere durable to keep it while the durable store is down.
+ */ let episode = null;
+/** Short, stable error code for the marker and the log line. */ function failureCode(error) {
+    var _ref;
+    const code = error == null ? void 0 : error.code;
+    if (typeof code === 'string' || typeof code === 'number') return String(code);
+    return String((_ref = error == null ? void 0 : error.message) != null ? _ref : 'unknown').slice(0, 120);
+}
+/**
+ * Record one fallback. Logs at the start of an episode and at most once a
+ * minute after that — the public REST API now calls this path on every
+ * request, so a per-call `console.error` during a Firestore outage would be a
+ * log flood that buries the signal it is meant to be.
+ */ function noteDegradation(nowMs, error) {
+    const bucket = Math.floor(nowMs / DEGRADATION_BUCKET_MS);
+    if (!episode) {
+        episode = {
+            count: 1,
+            firstAtMs: nowMs,
+            lastAtMs: nowMs,
+            code: failureCode(error),
+            lastLoggedBucket: bucket
+        };
+        console.error('[rate-limit] degraded: durable store unavailable, falling back to the per-instance cap', {
+            code: episode.code,
+            atMs: nowMs
+        });
+        return;
+    }
+    episode.count += 1;
+    episode.lastAtMs = nowMs;
+    episode.code = failureCode(error);
+    if (bucket > episode.lastLoggedBucket) {
+        episode.lastLoggedBucket = bucket;
+        console.error('[rate-limit] degraded: still falling back', {
+            code: episode.code,
+            count: episode.count,
+            sinceMs: episode.firstAtMs
+        });
+    }
+}
+/**
+ * An episode ended: close it out and leave a durable record of the window.
+ *
+ * Fire-and-forget and best-effort — this is a diagnostic, and failing a
+ * customer's request because the postmortem breadcrumb could not be written
+ * would be a worse bug than the one it documents. The transaction shape
+ * matches the counter above so a marker merges cleanly when several instances
+ * recover into the same minute.
+ */ function flushDegradation(firestore, nowMs) {
+    const ended = episode;
+    if (!ended) return;
+    // Cleared BEFORE the await so a concurrent recovery cannot flush it twice.
+    episode = null;
+    console.error('[rate-limit] recovered from degraded window', {
+        count: ended.count,
+        firstAtMs: ended.firstAtMs,
+        lastAtMs: ended.lastAtMs,
+        code: ended.code
+    });
+    const bucketStart = Math.floor(ended.firstAtMs / DEGRADATION_BUCKET_MS) * DEGRADATION_BUCKET_MS;
+    const ref = firestore.collection(RATE_LIMIT_COLLECTION).doc(`${DEGRADATION_DOC_PREFIX}${bucketStart}`);
+    void firestore.runTransaction(async (tx)=>{
+        var _ref, _ref1;
+        const snapshot = await tx.get(ref);
+        const priorCalls = (_ref = snapshot.exists ? snapshot.get('calls') : 0) != null ? _ref : 0;
+        const priorEpisodes = (_ref1 = snapshot.exists ? snapshot.get('episodes') : 0) != null ? _ref1 : 0;
+        const priorFirst = snapshot.exists ? snapshot.get('firstAtMs') : undefined;
+        const priorLast = snapshot.exists ? snapshot.get('lastAtMs') : undefined;
+        tx.set(ref, {
+            calls: priorCalls + ended.count,
+            episodes: priorEpisodes + 1,
+            firstAtMs: Math.min(priorFirst != null ? priorFirst : ended.firstAtMs, ended.firstAtMs),
+            lastAtMs: Math.max(priorLast != null ? priorLast : ended.lastAtMs, ended.lastAtMs),
+            code: ended.code,
+            region: deploymentRegion(),
+            // Same TTL field the counters use, so the policy already configured
+            // on this collection sweeps these too — just far later.
+            expiresAt: new Date(nowMs + DEGRADATION_RETENTION_MS)
+        }, {
+            merge: true
+        });
+    }).catch(()=>undefined);
+}
+/**
+ * The degradation episode in progress on this instance, or `null`. Exposed
+ * for tests and for any future health surface; callers must not treat it as a
+ * global view — it only ever describes the instance that answers.
+ */ export function currentRateLimitDegradation() {
+    return episode;
+}
+/** Test seam: forget any in-progress episode. */ export function resetRateLimitDegradationForTests() {
+    episode = null;
+}
+/**
+ * Document-id prefix for signup-refusal markers (AGL-1907).
+ *
+ * `/api/orgs/create` has been rate-limited since AGL-1534 (3/h per uid, 10/h
+ * per IP) and AGL-1536 watches org-creation VOLUME — but volume only counts
+ * the signups that SUCCEEDED. A scripted farm that trips the limiter is
+ * therefore invisible in exactly the moment it is being contained: the 429s
+ * are the attack's signature and nothing recorded them. Before Sep 1 that is
+ * the difference between "the limiter held" and "we have no idea whether it
+ * was ever tested".
+ *
+ * Written into the SAME `rateLimits` collection as the counters and the
+ * AGL-1679 degradation markers, for the same reason that one gave: it inherits
+ * the deny-all security rule and the `expiresAt` TTL policy that already
+ * exist, instead of needing a new collection, a rules deploy and a second TTL
+ * policy. Minute-bucketed so concurrent instances converge:
+ *
+ * ```
+ * rateLimits/signupRefused_1755100800000
+ * ```
+ *
+ * **The timestamp field is `refusedAtMs`, deliberately not `lastAtMs`.** The
+ * AGL-1693 rate-limiter health probe queries this collection with
+ * `where('lastAtMs', '>=', cutoff).orderBy('lastAtMs','desc').limit(N)`. A
+ * refusal marker carrying `lastAtMs` would be picked up by that range and,
+ * under a flood, could fill the limit and push the real degradation markers
+ * out of the result — silently blinding a sibling alarm. A distinct field name
+ * keeps the two queries disjoint at the index level rather than relying on the
+ * id-prefix filter that runs after the read.
+ */ export const SIGNUP_REFUSAL_DOC_PREFIX = 'signupRefused_';
+/** Marker id granularity. Matches the degradation markers. */ const SIGNUP_REFUSAL_BUCKET_MS = 60000;
+/**
+ * How long a refusal marker survives the TTL sweep. Shorter than the 30 days
+ * degradation markers get: these can be written once a minute under sustained
+ * pressure, and the question they answer ("was there a wave, and when") is
+ * asked in the days after launch, not the month after.
+ */ const SIGNUP_REFUSAL_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
+/**
+ * Record one refused org-creation attempt.
+ *
+ * Fire-and-forget and best-effort, like `flushDegradation`: refusing the
+ * request is the control, and failing a 429 because its breadcrumb could not
+ * be written would be strictly worse than not having the breadcrumb. Callers
+ * must not await this on the response path.
+ *
+ * **On the write-per-refusal cost.** A refused request is free to the attacker
+ * and now costs one transaction — the usual amplification objection. It does
+ * not apply here in kind, only in degree: `/api/orgs/create` already spends
+ * TWO `consumeRateLimit` transactions on every hit including the refused ones
+ * (AGL-1534 counts over-limit attempts by design), so this is a third write on
+ * a path that was already three, not a new class of cost. If it ever shows up
+ * on the bill the fix is in-process coalescing like `episode` above, not
+ * dropping the signal.
+ *
+ * Nothing identifying is stored. The counts are per-reason only; the uid and
+ * IP that were refused stay in the (hashed) limiter keys, which this never
+ * reads.
+ */ export function recordSignupRefusal(reason, options) {
+    var _ref;
+    const nowMs = (_ref = options == null ? void 0 : options.now) != null ? _ref : Date.now();
+    const bucketStart = Math.floor(nowMs / SIGNUP_REFUSAL_BUCKET_MS) * SIGNUP_REFUSAL_BUCKET_MS;
+    let firestore;
+    try {
+        var _ref1;
+        firestore = (_ref1 = options == null ? void 0 : options.firestore) != null ? _ref1 : firebaseAdmin.app().firestore();
+    } catch (unused) {
+        // No Admin app (a unit test, a misconfigured instance). The refusal still
+        // happened and the caller still refuses; only the breadcrumb is lost.
+        return;
+    }
+    const ref = firestore.collection(RATE_LIMIT_COLLECTION).doc(`${SIGNUP_REFUSAL_DOC_PREFIX}${bucketStart}`);
+    void firestore.runTransaction(async (tx)=>{
+        var _ref, _ref1, _ref2, _ref3;
+        const snapshot = await tx.get(ref);
+        const priorTotal = (_ref = snapshot.exists ? snapshot.get('refusals') : 0) != null ? _ref : 0;
+        const priorByReason = (_ref1 = snapshot.exists ? snapshot.get('byReason') : undefined) != null ? _ref1 : {};
+        const priorFirst = snapshot.exists ? snapshot.get('firstRefusedAtMs') : undefined;
+        tx.set(ref, {
+            refusals: priorTotal + 1,
+            byReason: _extends({}, priorByReason, {
+                [reason]: ((_ref2 = priorByReason == null ? void 0 : priorByReason[reason]) != null ? _ref2 : 0) + 1
+            }),
+            firstRefusedAtMs: Math.min(priorFirst != null ? priorFirst : nowMs, nowMs),
+            // NOT `lastAtMs` — see the prefix doc above.
+            refusedAtMs: Math.max((_ref3 = snapshot.exists ? snapshot.get('refusedAtMs') : 0) != null ? _ref3 : 0, nowMs),
+            expiresAt: new Date(nowMs + SIGNUP_REFUSAL_RETENTION_MS)
+        }, {
+            merge: true
+        });
+    }).catch(()=>undefined);
+}
+/**
+ * Document-id prefix for server-error markers (AGL-1921).
+ *
+ * ## Why a Firestore marker when the errors already go to Cloud Logging
+ *
+ * `reportServerError` forwards every `onRequestError` to a `server-errors` log
+ * in `aglyn-main`, which is the right sink for triage — Error Reporting groups
+ * them and a log-match policy can page on them. It is not a sink anything in
+ * this repo can READ. Measured 2026-08-24 against the production credential:
+ * `POST logging.googleapis.com/v2/entries:list` for that log answers
+ * **403 `Permission denied for all log views`**, because the firebase-admin
+ * service account can create log entries and cannot list them. So the only
+ * reader the log has is a GCP alert policy that does not exist yet, and
+ * creating one is the click, not a thing that ships with a commit.
+ *
+ * That is the AGL-2486 shape exactly — a detector written into a place nothing
+ * watches. This marker is the second copy of the count, in a store we can
+ * already read, so `/api/health/server-errors` can grade it and the readers
+ * that already exist (the 15-minute GitHub uptime probe, the external keyword
+ * monitors, `docs.aglyn.com/status`) become the listeners on day one.
+ *
+ * Written into the SAME `rateLimits` collection as the counters, the AGL-1679
+ * degradation markers and the AGL-1907 refusal markers, for the reason those
+ * two gave: it inherits the deny-all security rule and the `expiresAt` TTL
+ * policy that already exist, instead of needing a new collection, a rules
+ * deploy and a second TTL policy — i.e. instead of needing a console action
+ * nobody can take from code. Minute bucketed so concurrent instances
+ * converge:
+ *
+ * ```
+ * rateLimits/serverError_1755100800000
+ * ```
+ *
+ * **The timestamp field is `erroredAtMs`**, deliberately neither `lastAtMs`
+ * (AGL-1679's) nor `refusedAtMs` (AGL-1907's), for the reason spelled out on
+ * `SIGNUP_REFUSAL_DOC_PREFIX`: each health probe range-queries its own field,
+ * and a shared field would let one signal's flood fill another's read limit
+ * and silently blind it. Three signals, three disjoint indexes.
+ */ export const SERVER_ERROR_DOC_PREFIX = 'serverError_';
+/** Marker id granularity. Matches both sibling marker kinds. */ const SERVER_ERROR_BUCKET_MS = 60000;
+/**
+ * How long a server-error marker survives the TTL sweep. Seven days, matching
+ * the refusal markers rather than the degradation markers' thirty: these can
+ * be written every few seconds under a spike, and the question they answer
+ * ("was there a spike, when, and on which deployment") is asked in the days
+ * after an incident, not the month after.
+ */ const SERVER_ERROR_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
+/**
+ * Minimum spacing between marker writes from ONE instance (AGL-1921).
+ *
+ * The failure being watched for is a SPIKE, and a spike is exactly when an
+ * unbounded recorder turns one incident into a billing incident — the same
+ * argument that gave `reportServerError` its per-minute Logging budget. A
+ * write per error would also be a write per error onto a SINGLE document,
+ * which is where Firestore's per-document write ceiling lives and where
+ * AGL-2404's contention storm came from.
+ *
+ * So errors coalesce in process and land at most once every five seconds per
+ * instance — twelve writes a minute at the very worst, against a threshold
+ * measured in single digits over half an hour. The count is never rounded
+ * down: what is pending is added to the next flush, and a bucket rollover
+ * flushes what it was holding before the new bucket starts.
+ *
+ * **The first error of a window is written IMMEDIATELY** (`lastFlushAtMs`
+ * starts at 0), so a lone error is durable within a second and the alarm
+ * never waits on a second one to become visible.
+ */ const SERVER_ERROR_FLUSH_INTERVAL_MS = 5000;
+/**
+ * The errors this instance is holding, or null when it is holding none.
+ * Module-scoped for the same reason `episode` above is: it is a per-instance
+ * observation on its way to a durable place.
+ */ let serverErrors = null;
+/**
+ * Write what the accumulator is holding, and forget it.
+ *
+ * Fire-and-forget and best-effort, like `flushDegradation`: this runs while a
+ * request is already failing, and a monitoring breadcrumb must never be the
+ * reason a second thing breaks.
+ *
+ * `FieldValue.increment` with a merge, rather than the read-modify-write
+ * transaction the two sibling markers use: increments are commutative
+ * server-side, so several instances converging on one minute's document
+ * neither contend nor retry — which is the AGL-2416 lesson applied to a path
+ * that only ever runs during an incident.
+ */ function flushServerErrors(firestore, nowMs) {
+    const held = serverErrors;
+    if (!held || held.pending <= 0) return;
+    // Zeroed BEFORE the await so a concurrent flush cannot write them twice.
+    const errors = held.pending;
+    const byService = held.pendingByService;
+    const erroredAtMs = held.lastErrorAtMs;
+    const bucketStart = held.bucketStart;
+    held.pending = 0;
+    held.pendingByService = {};
+    held.lastFlushAtMs = nowMs;
+    const ref = firestore.collection(RATE_LIMIT_COLLECTION).doc(`${SERVER_ERROR_DOC_PREFIX}${bucketStart}`);
+    const byServiceIncrements = {};
+    for (const [service, count] of Object.entries(byService)){
+        byServiceIncrements[service] = FieldValue.increment(count);
+    }
+    void Promise.resolve(ref.set({
+        errors: FieldValue.increment(errors),
+        byService: byServiceIncrements,
+        // NOT `lastAtMs`, NOT `refusedAtMs` — see the prefix doc above.
+        erroredAtMs,
+        expiresAt: new Date(nowMs + SERVER_ERROR_RETENTION_MS)
+    }, {
+        merge: true
+    })).catch(()=>undefined);
+}
+/**
+ * Record one uncaught server-side error, for `/api/health/server-errors`.
+ *
+ * Called from `reportServerError`, which is called from each app's
+ * `onRequestError` hook — so this counts exactly what that hook can see: an
+ * uncaught throw in a render or a route handler. It does NOT see an error that
+ * kills the process first, a platform-level 5xx (function timeout, OOM,
+ * cold-start 502), or anything thrown in the edge runtime. Those need the
+ * Vercel log drain; `docs/UPTIME_AND_SLA.md` carries the list.
+ *
+ * Fire-and-forget and never throws. Nothing identifying is stored — a count
+ * and which deployment produced it. The message, the stack and the route
+ * pattern stay in the Logging entry, which is not public; this marker is read
+ * by an endpoint that is.
+ */ export function recordServerError(service, options) {
+    var _ref, _serverErrors_pendingByService_service;
+    const nowMs = (_ref = options == null ? void 0 : options.now) != null ? _ref : Date.now();
+    const bucketStart = Math.floor(nowMs / SERVER_ERROR_BUCKET_MS) * SERVER_ERROR_BUCKET_MS;
+    let firestore;
+    try {
+        var _ref1;
+        firestore = (_ref1 = options == null ? void 0 : options.firestore) != null ? _ref1 : firebaseAdmin.app().firestore();
+    } catch (unused) {
+        // No Admin app (a unit test, a misconfigured instance). The error still
+        // happened and the caller still reports it to Logging; only the count is
+        // lost — and a deployment that cannot reach Firestore at all is already
+        // red on `/api/health`'s own `firestore` check.
+        return;
+    }
+    // A rollover flushes what the OLD bucket was holding before anything is
+    // added to the new one, so a minute's count is never smeared into the next.
+    if (serverErrors && serverErrors.bucketStart !== bucketStart) {
+        flushServerErrors(firestore, nowMs);
+        serverErrors = null;
+    }
+    if (!serverErrors) {
+        serverErrors = {
+            bucketStart,
+            pending: 0,
+            pendingByService: {},
+            // 0, so the first error of a bucket is written immediately.
+            lastFlushAtMs: 0,
+            lastErrorAtMs: nowMs
+        };
+    }
+    serverErrors.pending += 1;
+    serverErrors.pendingByService[service] = ((_serverErrors_pendingByService_service = serverErrors.pendingByService[service]) != null ? _serverErrors_pendingByService_service : 0) + 1;
+    serverErrors.lastErrorAtMs = Math.max(serverErrors.lastErrorAtMs, nowMs);
+    if (nowMs - serverErrors.lastFlushAtMs >= SERVER_ERROR_FLUSH_INTERVAL_MS) {
+        flushServerErrors(firestore, nowMs);
+    }
+}
+/**
+ * Errors this instance is holding but has not written yet. Exposed for tests
+ * and for anyone reasoning about the coalescing window; callers must not treat
+ * it as a global view — it only ever describes the instance that answers.
+ */ export function pendingServerErrors() {
+    var _ref;
+    return (_ref = serverErrors == null ? void 0 : serverErrors.pending) != null ? _ref : 0;
+}
+/** Test seam: forget anything held. */ export function resetServerErrorsForTests() {
+    serverErrors = null;
+}
+/**
+ * Document-id prefix for the beacon's last-landed marker (AGL-2713).
+ *
+ * ## Why this one is not bucketed, and not queried
+ *
+ * Its four siblings above count OCCURRENCES over a window, so each one wants
+ * a stream of minute-bucketed documents and a range query over its own
+ * timestamp field. This answers a single question — *when did a heartbeat
+ * last reach Cloud Logging from this deployment* — so it is one document per
+ * service, read by id:
+ *
+ * ```
+ * rateLimits/beaconHeartbeat_console-web
+ * rateLimits/beaconHeartbeat_tenant-web
+ * ```
+ *
+ * A point read needs no index at all, which matters more than the cost: an
+ * index this repository cannot deploy without a token is an index that is not
+ * there when the failure is. Same collection as the siblings, for the reason
+ * they each gave — it inherits the deny-all rule and the `expiresAt` TTL
+ * policy that already exist, instead of needing a rules deploy nobody can
+ * make from code.
+ *
+ * **The timestamp field is `heartbeatAtMs`**, deliberately none of `lastAtMs`
+ * (AGL-1679), `refusedAtMs` (AGL-1907), `erroredAtMs` (AGL-1921) or
+ * `servedAtMs` (AGL-2583). This one is not range-queried, so the isolation
+ * argument the others make is not what earns it a field of its own — but a
+ * document carrying a sibling's field would enter that sibling's window and be
+ * counted as an episode it is not.
+ *
+ * ⚠️ **Evidence of a LANDING, never of a failure.** Nothing writes here when
+ * a heartbeat misses. So the worst a corrupt, stale or unreadable marker can
+ * do is make `/api/health/error-beacon` red sooner, and a deployment whose
+ * credential has never once worked has no marker at all and reds on its first
+ * probe. That asymmetry is what lets the door tolerate a miss without becoming
+ * a door that cannot go red.
+ */ export const BEACON_HEARTBEAT_DOC_PREFIX = 'beaconHeartbeat_';
+/**
+ * How long a last-landed marker survives the TTL sweep.
+ *
+ * Seven days, matching the refusal and server-error markers. It is refreshed
+ * on every successful probe, so the only way it ages out is a deployment that
+ * stopped answering entirely — by which time the door has been red for days
+ * and the marker's disappearance changes nothing.
+ */ const BEACON_HEARTBEAT_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
+/** How long the failure path waits for the marker before giving up on it. */ const BEACON_HEARTBEAT_READ_BUDGET_MS = 2000;
+/**
+ * Record that a heartbeat reached Cloud Logging (AGL-2713).
+ *
+ * Fire-and-forget and never throws, like `flushServerErrors`: this runs
+ * inside a monitoring probe, and a breadcrumb must never be the reason the
+ * probe it is attached to fails. A write that does not land simply means the
+ * next miss is graded without it, which is the safe direction.
+ *
+ * The caller is memoized per instance on a five-minute TTL, so the write rate
+ * is one per instance per five minutes however hard the public endpoint is
+ * hit — orders of magnitude under the per-document ceiling that produced
+ * AGL-2404's contention storm.
+ */ export function recordBeaconHeartbeat(service, options) {
+    var _ref;
+    const nowMs = (_ref = options == null ? void 0 : options.now) != null ? _ref : Date.now();
+    let firestore;
+    try {
+        var _ref1;
+        firestore = (_ref1 = options == null ? void 0 : options.firestore) != null ? _ref1 : firebaseAdmin.app().firestore();
+    } catch (unused) {
+        // No Admin app. The heartbeat still landed and the probe still reports
+        // green off the write itself; only the evidence for forgiving a FUTURE
+        // miss is lost, and a miss with no evidence reds.
+        return;
+    }
+    void Promise.resolve(firestore.collection(RATE_LIMIT_COLLECTION).doc(`${BEACON_HEARTBEAT_DOC_PREFIX}${service}`).set({
+        // NOT `lastAtMs`, NOT `refusedAtMs`, NOT `erroredAtMs`, NOT
+        // `servedAtMs` — see the prefix doc above.
+        heartbeatAtMs: nowMs,
+        service,
+        expiresAt: new Date(nowMs + BEACON_HEARTBEAT_RETENTION_MS)
+    }, {
+        merge: true
+    })).catch(()=>undefined);
+}
+/**
+ * When a heartbeat last landed for this deployment, or null (AGL-2713).
+ *
+ * Null covers three cases that must all grade the same way: no marker has
+ * ever been written, the document holds nothing usable, and the store could
+ * not be read inside its budget. Every one of them means *there is no proof a
+ * heartbeat landed recently*, and the caller forgives a miss only on proof.
+ * Folding them is therefore not a shortcut — distinguishing them could only
+ * ever be used to forgive something unproven.
+ *
+ * The budget is the reason this is not a bare `get()`. It runs on the failure
+ * path, where the credential is already misbehaving, and a Firestore client
+ * whose own token will not mint retries with backoff for far longer than a
+ * health endpoint may take to answer.
+ */ export async function readBeaconHeartbeat(service, options) {
+    try {
+        var _ref, _ref1;
+        const firestore = (_ref = options == null ? void 0 : options.firestore) != null ? _ref : firebaseAdmin.app().firestore();
+        const snapshot = await withBudget(firestore.collection(RATE_LIMIT_COLLECTION).doc(`${BEACON_HEARTBEAT_DOC_PREFIX}${service}`).get(), (_ref1 = options == null ? void 0 : options.budgetMs) != null ? _ref1 : BEACON_HEARTBEAT_READ_BUDGET_MS);
+        const landedAtMs = snapshot.get('heartbeatAtMs');
+        return typeof landedAtMs === 'number' && Number.isFinite(landedAtMs) ? landedAtMs : null;
+    } catch (unused) {
+        return null;
+    }
+}
+/**
+ * Document-id prefix for signup-page serve markers (AGL-2583).
+ *
+ * ## Why traffic is worth storing at all
+ *
+ * `/api/health/signups` counts orgs created in the trailing hour and goes red
+ * when there are TOO MANY. Zero — the reading that means nobody on earth can
+ * sign up — is its healthiest possible score, and that is how AGL-2581 refused
+ * every account creation for three days with the signup monitor green
+ * throughout. The missing half is a DENOMINATOR: zero accounts is an outage
+ * only if people were trying, and a quiet night otherwise.
+ *
+ * These markers are that denominator. Every render of the signup page fetches
+ * `/api/lockdown-status?feature=signups` to decide whether to show the paused
+ * notice, so that route is the one server touch a real arrival always makes,
+ * and counting it needs no new endpoint, no client beacon and no analytics
+ * vendor in the alerting path.
+ *
+ * Written into the SAME `rateLimits` collection as the counters and the three
+ * sibling marker kinds, for the reason they each gave: it inherits the
+ * deny-all security rule and the `expiresAt` TTL policy that already exist,
+ * instead of needing a new collection, a rules deploy and a second TTL policy.
+ * Minute bucketed so concurrent instances converge:
+ *
+ * ```
+ * rateLimits/signupServed_1755100800000
+ * ```
+ *
+ * **The timestamp field is `servedAtMs`**, deliberately none of `lastAtMs`
+ * (AGL-1679), `refusedAtMs` (AGL-1907) or `erroredAtMs` (AGL-1921), for the
+ * reason spelled out on `SIGNUP_REFUSAL_DOC_PREFIX`: each health probe
+ * range-queries its own field, and a shared field would let one signal's flood
+ * fill another's read limit and silently blind it. Four signals, four disjoint
+ * indexes.
+ */ export const SIGNUP_SERVED_DOC_PREFIX = 'signupServed_';
+/** Marker id granularity. Matches every sibling marker kind. */ const SIGNUP_SERVED_BUCKET_MS = 60000;
+/**
+ * How long a serve marker survives the TTL sweep. Seven days, matching the
+ * refusal and server-error markers: the question these answer ("were people
+ * arriving while nothing was being created") is asked during an incident and
+ * in the days after it, never a month later.
+ */ const SIGNUP_SERVED_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
+/**
+ * Minimum spacing between marker writes from ONE instance.
+ *
+ * The same argument `SERVER_ERROR_FLUSH_INTERVAL_MS` makes, for the same
+ * reason: this counts a PUBLIC page's traffic, so an unbounded recorder turns
+ * a marketing campaign into a write-per-visitor on a single hot document —
+ * which is where Firestore's per-document ceiling lives and where AGL-2404's
+ * contention storm came from. Serves coalesce in process and land at most once
+ * every five seconds per instance.
+ *
+ * **The first serve of a bucket is written IMMEDIATELY** (`lastFlushAtMs`
+ * starts at 0), so the denominator is never behind the numerator: an hour that
+ * saw traffic says so within a second of the first arrival.
+ */ const SIGNUP_SERVED_FLUSH_INTERVAL_MS = 5000;
+/**
+ * The serves this instance is holding, or null when it is holding none.
+ * Module-scoped for the same reason its siblings are: a per-instance
+ * observation on its way to a durable place.
+ */ let signupServes = null;
+/**
+ * Write what the accumulator is holding, and forget it.
+ *
+ * Fire-and-forget and best-effort: this runs on the signup page's own
+ * critical path, and a monitoring breadcrumb must never be the reason the
+ * page that sells the product gets slower or fails.
+ *
+ * `FieldValue.increment` with a merge, like the server-error marker: server
+ * side increments are commutative, so instances converging on one minute's
+ * document neither contend nor retry.
+ */ function flushSignupServes(firestore, nowMs) {
+    const held = signupServes;
+    if (!held || held.pending <= 0) return;
+    // Zeroed BEFORE the write so a concurrent flush cannot count them twice.
+    const serves = held.pending;
+    const servedAtMs = held.lastServedAtMs;
+    const bucketStart = held.bucketStart;
+    held.pending = 0;
+    held.lastFlushAtMs = nowMs;
+    try {
+        const ref = firestore.collection(RATE_LIMIT_COLLECTION).doc(`${SIGNUP_SERVED_DOC_PREFIX}${bucketStart}`);
+        void Promise.resolve(ref.set({
+            serves: FieldValue.increment(serves),
+            // NOT `lastAtMs`, NOT `refusedAtMs`, NOT `erroredAtMs` — see the
+            // prefix doc above.
+            servedAtMs,
+            expiresAt: new Date(nowMs + SIGNUP_SERVED_RETENTION_MS)
+        }, {
+            merge: true
+        })).catch(()=>undefined);
+    } catch (unused) {
+    // A Firestore handle that throws SYNCHRONOUSLY — a half-initialized admin
+    // app, a stub in a test — must not escape onto the signup page's request.
+    // The serve is lost from the denominator, which can only make the drought
+    // alarm quieter, never louder.
+    }
+}
+/**
+ * Record one serving of the signup page, for `/api/health/signup-volume`.
+ *
+ * Nothing identifying is stored — a count and a timestamp. No IP, no user
+ * agent, no referrer, no campaign: this marker is read by an endpoint that is
+ * public, and the drought verdict needs a number, not an audience.
+ *
+ * Never throws, and callers must not await it.
+ */ export function recordSignupServed(options) {
+    var _ref;
+    const nowMs = (_ref = options == null ? void 0 : options.now) != null ? _ref : Date.now();
+    const bucketStart = Math.floor(nowMs / SIGNUP_SERVED_BUCKET_MS) * SIGNUP_SERVED_BUCKET_MS;
+    let firestore;
+    try {
+        var _ref1;
+        firestore = (_ref1 = options == null ? void 0 : options.firestore) != null ? _ref1 : firebaseAdmin.app().firestore();
+    } catch (unused) {
+        // No Admin app (a unit test, a misconfigured instance). The page still
+        // serves; only the denominator loses a tick, and a deployment that cannot
+        // reach Firestore at all is already red on `/api/health`.
+        return;
+    }
+    // A rollover flushes what the OLD bucket was holding before anything is
+    // added to the new one, so a minute's count is never smeared into the next.
+    if (signupServes && signupServes.bucketStart !== bucketStart) {
+        flushSignupServes(firestore, nowMs);
+        signupServes = null;
+    }
+    if (!signupServes) {
+        signupServes = {
+            bucketStart,
+            pending: 0,
+            // 0, so the first serve of a bucket is written immediately.
+            lastFlushAtMs: 0,
+            lastServedAtMs: nowMs
+        };
+    }
+    signupServes.pending += 1;
+    signupServes.lastServedAtMs = Math.max(signupServes.lastServedAtMs, nowMs);
+    if (nowMs - signupServes.lastFlushAtMs >= SIGNUP_SERVED_FLUSH_INTERVAL_MS) {
+        flushSignupServes(firestore, nowMs);
+    }
+}
+/**
+ * Serves this instance is holding but has not written yet. Exposed for tests
+ * and for anyone reasoning about the coalescing window; it only ever describes
+ * the instance that answers.
+ */ export function pendingSignupServes() {
+    var _ref;
+    return (_ref = signupServes == null ? void 0 : signupServes.pending) != null ? _ref : 0;
+}
+/** Test seam: forget anything held. */ export function resetSignupServesForTests() {
+    signupServes = null;
+}
+/**
+ * Document-id prefix for org-creation ATTEMPT markers (AGL-2714).
+ *
+ * ## Why serves were the wrong denominator
+ *
+ * The drought verdict beside this one asks "did traffic arrive and no account
+ * come out", and it took its denominator from `signupServed_` — a hit on
+ * `/api/lockdown-status?feature=signups`, which the signup page fetches on
+ * every render. That counts LOOKERS. Crawlers, link previews, a person
+ * reading the plan names and closing the tab, and the diagnostic page load
+ * somebody makes while investigating the alert itself all land in it.
+ *
+ * At this platform's conversion rate an hour with a handful of arrivals and
+ * no account is the ordinary case, so the check could not tell a door that
+ * does not open from a quiet afternoon — and it paged as though the service
+ * were down. No threshold fixes that; the quantity is wrong.
+ *
+ * An ATTEMPT is somebody who authenticated, filled the form and asked for an
+ * org. If those arrive and no org appears, something is broken, and the
+ * question has an answer that does not depend on how many people were merely
+ * browsing.
+ *
+ * ## Why this is stronger than the refusal marker beside it
+ *
+ * `signupRefusal_` counts requests this route TURNED AWAY, which is a
+ * deliberate outcome the code chose. An attempt marker is written before any
+ * outcome is known, so the pair spans what refusals cannot see on their own:
+ * a request that 500s, hangs, or dies in the platform between the limiter and
+ * the write leaves an attempt and no org, and no refusal at all.
+ *
+ * **The field is `attemptedAtMs`**, deliberately none of `lastAtMs`
+ * (AGL-1679), `refusedAtMs` (AGL-1907), `erroredAtMs` (AGL-1921) or
+ * `servedAtMs` (AGL-2583) — same rule the four before it follow: each health
+ * probe range-queries its own field, and a shared field would let one
+ * signal's flood fill another's read limit and silently blind it.
+ */ export const SIGNUP_ATTEMPT_DOC_PREFIX = 'signupAttempted_';
+/** Marker id granularity. Matches every sibling marker kind. */ const SIGNUP_ATTEMPT_BUCKET_MS = 60000;
+/**
+ * How long an attempt marker survives the TTL sweep. Seven days, matching the
+ * serve and refusal markers it is read beside — the same incident asks all
+ * three, and a denominator that outlived its numerator would answer nothing.
+ */ const SIGNUP_ATTEMPT_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
+/**
+ * Record one attempt to create an org, for `/api/health/signup-volume`.
+ *
+ * Written per attempt with no in-process coalescing, unlike the serve marker.
+ * The serve marker guards a PUBLIC page whose traffic is unbounded; this one
+ * sits behind an authenticated route the limiter already caps at 3 per uid and
+ * 10 per IP an hour, so the write rate is bounded by the limiter rather than
+ * by the internet. It is also the third write on a path that already spends
+ * two `consumeRateLimit` transactions per hit, which is the same accounting
+ * `recordSignupRefusal` sets out.
+ *
+ * `FieldValue.increment` with a merge rather than a transaction: increments
+ * are commutative server-side, so instances converging on one minute's
+ * document neither contend nor retry.
+ *
+ * Nothing identifying is stored — a count and a timestamp. This marker is read
+ * by an endpoint that is public, and the drought verdict needs a number, not
+ * an audience.
+ *
+ * Never throws, and callers must not await it: creating the org is the
+ * control, and a monitoring breadcrumb must never be the reason a signup gets
+ * slower or fails.
+ */ export function recordSignupAttempt(options) {
+    var _ref;
+    const nowMs = (_ref = options == null ? void 0 : options.now) != null ? _ref : Date.now();
+    const bucketStart = Math.floor(nowMs / SIGNUP_ATTEMPT_BUCKET_MS) * SIGNUP_ATTEMPT_BUCKET_MS;
+    let firestore;
+    try {
+        var _ref1;
+        firestore = (_ref1 = options == null ? void 0 : options.firestore) != null ? _ref1 : firebaseAdmin.app().firestore();
+    } catch (unused) {
+        // No Admin app (a unit test, a misconfigured instance). The signup still
+        // proceeds; only the denominator loses a tick. Losing an attempt can only
+        // make the drought alarm quieter, never louder — the opposite bias to the
+        // one that would matter here.
+        return;
+    }
+    try {
+        const ref = firestore.collection(RATE_LIMIT_COLLECTION).doc(`${SIGNUP_ATTEMPT_DOC_PREFIX}${bucketStart}`);
+        void Promise.resolve(ref.set({
+            attempts: FieldValue.increment(1),
+            // NOT `lastAtMs`, NOT `refusedAtMs`, NOT `erroredAtMs`, NOT
+            // `servedAtMs` — see the prefix doc above.
+            attemptedAtMs: nowMs,
+            expiresAt: new Date(nowMs + SIGNUP_ATTEMPT_RETENTION_MS)
+        }, {
+            merge: true
+        })).catch(()=>undefined);
+    } catch (unused) {
+    // A Firestore handle that throws SYNCHRONOUSLY — a half-initialized admin
+    // app, a stub in a test — must not escape onto the signup request.
+    }
+}
+/**
+ * Wall-clock budget for one durable counter round trip (AGL-2404).
+ *
+ * Without a bound this function could not fail at all — it could only hang.
+ * The counter used to be a read-modify-write `runTransaction` on a single hot
+ * document: it contended, retried with backoff, and on a contended key
+ * routinely outran the platform's function ceiling, so the request died as a
+ * **504 with no body and no `Retry-After`** instead of the cheap 429 the
+ * limiter exists to produce. Measured against production on 2026-08-19 at
+ * `/api/protection/unlock`: sequential traffic refused cleanly at the 10th
+ * attempt, while **two** concurrent requests on one key were already enough
+ * to produce a 504 at ~10.3 s — the account-default function ceiling, since
+ * that route declares no `maxDuration`.
+ *
+ * AGL-2416 removed the read-modify-write (see {@link consumeRateLimit}), so
+ * the retry storm this bound was catching should no longer occur. The bound
+ * STAYS: it is what makes the function answerable at all, and a store that is
+ * slow for any other reason — a hot document at Firestore's own single-doc
+ * write ceiling, a network stall — must still produce a decision rather than
+ * a held function.
+ *
+ * 2.5 s is chosen to sit far below the smallest ceiling any caller runs at
+ * (10 s at the Vercel account default) while leaving room for the two round
+ * trips below, which measured ~0.6 s end to end on the same endpoint.
+ */ export const RATE_LIMIT_TRANSACTION_BUDGET_MS = 2500;
+/**
+ * Thrown when the durable counter could not reach a decision inside
+ * {@link RATE_LIMIT_TRANSACTION_BUDGET_MS}. Distinct from a store *error* on
+ * purpose — see the classification note on {@link consumeRateLimit}.
+ */ export class RateLimitContentionError extends Error {
+    constructor(message = 'rate-limit counter contended'){
+        super(message);
+        this.name = 'RateLimitContentionError';
+    }
+}
+/**
+ * gRPC status codes that mean "the store is up, this document is hot":
+ * `ABORTED` (10) is what Firestore returns when a transaction loses its
+ * optimistic race too many times, and `DEADLINE_EXCEEDED` (4) is the same
+ * condition observed as a timeout. Neither is an outage, so neither may take
+ * the fail-soft path — degrading on contention would let a caller widen its
+ * own cap just by going concurrent, which is the exact defect AGL-794 closed.
+ */ const CONTENTION_CODES = new Set([
+    4,
+    10
+]);
+function isContention(error) {
+    if (error instanceof RateLimitContentionError) return true;
+    const code = error == null ? void 0 : error.code;
+    return typeof code === 'number' && CONTENTION_CODES.has(code);
+}
+/**
+ * Resolve `work`, or reject with {@link RateLimitContentionError} once
+ * `budgetMs` elapses.
+ *
+ * The losing promise is explicitly silenced: an abandoned transaction that
+ * rejects later would otherwise surface as an unhandled rejection and, on a
+ * strict runtime, take the instance down — turning a contention fix into an
+ * availability bug.
+ */ async function withBudget(work, budgetMs) {
+    let timer;
+    work.catch(()=>undefined);
+    try {
+        return await Promise.race([
+            work,
+            new Promise((_, reject)=>{
+                timer = setTimeout(()=>reject(new RateLimitContentionError()), budgetMs);
+            })
+        ]);
+    } finally{
+        if (timer) clearTimeout(timer);
+    }
+}
+/**
+ * Add one to `ref`'s counter and report the total (AGL-2416).
+ *
+ * Two round trips, in this order and no other. The write MUST land before the
+ * read: reading first and writing second is a read-modify-write again, only
+ * without the transaction that made it safe, which would under-count under
+ * concurrency and let a caller widen its own cap by racing itself.
+ *
+ * `merge: true` creates the document on the first request of a window —
+ * `increment` on a missing field starts from zero — so no separate create is
+ * needed, and `windowStartMs`/`expiresAt` are re-stamped idempotently on every
+ * write rather than only on the first.
+ *
+ * A read-back that carries no usable count means the store accepted a write
+ * and then failed to show it. That is a malfunction, not contention, so it
+ * throws a plain error and takes the fail-SOFT path — the same posture as any
+ * other store failure. Returning `0` instead would read as "no requests yet"
+ * and admit every caller: fail-open, from the one branch that exists because
+ * the store is misbehaving.
+ */ async function countOne(ref, windowStartMs, resetMs, windowMs) {
+    var _snapshot_get;
+    await ref.set({
+        count: firebaseAdmin.firestore.FieldValue.increment(1),
+        windowStartMs,
+        // For a Firestore TTL policy on `expiresAt` — without one these
+        // documents accumulate forever. See docs/RATE_LIMITING.md.
+        expiresAt: new Date(resetMs + windowMs)
+    }, {
+        merge: true
+    });
+    const snapshot = await ref.get();
+    const observed = Number(snapshot == null ? void 0 : (_snapshot_get = snapshot.get) == null ? void 0 : _snapshot_get.call(snapshot, 'count'));
+    if (!Number.isFinite(observed) || observed < 1) {
+        throw new Error('rate-limit counter read-back returned no count');
+    }
+    return observed;
+}
+/**
+ * Document id for a (key, window) pair.
+ *
+ * The key is hashed rather than embedded: callers key on client IPs, and an
+ * IP is personal data that would otherwise sit in plaintext document ids
+ * (which also show up in any index export). Hashing additionally makes the id
+ * safe — Firestore ids may not contain `/`, which IPv6-mapped and
+ * path-derived keys can. Truncated to 32 hex chars: collisions would merely
+ * merge two callers into one bucket, and 128 bits is far past needing that.
+ */ function bucketId(key, windowStartMs) {
+    const hash = createHash('sha256').update(key).digest('hex').slice(0, 32);
+    return `${hash}_${windowStartMs}`;
+}
+/**
+ * Counts one request against `key`'s fixed window, globally.
+ *
+ * Fails *soft, not open*: if Firestore is unreachable the in-memory limiter
+ * answers and the result is flagged `degraded`. Failing fully open would let
+ * an attacker disable brute-force protection by inducing a storage error;
+ * failing fully closed would lock legitimate visitors out of a site because of
+ * an unrelated Firestore blip. Degrading to the per-instance cap keeps some
+ * protection and keeps the site usable, and says which happened.
+ *
+ * ## Two failures, two postures (AGL-2404)
+ *
+ * "Firestore is unreachable" and "this one document is contended" are not the
+ * same event and must not get the same answer:
+ *
+ * - **The store is down** (fast error — `UNAVAILABLE`, a missing app, a
+ *   credential failure). Fail SOFT, exactly as before: degrade to the
+ *   per-instance cap and flag `degraded`. A real visitor must not lose access
+ *   to a customer's site over an unrelated blip.
+ * - **The key is contended** (`ABORTED`, `DEADLINE_EXCEEDED`, or the budget
+ *   above elapsing). Fail CLOSED: refuse with `contended: true` and let the
+ *   caller answer 429 with its usual `Retry-After`. Degrading here would be a
+ *   partial bypass — concurrent requests on ONE key are cheap to generate,
+ *   and if they dropped the cap to a per-instance count then going wide would
+ *   widen the cap, which is precisely the property AGL-794 removed.
+ *
+ * Refusing on contention is never worse than the 504 it replaces. A 504 is
+ * also a failed request, but it costs a full function timeout, carries no
+ * `Retry-After` for a well-behaved client to back off on, and invites an
+ * immediate retry that deepens the contention. Contention on a single key
+ * also means, at nearly every call site, either abuse or a client
+ * double-submitting: the keys are per (host, screen, IP), per uid, or per API
+ * key, so a legitimate visitor essentially never races themselves.
+ *
+ * ## The counter is an atomic increment, not a transaction (AGL-2416)
+ *
+ * It used to be `runTransaction(read count, write count + 1)`. That is
+ * optimistic concurrency on ONE document, so two writers in flight at once
+ * already race: measured in production on 2026-08-19, **two** concurrent
+ * requests on a single fresh key were enough to make a transaction lose,
+ * retry, and blow past its budget. Two is ordinary client behaviour — a
+ * double-submit, a mobile retry, two visitors behind one NAT — and the
+ * documented 120/min per API key is not even reachable without concurrency,
+ * so an integration built to the published budget met this by design.
+ *
+ * `set({count: increment(1)}, {merge: true})` is applied by the server with
+ * no read set to conflict over, so concurrent writers do not abort each
+ * other. The decision then needs the value, which costs a read back — the
+ * same two round trips a transaction spent, and the same billing: one
+ * document read plus one document write.
+ *
+ * **The trade is exactness for headroom, and it is deliberately biased.** The
+ * read-back can observe increments from writers that landed after ours, so
+ * under `C` concurrent requests a caller may see a count up to `C - 1` higher
+ * than its own position. The consequences, precisely:
+ *
+ * - It can only ever refuse EARLY, never late. The count is monotonic within
+ *   a window and always includes this request's own increment, so an admitted
+ *   request is one where at most `limit` increments had landed. The cap can
+ *   never be exceeded, and going concurrent can never widen it.
+ * - "Exactly `limit` admitted" becomes "**at most** `limit` admitted". At the
+ *   window's edge, `C` simultaneous requests can all read the same post-burst
+ *   total and all be refused, so as few as `limit - C + 1` are admitted where
+ *   `limit` would have been. Bounded by the concurrency, confined to one
+ *   window, and in the customer-favourable direction for a *security* limiter
+ *   — which is what all nine of this store's call sites are.
+ * - A fixed-window limiter already admits up to `2 × limit` across a window
+ *   boundary, so exactness was never a property this shape had end to end.
+ * - **A call abandoned on its budget may already have counted.** The write
+ *   lands before the read-back, so a caller that gives up during the read-back
+ *   still spent its increment. The transaction it replaced committed nothing
+ *   when it timed out — which is exactly how AGL-2416 could observe "10
+ *   admitted" after a burst of 504s — so this is a genuine change, not a
+ *   restatement. It errs in the same safe direction: the counter over-counts,
+ *   so the cap still cannot be exceeded, and a caller can never buy budget by
+ *   timing out.
+ *
+ * The failure classification above is unchanged and still load-bearing: the
+ * budget can still elapse on a genuinely slow store, and when it does the
+ * answer is still a refusal rather than a degradation.
+ */ export async function consumeRateLimit(key, options) {
+    var _ref, _ref1, _ref2;
+    const limit = (_ref = options == null ? void 0 : options.limit) != null ? _ref : DEFAULT_RATE_LIMIT;
+    const windowMs = (_ref1 = options == null ? void 0 : options.windowMs) != null ? _ref1 : DEFAULT_RATE_WINDOW_MS;
+    const now = (_ref2 = options == null ? void 0 : options.now) != null ? _ref2 : Date.now();
+    const windowStartMs = Math.floor(now / windowMs) * windowMs;
+    const resetMs = windowStartMs + windowMs;
+    try {
+        var _ref3, _ref4;
+        const firestore = (_ref3 = options == null ? void 0 : options.firestore) != null ? _ref3 : firebaseAdmin.app().firestore();
+        const ref = firestore.collection(RATE_LIMIT_COLLECTION).doc(bucketId(key, windowStartMs));
+        // Explicit type argument: `firestore` is `any`, so the helper's promise
+        // infers as `any` and would widen the counter to `unknown`.
+        const count = await withBudget(countOne(ref, windowStartMs, resetMs, windowMs), (_ref4 = options == null ? void 0 : options.budgetMs) != null ? _ref4 : RATE_LIMIT_TRANSACTION_BUDGET_MS);
+        // The store answered, so any episode this instance was in is over. The
+        // marker is written here rather than in the `catch` because the store is
+        // unreachable exactly while the episode is happening (AGL-1679).
+        if (episode) flushDegradation(firestore, now);
+        return {
+            allowed: count <= limit,
+            limit,
+            remaining: Math.max(0, limit - count),
+            resetMs,
+            degraded: false,
+            contended: false
+        };
+    } catch (error) {
+        if (isContention(error)) {
+            // NOT `noteDegradation`: nothing degraded. The durable counter is still
+            // the only authority and it still holds — this caller simply did not get
+            // a turn. Recording it as a degradation would put contention markers in
+            // front of `/api/health/rate-limits`, whose whole question is "did the
+            // durable store stop answering", and answer it wrongly.
+            //
+            // `resetMs` stays the true end of the window so `X-RateLimit-Reset`
+            // remains honest, which also makes the caller's `Retry-After` a bounded
+            // back-off to the window boundary — the one client behaviour that
+            // actually relieves the contention.
+            return {
+                allowed: false,
+                limit,
+                remaining: 0,
+                resetMs,
+                degraded: false,
+                contended: true
+            };
+        }
+        noteDegradation(now, error);
+        return _extends({}, checkRateLimit(key, {
+            limit,
+            windowMs,
+            now
+        }), {
+            degraded: true,
+            contended: false
+        });
+    }
+}
+export default consumeRateLimit;
+/**
+ * Document id for the signup canary's verdict (AGL-2715).
+ *
+ * One document, not a bucketed series: this records the LAST walk, and a
+ * history of walks answers a question nobody asks during an incident. The
+ * walk that matters is the most recent one.
+ *
+ * Written by the scheduled canary, read by `/api/health/journeys`. The split
+ * is the same one the beacon heartbeat makes and for a stronger reason: the
+ * canary CREATES AN ACCOUNT AND AN ORG, and the door that reports it is
+ * public and unauthenticated. A probe that walked the signup itself would
+ * hand anyone with `curl` an org factory.
+ *
+ * ⚠️ NOT in the `rateLimits` TTL's usual seven-day shape. There is exactly one
+ * of these and it is overwritten on every run, so it costs one document
+ * forever; `expiresAt` is still stamped, far enough out that a canary which
+ * stopped running expires its own evidence rather than leaving a stale pass
+ * lying around to be misread. The health verdict's own staleness window is
+ * two hours, so expiry is a backstop, not the mechanism.
+ */ export const SIGNUP_CANARY_DOC_ID = 'signupCanary_production';
+/** How long a recorded walk survives the sweep. */ const SIGNUP_CANARY_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
+/** Budget for the single-document read on the health path. */ const SIGNUP_CANARY_READ_BUDGET_MS = 2000;
+/**
+ * Record the outcome of one signup walk.
+ *
+ * AWAITED by its caller, unlike every other recorder in this file. Those are
+ * breadcrumbs on a request path where the user's work is the control and the
+ * marker must never delay it. This one IS the work: a canary whose verdict
+ * did not land has not reported, and the door it feeds would rather red on a
+ * missing marker than believe a walk nobody wrote down.
+ *
+ * `set` without merge, deliberately: this document is a snapshot of the last
+ * walk, and merging would let a field from a previous run survive into a
+ * verdict it was not part of — a `failedStep` outliving the failure that
+ * produced it, read beside a fresh `ok: true`.
+ */ export async function recordSignupCanaryWalk(verdict, options) {
+    var _ref, _ref1, _verdict_failedStep;
+    const nowMs = (_ref = options == null ? void 0 : options.now) != null ? _ref : Date.now();
+    const firestore = (_ref1 = options == null ? void 0 : options.firestore) != null ? _ref1 : firebaseAdmin.app().firestore();
+    await firestore.collection(RATE_LIMIT_COLLECTION).doc(SIGNUP_CANARY_DOC_ID).set({
+        walkedAtMs: nowMs,
+        ok: verdict.ok === true,
+        failedStep: (_verdict_failedStep = verdict.failedStep) != null ? _verdict_failedStep : null,
+        elapsedMs: Number(verdict.elapsedMs) || 0,
+        reapedCleanly: verdict.reapedCleanly === true,
+        expiresAt: new Date(nowMs + SIGNUP_CANARY_RETENTION_MS)
+    });
+}
+/**
+ * The last recorded walk, or null (AGL-2715).
+ *
+ * Null covers the same three cases `readBeaconHeartbeat` folds, for the same
+ * reason: no marker has ever been written, the document holds nothing usable,
+ * and the store would not answer inside its budget. Each one means *nothing
+ * here has demonstrated that a stranger can sign up*, and the verdict grades
+ * all three as `canary-unavailable`. Distinguishing them could only ever be
+ * used to forgive something unproven.
+ */ export async function readSignupCanaryWalk(options) {
+    try {
+        var _ref, _ref1, _snapshot_get;
+        const firestore = (_ref = options == null ? void 0 : options.firestore) != null ? _ref : firebaseAdmin.app().firestore();
+        const snapshot = await withBudget(firestore.collection(RATE_LIMIT_COLLECTION).doc(SIGNUP_CANARY_DOC_ID).get(), (_ref1 = options == null ? void 0 : options.budgetMs) != null ? _ref1 : SIGNUP_CANARY_READ_BUDGET_MS);
+        if (!(snapshot == null ? void 0 : snapshot.exists)) return null;
+        const walkedAtMs = snapshot.get('walkedAtMs');
+        if (typeof walkedAtMs !== 'number' || !Number.isFinite(walkedAtMs)) return null;
+        return {
+            walkedAtMs,
+            ok: snapshot.get('ok') === true,
+            failedStep: (_snapshot_get = snapshot.get('failedStep')) != null ? _snapshot_get : null,
+            elapsedMs: snapshot.get('elapsedMs'),
+            reapedCleanly: snapshot.get('reapedCleanly')
+        };
+    } catch (unused) {
+        return null;
+    }
+}
+/**
+ * Document id for the App Check attestation sample (AGL-2715).
+ *
+ * The rate is published by Google to Cloud Monitoring, which a public health
+ * endpoint has no business calling: it needs a second credential, it is slow,
+ * and its quota is not something a route anyone can curl should be able to
+ * spend. So a scheduled job samples it and this holds the answer, exactly as
+ * the signup canary's own verdict is held.
+ *
+ * One document, overwritten each run — the last reading is the only one that
+ * answers "is attestation working now".
+ */ /**
+ * Where the metered-traffic sampler leaves its reading (AGL-2720).
+ *
+ * One document, like every sibling here. The sampler owns the judgement about
+ * whether the total moved; this file only carries it.
+ */ export const EDGE_ADMISSION_DOC_ID = 'edgeAdmission_production';
+/** Budget for the single-document read on the health path. */ const EDGE_ADMISSION_READ_BUDGET_MS = 2000;
+/**
+ * Read the last metered-traffic sample.
+ *
+ * Deliberately has NO max-age rejection, which is the one place this differs
+ * from {@link readAppCheckAttestation}. The quantity graded is already an age
+ * — how long since traffic moved — so discarding an old marker would turn the
+ * loudest possible reading into `edge-admission-unavailable` and lose which
+ * of the two things broke.
+ */ export async function readEdgeAdmission(options) {
+    try {
+        var _ref, _ref1;
+        const firestore = (_ref = options == null ? void 0 : options.firestore) != null ? _ref : firebaseAdmin.app().firestore();
+        const snapshot = await withBudget(firestore.collection(RATE_LIMIT_COLLECTION).doc(EDGE_ADMISSION_DOC_ID).get(), (_ref1 = options == null ? void 0 : options.budgetMs) != null ? _ref1 : EDGE_ADMISSION_READ_BUDGET_MS);
+        if (!(snapshot == null ? void 0 : snapshot.exists)) return null;
+        const advancedAtMs = snapshot.get('advancedAtMs');
+        if (typeof advancedAtMs !== 'number') return null;
+        return {
+            sampledAtMs: snapshot.get('sampledAtMs'),
+            advancedAtMs,
+            day: snapshot.get('day'),
+            total: snapshot.get('total')
+        };
+    } catch (unused) {
+        return null;
+    }
+}
+export const APP_CHECK_ATTESTATION_DOC_ID = 'appCheckAttestation_production';
+/** How long a sample survives the sweep. */ const APP_CHECK_ATTESTATION_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
+/** Budget for the single-document read on the health path. */ const APP_CHECK_ATTESTATION_READ_BUDGET_MS = 2000;
+/**
+ * Record one sampling of the App Check verification counts.
+ *
+ * Awaited by its caller, like the canary's verdict and unlike the breadcrumbs
+ * in this file: the sample IS the work, and a door would rather report a
+ * missing reading than believe one nobody wrote down.
+ */ export async function recordAppCheckAttestation(samples, options) {
+    var _ref, _ref1;
+    const nowMs = (_ref = options == null ? void 0 : options.now) != null ? _ref : Date.now();
+    const firestore = (_ref1 = options == null ? void 0 : options.firestore) != null ? _ref1 : firebaseAdmin.app().firestore();
+    await firestore.collection(RATE_LIMIT_COLLECTION).doc(APP_CHECK_ATTESTATION_DOC_ID).set({
+        sampledAtMs: nowMs,
+        samples,
+        expiresAt: new Date(nowMs + APP_CHECK_ATTESTATION_RETENTION_MS)
+    });
+}
+/**
+ * The last attestation sample, or null (AGL-2715).
+ *
+ * Null folds the three cases its siblings fold — never written, unusable, and
+ * the store would not answer — because each means *nothing here has shown that
+ * attestation is working*, and the verdict grades all three as
+ * `attestation-unavailable`.
+ *
+ * A sample older than the window it describes is also null. A stale reading is
+ * not a reading: reporting a six-hour-old rate as current is how a check comes
+ * to say attestation is fine long after it stopped being.
+ */ export async function readAppCheckAttestation(options) {
+    try {
+        var _ref, _ref1, _ref2, _ref3;
+        const firestore = (_ref = options == null ? void 0 : options.firestore) != null ? _ref : firebaseAdmin.app().firestore();
+        const snapshot = await withBudget(firestore.collection(RATE_LIMIT_COLLECTION).doc(APP_CHECK_ATTESTATION_DOC_ID).get(), (_ref1 = options == null ? void 0 : options.budgetMs) != null ? _ref1 : APP_CHECK_ATTESTATION_READ_BUDGET_MS);
+        if (!(snapshot == null ? void 0 : snapshot.exists)) return null;
+        const sampledAtMs = snapshot.get('sampledAtMs');
+        if (typeof sampledAtMs !== 'number') return null;
+        const nowMs = (_ref2 = options == null ? void 0 : options.now) != null ? _ref2 : Date.now();
+        // Twice the window it covers: one missed sampling is tolerated, two are
+        // not, and the reading still describes a period that overlaps now.
+        const maxAgeMs = (_ref3 = options == null ? void 0 : options.maxAgeMs) != null ? _ref3 : 12 * 60 * 60 * 1000;
+        if (nowMs - sampledAtMs > maxAgeMs) return null;
+        const samples = snapshot.get('samples');
+        return Array.isArray(samples) ? samples : null;
+    } catch (unused) {
+        return null;
+    }
+}
+
+//# sourceMappingURL=rate-limit-store.js.map