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

package/src/lib/server/vercel-log-drain.js

@@ -0,0 +1,479 @@
+/**
+ * @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.
+ */ /**
+ * The Vercel log-drain receiver (AGL-1921, third and last arm).
+ *
+ * ## Why this arm exists at all
+ *
+ * The two arms already shipped both start from OUR code running. The
+ * `onRequestError` hook (`reportServerError`) sees a render or route handler
+ * throw; `/api/health/server-errors` grades the markers that hook writes.
+ * Neither can see:
+ *
+ * - an error that kills the process before the hook runs,
+ * - a platform-level 5xx that never reaches our code at all — a function
+ *   timeout, an OOM kill, a cold-start 502,
+ * - anything thrown in the edge runtime.
+ *
+ * A log drain sees all three, because Vercel emits the request log whether or
+ * not our code got far enough to have an opinion. That is why this is the arm
+ * that closes the issue rather than a fourth partial view.
+ *
+ * ## The shape of the risk, and what each rule below buys
+ *
+ * A drain streams EVERY request log for both projects. The account's whole
+ * monitoring budget is about $20/month, so the dangerous failure mode here is
+ * not missing an error — it is faithfully forwarding a million healthy 200s
+ * into Cloud Logging and getting a bill for it. Hence, in order:
+ *
+ * 1. **Signature first, fail closed.** HMAC-SHA1 of the RAW body keyed by the
+ *    drain secret, timing-safe compared. Unsigned means unwritten, always.
+ * 2. **Filter before writing.** `isServerErrorEntry` is the cost gate: an
+ *    entry that is not a server error costs one predicate and zero writes.
+ * 3. **Never our own route.** See `RECEIVER_ROUTE_PATH`.
+ * 4. **Never a deliberate 5xx.** A 503 is how the lockdown notice and every
+ *    health contract SAY something, and forwarding a verdict as a fault makes
+ *    the stream unreadable: measured over the 48 hours to 2026-09-09, 229 of
+ *    the 251 entries in this log were `/api/health/*` reporting degraded and
+ *    22 were the only real outage in the window. See `isLockdownNoticeEntry`
+ *    and `isHealthContractEntry` (AGL-2709).
+ * 5. **A per-instance budget per window**, with suppression REPORTED. A
+ *    monitoring path that hides its own lossiness is the bug shape this repo
+ *    keeps rediscovering.
+ *
+ * ## Where it writes, and why not next door
+ *
+ * `vercel-runtime`, DELIBERATELY NOT `server-errors`. That log is the
+ * `onRequestError` hook's, and the alert policy
+ * `projects/aglyn-main/alertPolicies/11610705614308437855` keys on it. A 500
+ * our code threw is seen by BOTH arms, so merging the streams would count one
+ * incident twice and make triage start by asking which arm saw it. The same
+ * separation `client-errors` and `server-errors` already keep, for the same
+ * reason.
+ *
+ * The entries carry a real `httpRequest.status`, which is what makes the
+ * policy AGL-1921 originally specified — a log filter on logName matching
+ * "vercel" and httpRequest.status at or above 500 — expressible without a
+ * log-based metric on a jsonPayload field first.
+ */ /**
+ * LAZY, and that is load-bearing rather than stylistic (AGL-1921, 2026-08-26).
+ *
+ * `client-error-report` reaches `firebase-admin`. A static import here would
+ * pull the whole SDK into anything that bundles this module — including the
+ * Cloud Run receiver, whose entire reason for existing is to run this gate
+ * OFF Vercel with nothing but `node:crypto` and a metadata-server token. That
+ * receiver always supplies its own {@link DrainIngestOptions.target}, so this
+ * path is never reached there and the SDK is never resolved.
+ *
+ * Called through `defaultLoggingTarget` below, never at module scope.
+ */ async function defaultLoggingTarget() {
+    const { beaconLoggingTarget } = await import("./client-error-report.js");
+    return beaconLoggingTarget();
+}
+/**
+ * The log id the drain writes to. Contains "vercel" on purpose: the alert
+ * policy `projects/aglyn-main/alertPolicies/14031689508473384486` matches
+ * `logName=~"vercel"`, so the name is load-bearing. Renaming this log without
+ * repointing that policy silences the platform-5xx arm.
+ */ export const VERCEL_RUNTIME_LOG_ID = 'vercel-runtime';
+/** The env var holding the drain's signature secret. Fails closed if unset. */ export const DRAIN_SECRET_ENV = 'VERCEL_LOG_DRAIN_SECRET';
+/**
+ * The receiver's own path — the FEEDBACK-LOOP GUARD (requirement 5).
+ *
+ * ⚠️ HISTORICAL, AND KEPT AS DEFENCE IN DEPTH (2026-08-26). The receiver USED
+ * to run on `aglyn-console`, whose logs the console drain collects, and the
+ * two cuts below were the answer to one receiver 500 draining back in.
+ *
+ * They were not enough, and the reason is worth stating plainly because the
+ * docstring that used to live here got it wrong: **both cuts are about the
+ * WRITE, and the cost was the DELIVERY.** Nothing inside a receiver can
+ * decline to be requested, and every delivery POST is itself a request that
+ * produces a log the same drain then delivers. Measured at 695K invocations
+ * in nine hours. Vercel's drain `sampling` rules are not a fix either — a
+ * single `{rate: 0}` rule with no path prefix moved delivery volume from 31
+ * to 32 per five minutes, i.e. the whole `schemas.log` filter block is stored
+ * and never applied.
+ *
+ * The receiver now lives OFF Vercel, at `cloud/log-drain` on Cloud Run, which
+ * no drain watches — so the loop is structurally impossible rather than
+ * filtered against. These cuts stay because they cost nothing and they are
+ * the backstop if anyone ever mounts this gate on a Vercel route again.
+ *
+ * Two structural cuts, not one:
+ *
+ * a. Every entry whose path is this route is dropped before the 5xx filter —
+ *    so even the receiver's OWN 500s can never be forwarded, by anything, at
+ *    any budget. It is not "we try not to error"; it is that its errors are
+ *    unforwardable.
+ * b. Every line this module logs about itself is `console.warn`, i.e. Vercel
+ *    `level: "warning"`, and the filter forwards only 5xx and `fatal`. A
+ *    suppression summary drained back in is therefore dropped a second time,
+ *    on a different property, by a different rule.
+ *
+ * Matched as a PREFIX so `/api/log-drain`, a future `/api/log-drain/test` and
+ * the query-bearing `proxy.path` form all fall on the same side of it.
+ */ export const RECEIVER_ROUTE_PATH = '/api/log-drain';
+/**
+ * The lockdown notice route — a route whose 503 is the FEATURE, not a fault.
+ *
+ * `apps/tenant/app/api/locked/route.ts` answers every request with a real 503
+ * carrying `Retry-After`, and the middleware rewrites every path of a locked
+ * or bandwidth-capped host to it. That status is deliberate: a takedown
+ * notice answering 200 would tell crawlers and uptime checks the site is
+ * fine, which is the whole reason the notice is a route handler rather than a
+ * page.
+ *
+ * Forwarded, it is indistinguishable from an outage. One suspended host being
+ * crawled emits a 5xx per request, forever, into the arm whose only consumer
+ * is an alert policy — so the policy fires on a working feature and the next
+ * real incident arrives in a stream that is already red.
+ *
+ * Matched EXACTLY, not as a prefix: the notice is one path, and a future
+ * `/api/locked/*` would be a different route with no such guarantee about its
+ * status.
+ */ export const LOCKDOWN_NOTICE_ROUTE_PATH = '/api/locked';
+/**
+ * Per-instance write budget, mirroring `reportServerError`'s (same file
+ * neighbourhood, same rationale): the failure being watched is a SPIKE, and a
+ * spike is when an unbounded forwarder turns one incident into a second one
+ * denominated in dollars. 60 entries a minute per instance is far more than
+ * any threshold policy needs to cross — the shape of the spike survives; the
+ * bill does not follow it.
+ */ const DRAIN_BUDGET_PER_WINDOW = 60;
+const DRAIN_WINDOW_MS = 60000;
+let drainWindowStartedAt = 0;
+let drainWritten = 0;
+let drainSuppressed = 0;
+const MAX_MESSAGE = 1024;
+const WRITE_TIMEOUT_MS = 4000;
+/** Reset the budget counters. Test seam only — never called in production. */ export function resetDrainBudgetForTests() {
+    drainWindowStartedAt = 0;
+    drainWritten = 0;
+    drainSuppressed = 0;
+}
+function clampString(value, max) {
+    return typeof value === 'string' ? value.slice(0, max) : '';
+}
+/**
+ * The entries in one delivery, in either format Vercel will send.
+ *
+ * `json` delivers an array (and, per the reference's own example, sometimes a
+ * newline-separated sequence of objects); `ndjson` delivers one object per
+ * line. Parsing both means the drain's `deliveryFormat` can be changed in the
+ * dashboard without a deploy, and a malformed line is skipped rather than
+ * failing the whole delivery — Vercel disables a drain that errors too often,
+ * so a receiver that 500s on one bad line silences itself.
+ */ export function parseDrainPayload(rawBody) {
+    const body = rawBody.trim();
+    if (!body) return [];
+    try {
+        const parsed = JSON.parse(body);
+        if (Array.isArray(parsed)) {
+            return parsed.filter((entry)=>Boolean(entry) && typeof entry === 'object');
+        }
+        if (parsed && typeof parsed === 'object') return [
+            parsed
+        ];
+    } catch (unused) {
+    // Not a single JSON document — fall through to line-by-line.
+    }
+    const entries = [];
+    for (const line of body.split('\n')){
+        const trimmed = line.trim();
+        if (!trimmed) continue;
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                entries.push(parsed);
+            }
+        } catch (unused) {
+        // One unreadable line never fails a delivery.
+        }
+    }
+    return entries;
+}
+/** Does this entry describe the receiver's own route? See RECEIVER_ROUTE_PATH. */ export function isReceiverEntry(entry) {
+    var _entry_proxy;
+    const paths = [
+        entry.path,
+        (_entry_proxy = entry.proxy) == null ? void 0 : _entry_proxy.path
+    ];
+    return paths.some((path)=>{
+        if (typeof path !== 'string') return false;
+        // `proxy.path` carries the query string; compare the path part only.
+        const [pathname] = path.split('?');
+        return pathname === RECEIVER_ROUTE_PATH || pathname.startsWith(`${RECEIVER_ROUTE_PATH}/`);
+    });
+}
+/**
+ * Is this the lockdown notice serving its deliberate 503? See
+ * {@link LOCKDOWN_NOTICE_ROUTE_PATH}.
+ *
+ * Narrow on purpose — the route being exempt must not make the route
+ * unwatchable. Only a clean 503 is excused: a 500 the handler threw, the
+ * `statusCode -1` of a crashed lambda, and a `fatal` line all still forward,
+ * because those say the notice itself is broken and a locked host is then
+ * serving nothing at all.
+ */ export function isLockdownNoticeEntry(entry) {
+    var _entry_proxy, _entry_proxy1;
+    if (entry.level === 'fatal' || entry.type === 'fatal') return false;
+    const statuses = [
+        entry.statusCode,
+        (_entry_proxy = entry.proxy) == null ? void 0 : _entry_proxy.statusCode
+    ].filter((status)=>typeof status === 'number');
+    if (!statuses.length || statuses.some((status)=>status !== 503)) return false;
+    return [
+        entry.path,
+        (_entry_proxy1 = entry.proxy) == null ? void 0 : _entry_proxy1.path
+    ].some((path)=>{
+        if (typeof path !== 'string') return false;
+        // `proxy.path` carries the query string; compare the path part only.
+        const [pathname] = path.split('?');
+        return pathname === LOCKDOWN_NOTICE_ROUTE_PATH;
+    });
+}
+/**
+ * The health contract's routes, whose 503 is a VERDICT and not a fault.
+ *
+ * Prefix, not an exact path: every endpoint under it speaks the same contract
+ * — `healthHttpStatus` answers 200 while a check reports ok and 503 the moment
+ * it reports degraded — so `/api/health`, `/api/health/crons` and
+ * `/api/health/render/site` are all the same case.
+ */ export const HEALTH_ROUTE_PREFIX = '/api/health';
+/**
+ * Is this a health endpoint answering 503 because it is doing its job?
+ * (AGL-2709)
+ *
+ * ⚠️ THE STREAM WAS 91% THIS. Measured over the 48 hours to 2026-09-09, the
+ * drain forwarded 251 entries into `vercel-runtime`. **229 were `/api/health/*`
+ * answering 503** — `crons` 113, `funnel` 73, `server-errors` 18 — and 22 were
+ * the AGL-2708 outage, the only real server errors in the window. The policy
+ * on that log (`logName=~"vercel" AND severity>=ERROR`, one notification an
+ * hour) therefore mails about a working health check for as long as any
+ * subsystem is degraded: `/api/health/crons` was CORRECTLY reporting a broken
+ * job for six hours on 2026-09-07, which is six hours of "server errors" mail
+ * arriving in the same inbox that then had to notice 04:02 on 2026-09-09.
+ *
+ * Excusing it removes a DUPLICATE, not a signal, and the reason is structural
+ * rather than a judgement call: every `/api/health/*` route both apps ship has
+ * a monitor reading it, and `evaluateSubsystemReaders` fails the build if one
+ * ever does not. The 503 is already on the uptime probe's board, in an
+ * UptimeRobot monitor and on `docs.aglyn.com/status`, said in a body that
+ * names WHICH check failed — which the drain entry never could.
+ *
+ * Narrow in exactly the same three ways as {@link isLockdownNoticeEntry}, and
+ * each one is load-bearing:
+ *
+ *  - a clean 503 only. A 500 the handler threw means the health route itself
+ *    is broken, and a check that cannot answer must never look calm;
+ *  - never a `fatal` line, which is process death rather than a verdict;
+ *  - never `statusCode -1`, the crashed-lambda sentinel, which is not 503 and
+ *    so fails the status test above.
+ */ export function isHealthContractEntry(entry) {
+    var _entry_proxy, _entry_proxy1;
+    if (entry.level === 'fatal' || entry.type === 'fatal') return false;
+    const statuses = [
+        entry.statusCode,
+        (_entry_proxy = entry.proxy) == null ? void 0 : _entry_proxy.statusCode
+    ].filter((status)=>typeof status === 'number');
+    if (!statuses.length || statuses.some((status)=>status !== 503)) return false;
+    return [
+        entry.path,
+        (_entry_proxy1 = entry.proxy) == null ? void 0 : _entry_proxy1.path
+    ].some((path)=>{
+        if (typeof path !== 'string') return false;
+        // `proxy.path` carries the query string; compare the path part only.
+        const [pathname] = path.split('?');
+        return pathname === HEALTH_ROUTE_PREFIX || pathname.startsWith(`${HEALTH_ROUTE_PREFIX}/`);
+    });
+}
+/**
+ * THE COST GATE (requirement 3). Everything false here is dropped unwritten.
+ *
+ * What counts as a server error:
+ *
+ * - `statusCode >= 500` or `proxy.statusCode >= 500` — the platform 5xx this
+ *   whole arm exists for, including the ones our code never saw.
+ * - `statusCode === -1` — documented as "no response returned and the lambda
+ *   crashed". The OOM/hard-crash case, and the single most important entry
+ *   shape the `onRequestError` hook is structurally unable to produce.
+ * - `level === 'fatal'` or `type === 'fatal'` — the edge-runtime and
+ *   process-death shape, which may carry no status at all.
+ *
+ * What deliberately does NOT count:
+ *
+ * - `level === 'error'`. That is any `console.error`, including the fail-soft
+ *   warn/error lines the beacons themselves write, and forwarding it would
+ *   mean paying per line for a stream the `onRequestError` hook already
+ *   covers properly. If an errored request matters, it has a status.
+ * - `proxy.statusCode === -1`. Same sentinel, opposite meaning: on the proxy
+ *   object it documents a BACKGROUND REVALIDATION, which is a healthy ISR
+ *   refresh. Reading it as a crash would forward a steady trickle of normal
+ *   traffic forever — the exact bill this gate exists to prevent.
+ */ export function isServerErrorEntry(entry) {
+    var _entry_proxy;
+    if (typeof entry.statusCode === 'number') {
+        if (entry.statusCode >= 500) return true;
+        if (entry.statusCode === -1) return true;
+    }
+    const proxyStatus = (_entry_proxy = entry.proxy) == null ? void 0 : _entry_proxy.statusCode;
+    if (typeof proxyStatus === 'number' && proxyStatus >= 500) return true;
+    if (entry.level === 'fatal' || entry.type === 'fatal') return true;
+    return false;
+}
+/**
+ * Everything above, in the order the cost argument requires.
+ * Exported so the tests can assert the gate without a transport.
+ */ export function selectForwardableEntries(entries) {
+    return entries.filter((entry)=>!isReceiverEntry(entry) && !isLockdownNoticeEntry(entry) && !isHealthContractEntry(entry) && isServerErrorEntry(entry));
+}
+/**
+ * One Cloud Logging entry, carrying ONLY fields that are already inside the
+ * envelope the shipped beacons send (requirement 8).
+ *
+ * Explicitly absent, and each for a reason:
+ * `proxy.path` (query string — the AGL-1538 boundary is origin+pathname and
+ * this is the same boundary), `proxy.clientIp` and `proxy.userAgent` and
+ * `proxy.referer` (visitor identity; also why Vercel's own IP-visibility
+ * toggle exists), request or response bodies (never delivered, never wanted).
+ * `path` IS forwarded because Vercel documents it as the function or dynamic
+ * path — the route PATTERN, which is what you group and alert on anyway, and
+ * exactly what `reportServerError` already sends as `route`.
+ */ function toLogEntry(entry) {
+    var _entry_proxy, _entry_proxy1, _entry_proxy2;
+    const status = typeof entry.statusCode === 'number' && entry.statusCode >= 0 ? entry.statusCode : typeof ((_entry_proxy = entry.proxy) == null ? void 0 : _entry_proxy.statusCode) === 'number' && entry.proxy.statusCode >= 0 ? entry.proxy.statusCode : undefined;
+    return {
+        severity: 'ERROR',
+        // The structured field the AGL-1921 policy matches on. A jsonPayload key
+        // would need a log-based metric first; this one is queryable as shipped.
+        httpRequest: {
+            requestMethod: clampString((_entry_proxy1 = entry.proxy) == null ? void 0 : _entry_proxy1.method, 16) || undefined,
+            status
+        },
+        jsonPayload: {
+            // No ReportedErrorEvent `@type`: these are NOT ingested into Error
+            // Reporting. A function timeout has no stack, would group as one giant
+            // bucket, and would drown the real grouped errors the hook reports.
+            source: clampString(entry.source, 32) || undefined,
+            level: clampString(entry.level, 16) || undefined,
+            type: clampString(entry.type, 32) || undefined,
+            route: clampString(entry.path, 512) || undefined,
+            entrypoint: clampString(entry.entrypoint, 256) || undefined,
+            host: clampString(entry.host, 256) || undefined,
+            environment: clampString(entry.environment, 32) || undefined,
+            region: clampString(entry.executionRegion, 32) || undefined,
+            project: clampString(entry.projectName, 64) || undefined,
+            projectId: clampString(entry.projectId, 64) || undefined,
+            deploymentId: clampString(entry.deploymentId, 64) || undefined,
+            requestId: clampString(entry.requestId, 64) || undefined,
+            logId: clampString(entry.id, 64) || undefined,
+            statusCode: typeof entry.statusCode === 'number' ? entry.statusCode : undefined,
+            proxyStatusCode: typeof ((_entry_proxy2 = entry.proxy) == null ? void 0 : _entry_proxy2.statusCode) === 'number' ? entry.proxy.statusCode : undefined,
+            // Clamped like the beacon's own message. This is where "Task timed out
+            // after 10.01 seconds" lives, which is the whole triage value of the
+            // platform-5xx case.
+            message: clampString(entry.message, MAX_MESSAGE) || undefined
+        }
+    };
+}
+/**
+ * Ingest ONE verified delivery: filter, budget, then a single batched write.
+ *
+ * Never throws. Vercel disables a drain whose endpoint fails often enough, so
+ * a receiver that propagated a Logging outage would end by turning itself off
+ * during the incident it exists to report.
+ */ export async function ingestDrainDelivery(entries, options) {
+    var _ref;
+    const received = entries.length;
+    const matched = selectForwardableEntries(entries);
+    const result = {
+        received,
+        matched: matched.length,
+        forwarded: 0,
+        suppressed: 0
+    };
+    if (!matched.length) return result;
+    const now = Date.now();
+    if (now - drainWindowStartedAt >= DRAIN_WINDOW_MS) {
+        if (drainSuppressed > 0) {
+            // ⚠️ The lossiness is REPORTED. `level: "warning"`, so guard (b) in
+            // RECEIVER_ROUTE_PATH keeps this line from ever draining back in.
+            console.warn(JSON.stringify({
+                tag: 'AGL-1921:vercel-log-drain',
+                suppressed: drainSuppressed,
+                written: drainWritten,
+                windowMs: DRAIN_WINDOW_MS
+            }));
+        }
+        drainWindowStartedAt = now;
+        drainWritten = 0;
+        drainSuppressed = 0;
+    }
+    const room = Math.max(0, DRAIN_BUDGET_PER_WINDOW - drainWritten);
+    const writable = matched.slice(0, room);
+    const suppressed = matched.length - writable.length;
+    if (suppressed > 0) drainSuppressed += suppressed;
+    result.suppressed = suppressed;
+    if (!writable.length) return result;
+    const target = await ((_ref = options == null ? void 0 : options.target) != null ? _ref : defaultLoggingTarget)();
+    if (!target) {
+        console.warn(JSON.stringify({
+            tag: 'AGL-1921:vercel-log-drain',
+            drop: writable.length,
+            reason: 'no-credential'
+        }));
+        result.code = 'no-credential';
+        return result;
+    }
+    try {
+        const response = await fetch('https://logging.googleapis.com/v2/entries:write', {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${target.token}`,
+                'Content-Type': 'application/json'
+            },
+            body: JSON.stringify({
+                logName: `projects/${target.projectId}/logs/${VERCEL_RUNTIME_LOG_ID}`,
+                resource: {
+                    type: 'global'
+                },
+                entries: writable.map(toLogEntry)
+            }),
+            signal: AbortSignal.timeout(WRITE_TIMEOUT_MS)
+        });
+        if (!response.ok) {
+            console.warn(JSON.stringify({
+                tag: 'AGL-1921:vercel-log-drain',
+                status: response.status,
+                drop: writable.length
+            }));
+            result.code = `http-${response.status}`;
+            return result;
+        }
+        drainWritten += writable.length;
+        result.forwarded = writable.length;
+        return result;
+    } catch (error) {
+        console.warn(JSON.stringify({
+            tag: 'AGL-1921:vercel-log-drain',
+            transport: String(error).slice(0, 200)
+        }));
+        result.code = 'transport';
+        return result;
+    }
+}
+
+//# sourceMappingURL=vercel-log-drain.js.map

package/src/lib/server/vercel-log-drain.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/vercel-log-drain.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * The Vercel log-drain receiver (AGL-1921, third and last arm).\n *\n * ## Why this arm exists at all\n *\n * The two arms already shipped both start from OUR code running. The\n * `onRequestError` hook (`reportServerError`) sees a render or route handler\n * throw; `/api/health/server-errors` grades the markers that hook writes.\n * Neither can see:\n *\n * - an error that kills the process before the hook runs,\n * - a platform-level 5xx that never reaches our code at all — a function\n *   timeout, an OOM kill, a cold-start 502,\n * - anything thrown in the edge runtime.\n *\n * A log drain sees all three, because Vercel emits the request log whether or\n * not our code got far enough to have an opinion. That is why this is the arm\n * that closes the issue rather than a fourth partial view.\n *\n * ## The shape of the risk, and what each rule below buys\n *\n * A drain streams EVERY request log for both projects. The account's whole\n * monitoring budget is about $20/month, so the dangerous failure mode here is\n * not missing an error — it is faithfully forwarding a million healthy 200s\n * into Cloud Logging and getting a bill for it. Hence, in order:\n *\n * 1. **Signature first, fail closed.** HMAC-SHA1 of the RAW body keyed by the\n *    drain secret, timing-safe compared. Unsigned means unwritten, always.\n * 2. **Filter before writing.** `isServerErrorEntry` is the cost gate: an\n *    entry that is not a server error costs one predicate and zero writes.\n * 3. **Never our own route.** See `RECEIVER_ROUTE_PATH`.\n * 4. **Never a deliberate 5xx.** A 503 is how the lockdown notice and every\n *    health contract SAY something, and forwarding a verdict as a fault makes\n *    the stream unreadable: measured over the 48 hours to 2026-09-09, 229 of\n *    the 251 entries in this log were `/api/health/*` reporting degraded and\n *    22 were the only real outage in the window. See `isLockdownNoticeEntry`\n *    and `isHealthContractEntry` (AGL-2709).\n * 5. **A per-instance budget per window**, with suppression REPORTED. A\n *    monitoring path that hides its own lossiness is the bug shape this repo\n *    keeps rediscovering.\n *\n * ## Where it writes, and why not next door\n *\n * `vercel-runtime`, DELIBERATELY NOT `server-errors`. That log is the\n * `onRequestError` hook's, and the alert policy\n * `projects/aglyn-main/alertPolicies/11610705614308437855` keys on it. A 500\n * our code threw is seen by BOTH arms, so merging the streams would count one\n * incident twice and make triage start by asking which arm saw it. The same\n * separation `client-errors` and `server-errors` already keep, for the same\n * reason.\n *\n * The entries carry a real `httpRequest.status`, which is what makes the\n * policy AGL-1921 originally specified — a log filter on logName matching\n * \"vercel\" and httpRequest.status at or above 500 — expressible without a\n * log-based metric on a jsonPayload field first.\n */\n\n/**\n * LAZY, and that is load-bearing rather than stylistic (AGL-1921, 2026-08-26).\n *\n * `client-error-report` reaches `firebase-admin`. A static import here would\n * pull the whole SDK into anything that bundles this module — including the\n * Cloud Run receiver, whose entire reason for existing is to run this gate\n * OFF Vercel with nothing but `node:crypto` and a metadata-server token. That\n * receiver always supplies its own {@link DrainIngestOptions.target}, so this\n * path is never reached there and the SDK is never resolved.\n *\n * Called through `defaultLoggingTarget` below, never at module scope.\n */\nasync function defaultLoggingTarget(): Promise<{\n  token: string\n  projectId: string\n} | null> {\n  const { beaconLoggingTarget } = await import('./client-error-report')\n  return beaconLoggingTarget()\n}\n\n/**\n * The log id the drain writes to. Contains \"vercel\" on purpose: the alert\n * policy `projects/aglyn-main/alertPolicies/14031689508473384486` matches\n * `logName=~\"vercel\"`, so the name is load-bearing. Renaming this log without\n * repointing that policy silences the platform-5xx arm.\n */\nexport const VERCEL_RUNTIME_LOG_ID = 'vercel-runtime'\n\n/** The env var holding the drain's signature secret. Fails closed if unset. */\nexport const DRAIN_SECRET_ENV = 'VERCEL_LOG_DRAIN_SECRET'\n\n/**\n * The receiver's own path — the FEEDBACK-LOOP GUARD (requirement 5).\n *\n * ⚠️ HISTORICAL, AND KEPT AS DEFENCE IN DEPTH (2026-08-26). The receiver USED\n * to run on `aglyn-console`, whose logs the console drain collects, and the\n * two cuts below were the answer to one receiver 500 draining back in.\n *\n * They were not enough, and the reason is worth stating plainly because the\n * docstring that used to live here got it wrong: **both cuts are about the\n * WRITE, and the cost was the DELIVERY.** Nothing inside a receiver can\n * decline to be requested, and every delivery POST is itself a request that\n * produces a log the same drain then delivers. Measured at 695K invocations\n * in nine hours. Vercel's drain `sampling` rules are not a fix either — a\n * single `{rate: 0}` rule with no path prefix moved delivery volume from 31\n * to 32 per five minutes, i.e. the whole `schemas.log` filter block is stored\n * and never applied.\n *\n * The receiver now lives OFF Vercel, at `cloud/log-drain` on Cloud Run, which\n * no drain watches — so the loop is structurally impossible rather than\n * filtered against. These cuts stay because they cost nothing and they are\n * the backstop if anyone ever mounts this gate on a Vercel route again.\n *\n * Two structural cuts, not one:\n *\n * a. Every entry whose path is this route is dropped before the 5xx filter —\n *    so even the receiver's OWN 500s can never be forwarded, by anything, at\n *    any budget. It is not \"we try not to error\"; it is that its errors are\n *    unforwardable.\n * b. Every line this module logs about itself is `console.warn`, i.e. Vercel\n *    `level: \"warning\"`, and the filter forwards only 5xx and `fatal`. A\n *    suppression summary drained back in is therefore dropped a second time,\n *    on a different property, by a different rule.\n *\n * Matched as a PREFIX so `/api/log-drain`, a future `/api/log-drain/test` and\n * the query-bearing `proxy.path` form all fall on the same side of it.\n */\nexport const RECEIVER_ROUTE_PATH = '/api/log-drain'\n\n/**\n * The lockdown notice route — a route whose 503 is the FEATURE, not a fault.\n *\n * `apps/tenant/app/api/locked/route.ts` answers every request with a real 503\n * carrying `Retry-After`, and the middleware rewrites every path of a locked\n * or bandwidth-capped host to it. That status is deliberate: a takedown\n * notice answering 200 would tell crawlers and uptime checks the site is\n * fine, which is the whole reason the notice is a route handler rather than a\n * page.\n *\n * Forwarded, it is indistinguishable from an outage. One suspended host being\n * crawled emits a 5xx per request, forever, into the arm whose only consumer\n * is an alert policy — so the policy fires on a working feature and the next\n * real incident arrives in a stream that is already red.\n *\n * Matched EXACTLY, not as a prefix: the notice is one path, and a future\n * `/api/locked/*` would be a different route with no such guarantee about its\n * status.\n */\nexport const LOCKDOWN_NOTICE_ROUTE_PATH = '/api/locked'\n\n/**\n * Per-instance write budget, mirroring `reportServerError`'s (same file\n * neighbourhood, same rationale): the failure being watched is a SPIKE, and a\n * spike is when an unbounded forwarder turns one incident into a second one\n * denominated in dollars. 60 entries a minute per instance is far more than\n * any threshold policy needs to cross — the shape of the spike survives; the\n * bill does not follow it.\n */\nconst DRAIN_BUDGET_PER_WINDOW = 60\nconst DRAIN_WINDOW_MS = 60_000\nlet drainWindowStartedAt = 0\nlet drainWritten = 0\nlet drainSuppressed = 0\n\nconst MAX_MESSAGE = 1_024\nconst WRITE_TIMEOUT_MS = 4_000\n\n/** Reset the budget counters. Test seam only — never called in production. */\nexport function resetDrainBudgetForTests(): void {\n  drainWindowStartedAt = 0\n  drainWritten = 0\n  drainSuppressed = 0\n}\n\n/**\n * One log entry as a Vercel drain delivers it. Only the fields this receiver\n * reads are named; the wire object carries many more (client IP, user agent,\n * referer, the query-bearing `proxy.path`) which are deliberately NOT in this\n * type, because a field that has no name here cannot be forwarded by accident.\n */\nexport interface VercelDrainEntry {\n  id?: string\n  deploymentId?: string\n  projectId?: string\n  projectName?: string\n  source?: string\n  host?: string\n  timestamp?: number\n  level?: string\n  type?: string\n  message?: string\n  path?: string\n  entrypoint?: string\n  requestId?: string\n  statusCode?: number\n  environment?: string\n  executionRegion?: string\n  proxy?: {\n    method?: string\n    statusCode?: number\n    path?: string\n    pathType?: string\n  }\n}\n\nfunction clampString(value: unknown, max: number): string {\n  return typeof value === 'string' ? value.slice(0, max) : ''\n}\n\n/**\n * The entries in one delivery, in either format Vercel will send.\n *\n * `json` delivers an array (and, per the reference's own example, sometimes a\n * newline-separated sequence of objects); `ndjson` delivers one object per\n * line. Parsing both means the drain's `deliveryFormat` can be changed in the\n * dashboard without a deploy, and a malformed line is skipped rather than\n * failing the whole delivery — Vercel disables a drain that errors too often,\n * so a receiver that 500s on one bad line silences itself.\n */\nexport function parseDrainPayload(rawBody: string): VercelDrainEntry[] {\n  const body = rawBody.trim()\n  if (!body) return []\n  try {\n    const parsed: unknown = JSON.parse(body)\n    if (Array.isArray(parsed)) {\n      return parsed.filter(\n        (entry): entry is VercelDrainEntry =>\n          Boolean(entry) && typeof entry === 'object',\n      )\n    }\n    if (parsed && typeof parsed === 'object')\n      return [parsed as VercelDrainEntry]\n  } catch {\n    // Not a single JSON document — fall through to line-by-line.\n  }\n  const entries: VercelDrainEntry[] = []\n  for (const line of body.split('\\n')) {\n    const trimmed = line.trim()\n    if (!trimmed) continue\n    try {\n      const parsed: unknown = JSON.parse(trimmed)\n      if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {\n        entries.push(parsed as VercelDrainEntry)\n      }\n    } catch {\n      // One unreadable line never fails a delivery.\n    }\n  }\n  return entries\n}\n\n/** Does this entry describe the receiver's own route? See RECEIVER_ROUTE_PATH. */\nexport function isReceiverEntry(entry: VercelDrainEntry): boolean {\n  const paths = [entry.path, entry.proxy?.path]\n  return paths.some((path) => {\n    if (typeof path !== 'string') return false\n    // `proxy.path` carries the query string; compare the path part only.\n    const [pathname] = path.split('?')\n    return (\n      pathname === RECEIVER_ROUTE_PATH ||\n      pathname.startsWith(`${RECEIVER_ROUTE_PATH}/`)\n    )\n  })\n}\n\n/**\n * Is this the lockdown notice serving its deliberate 503? See\n * {@link LOCKDOWN_NOTICE_ROUTE_PATH}.\n *\n * Narrow on purpose — the route being exempt must not make the route\n * unwatchable. Only a clean 503 is excused: a 500 the handler threw, the\n * `statusCode -1` of a crashed lambda, and a `fatal` line all still forward,\n * because those say the notice itself is broken and a locked host is then\n * serving nothing at all.\n */\nexport function isLockdownNoticeEntry(entry: VercelDrainEntry): boolean {\n  if (entry.level === 'fatal' || entry.type === 'fatal') return false\n  const statuses = [entry.statusCode, entry.proxy?.statusCode].filter(\n    (status): status is number => typeof status === 'number',\n  )\n  if (!statuses.length || statuses.some((status) => status !== 503))\n    return false\n  return [entry.path, entry.proxy?.path].some((path) => {\n    if (typeof path !== 'string') return false\n    // `proxy.path` carries the query string; compare the path part only.\n    const [pathname] = path.split('?')\n    return pathname === LOCKDOWN_NOTICE_ROUTE_PATH\n  })\n}\n\n/**\n * The health contract's routes, whose 503 is a VERDICT and not a fault.\n *\n * Prefix, not an exact path: every endpoint under it speaks the same contract\n * — `healthHttpStatus` answers 200 while a check reports ok and 503 the moment\n * it reports degraded — so `/api/health`, `/api/health/crons` and\n * `/api/health/render/site` are all the same case.\n */\nexport const HEALTH_ROUTE_PREFIX = '/api/health'\n\n/**\n * Is this a health endpoint answering 503 because it is doing its job?\n * (AGL-2709)\n *\n * ⚠️ THE STREAM WAS 91% THIS. Measured over the 48 hours to 2026-09-09, the\n * drain forwarded 251 entries into `vercel-runtime`. **229 were `/api/health/*`\n * answering 503** — `crons` 113, `funnel` 73, `server-errors` 18 — and 22 were\n * the AGL-2708 outage, the only real server errors in the window. The policy\n * on that log (`logName=~\"vercel\" AND severity>=ERROR`, one notification an\n * hour) therefore mails about a working health check for as long as any\n * subsystem is degraded: `/api/health/crons` was CORRECTLY reporting a broken\n * job for six hours on 2026-09-07, which is six hours of \"server errors\" mail\n * arriving in the same inbox that then had to notice 04:02 on 2026-09-09.\n *\n * Excusing it removes a DUPLICATE, not a signal, and the reason is structural\n * rather than a judgement call: every `/api/health/*` route both apps ship has\n * a monitor reading it, and `evaluateSubsystemReaders` fails the build if one\n * ever does not. The 503 is already on the uptime probe's board, in an\n * UptimeRobot monitor and on `docs.aglyn.com/status`, said in a body that\n * names WHICH check failed — which the drain entry never could.\n *\n * Narrow in exactly the same three ways as {@link isLockdownNoticeEntry}, and\n * each one is load-bearing:\n *\n *  - a clean 503 only. A 500 the handler threw means the health route itself\n *    is broken, and a check that cannot answer must never look calm;\n *  - never a `fatal` line, which is process death rather than a verdict;\n *  - never `statusCode -1`, the crashed-lambda sentinel, which is not 503 and\n *    so fails the status test above.\n */\nexport function isHealthContractEntry(entry: VercelDrainEntry): boolean {\n  if (entry.level === 'fatal' || entry.type === 'fatal') return false\n  const statuses = [entry.statusCode, entry.proxy?.statusCode].filter(\n    (status): status is number => typeof status === 'number',\n  )\n  if (!statuses.length || statuses.some((status) => status !== 503))\n    return false\n  return [entry.path, entry.proxy?.path].some((path) => {\n    if (typeof path !== 'string') return false\n    // `proxy.path` carries the query string; compare the path part only.\n    const [pathname] = path.split('?')\n    return (\n      pathname === HEALTH_ROUTE_PREFIX ||\n      pathname.startsWith(`${HEALTH_ROUTE_PREFIX}/`)\n    )\n  })\n}\n\n/**\n * THE COST GATE (requirement 3). Everything false here is dropped unwritten.\n *\n * What counts as a server error:\n *\n * - `statusCode >= 500` or `proxy.statusCode >= 500` — the platform 5xx this\n *   whole arm exists for, including the ones our code never saw.\n * - `statusCode === -1` — documented as \"no response returned and the lambda\n *   crashed\". The OOM/hard-crash case, and the single most important entry\n *   shape the `onRequestError` hook is structurally unable to produce.\n * - `level === 'fatal'` or `type === 'fatal'` — the edge-runtime and\n *   process-death shape, which may carry no status at all.\n *\n * What deliberately does NOT count:\n *\n * - `level === 'error'`. That is any `console.error`, including the fail-soft\n *   warn/error lines the beacons themselves write, and forwarding it would\n *   mean paying per line for a stream the `onRequestError` hook already\n *   covers properly. If an errored request matters, it has a status.\n * - `proxy.statusCode === -1`. Same sentinel, opposite meaning: on the proxy\n *   object it documents a BACKGROUND REVALIDATION, which is a healthy ISR\n *   refresh. Reading it as a crash would forward a steady trickle of normal\n *   traffic forever — the exact bill this gate exists to prevent.\n */\nexport function isServerErrorEntry(entry: VercelDrainEntry): boolean {\n  if (typeof entry.statusCode === 'number') {\n    if (entry.statusCode >= 500) return true\n    if (entry.statusCode === -1) return true\n  }\n  const proxyStatus = entry.proxy?.statusCode\n  if (typeof proxyStatus === 'number' && proxyStatus >= 500) return true\n  if (entry.level === 'fatal' || entry.type === 'fatal') return true\n  return false\n}\n\n/**\n * Everything above, in the order the cost argument requires.\n * Exported so the tests can assert the gate without a transport.\n */\nexport function selectForwardableEntries(\n  entries: readonly VercelDrainEntry[],\n): VercelDrainEntry[] {\n  return entries.filter(\n    (entry) =>\n      !isReceiverEntry(entry) &&\n      !isLockdownNoticeEntry(entry) &&\n      !isHealthContractEntry(entry) &&\n      isServerErrorEntry(entry),\n  )\n}\n\n/**\n * One Cloud Logging entry, carrying ONLY fields that are already inside the\n * envelope the shipped beacons send (requirement 8).\n *\n * Explicitly absent, and each for a reason:\n * `proxy.path` (query string — the AGL-1538 boundary is origin+pathname and\n * this is the same boundary), `proxy.clientIp` and `proxy.userAgent` and\n * `proxy.referer` (visitor identity; also why Vercel's own IP-visibility\n * toggle exists), request or response bodies (never delivered, never wanted).\n * `path` IS forwarded because Vercel documents it as the function or dynamic\n * path — the route PATTERN, which is what you group and alert on anyway, and\n * exactly what `reportServerError` already sends as `route`.\n */\nfunction toLogEntry(entry: VercelDrainEntry): Record<string, unknown> {\n  const status =\n    typeof entry.statusCode === 'number' && entry.statusCode >= 0\n      ? entry.statusCode\n      : typeof entry.proxy?.statusCode === 'number' &&\n          entry.proxy.statusCode >= 0\n        ? entry.proxy.statusCode\n        : undefined\n  return {\n    severity: 'ERROR',\n    // The structured field the AGL-1921 policy matches on. A jsonPayload key\n    // would need a log-based metric first; this one is queryable as shipped.\n    httpRequest: {\n      requestMethod: clampString(entry.proxy?.method, 16) || undefined,\n      status,\n    },\n    jsonPayload: {\n      // No ReportedErrorEvent `@type`: these are NOT ingested into Error\n      // Reporting. A function timeout has no stack, would group as one giant\n      // bucket, and would drown the real grouped errors the hook reports.\n      source: clampString(entry.source, 32) || undefined,\n      level: clampString(entry.level, 16) || undefined,\n      type: clampString(entry.type, 32) || undefined,\n      route: clampString(entry.path, 512) || undefined,\n      entrypoint: clampString(entry.entrypoint, 256) || undefined,\n      host: clampString(entry.host, 256) || undefined,\n      environment: clampString(entry.environment, 32) || undefined,\n      region: clampString(entry.executionRegion, 32) || undefined,\n      project: clampString(entry.projectName, 64) || undefined,\n      projectId: clampString(entry.projectId, 64) || undefined,\n      deploymentId: clampString(entry.deploymentId, 64) || undefined,\n      requestId: clampString(entry.requestId, 64) || undefined,\n      logId: clampString(entry.id, 64) || undefined,\n      statusCode:\n        typeof entry.statusCode === 'number' ? entry.statusCode : undefined,\n      proxyStatusCode:\n        typeof entry.proxy?.statusCode === 'number'\n          ? entry.proxy.statusCode\n          : undefined,\n      // Clamped like the beacon's own message. This is where \"Task timed out\n      // after 10.01 seconds\" lives, which is the whole triage value of the\n      // platform-5xx case.\n      message: clampString(entry.message, MAX_MESSAGE) || undefined,\n    },\n  }\n}\n\n/** What one delivery did, for the response body, the tests and the caller. */\nexport interface DrainIngestResult {\n  /** Entries in the delivery. */\n  received: number\n  /** Entries that passed the receiver-path and 5xx gates. */\n  matched: number\n  /** Entries actually written to Cloud Logging. */\n  forwarded: number\n  /** Entries dropped by the per-window budget — REPORTED, never silent. */\n  suppressed: number\n  /** Set when nothing could be written at all; a stable code, never a message. */\n  code?: 'no-credential' | 'transport' | `http-${number}`\n}\n\n/**\n * Where the write goes, and under whose credential.\n *\n * Injectable because the receiver has to be able to run somewhere that is NOT\n * a Vercel project this drain watches — a delivery POST is a request to\n * whatever hosts it, and a request produces a log the same drain then\n * delivers, which is the AGL-1921 feedback loop. Vercel's drain `sampling`\n * rules look like the answer and are NOT: measured 2026-08-26, a single\n * `{rate: 0}` rule with no path prefix — literally \"drop everything\" — changed\n * delivery volume from 31 to 32 per five minutes. The whole `schemas.log`\n * filter block is accepted by the API, echoed back on `GET`, and never\n * applied. Separation is the only control that works.\n *\n * The default keeps every existing caller on the Firebase admin credential.\n * A receiver hosted off Vercel (Cloud Run in `aglyn-main`) passes its own\n * resolver instead and never imports `firebase-admin` at all, which is what\n * lets this module be bundled for it without dragging the SDK along.\n */\nexport interface DrainIngestOptions {\n  /**\n   * Resolve the Cloud Logging bearer token and project. Returning `null`\n   * means \"no credential\" and the delivery is dropped, reported, and answered\n   * 200 — never an error, because Vercel disables a drain whose endpoint\n   * fails often enough.\n   */\n  target?: () => Promise<{ token: string; projectId: string } | null>\n}\n\n/**\n * Ingest ONE verified delivery: filter, budget, then a single batched write.\n *\n * Never throws. Vercel disables a drain whose endpoint fails often enough, so\n * a receiver that propagated a Logging outage would end by turning itself off\n * during the incident it exists to report.\n */\nexport async function ingestDrainDelivery(\n  entries: readonly VercelDrainEntry[],\n  options?: DrainIngestOptions,\n): Promise<DrainIngestResult> {\n  const received = entries.length\n  const matched = selectForwardableEntries(entries)\n  const result: DrainIngestResult = {\n    received,\n    matched: matched.length,\n    forwarded: 0,\n    suppressed: 0,\n  }\n  if (!matched.length) return result\n\n  const now = Date.now()\n  if (now - drainWindowStartedAt >= DRAIN_WINDOW_MS) {\n    if (drainSuppressed > 0) {\n      // ⚠️ The lossiness is REPORTED. `level: \"warning\"`, so guard (b) in\n      // RECEIVER_ROUTE_PATH keeps this line from ever draining back in.\n      console.warn(\n        JSON.stringify({\n          tag: 'AGL-1921:vercel-log-drain',\n          suppressed: drainSuppressed,\n          written: drainWritten,\n          windowMs: DRAIN_WINDOW_MS,\n        }),\n      )\n    }\n    drainWindowStartedAt = now\n    drainWritten = 0\n    drainSuppressed = 0\n  }\n\n  const room = Math.max(0, DRAIN_BUDGET_PER_WINDOW - drainWritten)\n  const writable = matched.slice(0, room)\n  const suppressed = matched.length - writable.length\n  if (suppressed > 0) drainSuppressed += suppressed\n  result.suppressed = suppressed\n  if (!writable.length) return result\n\n  const target = await (options?.target ?? defaultLoggingTarget)()\n  if (!target) {\n    console.warn(\n      JSON.stringify({\n        tag: 'AGL-1921:vercel-log-drain',\n        drop: writable.length,\n        reason: 'no-credential',\n      }),\n    )\n    result.code = 'no-credential'\n    return result\n  }\n\n  try {\n    const response = await fetch(\n      'https://logging.googleapis.com/v2/entries:write',\n      {\n        method: 'POST',\n        headers: {\n          Authorization: `Bearer ${target.token}`,\n          'Content-Type': 'application/json',\n        },\n        body: JSON.stringify({\n          logName: `projects/${target.projectId}/logs/${VERCEL_RUNTIME_LOG_ID}`,\n          resource: { type: 'global' },\n          entries: writable.map(toLogEntry),\n        }),\n        signal: AbortSignal.timeout(WRITE_TIMEOUT_MS),\n      },\n    )\n    if (!response.ok) {\n      console.warn(\n        JSON.stringify({\n          tag: 'AGL-1921:vercel-log-drain',\n          status: response.status,\n          drop: writable.length,\n        }),\n      )\n      result.code = `http-${response.status}`\n      return result\n    }\n    drainWritten += writable.length\n    result.forwarded = writable.length\n    return result\n  } catch (error) {\n    console.warn(\n      JSON.stringify({\n        tag: 'AGL-1921:vercel-log-drain',\n        transport: String(error).slice(0, 200),\n      }),\n    )\n    result.code = 'transport'\n    return result\n  }\n}\n"],"names":["defaultLoggingTarget","beaconLoggingTarget","VERCEL_RUNTIME_LOG_ID","DRAIN_SECRET_ENV","RECEIVER_ROUTE_PATH","LOCKDOWN_NOTICE_ROUTE_PATH","DRAIN_BUDGET_PER_WINDOW","DRAIN_WINDOW_MS","drainWindowStartedAt","drainWritten","drainSuppressed","MAX_MESSAGE","WRITE_TIMEOUT_MS","resetDrainBudgetForTests","clampString","value","max","slice","parseDrainPayload","rawBody","body","trim","parsed","JSON","parse","Array","isArray","filter","entry","Boolean","entries","line","split","trimmed","push","isReceiverEntry","paths","path","proxy","some","pathname","startsWith","isLockdownNoticeEntry","level","type","statuses","statusCode","status","length","HEALTH_ROUTE_PREFIX","isHealthContractEntry","isServerErrorEntry","proxyStatus","selectForwardableEntries","toLogEntry","undefined","severity","httpRequest","requestMethod","method","jsonPayload","source","route","entrypoint","host","environment","region","executionRegion","project","projectName","projectId","deploymentId","requestId","logId","id","proxyStatusCode","message","ingestDrainDelivery","options","received","matched","result","forwarded","suppressed","now","Date","console","warn","stringify","tag","written","windowMs","room","Math","writable","target","drop","reason","code","response","fetch","headers","Authorization","token","logName","resource","map","signal","AbortSignal","timeout","ok","error","transport","String"],"mappings":"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"}

package/src/lib/server/verify-email-cooldown.d.ts

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