@wildo-ai/saas-backend-lib 1.1.2 → 1.1.4

package/dist/esm/security/authentications/services/auth-methods/auth-registration.backend.service.js

@@ -242,9 +242,59 @@ let AuthRegistrationBackendService = class AuthRegistrationBackendService {
     /**
      * User registration.
      * Returns generic success on email collision (anti-enumeration).
+     *
+     * ## Password-less registration, and the three questions it owed (#463)
+     *
+     * `params.method` selects how the registrant will authenticate afterwards. PASSWORD is unchanged
+     * and is the default. MAGIC_LINK and PASSKEY create the account with NO credential and hand back a
+     * magic link; there is no session at signup, because nothing has been proven yet.
+     *
+     * **Verification.** The link IS the proof — clicking it establishes both the address and the first
+     * session, so a magic-link registration cannot reach an authenticated state without verifying. For
+     * PASSKEY this is the only available proof: a passkey attests possession of an authenticator and
+     * says nothing whatsoever about an email address, and enrolling one needs a session bound to a
+     * user, which public signup has no invitation token to stand in for. So a public passkey signup
+     * necessarily routes through the link.
+     *
+     * **Anti-enumeration.** Unchanged and load-bearing: an address already in use returns the same
+     * success response and sends nothing. The observable a magic-link signup adds — whether a mail
+     * arrives — is exactly the one the existing password flow already exposes through its verification
+     * mail, so the surface is not widened. No `userId` is returned for a password-less registration,
+     * which the password path does return under DEFERRED: handing an unauthenticated caller an
+     * identifier for an account they have not shown they own would be a new disclosure.
+     *
+     * **Recovery — the question this issue said to settle first, and the design answers it.** A
+     * passkey-only account that loses its authenticator is NOT locked out, because the account always
+     * has a proven address and the magic link is a standing way in. The registrant requests a link,
+     * signs in, and enrolls a replacement passkey through the authenticated route. No separate recovery
+     * mechanism was needed, and none was invented — which is the strongest form the answer could take,
+     * because a recovery path that exists only for one method is a path nobody maintains.
+     *
+     * The corollary is worth stating so it is not weakened later: **a passkey-only account must keep a
+     * usable email address**, and anything that would let an application disable magic links for a user
+     * type while allowing passkey registration would recreate the lockout. That pairing belongs in
+     * `registration.allowedMethods` validation the day such a switch exists.
      */
     async registerUser(ec, params, ctx) {
         const { email, firstName, lastName, password, organizationName } = params;
+        /*
+         * PASSWORD when unstated — every caller predating #463 meant that, and defaulting keeps a
+         * registration that omits the field behaving exactly as it did.
+         */
+        const method = params.method ?? AuthMethod.PASSWORD;
+        /*
+         * MAGIC_LINK and PASSKEY both establish the account WITHOUT a local credential and prove the
+         * address by a link the registrant must click. So neither can issue a session at signup — there
+         * is nothing yet to authenticate — and both are handled by one branch below.
+         *
+         * PASSKEY is that branch plus an enrollment step, and the reason is worth stating because it was
+         * the design question this issue said to settle first: a passkey proves possession of an
+         * authenticator and says NOTHING about an email address, and enrolling one needs a session bound
+         * to a user. Public signup has no invitation token to stand in for that proof. So a passkey
+         * registration necessarily routes through an address proof, which is the magic link — and that
+         * is also what answers the recovery question, below.
+         */
+        const isPasswordlessMethod = method === AuthMethod.MAGIC_LINK || method === AuthMethod.PASSKEY;
         const { frontendUrl, ipAddress, userAgent, frontendServiceName, activeUserType } = ctx;
         const successResponse = this.authResponseHelper.getAuthResponse(AuthResponseMessageRef.REGISTRATION_SUCCESS);
         this.logDebug('Registration attempt', { email, activeUserType });
@@ -360,29 +410,38 @@ let AuthRegistrationBackendService = class AuthRegistrationBackendService {
             });
         }
         const allowedMethods = registrationConfig.allowedMethods;
-        if (!allowedMethods.includes(AuthMethod.PASSWORD)) {
+        // The requested method, not a hardcoded PASSWORD. An application that lists only MAGIC_LINK now
+        // refuses a password signup, which is the point of the list.
+        if (!allowedMethods.includes(method)) {
             throw this.errorBuilder.buildError(ErrorType.AUTHORIZATION, undefined, {
                 customMessageReference: ErrorCustomMessageReference.AUTHENTICATION_METHOD_NOT_SUPPORTED,
-                context: { method: AuthMethod.PASSWORD, allowedMethods },
+                context: { method, allowedMethods },
             });
         }
-        if (!password) {
-            throw this.errorBuilder.buildError(ErrorType.VALIDATION, undefined, {
-                customMessageReference: ErrorCustomMessageReference.REGISTRATION_PASSWORD_REQUIRED,
-            });
-        }
-        const passwordPolicy = userTypeAuthPolicy?.passwordPolicy;
-        const policyValidation = this.credentialVerifier.validatePasswordPolicy(password, passwordPolicy);
-        if (!policyValidation.valid) {
-            throw this.errorBuilder.buildError(ErrorType.VALIDATION, undefined, {
-                customMessageReference: ErrorCustomMessageReference
-                    .VALIDATION_PASSWORD_POLICY_VIOLATION,
-                context: {
-                    violations: policyValidation.violations,
-                    minLength: passwordPolicy?.minLength,
-                    maxLength: passwordPolicy?.maxLength,
-                },
-            });
+        /*
+         * The credential the method requires, and ONLY for the method that requires one. A password sent
+         * alongside `method: MAGIC_LINK` is ignored rather than refused: the registrant's client may
+         * carry a stale field, and refusing would fail a signup for a value that changes nothing.
+         */
+        if (method === AuthMethod.PASSWORD) {
+            if (!password) {
+                throw this.errorBuilder.buildError(ErrorType.VALIDATION, undefined, {
+                    customMessageReference: ErrorCustomMessageReference.REGISTRATION_PASSWORD_REQUIRED,
+                });
+            }
+            const passwordPolicy = userTypeAuthPolicy?.passwordPolicy;
+            const policyValidation = this.credentialVerifier.validatePasswordPolicy(password, passwordPolicy);
+            if (!policyValidation.valid) {
+                throw this.errorBuilder.buildError(ErrorType.VALIDATION, undefined, {
+                    customMessageReference: ErrorCustomMessageReference
+                        .VALIDATION_PASSWORD_POLICY_VIOLATION,
+                    context: {
+                        violations: policyValidation.violations,
+                        minLength: passwordPolicy?.minLength,
+                        maxLength: passwordPolicy?.maxLength,
+                    },
+                });
+            }
         }
         const existing = await this.userLookup.findUserByEmail(ec, email);
         if (existing) {
@@ -400,10 +459,37 @@ let AuthRegistrationBackendService = class AuthRegistrationBackendService {
                 }
             }
         }
-        const passwordHash = await this.credentialVerifier.hashPassword(password, config.auth.passwordHashing);
-        // W2.6: Email verification mode — DEFERRED creates user as ACTIVE immediately
+        // Undefined for a password-less method, which the persistence request already understands:
+        // `includeCredentials: passwordHash !== undefined` below was written for exactly this shape.
+        const passwordHash = method === AuthMethod.PASSWORD && password
+            ? await this.credentialVerifier.hashPassword(password, config.auth.passwordHashing)
+            : undefined;
+        // W2.6: Email verification mode — DEFERRED creates user as ACTIVE immediately.
         const isDeferredVerification = registrationConfig.emailVerification === EmailVerificationMode.DEFERRED;
-        const initialStatus = isDeferredVerification ? UserStatus.ACTIVE : UserStatus.PENDING_VERIFICATION;
+        /*
+         * A PASSWORD-LESS registrant is created ACTIVE whatever the verification mode says, and the
+         * status is what makes the flow work at all (#463).
+         *
+         * `verifyMagicLink` REFUSES any non-ACTIVE user (generically, as an invalid link — the status is
+         * recorded in the audit trail rather than told to the caller). So a magic-link or passkey
+         * registrant created `PENDING_VERIFICATION` would be sent a link that is rejected the moment they
+         * click it — an account reachable by nobody, created by the flow meant to reach it. The
+         * invitation-accept path already does exactly this: it ACTIVATES the invitee and only then mints
+         * the link.
+         *
+         * ACTIVE here does not mean "access granted". A password-less account holds no credential, so
+         * possession of the emailed link is the ONLY way in, and clicking it is what proves the address.
+         * The status gate and the verification gate are not the same gate, and conflating them is what
+         * makes this look wrong at first glance.
+         *
+         * Recorded because the first version of this code had it exactly inverted — it forced
+         * `PENDING_VERIFICATION` reasoning that "an ACTIVE account with an unproven address is worse",
+         * which reads well and would have shipped a flow that could not complete.
+         */
+        const initialStatusForMethod = isPasswordlessMethod
+            ? UserStatus.ACTIVE
+            : (isDeferredVerification ? UserStatus.ACTIVE : UserStatus.PENDING_VERIFICATION);
+        const initialStatus = initialStatusForMethod;
         // W3.4: Resolve userTypes and defaultAppRoles from the active user type definition
         const userTypes = activeUserType ? [activeUserType] : [];
         const userTypeDefinition = activeUserType
@@ -514,7 +600,10 @@ let AuthRegistrationBackendService = class AuthRegistrationBackendService {
         }
         // W2.6: Only send verification email when emailVerification !== DEFERRED. Delegated to the
         // shared initiator (one implementation across registration / resend / SCIM provisioning).
-        if (!isDeferredVerification) {
+        // Not for a password-less registration: the magic link below IS the address proof, and a second
+        // "confirm your address" mail arriving beside it asks the registrant to do the same thing twice
+        // through a link that grants less.
+        if (!isDeferredVerification && !isPasswordlessMethod) {
             await this.emailVerificationInitiator.sendVerificationEmail({
                 userId: newUser._id,
                 email: newUser.email,
@@ -523,6 +612,64 @@ let AuthRegistrationBackendService = class AuthRegistrationBackendService {
             });
         }
         this.auditLogsService.logUserRegistered({ userId: newUser._id, email: newUser.email, ipAddress, userAgent }, ec).catch(() => { });
+        /*
+         * PASSWORD-LESS REGISTRATION (#463) — the account exists, holds no credential, and its address is
+         * still unproven. A magic link is what closes both: clicking it proves the address AND
+         * establishes the first session.
+         *
+         * No session, no tokens and no `userId` are returned. That is not caution, it is the only honest
+         * answer: nothing has been proven yet, and returning a `userId` here would hand an unauthenticated
+         * caller a fact about an account they have not shown they own.
+         *
+         * No separate verification mail is sent: this link IS the address proof, and a second "confirm
+         * your address" message beside it would ask the registrant to do the same thing twice through a
+         * link that grants less.
+         */
+        if (isPasswordlessMethod) {
+            /*
+             * PASSKEY only: the WebAuthn challenge and the later verify both require a USER_CREDENTIALS row
+             * to exist, and a brand-new registrant has none. Provisioned here for the same reason and in the
+             * same non-fatal way as the invitation-accept path — a failure must not strand an account that
+             * has already been created, and the registrant can still enroll later through the authenticated
+             * route once the magic link has let them in.
+             */
+            if (method === AuthMethod.PASSKEY) {
+                try {
+                    await this._ensurePasswordlessCredentialRecord(ec, newUser._id);
+                }
+                catch (error) {
+                    this.logger.error('Password-less credential row provisioning failed at passkey registration (non-fatal)', {
+                        userId: newUser._id,
+                        ...projectCaughtErrorLogFields(error),
+                    });
+                }
+            }
+            /*
+             * `skipGlobalEnablementCheck: true`, for the reason the invitation path records: the method was
+             * already authorized above against this user type's own `registration.allowedMethods`, and we
+             * are PAST the account creation. Re-rejecting on `sendMagicLink`'s coarser base-policy gate
+             * would strand an account that now exists and has no other way in.
+             */
+            const magic = await this.authOrchestrator.sendMagicLink(ec, { email: newUser.email }, { ipAddress, userAgent }, true);
+            this.logDebug('Password-less registration completed — magic link minted for delivery', {
+                userId: newUser._id,
+                method,
+                // Diagnostic only: an absent token is the anti-enumeration no-op, which cannot happen for an
+                // account we have just created and activated-by-construction, so its absence is worth seeing.
+                hasToken: Boolean(magic.token),
+            });
+            return {
+                ...successResponse,
+                /*
+                 * The registrant's next act differs by method and the client cannot infer it: a magic-link
+                 * signup is finished once they click, a passkey signup has an enrollment step waiting on the
+                 * other side of the same click.
+                 */
+                nextStep: method === AuthMethod.PASSKEY
+                    ? AuthNextStep.PASSKEY_ENROLLMENT
+                    : AuthNextStep.MAGIC_LINK_SENT,
+            };
+        }
         // F7 fix: When email verification is deferred, the user is ACTIVE immediately.
         // Process through the registration pipeline (MFA check, etc.) and issue tokens
         // so the user can start using the app without a separate login step.
@@ -1319,6 +1466,38 @@ let AuthRegistrationBackendService = class AuthRegistrationBackendService {
             : new Set();
         const registrationMethodAllowed = credentialMethod !== AuthMethod.PASSWORD
             || resolvedPolicy?.registration.allowedMethods.includes(AuthMethod.PASSWORD) === true;
+        /*
+         * An UNRESOLVABLE policy and a DISABLED method are different faults, and they must not share a
+         * message (#388).
+         *
+         * When no user type resolves for the organization being joined, `resolvedPolicy` is null and the
+         * enabled set is EMPTY — so every method fails the check below identically, and reporting that as
+         * `AUTHENTICATION_METHOD_NOT_SUPPORTED` names the one thing that is NOT the cause. Measured: an
+         * application whose `userTypes.member` enabled PASSWORD *and* listed it in
+         * `registration.allowedMethods` was refused for PASSWORD, MAGIC_LINK and PASSKEY alike, because
+         * it declared no `organizationTypes` at all. Three methods were tried before anyone looked one
+         * level up, and the first written diagnosis was a false claim that the application had no auth
+         * policy.
+         *
+         * The refusal itself is unchanged and still fail-closed — an unresolvable policy must never
+         * silently permit a method. Only the DIAGNOSTIC is split, so the message names the missing
+         * declaration rather than the method that could never have satisfied it.
+         */
+        if (!resolvedPolicy) {
+            throw this.errorBuilder.buildError(ErrorType.AUTHORIZATION, undefined, {
+                customMessageReference: ErrorCustomMessageReference.INVITATION_ORGANIZATION_TYPE_UNRESOLVED,
+                context: {
+                    // Diagnostic (log-only): AUTHORIZATION strips non-allowlisted context at the wire.
+                    organizationId,
+                    orgType,
+                    resolutionUserType,
+                    method: credentialMethod,
+                    hint: orgType
+                        ? 'No user type resolved for this organization type. Declare `organizationTypes[<orgType>].userTypes` in the application configuration.'
+                        : 'The organization carries no `type`, so no organization-type entry could be looked up. Set the organization type, and declare `organizationTypes` in the application configuration.',
+                },
+            });
+        }
         if (!registrationMethodAllowed
             || !enabledMethods.has(credentialMethod)) {
             throw this.errorBuilder.buildError(ErrorType.AUTHORIZATION, undefined, {