@wildo-ai/saas-models 1.1.3 → 1.1.5

package/dist/esm/security/authentications/authentication.shared.schemas.js

@@ -129,17 +129,33 @@ export const OIDC_RESERVED_ID_TOKEN_CLAIM_NAMES = new Set([
  * | `ORG_SAML` | first or second | a connection resource on the organization, AND a Java runtime with the schema-validation helper compiled on every host that serves SAML |
  * | `ORG_OPENID_CONNECT` | first or second | a connection resource on the organization |
  *
- * ## ⚠️ The organization SSO methods are gated by the USER TYPE first
+ * ## Passkeys sign in without an email, and several accounts can share one device
  *
- * A perfectly configured SSO connection is never offered unless the user type enables `ORG_SAML` /
- * `ORG_OPENID_CONNECT`: the connection lookup only runs when the resolved policy already has the
- * method, so the organization is never consulted. The symptom is a login screen that simply does not
- * show the option, with nothing wrong on the connection and nothing in the logs. Enable the method on
- * the user type BEFORE debugging the connection.
+ * Enabling `PASSKEY` gives the sign-in screen two username-less entries on top of the passkey method
+ * shown after an email: passkey AUTOFILL on the email field, and a "Sign in with a passkey" button. The
+ * device lists every account the person holds a passkey for on this site, and the account that signs
+ * in is the one the chosen passkey belongs to — whatever email, if any, was typed.
+ *
+ * - **Every passkey is a discoverable credential.** There is no setting to turn this off: sign-in
+ *   names no account to the device, so the device must be able to offer the account itself.
+ * - **The sign-in options are identical for every email**, so they never reveal whether an account
+ *   exists or holds a passkey.
+ * - **A signed-in account is held to the same rules as a typed email**: the frontend must be allowed
+ *   to sign in that account's user type, and an organization that restricts its domain to SSO refuses
+ *   a passkey sign-in exactly as it refuses a password.
+ * - **Re-authentication does not offer the username-less entries** — a re-proof must be the same person.
+ *
+ * ## Organization SSO also requires an enabled method in the effective policy
+ *
+ * A configured connection alone does not enable `ORG_SAML` / `ORG_OPENID_CONNECT`. Check the user
+ * type's methods and the application's `auth.orgAuthMethodPolicy`: RESTRICT_ONLY intersects,
+ * EXPAND_WITHIN_SET permits additions from `auth.expandableOrgMethods`, and UNRESTRICTED uses the
+ * organization's set. Explicit organization method overrides intersect across memberships.
+ * Login-method expansion does not weaken the separate MFA, password or step-up requirements.
  *
  * ## Other refusals worth knowing before you pick one
  *
- * - **`EXTERNAL_OAUTH2` will not link or create an account from a provider that does not report the
+ * - **`EXTERNAL_OAUTH2` will not automatically link by email or create an account from a provider that does not report the
  *   email address as VERIFIED.** That is a refusal, not a warning — a provider whose claim mapping
  *   does not surface a verified flag cannot be used for sign-up until the mapping is corrected.
  * - **A missing SAML validation helper surfaces as an invalid signature**, not as a missing
@@ -189,6 +205,33 @@ export var AuthMethod;
     // Biometric/Modern (First or second factor)
     AuthMethod["PASSKEY"] = "PASSKEY"; // WebAuthn/FIDO2 Passkeys
 })(AuthMethod || (AuthMethod = {}));
+/**
+ * Is this method strong enough for a policy that demands a STRONG second factor?
+ *
+ * Derived from the method's own channel rather than from a hand-kept weak list: a second factor
+ * delivered to an email address is excluded, because email is not an acceptable channel for
+ * out-of-band authentication at all — "Email SHALL NOT be used for out-of-band authentication because
+ * it may be vulnerable to: Access using only a password; Interception in transit or at intermediate
+ * mail servers; Rerouting attacks".
+ *
+ * spec-cite: NIST SP 800-63B-4 §3.1.3.1 "Out-of-Band Authenticators"
+ * (https://pages.nist.gov/800-63-4/sp800-63b.html).
+ *
+ * **This reproduces the set the previous rule produced, and that is deliberate.** `requireStrongMFA`
+ * used to be expressed as "drop the factors that need no enrolment", which removed `EMAIL_OTP`
+ * because an address the account already proved needs no setup. That reasoning is sound and it was
+ * reaching the right answer by a property that only coincides with the one it meant — a second
+ * always-available factor on another channel would have been excluded for no reason, and a weak
+ * factor that DID need enrolment would have passed. Deriving from the channel says the thing itself.
+ *
+ * **What it deliberately does NOT change:** `SMS_OTP` stays strong. NIST classes PSTN out-of-band as
+ * the one RESTRICTED authenticator (§3.2.9) — permitted, with an obligation to offer an unrestricted
+ * alternative — rather than as a prohibited channel, and promoting "restricted" to "not strong" is a
+ * posture decision an application should make, not one this predicate should make for it.
+ */
+export function isStrongSecondFactor(method) {
+    return AUTH_METHOD_EVIDENCE[method].channel !== AuthProofChannel.EMAIL;
+}
 /** @wildo_source:part:end saas.models.auth.methods */
 /**
  * Authentication Factor Levels
@@ -238,7 +281,34 @@ export var AuthNextStep;
      * `registerUser`.
      */
     AuthNextStep["PASSKEY_ENROLLMENT"] = "passkey_enrollment";
+    /**
+     * An invitation was accepted and no session was issued (#1158). The user's effective policy disables the sign-in the
+     * invitation link amounts to (possession of the email address), so they continue on the sign-in page with a method
+     * their policy allows.
+     */
+    AuthNextStep["SIGN_IN_REQUIRED"] = "sign_in_required";
 })(AuthNextStep || (AuthNextStep = {}));
+/**
+ * What a re-authentication proof is FOR (#1417). It decides which factors may mint the proof and which
+ * doors accept it.
+ *
+ * - `STEP_UP`: a sensitive operation, removing a way to sign in, or turning TOTP off. Minted only from
+ *   a factor the effective `stepUpAuth.methods` accepts, as a `REAUTH` token.
+ * - `BIND_AUTHENTICATOR`: adding a way to sign in. Minted from any factor the account holds, as a
+ *   `REAUTH_BIND` token, which only the binding doors accept.
+ */
+export var ReAuthenticationPurpose;
+(function (ReAuthenticationPurpose) {
+    ReAuthenticationPurpose["STEP_UP"] = "step_up";
+    ReAuthenticationPurpose["BIND_AUTHENTICATOR"] = "bind_authenticator";
+})(ReAuthenticationPurpose || (ReAuthenticationPurpose = {}));
+/**
+ * The frontend page a federated re-authentication returns to (#1441), inside the popup the step-up
+ * dialog opened. The backend redirects there with `?code=` (a one-time `REAUTH_CODE_EXCHANGE` code) or
+ * `?error=`; the page hands either to the window that opened it and closes. ONE constant, so the URL the
+ * backend writes and the route the frontend mounts cannot disagree.
+ */
+export const REAUTHENTICATION_CALLBACK_PAGE_PATH = '/auth/reauth/callback';
 /**
  * W4.2: Session purpose — drives UI rendering and valid state transitions.
  */
@@ -264,6 +334,19 @@ export var MfaEnrollmentState;
 // ===============================
 // AUTHENTICATION METHOD CLASSIFICATION
 // ===============================
+/**
+ * @wildo_source:part:start saas.models.auth.methods facet:layer:shared facet:audience:app-developer
+ *
+ * ## What each method PROVES, and how the engine decides with it
+ *
+ * Three maps classify a method, and they answer different questions. Reach for the right one:
+ *
+ * | map | answers |
+ * |---|---|
+ * | `AUTH_METHOD_FACTOR_MAP` | WHERE it may sit — first factor, second factor, or either |
+ * | `AUTH_METHOD_CATEGORY_MAP` | which GROUP the sign-in page renders it in |
+ * | `AUTH_METHOD_EVIDENCE` | what it PROVES — the one the engine's factor rules read |
+ */
 /**
  * Authentication Method Factor Classification Map
  */
@@ -283,6 +366,44 @@ export const AUTH_METHOD_FACTOR_MAP = {
     // First or second factor - Modern biometric
     [AuthMethod.PASSKEY]: AuthFactorType.FIRST_OR_SECOND
 };
+/**
+ * The order authentication methods are PRESENTED in, and the order that decides which one is offered first.
+ *
+ * ONE authority, deliberately. Until #1218 there were two and neither was: the backend returned methods in
+ * `AUTH_METHOD_FACTOR_MAP` declaration order — so `defaultFirstFactorMethod` was `PASSWORD` because PASSWORD happens to
+ * be the first key of an unrelated map — and the frontend threw that order away and re-sorted by a display list only it
+ * could see. A domain routed to an enterprise identity provider still met the password form, with "Continue with your
+ * provider" relegated to "other methods".
+ *
+ * The head is the one the sign-in page already used, promoted rather than invented: the organization's own identity
+ * provider first, because a domain that routes to one is telling you where this person signs in; then the credentials a
+ * person holds directly; then the delegated and one-time channels.
+ *
+ * **The TRAILER orders the second-factor challenge, and it is strongest-first.** Those members are second-factor-only
+ * (or, for `SMS_OTP`, first-or-second), so they never appear in a first-factor list and their position here decides one
+ * thing: what the MFA screen offers first. `TOTP` leads them because it is an unrestricted authenticator; `SMS_OTP`
+ * follows because NIST classes PSTN out-of-band as RESTRICTED — permitted, with an obligation to offer an unrestricted
+ * alternative — and `EMAIL_OTP` is last because email "SHALL NOT be used for out-of-band authentication".
+ * spec-cite: NIST SP 800-63B-4 §3.2.9 (restricted authenticators) and §3.1.3.1 (out-of-band authenticators)
+ * (https://pages.nist.gov/800-63-4/sp800-63b.html). The same two sections `isStrongSecondFactor` cites.
+ *
+ * The frontend's deleted display order put `TOTP` last, behind both OTP channels, for no recorded reason — that is what
+ * this replaces, and the change is deliberate rather than incidental.
+ *
+ * TOTAL over the vocabulary, and pinned as total: a method added to `AuthMethod` tomorrow must be PLACED here, rather
+ * than appearing silently at the end of whichever list happened to be sorted last.
+ */
+export const AUTH_METHOD_PRECEDENCE = [
+    AuthMethod.ORG_SAML,
+    AuthMethod.ORG_OPENID_CONNECT,
+    AuthMethod.PASSWORD,
+    AuthMethod.PASSKEY,
+    AuthMethod.MAGIC_LINK,
+    AuthMethod.EXTERNAL_OAUTH2,
+    AuthMethod.TOTP,
+    AuthMethod.SMS_OTP,
+    AuthMethod.EMAIL_OTP,
+];
 /**
  * Authentication Method Category Map
  */
@@ -297,6 +418,258 @@ export const AUTH_METHOD_CATEGORY_MAP = {
     [AuthMethod.EMAIL_OTP]: AuthMethodCategory.MFA_TOKEN,
     [AuthMethod.PASSKEY]: AuthMethodCategory.BIOMETRIC
 };
+/**
+ * The factor CATEGORY a method proves, in the classical three — plus the one Wildo cannot classify.
+ *
+ * `FEDERATED` is not a fourth kind of factor. It means the proof happened at an identity provider, so
+ * what was proved is the IdP's answer and not ours: the engine reads it from the assertion's `acr`
+ * demands and assurance evidence rather than declaring it here. Giving a federated method a concrete
+ * category would be asserting something about somebody else's ceremony.
+ */
+export var AuthFactorCategory;
+(function (AuthFactorCategory) {
+    /** Something you know. */
+    AuthFactorCategory["KNOWLEDGE"] = "KNOWLEDGE";
+    /** Something you have. */
+    AuthFactorCategory["POSSESSION"] = "POSSESSION";
+    /** Something you are. */
+    AuthFactorCategory["INHERENCE"] = "INHERENCE";
+    /** Proved elsewhere; the assertion says what, not this map. */
+    AuthFactorCategory["FEDERATED"] = "FEDERATED";
+})(AuthFactorCategory || (AuthFactorCategory = {}));
+/**
+ * The CHANNEL a method's proof travels over — the axis that decides whether two factors are
+ * independent.
+ *
+ * Two factors that share a channel are one factor counted twice: whoever holds the channel holds
+ * both. A magic link and an email one-time code are the worked example, and the law states the rule
+ * directly — "the breach of one of the elements does not compromise the reliability of the other
+ * elements".
+ *
+ * spec-cite: Commission Delegated Regulation (EU) 2018/389, Art. 9(1) "Independence of the elements"
+ * (https://eur-lex.europa.eu/legal-content/EN/TXT/HTML/?uri=CELEX:32018R0389). That regulation binds
+ * payment service providers; it is cited here as the clearest statement of the principle, never as an
+ * obligation a Wildo application inherits.
+ *
+ * `NONE` means the proof does not travel: a password is typed, a TOTP code is computed from a secret
+ * shared once at enrolment. Those can never collide with anything, which is why the rule is expressed
+ * as "not the same channel" rather than as a list of forbidden pairs.
+ */
+export var AuthProofChannel;
+(function (AuthProofChannel) {
+    /** Nothing is delivered — the proof is presented directly. */
+    AuthProofChannel["NONE"] = "NONE";
+    /** Delivered to a mailbox. */
+    AuthProofChannel["EMAIL"] = "EMAIL";
+    /** Delivered over the public switched telephone network. */
+    AuthProofChannel["PSTN"] = "PSTN";
+    /** Produced by an authenticator on the device, and never transmitted. */
+    AuthProofChannel["LOCAL_AUTHENTICATOR"] = "LOCAL_AUTHENTICATOR";
+    /** Carried in an assertion from an identity provider. */
+    AuthProofChannel["FEDERATED"] = "FEDERATED";
+})(AuthProofChannel || (AuthProofChannel = {}));
+/**
+ * Whether ONE ceremony of this method can prove TWO factors by itself.
+ *
+ * Only a cryptographic authenticator can, and only when an activation factor unlocked its key —
+ * "a multi-factor cryptographic authenticator is 'something you have' and is activated by an
+ * activation factor that represents either 'something you know' or 'something you are'".
+ *
+ * spec-cite: NIST SP 800-63B-4 §3.1.7 "Multi-Factor Cryptographic Authentication"
+ * (https://pages.nist.gov/800-63-4/sp800-63b.html).
+ *
+ * `WHEN_USER_VERIFIED` is therefore a CONDITION, not a property: the same passkey proves two factors
+ * in a ceremony that verified the person and one in a ceremony that did not, and both produce a valid
+ * assertion. The engine reads the WebAuthn `UV` flag off the assertion to tell them apart.
+ */
+export var AuthSelfSufficientMultiFactor;
+(function (AuthSelfSufficientMultiFactor) {
+    /** One ceremony, one factor — always. */
+    AuthSelfSufficientMultiFactor["NEVER"] = "NEVER";
+    /** Two factors when the authenticator locally verified the person, one when it did not. */
+    AuthSelfSufficientMultiFactor["WHEN_USER_VERIFIED"] = "WHEN_USER_VERIFIED";
+})(AuthSelfSufficientMultiFactor || (AuthSelfSufficientMultiFactor = {}));
+/**
+ * Authentication Method Evidence Map — what each method PROVES.
+ *
+ * The two maps above say where a method may sit and how it is grouped on screen. Neither says what it
+ * proves, so every rule that depends on the strength of a proof used to be hand-applied at its own
+ * door and derived differently at each one: the MFA waiver matched a method NAME, `requireStrongMFA`
+ * was expressed as "drop the ones needing no enrolment", and nothing anywhere expressed the channel —
+ * which is why a magic-link sign-in could be completed by an email code to the same mailbox.
+ *
+ * Being `Record<AuthMethod, …>` is the point: a method added to the vocabulary tomorrow does not
+ * compile until it declares what it proves, so the rules below stay total over the vocabulary instead
+ * of quietly omitting it.
+ *
+ * ## Reading the rows
+ *
+ * - **`MAGIC_LINK` is POSSESSION, not knowledge.** It sits beside `PASSWORD` in
+ *   `AUTH_METHOD_CATEGORY_MAP` because both are rendered as "credentials", and that grouping is a
+ *   screen concern. What a magic link proves is control of a mailbox.
+ * - **`TOTP` has NO channel.** The secret is shared once at enrolment and the code is computed
+ *   locally, so nothing is delivered and it can never collide with another factor's channel.
+ * - **The three federated methods are `FEDERATED` on both axes.** Their strength question already has
+ *   an answer — `externalAssuranceEnforcement` and the connection's `acr` demands — and this map must
+ *   not grow a second, competing one.
+ *
+ * Imported from `@wildo-ai/saas-models`.
+ */
+export const AUTH_METHOD_EVIDENCE = {
+    [AuthMethod.PASSWORD]: {
+        factorCategory: AuthFactorCategory.KNOWLEDGE,
+        channel: AuthProofChannel.NONE,
+        phishingResistant: false,
+        selfSufficientMultiFactor: AuthSelfSufficientMultiFactor.NEVER,
+    },
+    [AuthMethod.MAGIC_LINK]: {
+        factorCategory: AuthFactorCategory.POSSESSION,
+        channel: AuthProofChannel.EMAIL,
+        phishingResistant: false,
+        selfSufficientMultiFactor: AuthSelfSufficientMultiFactor.NEVER,
+    },
+    [AuthMethod.EMAIL_OTP]: {
+        factorCategory: AuthFactorCategory.POSSESSION,
+        channel: AuthProofChannel.EMAIL,
+        phishingResistant: false,
+        selfSufficientMultiFactor: AuthSelfSufficientMultiFactor.NEVER,
+    },
+    [AuthMethod.SMS_OTP]: {
+        factorCategory: AuthFactorCategory.POSSESSION,
+        channel: AuthProofChannel.PSTN,
+        phishingResistant: false,
+        selfSufficientMultiFactor: AuthSelfSufficientMultiFactor.NEVER,
+    },
+    [AuthMethod.TOTP]: {
+        factorCategory: AuthFactorCategory.POSSESSION,
+        channel: AuthProofChannel.NONE,
+        phishingResistant: false,
+        selfSufficientMultiFactor: AuthSelfSufficientMultiFactor.NEVER,
+    },
+    [AuthMethod.PASSKEY]: {
+        factorCategory: AuthFactorCategory.POSSESSION,
+        channel: AuthProofChannel.LOCAL_AUTHENTICATOR,
+        phishingResistant: true,
+        selfSufficientMultiFactor: AuthSelfSufficientMultiFactor.WHEN_USER_VERIFIED,
+    },
+    [AuthMethod.EXTERNAL_OAUTH2]: {
+        factorCategory: AuthFactorCategory.FEDERATED,
+        channel: AuthProofChannel.FEDERATED,
+        phishingResistant: false,
+        selfSufficientMultiFactor: AuthSelfSufficientMultiFactor.NEVER,
+    },
+    [AuthMethod.ORG_SAML]: {
+        factorCategory: AuthFactorCategory.FEDERATED,
+        channel: AuthProofChannel.FEDERATED,
+        phishingResistant: false,
+        selfSufficientMultiFactor: AuthSelfSufficientMultiFactor.NEVER,
+    },
+    [AuthMethod.ORG_OPENID_CONNECT]: {
+        factorCategory: AuthFactorCategory.FEDERATED,
+        channel: AuthProofChannel.FEDERATED,
+        phishingResistant: false,
+        selfSufficientMultiFactor: AuthSelfSufficientMultiFactor.NEVER,
+    },
+};
+/**
+ * Do these two methods prove things a single breach could reach?
+ *
+ * The rule the engine applies when it offers or accepts a SECOND factor: a factor whose channel the
+ * FIRST factor already proved is not a second factor. `NONE` never collides, because nothing is
+ * delivered over it.
+ *
+ * @example
+ * sharesProofChannel(AuthMethod.MAGIC_LINK, AuthMethod.EMAIL_OTP); // true — one mailbox, counted twice
+ * sharesProofChannel(AuthMethod.PASSWORD, AuthMethod.EMAIL_OTP);   // false — nothing is delivered to prove a password
+ */
+export function sharesProofChannel(first, second) {
+    const firstChannel = AUTH_METHOD_EVIDENCE[first].channel;
+    if (firstChannel === AuthProofChannel.NONE) {
+        return false;
+    }
+    return firstChannel === AUTH_METHOD_EVIDENCE[second].channel;
+}
+/**
+ * The RFC 8176 `amr` values each method may claim, and nothing else (#1248).
+ *
+ * `amr` is what an ID token tells a relying party about HOW the person authenticated. Wildo demands
+ * exactly this of every identity provider it trusts — `oauth2-authentication` reads an upstream `amr`
+ * as session evidence — and published none of its own, so a client receiving a Wildo ID token could not
+ * make the decision Wildo insists on making about its own upstreams. That asymmetry is the defect.
+ *
+ * spec-cite: RFC 8176 "Authentication Method Reference Values", §2 — the registry of short names and
+ * their definitions (https://www.rfc-editor.org/rfc/rfc8176.html). Every value below is taken from
+ * that registry; none is invented.
+ *
+ * ## Only REGISTERED values, which is why three methods contribute none
+ *
+ * A value outside the registry is a private string a generic relying party cannot read, so an
+ * unregistered "email" or "sso" would be worse than silence — the same reasoning that keeps `acr`
+ * unpublished until Wildo defines what its values mean.
+ *
+ * - **The federated methods contribute nothing.** The registry has no value for "the person proved
+ *   themselves to somebody else and that party vouched for them", and restating the UPSTREAM's `amr`
+ *   as our own would assert a proof this application never observed. What the upstream proved is the
+ *   upstream's claim to make.
+ * - **`MAGIC_LINK` and `EMAIL_OTP` claim `mca`**, "Multiple-channel authentication involving
+ *   communication over distinct channels", which is literally what they are: the credential travels by
+ *   email, a channel distinct from the browser. That is applying a registered definition, not
+ *   stretching one. `EMAIL_OTP` also claims `otp`, which it plainly is; `MAGIC_LINK` is not an OTP —
+ *   the link itself is the credential.
+ * - **`PASSKEY` claims `user`**, "User presence test", because WebAuthn always tests presence. It does
+ *   NOT claim `hwk` or `swk`: which is true depends on whether the credential is single-device or
+ *   synced, and the session does not carry the credential's device type. Claiming either would be a
+ *   guess about the authenticator, and `hwk` is precisely what a relying party reads as
+ *   phishing-resistant hardware.
+ */
+export const AUTH_METHOD_AMR = {
+    [AuthMethod.PASSWORD]: ['pwd'],
+    [AuthMethod.TOTP]: ['otp'],
+    [AuthMethod.SMS_OTP]: ['sms', 'otp'],
+    [AuthMethod.EMAIL_OTP]: ['mca', 'otp'],
+    [AuthMethod.MAGIC_LINK]: ['mca'],
+    [AuthMethod.PASSKEY]: ['user'],
+    [AuthMethod.EXTERNAL_OAUTH2]: [],
+    [AuthMethod.ORG_OPENID_CONNECT]: [],
+    [AuthMethod.ORG_SAML]: [],
+};
+/**
+ * What an ID token may say about how THIS session was authenticated (#1248).
+ *
+ * Returns the sorted, de-duplicated registered `amr` values for the factors the session actually
+ * completed — never for the factors it could have used. An empty result means the session has nothing
+ * a relying party could read, and the caller omits the claim rather than emitting `[]`: an empty array
+ * asserts "authenticated by no method", which is false, where an absent claim correctly says nothing.
+ *
+ * ## `mfa` is DERIVED, and it is the value that matters most
+ *
+ * "Multiple-factor authentication" is claimed when the session genuinely holds two independent proofs,
+ * decided by the same {@link AUTH_METHOD_EVIDENCE} channels that decide whether a second factor is
+ * admissible — so an ID token cannot claim `mfa` for a pair this application's own sign-in doors would
+ * refuse as sharing a channel. A password plus an email OTP is two methods and one mailbox; it does
+ * not claim `mfa`.
+ *
+ * A single passkey claims `mfa` when the authenticator locally verified the person, because that
+ * ceremony IS two factors — possession of the authenticator and the activation that unlocked it — and
+ * the WebAuthn UV flag is the only report that the activation happened. That is the distinction the
+ * acceptance asks an ID token to carry, and it is readable only because the verifier reads the flag
+ * off the assertion rather than inferring it from the policy that requested it.
+ */
+export function deriveAuthenticationMethodReferences(completedFactors, ceremony) {
+    const values = new Set();
+    for (const method of completedFactors) {
+        for (const value of AUTH_METHOD_AMR[method] ?? [])
+            values.add(value);
+    }
+    const userVerifiedPasskey = completedFactors.includes(AuthMethod.PASSKEY) && ceremony?.passkeyUserVerified === true;
+    const independentPair = completedFactors.some((first, index) => completedFactors.slice(index + 1).some((second) => !sharesProofChannel(first, second)));
+    if (userVerifiedPasskey || independentPair)
+        values.add('mfa');
+    // Sorted so the claim is stable across sign-ins completing the same factors in a different order —
+    // a relying party comparing tokens should not see a difference that is only iteration order.
+    return [...values].sort();
+}
+/** @wildo_source:part:end saas.models.auth.methods */
 /**
  * Scope type for auth policies — organization-level vs application-level.
  *
@@ -332,7 +705,37 @@ export const AvailableMethodSchema = z.object({
     category: z.enum(AuthMethodCategory),
     canBeFirstFactor: z.boolean(),
     canBeSecondFactor: z.boolean(),
-    required: z.boolean(),
+    /**
+     * The organization that owns this address requires THIS method as the first factor.
+     *
+     * True only where an enterprise connection's `enforcement.requireSSO` is set, so it appears on
+     * `ORG_SAML` and `ORG_OPENID_CONNECT` and nowhere else. It is not the same statement as "this is
+     * the only method offered": when the tenant allows a password fallback, or names break-glass
+     * accounts, the offered list deliberately KEEPS the password field for every address at the domain
+     * (enumeration safety — narrowing it for the listed accounts would publish who they are). This flag
+     * is what lets the sign-in page say that the password beside it is a fallback rather than a peer.
+     */
+    enforcedFirstFactor: z.boolean(),
+    /**
+     * The account's policy requires a second factor, and this method can serve as one.
+     *
+     * Meaningful only in a SECOND-factor list. It is derived from `mfaPolicy.requireMFA` together with
+     * the method's factor classification, so it is true of every acceptable second factor at once — it
+     * says "a second factor is mandatory", never "this particular one is".
+     *
+     * ## Why this is two fields and not one
+     *
+     * Both of these were a single `required: boolean` until #1220, written by two branches with
+     * incompatible meanings, and `_buildAvailableMethodObject` builds BOTH the first- and second-factor
+     * lists — so each writer was noise in the other's list. In the FIRST-factor list a passkey came back
+     * `required: true` merely because the user type demands MFA, where it means nothing at all; the flag
+     * was read by no frontend code, so nothing ever noticed. A consumer taking it at face value would
+     * have presented a passkey as a mandatory first factor, which is the opposite of true.
+     *
+     * Two names, one writer each, each meaningful in exactly one list. Merging them back would restore a
+     * field whose meaning depends on which list you found it in, which is not a meaning.
+     */
+    satisfiesRequiredSecondFactor: z.boolean(),
     // Provider-specific information
     oauth2ProviderRefs: z.array(z.string()).optional(), // For third-party OAuth2
     ssoIds: z.array(z.string()).optional(), // For organization SSO