@aglyn/aglyn 1.0.0-beta.143

package/src/lib/app-utils/account-emails.d.ts

@@ -0,0 +1,263 @@
+/**
+ * @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.
+ */
+/**
+ * Several email addresses per account (AGL-2486) — GitHub's model, adopted
+ * verbatim because the answer to "how should a secondary address interact
+ * with an SSO domain claim?" was "do whatever github does to handle this".
+ *
+ * ## The one rule everything else here exists to serve
+ *
+ * **Adding an address to an account NEVER grants organization access.**
+ *
+ * On GitHub, org membership comes from an invitation or from SAML/SCIM
+ * provisioning by the IdP. Verified domains drive notification restrictions
+ * and badges; they do not auto-join anybody. SAML SSO links an *external
+ * identity* — the assertion the IdP makes at sign-in — to the account. It
+ * never matches on the domain of an address the user typed into a settings
+ * form.
+ *
+ * That distinction is load-bearing HERE in a way it is not on GitHub, because
+ * Aglyn has `/api/auth/sso-jit`, which just-in-time provisions org membership
+ * from a verified email's domain. If a secondary address could satisfy an
+ * `ssoDomains` lookup, then adding an address to your own account would JIT
+ * you into somebody else's organization — a privilege escalation delivered by
+ * a feature that looks like a convenience. So:
+ *
+ *  - SSO domain routing and JIT provisioning read the identity **the IdP
+ *    asserted at sign-in** (`decoded.email`, re-verified against the org's
+ *    GCIP tenant). Never this collection.
+ *  - Where a domain is consulted outside the SSO flow at all, it is derived
+ *    from the **primary** address only — which is the Firebase Auth record's
+ *    email, i.e. the same string the token carries.
+ *  - A secondary address is a *sign-in identifier* and a *delivery address*.
+ *    It is never an authorization input.
+ *
+ * `apps/console/specs/account-emails-never-reach-sso.spec.ts` is the negative
+ * proof, and it is written to FAIL if the guards are removed.
+ *
+ * ## Why the primary is special, and why it cannot always be moved
+ *
+ * The primary IS the Firebase Auth record's email. It is what
+ * `decoded.email` carries, so it is the input to
+ * `evaluateSsoDomainPolicy` at the session mint and to the invite-accept
+ * comparison. Re-designating it therefore CHANGES an authorization input —
+ * which is why {@link evaluatePrimaryChange} exists and why it refuses to
+ * move a primary off an SSO-governed domain. Without that refusal, this
+ * feature would hand every governed account a one-click way out of its own
+ * organization's sign-in policy. See the verdict docs below.
+ *
+ * ## This module is PURE
+ *
+ * No Firebase, no env, no I/O — every fact it decides on is passed in. That
+ * is deliberate and copied from `sso-domain-policy.ts`: a spec can drive
+ * every combination directly, and the console (which shows the user *why* a
+ * control is disabled) and the API route (which enforces it) can never
+ * disagree about what the policy says.
+ */
+/**
+ * How many addresses one account may hold, primary included.
+ *
+ * THE CAP IS NOT DECORATION. `users/{uid}/emails` is a new subcollection, and
+ * this repo has a recorded hole from shipping exactly one of those with no
+ * ceiling (AGL-2266: content entries, a free org minting unbounded Firestore
+ * documents from the browser). The rules deny client writes here outright —
+ * see the `emails` match block — so the browser cannot create these at all;
+ * this number is the server-side ceiling that stops the API route being the
+ * unbounded writer instead. Every add path counts before it writes.
+ *
+ * Five rather than GitHub's much larger allowance: each address costs a
+ * verification email, and the point of the feature is "my work address and my
+ * personal one", not address collecting.
+ */
+export declare const MAX_ACCOUNT_EMAILS = 5;
+/** RFC 5321's practical ceiling; also what Firebase Auth accepts. */
+export declare const ACCOUNT_EMAIL_MAX_LENGTH = 254;
+/**
+ * The addresses this feature accepts.
+ *
+ * Deliberately NARROWER than RFC 5322, for a reason beyond tidiness: a
+ * normalized address is used verbatim as a Firestore **document id** (both
+ * `users/{uid}/emails/{address}` and `emailIdentityIndex/{address}`), so the
+ * pattern has to exclude every string a document id may not be:
+ *
+ *  - no `/` — the one character a document id genuinely cannot contain;
+ *  - no leading/trailing/doubled dot in the local part, so the id can never be
+ *    `.` or `..`;
+ *  - the required `@` means the id can never match Firestore's reserved
+ *    `__.*__` form.
+ *
+ * A hash would also have worked and would have been unreadable in the
+ * console, in an export, and in a support conversation. The uniqueness index
+ * is a thing humans have to debug, so it stays legible.
+ */
+export declare const ACCOUNT_EMAIL_PATTERN: RegExp;
+/**
+ * Trim, lower-case, validate. Returns null for anything this feature will not
+ * store — callers treat null as "reject", never as "store the raw input".
+ *
+ * **Lower-casing the LOCAL part is a deliberate, lossy choice.** RFC 5321 says
+ * the local part is the receiving server's business and may be
+ * case-sensitive; in practice no mainstream provider treats it that way, and
+ * Firebase Auth lower-cases it too. It has to happen here because uniqueness
+ * is the whole security property: if `Ada@acme.com` and `ada@acme.com` could
+ * both be verified, they would be two index entries for one mailbox and the
+ * sign-in identifier would be ambiguous — which is the account-takeover shape
+ * this feature has to avoid.
+ *
+ * What is NOT normalized away, on purpose: plus-addressing and dots in the
+ * local part. `a+b@x.com` and `a@x.com` are the same mailbox at Gmail and
+ * different mailboxes almost everywhere else, so collapsing them would refuse
+ * an address the user legitimately owns at every provider that is not Gmail.
+ * Two accounts CAN therefore hold `a@x.com` and `a+b@x.com` separately; that
+ * is correct, because delivery is what an address means here.
+ */
+export declare function normalizeAccountEmail(input: unknown): string | null;
+/**
+ * The domain of an address, lower-cased; null when there isn't one.
+ *
+ * Same shape and same `lastIndexOf` as `domainOf` in `sso-domain-policy.ts`.
+ * It is duplicated rather than imported because that module is server-only
+ * (`@aglyn/tenant-data-admin`) and this one is imported by the console's
+ * client bundle — an nx boundary the lint enforces.
+ *
+ * WHERE THIS MAY BE USED: display, and the primary-change policy below.
+ * NOT for resolving an org, an IdP, or a membership. Those read the address
+ * the IdP asserted, and there is exactly one of those.
+ */
+export declare function accountEmailDomain(email: string | null | undefined): string | null;
+/** One row of `users/{uid}/emails`. */
+export interface AccountEmail {
+    /** Normalized address; mirrors the document id. */
+    address: string;
+    /**
+     * Proven by an emailed round-trip. An UNVERIFIED address does nothing at
+     * all: it is not a sign-in identifier, it receives no account mail beyond
+     * its own verification, it holds no claim on the address against another
+     * account, and it cannot be made primary.
+     */
+    verified: boolean;
+    /**
+     * Exactly one per account. The primary is the Firebase Auth record's email
+     * — receipts, account-critical mail, and every domain-derived decision read
+     * it and only it.
+     */
+    primary: boolean;
+}
+/** Why a primary re-designation was refused. */
+export type PrimaryChangeVerdict = 
+/** Allowed. */
+'ok'
+/** No such address on this account. */
+ | 'unknown-address'
+/** The address exists but has not completed its round-trip. */
+ | 'unverified'
+/** It is already the primary; a no-op, refused so the UI need not guess. */
+ | 'already-primary'
+/**
+ * THE SECURITY REFUSAL. The CURRENT primary sits on a domain this
+ * deployment requires SSO for, and the requested primary does not.
+ *
+ * The primary is `decoded.email`. `evaluateSsoDomainPolicy` reads
+ * `decoded.email` at the session mint and refuses an account on a governed
+ * domain that did not come through the designated tenant. So an account
+ * governed by that policy could add a personal address, promote it, and
+ * walk straight out of the rule — with no IdP involved and nothing in the
+ * org's control plane recording it.
+ *
+ * Refused rather than merely flagged: the whole point of the policy is that
+ * the account cannot choose to be ungoverned.
+ */
+ | 'sso-governed-escape'
+/**
+ * The requested primary sits on a governed domain the account cannot
+ * satisfy — promoting it would make the NEXT session mint refuse them.
+ *
+ * This is self-lockout rather than escalation, so it is refused for the
+ * user's sake rather than the platform's: verifying a mailbox proves
+ * delivery, it does not put the account inside the org's IdP.
+ */
+ | 'sso-governed-lockout';
+export interface PrimaryChangeFacts {
+    /** The account's current primary, or null when it somehow has none. */
+    current: AccountEmail | null;
+    /** The row the caller asked to promote, or null when they named an unknown address. */
+    next: AccountEmail | null;
+    /**
+     * `ssoRequiredDomains()` — domain → the GCIP tenant id that domain must
+     * sign in through. Empty on a self-host install and on any deployment that
+     * has not configured the policy, which makes both refusals inert there.
+     */
+    requiredDomains: Record<string, string>;
+    /**
+     * The tenant the account actually signed in through; null = project pool.
+     * Straight from `decoded.firebase?.tenant`, never inferred.
+     */
+    tenantId: string | null;
+    /**
+     * Whether the enforcement switch (`AGLYN_SSO_DOMAIN_ENFORCEMENT`) is on.
+     *
+     * The LOCKOUT refusal is gated on it, because with the switch off promoting
+     * a governed address locks nobody out. The ESCAPE refusal is NOT gated on
+     * it — see {@link evaluatePrimaryChange}.
+     */
+    enforcementEnabled: boolean;
+}
+export interface PrimaryChangeDecision {
+    allowed: boolean;
+    verdict: PrimaryChangeVerdict;
+    /** What the person is told. Null when allowed. */
+    message: string | null;
+}
+/**
+ * May this account promote `next` to primary?
+ *
+ * Pure and total, so the console can grey out the control with the same
+ * verdict the API route refuses with.
+ *
+ * ## Why the ESCAPE refusal ignores the enforcement switch
+ *
+ * `ssoDomainRefusal` ships inert: it computes `refused` but returns null
+ * until `AGLYN_SSO_DOMAIN_ENFORCEMENT=on`, so the audit trail accumulates
+ * under the real rule before the rule bites. That is right for a gate that
+ * turns people away.
+ *
+ * It is exactly wrong for this one. A primary change is PERSISTENT: promote a
+ * personal address while the switch is off, and when the switch is later
+ * flipped the account is simply not on a governed domain any more. The
+ * escape would already have happened, silently, and the audit trail the
+ * inert period was supposed to build would record nothing — because from the
+ * policy's point of view there is no longer anything to record.
+ *
+ * So the escape is refused whenever the deployment has CONFIGURED governed
+ * domains, switch or no switch. A deployment that has configured none — every
+ * self-host install, and Aglyn itself until the domains are set — is
+ * unaffected, because `requiredDomains` is empty and `requiredTenantFor`
+ * returns null for everything.
+ */
+export declare function evaluatePrimaryChange(facts: PrimaryChangeFacts): PrimaryChangeDecision;
+/**
+ * Whether an address may be removed.
+ *
+ * Two floors, both from GitHub: the primary is not removable (demote it
+ * first), and the LAST VERIFIED address is not removable — an account with no
+ * verified address has no way to receive a password reset, which is an
+ * account nobody can recover.
+ */
+export declare function canRemoveAccountEmail(address: string, emails: readonly AccountEmail[]): {
+    allowed: boolean;
+    message: string | null;
+};

package/src/lib/app-utils/account-emails.js

@@ -0,0 +1,264 @@
+/**
+ * @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.
+ */ /**
+ * Several email addresses per account (AGL-2486) — GitHub's model, adopted
+ * verbatim because the answer to "how should a secondary address interact
+ * with an SSO domain claim?" was "do whatever github does to handle this".
+ *
+ * ## The one rule everything else here exists to serve
+ *
+ * **Adding an address to an account NEVER grants organization access.**
+ *
+ * On GitHub, org membership comes from an invitation or from SAML/SCIM
+ * provisioning by the IdP. Verified domains drive notification restrictions
+ * and badges; they do not auto-join anybody. SAML SSO links an *external
+ * identity* — the assertion the IdP makes at sign-in — to the account. It
+ * never matches on the domain of an address the user typed into a settings
+ * form.
+ *
+ * That distinction is load-bearing HERE in a way it is not on GitHub, because
+ * Aglyn has `/api/auth/sso-jit`, which just-in-time provisions org membership
+ * from a verified email's domain. If a secondary address could satisfy an
+ * `ssoDomains` lookup, then adding an address to your own account would JIT
+ * you into somebody else's organization — a privilege escalation delivered by
+ * a feature that looks like a convenience. So:
+ *
+ *  - SSO domain routing and JIT provisioning read the identity **the IdP
+ *    asserted at sign-in** (`decoded.email`, re-verified against the org's
+ *    GCIP tenant). Never this collection.
+ *  - Where a domain is consulted outside the SSO flow at all, it is derived
+ *    from the **primary** address only — which is the Firebase Auth record's
+ *    email, i.e. the same string the token carries.
+ *  - A secondary address is a *sign-in identifier* and a *delivery address*.
+ *    It is never an authorization input.
+ *
+ * `apps/console/specs/account-emails-never-reach-sso.spec.ts` is the negative
+ * proof, and it is written to FAIL if the guards are removed.
+ *
+ * ## Why the primary is special, and why it cannot always be moved
+ *
+ * The primary IS the Firebase Auth record's email. It is what
+ * `decoded.email` carries, so it is the input to
+ * `evaluateSsoDomainPolicy` at the session mint and to the invite-accept
+ * comparison. Re-designating it therefore CHANGES an authorization input —
+ * which is why {@link evaluatePrimaryChange} exists and why it refuses to
+ * move a primary off an SSO-governed domain. Without that refusal, this
+ * feature would hand every governed account a one-click way out of its own
+ * organization's sign-in policy. See the verdict docs below.
+ *
+ * ## This module is PURE
+ *
+ * No Firebase, no env, no I/O — every fact it decides on is passed in. That
+ * is deliberate and copied from `sso-domain-policy.ts`: a spec can drive
+ * every combination directly, and the console (which shows the user *why* a
+ * control is disabled) and the API route (which enforces it) can never
+ * disagree about what the policy says.
+ */ /**
+ * How many addresses one account may hold, primary included.
+ *
+ * THE CAP IS NOT DECORATION. `users/{uid}/emails` is a new subcollection, and
+ * this repo has a recorded hole from shipping exactly one of those with no
+ * ceiling (AGL-2266: content entries, a free org minting unbounded Firestore
+ * documents from the browser). The rules deny client writes here outright —
+ * see the `emails` match block — so the browser cannot create these at all;
+ * this number is the server-side ceiling that stops the API route being the
+ * unbounded writer instead. Every add path counts before it writes.
+ *
+ * Five rather than GitHub's much larger allowance: each address costs a
+ * verification email, and the point of the feature is "my work address and my
+ * personal one", not address collecting.
+ */ export const MAX_ACCOUNT_EMAILS = 5;
+/** RFC 5321's practical ceiling; also what Firebase Auth accepts. */ export const ACCOUNT_EMAIL_MAX_LENGTH = 254;
+/**
+ * The addresses this feature accepts.
+ *
+ * Deliberately NARROWER than RFC 5322, for a reason beyond tidiness: a
+ * normalized address is used verbatim as a Firestore **document id** (both
+ * `users/{uid}/emails/{address}` and `emailIdentityIndex/{address}`), so the
+ * pattern has to exclude every string a document id may not be:
+ *
+ *  - no `/` — the one character a document id genuinely cannot contain;
+ *  - no leading/trailing/doubled dot in the local part, so the id can never be
+ *    `.` or `..`;
+ *  - the required `@` means the id can never match Firestore's reserved
+ *    `__.*__` form.
+ *
+ * A hash would also have worked and would have been unreadable in the
+ * console, in an export, and in a support conversation. The uniqueness index
+ * is a thing humans have to debug, so it stays legible.
+ */ export const ACCOUNT_EMAIL_PATTERN = /^[a-z0-9!#$%&'*+=?^_`{|}~-]+(?:\.[a-z0-9!#$%&'*+=?^_`{|}~-]+)*@[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)+$/;
+/**
+ * Trim, lower-case, validate. Returns null for anything this feature will not
+ * store — callers treat null as "reject", never as "store the raw input".
+ *
+ * **Lower-casing the LOCAL part is a deliberate, lossy choice.** RFC 5321 says
+ * the local part is the receiving server's business and may be
+ * case-sensitive; in practice no mainstream provider treats it that way, and
+ * Firebase Auth lower-cases it too. It has to happen here because uniqueness
+ * is the whole security property: if `Ada@acme.com` and `ada@acme.com` could
+ * both be verified, they would be two index entries for one mailbox and the
+ * sign-in identifier would be ambiguous — which is the account-takeover shape
+ * this feature has to avoid.
+ *
+ * What is NOT normalized away, on purpose: plus-addressing and dots in the
+ * local part. `a+b@x.com` and `a@x.com` are the same mailbox at Gmail and
+ * different mailboxes almost everywhere else, so collapsing them would refuse
+ * an address the user legitimately owns at every provider that is not Gmail.
+ * Two accounts CAN therefore hold `a@x.com` and `a+b@x.com` separately; that
+ * is correct, because delivery is what an address means here.
+ */ export function normalizeAccountEmail(input) {
+    const raw = String(input != null ? input : '').trim().toLowerCase();
+    if (!raw || raw.length > ACCOUNT_EMAIL_MAX_LENGTH) return null;
+    if (!ACCOUNT_EMAIL_PATTERN.test(raw)) return null;
+    return raw;
+}
+/**
+ * The domain of an address, lower-cased; null when there isn't one.
+ *
+ * Same shape and same `lastIndexOf` as `domainOf` in `sso-domain-policy.ts`.
+ * It is duplicated rather than imported because that module is server-only
+ * (`@aglyn/tenant-data-admin`) and this one is imported by the console's
+ * client bundle — an nx boundary the lint enforces.
+ *
+ * WHERE THIS MAY BE USED: display, and the primary-change policy below.
+ * NOT for resolving an org, an IdP, or a membership. Those read the address
+ * the IdP asserted, and there is exactly one of those.
+ */ export function accountEmailDomain(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);
+}
+/** Exact-match lookup, never a suffix test — `notacme.com` ends with `acme.com`. */ function requiredTenantFor(domain, domains) {
+    var _domains_domain;
+    if (domain === null || domain === '') return null;
+    if (!Object.prototype.hasOwnProperty.call(domains, domain)) return null;
+    return (_domains_domain = domains[domain]) != null ? _domains_domain : null;
+}
+/**
+ * May this account promote `next` to primary?
+ *
+ * Pure and total, so the console can grey out the control with the same
+ * verdict the API route refuses with.
+ *
+ * ## Why the ESCAPE refusal ignores the enforcement switch
+ *
+ * `ssoDomainRefusal` ships inert: it computes `refused` but returns null
+ * until `AGLYN_SSO_DOMAIN_ENFORCEMENT=on`, so the audit trail accumulates
+ * under the real rule before the rule bites. That is right for a gate that
+ * turns people away.
+ *
+ * It is exactly wrong for this one. A primary change is PERSISTENT: promote a
+ * personal address while the switch is off, and when the switch is later
+ * flipped the account is simply not on a governed domain any more. The
+ * escape would already have happened, silently, and the audit trail the
+ * inert period was supposed to build would record nothing — because from the
+ * policy's point of view there is no longer anything to record.
+ *
+ * So the escape is refused whenever the deployment has CONFIGURED governed
+ * domains, switch or no switch. A deployment that has configured none — every
+ * self-host install, and Aglyn itself until the domains are set — is
+ * unaffected, because `requiredDomains` is empty and `requiredTenantFor`
+ * returns null for everything.
+ */ export function evaluatePrimaryChange(facts) {
+    const next = facts.next;
+    if (next === null || next === undefined) {
+        return {
+            allowed: false,
+            verdict: 'unknown-address',
+            message: 'That address is not on this account.'
+        };
+    }
+    if (next.verified !== true) {
+        return {
+            allowed: false,
+            verdict: 'unverified',
+            message: 'Confirm this address before making it your primary.'
+        };
+    }
+    if (next.primary === true) {
+        return {
+            allowed: false,
+            verdict: 'already-primary',
+            message: 'That address is already your primary.'
+        };
+    }
+    const currentAddress = facts.current === null || facts.current === undefined ? null : facts.current.address;
+    const currentRequired = requiredTenantFor(accountEmailDomain(currentAddress), facts.requiredDomains);
+    const nextRequired = requiredTenantFor(accountEmailDomain(next.address), facts.requiredDomains);
+    // ESCAPE: leaving a governed domain for one the policy does not reach.
+    // Note this compares the REQUIREMENT, not the domain — moving between two
+    // domains that are both governed by the same tenant is not an escape.
+    if (currentRequired !== null && nextRequired !== currentRequired) {
+        return {
+            allowed: false,
+            verdict: 'sso-governed-escape',
+            message: 'Your organization requires single sign-on for this address, so it ' + 'has to stay your primary. Ask an administrator to change it for you.'
+        };
+    }
+    // LOCKOUT: moving ONTO a governed domain the account does not sign in
+    // through. Verifying a mailbox proves delivery; it does not put you inside
+    // the organization's identity provider.
+    if (facts.enforcementEnabled === true && nextRequired !== null && facts.tenantId !== nextRequired) {
+        return {
+            allowed: false,
+            verdict: 'sso-governed-lockout',
+            message: 'That address is on a domain that signs in through an identity ' + 'provider. Making it your primary would lock this account out, so ' + 'sign in through that provider instead.'
+        };
+    }
+    return {
+        allowed: true,
+        verdict: 'ok',
+        message: null
+    };
+}
+/**
+ * Whether an address may be removed.
+ *
+ * Two floors, both from GitHub: the primary is not removable (demote it
+ * first), and the LAST VERIFIED address is not removable — an account with no
+ * verified address has no way to receive a password reset, which is an
+ * account nobody can recover.
+ */ export function canRemoveAccountEmail(address, emails) {
+    const row = emails.find((entry)=>entry.address === address);
+    if (row === undefined) {
+        return {
+            allowed: false,
+            message: 'That address is not on this account.'
+        };
+    }
+    if (row.primary === true) {
+        return {
+            allowed: false,
+            message: 'This is your primary address. Make another address primary first.'
+        };
+    }
+    if (row.verified === true) {
+        const otherVerified = emails.filter((entry)=>entry.verified === true && entry.address !== address);
+        if (otherVerified.length === 0) {
+            return {
+                allowed: false,
+                message: 'This is your only confirmed address — removing it would leave no ' + 'way to recover this account.'
+            };
+        }
+    }
+    return {
+        allowed: true,
+        message: null
+    };
+}
+
+//# sourceMappingURL=account-emails.js.map

package/src/lib/app-utils/account-emails.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/account-emails.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 * Several email addresses per account (AGL-2486) — GitHub's model, adopted\n * verbatim because the answer to \"how should a secondary address interact\n * with an SSO domain claim?\" was \"do whatever github does to handle this\".\n *\n * ## The one rule everything else here exists to serve\n *\n * **Adding an address to an account NEVER grants organization access.**\n *\n * On GitHub, org membership comes from an invitation or from SAML/SCIM\n * provisioning by the IdP. Verified domains drive notification restrictions\n * and badges; they do not auto-join anybody. SAML SSO links an *external\n * identity* — the assertion the IdP makes at sign-in — to the account. It\n * never matches on the domain of an address the user typed into a settings\n * form.\n *\n * That distinction is load-bearing HERE in a way it is not on GitHub, because\n * Aglyn has `/api/auth/sso-jit`, which just-in-time provisions org membership\n * from a verified email's domain. If a secondary address could satisfy an\n * `ssoDomains` lookup, then adding an address to your own account would JIT\n * you into somebody else's organization — a privilege escalation delivered by\n * a feature that looks like a convenience. So:\n *\n *  - SSO domain routing and JIT provisioning read the identity **the IdP\n *    asserted at sign-in** (`decoded.email`, re-verified against the org's\n *    GCIP tenant). Never this collection.\n *  - Where a domain is consulted outside the SSO flow at all, it is derived\n *    from the **primary** address only — which is the Firebase Auth record's\n *    email, i.e. the same string the token carries.\n *  - A secondary address is a *sign-in identifier* and a *delivery address*.\n *    It is never an authorization input.\n *\n * `apps/console/specs/account-emails-never-reach-sso.spec.ts` is the negative\n * proof, and it is written to FAIL if the guards are removed.\n *\n * ## Why the primary is special, and why it cannot always be moved\n *\n * The primary IS the Firebase Auth record's email. It is what\n * `decoded.email` carries, so it is the input to\n * `evaluateSsoDomainPolicy` at the session mint and to the invite-accept\n * comparison. Re-designating it therefore CHANGES an authorization input —\n * which is why {@link evaluatePrimaryChange} exists and why it refuses to\n * move a primary off an SSO-governed domain. Without that refusal, this\n * feature would hand every governed account a one-click way out of its own\n * organization's sign-in policy. See the verdict docs below.\n *\n * ## This module is PURE\n *\n * No Firebase, no env, no I/O — every fact it decides on is passed in. That\n * is deliberate and copied from `sso-domain-policy.ts`: a spec can drive\n * every combination directly, and the console (which shows the user *why* a\n * control is disabled) and the API route (which enforces it) can never\n * disagree about what the policy says.\n */\n\n/**\n * How many addresses one account may hold, primary included.\n *\n * THE CAP IS NOT DECORATION. `users/{uid}/emails` is a new subcollection, and\n * this repo has a recorded hole from shipping exactly one of those with no\n * ceiling (AGL-2266: content entries, a free org minting unbounded Firestore\n * documents from the browser). The rules deny client writes here outright —\n * see the `emails` match block — so the browser cannot create these at all;\n * this number is the server-side ceiling that stops the API route being the\n * unbounded writer instead. Every add path counts before it writes.\n *\n * Five rather than GitHub's much larger allowance: each address costs a\n * verification email, and the point of the feature is \"my work address and my\n * personal one\", not address collecting.\n */\nexport const MAX_ACCOUNT_EMAILS = 5\n\n/** RFC 5321's practical ceiling; also what Firebase Auth accepts. */\nexport const ACCOUNT_EMAIL_MAX_LENGTH = 254\n\n/**\n * The addresses this feature accepts.\n *\n * Deliberately NARROWER than RFC 5322, for a reason beyond tidiness: a\n * normalized address is used verbatim as a Firestore **document id** (both\n * `users/{uid}/emails/{address}` and `emailIdentityIndex/{address}`), so the\n * pattern has to exclude every string a document id may not be:\n *\n *  - no `/` — the one character a document id genuinely cannot contain;\n *  - no leading/trailing/doubled dot in the local part, so the id can never be\n *    `.` or `..`;\n *  - the required `@` means the id can never match Firestore's reserved\n *    `__.*__` form.\n *\n * A hash would also have worked and would have been unreadable in the\n * console, in an export, and in a support conversation. The uniqueness index\n * is a thing humans have to debug, so it stays legible.\n */\nexport const ACCOUNT_EMAIL_PATTERN =\n  /^[a-z0-9!#$%&'*+=?^_`{|}~-]+(?:\\.[a-z0-9!#$%&'*+=?^_`{|}~-]+)*@[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)+$/\n\n/**\n * Trim, lower-case, validate. Returns null for anything this feature will not\n * store — callers treat null as \"reject\", never as \"store the raw input\".\n *\n * **Lower-casing the LOCAL part is a deliberate, lossy choice.** RFC 5321 says\n * the local part is the receiving server's business and may be\n * case-sensitive; in practice no mainstream provider treats it that way, and\n * Firebase Auth lower-cases it too. It has to happen here because uniqueness\n * is the whole security property: if `Ada@acme.com` and `ada@acme.com` could\n * both be verified, they would be two index entries for one mailbox and the\n * sign-in identifier would be ambiguous — which is the account-takeover shape\n * this feature has to avoid.\n *\n * What is NOT normalized away, on purpose: plus-addressing and dots in the\n * local part. `a+b@x.com` and `a@x.com` are the same mailbox at Gmail and\n * different mailboxes almost everywhere else, so collapsing them would refuse\n * an address the user legitimately owns at every provider that is not Gmail.\n * Two accounts CAN therefore hold `a@x.com` and `a+b@x.com` separately; that\n * is correct, because delivery is what an address means here.\n */\nexport function normalizeAccountEmail(input: unknown): string | null {\n  const raw = String(input ?? '')\n    .trim()\n    .toLowerCase()\n  if (!raw || raw.length > ACCOUNT_EMAIL_MAX_LENGTH) return null\n  if (!ACCOUNT_EMAIL_PATTERN.test(raw)) return null\n  return raw\n}\n\n/**\n * The domain of an address, lower-cased; null when there isn't one.\n *\n * Same shape and same `lastIndexOf` as `domainOf` in `sso-domain-policy.ts`.\n * It is duplicated rather than imported because that module is server-only\n * (`@aglyn/tenant-data-admin`) and this one is imported by the console's\n * client bundle — an nx boundary the lint enforces.\n *\n * WHERE THIS MAY BE USED: display, and the primary-change policy below.\n * NOT for resolving an org, an IdP, or a membership. Those read the address\n * the IdP asserted, and there is exactly one of those.\n */\nexport function accountEmailDomain(email: string | null | undefined): string | null {\n  const address = String(email ?? '')\n    .trim()\n    .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/** One row of `users/{uid}/emails`. */\nexport interface AccountEmail {\n  /** Normalized address; mirrors the document id. */\n  address: string\n  /**\n   * Proven by an emailed round-trip. An UNVERIFIED address does nothing at\n   * all: it is not a sign-in identifier, it receives no account mail beyond\n   * its own verification, it holds no claim on the address against another\n   * account, and it cannot be made primary.\n   */\n  verified: boolean\n  /**\n   * Exactly one per account. The primary is the Firebase Auth record's email\n   * — receipts, account-critical mail, and every domain-derived decision read\n   * it and only it.\n   */\n  primary: boolean\n}\n\n/** Why a primary re-designation was refused. */\nexport type PrimaryChangeVerdict =\n  /** Allowed. */\n  | 'ok'\n  /** No such address on this account. */\n  | 'unknown-address'\n  /** The address exists but has not completed its round-trip. */\n  | 'unverified'\n  /** It is already the primary; a no-op, refused so the UI need not guess. */\n  | 'already-primary'\n  /**\n   * THE SECURITY REFUSAL. The CURRENT primary sits on a domain this\n   * deployment requires SSO for, and the requested primary does not.\n   *\n   * The primary is `decoded.email`. `evaluateSsoDomainPolicy` reads\n   * `decoded.email` at the session mint and refuses an account on a governed\n   * domain that did not come through the designated tenant. So an account\n   * governed by that policy could add a personal address, promote it, and\n   * walk straight out of the rule — with no IdP involved and nothing in the\n   * org's control plane recording it.\n   *\n   * Refused rather than merely flagged: the whole point of the policy is that\n   * the account cannot choose to be ungoverned.\n   */\n  | 'sso-governed-escape'\n  /**\n   * The requested primary sits on a governed domain the account cannot\n   * satisfy — promoting it would make the NEXT session mint refuse them.\n   *\n   * This is self-lockout rather than escalation, so it is refused for the\n   * user's sake rather than the platform's: verifying a mailbox proves\n   * delivery, it does not put the account inside the org's IdP.\n   */\n  | 'sso-governed-lockout'\n\nexport interface PrimaryChangeFacts {\n  /** The account's current primary, or null when it somehow has none. */\n  current: AccountEmail | null\n  /** The row the caller asked to promote, or null when they named an unknown address. */\n  next: AccountEmail | null\n  /**\n   * `ssoRequiredDomains()` — domain → the GCIP tenant id that domain must\n   * sign in through. Empty on a self-host install and on any deployment that\n   * has not configured the policy, which makes both refusals inert there.\n   */\n  requiredDomains: Record<string, string>\n  /**\n   * The tenant the account actually signed in through; null = project pool.\n   * Straight from `decoded.firebase?.tenant`, never inferred.\n   */\n  tenantId: string | null\n  /**\n   * Whether the enforcement switch (`AGLYN_SSO_DOMAIN_ENFORCEMENT`) is on.\n   *\n   * The LOCKOUT refusal is gated on it, because with the switch off promoting\n   * a governed address locks nobody out. The ESCAPE refusal is NOT gated on\n   * it — see {@link evaluatePrimaryChange}.\n   */\n  enforcementEnabled: boolean\n}\n\nexport interface PrimaryChangeDecision {\n  allowed: boolean\n  verdict: PrimaryChangeVerdict\n  /** What the person is told. Null when allowed. */\n  message: string | null\n}\n\n/** Exact-match lookup, never a suffix test — `notacme.com` ends with `acme.com`. */\nfunction requiredTenantFor(\n  domain: string | null,\n  domains: Record<string, string>,\n): string | null {\n  if (domain === null || domain === '') return null\n  if (!Object.prototype.hasOwnProperty.call(domains, domain)) return null\n  return domains[domain] ?? null\n}\n\n/**\n * May this account promote `next` to primary?\n *\n * Pure and total, so the console can grey out the control with the same\n * verdict the API route refuses with.\n *\n * ## Why the ESCAPE refusal ignores the enforcement switch\n *\n * `ssoDomainRefusal` ships inert: it computes `refused` but returns null\n * until `AGLYN_SSO_DOMAIN_ENFORCEMENT=on`, so the audit trail accumulates\n * under the real rule before the rule bites. That is right for a gate that\n * turns people away.\n *\n * It is exactly wrong for this one. A primary change is PERSISTENT: promote a\n * personal address while the switch is off, and when the switch is later\n * flipped the account is simply not on a governed domain any more. The\n * escape would already have happened, silently, and the audit trail the\n * inert period was supposed to build would record nothing — because from the\n * policy's point of view there is no longer anything to record.\n *\n * So the escape is refused whenever the deployment has CONFIGURED governed\n * domains, switch or no switch. A deployment that has configured none — every\n * self-host install, and Aglyn itself until the domains are set — is\n * unaffected, because `requiredDomains` is empty and `requiredTenantFor`\n * returns null for everything.\n */\nexport function evaluatePrimaryChange(\n  facts: PrimaryChangeFacts,\n): PrimaryChangeDecision {\n  const next = facts.next\n  if (next === null || next === undefined) {\n    return {\n      allowed: false,\n      verdict: 'unknown-address',\n      message: 'That address is not on this account.',\n    }\n  }\n  if (next.verified !== true) {\n    return {\n      allowed: false,\n      verdict: 'unverified',\n      message: 'Confirm this address before making it your primary.',\n    }\n  }\n  if (next.primary === true) {\n    return {\n      allowed: false,\n      verdict: 'already-primary',\n      message: 'That address is already your primary.',\n    }\n  }\n\n  const currentAddress =\n    facts.current === null || facts.current === undefined\n      ? null\n      : facts.current.address\n  const currentRequired = requiredTenantFor(\n    accountEmailDomain(currentAddress),\n    facts.requiredDomains,\n  )\n  const nextRequired = requiredTenantFor(\n    accountEmailDomain(next.address),\n    facts.requiredDomains,\n  )\n\n  // ESCAPE: leaving a governed domain for one the policy does not reach.\n  // Note this compares the REQUIREMENT, not the domain — moving between two\n  // domains that are both governed by the same tenant is not an escape.\n  if (currentRequired !== null && nextRequired !== currentRequired) {\n    return {\n      allowed: false,\n      verdict: 'sso-governed-escape',\n      message:\n        'Your organization requires single sign-on for this address, so it ' +\n        'has to stay your primary. Ask an administrator to change it for you.',\n    }\n  }\n\n  // LOCKOUT: moving ONTO a governed domain the account does not sign in\n  // through. Verifying a mailbox proves delivery; it does not put you inside\n  // the organization's identity provider.\n  if (\n    facts.enforcementEnabled === true &&\n    nextRequired !== null &&\n    facts.tenantId !== nextRequired\n  ) {\n    return {\n      allowed: false,\n      verdict: 'sso-governed-lockout',\n      message:\n        'That address is on a domain that signs in through an identity ' +\n        'provider. Making it your primary would lock this account out, so ' +\n        'sign in through that provider instead.',\n    }\n  }\n\n  return { allowed: true, verdict: 'ok', message: null }\n}\n\n/**\n * Whether an address may be removed.\n *\n * Two floors, both from GitHub: the primary is not removable (demote it\n * first), and the LAST VERIFIED address is not removable — an account with no\n * verified address has no way to receive a password reset, which is an\n * account nobody can recover.\n */\nexport function canRemoveAccountEmail(\n  address: string,\n  emails: readonly AccountEmail[],\n): { allowed: boolean; message: string | null } {\n  const row = emails.find((entry) => entry.address === address)\n  if (row === undefined) {\n    return { allowed: false, message: 'That address is not on this account.' }\n  }\n  if (row.primary === true) {\n    return {\n      allowed: false,\n      message:\n        'This is your primary address. Make another address primary first.',\n    }\n  }\n  if (row.verified === true) {\n    const otherVerified = emails.filter(\n      (entry) => entry.verified === true && entry.address !== address,\n    )\n    if (otherVerified.length === 0) {\n      return {\n        allowed: false,\n        message:\n          'This is your only confirmed address — removing it would leave no ' +\n          'way to recover this account.',\n      }\n    }\n  }\n  return { allowed: true, message: null }\n}\n"],"names":["MAX_ACCOUNT_EMAILS","ACCOUNT_EMAIL_MAX_LENGTH","ACCOUNT_EMAIL_PATTERN","normalizeAccountEmail","input","raw","String","trim","toLowerCase","length","test","accountEmailDomain","email","address","at","lastIndexOf","slice","requiredTenantFor","domain","domains","Object","prototype","hasOwnProperty","call","evaluatePrimaryChange","facts","next","undefined","allowed","verdict","message","verified","primary","currentAddress","current","currentRequired","requiredDomains","nextRequired","enforcementEnabled","tenantId","canRemoveAccountEmail","emails","row","find","entry","otherVerified","filter"],"mappings":"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"}