@cairs-npm/express-auth-2fa 0.1.1 → 0.1.3

package/dist/index.d.cts

@@ -1,6 +1,6 @@
 import * as mongodb from 'mongodb';
 import { ObjectId, Db, MongoClient } from 'mongodb';
-import { MethodType, ErrorCode, LoginResponse, Method } from '@cairs-npm/auth-2fa-contract';
+import { MethodType, ErrorCode, LoginResponse, LoginMfaRequired, Method } from '@cairs-npm/auth-2fa-contract';
 export { ApiError, Method, Session, Tokens, User } from '@cairs-npm/auth-2fa-contract';
 import { Request, Response, NextFunction, Router } from 'express';
 import { z } from 'zod';
@@ -58,6 +58,10 @@ interface ChallengeDoc {
     smsSentAt: Date | null;
     smsSendCount: number;
     attempts: number;
+    /** Started by /auth/login/start (no password): sign-in records only the second factor. */
+    passwordless?: boolean;
+    /** `type` from /auth/login/start (e.g. "badge"), so the host app knows who's signing in. */
+    clientType?: string;
     /** WebAuthn challenge issued for this login / passkey enrollment (base64url). */
     webauthnChallenge?: string | null;
     expiresAt: Date;
@@ -121,7 +125,11 @@ interface AdapterUser {
     [key: string]: unknown;
 }
 interface UserAdapter {
-    findByLogin: (login: string) => Promise<AdapterUser | null>;
+    /** `ctx` is only set by passwordless sign-in (/auth/login/start), e.g. { type: "badge", passwordless: true }. */
+    findByLogin: (login: string, ctx?: {
+        type?: string;
+        passwordless?: boolean;
+    }) => Promise<AdapterUser | null>;
     findById: (id: string) => Promise<AdapterUser | null>;
 }
 interface SmsProvider {
@@ -188,6 +196,24 @@ declare const configSchema: z.ZodObject<{
         rpName: string;
         origins: string[];
     }>>;
+    /**
+     * Allow POST /auth/login/start: sign in with the identifier and a verification method only
+     * (no password). Single-factor — enable only for apps that already sign in by code. Pass a
+     * function to allow it per request, e.g. only for `type: "badge"`.
+     */
+    passwordlessLogin: z.ZodDefault<z.ZodUnion<[z.ZodBoolean, z.ZodType<(input: {
+        username: string;
+        type?: string;
+    }) => boolean | Promise<boolean>, z.ZodTypeDef, (input: {
+        username: string;
+        type?: string;
+    }) => boolean | Promise<boolean>>]>>;
+    /**
+     * Project-wide 2-Step Verification switch. False: password sign-in never asks for a code
+     * (whatever each user chose) and the two-step setting can't be turned on. Passwordless
+     * sign-in still sends a code — it's the only factor there.
+     */
+    twoStepEnabled: z.ZodDefault<z.ZodBoolean>;
     /** 2-Step Verification state for users who have not chosen one yet. */
     twoStepDefault: z.ZodDefault<z.ZodBoolean>;
     limits: z.ZodDefault<z.ZodObject<{
@@ -309,6 +335,11 @@ declare const configSchema: z.ZodObject<{
     userAdapter: UserAdapter;
     smsProvider: SmsProvider;
     collectionPrefix: string;
+    passwordlessLogin: boolean | ((input: {
+        username: string;
+        type?: string;
+    }) => boolean | Promise<boolean>);
+    twoStepEnabled: boolean;
     twoStepDefault: boolean;
     limits: {
         loginMaxAttempts: number;
@@ -374,6 +405,11 @@ declare const configSchema: z.ZodObject<{
         rpName: string;
         origins: string[];
     } | undefined;
+    passwordlessLogin?: boolean | ((input: {
+        username: string;
+        type?: string;
+    }) => boolean | Promise<boolean>) | undefined;
+    twoStepEnabled?: boolean | undefined;
     twoStepDefault?: boolean | undefined;
     limits?: {
         loginMaxAttempts?: number | undefined;
@@ -533,6 +569,17 @@ declare class AuthService {
         password: string;
         rememberMe: boolean;
     }): Promise<LoginResponse>;
+    /**
+     * Passwordless sign-in (config.passwordlessLogin): the identifier alone starts the same
+     * verification step as a password sign-in. Always needs a method — there's no password to
+     * fall back on.
+     */
+    loginStart(req: Request, input: {
+        username: string;
+        type?: string;
+    }): Promise<LoginMfaRequired>;
+    /** Creates a login challenge over the user's active methods; null when there are none. */
+    private issueLoginChallenge;
     private registerFailedLogin;
     private resetFailedLogins;
     private checkTrustedDevice;

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as mongodb from 'mongodb';
 import { ObjectId, Db, MongoClient } from 'mongodb';
-import { MethodType, ErrorCode, LoginResponse, Method } from '@cairs-npm/auth-2fa-contract';
+import { MethodType, ErrorCode, LoginResponse, LoginMfaRequired, Method } from '@cairs-npm/auth-2fa-contract';
 export { ApiError, Method, Session, Tokens, User } from '@cairs-npm/auth-2fa-contract';
 import { Request, Response, NextFunction, Router } from 'express';
 import { z } from 'zod';
@@ -58,6 +58,10 @@ interface ChallengeDoc {
     smsSentAt: Date | null;
     smsSendCount: number;
     attempts: number;
+    /** Started by /auth/login/start (no password): sign-in records only the second factor. */
+    passwordless?: boolean;
+    /** `type` from /auth/login/start (e.g. "badge"), so the host app knows who's signing in. */
+    clientType?: string;
     /** WebAuthn challenge issued for this login / passkey enrollment (base64url). */
     webauthnChallenge?: string | null;
     expiresAt: Date;
@@ -121,7 +125,11 @@ interface AdapterUser {
     [key: string]: unknown;
 }
 interface UserAdapter {
-    findByLogin: (login: string) => Promise<AdapterUser | null>;
+    /** `ctx` is only set by passwordless sign-in (/auth/login/start), e.g. { type: "badge", passwordless: true }. */
+    findByLogin: (login: string, ctx?: {
+        type?: string;
+        passwordless?: boolean;
+    }) => Promise<AdapterUser | null>;
     findById: (id: string) => Promise<AdapterUser | null>;
 }
 interface SmsProvider {
@@ -188,6 +196,24 @@ declare const configSchema: z.ZodObject<{
         rpName: string;
         origins: string[];
     }>>;
+    /**
+     * Allow POST /auth/login/start: sign in with the identifier and a verification method only
+     * (no password). Single-factor — enable only for apps that already sign in by code. Pass a
+     * function to allow it per request, e.g. only for `type: "badge"`.
+     */
+    passwordlessLogin: z.ZodDefault<z.ZodUnion<[z.ZodBoolean, z.ZodType<(input: {
+        username: string;
+        type?: string;
+    }) => boolean | Promise<boolean>, z.ZodTypeDef, (input: {
+        username: string;
+        type?: string;
+    }) => boolean | Promise<boolean>>]>>;
+    /**
+     * Project-wide 2-Step Verification switch. False: password sign-in never asks for a code
+     * (whatever each user chose) and the two-step setting can't be turned on. Passwordless
+     * sign-in still sends a code — it's the only factor there.
+     */
+    twoStepEnabled: z.ZodDefault<z.ZodBoolean>;
     /** 2-Step Verification state for users who have not chosen one yet. */
     twoStepDefault: z.ZodDefault<z.ZodBoolean>;
     limits: z.ZodDefault<z.ZodObject<{
@@ -309,6 +335,11 @@ declare const configSchema: z.ZodObject<{
     userAdapter: UserAdapter;
     smsProvider: SmsProvider;
     collectionPrefix: string;
+    passwordlessLogin: boolean | ((input: {
+        username: string;
+        type?: string;
+    }) => boolean | Promise<boolean>);
+    twoStepEnabled: boolean;
     twoStepDefault: boolean;
     limits: {
         loginMaxAttempts: number;
@@ -374,6 +405,11 @@ declare const configSchema: z.ZodObject<{
         rpName: string;
         origins: string[];
     } | undefined;
+    passwordlessLogin?: boolean | ((input: {
+        username: string;
+        type?: string;
+    }) => boolean | Promise<boolean>) | undefined;
+    twoStepEnabled?: boolean | undefined;
     twoStepDefault?: boolean | undefined;
     limits?: {
         loginMaxAttempts?: number | undefined;
@@ -533,6 +569,17 @@ declare class AuthService {
         password: string;
         rememberMe: boolean;
     }): Promise<LoginResponse>;
+    /**
+     * Passwordless sign-in (config.passwordlessLogin): the identifier alone starts the same
+     * verification step as a password sign-in. Always needs a method — there's no password to
+     * fall back on.
+     */
+    loginStart(req: Request, input: {
+        username: string;
+        type?: string;
+    }): Promise<LoginMfaRequired>;
+    /** Creates a login challenge over the user's active methods; null when there are none. */
+    private issueLoginChallenge;
     private registerFailedLogin;
     private resetFailedLogins;
     private checkTrustedDevice;

package/dist/index.js

@@ -88,6 +88,23 @@ var configSchema = z.object({
     rpName: z.string().min(1),
     origins: z.array(z.string().url()).min(1)
   }).optional(),
+  /**
+   * Allow POST /auth/login/start: sign in with the identifier and a verification method only
+   * (no password). Single-factor — enable only for apps that already sign in by code. Pass a
+   * function to allow it per request, e.g. only for `type: "badge"`.
+   */
+  passwordlessLogin: z.union([
+    z.boolean(),
+    z.custom(
+      (v) => typeof v === "function"
+    )
+  ]).default(false),
+  /**
+   * Project-wide 2-Step Verification switch. False: password sign-in never asks for a code
+   * (whatever each user chose) and the two-step setting can't be turned on. Passwordless
+   * sign-in still sends a code — it's the only factor there.
+   */
+  twoStepEnabled: z.boolean().default(true),
   /** 2-Step Verification state for users who have not chosen one yet. */
   twoStepDefault: z.boolean().default(false),
   limits: limitSchema.default({}),
@@ -544,11 +561,16 @@ var MethodService = class {
     const cred = await this.cols.credentials.findOne({ userId });
     const docs = await this.cols.methods.find({ userId, status: "active" }).toArray();
     const methods = docs.sort((a, b) => Number(b.isDefault) - Number(a.isDefault) || a.createdAt.getTime() - b.createdAt.getTime()).map(toApiMethod);
-    return { twoStepEnabled: cred?.twoStepEnabled ?? this.config.twoStepDefault, methods };
+    const available = this.config.twoStepEnabled;
+    const twoStepEnabled = available && (cred?.twoStepEnabled ?? this.config.twoStepDefault);
+    return { twoStepEnabled, twoStepAvailable: available, methods };
   }
   /** BR-15 — enable needs ≥1 active method; disable needs step-up + revokes trusted devices. */
   async setTwoStep(userId, sid, enabled, stepUpToken) {
     const now = this.config.clock();
+    if (enabled && !this.config.twoStepEnabled) {
+      throw apiError(409, "VALIDATION_ERROR", "2-Step Verification is turned off for this application.");
+    }
     if (enabled) {
       await ensureEmailMethod(this.config, this.cols, userId);
       const count = await this.cols.methods.countDocuments({ userId, status: "active" });
@@ -788,18 +810,48 @@ var AuthService = class {
       throw apiError(423, "LOCKED", "Too many attempts. Try again later.", { retryAt: cred.lockedUntil });
     }
     await this.resetFailedLogins(cred, now);
-    const trustedOk = cred.twoStepEnabled && await this.checkTrustedDevice(req, user.id);
-    if (!cred.twoStepEnabled || trustedOk) {
+    const twoStep = this.config.twoStepEnabled && cred.twoStepEnabled;
+    const trustedOk = twoStep && await this.checkTrustedDevice(req, user.id);
+    if (!twoStep || trustedOk) {
       await this.audit.record(user.id, "login_success", ctx);
       return this.authenticate(user.id, req, res, ["pwd"], { rememberMe: input.rememberMe });
     }
-    await ensureEmailMethod(this.config, this.cols, user.id, user.email);
-    await pruneUnreadableMethods(this.config, this.cols, user.id, this.audit);
-    const active = await this.cols.methods.find({ userId: user.id, status: "active" }).toArray();
-    if (active.length === 0) {
+    const challenge = await this.issueLoginChallenge(user, ctx, now, false);
+    if (!challenge) {
       await this.audit.record(user.id, "login_success", ctx);
       return this.authenticate(user.id, req, res, ["pwd"], { rememberMe: input.rememberMe });
     }
+    return challenge;
+  }
+  /**
+   * Passwordless sign-in (config.passwordlessLogin): the identifier alone starts the same
+   * verification step as a password sign-in. Always needs a method — there's no password to
+   * fall back on.
+   */
+  async loginStart(req, input) {
+    const allow = this.config.passwordlessLogin;
+    const allowed = typeof allow === "function" ? await allow({ username: input.username, type: input.type }) : allow;
+    if (!allowed) throw apiError(404, "VALIDATION_ERROR", "Not found.");
+    const now = this.config.clock();
+    const ctx = ctxOf(req);
+    const user = await this.config.userAdapter.findByLogin(input.username, { type: input.type, passwordless: true });
+    if (!user) throw apiError(404, "INVALID_CREDENTIALS", "We couldn't find an account with that email.");
+    const cred = await this.getCredentials(user.id);
+    if (cred?.lockedUntil && cred.lockedUntil.getTime() > now.getTime()) {
+      throw apiError(423, "LOCKED", "Too many attempts. Try again later.", { retryAt: cred.lockedUntil });
+    }
+    const challenge = await this.issueLoginChallenge(user, ctx, now, true, input.type);
+    if (!challenge) {
+      throw apiError(409, "NO_METHODS", "We can't send you a code: this account has no email or verification method.");
+    }
+    return challenge;
+  }
+  /** Creates a login challenge over the user's active methods; null when there are none. */
+  async issueLoginChallenge(user, ctx, now, passwordless, clientType) {
+    await ensureEmailMethod(this.config, this.cols, user.id, user.email);
+    await pruneUnreadableMethods(this.config, this.cols, user.id, this.audit);
+    const active = await this.cols.methods.find({ userId: user.id, status: "active" }).toArray();
+    if (active.length === 0) return null;
     const challengeId = randomId("chg");
     await this.cols.challenges.insertOne({
       _id: challengeId,
@@ -810,6 +862,8 @@ var AuthService = class {
       smsSentAt: null,
       smsSendCount: 0,
       attempts: 0,
+      ...passwordless ? { passwordless: true } : {},
+      ...clientType ? { clientType } : {},
       expiresAt: new Date(now.getTime() + this.config.ttl.challengeSec * 1e3),
       createdAt: now
     });
@@ -1042,7 +1096,7 @@ var MfaService = class {
     await this.audit.record(ch.userId, "login_success", ctxOf(req));
     const user = await this.config.userAdapter.findById(ch.userId);
     const ua = req.headers["user-agent"];
-    const result = await this.auth.authenticate(ch.userId, req, res, ["pwd", "otp"], {
+    const result = await this.auth.authenticate(ch.userId, req, res, ch.passwordless ? ["otp"] : ["pwd", "otp"], {
       rememberDevice: input.rememberDevice,
       deviceLabel: typeof ua === "string" ? ua.slice(0, 80) : void 0
     });
@@ -1294,7 +1348,7 @@ var PasskeyService = class {
     );
     await this.audit.record(ch.userId, "login_success", ctxOf(req));
     const ua = req.headers["user-agent"];
-    const result = await this.auth.authenticate(ch.userId, req, res, ["pwd", "hwk"], {
+    const result = await this.auth.authenticate(ch.userId, req, res, ch.passwordless ? ["hwk"] : ["pwd", "hwk"], {
       rememberDevice: input.rememberDevice,
       deviceLabel: typeof ua === "string" ? ua.slice(0, 80) : void 0
     });
@@ -1456,6 +1510,7 @@ var AuditService = class {
 import { Router } from "express";
 import {
   loginRequestSchema,
+  loginStartRequestSchema,
   mfaSendRequestSchema,
   mfaVerifyRequestSchema,
   passkeyLoginOptionsRequestSchema,
@@ -1490,6 +1545,10 @@ function buildAuthRouter(config, cols, services) {
     const input = parseBody(loginRequestSchema, req.body);
     return services.auth.login(req, res, input);
   }));
+  router.post("/auth/login/start", rateLimit(cols, config, "login_ip", loginIpPerMin, 6e4), wrap(async (req) => {
+    const input = parseBody(loginStartRequestSchema, req.body);
+    return services.auth.loginStart(req, input);
+  }));
   router.post("/auth/mfa/send", rateLimit(cols, config, "mfa_send_ip", verifyIpPerMin, 6e4), wrap(async (req) => {
     const input = parseBody(mfaSendRequestSchema, req.body);
     return services.mfa.sendCode(input.challengeId, input.methodId);