@aglyn/tenant-data-admin 1.0.0-beta.261 → 1.0.0-beta.263

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

@@ -14,6 +14,15 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+/**
+ * The block below runs in two places: here, at the session mint, and in the
+ * `cloud/functions` account-creation blocking function, which refuses the
+ * account before it exists. `cloud/functions` is a plain npm package that can
+ * import only firebase-admin and firebase-functions, so it holds a verbatim
+ * copy (`cloud/functions/src/sso-domain-policy.ts`), and
+ * `apps/console/specs/sso-domain-creation-wiring.spec.ts` fails if the two
+ * differ by a single character. Change it here, then copy the region across.
+ */
 export declare const SSO_REQUIRED_DOMAINS_ENV = "AGLYN_SSO_REQUIRED_DOMAINS";
 export type SsoRequiredDomains = Readonly<Record<string, string>>;
 /**
@@ -28,6 +37,23 @@ export declare function parseSsoRequiredDomains(raw: string | null | undefined):
  * The operator's SSO-required domains. Empty unless configured — see above.
  */
 export declare function ssoRequiredDomains(env?: Record<string, string | undefined>): SsoRequiredDomains;
+/**
+ * Addresses on a governed domain that may still sign in OUTSIDE its tenant.
+ *
+ * For accounts that cannot use the IdP at all because someone outside the
+ * company has to sign in with them: the demo login an app store reviewer is
+ * given, for example. Exact addresses only, never a pattern, so every
+ * exception is named and can be read back from configuration:
+ *
+ * ```
+ * AGLYN_SSO_EXEMPT_EMAILS="reviewer@example.com"
+ * ```
+ *
+ * Comma or whitespace separated, compared lower-cased. Empty by default.
+ */
+export declare const SSO_EXEMPT_EMAILS_ENV = "AGLYN_SSO_EXEMPT_EMAILS";
+export declare function parseSsoExemptEmails(raw: string | null | undefined): ReadonlySet<string>;
+export declare function ssoExemptEmails(env?: Record<string, string | undefined>): ReadonlySet<string>;
 export type SsoDomainVerdict = 
 /** Domain is not governed. Any pool is fine — this is most of the world. */
 'allow-ungoverned'
@@ -39,6 +65,11 @@ export type SsoDomainVerdict =
  * nobody asked for — but surfaced so a staff-access review can see it.
  */
  | 'allow-foreign-tenant'
+/**
+ * Governed domain, no tenant, but the address is named in
+ * {@link SSO_EXEMPT_EMAILS_ENV}. Allowed and reviewable.
+ */
+ | 'allow-exempt'
 /**
  * Governed domain with NO tenant at all: a project-pool password or consumer
  * Google sign-in. The only refusal this policy ever produces.
@@ -82,7 +113,7 @@ export declare function domainOf(email: string | null | undefined): string | nul
  * 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;
+export declare function evaluateSsoDomainPolicy(identity: SsoDomainIdentity, domains?: SsoRequiredDomains, exempt?: ReadonlySet<string>): SsoDomainDecision;
 /**
  * THE ENFORCEMENT SWITCH — ships OFF.
  *
@@ -102,18 +133,23 @@ export declare function evaluateSsoDomainPolicy(identity: SsoDomainIdentity, dom
  * **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.
+ *  2. Every identity on a governed domain has been migrated into its tenant,
+ *     retired, or named in {@link SSO_EXEMPT_EMAILS_ENV}. An automation or
+ *     reviewer account is the one that bites without warning: 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;
+/**
+ * Whether an account about to be CREATED must be refused. Same switch, same
+ * domains, same exemptions as the session mint, so an address the mint would
+ * turn away is never created in the first place, and an address it admits
+ * is never refused here.
+ */
+export declare function ssoDomainCreationRefused(identity: SsoDomainIdentity, env?: Record<string, string | undefined>): boolean;
 /**
  * What the refused person is told. Names the fix, not the mechanism.
  *

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

@@ -83,6 +83,15 @@
  * 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";
+/**
+ * The block below runs in two places: here, at the session mint, and in the
+ * `cloud/functions` account-creation blocking function, which refuses the
+ * account before it exists. `cloud/functions` is a plain npm package that can
+ * import only firebase-admin and firebase-functions, so it holds a verbatim
+ * copy (`cloud/functions/src/sso-domain-policy.ts`), and
+ * `apps/console/specs/sso-domain-creation-wiring.spec.ts` fails if the two
+ * differ by a single character. Change it here, then copy the region across.
+ */ // #region sso-domain-policy
 export const SSO_REQUIRED_DOMAINS_ENV = 'AGLYN_SSO_REQUIRED_DOMAINS';
 /**
  * Parse the configured domain→tenant map. Total: anything unparseable is
@@ -108,6 +117,31 @@ export const SSO_REQUIRED_DOMAINS_ENV = 'AGLYN_SSO_REQUIRED_DOMAINS';
  */ export function ssoRequiredDomains(env = process.env) {
     return parseSsoRequiredDomains(env[SSO_REQUIRED_DOMAINS_ENV]);
 }
+/**
+ * Addresses on a governed domain that may still sign in OUTSIDE its tenant.
+ *
+ * For accounts that cannot use the IdP at all because someone outside the
+ * company has to sign in with them: the demo login an app store reviewer is
+ * given, for example. Exact addresses only, never a pattern, so every
+ * exception is named and can be read back from configuration:
+ *
+ * ```
+ * AGLYN_SSO_EXEMPT_EMAILS="reviewer@example.com"
+ * ```
+ *
+ * Comma or whitespace separated, compared lower-cased. Empty by default.
+ */ export const SSO_EXEMPT_EMAILS_ENV = 'AGLYN_SSO_EXEMPT_EMAILS';
+export function parseSsoExemptEmails(raw) {
+    const emails = new Set();
+    for (const entry of String(raw != null ? raw : '').split(/[,\s]+/)){
+        const email = entry.trim().toLowerCase();
+        if (email.includes('@')) emails.add(email);
+    }
+    return emails;
+}
+export function ssoExemptEmails(env = process.env) {
+    return parseSsoExemptEmails(env[SSO_EXEMPT_EMAILS_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('@');
@@ -118,8 +152,8 @@ export const SSO_REQUIRED_DOMAINS_ENV = 'AGLYN_SSO_REQUIRED_DOMAINS';
  * 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;
+ */ export function evaluateSsoDomainPolicy(identity, domains = ssoRequiredDomains(), exempt = ssoExemptEmails()) {
+    var _identity_tenantId, _identity_email;
     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
@@ -161,6 +195,16 @@ export const SSO_REQUIRED_DOMAINS_ENV = 'AGLYN_SSO_REQUIRED_DOMAINS';
             reviewable: true
         };
     }
+    if (exempt.has(String((_identity_email = identity.email) != null ? _identity_email : '').trim().toLowerCase())) {
+        return {
+            verdict: 'allow-exempt',
+            refused: false,
+            domain,
+            requiredTenantId,
+            tenantId: null,
+            reviewable: true
+        };
+    }
     return {
         verdict: 'refuse-sso-required',
         refused: true,
@@ -189,12 +233,10 @@ export const SSO_REQUIRED_DOMAINS_ENV = 'AGLYN_SSO_REQUIRED_DOMAINS';
  * **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.
+ *  2. Every identity on a governed domain has been migrated into its tenant,
+ *     retired, or named in {@link SSO_EXEMPT_EMAILS_ENV}. An automation or
+ *     reviewer account is the one that bites without warning: 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.
@@ -202,6 +244,16 @@ export const SSO_REQUIRED_DOMAINS_ENV = 'AGLYN_SSO_REQUIRED_DOMAINS';
 export function ssoDomainEnforcementEnabled(env = process.env) {
     return env[SSO_DOMAIN_ENFORCEMENT_ENV] === 'on';
 }
+/**
+ * Whether an account about to be CREATED must be refused. Same switch, same
+ * domains, same exemptions as the session mint, so an address the mint would
+ * turn away is never created in the first place, and an address it admits
+ * is never refused here.
+ */ export function ssoDomainCreationRefused(identity, env = process.env) {
+    if (!ssoDomainEnforcementEnabled(env)) return false;
+    return evaluateSsoDomainPolicy(identity, ssoRequiredDomains(env), ssoExemptEmails(env)).refused;
+}
+// #endregion sso-domain-policy
 /**
  * What the refused person is told. Names the fix, not the mechanism.
  *
@@ -220,7 +272,7 @@ export function ssoDomainEnforcementEnabled(env = process.env) {
  * 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));
+    const decision = evaluateSsoDomainPolicy(identity, ssoRequiredDomains(env), ssoExemptEmails(env));
     if (!decision.refused) return null;
     if (!ssoDomainEnforcementEnabled(env)) return null;
     return {

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

@@ -1 +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":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8CC,GAED;;;;;;;;;;;;;;;;;;;;;;;CAuBC,GACD,SAASA,mBAAmB,QAAQ,wCAAuC;AAE3E,OAAO,MAAMC,2BAA2B,6BAA4B;AAIpE;;;;;;CAMC,GACD,OAAO,SAASC,wBACdC,GAA8B;IAE9B,MAAMC,MAA8B,CAAC;IACrC,KAAK,MAAMC,QAAQC,OAAOH,cAAAA,MAAO,IAAII,KAAK,CAAC,UAAW;QACpD,IAAI,CAACF,MAAM;QACX,MAAMG,KAAKH,KAAKI,OAAO,CAAC;QACxB,IAAID,MAAM,GAAG;QACb,MAAME,SAASL,KAAKM,KAAK,CAAC,GAAGH,IAAII,IAAI,GAAGC,WAAW;QACnD,MAAMC,WAAWT,KAAKM,KAAK,CAACH,KAAK,GAAGI,IAAI;QACxC,IAAI,CAACF,UAAU,CAACI,UAAU;QAC1BV,GAAG,CAACM,OAAO,GAAGI;IAChB;IACA,OAAOV;AACT;AAEA;;CAEC,GACD,OAAO,SAASW,mBACdC,MAA0CC,QAAQD,GAAG;IAErD,OAAOd,wBAAwBc,GAAG,CAACf,yBAAyB;AAC9D;AAoDA,2EAA2E,GAC3E,OAAO,SAASiB,SAASC,KAAgC;IACvD,MAAMC,UAAUd,OAAOa,gBAAAA,QAAS,IAAIP,IAAI,GAAGC,WAAW;IACtD,MAAMQ,KAAKD,QAAQE,WAAW,CAAC;IAC/B,IAAID,KAAK,KAAKA,OAAOD,QAAQG,MAAM,GAAG,GAAG,OAAO;IAChD,OAAOH,QAAQT,KAAK,CAACU,KAAK;AAC5B;AAEA;;;;CAIC,GACD,OAAO,SAASG,wBACdC,QAA2B,EAC3BC,UAA8BX,oBAAoB;QAGjCU;IADjB,MAAMf,SAASQ,SAASO,SAASN,KAAK;IACtC,MAAML,YAAWW,qBAAAA,SAASX,QAAQ,YAAjBW,qBAAqB;IACtC,oEAAoE;IACpE,4EAA4E;IAC5E,MAAME,mBAAmBjB,SACpBkB,OAAOC,SAAS,CAACC,cAAc,CAACC,IAAI,CAACL,SAAShB,UAC3CgB,OAAO,CAAChB,OAAO,GACf,OACJ;IAEJ,IAAI,CAACiB,kBAAkB;QACrB,wEAAwE;QACxE,uEAAuE;QACvE,0DAA0D;QAC1D,OAAO;YACLK,SAAS;YACTC,SAAS;YACTvB;YACAiB,kBAAkB;YAClBb;YACAoB,YAAY;QACd;IACF;IAEA,IAAIpB,aAAaa,kBAAkB;QACjC,OAAO;YACLK,SAAS;YACTC,SAAS;YACTvB;YACAiB;YACAb;YACAoB,YAAY;QACd;IACF;IAEA,IAAIpB,UAAU;QACZ,uEAAuE;QACvE,wEAAwE;QACxE,kEAAkE;QAClE,OAAO;YACLkB,SAAS;YACTC,SAAS;YACTvB;YACAiB;YACAb;YACAoB,YAAY;QACd;IACF;IAEA,OAAO;QACLF,SAAS;QACTC,SAAS;QACTvB;QACAiB;QACAb,UAAU;QACVoB,YAAY;IACd;AACF;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4BC,GACD,OAAO,MAAMC,6BAA6B,+BAA8B;AAExE,OAAO,SAASC,4BACdpB,MAA0CC,QAAQD,GAAG;IAErD,OAAOA,GAAG,CAACmB,2BAA2B,KAAK;AAC7C;AAEA;;;;;;;;;;CAUC,GACD,OAAO,MAAME,6BACX,CAAC,kBAAkB,EAAErC,oBAAoB,mBAAmB,CAAC,GAC7D,wEACA,2BAA0B;AAE5B;;;;;;CAMC,GACD,OAAO,SAASsC,iBACdb,QAA2B,EAC3BT,MAA0CC,QAAQD,GAAG;IAErD,MAAMuB,WAAWf,wBAAwBC,UAAUV,mBAAmBC;IACtE,IAAI,CAACuB,SAASN,OAAO,EAAE,OAAO;IAC9B,IAAI,CAACG,4BAA4BpB,MAAM,OAAO;IAC9C,OAAO;QACLuB;QACAC,UAAUC,SAASC,IAAI,CACrB;YACEC,OAAON;YACPO,QAAQ;YACRlC,QAAQ6B,SAAS7B,MAAM;QACzB,GACA;YAAEmC,QAAQ;QAAI;IAElB;AACF;AAEA,eAAerB,wBAAuB"}
+{"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\n/**\n * The block below runs in two places: here, at the session mint, and in the\n * `cloud/functions` account-creation blocking function, which refuses the\n * account before it exists. `cloud/functions` is a plain npm package that can\n * import only firebase-admin and firebase-functions, so it holds a verbatim\n * copy (`cloud/functions/src/sso-domain-policy.ts`), and\n * `apps/console/specs/sso-domain-creation-wiring.spec.ts` fails if the two\n * differ by a single character. Change it here, then copy the region across.\n */\n// #region sso-domain-policy\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\n/**\n * Addresses on a governed domain that may still sign in OUTSIDE its tenant.\n *\n * For accounts that cannot use the IdP at all because someone outside the\n * company has to sign in with them: the demo login an app store reviewer is\n * given, for example. Exact addresses only, never a pattern, so every\n * exception is named and can be read back from configuration:\n *\n * ```\n * AGLYN_SSO_EXEMPT_EMAILS=\"reviewer@example.com\"\n * ```\n *\n * Comma or whitespace separated, compared lower-cased. Empty by default.\n */\nexport const SSO_EXEMPT_EMAILS_ENV = 'AGLYN_SSO_EXEMPT_EMAILS'\n\nexport function parseSsoExemptEmails(\n  raw: string | null | undefined,\n): ReadonlySet<string> {\n  const emails = new Set<string>()\n  for (const entry of String(raw ?? '').split(/[,\\s]+/)) {\n    const email = entry.trim().toLowerCase()\n    if (email.includes('@')) emails.add(email)\n  }\n  return emails\n}\n\nexport function ssoExemptEmails(\n  env: Record<string, string | undefined> = process.env,\n): ReadonlySet<string> {\n  return parseSsoExemptEmails(env[SSO_EXEMPT_EMAILS_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, no tenant, but the address is named in\n   * {@link SSO_EXEMPT_EMAILS_ENV}. Allowed and reviewable.\n   */\n  | 'allow-exempt'\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  exempt: ReadonlySet<string> = ssoExemptEmails(),\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  if (exempt.has(String(identity.email ?? '').trim().toLowerCase())) {\n    return {\n      verdict: 'allow-exempt',\n      refused: false,\n      domain,\n      requiredTenantId,\n      tenantId: null,\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,\n *     retired, or named in {@link SSO_EXEMPT_EMAILS_ENV}. An automation or\n *     reviewer account is the one that bites without warning: nobody is\n *     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 * Whether an account about to be CREATED must be refused. Same switch, same\n * domains, same exemptions as the session mint, so an address the mint would\n * turn away is never created in the first place, and an address it admits\n * is never refused here.\n */\nexport function ssoDomainCreationRefused(\n  identity: SsoDomainIdentity,\n  env: Record<string, string | undefined> = process.env,\n): boolean {\n  if (!ssoDomainEnforcementEnabled(env)) return false\n  return evaluateSsoDomainPolicy(\n    identity,\n    ssoRequiredDomains(env),\n    ssoExemptEmails(env),\n  ).refused\n}\n// #endregion sso-domain-policy\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(\n    identity,\n    ssoRequiredDomains(env),\n    ssoExemptEmails(env),\n  )\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","SSO_EXEMPT_EMAILS_ENV","parseSsoExemptEmails","emails","Set","entry","email","includes","add","ssoExemptEmails","domainOf","address","at","lastIndexOf","length","evaluateSsoDomainPolicy","identity","domains","exempt","requiredTenantId","Object","prototype","hasOwnProperty","call","verdict","refused","reviewable","has","SSO_DOMAIN_ENFORCEMENT_ENV","ssoDomainEnforcementEnabled","ssoDomainCreationRefused","SSO_DOMAIN_REFUSAL_MESSAGE","ssoDomainRefusal","decision","response","Response","json","error","reason","status"],"mappings":"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"}

package/src/lib/server/weekly-summary.d.ts

@@ -0,0 +1,160 @@
+/**
+ * @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 { AglynOrgMember } from '@aglyn/aglyn/foundation/definitions/organization.types';
+import { type ReleaseFlagKey } from '@aglyn/aglyn/app-utils/release-flags';
+import { type WeeklySummaryColors, type WeeklySummaryEmail } from '@aglyn/aglyn/app-utils/weekly-summary';
+import { type ResolvedPluginFigureReader } from '@aglyn/aglyn/plugin-manager/plugin-figures';
+import { type FigureReaderContext } from './figure-readers';
+/**
+ * THE WEEKLY SUMMARY'S SENDS (AGL-3867): `POST /api/admin/weekly-summary`,
+ * Mondays at 13:00 UTC (08:00 Central) from `scheduled-crons.yml`.
+ *
+ * ## What is sent, and to whom
+ *
+ * One email for each of a workspace's sites that had something to report,
+ * and a workspace overview that adds them up: totals across the sites, a line
+ * for each, and the workspace's own figures, such as its deals.
+ *
+ *  - The workspace's owners and admins get the overview and every site's
+ *    email. In a workspace where only one site had anything to report, the
+ *    overview would repeat it, so that site's email carries the workspace's
+ *    own figures instead and no overview is sent.
+ *  - A member who is an admin of a site, without being one of the
+ *    workspace's, gets that site's email: they run it.
+ *
+ * The **Weekly summary** switch on each person's account
+ * (`users/{uid}.digestPrefs.weeklySummary`, on until turned off) governs all
+ * of it. A locked or disabled account, a suppressed address and a suspended
+ * member are not mailed.
+ *
+ * ## What it reads
+ *
+ * The workspace's busiest `WEEKLY_SUMMARY_MAX_SITES` sites by last week's
+ * page views, each through every site reader that declares a
+ * `weeklySummary`, and the workspace through every workspace reader that
+ * does. Each reader is offered only where its plan feature is included and
+ * its plugin runs (`eligibleFigureReaders`), read over the seven whole days
+ * before the run, and summarized by its owner. A reader that fails is left
+ * out; the rest are still read. Every figure is read once per workspace, and
+ * every recipient is sent the same figures.
+ *
+ * ## Once a week, and resumable
+ *
+ * `orgs/{orgId}/weeklySummaries/{week}.sent.{uid}.{email}` records each
+ * email sent — `overview`, or a site's id — stamped after each send, so a run
+ * that dies mid-workspace sends only what never went, and a second run in the
+ * same week sends nothing. Workspaces are swept in id order behind a cursor,
+ * the `done: false` loop the workflow already runs for the CRM digest.
+ *
+ * The email is a `bulk` send under the platform send-rate governor: a refusal
+ * stops the run and answers `done: true`, and a manual re-run in the same week
+ * picks up the rest. Metered as PLATFORM mail, not the workspace's: it is the
+ * platform reporting to the people who run it.
+ */
+type Firestore = FirebaseFirestore.Firestore;
+/** The beat `/api/health/crons` reads, once this job joins its inventory. */
+export declare const WEEKLY_SUMMARY_JOB_ID = "weekly-summary";
+/** `orgs/{orgId}/weeklySummaries/{week}` — server-written, matched by no rule. */
+export declare const WEEKLY_SUMMARY_MARKERS = "weeklySummaries";
+/** The marker key of the overview; a site's email is keyed by the site's id. */
+export declare const WEEKLY_SUMMARY_OVERVIEW = "overview";
+/** The system emails: the overview, and one site's. */
+export declare const WEEKLY_SUMMARY_TEMPLATE = "weekly-summary";
+export declare const WEEKLY_SUMMARY_SITE_TEMPLATE = "weekly-summary-site";
+/** Workspaces per invocation; a chunk that times out never advances its cursor. */
+export declare const WEEKLY_SUMMARY_ORG_CHUNK = 20;
+/** Sites a workspace's sweep ranks, by document id. */
+export declare const WEEKLY_SUMMARY_HOST_READ_LIMIT = 50;
+/** Sites a week's summary reports on: the busiest by last week's page views. */
+export declare const WEEKLY_SUMMARY_MAX_SITES = 5;
+/** Members per workspace whose address is chased through the auth pools when their member document has none. */
+export declare const WEEKLY_SUMMARY_MAX_UID_LOOKUPS = 5;
+/** How long one call works before it stops and leaves the rest to the next. */
+export declare const WEEKLY_SUMMARY_RUN_BUDGET_MS = 45000;
+export interface WeeklySummarySendResult {
+    sent: boolean;
+    /** The platform's send rate refused it for now. */
+    rateLimited: boolean;
+    reason?: string;
+}
+export interface WeeklySummaryMessage {
+    to: string;
+    template: typeof WEEKLY_SUMMARY_TEMPLATE | typeof WEEKLY_SUMMARY_SITE_TEMPLATE;
+    email: WeeklySummaryEmail;
+    org: Record<string, unknown>;
+    merge: Record<string, string>;
+}
+/** Everything the sweep reaches beyond Firestore, so a spec can hold each one. */
+export interface WeeklySummaryDeps {
+    firestore: Firestore;
+    runAt: Date;
+    dryRun: boolean;
+    /** The console's absolute origin, or `''` when none is configured. */
+    origin: string;
+    /** Whether a release flag is on for an org. */
+    flagOn: (flag: ReleaseFlagKey, orgId: string, org: Record<string, unknown>) => boolean;
+    orgMembers: (orgId: string) => Promise<AglynOrgMember[]>;
+    /** The uids whose accounts may be mailed. */
+    reachable: (uids: string[]) => Promise<string[]>;
+    /** The readers that declare a `weeklySummary` and pass the gates here. */
+    readers: (context: Omit<FigureReaderContext, 'accept'>) => Promise<ResolvedPluginFigureReader[]>;
+    /** The org's email colors, from its theme. */
+    colors: (org: Record<string, unknown>) => WeeklySummaryColors;
+    /** The member's deliverable address, or `null` when there is none or it is suppressed. */
+    address: (member: AglynOrgMember, lookups: {
+        left: number;
+    }) => Promise<string | null>;
+    send: (message: WeeklySummaryMessage) => Promise<WeeklySummarySendResult>;
+    budgetMs?: number;
+}
+export interface WeeklySummaryOrgReport {
+    skipped?: string;
+    sites: number;
+    recipients: number;
+    sent: number;
+    failed?: number;
+    /** Why the workspace stopped short: the call's time ran out, or the send rate refused. */
+    deferred?: 'time' | 'rate';
+}
+export interface WeeklySummaryReport {
+    week: string;
+    dryRun: boolean;
+    swept: number;
+    sent: number;
+    orgs: Record<string, WeeklySummaryOrgReport>;
+    deferred: false | 'time' | 'rate';
+    nextCursor: string | null;
+    done: boolean;
+}
+/** One chunk of the sweep: workspaces in id order after `cursor`. */
+export declare function runWeeklySummarySweep(deps: WeeklySummaryDeps, options?: {
+    cursor?: string | null;
+    limit?: number;
+}): Promise<WeeklySummaryReport>;
+/** The sweep's reach into the real platform: Firestore, the flags, the roster, the mail. */
+/** The sweep's reach into the real platform: Firestore, the flags, the roster, the mail. */
+export declare function weeklySummaryDeps(options: {
+    runAt: Date;
+    dryRun: boolean;
+}): Promise<WeeklySummaryDeps>;
+/**
+ * `POST /api/admin/weekly-summary` sends; a GET, or `{"dryRun": true}`,
+ * reports who would be sent what and sends nothing. The body may carry the
+ * `cursor` a previous chunk answered and a smaller `limit`.
+ */
+export declare function weeklySummaryRoute(request: Request): Promise<Response>;
+export {};