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

package/src/lib/server/sso-break-glass-owners.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/sso-break-glass-owners.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 * Break-glass by way of an org owner who lives OUTSIDE the SSO pool\n * (AGL-1888, option (a) — decided).\n *\n * ## Why this exists\n *\n * `assessSsoLockoutRisk` only ever looked inside the org's GCIP tenant, and\n * nothing inside that tenant can hold a credential the IdP does not mediate:\n * `provisionSsoPool` creates the pool with `emailSignInConfig.enabled: false`,\n * `/api/orgs/members/password` refuses outright on `tenantId`, and a social\n * login cannot be linked to a governed account at all. So the pre-flight was\n * unsatisfiable and enforcement was unreachable for every org.\n *\n * The way out is the account the pre-flight was always described as wanting:\n * *\"at least one org owner holding a project-level credential\"*. A\n * project-pool account is not in the tenant, so the enforcement sweep cannot\n * see it, let alone strip it — the same invisibility that made SSO users\n * disappear from the staff console (AGL-1122) is what makes this work.\n *\n * ## The property being checked\n *\n * **Could this person still sign in if the org's IdP stopped answering?** A\n * lapsed certificate, a deleted SAML application, a revoked provider config.\n * Every condition below exists because failing it means the answer is no —\n * or means we cannot establish that the answer is yes, which for a control\n * whose failure mode is \"a paying customer loses its console permanently\" is\n * the same thing.\n *\n *  1. **Role `owner`, not `admin`.** The narrow reading of the decision, and\n *     the strict one. An org whose only owner is an SSO account can promote a\n *     project-level member to owner — a self-serve action — so requiring the\n *     stronger role does not put anybody back in front of a support queue.\n *  2. **Present in the PROJECT pool**, resolved there directly rather than\n *     through {@link findUserByUidAcrossPools}: the question is not \"where\n *     does this uid live\", it is \"does a project-pool record exist\", and a\n *     cross-pool resolver answering with the tenant record would silently\n *     turn a pooled account into a qualifying one.\n *  3. **Not the emailless twin.** A cross-pool `signInWithCustomToken`\n *     manufactures a project-pool record with no address and no providers\n *     (AGL-1962/2005) — a record nobody can sign in as, and exactly the shape\n *     a bare existence check accepts. There is no separate test for it here:\n *     conditions (5) and (6) are each strictly stronger than\n *     {@link isIdentifiedUserRecord}, so calling that as well would be a\n *     guard no mutation can make fail — a control that reads as a check and\n *     is not one. The twin is rejected, and the spec names which condition\n *     does it.\n *  4. **NOT also in the org's tenant pool.** A uid in both pools is that same\n *     collision seen from the other side, and it makes the identity ambiguous\n *     at the moment it matters most. Refused rather than guessed.\n *  5. **Not disabled**, and **email verified**. The console refuses an\n *     unverified session before it reaches any org setting\n *     (`emailUnverifiedResponse`), so an unverified owner cannot turn\n *     enforcement back off — which is the entire job of a break-glass\n *     account. A credential that cannot be used is not a credential.\n *  6. **Holds a provider that is not the org's IdP.** Same rule the in-pool\n *     assessment uses, applied to the project-pool record.\n *  7. **Not on a domain the operator REQUIRES SSO for**\n *     ({@link evaluateSsoDomainPolicy}). This is the subtle one. A\n *     project-pool `@aglyn.com` password is a perfectly good credential right\n *     up until `AGLYN_SSO_DOMAIN_ENFORCEMENT` is switched on, at which point\n *     that identity is refused at sign-in and the break-glass account\n *     silently stops being one. `refused` is computed independently of the\n *     switch by design, so this reads the rule rather than today's setting.\n *\n * Note what is deliberately NOT required: that the credential be a password.\n * A project-pool `google.com` link survives a lapsed SAML certificate just as\n * a password does — the org's IdP does not mediate it. The residual is that a\n * customer whose IdP and mailbox are the same vendor (Workspace SAML plus\n * Workspace Google sign-in) has a correlated failure if the whole vendor\n * account is deleted rather than the SAML app; that is a narrower failure\n * than the one this control exists for, and the docs say so.\n *\n * ## Failing safe\n *\n * Every error path yields **no owners**, which makes the assessment unsafe\n * and enforcement refuse. `unavailable` is carried alongside so the refusal\n * can say \"we could not check\" instead of \"you have nobody\" — a swallowed\n * query that renders as a measured zero is worse than an error, because\n * nothing looks wrong.\n */\n\nimport { authForPool } from './auth-pools'\nimport { evaluateSsoDomainPolicy } from './sso-domain-policy'\nimport firebaseAdmin from './firebase-admin'\n\n/**\n * ## One predicate, two callers\n *\n * The seven conditions live in {@link qualifiesAsBreakGlassOwner}, asked of\n * ONE uid, because two places need the same answer about different people:\n *\n *  - {@link findBreakGlassOrgOwners} asks it of every owner on the roster,\n *    which is what the enforcement pre-flight consumes;\n *  - the ownership-transfer guard asks it of the person about to BECOME the\n *    only owner, before the transfer happens (AGL-1888).\n *\n * The second caller exists because an org has exactly one owner at a time —\n * `transferOrgOwnership` moves the role rather than adding a second holder —\n * so a transfer can move the whole of an org's break-glass protection onto an\n * account inside the pool, after the pre-flight has already passed, with the\n * sweep long since finished. The pre-flight is a gate at one moment; this is\n * the same question asked again at the only other moment the answer can\n * change. Written as one function rather than two so the transfer guard\n * cannot drift into a second, laxer definition of who counts.\n */\n\n/** An org owner who would still be able to sign in without the org's IdP. */\nexport interface SsoBreakGlassOwner {\n  uid: string\n  email: string | null\n  /** Project-pool sign-in methods, none of them the org's IdP. */\n  providers: string[]\n}\n\nexport interface SsoBreakGlassOwnerLookup {\n  owners: SsoBreakGlassOwner[]\n  /**\n   * True when a lookup failed for a reason that is not \"no such user\" — an\n   * Auth or Firestore outage. The owner list is then INCOMPLETE, not empty,\n   * and the caller must not report \"this org has nobody\" on the strength of\n   * it.\n   */\n  unavailable: boolean\n}\n\n/** Owners walked in one lookup. An org with more has other problems. */\nconst OWNER_SCAN_CAP = 25\n\n/** Firebase's \"this pool does not have that uid\" — a real negative. */\nconst NOT_FOUND = 'auth/user-not-found'\n\nconst codeOf = (error: unknown): string =>\n  String((error as { code?: unknown })?.code ?? '')\n\n/** Whether ONE account would still be a way in without the org's IdP. */\nexport interface SsoBreakGlassVerdict {\n  /** The qualifying owner, or null when this account does not count. */\n  owner: SsoBreakGlassOwner | null\n  /**\n   * A lookup failed for a reason that is not \"no such user\". `owner` is then\n   * null because we could not establish that it should be anything else —\n   * never because we established the account does not qualify. A caller must\n   * refuse on this, not treat it as a clean negative.\n   */\n  unavailable: boolean\n}\n\nconst DOES_NOT_QUALIFY: SsoBreakGlassVerdict = {\n  owner: null,\n  unavailable: false,\n}\nconst COULD_NOT_CHECK: SsoBreakGlassVerdict = { owner: null, unavailable: true }\n\n/**\n * The seven conditions, asked of one uid.\n *\n * Callers must distinguish the two answers that both carry a null owner. A\n * null owner with `unavailable` false means \"we checked, and no\"; a null owner\n * with `unavailable` true means \"we could not check\". Collapsing them is how a\n * swallowed query starts rendering as a measured zero.\n *\n * @param uid - the account being judged. NOT checked for org membership here;\n *   both callers establish that first, by different routes (a roster query,\n *   and `transferOrgOwnership`'s own \"must already be a member\" transaction).\n * @param providerId - the org's SAML provider id, so a project-pool record\n *   holding only that provider cannot qualify\n * @param tenantId - the org's GCIP pool, checked for the collision in (4)\n */\nexport async function qualifiesAsBreakGlassOwner(\n  uid: string,\n  providerId: string,\n  tenantId: string,\n): Promise<SsoBreakGlassVerdict> {\n  let record\n  try {\n    // Written inline rather than through a hoisted `projectPool` const so\n    // the AGL-1122 guard can SEE that the receiver is pool-scoped: it\n    // matches on the receiver text, and a variable named `projectPool` is\n    // indistinguishable to it from a bare `auth().getUser`. A guard that\n    // cannot read a legitimate call is one somebody widens, so the call\n    // site moves instead of the guard.\n    record = await authForPool(null).getUser(uid)\n  } catch (error) {\n    // Not in the project pool is the ORDINARY answer here — it means this\n    // owner signs in through the IdP like everyone else. Anything else is\n    // an outage, and an outage must not read as a clean negative.\n    if (codeOf(error) !== NOT_FOUND) {\n      console.error(`[sso] project-pool lookup failed for ${uid}`, error)\n      return COULD_NOT_CHECK\n    }\n    return DOES_NOT_QUALIFY\n  }\n  // (5) Both halves. A disabled account is not a way in, and an unverified\n  // address cannot reach an org setting to undo enforcement.\n  //\n  // These two also subsume (3): the emailless cross-pool artifact has no\n  // address, so it never gets past the line below. That is why there is no\n  // `isIdentifiedUserRecord` call here — it could never be the condition\n  // that rejects anything, and a guard no mutation can break is not a\n  // guard.\n  if (record.disabled) return DOES_NOT_QUALIFY\n  if (!record.email || !record.emailVerified) return DOES_NOT_QUALIFY\n  // (6) The same rule the in-pool assessment applies. Also the second half\n  // of (3): a record with no providers at all cannot qualify.\n  const providers = (record.providerData ?? [])\n    .map((info) => info?.providerId)\n    .filter((id): id is string => Boolean(id) && id !== providerId)\n  if (!providers.length) return DOES_NOT_QUALIFY\n  // (7) A domain the operator requires SSO for. Read from the RULE, not\n  // from whether the switch happens to be on today.\n  if (evaluateSsoDomainPolicy({ email: record.email, tenantId: null }).refused) {\n    return DOES_NOT_QUALIFY\n  }\n  // (4) Last, because it costs a call: the same uid in the org's own pool.\n  try {\n    await authForPool(tenantId).getUser(uid)\n    // It answered — this uid names an account in the pool as well, so the\n    // sweep will touch it and \"which record is this owner\" has no answer.\n    return DOES_NOT_QUALIFY\n  } catch (error) {\n    if (codeOf(error) !== NOT_FOUND) {\n      console.error(`[sso] tenant-pool lookup failed for ${uid}`, error)\n      return COULD_NOT_CHECK\n    }\n  }\n  return {\n    owner: { uid, email: record.email ?? null, providers },\n    unavailable: false,\n  }\n}\n\n/**\n * Org owners who hold a credential the org's IdP does not mediate.\n *\n * @param orgId - the organization being enforced\n * @param providerId - the org's SAML provider id, so a project-pool record\n *   holding only that provider cannot qualify\n * @param tenantId - the org's GCIP pool, checked for the collision in (4)\n */\nexport async function findBreakGlassOrgOwners(\n  orgId: string,\n  providerId: string,\n  tenantId: string,\n): Promise<SsoBreakGlassOwnerLookup> {\n  let ownerUids: string[]\n  try {\n    const snapshot = await firebaseAdmin\n      .app()\n      .firestore()\n      .collection('orgs')\n      .doc(orgId)\n      .collection('members')\n      .where('role', '==', 'owner')\n      .get()\n    ownerUids = snapshot.docs.slice(0, OWNER_SCAN_CAP).map((doc) => doc.id)\n  } catch (error) {\n    console.error(`[sso] owner roster read failed for ${orgId}`, error)\n    return { owners: [], unavailable: true }\n  }\n\n  const owners: SsoBreakGlassOwner[] = []\n  let unavailable = false\n\n  for (const uid of ownerUids) {\n    const verdict = await qualifiesAsBreakGlassOwner(uid, providerId, tenantId)\n    // Accumulated rather than returned early: one unreachable owner must not\n    // hide the qualifying one standing next to them, and it must not be\n    // forgotten either. An org is safe if ANY owner qualifies, and the caller\n    // still gets told the picture is incomplete.\n    if (verdict.unavailable) unavailable = true\n    if (verdict.owner) owners.push(verdict.owner)\n  }\n\n  return { owners, unavailable }\n}\n\nexport default findBreakGlassOrgOwners\n"],"names":["authForPool","evaluateSsoDomainPolicy","firebaseAdmin","OWNER_SCAN_CAP","NOT_FOUND","codeOf","error","String","code","DOES_NOT_QUALIFY","owner","unavailable","COULD_NOT_CHECK","qualifiesAsBreakGlassOwner","uid","providerId","tenantId","record","getUser","console","disabled","email","emailVerified","providers","providerData","map","info","filter","id","Boolean","length","refused","findBreakGlassOrgOwners","orgId","ownerUids","snapshot","app","firestore","collection","doc","where","get","docs","slice","owners","verdict","push"],"mappings":"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"}

package/src/lib/server/sso-domain-policy.d.ts

@@ -0,0 +1,140 @@
+/**
+ * @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 declare const SSO_REQUIRED_DOMAINS_ENV = "AGLYN_SSO_REQUIRED_DOMAINS";
+export type SsoRequiredDomains = Readonly<Record<string, string>>;
+/**
+ * Parse the configured domain→tenant map. Total: anything unparseable is
+ * dropped rather than throwing, because this sits on the authentication path
+ * and a malformed env var must not take sign-in down. A dropped entry fails
+ * OPEN (the domain is simply ungoverned), which is the safe direction for a
+ * rule whose only power is to refuse.
+ */
+export declare function parseSsoRequiredDomains(raw: string | null | undefined): SsoRequiredDomains;
+/**
+ * The operator's SSO-required domains. Empty unless configured — see above.
+ */
+export declare function ssoRequiredDomains(env?: Record<string, string | undefined>): SsoRequiredDomains;
+export type SsoDomainVerdict = 
+/** Domain is not governed. Any pool is fine — this is most of the world. */
+'allow-ungoverned'
+/** Governed domain, signed in through the tenant we designated for it. */
+ | 'allow-designated-tenant'
+/**
+ * Governed domain, signed in through SOME tenant, but not the designated
+ * one. Allowed — they did use SSO, and refusing would invent a restriction
+ * nobody asked for — but surfaced so a staff-access review can see it.
+ */
+ | 'allow-foreign-tenant'
+/**
+ * Governed domain with NO tenant at all: a project-pool password or consumer
+ * Google sign-in. The only refusal this policy ever produces.
+ */
+ | 'refuse-sso-required';
+export interface SsoDomainDecision {
+    verdict: SsoDomainVerdict;
+    /**
+     * Whether enforcement WOULD refuse this identity. Independent of whether
+     * enforcement is currently switched on — {@link ssoDomainEnforcementEnabled}
+     * decides that — so the same evaluation can drive both an audit in
+     * report-only mode and the refusal once the switch is flipped.
+     */
+    refused: boolean;
+    /** Lower-cased domain, or null when the identity has no email address. */
+    domain: string | null;
+    /** Tenant this domain is required to use, or null when ungoverned. */
+    requiredTenantId: string | null;
+    /** Tenant the identity actually signed in through; null = project pool. */
+    tenantId: string | null;
+    /** Worth a human look even though it is allowed (foreign-tenant case). */
+    reviewable: boolean;
+}
+export interface SsoDomainIdentity {
+    /** The identity's email address. Absent/empty is treated as ungoverned. */
+    email?: string | null;
+    /**
+     * GCIP tenant the identity signed in through — `decoded.firebase?.tenant`,
+     * or a `PooledUserRecord.tenantId`. Null/undefined means the project pool.
+     *
+     * Never inferred and never defaulted to a hard-coded tenant: a uid is only
+     * unique WITHIN a pool, and assuming one is how a lookup silently lands on
+     * the wrong record.
+     */
+    tenantId?: string | null;
+}
+/** The domain part of an address, lower-cased. Null when there isn't one. */
+export declare function domainOf(email: string | null | undefined): string | null;
+/**
+ * Decide the policy for one identity. Pure and total — no Firebase, no env —
+ * so a spec can drive every combination directly, and so the audit view and
+ * the enforcement path can never disagree about what the policy says.
+ */
+export declare function evaluateSsoDomainPolicy(identity: SsoDomainIdentity, domains?: SsoRequiredDomains): SsoDomainDecision;
+/**
+ * THE ENFORCEMENT SWITCH — ships OFF.
+ *
+ * Off means `evaluateSsoDomainPolicy` still computes `refused`, and callers
+ * still record it, but nobody is turned away. That is deliberate: the audit
+ * trail accumulates under the real rule before the rule bites, so flipping the
+ * switch holds no surprises.
+ *
+ * Opt-in by exact string. Anything else — unset, empty, `false`, `0`, a typo —
+ * is OFF. A security control that switches itself on through a misspelling is
+ * a control that can lock people out through a misspelling.
+ *
+ * Note both halves must be set for anything to happen: this switch AND a
+ * non-empty {@link SSO_REQUIRED_DOMAINS_ENV}. A self-host install that sets
+ * only this switch still governs nothing.
+ *
+ * **Precondition for flipping it — written down so it is not re-litigated:**
+ *  1. SSO staff access verified working through a REAL sign-in (not a token
+ *     inspection): a staff account reaches `/admin/*` via the SAML tenant.
+ *  2. Every identity on a governed domain has been migrated into its tenant or
+ *     retired. Measured on aglyn-main 2026-08-18: TWO would have been refused,
+ *     neither of them staff — one on a consumer `google.com` provider, and the
+ *     e2e smoke account on `password`. Flipping before migrating breaks the
+ *     e2e smoke sign-in, which is the one that bites without warning: it is an
+ *     AUTOMATION account, so nobody is watching a sign-in page when it fails.
+ *
+ * A second staff identity is NOT a precondition: the permanent break-glass
+ * account is on an ungoverned domain, so this rule can never refuse it.
+ */
+export declare const SSO_DOMAIN_ENFORCEMENT_ENV = "AGLYN_SSO_DOMAIN_ENFORCEMENT";
+export declare function ssoDomainEnforcementEnabled(env?: Record<string, string | undefined>): boolean;
+/**
+ * What the refused person is told. Names the fix, not the mechanism.
+ *
+ * `PLATFORM_BRAND_NAME`, not a literal (AGL-2214). Everything else in this
+ * module is careful that the RULE is configuration rather than a compiled-in
+ * assumption about Aglyn — and then the one string a refused person actually
+ * reads named us anyway. A self-hoster who governs their own domain would
+ * have turned their own staff away in our name.
+ *
+ * Byte-identical for a deployment that has not renamed itself.
+ */
+export declare const SSO_DOMAIN_REFUSAL_MESSAGE: string;
+/**
+ * The refusal a caller should return, or null to carry on.
+ *
+ * Returns null whenever the switch is off, so wiring this into an
+ * authentication path is inert until the account owner flips it — the call site is live,
+ * the consequence is not.
+ */
+export declare function ssoDomainRefusal(identity: SsoDomainIdentity, env?: Record<string, string | undefined>): {
+    decision: SsoDomainDecision;
+    response: Response;
+} | null;
+export default evaluateSsoDomainPolicy;

package/src/lib/server/sso-domain-policy.js

@@ -0,0 +1,239 @@
+/**
+ * @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.
+ */ /**
+ * Workspace-domain SSO policy (AGL-1993).
+ *
+ * **The rule is about a DOMAIN, not about staff.** An `@aglyn.com` address is a
+ * Google Workspace identity, and Workspace is what enforces MFA, disables an
+ * account at offboarding, and lets an admin revoke a session. An `@aglyn.com`
+ * address that signs in through a project-pool password or a consumer Google
+ * account has none of that: it looks like a company identity and is governed
+ * like a personal one. That gap is the whole reason this module exists.
+ *
+ * ## Staff is a SEPARATE axis and this module never reads it
+ *
+ * Staff may be granted to anybody — SSO or not, `@aglyn.com` or not, project
+ * pool or any GCIP tenant including a *customer's*. Nothing here consults the
+ * `staff` claim, and `sso-domain-policy.spec.ts` pins that by evaluating every
+ * staff permutation and asserting the verdict does not move. The two axes are
+ * independent; conflating them would turn a narrow domain control into an
+ * accidental SSO mandate for staff, which is explicitly not the policy.
+ *
+ * These all remain valid, and each has a test:
+ *
+ * | identity                                   | staff | verdict                   |
+ * | ------------------------------------------ | ----- | ------------------------- |
+ * | `@aglyn.com` in the designated tenant       | yes   | allowed                   |
+ * | personal address, project pool (break-glass)| yes   | allowed — permanent design|
+ * | personal address, project pool              | no    | allowed                   |
+ * | SSO identity in a CUSTOMER org's tenant     | yes   | allowed                   |
+ * | `@aglyn.com` in the PROJECT pool            | any   | **refused** when enforced |
+ *
+ * Only the last row is what the switch exists for.
+ *
+ * ## How this differs from `sso-enforcement.ts`
+ *
+ * {@link enforceSsoSignInMethods} (AGL-1128/1129) strips non-IdP providers from
+ * accounts that are ALREADY INSIDE a tenant. It cannot see an identity that
+ * never joined the tenant at all — a project-pool `@aglyn.com` account is
+ * invisible to every tenant sweep, by construction. Measured on aglyn-main on
+ * 2026-08-18: two such accounts existed, one of them holding a live
+ * `google.com` provider. This module covers that outside-the-tenant half.
+ *
+ * ## Shape note: deliberately NOT a discriminated union
+ *
+ * `strictNullChecks` is off repo-wide, which defeats boolean-discriminant
+ * narrowing — a spec can read the wrong arm of a union and pass silently. So
+ * the decision is ONE flat interface with a string `verdict`, and specs assert
+ * the literal. There is no arm to read by mistake.
+ */ /**
+ * ## Self-hosting: this policy is CONFIGURATION, never a compiled-in constant
+ *
+ * Aglyn ships in two shapes — the Aglyn-operated SaaS, and self-hosted installs
+ * on the operator's own Firebase project. `aglyn.com` is *our* Workspace
+ * domain; a self-hoster has their own domain, their own IdP, or none at all.
+ * Baking our domain in would make the rule dead weight for them at best and a
+ * lockout at worst, so the governed set is read from configuration and is
+ * **empty by default**.
+ *
+ * Empty means the rule does nothing. That is simultaneously the correct
+ * behaviour for a fresh self-host install and the correct OFF state for us —
+ * one default serving both, rather than a special case for either.
+ *
+ * Format — `domain=tenantId`, comma or whitespace separated:
+ *
+ * ```
+ * AGLYN_SSO_REQUIRED_DOMAINS="aglyn.com=aglyn-org-y5v14"
+ * ```
+ *
+ * A map rather than a bare list because "must use SSO" is meaningless without
+ * naming WHOSE SSO: the point is IdP lifecycle control, which only the tenant
+ * wired to that domain's SAML provider delivers.
+ */ import { PLATFORM_BRAND_NAME } from "@aglyn/aglyn/app-utils/platform-brand";
+export const SSO_REQUIRED_DOMAINS_ENV = 'AGLYN_SSO_REQUIRED_DOMAINS';
+/**
+ * Parse the configured domain→tenant map. Total: anything unparseable is
+ * dropped rather than throwing, because this sits on the authentication path
+ * and a malformed env var must not take sign-in down. A dropped entry fails
+ * OPEN (the domain is simply ungoverned), which is the safe direction for a
+ * rule whose only power is to refuse.
+ */ export function parseSsoRequiredDomains(raw) {
+    const map = {};
+    for (const pair of String(raw != null ? raw : '').split(/[,\s]+/)){
+        if (!pair) continue;
+        const eq = pair.indexOf('=');
+        if (eq <= 0) continue;
+        const domain = pair.slice(0, eq).trim().toLowerCase();
+        const tenantId = pair.slice(eq + 1).trim();
+        if (!domain || !tenantId) continue;
+        map[domain] = tenantId;
+    }
+    return map;
+}
+/**
+ * The operator's SSO-required domains. Empty unless configured — see above.
+ */ export function ssoRequiredDomains(env = process.env) {
+    return parseSsoRequiredDomains(env[SSO_REQUIRED_DOMAINS_ENV]);
+}
+/** The domain part of an address, lower-cased. Null when there isn't one. */ export function domainOf(email) {
+    const address = String(email != null ? email : '').trim().toLowerCase();
+    const at = address.lastIndexOf('@');
+    if (at < 0 || at === address.length - 1) return null;
+    return address.slice(at + 1);
+}
+/**
+ * Decide the policy for one identity. Pure and total — no Firebase, no env —
+ * so a spec can drive every combination directly, and so the audit view and
+ * the enforcement path can never disagree about what the policy says.
+ */ export function evaluateSsoDomainPolicy(identity, domains = ssoRequiredDomains()) {
+    var _identity_tenantId;
+    const domain = domainOf(identity.email);
+    const tenantId = (_identity_tenantId = identity.tenantId) != null ? _identity_tenantId : null;
+    // Exact-match lookup, never a suffix test: `notaglyn.com` ends with
+    // `aglyn.com`, and a suffix test would refuse an unrelated company's staff.
+    const requiredTenantId = domain ? Object.prototype.hasOwnProperty.call(domains, domain) ? domains[domain] : null : null;
+    if (!requiredTenantId) {
+        // Ungoverned: a personal address, a customer's address, anything not on
+        // the list. Includes the permanent break-glass account by construction
+        // rather than by special case — see the staff-access doc.
+        return {
+            verdict: 'allow-ungoverned',
+            refused: false,
+            domain,
+            requiredTenantId: null,
+            tenantId,
+            reviewable: false
+        };
+    }
+    if (tenantId === requiredTenantId) {
+        return {
+            verdict: 'allow-designated-tenant',
+            refused: false,
+            domain,
+            requiredTenantId,
+            tenantId,
+            reviewable: false
+        };
+    }
+    if (tenantId) {
+        // A governed address inside somebody else's tenant. They authenticated
+        // through an IdP, so the hole this policy closes is not open here — but
+        // the IdP is not one Aglyn controls, so it is flagged for review.
+        return {
+            verdict: 'allow-foreign-tenant',
+            refused: false,
+            domain,
+            requiredTenantId,
+            tenantId,
+            reviewable: true
+        };
+    }
+    return {
+        verdict: 'refuse-sso-required',
+        refused: true,
+        domain,
+        requiredTenantId,
+        tenantId: null,
+        reviewable: true
+    };
+}
+/**
+ * THE ENFORCEMENT SWITCH — ships OFF.
+ *
+ * Off means `evaluateSsoDomainPolicy` still computes `refused`, and callers
+ * still record it, but nobody is turned away. That is deliberate: the audit
+ * trail accumulates under the real rule before the rule bites, so flipping the
+ * switch holds no surprises.
+ *
+ * Opt-in by exact string. Anything else — unset, empty, `false`, `0`, a typo —
+ * is OFF. A security control that switches itself on through a misspelling is
+ * a control that can lock people out through a misspelling.
+ *
+ * Note both halves must be set for anything to happen: this switch AND a
+ * non-empty {@link SSO_REQUIRED_DOMAINS_ENV}. A self-host install that sets
+ * only this switch still governs nothing.
+ *
+ * **Precondition for flipping it — written down so it is not re-litigated:**
+ *  1. SSO staff access verified working through a REAL sign-in (not a token
+ *     inspection): a staff account reaches `/admin/*` via the SAML tenant.
+ *  2. Every identity on a governed domain has been migrated into its tenant or
+ *     retired. Measured on aglyn-main 2026-08-18: TWO would have been refused,
+ *     neither of them staff — one on a consumer `google.com` provider, and the
+ *     e2e smoke account on `password`. Flipping before migrating breaks the
+ *     e2e smoke sign-in, which is the one that bites without warning: it is an
+ *     AUTOMATION account, so nobody is watching a sign-in page when it fails.
+ *
+ * A second staff identity is NOT a precondition: the permanent break-glass
+ * account is on an ungoverned domain, so this rule can never refuse it.
+ */ export const SSO_DOMAIN_ENFORCEMENT_ENV = 'AGLYN_SSO_DOMAIN_ENFORCEMENT';
+export function ssoDomainEnforcementEnabled(env = process.env) {
+    return env[SSO_DOMAIN_ENFORCEMENT_ENV] === 'on';
+}
+/**
+ * What the refused person is told. Names the fix, not the mechanism.
+ *
+ * `PLATFORM_BRAND_NAME`, not a literal (AGL-2214). Everything else in this
+ * module is careful that the RULE is configuration rather than a compiled-in
+ * assumption about Aglyn — and then the one string a refused person actually
+ * reads named us anyway. A self-hoster who governs their own domain would
+ * have turned their own staff away in our name.
+ *
+ * Byte-identical for a deployment that has not renamed itself.
+ */ export const SSO_DOMAIN_REFUSAL_MESSAGE = `Sign in with your ${PLATFORM_BRAND_NAME} Workspace account ` + '(Single sign-on). Accounts on this domain cannot use a password or ' + 'personal Google sign-in.';
+/**
+ * The refusal a caller should return, or null to carry on.
+ *
+ * Returns null whenever the switch is off, so wiring this into an
+ * authentication path is inert until the account owner flips it — the call site is live,
+ * the consequence is not.
+ */ export function ssoDomainRefusal(identity, env = process.env) {
+    const decision = evaluateSsoDomainPolicy(identity, ssoRequiredDomains(env));
+    if (!decision.refused) return null;
+    if (!ssoDomainEnforcementEnabled(env)) return null;
+    return {
+        decision,
+        response: Response.json({
+            error: SSO_DOMAIN_REFUSAL_MESSAGE,
+            reason: 'sso-domain-required',
+            domain: decision.domain
+        }, {
+            status: 403
+        })
+    };
+}
+export default evaluateSsoDomainPolicy;
+
+//# sourceMappingURL=sso-domain-policy.js.map

package/src/lib/server/sso-domain-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/sso-domain-policy.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 * Workspace-domain SSO policy (AGL-1993).\n *\n * **The rule is about a DOMAIN, not about staff.** An `@aglyn.com` address is a\n * Google Workspace identity, and Workspace is what enforces MFA, disables an\n * account at offboarding, and lets an admin revoke a session. An `@aglyn.com`\n * address that signs in through a project-pool password or a consumer Google\n * account has none of that: it looks like a company identity and is governed\n * like a personal one. That gap is the whole reason this module exists.\n *\n * ## Staff is a SEPARATE axis and this module never reads it\n *\n * Staff may be granted to anybody — SSO or not, `@aglyn.com` or not, project\n * pool or any GCIP tenant including a *customer's*. Nothing here consults the\n * `staff` claim, and `sso-domain-policy.spec.ts` pins that by evaluating every\n * staff permutation and asserting the verdict does not move. The two axes are\n * independent; conflating them would turn a narrow domain control into an\n * accidental SSO mandate for staff, which is explicitly not the policy.\n *\n * These all remain valid, and each has a test:\n *\n * | identity                                   | staff | verdict                   |\n * | ------------------------------------------ | ----- | ------------------------- |\n * | `@aglyn.com` in the designated tenant       | yes   | allowed                   |\n * | personal address, project pool (break-glass)| yes   | allowed — permanent design|\n * | personal address, project pool              | no    | allowed                   |\n * | SSO identity in a CUSTOMER org's tenant     | yes   | allowed                   |\n * | `@aglyn.com` in the PROJECT pool            | any   | **refused** when enforced |\n *\n * Only the last row is what the switch exists for.\n *\n * ## How this differs from `sso-enforcement.ts`\n *\n * {@link enforceSsoSignInMethods} (AGL-1128/1129) strips non-IdP providers from\n * accounts that are ALREADY INSIDE a tenant. It cannot see an identity that\n * never joined the tenant at all — a project-pool `@aglyn.com` account is\n * invisible to every tenant sweep, by construction. Measured on aglyn-main on\n * 2026-08-18: two such accounts existed, one of them holding a live\n * `google.com` provider. This module covers that outside-the-tenant half.\n *\n * ## Shape note: deliberately NOT a discriminated union\n *\n * `strictNullChecks` is off repo-wide, which defeats boolean-discriminant\n * narrowing — a spec can read the wrong arm of a union and pass silently. So\n * the decision is ONE flat interface with a string `verdict`, and specs assert\n * the literal. There is no arm to read by mistake.\n */\n\n/**\n * ## Self-hosting: this policy is CONFIGURATION, never a compiled-in constant\n *\n * Aglyn ships in two shapes — the Aglyn-operated SaaS, and self-hosted installs\n * on the operator's own Firebase project. `aglyn.com` is *our* Workspace\n * domain; a self-hoster has their own domain, their own IdP, or none at all.\n * Baking our domain in would make the rule dead weight for them at best and a\n * lockout at worst, so the governed set is read from configuration and is\n * **empty by default**.\n *\n * Empty means the rule does nothing. That is simultaneously the correct\n * behaviour for a fresh self-host install and the correct OFF state for us —\n * one default serving both, rather than a special case for either.\n *\n * Format — `domain=tenantId`, comma or whitespace separated:\n *\n * ```\n * AGLYN_SSO_REQUIRED_DOMAINS=\"aglyn.com=aglyn-org-y5v14\"\n * ```\n *\n * A map rather than a bare list because \"must use SSO\" is meaningless without\n * naming WHOSE SSO: the point is IdP lifecycle control, which only the tenant\n * wired to that domain's SAML provider delivers.\n */\nimport { PLATFORM_BRAND_NAME } from '@aglyn/aglyn/app-utils/platform-brand'\n\nexport const SSO_REQUIRED_DOMAINS_ENV = 'AGLYN_SSO_REQUIRED_DOMAINS'\n\nexport type SsoRequiredDomains = Readonly<Record<string, string>>\n\n/**\n * Parse the configured domain→tenant map. Total: anything unparseable is\n * dropped rather than throwing, because this sits on the authentication path\n * and a malformed env var must not take sign-in down. A dropped entry fails\n * OPEN (the domain is simply ungoverned), which is the safe direction for a\n * rule whose only power is to refuse.\n */\nexport function parseSsoRequiredDomains(\n  raw: string | null | undefined,\n): SsoRequiredDomains {\n  const map: Record<string, string> = {}\n  for (const pair of String(raw ?? '').split(/[,\\s]+/)) {\n    if (!pair) continue\n    const eq = pair.indexOf('=')\n    if (eq <= 0) continue\n    const domain = pair.slice(0, eq).trim().toLowerCase()\n    const tenantId = pair.slice(eq + 1).trim()\n    if (!domain || !tenantId) continue\n    map[domain] = tenantId\n  }\n  return map\n}\n\n/**\n * The operator's SSO-required domains. Empty unless configured — see above.\n */\nexport function ssoRequiredDomains(\n  env: Record<string, string | undefined> = process.env,\n): SsoRequiredDomains {\n  return parseSsoRequiredDomains(env[SSO_REQUIRED_DOMAINS_ENV])\n}\n\nexport type SsoDomainVerdict =\n  /** Domain is not governed. Any pool is fine — this is most of the world. */\n  | 'allow-ungoverned'\n  /** Governed domain, signed in through the tenant we designated for it. */\n  | 'allow-designated-tenant'\n  /**\n   * Governed domain, signed in through SOME tenant, but not the designated\n   * one. Allowed — they did use SSO, and refusing would invent a restriction\n   * nobody asked for — but surfaced so a staff-access review can see it.\n   */\n  | 'allow-foreign-tenant'\n  /**\n   * Governed domain with NO tenant at all: a project-pool password or consumer\n   * Google sign-in. The only refusal this policy ever produces.\n   */\n  | 'refuse-sso-required'\n\nexport interface SsoDomainDecision {\n  verdict: SsoDomainVerdict\n  /**\n   * Whether enforcement WOULD refuse this identity. Independent of whether\n   * enforcement is currently switched on — {@link ssoDomainEnforcementEnabled}\n   * decides that — so the same evaluation can drive both an audit in\n   * report-only mode and the refusal once the switch is flipped.\n   */\n  refused: boolean\n  /** Lower-cased domain, or null when the identity has no email address. */\n  domain: string | null\n  /** Tenant this domain is required to use, or null when ungoverned. */\n  requiredTenantId: string | null\n  /** Tenant the identity actually signed in through; null = project pool. */\n  tenantId: string | null\n  /** Worth a human look even though it is allowed (foreign-tenant case). */\n  reviewable: boolean\n}\n\nexport interface SsoDomainIdentity {\n  /** The identity's email address. Absent/empty is treated as ungoverned. */\n  email?: string | null\n  /**\n   * GCIP tenant the identity signed in through — `decoded.firebase?.tenant`,\n   * or a `PooledUserRecord.tenantId`. Null/undefined means the project pool.\n   *\n   * Never inferred and never defaulted to a hard-coded tenant: a uid is only\n   * unique WITHIN a pool, and assuming one is how a lookup silently lands on\n   * the wrong record.\n   */\n  tenantId?: string | null\n}\n\n/** The domain part of an address, lower-cased. Null when there isn't one. */\nexport function domainOf(email: string | null | undefined): string | null {\n  const address = String(email ?? '').trim().toLowerCase()\n  const at = address.lastIndexOf('@')\n  if (at < 0 || at === address.length - 1) return null\n  return address.slice(at + 1)\n}\n\n/**\n * Decide the policy for one identity. Pure and total — no Firebase, no env —\n * so a spec can drive every combination directly, and so the audit view and\n * the enforcement path can never disagree about what the policy says.\n */\nexport function evaluateSsoDomainPolicy(\n  identity: SsoDomainIdentity,\n  domains: SsoRequiredDomains = ssoRequiredDomains(),\n): SsoDomainDecision {\n  const domain = domainOf(identity.email)\n  const tenantId = identity.tenantId ?? null\n  // Exact-match lookup, never a suffix test: `notaglyn.com` ends with\n  // `aglyn.com`, and a suffix test would refuse an unrelated company's staff.\n  const requiredTenantId = domain\n    ? (Object.prototype.hasOwnProperty.call(domains, domain)\n        ? domains[domain]\n        : null)\n    : null\n\n  if (!requiredTenantId) {\n    // Ungoverned: a personal address, a customer's address, anything not on\n    // the list. Includes the permanent break-glass account by construction\n    // rather than by special case — see the staff-access doc.\n    return {\n      verdict: 'allow-ungoverned',\n      refused: false,\n      domain,\n      requiredTenantId: null,\n      tenantId,\n      reviewable: false,\n    }\n  }\n\n  if (tenantId === requiredTenantId) {\n    return {\n      verdict: 'allow-designated-tenant',\n      refused: false,\n      domain,\n      requiredTenantId,\n      tenantId,\n      reviewable: false,\n    }\n  }\n\n  if (tenantId) {\n    // A governed address inside somebody else's tenant. They authenticated\n    // through an IdP, so the hole this policy closes is not open here — but\n    // the IdP is not one Aglyn controls, so it is flagged for review.\n    return {\n      verdict: 'allow-foreign-tenant',\n      refused: false,\n      domain,\n      requiredTenantId,\n      tenantId,\n      reviewable: true,\n    }\n  }\n\n  return {\n    verdict: 'refuse-sso-required',\n    refused: true,\n    domain,\n    requiredTenantId,\n    tenantId: null,\n    reviewable: true,\n  }\n}\n\n/**\n * THE ENFORCEMENT SWITCH — ships OFF.\n *\n * Off means `evaluateSsoDomainPolicy` still computes `refused`, and callers\n * still record it, but nobody is turned away. That is deliberate: the audit\n * trail accumulates under the real rule before the rule bites, so flipping the\n * switch holds no surprises.\n *\n * Opt-in by exact string. Anything else — unset, empty, `false`, `0`, a typo —\n * is OFF. A security control that switches itself on through a misspelling is\n * a control that can lock people out through a misspelling.\n *\n * Note both halves must be set for anything to happen: this switch AND a\n * non-empty {@link SSO_REQUIRED_DOMAINS_ENV}. A self-host install that sets\n * only this switch still governs nothing.\n *\n * **Precondition for flipping it — written down so it is not re-litigated:**\n *  1. SSO staff access verified working through a REAL sign-in (not a token\n *     inspection): a staff account reaches `/admin/*` via the SAML tenant.\n *  2. Every identity on a governed domain has been migrated into its tenant or\n *     retired. Measured on aglyn-main 2026-08-18: TWO would have been refused,\n *     neither of them staff — one on a consumer `google.com` provider, and the\n *     e2e smoke account on `password`. Flipping before migrating breaks the\n *     e2e smoke sign-in, which is the one that bites without warning: it is an\n *     AUTOMATION account, so nobody is watching a sign-in page when it fails.\n *\n * A second staff identity is NOT a precondition: the permanent break-glass\n * account is on an ungoverned domain, so this rule can never refuse it.\n */\nexport const SSO_DOMAIN_ENFORCEMENT_ENV = 'AGLYN_SSO_DOMAIN_ENFORCEMENT'\n\nexport function ssoDomainEnforcementEnabled(\n  env: Record<string, string | undefined> = process.env,\n): boolean {\n  return env[SSO_DOMAIN_ENFORCEMENT_ENV] === 'on'\n}\n\n/**\n * What the refused person is told. Names the fix, not the mechanism.\n *\n * `PLATFORM_BRAND_NAME`, not a literal (AGL-2214). Everything else in this\n * module is careful that the RULE is configuration rather than a compiled-in\n * assumption about Aglyn — and then the one string a refused person actually\n * reads named us anyway. A self-hoster who governs their own domain would\n * have turned their own staff away in our name.\n *\n * Byte-identical for a deployment that has not renamed itself.\n */\nexport const SSO_DOMAIN_REFUSAL_MESSAGE =\n  `Sign in with your ${PLATFORM_BRAND_NAME} Workspace account ` +\n  '(Single sign-on). Accounts on this domain cannot use a password or ' +\n  'personal Google sign-in.'\n\n/**\n * The refusal a caller should return, or null to carry on.\n *\n * Returns null whenever the switch is off, so wiring this into an\n * authentication path is inert until the account owner flips it — the call site is live,\n * the consequence is not.\n */\nexport function ssoDomainRefusal(\n  identity: SsoDomainIdentity,\n  env: Record<string, string | undefined> = process.env,\n): { decision: SsoDomainDecision; response: Response } | null {\n  const decision = evaluateSsoDomainPolicy(identity, ssoRequiredDomains(env))\n  if (!decision.refused) return null\n  if (!ssoDomainEnforcementEnabled(env)) return null\n  return {\n    decision,\n    response: Response.json(\n      {\n        error: SSO_DOMAIN_REFUSAL_MESSAGE,\n        reason: 'sso-domain-required',\n        domain: decision.domain,\n      },\n      { status: 403 },\n    ),\n  }\n}\n\nexport default evaluateSsoDomainPolicy\n"],"names":["PLATFORM_BRAND_NAME","SSO_REQUIRED_DOMAINS_ENV","parseSsoRequiredDomains","raw","map","pair","String","split","eq","indexOf","domain","slice","trim","toLowerCase","tenantId","ssoRequiredDomains","env","process","domainOf","email","address","at","lastIndexOf","length","evaluateSsoDomainPolicy","identity","domains","requiredTenantId","Object","prototype","hasOwnProperty","call","verdict","refused","reviewable","SSO_DOMAIN_ENFORCEMENT_ENV","ssoDomainEnforcementEnabled","SSO_DOMAIN_REFUSAL_MESSAGE","ssoDomainRefusal","decision","response","Response","json","error","reason","status"],"mappings":"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"}

package/src/lib/server/sso-drift-logic.d.ts

@@ -0,0 +1,106 @@
+/**
+ * @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.
+ */
+/**
+ * Has an SSO domain stopped proving it belongs to the org routing it, and is
+ * that conclusion safe to act on? (AGL-1210)
+ *
+ * PURE, and in its own file with NO imports at all — not `dns`, not
+ * `firebase-admin`. `sso-provisioning.ts` re-exports everything here, so the
+ * public surface is unchanged, but the decision can be required by a test on
+ * either side of the app/lib boundary without dragging in the admin SDK. The
+ * console route's spec does exactly that: it fakes the I/O and runs the REAL
+ * decision, which is the only arrangement where "the route obeys the rule"
+ * means anything.
+ *
+ * The reasoning for the policy itself lives in `sso-provisioning.ts`, next to
+ * the probe it interprets. In one line: a DNS lookup cannot distinguish "the
+ * record is gone" from "nobody answered", so the third state below is what
+ * stops a resolver blip from being read as every customer deleting their TXT
+ * record at the same instant.
+ */
+/**
+ * What a re-verification lookup actually established.
+ *
+ * The third state is the whole point. A resolver that did not answer has told
+ * us nothing, and "nothing" must not be counted as "gone".
+ */
+export type DomainProbeStatus = 
+/** The record is there and matches this org's token. */
+'proven'
+/** We got an ANSWER, and the token is not in it. Conclusive. */
+ | 'missing'
+/** Nobody answered. Not evidence of anything, in either direction. */
+ | 'unreachable';
+export interface DomainProbe {
+    status: DomainProbeStatus;
+    /** What the lookup saw — the difference between "gone" and "changed". */
+    records: string[];
+}
+/**
+ * Consecutive conclusive failures before a domain is REPORTED as drifted.
+ *
+ * Three, against a weekly sweep, is a three-week signal. Exported so the
+ * threshold is one named number rather than a literal buried in a loop, and so
+ * a test can state the boundary it is checking.
+ */
+export declare const SSO_DRIFT_FAILURES_BEFORE_REPORT = 3;
+/**
+ * And the wall-clock floor the same run must clear, independent of the count.
+ *
+ * Belt AND braces, because the two guard different mistakes. The count alone
+ * can be run up in three minutes by a staff member re-running the sweep by
+ * hand, or by a scheduler firing more often than anyone intended — and "we
+ * checked three times" reads as diligence while meaning nothing. The age alone
+ * would report a domain that failed once a month ago and has answered every
+ * time since. A report needs both.
+ */
+export declare const SSO_DRIFT_MIN_AGE_MS: number;
+/** The drift bookkeeping carried on a claim between sweeps. */
+export interface DomainDriftState {
+    /** Conclusive failures in a row. Reset by any single `proven`. */
+    consecutiveFailures: number;
+    /** When the current run of failures began. Null when there is no run. */
+    firstFailureAtMs: number | null;
+}
+export type DomainDriftAction = 
+/** Proven. Any failure run ends here. */
+'clear'
+/** Unreachable. Change nothing at all — this is not evidence. */
+ | 'hold'
+/** Conclusive failure, but not yet enough of them for long enough. */
+ | 'count'
+/** Enough, for long enough. Tell people. Still revoke nothing. */
+ | 'report';
+export interface DomainDriftVerdict {
+    action: DomainDriftAction;
+    /** The run length AFTER this probe. Unchanged on `hold`. */
+    consecutiveFailures: number;
+    /** Start of the run after this probe, for the next sweep to carry. */
+    firstFailureAtMs: number | null;
+}
+/**
+ * Should this probe change anything, and has the domain drifted?
+ *
+ * `hold` is the load-bearing arm. An `unreachable` probe neither increments
+ * the count nor resets it — an outage must not manufacture evidence, and must
+ * not launder away evidence already gathered either. The run simply pauses,
+ * and the next conclusive answer continues it.
+ *
+ * Note what this function CANNOT return: there is no `revoke`. Detection is
+ * the whole of its vocabulary, and revocation stays a human act.
+ */
+export declare function assessDomainDrift(probe: DomainProbe, prior: DomainDriftState, nowMs: number, failuresBeforeReport?: number, minAgeMs?: number): DomainDriftVerdict;