@logto/schemas 1.43.0 → 1.45.0

package/lib/foundations/jsonb-types/captcha.js

@@ -3,6 +3,7 @@ export var CaptchaType;
 (function (CaptchaType) {
     CaptchaType["RecaptchaEnterprise"] = "RecaptchaEnterprise";
     CaptchaType["Turnstile"] = "Turnstile";
+    CaptchaType["Cap"] = "Cap";
 })(CaptchaType || (CaptchaType = {}));
 export var RecaptchaEnterpriseMode;
 (function (RecaptchaEnterpriseMode) {
@@ -21,8 +22,27 @@ export const recaptchaEnterpriseConfigGuard = z.object({
     projectId: z.string(),
     domain: z.string().optional(),
     mode: z.nativeEnum(RecaptchaEnterpriseMode).optional(),
+    scoreThreshold: z.number().min(0).max(1).optional(),
+});
+/**
+ * Config of a self-hosted Cap Standalone instance.
+ *
+ * @see https://capjs.js.org/guide/standalone/
+ */
+export const capConfigGuard = z.object({
+    type: z.literal(CaptchaType.Cap),
+    /** The public base URL of the Cap Standalone instance, e.g. `https://cap.example.com`. */
+    endpoint: z
+        .string()
+        .url()
+        .refine((value) => ['http:', 'https:'].includes(new URL(value).protocol), {
+        message: 'The endpoint must be an HTTP(S) URL.',
+    }),
+    siteKey: z.string(),
+    secretKey: z.string(),
 });
 export const captchaConfigGuard = z.discriminatedUnion('type', [
     turnstileConfigGuard,
     recaptchaEnterpriseConfigGuard,
+    capConfigGuard,
 ]);

package/lib/foundations/jsonb-types/hooks.d.ts

@@ -33,9 +33,6 @@ type CustomDataHookMutableSchema = `${Exclude<DataHookSchema, DataHookSchema.Tru
 type DataHookPropertyUpdateEvent = `${CustomDataHookMutableSchema}.${DataHookDetailMutationType.Updated}`;
 export type ExceptionHookEvent = 'Identifier.Lockout' | 'Message.RateLimited' | 'Grant.LimitExceeded';
 export type DataHookEvent = BasicDataHookEvent | DataHookPropertyUpdateEvent;
-/** Data hook events that are available only while their feature is under development. */
-export declare const devFeatureHookEvents: readonly ["TrustedDevice.Created", "TrustedDevice.Deleted"];
-export type DevFeatureHookEvent = (typeof devFeatureHookEvents)[number];
 /** The hook event values that can be registered. */
 export declare const hookEvents: readonly [InteractionHookEvent.PostRegister, InteractionHookEvent.PostSignIn, InteractionHookEvent.PostSignInAdaptiveMfaTriggered, InteractionHookEvent.PostResetPassword, "User.Created", "User.Deleted", "User.Data.Updated", "User.SuspensionStatus.Updated", "TrustedDevice.Created", "TrustedDevice.Deleted", "Role.Created", "Role.Deleted", "Role.Data.Updated", "Role.Scopes.Updated", "Scope.Created", "Scope.Deleted", "Scope.Data.Updated", "Organization.Created", "Organization.Deleted", "Organization.Data.Updated", "Organization.Membership.Updated", "OrganizationRole.Created", "OrganizationRole.Deleted", "OrganizationRole.Data.Updated", "OrganizationRole.Scopes.Updated", "OrganizationScope.Created", "OrganizationScope.Deleted", "OrganizationScope.Data.Updated", "Identifier.Lockout", "Message.RateLimited", "Grant.LimitExceeded"];
 /** The type of hook event values that can be registered. */

package/lib/foundations/jsonb-types/hooks.js

@@ -34,11 +34,6 @@ var DataHookDetailMutationType;
 (function (DataHookDetailMutationType) {
     DataHookDetailMutationType["Updated"] = "Updated";
 })(DataHookDetailMutationType || (DataHookDetailMutationType = {}));
-/** Data hook events that are available only while their feature is under development. */
-export const devFeatureHookEvents = Object.freeze([
-    'TrustedDevice.Created',
-    'TrustedDevice.Deleted',
-]);
 /** The hook event values that can be registered. */
 export const hookEvents = Object.freeze([
     InteractionHookEvent.PostRegister,
@@ -49,7 +44,8 @@ export const hookEvents = Object.freeze([
     'User.Deleted',
     'User.Data.Updated',
     'User.SuspensionStatus.Updated',
-    ...devFeatureHookEvents,
+    'TrustedDevice.Created',
+    'TrustedDevice.Deleted',
     'Role.Created',
     'Role.Deleted',
     'Role.Data.Updated',

package/lib/foundations/jsonb-types/saml-application-configs.d.ts

@@ -49,6 +49,29 @@ export declare const samlEncryptionGuard: z.ZodEffects<z.ZodObject<{
     certificate?: string | undefined;
 }>;
 export type SamlEncryption = z.input<typeof samlEncryptionGuard>;
+/** Authentication and request-signature policy for a SAML application. */
+export declare const samlAuthnRequestConfigGuard: z.ZodEffects<z.ZodObject<{
+    forceAuthn: z.ZodOptional<z.ZodBoolean>;
+    requireSignedAuthnRequests: z.ZodOptional<z.ZodBoolean>;
+    signingCertificate: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    forceAuthn?: boolean | undefined;
+    requireSignedAuthnRequests?: boolean | undefined;
+    signingCertificate?: string | undefined;
+}, {
+    forceAuthn?: boolean | undefined;
+    requireSignedAuthnRequests?: boolean | undefined;
+    signingCertificate?: string | undefined;
+}>, {
+    forceAuthn?: boolean | undefined;
+    requireSignedAuthnRequests?: boolean | undefined;
+    signingCertificate?: string | undefined;
+}, {
+    forceAuthn?: boolean | undefined;
+    requireSignedAuthnRequests?: boolean | undefined;
+    signingCertificate?: string | undefined;
+}>;
+export type SamlAuthnRequestConfig = z.infer<typeof samlAuthnRequestConfigGuard>;
 export declare enum NameIdFormat {
     /** Uses unique and persistent identifiers for the user. */
     Persistent = "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent",

package/lib/foundations/jsonb-types/saml-application-configs.js

@@ -28,6 +28,22 @@ export const samlEncryptionGuard = z
         return z.NEVER;
     }
 });
+/** Authentication and request-signature policy for a SAML application. */
+export const samlAuthnRequestConfigGuard = z
+    .object({
+    forceAuthn: z.boolean().optional(),
+    requireSignedAuthnRequests: z.boolean().optional(),
+    signingCertificate: z.string().trim().min(1).optional(),
+})
+    .superRefine(({ requireSignedAuthnRequests, signingCertificate }, ctx) => {
+    if (requireSignedAuthnRequests && !signingCertificate) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['signingCertificate'],
+            message: '`signingCertificate` is required when `requireSignedAuthnRequests` is `true`',
+        });
+    }
+});
 export var NameIdFormat;
 (function (NameIdFormat) {
     /** Uses unique and persistent identifiers for the user. */

package/lib/foundations/jsonb-types/saml-application-configs.test.js

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { samlEncryptionGuard } from './saml-application-configs.js';
+import { samlEncryptionGuard, samlAuthnRequestConfigGuard } from './saml-application-configs.js';
 describe('samlEncryptionGuard', () => {
     // Test valid configurations
     it('should pass when encryption is disabled', () => {
@@ -47,3 +47,26 @@ describe('samlEncryptionGuard', () => {
         }
     });
 });
+describe('samlAuthnRequestConfigGuard', () => {
+    it('keeps the per-application force-login setting', () => {
+        expect(samlAuthnRequestConfigGuard.parse({ forceAuthn: true })).toEqual({ forceAuthn: true });
+    });
+    it('allows default session reuse', () => {
+        expect(samlAuthnRequestConfigGuard.parse({})).toEqual({});
+    });
+    it('rejects a non-boolean force-login setting', () => {
+        expect(samlAuthnRequestConfigGuard.safeParse({ forceAuthn: 'true' }).success).toBe(false);
+    });
+});
+describe('signed AuthnRequest policy', () => {
+    it('requires a signing certificate when signatures are required', () => {
+        expect(samlAuthnRequestConfigGuard.safeParse({ requireSignedAuthnRequests: true }).success).toBe(false);
+    });
+    it('keeps the configured trust certificate', () => {
+        const config = { requireSignedAuthnRequests: true, signingCertificate: 'certificate' };
+        expect(samlAuthnRequestConfigGuard.parse(config)).toEqual(config);
+    });
+    it.each(['', '   '])('rejects an empty certificate: %j', (signingCertificate) => {
+        expect(samlAuthnRequestConfigGuard.safeParse({ signingCertificate }).success).toBe(false);
+    });
+});

package/lib/types/authentication-context.d.ts

@@ -0,0 +1,224 @@
+/**
+ * @file The authoritative vocabulary for the authentication context Logto records on a sign-in or
+ * step-up: the supported Authentication Context Class Reference (ACR) values, their satisfaction
+ * relation, and the Authentication Methods References (AMR) each verification contributes.
+ *
+ * @see {@link https://openid.net/specs/openid-connect-core-1_0.html#IDToken | OpenID Connect Core `acr` / `amr`}
+ * @see {@link https://www.rfc-editor.org/rfc/rfc8176.html | RFC 8176 Authentication Method Reference Values}
+ */
+import { z } from 'zod';
+import { VerificationType } from './verification-records/verification-type.js';
+/** The Logto-defined ACR values. Only these can be requested through `acr_values`. */
+export declare enum LogtoAcr {
+    /**
+     * At least one active factor that Logto can directly verify: password, the user's primary
+     * email / phone verification code, or an enrolled MFA factor. Social and enterprise SSO never
+     * satisfy this class.
+     */
+    FirstFactor = "urn:logto:acr:1fa",
+    /**
+     * A Logto-verifiable {@link LogtoAcr.FirstFactor} context plus an `mfa`-class record from a
+     * different factor, or WebAuthn / passkey with required user verification alone.
+     */
+    Mfa = "urn:logto:acr:mfa"
+}
+/** The ACR values advertised in Discovery as `acr_values_supported`, in the provider order. */
+export declare const logtoAcrValues: readonly [LogtoAcr.FirstFactor, LogtoAcr.Mfa];
+/** Whether a value, e.g. one of the requested `acr_values` or a session `acr`, is a Logto ACR. */
+export declare const isLogtoAcr: (value: unknown) => value is LogtoAcr;
+/**
+ * Whether an achieved ACR, e.g. the `acr` recorded on the OIDC session, satisfies a required
+ * class. An achieved value that is not a Logto ACR, including an absent one, satisfies nothing.
+ */
+export declare const acrSatisfies: (achieved: unknown, required: LogtoAcr) => boolean;
+/** How Experience handles a login prompt that carries a requested authentication context. */
+export declare enum AuthenticationContextMode {
+    /**
+     * An authenticated OIDC session exists but does not satisfy the request: the subject is pinned
+     * from the session and the interaction asks only for the missing assurance.
+     */
+    StepUp = "stepUp"
+}
+/**
+ * The authentication context the OIDC interaction policy writes into the login prompt details
+ * when the authorization request carries supported `acr_values`. Experience reads it at
+ * interaction creation; `interactions.url` routes on {@link RequestedAuthenticationContext.mode}.
+ */
+export type RequestedAuthenticationContext = {
+    /** The supported classes from `acr_values`, in the caller's order. */
+    requestedAcrValues: LogtoAcr[];
+    /**
+     * The first requested class, the minimum the interaction must reach. Present only in step-up
+     * mode; a sign-in without a session applies the same selection rule once the user is identified.
+     */
+    selectedAcr?: LogtoAcr;
+    /** Present only when an authenticated session pins the subject. */
+    mode?: AuthenticationContextMode;
+};
+export declare const requestedAuthenticationContextGuard: z.ZodObject<{
+    requestedAcrValues: z.ZodArray<z.ZodNativeEnum<typeof LogtoAcr>, "many">;
+    selectedAcr: z.ZodOptional<z.ZodNativeEnum<typeof LogtoAcr>>;
+    mode: z.ZodOptional<z.ZodNativeEnum<typeof AuthenticationContextMode>>;
+}, "strip", z.ZodTypeAny, {
+    requestedAcrValues: LogtoAcr[];
+    mode?: AuthenticationContextMode | undefined;
+    selectedAcr?: LogtoAcr | undefined;
+}, {
+    requestedAcrValues: LogtoAcr[];
+    mode?: AuthenticationContextMode | undefined;
+    selectedAcr?: LogtoAcr | undefined;
+}>;
+/**
+ * The login prompt details that carry a {@link RequestedAuthenticationContext}. Absent when the
+ * authorization request carried no supported `acr_values`.
+ */
+export type LoginPromptAuthenticationContextDetails = {
+    authenticationContext?: RequestedAuthenticationContext;
+};
+export declare const loginPromptAuthenticationContextDetailsGuard: z.ZodObject<{
+    authenticationContext: z.ZodOptional<z.ZodObject<{
+        requestedAcrValues: z.ZodArray<z.ZodNativeEnum<typeof LogtoAcr>, "many">;
+        selectedAcr: z.ZodOptional<z.ZodNativeEnum<typeof LogtoAcr>>;
+        mode: z.ZodOptional<z.ZodNativeEnum<typeof AuthenticationContextMode>>;
+    }, "strip", z.ZodTypeAny, {
+        requestedAcrValues: LogtoAcr[];
+        mode?: AuthenticationContextMode | undefined;
+        selectedAcr?: LogtoAcr | undefined;
+    }, {
+        requestedAcrValues: LogtoAcr[];
+        mode?: AuthenticationContextMode | undefined;
+        selectedAcr?: LogtoAcr | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    authenticationContext?: {
+        requestedAcrValues: LogtoAcr[];
+        mode?: AuthenticationContextMode | undefined;
+        selectedAcr?: LogtoAcr | undefined;
+    } | undefined;
+}, {
+    authenticationContext?: {
+        requestedAcrValues: LogtoAcr[];
+        mode?: AuthenticationContextMode | undefined;
+        selectedAcr?: LogtoAcr | undefined;
+    } | undefined;
+}>;
+/**
+ * The AMR values Logto emits. All except {@link AuthenticationMethodReference.Federated} are
+ * registered in RFC 8176; `fed` is the de facto industry value for authentication delegated to an
+ * upstream identity provider and is the only unregistered value Logto emits.
+ */
+export declare enum AuthenticationMethodReference {
+    /** Password-based authentication. */
+    Password = "pwd",
+    /** One-time password: email verification code, TOTP, backup code, or one-time token. */
+    Otp = "otp",
+    /** Verification code delivered by SMS. */
+    Sms = "sms",
+    /** Proof-of-possession of a key, e.g. WebAuthn. */
+    ProofOfPossession = "pop",
+    /** User presence / verification by the authenticator, e.g. WebAuthn user verification. */
+    UserPresence = "user",
+    /** Multiple-factor authentication; appended whenever the achieved ACR is {@link LogtoAcr.Mfa}. */
+    Mfa = "mfa",
+    /** Federated authentication assertion from a social or enterprise SSO provider. */
+    Federated = "fed"
+}
+/**
+ * The role a proof can fill when proofs are combined into an ACR. This is not the ACR a proof
+ * reaches on its own: any proof with a class reaches {@link LogtoAcr.FirstFactor} alone, and the
+ * class only decides which side of the pair the proof can stand on when
+ * {@link LogtoAcr.Mfa} is derived. That level needs a `1fa`-role proof and an `mfa`-role proof of
+ * two different factors, so two `mfa`-class factors, such as a TOTP and a backup code, never reach
+ * it together.
+ */
+export declare enum AuthenticationFactorClass {
+    /** Fills the `1fa` role: a password or a primary email / phone code. */
+    FirstFactor = "1fa",
+    /**
+     * Fills the `mfa` role: TOTP, a backup code or an MFA email / phone code. Alone it reaches
+     * {@link LogtoAcr.FirstFactor}; paired with a `1fa`-role proof of a different factor it reaches
+     * {@link LogtoAcr.Mfa}.
+     */
+    Mfa = "mfa",
+    /**
+     * Fills both roles by itself, so it reaches {@link LogtoAcr.Mfa} alone: a user-verified WebAuthn
+     * authenticator is possession plus user verification in one act. Kept as a class rather than a
+     * special case on the factor so that every "can fill this role" check stays a class comparison
+     * and this table stays the single place that decides.
+     */
+    Both = "both"
+}
+/** Classify a verification type; see {@link authenticationFactorClasses}. */
+export declare const getAuthenticationFactorClass: (type: VerificationType) => AuthenticationFactorClass | undefined;
+/**
+ * The factor a verification record is a proof of. Repeated proofs of one factor count once, and
+ * {@link LogtoAcr.Mfa} needs a `1fa`-class and an `mfa`-class proof of two different factors: a
+ * one-time token and an MFA email code are two proofs of the same mailbox, not two factors.
+ */
+export declare enum AuthenticationFactor {
+    Password = "password",
+    Email = "email",
+    Phone = "phone",
+    Totp = "totp",
+    BackupCode = "backupCode",
+    WebAuthn = "webAuthn",
+    Federated = "federated"
+}
+/** The factor a verification type is a proof of; see {@link authenticationFactors}. */
+export declare const getAuthenticationFactor: (type: VerificationType) => AuthenticationFactor;
+/** The AMR values a verification type contributes; see {@link authenticationMethodReferences}. */
+export declare const getAuthenticationMethodReferences: (type: VerificationType) => readonly AuthenticationMethodReference[];
+/**
+ * Build the `amr` claim from the references each counted proof contributes and the ACR they
+ * achieved: the union in first-seen order, with `mfa` always last, present whenever a proof carries
+ * it (WebAuthn) or the achieved ACR is {@link LogtoAcr.Mfa}.
+ */
+export declare const buildAuthenticationMethodReferences: (references: Iterable<readonly AuthenticationMethodReference[]>, achievedAcr?: LogtoAcr) => AuthenticationMethodReference[];
+/**
+ * Why a proof was recorded: the touchpoint that consumed the credential. Aggregation into `acr` /
+ * `amr` ignores the role; it exists for the MFA gate and for step-up freshness, and never reaches
+ * a token.
+ */
+export declare enum AuthenticationProofRole {
+    /** `createUser()` created the account from the record. */
+    Create = "create",
+    /** `identifyUser()` identified the user with the record. */
+    Identify = "identify",
+    /** The credential or factor was written to the account by this interaction. */
+    Bind = "bind",
+    /** An MFA challenge was answered with the record. */
+    Mfa = "mfa"
+}
+/**
+ * A proof that the identified user authenticated in the interaction, recorded at the single
+ * touchpoint that consumed the credential. What counts is decided where the interaction relies on
+ * the credential, never by inspecting verification records afterwards.
+ */
+export type AuthenticationProof = {
+    /** The verification record id, or `password` for a password established through the profile. */
+    id: string;
+    factor: AuthenticationFactor;
+    /** Absent for a federated proof, which contributes `fed` to AMR and nothing to the ACR. */
+    class?: AuthenticationFactorClass;
+    amr: AuthenticationMethodReference[];
+    role: AuthenticationProofRole;
+};
+export declare const authenticationProofGuard: z.ZodObject<{
+    id: z.ZodString;
+    factor: z.ZodNativeEnum<typeof AuthenticationFactor>;
+    class: z.ZodOptional<z.ZodNativeEnum<typeof AuthenticationFactorClass>>;
+    amr: z.ZodArray<z.ZodNativeEnum<typeof AuthenticationMethodReference>, "many">;
+    role: z.ZodNativeEnum<typeof AuthenticationProofRole>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    role: AuthenticationProofRole;
+    factor: AuthenticationFactor;
+    amr: AuthenticationMethodReference[];
+    class?: AuthenticationFactorClass | undefined;
+}, {
+    id: string;
+    role: AuthenticationProofRole;
+    factor: AuthenticationFactor;
+    amr: AuthenticationMethodReference[];
+    class?: AuthenticationFactorClass | undefined;
+}>;

package/lib/types/authentication-context.js

@@ -0,0 +1,238 @@
+/**
+ * @file The authoritative vocabulary for the authentication context Logto records on a sign-in or
+ * step-up: the supported Authentication Context Class Reference (ACR) values, their satisfaction
+ * relation, and the Authentication Methods References (AMR) each verification contributes.
+ *
+ * @see {@link https://openid.net/specs/openid-connect-core-1_0.html#IDToken | OpenID Connect Core `acr` / `amr`}
+ * @see {@link https://www.rfc-editor.org/rfc/rfc8176.html | RFC 8176 Authentication Method Reference Values}
+ */
+import { z } from 'zod';
+import { VerificationType } from './verification-records/verification-type.js';
+/** The Logto-defined ACR values. Only these can be requested through `acr_values`. */
+export var LogtoAcr;
+(function (LogtoAcr) {
+    /**
+     * At least one active factor that Logto can directly verify: password, the user's primary
+     * email / phone verification code, or an enrolled MFA factor. Social and enterprise SSO never
+     * satisfy this class.
+     */
+    LogtoAcr["FirstFactor"] = "urn:logto:acr:1fa";
+    /**
+     * A Logto-verifiable {@link LogtoAcr.FirstFactor} context plus an `mfa`-class record from a
+     * different factor, or WebAuthn / passkey with required user verification alone.
+     */
+    LogtoAcr["Mfa"] = "urn:logto:acr:mfa";
+})(LogtoAcr || (LogtoAcr = {}));
+/** The ACR values advertised in Discovery as `acr_values_supported`, in the provider order. */
+export const logtoAcrValues = Object.freeze([LogtoAcr.FirstFactor, LogtoAcr.Mfa]);
+const logtoAcrSet = new Set(logtoAcrValues);
+/** Whether a value, e.g. one of the requested `acr_values` or a session `acr`, is a Logto ACR. */
+export const isLogtoAcr = (value) => typeof value === 'string' && logtoAcrSet.has(value);
+/**
+ * The classes each Logto ACR satisfies. Satisfaction is this explicit map, never the provider's
+ * exact match: {@link LogtoAcr.Mfa} is a {@link LogtoAcr.FirstFactor} context plus more, so it
+ * satisfies both classes, while {@link LogtoAcr.FirstFactor} satisfies only itself.
+ */
+const satisfiedAcrs = Object.freeze({
+    [LogtoAcr.FirstFactor]: [LogtoAcr.FirstFactor],
+    [LogtoAcr.Mfa]: [LogtoAcr.Mfa, LogtoAcr.FirstFactor],
+});
+/**
+ * Whether an achieved ACR, e.g. the `acr` recorded on the OIDC session, satisfies a required
+ * class. An achieved value that is not a Logto ACR, including an absent one, satisfies nothing.
+ */
+export const acrSatisfies = (achieved, required) => isLogtoAcr(achieved) && satisfiedAcrs[achieved].includes(required);
+/** How Experience handles a login prompt that carries a requested authentication context. */
+export var AuthenticationContextMode;
+(function (AuthenticationContextMode) {
+    /**
+     * An authenticated OIDC session exists but does not satisfy the request: the subject is pinned
+     * from the session and the interaction asks only for the missing assurance.
+     */
+    AuthenticationContextMode["StepUp"] = "stepUp";
+})(AuthenticationContextMode || (AuthenticationContextMode = {}));
+export const requestedAuthenticationContextGuard = z.object({
+    requestedAcrValues: z.nativeEnum(LogtoAcr).array(),
+    selectedAcr: z.nativeEnum(LogtoAcr).optional(),
+    mode: z.nativeEnum(AuthenticationContextMode).optional(),
+});
+export const loginPromptAuthenticationContextDetailsGuard = z.object({
+    authenticationContext: requestedAuthenticationContextGuard.optional(),
+});
+/**
+ * The AMR values Logto emits. All except {@link AuthenticationMethodReference.Federated} are
+ * registered in RFC 8176; `fed` is the de facto industry value for authentication delegated to an
+ * upstream identity provider and is the only unregistered value Logto emits.
+ */
+export var AuthenticationMethodReference;
+(function (AuthenticationMethodReference) {
+    /** Password-based authentication. */
+    AuthenticationMethodReference["Password"] = "pwd";
+    /** One-time password: email verification code, TOTP, backup code, or one-time token. */
+    AuthenticationMethodReference["Otp"] = "otp";
+    /** Verification code delivered by SMS. */
+    AuthenticationMethodReference["Sms"] = "sms";
+    /** Proof-of-possession of a key, e.g. WebAuthn. */
+    AuthenticationMethodReference["ProofOfPossession"] = "pop";
+    /** User presence / verification by the authenticator, e.g. WebAuthn user verification. */
+    AuthenticationMethodReference["UserPresence"] = "user";
+    /** Multiple-factor authentication; appended whenever the achieved ACR is {@link LogtoAcr.Mfa}. */
+    AuthenticationMethodReference["Mfa"] = "mfa";
+    /** Federated authentication assertion from a social or enterprise SSO provider. */
+    AuthenticationMethodReference["Federated"] = "fed";
+})(AuthenticationMethodReference || (AuthenticationMethodReference = {}));
+/**
+ * The role a proof can fill when proofs are combined into an ACR. This is not the ACR a proof
+ * reaches on its own: any proof with a class reaches {@link LogtoAcr.FirstFactor} alone, and the
+ * class only decides which side of the pair the proof can stand on when
+ * {@link LogtoAcr.Mfa} is derived. That level needs a `1fa`-role proof and an `mfa`-role proof of
+ * two different factors, so two `mfa`-class factors, such as a TOTP and a backup code, never reach
+ * it together.
+ */
+export var AuthenticationFactorClass;
+(function (AuthenticationFactorClass) {
+    /** Fills the `1fa` role: a password or a primary email / phone code. */
+    AuthenticationFactorClass["FirstFactor"] = "1fa";
+    /**
+     * Fills the `mfa` role: TOTP, a backup code or an MFA email / phone code. Alone it reaches
+     * {@link LogtoAcr.FirstFactor}; paired with a `1fa`-role proof of a different factor it reaches
+     * {@link LogtoAcr.Mfa}.
+     */
+    AuthenticationFactorClass["Mfa"] = "mfa";
+    /**
+     * Fills both roles by itself, so it reaches {@link LogtoAcr.Mfa} alone: a user-verified WebAuthn
+     * authenticator is possession plus user verification in one act. Kept as a class rather than a
+     * special case on the factor so that every "can fill this role" check stays a class comparison
+     * and this table stays the single place that decides.
+     */
+    AuthenticationFactorClass["Both"] = "both";
+})(AuthenticationFactorClass || (AuthenticationFactorClass = {}));
+/**
+ * The class each verification type contributes: `1fa`-class, `mfa`-class, `both`, or `undefined`
+ * for social / enterprise SSO, which contribute `fed` to AMR but nothing to the ACR.
+ *
+ * The record is keyed by every {@link VerificationType}, so a new type fails at compile time until
+ * it is mapped here. Logto requires user verification for every WebAuthn ceremony, registration and
+ * authentication alike, so a verified WebAuthn record is user-verified by construction.
+ */
+const authenticationFactorClasses = Object.freeze({
+    [VerificationType.Password]: AuthenticationFactorClass.FirstFactor,
+    [VerificationType.EmailVerificationCode]: AuthenticationFactorClass.FirstFactor,
+    [VerificationType.PhoneVerificationCode]: AuthenticationFactorClass.FirstFactor,
+    [VerificationType.OneTimeToken]: AuthenticationFactorClass.FirstFactor,
+    // A password established by a registration; it is a proof once `createUser()` consumes it.
+    [VerificationType.NewPasswordIdentity]: AuthenticationFactorClass.FirstFactor,
+    [VerificationType.TOTP]: AuthenticationFactorClass.Mfa,
+    [VerificationType.MfaEmailVerificationCode]: AuthenticationFactorClass.Mfa,
+    [VerificationType.MfaPhoneVerificationCode]: AuthenticationFactorClass.Mfa,
+    [VerificationType.BackupCode]: AuthenticationFactorClass.Mfa,
+    [VerificationType.WebAuthn]: AuthenticationFactorClass.Both,
+    [VerificationType.SignInPasskey]: AuthenticationFactorClass.Both,
+    [VerificationType.Social]: undefined,
+    [VerificationType.EnterpriseSso]: undefined,
+});
+/** Classify a verification type; see {@link authenticationFactorClasses}. */
+export const getAuthenticationFactorClass = (type) => authenticationFactorClasses[type];
+/**
+ * The factor a verification record is a proof of. Repeated proofs of one factor count once, and
+ * {@link LogtoAcr.Mfa} needs a `1fa`-class and an `mfa`-class proof of two different factors: a
+ * one-time token and an MFA email code are two proofs of the same mailbox, not two factors.
+ */
+export var AuthenticationFactor;
+(function (AuthenticationFactor) {
+    AuthenticationFactor["Password"] = "password";
+    AuthenticationFactor["Email"] = "email";
+    AuthenticationFactor["Phone"] = "phone";
+    AuthenticationFactor["Totp"] = "totp";
+    AuthenticationFactor["BackupCode"] = "backupCode";
+    AuthenticationFactor["WebAuthn"] = "webAuthn";
+    AuthenticationFactor["Federated"] = "federated";
+})(AuthenticationFactor || (AuthenticationFactor = {}));
+/** Keyed by every {@link VerificationType}, so a new type fails at compile time until mapped. */
+const authenticationFactors = Object.freeze({
+    [VerificationType.Password]: AuthenticationFactor.Password,
+    [VerificationType.NewPasswordIdentity]: AuthenticationFactor.Password,
+    [VerificationType.EmailVerificationCode]: AuthenticationFactor.Email,
+    [VerificationType.MfaEmailVerificationCode]: AuthenticationFactor.Email,
+    [VerificationType.OneTimeToken]: AuthenticationFactor.Email,
+    [VerificationType.PhoneVerificationCode]: AuthenticationFactor.Phone,
+    [VerificationType.MfaPhoneVerificationCode]: AuthenticationFactor.Phone,
+    [VerificationType.TOTP]: AuthenticationFactor.Totp,
+    [VerificationType.BackupCode]: AuthenticationFactor.BackupCode,
+    [VerificationType.WebAuthn]: AuthenticationFactor.WebAuthn,
+    [VerificationType.SignInPasskey]: AuthenticationFactor.WebAuthn,
+    [VerificationType.Social]: AuthenticationFactor.Federated,
+    [VerificationType.EnterpriseSso]: AuthenticationFactor.Federated,
+});
+/** The factor a verification type is a proof of; see {@link authenticationFactors}. */
+export const getAuthenticationFactor = (type) => authenticationFactors[type];
+/**
+ * The AMR values a single verification type contributes, per the step-up tech design. The record
+ * is keyed by every {@link VerificationType}, so a new type fails at compile time until it is
+ * mapped here.
+ *
+ * The trailing `mfa` marker for an achieved {@link LogtoAcr.Mfa} is added by
+ * {@link buildAuthenticationMethodReferences}, not here; WebAuthn carries it inherently because a
+ * user-verified passkey is a multi-factor authenticator on its own.
+ */
+const authenticationMethodReferences = Object.freeze({
+    [VerificationType.Password]: [AuthenticationMethodReference.Password],
+    [VerificationType.NewPasswordIdentity]: [AuthenticationMethodReference.Password],
+    [VerificationType.EmailVerificationCode]: [AuthenticationMethodReference.Otp],
+    [VerificationType.OneTimeToken]: [AuthenticationMethodReference.Otp],
+    [VerificationType.TOTP]: [AuthenticationMethodReference.Otp],
+    [VerificationType.MfaEmailVerificationCode]: [AuthenticationMethodReference.Otp],
+    [VerificationType.BackupCode]: [AuthenticationMethodReference.Otp],
+    [VerificationType.PhoneVerificationCode]: [AuthenticationMethodReference.Sms],
+    [VerificationType.MfaPhoneVerificationCode]: [AuthenticationMethodReference.Sms],
+    [VerificationType.WebAuthn]: [
+        AuthenticationMethodReference.ProofOfPossession,
+        AuthenticationMethodReference.UserPresence,
+        AuthenticationMethodReference.Mfa,
+    ],
+    [VerificationType.SignInPasskey]: [
+        AuthenticationMethodReference.ProofOfPossession,
+        AuthenticationMethodReference.UserPresence,
+        AuthenticationMethodReference.Mfa,
+    ],
+    [VerificationType.Social]: [AuthenticationMethodReference.Federated],
+    [VerificationType.EnterpriseSso]: [AuthenticationMethodReference.Federated],
+});
+/** The AMR values a verification type contributes; see {@link authenticationMethodReferences}. */
+export const getAuthenticationMethodReferences = (type) => authenticationMethodReferences[type];
+/**
+ * Build the `amr` claim from the references each counted proof contributes and the ACR they
+ * achieved: the union in first-seen order, with `mfa` always last, present whenever a proof carries
+ * it (WebAuthn) or the achieved ACR is {@link LogtoAcr.Mfa}.
+ */
+export const buildAuthenticationMethodReferences = (references, achievedAcr) => {
+    const flattened = [...references].flat();
+    const hasMfa = achievedAcr === LogtoAcr.Mfa || flattened.includes(AuthenticationMethodReference.Mfa);
+    return [
+        ...new Set(flattened.filter((reference) => reference !== AuthenticationMethodReference.Mfa)),
+        ...(hasMfa ? [AuthenticationMethodReference.Mfa] : []),
+    ];
+};
+/**
+ * Why a proof was recorded: the touchpoint that consumed the credential. Aggregation into `acr` /
+ * `amr` ignores the role; it exists for the MFA gate and for step-up freshness, and never reaches
+ * a token.
+ */
+export var AuthenticationProofRole;
+(function (AuthenticationProofRole) {
+    /** `createUser()` created the account from the record. */
+    AuthenticationProofRole["Create"] = "create";
+    /** `identifyUser()` identified the user with the record. */
+    AuthenticationProofRole["Identify"] = "identify";
+    /** The credential or factor was written to the account by this interaction. */
+    AuthenticationProofRole["Bind"] = "bind";
+    /** An MFA challenge was answered with the record. */
+    AuthenticationProofRole["Mfa"] = "mfa";
+})(AuthenticationProofRole || (AuthenticationProofRole = {}));
+export const authenticationProofGuard = z.object({
+    id: z.string().min(1),
+    factor: z.nativeEnum(AuthenticationFactor),
+    class: z.nativeEnum(AuthenticationFactorClass).optional(),
+    amr: z.nativeEnum(AuthenticationMethodReference).array().min(1),
+    role: z.nativeEnum(AuthenticationProofRole),
+});

package/lib/types/authentication-context.test.d.ts

@@ -0,0 +1 @@
+export {};