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

package/src/lib/server/recaptcha-allowlist.d.ts

@@ -0,0 +1,90 @@
+/**
+ * @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.
+ */
+/**
+ * Published ceiling for `webSettings.allowedDomains`, quoted rather than
+ * measured: *"Each key supports a maximum of 250 domains."* An occupancy
+ * reading is NOT a limit — this repo already spent two weeks treating a
+ * snapshot of nine entries as a hard ceiling. Re-probe occupancy, never the
+ * limit.
+ */
+export declare const MAX_ALLOWED_DOMAINS = 250;
+export type RecaptchaAllowlistOutcome = 
+/** We wrote the entry and re-read the key to confirm it. */
+'listed'
+/** The exact name was already on the key; nothing was written. */
+ | 'already-listed'
+/** We removed the entry and re-read the key to confirm it. */
+ | 'removed'
+/** Nothing to remove — the exact name was not on the key. */
+ | 'absent'
+/**
+ * This deployment runs no App Check reCAPTCHA provider, so there is no
+ * allowlist to maintain and nothing is gated. Self-host, and local dev.
+ */
+ | 'unenforced'
+/** The key is at {@link MAX_ALLOWED_DOMAINS}. A commercial event, not a bug. */
+ | 'full'
+/** Anything else: misconfiguration, IAM, transport, or a suspicious write. */
+ | 'failed';
+export interface RecaptchaAllowlistResult {
+    outcome: RecaptchaAllowlistOutcome;
+    domain: string;
+    /** Human-readable cause. Always set when the outcome is not a success. */
+    detail?: string;
+    /**
+     * Live `allowedDomains` after the operation, when we got far enough to read
+     * them. Occupancy is worth surfacing precisely because it must never be
+     * quoted from memory.
+     */
+    allowedDomains?: string[];
+}
+/**
+ * Does this outcome mean the origin can attest?
+ *
+ * The single decision point, so that no caller can invent a looser one. Note
+ * what is NOT here: `full` and `failed` both leave a domain that will 401 its
+ * customer at sign-in, and `full` is the easier of the two to mistake for a
+ * warning.
+ */
+export declare function allowlistSatisfied(outcome: RecaptchaAllowlistOutcome): boolean;
+/**
+ * Put a custom console domain on the key, so a browser there can attest.
+ *
+ * Called by `activateConsoleDomain` for the **serving** name only. Redirect
+ * twins (`www.acme.com` → `acme.com`) never execute the console, never load
+ * reCAPTCHA, and would spend a slot of the 250 for nothing.
+ */
+export declare function allowConsoleOrigin(input: string): Promise<RecaptchaAllowlistResult>;
+/**
+ * Take a domain back off the key when its claim is released.
+ *
+ * Removes the EXACT entry and nothing else. A filter that matched subdomains
+ * would take `aglyn.com` off the key while releasing `console.aglyn.com` —
+ * and the entry it deleted is the one every Aglyn origin attests against.
+ */
+export declare function reclaimConsoleOrigin(input: string): Promise<RecaptchaAllowlistResult>;
+/**
+ * Read-only occupancy, for an operator asking "how many of the 250 are gone?"
+ *
+ * Deliberately returns the live list rather than a count: a count is what got
+ * quoted as a ceiling for two weeks.
+ */
+export declare function readConsoleOriginAllowlist(): Promise<{
+    domains: string[] | null;
+    limit: number;
+    detail?: string;
+}>;

package/src/lib/server/recaptcha-allowlist.js

@@ -0,0 +1,409 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+import { _ as _object_without_properties_loose } from "@swc/helpers/_/_object_without_properties_loose";
+/**
+ * @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 App Check reCAPTCHA allowlist, written from the product (AGL-1378).
+ *
+ * ## Why this file has to exist
+ *
+ * The console reads Firestore **client-side**, and App Check gates those reads
+ * with a reCAPTCHA token that the key itself refuses to mint on an origin it
+ * has never heard of. Measured against the live key on 2026-08-23, with both
+ * controls, by requesting `recaptcha/api2/anchor` with a base64 `co` origin:
+ *
+ * ```
+ * https://app.aglyn.com:443                    ACCEPTED   (listed)
+ * https://never-registered-9f3x.aglyn.com:443  ACCEPTED   (subtree of a listed entry)
+ * https://console.acme-agency.example:443      REJECTED   "Invalid domain for site key"
+ * https://console.northwind-coffee.com:443     REJECTED   "Invalid domain for site key"
+ * ```
+ *
+ * A rejected solve means `initializeAppCheck` → `getToken` fails with
+ * `appCheck/recaptcha-error`, and the very next Identity Platform call is
+ * refused `401 UNAUTHENTICATED — "Firebase App Check token is invalid"`
+ * **before** token validation (`docs/design/agl-1099a-poc-findings.md` §2).
+ * So a custom console domain that is attached and routed but not allowlisted
+ * renders a console that can never sign anyone in — and the symptom the
+ * customer reports is "Missing or insufficient permissions", which is the same
+ * string a Security Rules verdict produces. That is the misdiagnosis this
+ * whole area keeps generating; the fix is to never let the state exist.
+ *
+ * ## Why it was believed impossible, and why that is stale
+ *
+ * AGL-1378 concluded the key was a classic v3 key with no management API. The
+ * key was auto-migrated into a Google-created project, and every probe asked
+ * `aglyn-main` — where the reCAPTCHA API genuinely is disabled — rather than
+ * the project the key actually lives in. Measured 2026-08-23:
+ * `recaptchaenterprise.googleapis.com` is enabled there, two accounts we
+ * control are `roles/owner`, and `projects.keys.patch` on
+ * `webSettings.allowedDomains` answers `200`.
+ *
+ * ## The two hazards this code is shaped around
+ *
+ * 1. **A patch that drops sibling fields.** `webSettings` also carries
+ *    `allowAllDomains`, `integrationType`, `allowAmpTraffic` and
+ *    `challengeSecurityPreference`; a whole-object write that omitted
+ *    `allowAllDomains` would read as `false`… or a future default. So the mask
+ *    is `webSettings.allowedDomains` — the narrowest path the API accepts —
+ *    **and** the response is re-read afterwards: every domain that was there
+ *    before must still be there, and `allowAllDomains` must still be `false`.
+ *    A write that silently widened the key to every origin is a worse outcome
+ *    than the domain never being listed.
+ * 2. **Silent success.** Every outcome here is explicit, and
+ *    {@link allowlistSatisfied} is the ONLY place that decides which ones mean
+ *    "the customer can actually sign in". `activateConsoleDomain` refuses to
+ *    mark a claim `active` unless it says yes.
+ *
+ * ## Exact names, never subtree cover
+ *
+ * A listed entry covers its whole subtree but never its parents (proved
+ * 2026-08-10). It is therefore tempting to skip the write when some existing
+ * entry already covers the new name. Deliberately not done: if org A holds
+ * `acme.com` and org B later claims `console.acme.com`, B would be silently
+ * covered by A's entry — and A detaching would break B with no trace linking
+ * the two. One entry per claimed apex is what the documented 250-domain
+ * ceiling is denominated in anyway (250 distinct customer apexes, occupancy 5
+ * on 2026-08-23), so exactness costs nothing we were not already counting.
+ */ import { getApp } from "firebase-admin/app";
+const RECAPTCHA_API = 'https://recaptchaenterprise.googleapis.com/v1';
+/**
+ * Published ceiling for `webSettings.allowedDomains`, quoted rather than
+ * measured: *"Each key supports a maximum of 250 domains."* An occupancy
+ * reading is NOT a limit — this repo already spent two weeks treating a
+ * snapshot of nine entries as a hard ceiling. Re-probe occupancy, never the
+ * limit.
+ */ export const MAX_ALLOWED_DOMAINS = 250;
+/**
+ * Ceiling on the whole exchange, matching `workspace-domains.ts`.
+ *
+ * This one is awaited by an attach the operator is watching, so an
+ * unresponsive Google API must lose quickly rather than hang the activation
+ * until the platform kills the function.
+ */ const REQUEST_TIMEOUT_MS = 8000;
+/**
+ * Does this outcome mean the origin can attest?
+ *
+ * The single decision point, so that no caller can invent a looser one. Note
+ * what is NOT here: `full` and `failed` both leave a domain that will 401 its
+ * customer at sign-in, and `full` is the easier of the two to mistake for a
+ * warning.
+ */ export function allowlistSatisfied(outcome) {
+    return outcome === 'listed' || outcome === 'already-listed' || outcome === 'removed' || outcome === 'absent' || outcome === 'unenforced';
+}
+/**
+ * `unenforced` is the ONLY safe way to skip, and it is gated on the client's
+ * own site key rather than on this file's credentials.
+ *
+ * The failure this shape exists to prevent: a production deployment that runs
+ * App Check but has no `RECAPTCHA_ADMIN_KEY_NAME` would, under a
+ * "missing config → skip" rule, report every custom domain ready while listing
+ * none of them. Configuration absence must therefore mean two different things
+ * depending on whether App Check is running at all — and the tell is
+ * `NEXT_PUBLIC_RECAPTCHA_PUBLIC_KEY`, which is exactly what
+ * `new ReCaptchaV3Provider(...)` is handed.
+ *
+ * The admin key name must also END with that site key. A resource name
+ * pointing at a different key would be written happily and attest nothing —
+ * the one misconfiguration whose symptom is indistinguishable from success.
+ */ function config() {
+    var _process_env_NEXT_PUBLIC_RECAPTCHA_PUBLIC_KEY, _process_env_RECAPTCHA_ADMIN_KEY_NAME;
+    const siteKey = String((_process_env_NEXT_PUBLIC_RECAPTCHA_PUBLIC_KEY = process.env.NEXT_PUBLIC_RECAPTCHA_PUBLIC_KEY) != null ? _process_env_NEXT_PUBLIC_RECAPTCHA_PUBLIC_KEY : '').trim();
+    const keyName = String((_process_env_RECAPTCHA_ADMIN_KEY_NAME = process.env.RECAPTCHA_ADMIN_KEY_NAME) != null ? _process_env_RECAPTCHA_ADMIN_KEY_NAME : '').trim();
+    if (!siteKey) return {
+        kind: 'unenforced'
+    };
+    if (!keyName) {
+        return {
+            kind: 'misconfigured',
+            detail: 'App Check runs here (NEXT_PUBLIC_RECAPTCHA_PUBLIC_KEY is set) but RECAPTCHA_ADMIN_KEY_NAME is not, so the allowlist cannot be written'
+        };
+    }
+    if (!/^projects\/[^/]+\/keys\/[^/]+$/.test(keyName)) {
+        return {
+            kind: 'misconfigured',
+            detail: `RECAPTCHA_ADMIN_KEY_NAME must be projects/{project}/keys/{siteKey}, got "${keyName}"`
+        };
+    }
+    if (!keyName.endsWith(`/${siteKey}`)) {
+        return {
+            kind: 'misconfigured',
+            detail: 'RECAPTCHA_ADMIN_KEY_NAME names a different key than NEXT_PUBLIC_RECAPTCHA_PUBLIC_KEY — writing it would allowlist a key nothing uses'
+        };
+    }
+    return {
+        kind: 'ready',
+        keyName
+    };
+}
+/**
+ * An OAuth token for the same service account firebase-admin already runs as.
+ *
+ * Not a second credential: `cert()`'s `getAccessToken()` requests
+ * `https://www.googleapis.com/auth/cloud-platform` among its scopes, which is
+ * the scope `recaptchaenterprise.googleapis.com` asks for. The account needs
+ * `recaptchaenterprise.keys.get` + `.update` on the project the KEY lives in —
+ * which is not `aglyn-main`; the key was migrated into its own project and
+ * that is the whole reason this was thought unautomatable.
+ */ async function accessToken() {
+    const credential = getApp().options.credential;
+    if (!credential) throw new Error('firebase-admin app has no credential');
+    const token = await credential.getAccessToken();
+    const value = token == null ? void 0 : token.access_token;
+    if (!value) throw new Error('credential returned no access token');
+    return value;
+}
+async function call(url, init) {
+    var _rest_headers;
+    const { token } = init, rest = _object_without_properties_loose(init, [
+        "token"
+    ]);
+    const response = await fetch(url, _extends({}, rest, {
+        headers: _extends({}, (_rest_headers = rest.headers) != null ? _rest_headers : {}, {
+            Authorization: `Bearer ${token}`,
+            'Content-Type': 'application/json'
+        }),
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
+    }));
+    const body = await response.json().catch(()=>({}));
+    return {
+        ok: response.ok,
+        status: response.status,
+        body
+    };
+}
+function domainsOf(key) {
+    var _key_webSettings;
+    const domains = key == null ? void 0 : (_key_webSettings = key.webSettings) == null ? void 0 : _key_webSettings.allowedDomains;
+    return Array.isArray(domains) ? domains.map((entry)=>String(entry)) : [];
+}
+function normalize(input) {
+    return String(input != null ? input : '').trim().toLowerCase().replace(/\.$/, '');
+}
+/**
+ * Read the key, apply `mutate` to its domains, write back, and prove the write.
+ *
+ * `mutate` returning `null` means "no write is needed" and is a success.
+ */ async function rewrite(domain, mutate) {
+    var _after_webSettings;
+    const settings = config();
+    if (settings.kind === 'unenforced') return {
+        outcome: 'unenforced',
+        domain
+    };
+    if (settings.kind === 'misconfigured') {
+        return {
+            outcome: 'failed',
+            domain,
+            detail: settings.detail
+        };
+    }
+    let token;
+    try {
+        token = await accessToken();
+    } catch (error) {
+        return {
+            outcome: 'failed',
+            domain,
+            detail: `credential: ${String(error)}`
+        };
+    }
+    const url = `${RECAPTCHA_API}/${settings.keyName}`;
+    let before;
+    try {
+        const read = await call(url, {
+            method: 'GET',
+            token
+        });
+        if (!read.ok) {
+            var _ref;
+            var _read_body_error, _read_body;
+            return {
+                outcome: 'failed',
+                domain,
+                detail: `read ${read.status}: ${(_ref = (_read_body = read.body) == null ? void 0 : (_read_body_error = _read_body.error) == null ? void 0 : _read_body_error.message) != null ? _ref : 'unknown'}`
+            };
+        }
+        before = read.body;
+    } catch (error) {
+        return {
+            outcome: 'failed',
+            domain,
+            detail: `read: ${String(error)}`
+        };
+    }
+    const current = domainsOf(before);
+    const plan = mutate(current);
+    if ('skip' in plan) {
+        return {
+            outcome: plan.skip,
+            domain,
+            detail: plan.detail,
+            allowedDomains: current
+        };
+    }
+    let after;
+    try {
+        const written = await call(`${url}?updateMask=webSettings.allowedDomains`, {
+            method: 'PATCH',
+            token,
+            body: JSON.stringify({
+                webSettings: {
+                    allowedDomains: plan.next
+                }
+            })
+        });
+        if (!written.ok) {
+            var _ref1;
+            var _written_body_error, _written_body;
+            return {
+                outcome: 'failed',
+                domain,
+                detail: `write ${written.status}: ${(_ref1 = (_written_body = written.body) == null ? void 0 : (_written_body_error = _written_body.error) == null ? void 0 : _written_body_error.message) != null ? _ref1 : 'unknown'}`,
+                allowedDomains: current
+            };
+        }
+        after = written.body;
+    } catch (error) {
+        return {
+            outcome: 'failed',
+            domain,
+            detail: `write: ${String(error)}`,
+            allowedDomains: current
+        };
+    }
+    // Hazard 1. The response is the authoritative post-state, so believe it
+    // rather than the request body. A mask that the API interpreted more
+    // broadly than intended shows up here as a missing sibling field or a
+    // vanished entry — and `allowAllDomains: true` would be a key open to every
+    // origin on the internet, which must never be a side effect of adding one.
+    const applied = domainsOf(after);
+    const lost = plan.next.filter((entry)=>!applied.includes(entry));
+    if (lost.length > 0) {
+        return {
+            outcome: 'failed',
+            domain,
+            detail: `the key did not keep every domain the write sent (missing: ${lost.join(', ')})`,
+            allowedDomains: applied
+        };
+    }
+    if ((after == null ? void 0 : (_after_webSettings = after.webSettings) == null ? void 0 : _after_webSettings.allowAllDomains) === true) {
+        return {
+            outcome: 'failed',
+            domain,
+            detail: 'the write left allowAllDomains true — the key would accept every origin',
+            allowedDomains: applied
+        };
+    }
+    return {
+        outcome: plan.outcome,
+        domain,
+        allowedDomains: applied
+    };
+}
+/**
+ * Put a custom console domain on the key, so a browser there can attest.
+ *
+ * Called by `activateConsoleDomain` for the **serving** name only. Redirect
+ * twins (`www.acme.com` → `acme.com`) never execute the console, never load
+ * reCAPTCHA, and would spend a slot of the 250 for nothing.
+ */ export async function allowConsoleOrigin(input) {
+    const domain = normalize(input);
+    if (!domain) return {
+        outcome: 'failed',
+        domain: '',
+        detail: 'No domain given'
+    };
+    return rewrite(domain, (current)=>{
+        if (current.includes(domain)) return {
+            skip: 'already-listed'
+        };
+        if (current.length >= MAX_ALLOWED_DOMAINS) {
+            return {
+                skip: 'full',
+                detail: `the key holds ${current.length} of ${MAX_ALLOWED_DOMAINS} domains`
+            };
+        }
+        return {
+            next: [
+                ...current,
+                domain
+            ],
+            outcome: 'listed'
+        };
+    });
+}
+/**
+ * Take a domain back off the key when its claim is released.
+ *
+ * Removes the EXACT entry and nothing else. A filter that matched subdomains
+ * would take `aglyn.com` off the key while releasing `console.aglyn.com` —
+ * and the entry it deleted is the one every Aglyn origin attests against.
+ */ export async function reclaimConsoleOrigin(input) {
+    const domain = normalize(input);
+    if (!domain) return {
+        outcome: 'failed',
+        domain: '',
+        detail: 'No domain given'
+    };
+    return rewrite(domain, (current)=>{
+        if (!current.includes(domain)) return {
+            skip: 'absent'
+        };
+        const next = current.filter((entry)=>entry !== domain);
+        if (next.length !== current.length - 1) {
+            return {
+                skip: 'failed',
+                detail: `removing ${domain} would have removed ${current.length - next.length} entries`
+            };
+        }
+        return {
+            next,
+            outcome: 'removed'
+        };
+    });
+}
+/**
+ * Read-only occupancy, for an operator asking "how many of the 250 are gone?"
+ *
+ * Deliberately returns the live list rather than a count: a count is what got
+ * quoted as a ceiling for two weeks.
+ */ export async function readConsoleOriginAllowlist() {
+    var _result_allowedDomains;
+    const result = await rewrite('', ()=>({
+            skip: 'absent'
+        }));
+    if (result.outcome === 'unenforced') {
+        return {
+            domains: null,
+            limit: MAX_ALLOWED_DOMAINS,
+            detail: 'App Check is not configured here'
+        };
+    }
+    if (result.outcome === 'failed') {
+        return {
+            domains: null,
+            limit: MAX_ALLOWED_DOMAINS,
+            detail: result.detail
+        };
+    }
+    return {
+        domains: (_result_allowedDomains = result.allowedDomains) != null ? _result_allowedDomains : [],
+        limit: MAX_ALLOWED_DOMAINS
+    };
+}
+
+//# sourceMappingURL=recaptcha-allowlist.js.map

package/src/lib/server/recaptcha-allowlist.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/recaptcha-allowlist.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 App Check reCAPTCHA allowlist, written from the product (AGL-1378).\n *\n * ## Why this file has to exist\n *\n * The console reads Firestore **client-side**, and App Check gates those reads\n * with a reCAPTCHA token that the key itself refuses to mint on an origin it\n * has never heard of. Measured against the live key on 2026-08-23, with both\n * controls, by requesting `recaptcha/api2/anchor` with a base64 `co` origin:\n *\n * ```\n * https://app.aglyn.com:443                    ACCEPTED   (listed)\n * https://never-registered-9f3x.aglyn.com:443  ACCEPTED   (subtree of a listed entry)\n * https://console.acme-agency.example:443      REJECTED   \"Invalid domain for site key\"\n * https://console.northwind-coffee.com:443     REJECTED   \"Invalid domain for site key\"\n * ```\n *\n * A rejected solve means `initializeAppCheck` → `getToken` fails with\n * `appCheck/recaptcha-error`, and the very next Identity Platform call is\n * refused `401 UNAUTHENTICATED — \"Firebase App Check token is invalid\"`\n * **before** token validation (`docs/design/agl-1099a-poc-findings.md` §2).\n * So a custom console domain that is attached and routed but not allowlisted\n * renders a console that can never sign anyone in — and the symptom the\n * customer reports is \"Missing or insufficient permissions\", which is the same\n * string a Security Rules verdict produces. That is the misdiagnosis this\n * whole area keeps generating; the fix is to never let the state exist.\n *\n * ## Why it was believed impossible, and why that is stale\n *\n * AGL-1378 concluded the key was a classic v3 key with no management API. The\n * key was auto-migrated into a Google-created project, and every probe asked\n * `aglyn-main` — where the reCAPTCHA API genuinely is disabled — rather than\n * the project the key actually lives in. Measured 2026-08-23:\n * `recaptchaenterprise.googleapis.com` is enabled there, two accounts we\n * control are `roles/owner`, and `projects.keys.patch` on\n * `webSettings.allowedDomains` answers `200`.\n *\n * ## The two hazards this code is shaped around\n *\n * 1. **A patch that drops sibling fields.** `webSettings` also carries\n *    `allowAllDomains`, `integrationType`, `allowAmpTraffic` and\n *    `challengeSecurityPreference`; a whole-object write that omitted\n *    `allowAllDomains` would read as `false`… or a future default. So the mask\n *    is `webSettings.allowedDomains` — the narrowest path the API accepts —\n *    **and** the response is re-read afterwards: every domain that was there\n *    before must still be there, and `allowAllDomains` must still be `false`.\n *    A write that silently widened the key to every origin is a worse outcome\n *    than the domain never being listed.\n * 2. **Silent success.** Every outcome here is explicit, and\n *    {@link allowlistSatisfied} is the ONLY place that decides which ones mean\n *    \"the customer can actually sign in\". `activateConsoleDomain` refuses to\n *    mark a claim `active` unless it says yes.\n *\n * ## Exact names, never subtree cover\n *\n * A listed entry covers its whole subtree but never its parents (proved\n * 2026-08-10). It is therefore tempting to skip the write when some existing\n * entry already covers the new name. Deliberately not done: if org A holds\n * `acme.com` and org B later claims `console.acme.com`, B would be silently\n * covered by A's entry — and A detaching would break B with no trace linking\n * the two. One entry per claimed apex is what the documented 250-domain\n * ceiling is denominated in anyway (250 distinct customer apexes, occupancy 5\n * on 2026-08-23), so exactness costs nothing we were not already counting.\n */\n\nimport { getApp } from 'firebase-admin/app'\n\nconst RECAPTCHA_API = 'https://recaptchaenterprise.googleapis.com/v1'\n\n/**\n * Published ceiling for `webSettings.allowedDomains`, quoted rather than\n * measured: *\"Each key supports a maximum of 250 domains.\"* An occupancy\n * reading is NOT a limit — this repo already spent two weeks treating a\n * snapshot of nine entries as a hard ceiling. Re-probe occupancy, never the\n * limit.\n */\nexport const MAX_ALLOWED_DOMAINS = 250\n\n/**\n * Ceiling on the whole exchange, matching `workspace-domains.ts`.\n *\n * This one is awaited by an attach the operator is watching, so an\n * unresponsive Google API must lose quickly rather than hang the activation\n * until the platform kills the function.\n */\nconst REQUEST_TIMEOUT_MS = 8_000\n\nexport type RecaptchaAllowlistOutcome =\n  /** We wrote the entry and re-read the key to confirm it. */\n  | 'listed'\n  /** The exact name was already on the key; nothing was written. */\n  | 'already-listed'\n  /** We removed the entry and re-read the key to confirm it. */\n  | 'removed'\n  /** Nothing to remove — the exact name was not on the key. */\n  | 'absent'\n  /**\n   * This deployment runs no App Check reCAPTCHA provider, so there is no\n   * allowlist to maintain and nothing is gated. Self-host, and local dev.\n   */\n  | 'unenforced'\n  /** The key is at {@link MAX_ALLOWED_DOMAINS}. A commercial event, not a bug. */\n  | 'full'\n  /** Anything else: misconfiguration, IAM, transport, or a suspicious write. */\n  | 'failed'\n\nexport interface RecaptchaAllowlistResult {\n  outcome: RecaptchaAllowlistOutcome\n  domain: string\n  /** Human-readable cause. Always set when the outcome is not a success. */\n  detail?: string\n  /**\n   * Live `allowedDomains` after the operation, when we got far enough to read\n   * them. Occupancy is worth surfacing precisely because it must never be\n   * quoted from memory.\n   */\n  allowedDomains?: string[]\n}\n\n/**\n * Does this outcome mean the origin can attest?\n *\n * The single decision point, so that no caller can invent a looser one. Note\n * what is NOT here: `full` and `failed` both leave a domain that will 401 its\n * customer at sign-in, and `full` is the easier of the two to mistake for a\n * warning.\n */\nexport function allowlistSatisfied(outcome: RecaptchaAllowlistOutcome): boolean {\n  return (\n    outcome === 'listed' ||\n    outcome === 'already-listed' ||\n    outcome === 'removed' ||\n    outcome === 'absent' ||\n    outcome === 'unenforced'\n  )\n}\n\ntype Config =\n  | { kind: 'unenforced' }\n  | { kind: 'misconfigured'; detail: string }\n  | { kind: 'ready'; keyName: string }\n\n/**\n * `unenforced` is the ONLY safe way to skip, and it is gated on the client's\n * own site key rather than on this file's credentials.\n *\n * The failure this shape exists to prevent: a production deployment that runs\n * App Check but has no `RECAPTCHA_ADMIN_KEY_NAME` would, under a\n * \"missing config → skip\" rule, report every custom domain ready while listing\n * none of them. Configuration absence must therefore mean two different things\n * depending on whether App Check is running at all — and the tell is\n * `NEXT_PUBLIC_RECAPTCHA_PUBLIC_KEY`, which is exactly what\n * `new ReCaptchaV3Provider(...)` is handed.\n *\n * The admin key name must also END with that site key. A resource name\n * pointing at a different key would be written happily and attest nothing —\n * the one misconfiguration whose symptom is indistinguishable from success.\n */\nfunction config(): Config {\n  const siteKey = String(process.env.NEXT_PUBLIC_RECAPTCHA_PUBLIC_KEY ?? '').trim()\n  const keyName = String(process.env.RECAPTCHA_ADMIN_KEY_NAME ?? '').trim()\n  if (!siteKey) return { kind: 'unenforced' }\n  if (!keyName) {\n    return {\n      kind: 'misconfigured',\n      detail:\n        'App Check runs here (NEXT_PUBLIC_RECAPTCHA_PUBLIC_KEY is set) but RECAPTCHA_ADMIN_KEY_NAME is not, so the allowlist cannot be written',\n    }\n  }\n  if (!/^projects\\/[^/]+\\/keys\\/[^/]+$/.test(keyName)) {\n    return {\n      kind: 'misconfigured',\n      detail: `RECAPTCHA_ADMIN_KEY_NAME must be projects/{project}/keys/{siteKey}, got \"${keyName}\"`,\n    }\n  }\n  if (!keyName.endsWith(`/${siteKey}`)) {\n    return {\n      kind: 'misconfigured',\n      detail:\n        'RECAPTCHA_ADMIN_KEY_NAME names a different key than NEXT_PUBLIC_RECAPTCHA_PUBLIC_KEY — writing it would allowlist a key nothing uses',\n    }\n  }\n  return { kind: 'ready', keyName }\n}\n\n/**\n * An OAuth token for the same service account firebase-admin already runs as.\n *\n * Not a second credential: `cert()`'s `getAccessToken()` requests\n * `https://www.googleapis.com/auth/cloud-platform` among its scopes, which is\n * the scope `recaptchaenterprise.googleapis.com` asks for. The account needs\n * `recaptchaenterprise.keys.get` + `.update` on the project the KEY lives in —\n * which is not `aglyn-main`; the key was migrated into its own project and\n * that is the whole reason this was thought unautomatable.\n */\nasync function accessToken(): Promise<string> {\n  const credential = getApp().options.credential\n  if (!credential) throw new Error('firebase-admin app has no credential')\n  const token = await credential.getAccessToken()\n  const value = token?.access_token\n  if (!value) throw new Error('credential returned no access token')\n  return value\n}\n\nasync function call(\n  url: string,\n  init: RequestInit & { token: string },\n): Promise<{ ok: boolean; status: number; body: any }> {\n  const { token, ...rest } = init\n  const response = await fetch(url, {\n    ...rest,\n    headers: {\n      ...(rest.headers ?? {}),\n      Authorization: `Bearer ${token}`,\n      'Content-Type': 'application/json',\n    },\n    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),\n  })\n  const body = await response.json().catch(() => ({}))\n  return { ok: response.ok, status: response.status, body }\n}\n\nfunction domainsOf(key: any): string[] {\n  const domains = key?.webSettings?.allowedDomains\n  return Array.isArray(domains) ? domains.map((entry: unknown) => String(entry)) : []\n}\n\nfunction normalize(input: string): string {\n  return String(input ?? '')\n    .trim()\n    .toLowerCase()\n    .replace(/\\.$/, '')\n}\n\n/**\n * Read the key, apply `mutate` to its domains, write back, and prove the write.\n *\n * `mutate` returning `null` means \"no write is needed\" and is a success.\n */\nasync function rewrite(\n  domain: string,\n  mutate: (\n    current: string[],\n  ) =>\n    | { next: string[]; outcome: RecaptchaAllowlistOutcome }\n    | { skip: RecaptchaAllowlistOutcome; detail?: string },\n): Promise<RecaptchaAllowlistResult> {\n  const settings = config()\n  if (settings.kind === 'unenforced') return { outcome: 'unenforced', domain }\n  if (settings.kind === 'misconfigured') {\n    return { outcome: 'failed', domain, detail: settings.detail }\n  }\n\n  let token: string\n  try {\n    token = await accessToken()\n  } catch (error) {\n    return { outcome: 'failed', domain, detail: `credential: ${String(error)}` }\n  }\n\n  const url = `${RECAPTCHA_API}/${settings.keyName}`\n  let before: any\n  try {\n    const read = await call(url, { method: 'GET', token })\n    if (!read.ok) {\n      return {\n        outcome: 'failed',\n        domain,\n        detail: `read ${read.status}: ${read.body?.error?.message ?? 'unknown'}`,\n      }\n    }\n    before = read.body\n  } catch (error) {\n    return { outcome: 'failed', domain, detail: `read: ${String(error)}` }\n  }\n\n  const current = domainsOf(before)\n  const plan = mutate(current)\n  if ('skip' in plan) {\n    return {\n      outcome: plan.skip,\n      domain,\n      detail: plan.detail,\n      allowedDomains: current,\n    }\n  }\n\n  let after: any\n  try {\n    const written = await call(`${url}?updateMask=webSettings.allowedDomains`, {\n      method: 'PATCH',\n      token,\n      body: JSON.stringify({ webSettings: { allowedDomains: plan.next } }),\n    })\n    if (!written.ok) {\n      return {\n        outcome: 'failed',\n        domain,\n        detail: `write ${written.status}: ${written.body?.error?.message ?? 'unknown'}`,\n        allowedDomains: current,\n      }\n    }\n    after = written.body\n  } catch (error) {\n    return { outcome: 'failed', domain, detail: `write: ${String(error)}`, allowedDomains: current }\n  }\n\n  // Hazard 1. The response is the authoritative post-state, so believe it\n  // rather than the request body. A mask that the API interpreted more\n  // broadly than intended shows up here as a missing sibling field or a\n  // vanished entry — and `allowAllDomains: true` would be a key open to every\n  // origin on the internet, which must never be a side effect of adding one.\n  const applied = domainsOf(after)\n  const lost = plan.next.filter((entry) => !applied.includes(entry))\n  if (lost.length > 0) {\n    return {\n      outcome: 'failed',\n      domain,\n      detail: `the key did not keep every domain the write sent (missing: ${lost.join(', ')})`,\n      allowedDomains: applied,\n    }\n  }\n  if (after?.webSettings?.allowAllDomains === true) {\n    return {\n      outcome: 'failed',\n      domain,\n      detail: 'the write left allowAllDomains true — the key would accept every origin',\n      allowedDomains: applied,\n    }\n  }\n\n  return { outcome: plan.outcome, domain, allowedDomains: applied }\n}\n\n/**\n * Put a custom console domain on the key, so a browser there can attest.\n *\n * Called by `activateConsoleDomain` for the **serving** name only. Redirect\n * twins (`www.acme.com` → `acme.com`) never execute the console, never load\n * reCAPTCHA, and would spend a slot of the 250 for nothing.\n */\nexport async function allowConsoleOrigin(\n  input: string,\n): Promise<RecaptchaAllowlistResult> {\n  const domain = normalize(input)\n  if (!domain) return { outcome: 'failed', domain: '', detail: 'No domain given' }\n  return rewrite(domain, (current) => {\n    if (current.includes(domain)) return { skip: 'already-listed' as const }\n    if (current.length >= MAX_ALLOWED_DOMAINS) {\n      return {\n        skip: 'full' as const,\n        detail: `the key holds ${current.length} of ${MAX_ALLOWED_DOMAINS} domains`,\n      }\n    }\n    return { next: [...current, domain], outcome: 'listed' as const }\n  })\n}\n\n/**\n * Take a domain back off the key when its claim is released.\n *\n * Removes the EXACT entry and nothing else. A filter that matched subdomains\n * would take `aglyn.com` off the key while releasing `console.aglyn.com` —\n * and the entry it deleted is the one every Aglyn origin attests against.\n */\nexport async function reclaimConsoleOrigin(\n  input: string,\n): Promise<RecaptchaAllowlistResult> {\n  const domain = normalize(input)\n  if (!domain) return { outcome: 'failed', domain: '', detail: 'No domain given' }\n  return rewrite(domain, (current) => {\n    if (!current.includes(domain)) return { skip: 'absent' as const }\n    const next = current.filter((entry) => entry !== domain)\n    if (next.length !== current.length - 1) {\n      return {\n        skip: 'failed' as const,\n        detail: `removing ${domain} would have removed ${current.length - next.length} entries`,\n      }\n    }\n    return { next, outcome: 'removed' as const }\n  })\n}\n\n/**\n * Read-only occupancy, for an operator asking \"how many of the 250 are gone?\"\n *\n * Deliberately returns the live list rather than a count: a count is what got\n * quoted as a ceiling for two weeks.\n */\nexport async function readConsoleOriginAllowlist(): Promise<{\n  domains: string[] | null\n  limit: number\n  detail?: string\n}> {\n  const result = await rewrite('', () => ({ skip: 'absent' as const }))\n  if (result.outcome === 'unenforced') {\n    return { domains: null, limit: MAX_ALLOWED_DOMAINS, detail: 'App Check is not configured here' }\n  }\n  if (result.outcome === 'failed') {\n    return { domains: null, limit: MAX_ALLOWED_DOMAINS, detail: result.detail }\n  }\n  return { domains: result.allowedDomains ?? [], limit: MAX_ALLOWED_DOMAINS }\n}\n"],"names":["getApp","RECAPTCHA_API","MAX_ALLOWED_DOMAINS","REQUEST_TIMEOUT_MS","allowlistSatisfied","outcome","config","process","siteKey","String","env","NEXT_PUBLIC_RECAPTCHA_PUBLIC_KEY","trim","keyName","RECAPTCHA_ADMIN_KEY_NAME","kind","detail","test","endsWith","accessToken","credential","options","Error","token","getAccessToken","value","access_token","call","url","init","rest","response","fetch","headers","Authorization","signal","AbortSignal","timeout","body","json","catch","ok","status","domainsOf","key","domains","webSettings","allowedDomains","Array","isArray","map","entry","normalize","input","toLowerCase","replace","rewrite","domain","mutate","after","settings","error","before","read","method","message","current","plan","skip","written","JSON","stringify","next","applied","lost","filter","includes","length","join","allowAllDomains","allowConsoleOrigin","reclaimConsoleOrigin","readConsoleOriginAllowlist","result","limit"],"mappings":"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"}

package/src/lib/server/release-flags.d.ts

@@ -0,0 +1,105 @@
+/**
+ * @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 OrgPlan, type OrgReleaseFlagOverrides, type ReleaseFlagKey, type ReleaseFlagValue } from '@aglyn/aglyn/server';
+export declare function getServerReleaseFlagValues(): Promise<Record<ReleaseFlagKey, ReleaseFlagValue>>;
+/**
+ * Per-org release-flag overrides (AGL-1635), read off `orgs/{orgId}`.
+ *
+ * Cached on the same TTL as the template read above, and for the same
+ * reason: these are consulted on every published page render and every API
+ * dispatch, so an uncached read would add a Firestore round trip to the hot
+ * path. A grant therefore takes up to a minute to land, matching how long a
+ * flag flip already takes — one propagation story, not two.
+ *
+ * Keyed by orgId because a subject may be a uid or a hostId, and only an
+ * org can carry overrides. Failure is silent and yields `{}`: a missing org
+ * doc or a denied read must gate exactly as "no override set", never as an
+ * error that takes a published page down.
+ */
+/**
+ * What one org read answers about release flags: the staff overrides, and
+ * the org's EFFECTIVE plan for tier targeting (AGL-2486).
+ *
+ * `plan` is null when the read did not produce an org document — missing,
+ * denied, or no Firestore at all. Deliberately not `'free'`: an org whose
+ * doc could not be read has an UNKNOWN tier, and
+ * `resolveEffectivePlan(undefined)` answers `'free'`, which would hand a
+ * Free-targeted flag to every org the read failed for. The two cases have to
+ * stay distinguishable at the boundary, because the evaluator treats an
+ * unknown plan as a refusal and a known `'free'` as a match.
+ */
+interface OrgReleaseFlagTargeting {
+    overrides: OrgReleaseFlagOverrides;
+    plan: OrgPlan | null;
+}
+/**
+ * Both halves of the per-org answer from ONE cached document read.
+ *
+ * Sharing the read is the point: `plan` and `releaseFlags` live on the same
+ * org document, this runs on every published page render and every API
+ * dispatch, and fetching the tier separately would have doubled the hot-path
+ * Firestore traffic to learn something already in hand.
+ */
+export declare function getOrgReleaseFlagTargeting(orgId: string | null | undefined): Promise<OrgReleaseFlagTargeting>;
+export declare function getOrgReleaseFlagOverrides(orgId: string | null | undefined): Promise<OrgReleaseFlagOverrides>;
+/**
+ * The verdict for ONE flag and ONE org, overrides applied (AGL-1635).
+ *
+ * The surfaces that gate a single flag server-side — the tenant admin bar
+ * slot, edit-context redemption, edit-access minting — resolve through here
+ * rather than reading `getServerReleaseFlagValues()` and calling
+ * `isReleaseFlagOn` themselves, so a per-org grant reaches all of them at
+ * once. A gate that kept the old two-step would silently ignore overrides,
+ * which is the failure this issue exists to fix.
+ */
+export declare function isServerReleaseFlagOnForOrg(flagKey: ReleaseFlagKey, orgId: string | null | undefined): Promise<boolean>;
+/** Test seam: drops both caches so a spec can change a verdict. */
+export declare function __resetReleaseFlagCaches(): void;
+/**
+ * The server half of the plugin release gate (AGL-422): subtracts
+ * flagged-off first-party plugins from an effective set. The staff bypass is
+ * only paid for when something was actually subtracted AND the request
+ * carries a bearer token — the common all-flags-on path never verifies.
+ *
+ * `orgId` is the ONLY subject: it selects the per-org overrides (AGL-1635)
+ * and it is the rollout bucket. AGL-1635 took a separate `subjectId` here
+ * because callers fell back to a hostId when the org lookup missed, and a
+ * hostId must never be read as an org id. AGL-1656 removed that fallback
+ * instead of accommodating it — a hostId and an orgId hash to different
+ * buckets, so a mid-rollout flag could land the published site and the
+ * console on opposite sides of the same percentage for the same workspace.
+ * With one subject the two cannot disagree by construction, and there is no
+ * longer a parameter through which a non-org subject could be reintroduced.
+ */
+export declare function filterEnabledPluginsByReleaseFlags(pluginIds: readonly string[], options: {
+    /**
+     * The org this request belongs to: rollout bucket AND override key.
+     * Null when no org could be resolved — a subject-less request gets the
+     * fully-enabled flags only, never a partial rollout.
+     */
+    orgId?: string | null;
+    /** Raw Authorization header, when the caller has one (API dispatch). */
+    authorization?: string | null;
+    /**
+     * The account a TOKENLESS request acts for, as its route proved it
+     * (AGL-2978) — see `PluginApiRequestSubject.uid`. Consulted for the staff
+     * preview only, and only when the request carries no bearer token: a
+     * request with a token is the token's, whatever else it names.
+     */
+    subjectUid?: string | null;
+}): Promise<string[]>;
+export {};