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

package/src/lib/server/rate-limit-store.d.ts

@@ -0,0 +1,702 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { type RateLimitResult } from './api-http';
+/**
+ * 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 declare 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 declare const DEGRADATION_DOC_PREFIX = "degraded_";
+interface DegradationEpisode {
+    /** Calls that fell back to the in-process limiter. */
+    count: number;
+    firstAtMs: number;
+    lastAtMs: number;
+    /** Last failure's code/message, truncated. */
+    code: string;
+    /** Last minute we logged, so a sustained outage cannot flood the log. */
+    lastLoggedBucket: number;
+}
+/**
+ * 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 declare function currentRateLimitDegradation(): Readonly<DegradationEpisode> | null;
+/** Test seam: forget any in-progress episode. */
+export declare function resetRateLimitDegradationForTests(): void;
+/**
+ * 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 declare const SIGNUP_REFUSAL_DOC_PREFIX = "signupRefused_";
+/**
+ * What refused. Bounded on purpose — this is a public health body.
+ *
+ * `uid` and `ip` are this limiter's two caps. `locked` and `unreadable` are
+ * written by the `beforeUserCreated` blocking function in `cloud/functions`,
+ * which refuses on the Identity Platform path before any Aglyn route runs
+ * and therefore never reaches `consumeRateLimit` (AGL-2583). It cannot import
+ * this module — it is a plain npm package outside the workspace — so it
+ * writes the same document shape by hand and
+ * `apps/console/specs/signup-refusal-marker-wiring.spec.ts` fails if the two
+ * ever disagree about the collection, the prefix or the fields.
+ */
+export type SignupRefusalReason = 'uid' | 'ip' | 'locked' | 'unreadable';
+/**
+ * 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 declare function recordSignupRefusal(reason: SignupRefusalReason, options?: {
+    now?: number;
+    firestore?: any;
+}): void;
+/**
+ * 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 declare const SERVER_ERROR_DOC_PREFIX = "serverError_";
+/**
+ * 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 declare function recordServerError(service: string, options?: {
+    now?: number;
+    firestore?: any;
+}): void;
+/**
+ * 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 declare function pendingServerErrors(): number;
+/** Test seam: forget anything held. */
+export declare function resetServerErrorsForTests(): void;
+/**
+ * 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 declare const BEACON_HEARTBEAT_DOC_PREFIX = "beaconHeartbeat_";
+/**
+ * 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 declare function recordBeaconHeartbeat(service: string, options?: {
+    now?: number;
+    firestore?: any;
+}): void;
+/**
+ * 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 declare function readBeaconHeartbeat(service: string, options?: {
+    firestore?: any;
+    budgetMs?: number;
+}): Promise<number | 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 declare const SIGNUP_SERVED_DOC_PREFIX = "signupServed_";
+/**
+ * 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 declare function recordSignupServed(options?: {
+    now?: number;
+    firestore?: any;
+}): void;
+/**
+ * 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 declare function pendingSignupServes(): number;
+/** Test seam: forget anything held. */
+export declare function resetSignupServesForTests(): void;
+/**
+ * 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 declare const SIGNUP_ATTEMPT_DOC_PREFIX = "signupAttempted_";
+/**
+ * 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 declare function recordSignupAttempt(options?: {
+    now?: number;
+    firestore?: any;
+}): void;
+/**
+ * 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 declare 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 declare class RateLimitContentionError extends Error {
+    constructor(message?: string);
+}
+export interface DurableRateLimitOptions {
+    limit?: number;
+    windowMs?: number;
+    now?: number;
+    /** Injectable for tests; defaults to the Admin SDK's Firestore. */
+    firestore?: any;
+    /** Injectable for tests; defaults to {@link RATE_LIMIT_TRANSACTION_BUDGET_MS}. */
+    budgetMs?: number;
+}
+export interface DurableRateLimitResult extends RateLimitResult {
+    /**
+     * True when the durable store was unreachable and the in-memory limiter
+     * answered instead — the cap held for this instance only.
+     */
+    degraded: boolean;
+    /**
+     * True when the counter could not be read and written inside its budget
+     * because the key is contended, and the request was refused on that basis
+     * rather than on a counted overage (AGL-2404). Always `false` on an
+     * allowed result.
+     */
+    contended: boolean;
+}
+/**
+ * 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 declare function consumeRateLimit(key: string, options?: DurableRateLimitOptions): Promise<DurableRateLimitResult>;
+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 declare const SIGNUP_CANARY_DOC_ID = "signupCanary_production";
+export interface SignupCanaryVerdict {
+    /** Whether every step of the walk succeeded. */
+    ok: boolean;
+    /** Which step broke. Never an error message, never a uid or an email. */
+    failedStep?: string | null;
+    /** Wall clock for the whole walk. */
+    elapsedMs: number;
+    /** Whether the walk deleted everything it created. */
+    reapedCleanly: boolean;
+}
+/**
+ * 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 declare function recordSignupCanaryWalk(verdict: SignupCanaryVerdict, options?: {
+    now?: number;
+    firestore?: any;
+}): Promise<void>;
+/**
+ * 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 declare function readSignupCanaryWalk(options?: {
+    firestore?: any;
+    budgetMs?: number;
+}): Promise<{
+    walkedAtMs?: number;
+    ok?: boolean;
+    failedStep?: string | null;
+    elapsedMs?: number;
+    reapedCleanly?: boolean;
+} | 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 declare const EDGE_ADMISSION_DOC_ID = "edgeAdmission_production";
+/**
+ * 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 declare function readEdgeAdmission(options?: {
+    firestore?: any;
+    budgetMs?: number;
+}): Promise<{
+    sampledAtMs?: number;
+    advancedAtMs?: number;
+    day?: string;
+    total?: number;
+} | null>;
+export declare const APP_CHECK_ATTESTATION_DOC_ID = "appCheckAttestation_production";
+/**
+ * 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 declare function recordAppCheckAttestation(samples: Array<{
+    result?: string;
+    security?: string;
+    service?: string;
+    count?: number;
+}>, options?: {
+    now?: number;
+    firestore?: any;
+}): Promise<void>;
+/**
+ * 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 declare function readAppCheckAttestation(options?: {
+    firestore?: any;
+    budgetMs?: number;
+    now?: number;
+    maxAgeMs?: number;
+}): Promise<Array<{
+    result?: string;
+    security?: string;
+    service?: string;
+    count?: number;
+}> | null>;