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

package/src/lib/server/console-api-rate-limit.d.ts

@@ -0,0 +1,81 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+export interface ConsoleApiRateLimitOptions {
+    /** Dispatcher path, e.g. `email/list-members-add`. Decides machine vs not. */
+    path: string;
+    /**
+     * The verified Firebase uid, or null when the request carried no bearer
+     * token or one that did not decode. The console dispatcher has already
+     * decoded it for the lockdown gate, so this costs no second verification.
+     */
+    uid: string | null;
+    /** Read for its method and its client-address headers. */
+    request: {
+        method?: string;
+        headers?: {
+            get?: (name: string) => unknown;
+        };
+    };
+    limit?: number;
+    windowMs?: number;
+    nowMs?: number;
+    /** Injectable for tests; defaults to the Admin SDK's Firestore. */
+    firestore?: unknown;
+}
+/**
+ * Counts one console write and returns a 429 once the window is spent.
+ *
+ * ## Reads are not limited
+ *
+ * The standing rule in `RATE_LIMITING.md` is "`checkRateLimit` for volume,
+ * `consumeRateLimit` for consequence": a durable call costs one Firestore read
+ * plus one write, which is the right price beside a handler that installs a
+ * bundle or calls a paid model, and the wrong price in front of a listing GET.
+ * Every route on this surface that spends something spends it on a POST — the
+ * two email list previews, the member add, the suppression writes, `ai/assist`,
+ * every marketplace install and publish — so writes-only covers the exposure
+ * rather than merely most of it.
+ *
+ * ## Fail SOFT, inherited from `consumeRateLimit`
+ *
+ * A Firestore outage lets traffic through, flagged `degraded`, rather than
+ * refusing it; a contended key is refused. That classification is the store's
+ * and is not re-decided here. Failing closed would take the console's write
+ * surface down during an unrelated blip — the operator's own recovery tools
+ * among them — to bound spend that the outage has already stopped, since the
+ * counter and the documents these handlers write are one Firestore. CSRF fails
+ * closed because forging a request is the threat; here the threat is volume,
+ * and volume during an outage is not the incident.
+ *
+ * ## No staff bypass
+ *
+ * The lockdown gates above this one grant staff a bypass, because their
+ * question is "should anyone be doing this right now" and staff are how an
+ * incident gets diagnosed. This one's question is "how much is this costing",
+ * and a staff session spends exactly what a customer session spends. A bypass
+ * would also make the surface unlimited for the accounts most likely to be
+ * driving it from a script.
+ *
+ * ## What the caller is told
+ *
+ * A bare 429 with `Retry-After`, following `visitorWriteRateLimitRefusal` and
+ * `forms/submit`. The fallback bucket below is reached by callers that proved
+ * nothing, so the response says nothing a caller could spend the rest of the
+ * window on.
+ */
+export declare function consoleApiRateLimitRefusal(options: ConsoleApiRateLimitOptions): Promise<Response | null>;
+export default consoleApiRateLimitRefusal;

package/src/lib/server/console-api-rate-limit.js

@@ -0,0 +1,111 @@
+/**
+ * @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 { CONSOLE_API_RATE_LIMIT, CONSOLE_API_RATE_WINDOW_MS, consoleApiRateLimitKey, isMachinePluginApiPath, lockdownIntentForMethod } from "@aglyn/aglyn/server";
+import { consumeRateLimit } from "./rate-limit-store.js";
+import { NO_CLIENT_ADDRESS_BUCKET, readClientIp } from "@aglyn/aglyn/app-utils/request-ip";
+/**
+ * The rate-limit refusal a console plugin-API write returns, or null to
+ * proceed:
+ *
+ *   const limited = await consoleApiRateLimitRefusal({ path, uid, request })
+ *   if (limited) return limited
+ *
+ * The same split as `visitorWriteRateLimitRefusal` beside it — the policy
+ * (ceiling, window, key, which paths are exempt) is pure and lives in
+ * `@aglyn/aglyn/server`; this is only the durable half, which needs Firestore.
+ * The counter is `consumeRateLimit`, unchanged and unwrapped, so the console
+ * inherits its postures rather than acquiring a second set.
+ */ /**
+ * The caller's address, through the shared reader, or the no-address bucket.
+ *
+ * `readClientIp` counts from the RIGHT of the forwarding chain and is the only
+ * reader allowed to answer this question, so a caller cannot choose its own
+ * bucket by prepending an address.
+ */ function clientIp(request) {
+    var _readClientIp;
+    const headers = request == null ? void 0 : request.headers;
+    if (typeof (headers == null ? void 0 : headers.get) !== 'function') return NO_CLIENT_ADDRESS_BUCKET;
+    return (_readClientIp = readClientIp(headers)) != null ? _readClientIp : NO_CLIENT_ADDRESS_BUCKET;
+}
+/**
+ * Counts one console write and returns a 429 once the window is spent.
+ *
+ * ## Reads are not limited
+ *
+ * The standing rule in `RATE_LIMITING.md` is "`checkRateLimit` for volume,
+ * `consumeRateLimit` for consequence": a durable call costs one Firestore read
+ * plus one write, which is the right price beside a handler that installs a
+ * bundle or calls a paid model, and the wrong price in front of a listing GET.
+ * Every route on this surface that spends something spends it on a POST — the
+ * two email list previews, the member add, the suppression writes, `ai/assist`,
+ * every marketplace install and publish — so writes-only covers the exposure
+ * rather than merely most of it.
+ *
+ * ## Fail SOFT, inherited from `consumeRateLimit`
+ *
+ * A Firestore outage lets traffic through, flagged `degraded`, rather than
+ * refusing it; a contended key is refused. That classification is the store's
+ * and is not re-decided here. Failing closed would take the console's write
+ * surface down during an unrelated blip — the operator's own recovery tools
+ * among them — to bound spend that the outage has already stopped, since the
+ * counter and the documents these handlers write are one Firestore. CSRF fails
+ * closed because forging a request is the threat; here the threat is volume,
+ * and volume during an outage is not the incident.
+ *
+ * ## No staff bypass
+ *
+ * The lockdown gates above this one grant staff a bypass, because their
+ * question is "should anyone be doing this right now" and staff are how an
+ * incident gets diagnosed. This one's question is "how much is this costing",
+ * and a staff session spends exactly what a customer session spends. A bypass
+ * would also make the surface unlimited for the accounts most likely to be
+ * driving it from a script.
+ *
+ * ## What the caller is told
+ *
+ * A bare 429 with `Retry-After`, following `visitorWriteRateLimitRefusal` and
+ * `forms/submit`. The fallback bucket below is reached by callers that proved
+ * nothing, so the response says nothing a caller could spend the rest of the
+ * window on.
+ */ export async function consoleApiRateLimitRefusal(options) {
+    var _options_nowMs, _options_limit, _options_windowMs;
+    var _options_request;
+    if (lockdownIntentForMethod((_options_request = options.request) == null ? void 0 : _options_request.method) === 'read') return null;
+    if (isMachinePluginApiPath(options.path)) return null;
+    const nowMs = (_options_nowMs = options.nowMs) != null ? _options_nowMs : Date.now();
+    // Prefixed, so an address can never collide with a uid: Firebase uids are
+    // opaque and a bucket shared between an identified operator and everyone
+    // arriving from one address would refuse the wrong one of them.
+    const subject = options.uid ? `uid:${options.uid}` : `ip:${clientIp(options.request)}`;
+    const rate = await consumeRateLimit(consoleApiRateLimitKey(subject), {
+        limit: (_options_limit = options.limit) != null ? _options_limit : CONSOLE_API_RATE_LIMIT,
+        windowMs: (_options_windowMs = options.windowMs) != null ? _options_windowMs : CONSOLE_API_RATE_WINDOW_MS,
+        now: nowMs,
+        firestore: options.firestore
+    });
+    if (rate.allowed) return null;
+    return Response.json({
+        error: 'Too many requests'
+    }, {
+        status: 429,
+        headers: {
+            'Retry-After': String(Math.max(1, Math.ceil((rate.resetMs - nowMs) / 1000)))
+        }
+    });
+}
+export default consoleApiRateLimitRefusal;
+
+//# sourceMappingURL=console-api-rate-limit.js.map

package/src/lib/server/console-api-rate-limit.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/console-api-rate-limit.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport {\n  CONSOLE_API_RATE_LIMIT,\n  CONSOLE_API_RATE_WINDOW_MS,\n  consoleApiRateLimitKey,\n  isMachinePluginApiPath,\n  lockdownIntentForMethod,\n} from '@aglyn/aglyn/server'\nimport { consumeRateLimit } from './rate-limit-store'\nimport {\n  NO_CLIENT_ADDRESS_BUCKET,\n  readClientIp,\n} from '@aglyn/aglyn/app-utils/request-ip'\n\n/**\n * The rate-limit refusal a console plugin-API write returns, or null to\n * proceed:\n *\n *   const limited = await consoleApiRateLimitRefusal({ path, uid, request })\n *   if (limited) return limited\n *\n * The same split as `visitorWriteRateLimitRefusal` beside it — the policy\n * (ceiling, window, key, which paths are exempt) is pure and lives in\n * `@aglyn/aglyn/server`; this is only the durable half, which needs Firestore.\n * The counter is `consumeRateLimit`, unchanged and unwrapped, so the console\n * inherits its postures rather than acquiring a second set.\n */\n\n/**\n * The caller's address, through the shared reader, or the no-address bucket.\n *\n * `readClientIp` counts from the RIGHT of the forwarding chain and is the only\n * reader allowed to answer this question, so a caller cannot choose its own\n * bucket by prepending an address.\n */\nfunction clientIp(request: {\n  headers?: { get?: (name: string) => unknown }\n}): string {\n  const headers = request?.headers\n  if (typeof headers?.get !== 'function') return NO_CLIENT_ADDRESS_BUCKET\n  return (\n    readClientIp(headers as { get(name: string): string | null }) ??\n    NO_CLIENT_ADDRESS_BUCKET\n  )\n}\n\nexport interface ConsoleApiRateLimitOptions {\n  /** Dispatcher path, e.g. `email/list-members-add`. Decides machine vs not. */\n  path: string\n  /**\n   * The verified Firebase uid, or null when the request carried no bearer\n   * token or one that did not decode. The console dispatcher has already\n   * decoded it for the lockdown gate, so this costs no second verification.\n   */\n  uid: string | null\n  /** Read for its method and its client-address headers. */\n  request: { method?: string; headers?: { get?: (name: string) => unknown } }\n  limit?: number\n  windowMs?: number\n  nowMs?: number\n  /** Injectable for tests; defaults to the Admin SDK's Firestore. */\n  firestore?: unknown\n}\n\n/**\n * Counts one console write and returns a 429 once the window is spent.\n *\n * ## Reads are not limited\n *\n * The standing rule in `RATE_LIMITING.md` is \"`checkRateLimit` for volume,\n * `consumeRateLimit` for consequence\": a durable call costs one Firestore read\n * plus one write, which is the right price beside a handler that installs a\n * bundle or calls a paid model, and the wrong price in front of a listing GET.\n * Every route on this surface that spends something spends it on a POST — the\n * two email list previews, the member add, the suppression writes, `ai/assist`,\n * every marketplace install and publish — so writes-only covers the exposure\n * rather than merely most of it.\n *\n * ## Fail SOFT, inherited from `consumeRateLimit`\n *\n * A Firestore outage lets traffic through, flagged `degraded`, rather than\n * refusing it; a contended key is refused. That classification is the store's\n * and is not re-decided here. Failing closed would take the console's write\n * surface down during an unrelated blip — the operator's own recovery tools\n * among them — to bound spend that the outage has already stopped, since the\n * counter and the documents these handlers write are one Firestore. CSRF fails\n * closed because forging a request is the threat; here the threat is volume,\n * and volume during an outage is not the incident.\n *\n * ## No staff bypass\n *\n * The lockdown gates above this one grant staff a bypass, because their\n * question is \"should anyone be doing this right now\" and staff are how an\n * incident gets diagnosed. This one's question is \"how much is this costing\",\n * and a staff session spends exactly what a customer session spends. A bypass\n * would also make the surface unlimited for the accounts most likely to be\n * driving it from a script.\n *\n * ## What the caller is told\n *\n * A bare 429 with `Retry-After`, following `visitorWriteRateLimitRefusal` and\n * `forms/submit`. The fallback bucket below is reached by callers that proved\n * nothing, so the response says nothing a caller could spend the rest of the\n * window on.\n */\nexport async function consoleApiRateLimitRefusal(\n  options: ConsoleApiRateLimitOptions,\n): Promise<Response | null> {\n  if (lockdownIntentForMethod(options.request?.method) === 'read') return null\n  if (isMachinePluginApiPath(options.path)) return null\n\n  const nowMs = options.nowMs ?? Date.now()\n  // Prefixed, so an address can never collide with a uid: Firebase uids are\n  // opaque and a bucket shared between an identified operator and everyone\n  // arriving from one address would refuse the wrong one of them.\n  const subject = options.uid\n    ? `uid:${options.uid}`\n    : `ip:${clientIp(options.request)}`\n  const rate = await consumeRateLimit(consoleApiRateLimitKey(subject), {\n    limit: options.limit ?? CONSOLE_API_RATE_LIMIT,\n    windowMs: options.windowMs ?? CONSOLE_API_RATE_WINDOW_MS,\n    now: nowMs,\n    firestore: options.firestore,\n  })\n  if (rate.allowed) return null\n\n  return Response.json(\n    { error: 'Too many requests' },\n    {\n      status: 429,\n      headers: {\n        'Retry-After': String(\n          Math.max(1, Math.ceil((rate.resetMs - nowMs) / 1000)),\n        ),\n      },\n    },\n  )\n}\n\nexport default consoleApiRateLimitRefusal\n"],"names":["CONSOLE_API_RATE_LIMIT","CONSOLE_API_RATE_WINDOW_MS","consoleApiRateLimitKey","isMachinePluginApiPath","lockdownIntentForMethod","consumeRateLimit","NO_CLIENT_ADDRESS_BUCKET","readClientIp","clientIp","request","headers","get","consoleApiRateLimitRefusal","options","method","path","nowMs","Date","now","subject","uid","rate","limit","windowMs","firestore","allowed","Response","json","error","status","String","Math","max","ceil","resetMs"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SACEA,sBAAsB,EACtBC,0BAA0B,EAC1BC,sBAAsB,EACtBC,sBAAsB,EACtBC,uBAAuB,QAClB,sBAAqB;AAC5B,SAASC,gBAAgB,QAAQ,wBAAoB;AACrD,SACEC,wBAAwB,EACxBC,YAAY,QACP,oCAAmC;AAE1C;;;;;;;;;;;;CAYC,GAED;;;;;;CAMC,GACD,SAASC,SAASC,OAEjB;QAIGF;IAHF,MAAMG,UAAUD,2BAAAA,QAASC,OAAO;IAChC,IAAI,QAAOA,2BAAAA,QAASC,GAAG,MAAK,YAAY,OAAOL;IAC/C,QACEC,gBAAAA,aAAaG,oBAAbH,gBACAD;AAEJ;AAoBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwCC,GACD,OAAO,eAAeM,2BACpBC,OAAmC;QAKrBA,gBAQLA,gBACGA;QAZgBA;IAA5B,IAAIT,yBAAwBS,mBAAAA,QAAQJ,OAAO,qBAAfI,iBAAiBC,MAAM,MAAM,QAAQ,OAAO;IACxE,IAAIX,uBAAuBU,QAAQE,IAAI,GAAG,OAAO;IAEjD,MAAMC,SAAQH,iBAAAA,QAAQG,KAAK,YAAbH,iBAAiBI,KAAKC,GAAG;IACvC,0EAA0E;IAC1E,yEAAyE;IACzE,gEAAgE;IAChE,MAAMC,UAAUN,QAAQO,GAAG,GACvB,CAAC,IAAI,EAAEP,QAAQO,GAAG,EAAE,GACpB,CAAC,GAAG,EAAEZ,SAASK,QAAQJ,OAAO,GAAG;IACrC,MAAMY,OAAO,MAAMhB,iBAAiBH,uBAAuBiB,UAAU;QACnEG,KAAK,GAAET,iBAAAA,QAAQS,KAAK,YAAbT,iBAAiBb;QACxBuB,QAAQ,GAAEV,oBAAAA,QAAQU,QAAQ,YAAhBV,oBAAoBZ;QAC9BiB,KAAKF;QACLQ,WAAWX,QAAQW,SAAS;IAC9B;IACA,IAAIH,KAAKI,OAAO,EAAE,OAAO;IAEzB,OAAOC,SAASC,IAAI,CAClB;QAAEC,OAAO;IAAoB,GAC7B;QACEC,QAAQ;QACRnB,SAAS;YACP,eAAeoB,OACbC,KAAKC,GAAG,CAAC,GAAGD,KAAKE,IAAI,CAAC,AAACZ,CAAAA,KAAKa,OAAO,GAAGlB,KAAI,IAAK;QAEnD;IACF;AAEJ;AAEA,eAAeJ,2BAA0B"}

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

@@ -0,0 +1,326 @@
+/**
+ * @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 DomainCheck } from './sso-provisioning';
+import { type RecaptchaAllowlistResult } from './recaptcha-allowlist';
+import { type WorkspaceDomainResult } from './workspace-domains';
+import { normalizePlatformDomain } from './platform-domain-names';
+/** Collection name, kept in one place so the rules file and this agree. */
+export declare const CONSOLE_DOMAINS_COLLECTION = "consoleDomains";
+/**
+ * Trim, lowercase, drop a trailing root dot, and tolerate a pasted URL.
+ *
+ * The console-flavoured name for the shared normaliser, kept because callers
+ * and the docs use it.
+ */
+export declare const normalizeConsoleDomain: typeof normalizePlatformDomain;
+/**
+ * Shape, length and reserved-name check.
+ *
+ * The RULES moved to `platform-domain-names.ts` (AGL-1430) so the site
+ * custom-domain path could stop being the only surface without them — it was
+ * the one with the live hole. Only the wording stays here: these two strings
+ * are what a customer reads in the console-domain wizard.
+ *
+ * `{ domain, error }` with both keys always present rather than a discriminated
+ * union, matching `validateSsoDomain` — `strictNullChecks` is off repo-wide and
+ * an `{ ok: true } | { ok: false }` union does not narrow reliably once it
+ * crosses a library boundary.
+ */
+export declare function validateConsoleDomain(input: string): DomainCheck;
+/**
+ * Every name this claim covers: the primary, then its twins.
+ *
+ * **A twin is a name we attach to Vercel that is not the one the customer
+ * asked for**, and it is the sharp edge of the whole file. Attaching
+ * `acme.com` without also attaching `www.acme.com` leaves half the traffic on
+ * the floor; attaching `www.acme.com` without *claiming* it leaves a name in
+ * our Vercel project that no Firestore document accounts for — and then a
+ * second org claims it, `attachProjectDomain` answers `already-exists`, and
+ * that org's visitors are redirected to the first org's console. The name is
+ * therefore derived here, claimed here, and attached from the same list.
+ *
+ * The apex test is deliberately narrow: exactly two labels. `acme.co.uk` is
+ * also an apex and gets no twin, which costs a customer a `www` redirect they
+ * can ask for by hand. Guessing wrong in the other direction — treating
+ * `console.acme.com` as an apex and quietly reserving `www.console.acme.com` —
+ * would reserve names on an org's behalf that it never asked for, and a
+ * reservation is the thing that locks another org out.
+ */
+export declare function consoleDomainNames(domain: string): string[];
+export type ConsoleDomainStatus = 'pending' | 'verified' | 'active' | 'suspended';
+export interface ConsoleDomainClaimView {
+    domain: string;
+    orgId: string;
+    status: ConsoleDomainStatus;
+    token: string;
+    /** Every name the claim reserves — primary first. */
+    names: string[];
+    /** Fully-qualified host the TXT record goes on. */
+    recordHost: string;
+    /** Exact value the TXT record must carry. */
+    recordValue: string;
+    verified: boolean;
+    lastRecords?: string[];
+}
+/** Both keys always present, one always null — see `validateConsoleDomain`. */
+export interface ConsoleDomainResult {
+    claim: ConsoleDomainClaimView | null;
+    error: string | null;
+    /** HTTP status a route should return. 200 whenever `claim` is set. */
+    status: number;
+}
+export declare class ConsoleDomainTakenError extends Error {
+    readonly domain: string;
+    constructor(domain: string);
+}
+/**
+ * Claim the primary and every twin in ONE transaction, or none of them.
+ *
+ * Modelled on the `orgSlugs` reservation in `organizations.ts`: read inside the
+ * transaction, refuse if someone else holds it, write in the same transaction.
+ * Every name is read with a single `getAll` so the whole set is covered by one
+ * transaction's read-set — claiming a twin in a follow-up write is precisely
+ * the AGL-743 hole this exists to close.
+ *
+ * Idempotent for the owning org, and it **keeps the existing token**: reissuing
+ * would invalidate a TXT record the customer may already have published and
+ * turn a working setup into a mysterious failure (the same reasoning as
+ * `issueDomainClaim`).
+ *
+ * Throws `ConsoleDomainTakenError` when any name in the set belongs to another
+ * org. Exported for the integration test, which needs to drive the transaction
+ * under real contention.
+ */
+export declare function claimConsoleDomain(orgId: string, domain: string): Promise<ConsoleDomainClaimView>;
+/**
+ * Start (or re-read) a registration: entitlement, validation, then the claim.
+ *
+ * The order matters. An org without `whiteLabel` must not be able to learn
+ * whether a domain is free, and must not leave a `pending` claim behind that
+ * blocks the org that *is* entitled to it.
+ */
+export declare function registerConsoleDomain(options: {
+    orgId: string;
+    domain: string;
+}): Promise<ConsoleDomainResult>;
+/**
+ * Re-read DNS and record the verdict.
+ *
+ * Re-reads the claim first and refuses if the caller does not own it — the
+ * `publishSsoDomains` discipline, where nothing reaches the collection sign-in
+ * consults until a fresh lookup has seen the record. The comparison itself is
+ * `recordsProveOwnership`, an exact match on a whole TXT record: a substring
+ * test would accept `aglyn-domain-verification=<token>-and-more`, and a prefix
+ * test would accept anything that merely starts the same way.
+ */
+export declare function verifyConsoleDomain(options: {
+    orgId: string;
+    domain: string;
+}): Promise<ConsoleDomainResult>;
+export interface ConsoleDomainAttachment {
+    domain: string;
+    results: WorkspaceDomainResult[];
+    /** Vercel's verdict alone: every claimed name is on the console project. */
+    attached: boolean;
+    /**
+     * Attached **and** able to attest — the only thing a caller may treat as
+     * "the customer can use this domain". `attached && !ready` is a real and
+     * reachable state: Vercel serves the name, App Check refuses it.
+     */
+    ready: boolean;
+    /**
+     * Non-null when a name this claim SERVES on cannot complete a large upload
+     * (AGL-1452), carrying the exact ordered command that fixes it.
+     *
+     * The attach itself still succeeds — the console does serve on the name, and
+     * refusing the domain over the upload path would be the worse outcome. But
+     * the customer's video, PDF and ZIP uploads will fail behind a generic "try
+     * again" snackbar until this is cleared, and the whole point of surfacing it
+     * here is that it stops being something a person has to remember: GCS
+     * matches CORS origins EXACTLY, so a new console origin needs its own entry
+     * and nothing about the eventual symptom points at bucket configuration.
+     *
+     * `attachProjectDomain` tries to add the entry itself; this is what is left
+     * when it could not — in practice, a runtime service account without
+     * `storage.buckets.update`.
+     */
+    uploadCorsRemedy: string | null;
+    /**
+     * The App Check reCAPTCHA allowlist write for the SERVING name (AGL-1378).
+     *
+     * Unlike `uploadCorsRemedy` this is **not** advisory. A console origin the
+     * key has never heard of cannot solve reCAPTCHA, so `getToken` fails with
+     * `appCheck/recaptcha-error` and Identity Platform refuses the first
+     * `signInWithCustomToken` with `401 UNAUTHENTICATED` — before it looks at
+     * the token. The domain would serve a console that renders and can never
+     * sign anyone in, and the customer-visible symptom is "Missing or
+     * insufficient permissions", indistinguishable from a rules verdict.
+     *
+     * So this participates in `attached`: a claim does not reach `active` unless
+     * `allowlistSatisfied()` says the origin can attest.
+     */
+    allowlist: RecaptchaAllowlistResult;
+}
+/**
+ * Attach every claimed name to the console Vercel project.
+ *
+ * ⚠️ Not called from anywhere. It exists so the mechanism is complete and
+ * tested; wiring it to a route is 1099c's job and must not happen before 1099d
+ * (see the header).
+ *
+ * Refuses unless the claim is this org's **and** currently verified, and unless
+ * the org still passes `whiteLabel`. The names come from the stored claim, not
+ * from `consoleDomainNames`, so a change to the twin rule can never attach a
+ * name the transaction did not reserve.
+ *
+ * Twins are registered as per-domain **redirects to the primary**, and the
+ * redirect value is a **bare hostname** — `attachProjectDomain` enforces that,
+ * because `https://${target}` is rejected by Vercel with a message that blames
+ * the target for being absent rather than the format (AGL-1365).
+ */
+export declare function activateConsoleDomain(options: {
+    orgId: string;
+    domain: string;
+}): Promise<ConsoleDomainResult & {
+    attachment: ConsoleDomainAttachment | null;
+}>;
+/**
+ * Kill the sessions, detach every name, then drop the claim — in that order.
+ *
+ * **The epoch bump comes first, and that is D7's own ordering**: *"`sessionEpoch
+ * = now` first, then Vercel `DELETE`, then delete the doc. Order matters: kill
+ * the sessions while we still control the host."* It was the one step of that
+ * sentence this function never performed, while
+ * {@link consoleSessionEpochRefuses} documented it as something release
+ * already did.
+ *
+ * Two things went wrong without it, and neither is covered by the Vercel
+ * detach:
+ *
+ * - **The in-flight window.** Vercel's `DELETE` and the allowlist reclaim are
+ *   network round trips. Across all of them the claim still reads `active`, so
+ *   `resolveConsoleDomain` says `servable` and `redeemConsoleHandoff` — which
+ *   sits on `/api/*`, outside the middleware matcher — happily cashes an
+ *   authorized handoff into a brand-new session on a domain we are in the
+ *   middle of giving up.
+ * - **And that session then outlives the release entirely**, because the
+ *   document carrying the epoch is deleted a moment later and
+ *   `readConsoleSessionEpoch` reads a missing document as `0`, which every
+ *   caller treats as "this control has nothing to say" and FAILS OPEN. The
+ *   effect was that `suspendOnDowngrade` — the *lesser* action — revoked
+ *   sessions properly while an explicit release did not revoke them at all.
+ *
+ * Bumping first inverts that: an authorization that predates the bump is
+ * refused `revoked` at redemption, so the window closes rather than merely
+ * being short. What survives the release is still only Vercel's allowlist,
+ * which is the boundary; this is the defence in depth behind it that D7 asked
+ * for and the code had stopped providing.
+ *
+ * Vercel before the documents, though, for the reason the header gives: a claim
+ * released while the name is still on the project is the unindexed-name hole,
+ * opened deliberately. If a detach fails the claim is kept and the caller is
+ * told, so the name stays reserved to the org that still holds it in Vercel —
+ * and the epoch bump is exactly the right residue on that path too, since
+ * sessions on a domain we just tried to release should not survive the attempt.
+ */
+export declare function releaseConsoleDomain(options: {
+    orgId: string;
+    domain: string;
+}): Promise<{
+    released: boolean;
+    results: WorkspaceDomainResult[];
+    /** Present once the reclaim was attempted — absent when Vercel refused first. */
+    allowlist?: RecaptchaAllowlistResult;
+    error: string | null;
+}>;
+/**
+ * Drop a claim that was never attached, without touching Vercel.
+ *
+ * The counterpart to claiming from the branding form: an org that clears or
+ * changes `customConsoleDomain` must not leave its old reservation standing,
+ * or it locks another org out of a name nobody is using. Deliberately refuses
+ * once the claim has proved ownership or reached Vercel — releasing *that*
+ * needs `releaseConsoleDomain`, because a claim dropped while the name is
+ * still on the project is the unindexed-name hole in the header.
+ */
+export declare function releasePendingConsoleDomain(options: {
+    orgId: string;
+    domain: string;
+}): Promise<boolean>;
+/**
+ * Why a host may — or may not — be served the console (AGL-1099c).
+ *
+ * `reason` is not decoration. `unknown` and `degraded` both mean "serve it,
+ * this gate has no opinion", and they mean it for opposite causes; every other
+ * value means "refuse". Collapsing them into a boolean is how a lookup outage
+ * would come to read the same as a revoked entitlement.
+ */
+export type ConsoleDomainReason = 'active' | 'unknown' | 'no-org' | 'not-entitled' | 'not-active' | 'degraded';
+export interface ConsoleDomainVerdict {
+    /** A claim exists for this exact host. */
+    known: boolean;
+    /** The console may be served here, pinned to `orgSlug`. */
+    servable: boolean;
+    /**
+     * Workspace slug of the owning org — where a refused visitor is sent, and
+     * the org the path is rewritten under when servable. Never the `orgId`: a
+     * verdict is read by an unauthenticated route.
+     */
+    orgSlug: string | null;
+    reason: ConsoleDomainReason;
+    /** The lookup could not be completed. Honour it, never cache it. */
+    degraded: boolean;
+}
+/**
+ * Host → org, for the middleware gate and the session-route boundary.
+ *
+ * **One host pins exactly one org.** That is enforced by the document being
+ * keyed on the host and claimed transactionally (see the header), not by
+ * anything here — this function only ever reads the pin, and there is no input
+ * by which a caller can ask for a different org.
+ *
+ * The three "serve it anyway" answers, and why each is right:
+ *
+ * - **`unknown`** — no claim on this host. localhost, preview deployments and
+ *   self-hosted installs all land here, and they must keep working. It is safe
+ *   because of the detach ordering `releaseConsoleDomain` enforces: Vercel
+ *   first, documents second, and the claim is kept if the detach fails. So a
+ *   name the console project still answers for always has a document, and a
+ *   name with no document cannot reach this deployment through the console
+ *   project at all (AGL-1430's correspondence — do not break it).
+ * - **`degraded`** — Firestore could not be reached. Fails OPEN, matching the
+ *   workspace gate and for the reason AGL-1135 recorded: the Vercel domain
+ *   allowlist is the boundary, and a customer's console going dark because a
+ *   lookup timed out is worse than the residual exposure. Never cached.
+ * - a claim that is `active` and entitled.
+ *
+ * Everything else refuses. In particular a `verified` claim is **not**
+ * servable: until AGL-1378 clears, activation includes a manual App Check
+ * allowlist entry, so "ownership proved" must never imply "serve it".
+ */
+export declare function resolveConsoleDomain(host: string): Promise<ConsoleDomainVerdict>;
+/**
+ * The org a console domain belongs to, or null.
+ *
+ * Read-only, and used today only to refuse a `customConsoleDomain` that another
+ * org already holds. Routing reads `resolveConsoleDomain` instead, which asks
+ * the entitlement question this one does not.
+ */
+export declare function getConsoleDomainClaim(domain: string): Promise<{
+    orgId: string;
+    status: ConsoleDomainStatus;
+} | null>;