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

package/src/lib/server/sso-enforcement.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/sso-enforcement.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 * SSO enforcement sweep (AGL-1129): when an org turns on `sso.enforced`,\n * every account in its GCIP tenant loses any sign-in method that is not the\n * org's own IdP.\n *\n * AGL-1128 stopped SSO-governed accounts from linking NEW consumer providers.\n * This is the grandfathering half: an account that linked Google before\n * enforcement keeps a way in that the customer's IdP cannot see or revoke, and\n * a bypass that predates the switch is still a bypass.\n *\n * Runs against the TENANT pool via `authForPool` — project-level Admin SDK\n * calls cannot see, let alone mutate, these accounts (AGL-1122).\n *\n * Three properties this must have, in order of how badly they bite:\n *\n *  1. **Never unlink down to zero.** An account whose only provider is the one\n *     we are about to remove would be orphaned — reachable by nobody, not even\n *     the IdP. Skipped and reported, never assumed away: being in the tenant\n *     does not prove the SAML link is present.\n *  2. **Revoke refresh tokens for accounts it actually changed.** Unlinking\n *     does not end a live session, so without this the bypass simply has a\n *     clock on it. Only for accounts that changed — a sweep that revoked\n *     everyone would sign out the org's whole staff on a no-op run.\n *  3. **Idempotent.** Re-running is the natural way to catch accounts created\n *     between the flag flip and the sweep, so a second run must be a no-op\n *     rather than a second round of revocations.\n *  4. **Never leave the ORG with no way in** (AGL-1888). Property 1 protects\n *     one account at a time and is blind to the org-level failure: strip every\n *     account down to the SAML link and the pool is perfectly consistent right\n *     up until the IdP stops answering, at which point nobody can sign in and\n *     we cannot let them back in either. The `aglyn-org-y5v14` tenant is in\n *     that state today. So enforcement REFUSES unless the org keeps a way in\n *     that does\n *     not depend on the IdP: either a DESIGNATED break-glass account inside\n *     the pool, or an org owner who lives OUTSIDE it\n *     ({@link findBreakGlassOrgOwners}). The second is what makes the first\n *     satisfiable at all — nothing inside a pool we provisioned can hold a\n *     password, so for a while this guard could only ever say no.\n */\n\nimport type { UserRecord } from 'firebase-admin/auth'\nimport { FieldValue } from 'firebase-admin/firestore'\nimport { authForPool } from './auth-pools'\nimport {\n  findBreakGlassOrgOwners,\n  type SsoBreakGlassOwner,\n} from './sso-break-glass-owners'\nimport { invalidateTokenRevocationCache } from './token-revocation'\nimport firebaseAdmin from './firebase-admin'\nimport { notifyUsers } from './notifications'\n\nconst firestore = () => firebaseAdmin.app().firestore()\n\n/** How many tenant accounts one sweep will walk. Enterprise pools are small. */\nconst TENANT_USER_CAP = 1000\n\nexport interface SsoEnforcementOptions {\n  /** Staff uid recorded on the audit rows; `system` for an automated run. */\n  actorUid?: string\n  /** Report what would change without touching anything. */\n  dryRun?: boolean\n  /**\n   * Run even when `sso.enforced` is false. ONLY for a rehearsal against a\n   * throwaway account — the flag is the customer's instruction, and acting\n   * without it removes sign-in methods nobody asked us to remove.\n   */\n  force?: boolean\n}\n\n/** Why an account with removable providers was left alone. */\nexport type SsoEnforcementSkip = 'would-orphan' | 'break-glass'\n\nexport interface SsoEnforcementAccount {\n  uid: string\n  email: string | null\n  /** Providers removed (or that would be, in a dry run). */\n  unlinked: string[]\n  /** Providers left in place. */\n  kept: string[]\n  /** Why an account with removable providers was left alone. */\n  skipped?: SsoEnforcementSkip\n}\n\n/**\n * Whether this org would still have a way in if its IdP stopped answering\n * (AGL-1888).\n */\nexport interface SsoLockoutAssessment {\n  /**\n   * True when the org keeps at least one way in that its IdP does not\n   * mediate: a DESIGNATED break-glass account inside the pool, or an org\n   * owner outside it.\n   */\n  safe: boolean\n  /** Designated break-glass uids that actually retain a non-IdP credential. */\n  retainedBy: string[]\n  /**\n   * Designated uids that do NOT protect anybody — either absent from the pool,\n   * or holding nothing but the IdP link. Named rather than silently ignored:\n   * a designation that protects nothing is worse than none, because it reads\n   * as protection.\n   */\n  ineffective: string[]\n  /**\n   * Org owners in the PROJECT pool (AGL-1888 option (a)). The sweep cannot\n   * see these accounts, so an IdP that stops answering cannot lock them out.\n   * Named, not counted: the admin has to recognise the person.\n   */\n  ownersOutsidePool: SsoBreakGlassOwner[]\n  /**\n   * The owner lookup could not be completed. `ownersOutsidePool` is then\n   * INCOMPLETE rather than empty, so the refusal must say we could not check\n   * instead of asserting the org has nobody. Never makes an org safe.\n   */\n  ownerLookupFailed: boolean\n}\n\nexport interface SsoEnforcementResult {\n  orgId: string\n  tenantId: string\n  providerId: string\n  dryRun: boolean\n  /** Accounts walked. */\n  scanned: number\n  /** Accounts whose providers changed (0 on a converged re-run). */\n  changed: number\n  accounts: SsoEnforcementAccount[]\n  /** True when the tenant holds more accounts than one sweep walks. */\n  truncated: boolean\n  /**\n   * Whether the org retains a way in that does not depend on its IdP\n   * (AGL-1888). Present on the DRY RUN too — that is the point, since the\n   * rehearsal is where an org is supposed to discover it needs one.\n   */\n  lockout: SsoLockoutAssessment\n}\n\nexport class SsoEnforcementError extends Error {}\n\n/**\n * Strip non-IdP sign-in methods from every account in an org's SSO tenant.\n *\n * Throws when the org has no active SSO config, or when `sso.enforced` is\n * false without `force` — enforcement is the customer's switch, and running\n * this without it would be us deciding to remove their people's sign-in\n * methods on our own.\n */\nexport async function enforceSsoSignInMethods(\n  orgId: string,\n  options: SsoEnforcementOptions = {},\n): Promise<SsoEnforcementResult> {\n  const { actorUid = 'system', dryRun = false, force = false } = options\n  const db = firestore()\n  const orgSnapshot = await db.collection('orgs').doc(orgId).get()\n  if (!orgSnapshot.exists) {\n    throw new SsoEnforcementError(`No such organization: ${orgId}`)\n  }\n  const sso = orgSnapshot.get('sso') as\n    | {\n        tenantId?: string\n        providerId?: string\n        enforced?: boolean\n        status?: string\n        /** Accounts the org designated to keep a non-IdP way in (AGL-1888). */\n        breakGlassUids?: unknown\n      }\n    | undefined\n  const tenantId = sso?.tenantId\n  const providerId = sso?.providerId\n  if (!tenantId || !providerId) {\n    throw new SsoEnforcementError(`${orgId} has no SSO tenant configured`)\n  }\n  if (sso?.status !== 'active') {\n    throw new SsoEnforcementError(\n      `${orgId} SSO status is \"${sso?.status ?? 'unset'}\", not active`,\n    )\n  }\n  if (!sso?.enforced && !force) {\n    throw new SsoEnforcementError(\n      `${orgId} has sso.enforced = false — nothing to enforce`,\n    )\n  }\n\n  const breakGlassUids = Array.isArray(sso?.breakGlassUids)\n    ? (sso.breakGlassUids as unknown[]).map(String).filter(Boolean)\n    : []\n\n  const pool = authForPool(tenantId)\n  const page = await pool.listUsers(TENANT_USER_CAP)\n  const accounts: SsoEnforcementAccount[] = []\n  const changedUids: string[] = []\n  const breakGlass = new Set(breakGlassUids)\n\n  for (const record of page.users) {\n    const summary = planAccount(record, providerId, breakGlass)\n    accounts.push(summary)\n  }\n\n  // The half the pool cannot supply (AGL-1888 option (a)). Run for the DRY\n  // RUN too: the rehearsal is where an org learns whether it may enforce, and\n  // a rehearsal that skipped this would report a lockout risk the real run\n  // then disagrees with.\n  const ownerLookup = await findBreakGlassOrgOwners(orgId, providerId, tenantId)\n  const lockout = assessSsoLockoutRisk(\n    accounts,\n    providerId,\n    breakGlassUids,\n    ownerLookup.owners,\n    ownerLookup.unavailable,\n  )\n\n  // THE PRE-FLIGHT (AGL-1888). Planned first, refused before a single\n  // `updateUser` — this is the whole reason the plan is computed separately\n  // from being carried out. Half a sweep is the worst outcome available: the\n  // accounts already stripped are stripped, and the org is locked out with no\n  // record of how far it got.\n  //\n  // The dry run is exempt, and has to be. The rehearsal is exactly how an org\n  // FINDS OUT it needs a break-glass account, so refusing to rehearse would\n  // leave them guessing at the requirement they are being held to.\n  //\n  // No override parameter. An `acknowledgeLockoutRisk: true` a caller can pass\n  // is not a guard, it is a spelling of the guard being off — and the caller\n  // that would pass it is the one already convinced enforcement is fine.\n  if (!dryRun && !lockout.safe) {\n    throw new SsoEnforcementError(SSO_LOCKOUT_REFUSAL)\n  }\n\n  for (const summary of accounts) {\n    const record = page.users.find((user) => user.uid === summary.uid)\n    if (!record) continue\n    if (!summary.unlinked.length || summary.skipped) continue\n    if (!dryRun) {\n      await pool.updateUser(record.uid, {\n        providersToUnlink: summary.unlinked,\n      })\n      // Only for accounts that actually changed (property 2 above). An\n      // existing session outlives the unlink otherwise.\n      await pool.revokeRefreshTokens(record.uid)\n      // This process refuses the old token NOW (AGL-1881); every other one\n      // converges within TOKEN_REVOCATION_TTL_MS.\n      invalidateTokenRevocationCache(record.uid, tenantId)\n      await db.collection('adminAudit').add({\n        actorUid,\n        action: 'org.sso.enforceSignInMethods',\n        target: `users/${record.uid}`,\n        before: { providers: providerIdsOf(record) },\n        after: {\n          providers: summary.kept,\n          orgId,\n          tenantId,\n          unlinked: summary.unlinked,\n          tokensRevoked: true,\n        },\n        at: FieldValue.serverTimestamp(),\n      })\n    }\n    changedUids.push(record.uid)\n  }\n\n  if (!dryRun && changedUids.length) {\n    // Explaining it beats a mysteriously missing button on their next visit.\n    await notifyUsers(changedUids, {\n      type: 'system.signInMethodRemoved',\n      title: 'Your sign-in methods changed',\n      body:\n        'Your organization now requires single sign-on, so other sign-in ' +\n        'methods have been removed from your account. Sign in through your ' +\n        'organization instead.',\n      orgId,\n      link: '/manage/user',\n    })\n  }\n\n  return {\n    orgId,\n    tenantId,\n    providerId,\n    dryRun,\n    scanned: page.users.length,\n    changed: changedUids.length,\n    accounts,\n    truncated: Boolean(page.pageToken),\n    lockout,\n  }\n}\n\nconst providerIdsOf = (record: UserRecord): string[] =>\n  (record.providerData ?? [])\n    .map((info) => info?.providerId)\n    .filter((id): id is string => Boolean(id))\n\n/**\n * What one account loses, decided without mutating anything so the dry run\n * and the real run cannot disagree.\n *\n * `password` counts as a provider to strip: an email/password credential on a\n * governed account is exactly the sort of standing bypass enforcement is\n * bought to remove, and it is not the org's IdP.\n *\n * @param breakGlass uids the org has DESIGNATED to keep their other sign-in\n *        methods (AGL-1888). Deliberately a parameter rather than a lookup:\n *        this function is the whole decision and stays pure, so the rehearsal\n *        and the real run cannot diverge on it either.\n */\nexport function planAccount(\n  record: UserRecord,\n  providerId: string,\n  breakGlass: ReadonlySet<string> = new Set(),\n): SsoEnforcementAccount {\n  const providers = providerIdsOf(record)\n  const unlinked = providers.filter((id) => id !== providerId)\n  const kept = providers.filter((id) => id === providerId)\n  const summary: SsoEnforcementAccount = {\n    uid: record.uid,\n    email: record.email ?? null,\n    unlinked,\n    kept,\n  }\n  // Property 1: an account with nothing but removable providers keeps them.\n  // It is misconfigured, not a bypass to close, and orphaning it would turn a\n  // security tightening into a lockout with no way back.\n  if (unlinked.length && !kept.length) {\n    return { ...summary, unlinked: [], kept: providers, skipped: 'would-orphan' }\n  }\n  // Property 4 (AGL-1888): a designated break-glass account keeps everything.\n  //\n  // This IS a standing bypass of SSO enforcement, and it is meant to be —\n  // that is what makes it a way back in when the IdP stops answering. The\n  // alternative is the state the `aglyn-org-y5v14` tenant is in today: every\n  // account in the pool holds nothing but a SAML link, and a lapsed\n  // certificate or a deleted SAML app locks the organization out of itself\n  // permanently.\n  //\n  // Checked AFTER the orphan rule so the two cannot disagree about an account\n  // that is both, and it changes nothing for a break-glass account that has\n  // no removable provider anyway — `skipped` marks a decision, so it is set\n  // only where there was something to decide.\n  if (unlinked.length && breakGlass.has(record.uid)) {\n    return { ...summary, unlinked: [], kept: providers, skipped: 'break-glass' }\n  }\n  return summary\n}\n\n/**\n * Would this org still have a way in after the sweep? (AGL-1888)\n *\n * Pure, and over the PLANNED accounts rather than the raw records, so it\n * answers the question about the state enforcement is actually about to\n * create rather than the one it is in now.\n *\n * ONLY A DESIGNATED ACCOUNT COUNTS. An account that happens to retain a\n * password because it is misconfigured — the `would-orphan` case, which has no\n * IdP link at all — is not break-glass: nobody chose it, it may be a stale\n * record or a service account, and an org protected by an accident it does not\n * know about is not protected. Requiring the designation is what makes this a\n * control rather than a coincidence.\n *\n * A designation only counts when the account actually holds something OTHER\n * than the org's IdP. Naming an account whose sole credential is the SAML link\n * is the most natural way to get this wrong — it looks like a break-glass\n * account and provides nothing, because it fails in exactly the situation it\n * exists for.\n *\n * THE SECOND WAY IN IS NOT IN THE POOL AT ALL (AGL-1888 option (a)). An org\n * owner holding a project-level credential is invisible to the sweep — the\n * enforcement pass lists `authForPool(tenantId)` and never touches the\n * project pool — so a lapsed certificate cannot reach them. No designation is\n * required for those: nobody has to be told to keep the key they already\n * hold, and requiring a tick would put the requirement back out of reach for\n * exactly the org that already satisfies it. Whether such an owner exists is\n * decided by {@link findBreakGlassOrgOwners}, which is where the seven\n * conditions live; this function only counts what it is handed, so that the\n * rehearsal and the real run cannot disagree.\n *\n * `ownerLookupFailed` deliberately does NOT make an org safe. It exists so a\n * refusal can distinguish \"you have nobody\" from \"we could not check\" — an\n * error swallowed into an empty list renders as a measured zero, and nothing\n * about it looks wrong.\n */\nexport function assessSsoLockoutRisk(\n  accounts: readonly SsoEnforcementAccount[],\n  providerId: string,\n  breakGlass: readonly string[],\n  ownersOutsidePool: readonly SsoBreakGlassOwner[] = [],\n  ownerLookupFailed = false,\n): SsoLockoutAssessment {\n  const designated = [...new Set(breakGlass.filter(Boolean))]\n  const byUid = new Map(accounts.map((account) => [account.uid, account]))\n  const retainedBy: string[] = []\n  const ineffective: string[] = []\n  for (const uid of designated) {\n    const account = byUid.get(uid)\n    const protects = Boolean(\n      account?.kept.some((id) => id !== providerId),\n    )\n    if (protects) retainedBy.push(uid)\n    else ineffective.push(uid)\n  }\n  const owners = [...ownersOutsidePool]\n  return {\n    safe: retainedBy.length > 0 || owners.length > 0,\n    retainedBy,\n    ineffective,\n    ownersOutsidePool: owners,\n    ownerLookupFailed,\n  }\n}\n\n/**\n * The refusal an org sees when enforcing would lock it out of itself.\n *\n * Says what to do, because a refusal that only says no sends someone to turn\n * the guard off. Deliberately free of a product name — this string is read by\n * self-host operators too.\n */\nexport const SSO_LOCKOUT_REFUSAL =\n  'Enforcing single sign-on would remove every sign-in method that does not ' +\n  'go through your identity provider, and this organization would be left ' +\n  'with no way in that survives your identity provider failing. If its ' +\n  'certificate lapses or its application is removed, nobody would be able ' +\n  'to sign in and we could not let you back in either. Give the ' +\n  'organization one of two things first: an owner who signs in outside your ' +\n  'identity pool, or a designated break-glass account inside it that keeps ' +\n  'a password.'\n\nexport default enforceSsoSignInMethods\n"],"names":["FieldValue","authForPool","findBreakGlassOrgOwners","invalidateTokenRevocationCache","firebaseAdmin","notifyUsers","firestore","app","TENANT_USER_CAP","SsoEnforcementError","Error","enforceSsoSignInMethods","orgId","options","actorUid","dryRun","force","db","orgSnapshot","collection","doc","get","exists","sso","tenantId","providerId","status","enforced","breakGlassUids","Array","isArray","map","String","filter","Boolean","pool","page","listUsers","accounts","changedUids","breakGlass","Set","record","users","summary","planAccount","push","ownerLookup","lockout","assessSsoLockoutRisk","owners","unavailable","safe","SSO_LOCKOUT_REFUSAL","find","user","uid","unlinked","length","skipped","updateUser","providersToUnlink","revokeRefreshTokens","add","action","target","before","providers","providerIdsOf","after","kept","tokensRevoked","at","serverTimestamp","type","title","body","link","scanned","changed","truncated","pageToken","providerData","info","id","email","has","ownersOutsidePool","ownerLookupFailed","designated","byUid","Map","account","retainedBy","ineffective","protects","some"],"mappings":"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"}

package/src/lib/server/sso-provisioning.d.ts

@@ -0,0 +1,320 @@
+/**
+ * @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 { DomainProbe } from './sso-drift-logic';
+/** Subdomain the challenge record is published at. */
+export declare const SSO_CHALLENGE_PREFIX = "_aglyn-challenge";
+/** Prefix on the TXT value, so an unrelated record cannot pass by accident. */
+export declare const SSO_TXT_PREFIX = "aglyn-domain-verification=";
+export declare function normalizeSsoDomain(input: string): string;
+/**
+ * `{ value, error }` rather than a discriminated union on purpose: an
+ * `{ ok: true } | { ok: false }` union does not narrow reliably once it crosses
+ * a library boundary in this repo (`strictNullChecks` is off), and the caller
+ * ends up unable to reach either arm's fields. Both keys always present, one of
+ * them always null.
+ */
+export interface DomainCheck {
+    domain: string | null;
+    error: string | null;
+}
+export declare function validateSsoDomain(input: string): DomainCheck;
+/**
+ * TXT records at the challenge host, lowercased and unwrapped.
+ *
+ * A TXT answer arrives as an array of string CHUNKS per record (DNS splits
+ * strings over 255 bytes), so each record is joined before comparison —
+ * otherwise a long token would never match.
+ */
+export declare function resolveChallengeTxt(domain: string): Promise<string[]>;
+/** The exact TXT value an org must publish for a domain. */
+export declare function challengeValue(token: string): string;
+/**
+ * Does this set of TXT records prove control of the zone for THIS token?
+ *
+ * Extracted so the comparison that domain verification rests on is reachable
+ * from a test without standing up Firestore. It is deliberately an exact match
+ * on a whole record: a substring test would accept
+ * `aglyn-domain-verification=<token>-and-more`, and a prefix test would accept
+ * any record that merely starts the same way. Neither proves anything.
+ */
+export declare function recordsProveOwnership(records: readonly string[], token: string): boolean;
+/**
+ * The pure half of re-verification — the probe STATES and the decision made
+ * from them — lives in `sso-drift-logic.ts` and is re-exported here so the
+ * public surface is one module. It has no imports at all, which is what lets
+ * the console route's spec run the REAL decision against faked I/O.
+ */
+export { assessDomainDrift, SSO_DRIFT_FAILURES_BEFORE_REPORT, SSO_DRIFT_MIN_AGE_MS, type DomainDriftAction, type DomainDriftState, type DomainDriftVerdict, type DomainProbe, type DomainProbeStatus, } from './sso-drift-logic';
+/**
+ * Re-check a claim's TXT record, distinguishing silence from absence.
+ *
+ * Same pinned public resolvers and same fallback as {@link resolveChallengeTxt}
+ * — this is not a second opinion about DNS, it is the same lookup reporting one
+ * more bit. NXDOMAIN/ENOTFOUND/ENODATA are ANSWERS ("that name has no TXT
+ * record") and stay conclusive; anything else from both the pinned resolvers
+ * and the runtime fallback is `unreachable`.
+ *
+ * Never throws: a sweep across every org must not stop at the first bad zone.
+ */
+export declare function probeChallengeTxt(domain: string, token: string): Promise<DomainProbe>;
+export interface SsoDomainClaimView {
+    domain: string;
+    token: string;
+    verified: boolean;
+    /** Fully-qualified host the record goes on. */
+    recordHost: string;
+    /** Exact value the record must carry. */
+    recordValue: string;
+    lastRecords?: string[];
+}
+/**
+ * Start (or re-read) a claim on a domain. Idempotent: an existing claim keeps
+ * its token, because reissuing would invalidate a record the customer may have
+ * already published and turn a working setup into a mysterious failure.
+ */
+export declare function issueDomainClaim(orgId: string, rawDomain: string): Promise<{
+    claim: SsoDomainClaimView | null;
+    error: string | null;
+}>;
+export interface DomainVerifyResult {
+    domain: string;
+    verified: boolean;
+    /** What the lookup actually saw — the difference between "missing" and "wrong". */
+    records: string[];
+    expected: string;
+}
+/**
+ * Check a claim against live DNS and, on success, promote the domain into
+ * `sso.domains` — the array that sign-in consults.
+ *
+ * Failure is recorded but never destructive: a transient DNS outage must not
+ * silently un-govern a domain mid-flight. Removal is `revokeDomain`, which is
+ * an explicit act.
+ */
+export declare function verifyDomainClaim(orgId: string, rawDomain: string): Promise<{
+    result: DomainVerifyResult | null;
+    error: string | null;
+}>;
+/**
+ * Drop a domain: out of `sso.domains`, and its public routing doc deactivated.
+ *
+ * Order matters. The public doc goes first, because it is the one an attacker
+ * would benefit from: while it says `active`, sign-ins for the domain still
+ * route to this org's IdP regardless of what the org doc says.
+ */
+export declare function revokeDomain(orgId: string, rawDomain: string): Promise<void>;
+/**
+ * What the customer needs to type into their IdP. Derived, never stored —
+ * these are properties of OUR deployment, and a stale stored copy would send
+ * somebody to configure an ACS URL we no longer serve.
+ *
+ * The callback is Firebase Auth's own handler on the project `authDomain`;
+ * `rpEntityId` is the relying-party entity id their IdP will see.
+ */
+export interface SsoServiceMetadata {
+    acsUrl: string;
+    entityId: string;
+    authDomain: string;
+}
+/**
+ * Thrown by `ssoServiceMetadata()` when this deployment has no auth origin at
+ * all (AGL-2020).
+ *
+ * Deliberately names the variables and NOT a value: handing the operator
+ * a `*.firebaseapp.com` example here is how they end up pasting somebody
+ * else's project id into their IdP. `sso-provisioning.spec.ts` asserts this
+ * string mentions no Aglyn host.
+ */
+export declare const SSO_AUTH_ORIGIN_UNCONFIGURED_MESSAGE: string;
+/**
+ * The auth origin this deployment actually serves (AGL-1381).
+ *
+ * Mirrors `resolveFirebaseAuthDomain()` in the client's `firebase-config`: on a
+ * workspace deployment the whole OAuth/SAML handshake is funnelled through one
+ * dedicated same-site origin, `auth.<workspaceDomain>`, which reverse-proxies
+ * Firebase's `/__/auth/*` helpers (AGL-462). The IdP has to post the assertion
+ * to THAT origin — the one holding the pending-redirect state — or browser
+ * storage partitioning severs the two halves of the flow.
+ *
+ * The order is load-bearing:
+ *
+ *   1. `NEXT_PUBLIC_FIREBASE_AUTH_HANDLER_HOST` — an explicit override wins.
+ *   2. `auth.<NEXT_PUBLIC_WORKSPACE_DOMAIN>` — the deployed workspace origin.
+ *      Derived only when the variable is actually set, never defaulted: falling
+ *      back to `auth.aglyn.com` would point a self-hosted install at OUR auth
+ *      origin, and it would also make the `firebaseapp.com` arm unreachable.
+ *      It sits ABOVE `AUTH_DOMAIN` because production sets both, and the
+ *      branded host is the one production serves.
+ *   3–4. the project's `*.firebaseapp.com` domain — localhost, previews that
+ *      are not on the workspace domain, the emulator, and self-host installs
+ *      that have not stood up an auth subdomain.
+ *
+ * When all four are absent this THROWS (AGL-2020). It used to default the
+ * project id to `aglyn-main` — ours — which is the anti-pattern AGL-1919
+ * exists to prevent, and it was silent in both directions that matter:
+ * `provisionSsoPool()` wrote our origin into the operator's OWN GCIP provider
+ * as `rpEntityId`/`callbackURL`, and the console printed it as the Reply URL
+ * for their customer to paste into their IdP. A third party's SAML assertions
+ * would then be posted at infrastructure the operator does not run.
+ *
+ * Throwing rather than degrading is deliberate, and this is the one place in
+ * the self-host audit where "run with the feature off" is not available: there
+ * is no empty value to fall back to. `authDomain: ''` emits
+ * `https:///__/auth/handler`, which GCIP accepts on write and which then
+ * rejects every assertion afterwards with nothing in the config that looks
+ * wrong — the same "looks configured, works never" shape as an App Check
+ * provider built on `undefined`. SSO is opt-in and deliberately configured, so
+ * an operator reaching this has asked for it; a named error telling them which
+ * variable to set is strictly better than either wrong origin.
+ *
+ * The READ path degrades instead of 500ing: `/api/orgs/sso?action=status`
+ * catches this and returns `metadata: null` with the message, so the settings
+ * page renders the reason rather than a wrong instruction. The WRITE path
+ * (`provisionSsoPool`) lets it fly.
+ *
+ * `entityId` carries the scheme. It is not cosmetic: live GCIP for the first
+ * SSO org holds `https://auth.aglyn.com`, and Google Workspace is already
+ * sending that exact Audience. Emitting the bare host here would be written
+ * over the working config by the next `provisionSsoPool()` save and lock out
+ * every SSO-only user in the org. `sso-provisioning.spec.ts` pins both strings
+ * character for character for that reason.
+ */
+export declare function ssoServiceMetadata(): SsoServiceMetadata;
+/**
+ * GCIP display names are constrained (4–20 chars, must start with a letter,
+ * letters/digits/hyphens only). An org slug can violate every one of those, so
+ * derive rather than pass through — a rejected display name would surface as an
+ * opaque provisioning failure at the worst moment.
+ */
+export declare function poolDisplayName(orgSlug: string, orgId: string): string;
+export interface SamlIdpMetadata {
+    entityId: string;
+    ssoUrl: string;
+    certificates: string[];
+}
+export interface ProvisionResult {
+    tenantId: string;
+    providerId: string;
+    /** True when this call created the pool rather than reusing one. */
+    createdPool: boolean;
+    /** True when this call created the provider rather than updating one. */
+    createdProvider: boolean;
+}
+/**
+ * Create (or update) the org's GCIP pool and its SAML provider.
+ *
+ * Idempotent by construction: an org that already has a `tenantId` reuses it,
+ * and a provider that already exists is UPDATED rather than recreated. Creating
+ * a second pool would strand every user in the first one — they are separate
+ * user namespaces, so "just make a new one" silently locks out everybody who
+ * has already signed in.
+ */
+export declare function provisionSsoPool(options: {
+    orgId: string;
+    orgSlug: string;
+    existingTenantId?: string;
+    existingProviderId?: string;
+    displayName: string;
+    idp: SamlIdpMetadata;
+}): Promise<ProvisionResult>;
+/**
+ * Is this claim a STAFF ATTESTATION that the org owns the domain? (AGL-1887)
+ *
+ * The second of exactly two ways a domain can be proven, and the one that
+ * exists for orgs onboarded before self-serve. Their domain was written onto
+ * `sso.domains` by a person who checked, with no claim document behind it — so
+ * `unpublishSsoDomains` deactivated their routing happily and
+ * `publishSsoDomains` then refused to bring it back. Off worked, on did not,
+ * and for `aglyn-org` the owner's only credential lives inside the pool that
+ * stops answering (AGL-1888).
+ *
+ * A POSITIVE MARKER, never an absence. The rejected alternative was to treat
+ * "a routing doc already exists naming this org" as permission to re-publish,
+ * which makes `unpublish` non-final and would let a domain whose claim was
+ * revoked come back. What is trusted here is a field a staff member wrote on
+ * purpose, and it says WHO, so the trust is attributable.
+ *
+ * WHY THIS IS NOT A CLIENT-REACHABLE HOLE, which is the only question that
+ * matters about it:
+ *
+ *  - `orgs/{orgId}/ssoDomains/{domain}` is `allow read, write: if false` in
+ *    `cloud/firebase-firestore.rules` — deny-all for every client, reads
+ *    included. Only the Admin SDK, which bypasses rules, can write here.
+ *  - No customer-reachable route writes this field. `issueDomainClaim` is the
+ *    only claim writer on the org's own path and it writes `domain`, `token`,
+ *    `verified: false` and `createdAt` — never `attestedBy`.
+ *  - {@link attestSsoDomain} is the only writer, and it is staff-only by
+ *    construction: it lives here, server-side, and takes the attesting uid.
+ *
+ * That is why AGL-1887's proposed rules change is NOT part of this: the
+ * subcollection is already deny-all, and adding a rule permitting a narrower
+ * write than "none" would loosen it, not tighten it.
+ *
+ * A non-empty STRING, checked strictly. `true`, `1` or `{}` are not an
+ * attestation by anybody, and a field that can be satisfied by any truthy
+ * value is one a future careless write can satisfy by accident.
+ */
+export declare function isStaffAttestedClaim(attestedBy: unknown): boolean;
+/**
+ * Record that staff have verified, out of band, that an org owns a domain
+ * (AGL-1887).
+ *
+ * This is the write half of the attestation {@link isStaffAttestedClaim}
+ * reads, and it exists so there is exactly ONE way the marker can be created
+ * and it is a named function with an actor on it — rather than a field somebody
+ * sets by hand in the Firebase console with no record of who or why.
+ *
+ * `verified` is left FALSE and untouched. The two facts are different: DNS
+ * verification is a proof we re-ran ourselves, an attestation is a person
+ * vouching. Collapsing them would make an attested domain indistinguishable
+ * from a DNS-proven one in the data, and the `verified` flag is what
+ * `verifyDomainClaim` owns.
+ *
+ * Not exposed through `/api/orgs/sso`, deliberately. An org admin proving
+ * their own domain has DNS for that; an attestation is us saying we checked,
+ * and a customer-reachable path that wrote it would be a customer-reachable
+ * path to publishing any domain.
+ */
+export declare function attestSsoDomain(options: {
+    orgId: string;
+    domain: string;
+    /** The staff member vouching. Recorded, and required. */
+    attestedByUid: string;
+    note?: string | null;
+}): Promise<{
+    domain: string | null;
+    error: string | null;
+}>;
+/**
+ * Publish the public routing docs — the last step, and the one that actually
+ * turns SSO on for a domain.
+ *
+ * Only PROVEN domains are written — DNS-verified, or staff-attested per
+ * {@link isStaffAttestedClaim}. This function is the single writer of
+ * `ssoDomains`, so the invariant "a live routing doc implies proven ownership"
+ * is enforceable by reading one place.
+ */
+export declare function publishSsoDomains(options: {
+    orgId: string;
+    tenantId: string;
+    providerId: string;
+    protocol: 'saml' | 'oidc';
+    displayName?: string;
+    domains: string[];
+}): Promise<string[]>;
+/** Deactivate every routing doc this org owns (disable, not delete). */
+export declare function unpublishSsoDomains(orgId: string): Promise<void>;