@cairs-npm/express-auth-2fa 0.1.0 → 0.1.2

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,18 @@ 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>>]>>;
     /** 2-Step Verification state for users who have not chosen one yet. */
     twoStepDefault: z.ZodDefault<z.ZodBoolean>;
     limits: z.ZodDefault<z.ZodObject<{
@@ -309,6 +329,10 @@ declare const configSchema: z.ZodObject<{
     userAdapter: UserAdapter;
     smsProvider: SmsProvider;
     collectionPrefix: string;
+    passwordlessLogin: boolean | ((input: {
+        username: string;
+        type?: string;
+    }) => boolean | Promise<boolean>);
     twoStepDefault: boolean;
     limits: {
         loginMaxAttempts: number;
@@ -374,6 +398,10 @@ declare const configSchema: z.ZodObject<{
         rpName: string;
         origins: string[];
     } | undefined;
+    passwordlessLogin?: boolean | ((input: {
+        username: string;
+        type?: string;
+    }) => boolean | Promise<boolean>) | undefined;
     twoStepDefault?: boolean | undefined;
     limits?: {
         loginMaxAttempts?: number | undefined;
@@ -533,6 +561,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;
@@ -551,12 +590,14 @@ declare class AuthService {
         tokens: {
             accessToken: string;
             expiresInSec: number;
+            csrfToken?: string;
         };
     }>;
     trustDevice(userId: string, res: Response, label: string): Promise<void>;
     refresh(req: Request, res: Response): Promise<{
         accessToken: string;
         expiresInSec: number;
+        csrfToken?: string;
     }>;
     logout(req: Request, res: Response, sid: string): Promise<void>;
     listActiveMethods(userId: string): Promise<Method[]>;

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,18 @@ 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>>]>>;
     /** 2-Step Verification state for users who have not chosen one yet. */
     twoStepDefault: z.ZodDefault<z.ZodBoolean>;
     limits: z.ZodDefault<z.ZodObject<{
@@ -309,6 +329,10 @@ declare const configSchema: z.ZodObject<{
     userAdapter: UserAdapter;
     smsProvider: SmsProvider;
     collectionPrefix: string;
+    passwordlessLogin: boolean | ((input: {
+        username: string;
+        type?: string;
+    }) => boolean | Promise<boolean>);
     twoStepDefault: boolean;
     limits: {
         loginMaxAttempts: number;
@@ -374,6 +398,10 @@ declare const configSchema: z.ZodObject<{
         rpName: string;
         origins: string[];
     } | undefined;
+    passwordlessLogin?: boolean | ((input: {
+        username: string;
+        type?: string;
+    }) => boolean | Promise<boolean>) | undefined;
     twoStepDefault?: boolean | undefined;
     limits?: {
         loginMaxAttempts?: number | undefined;
@@ -533,6 +561,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;
@@ -551,12 +590,14 @@ declare class AuthService {
         tokens: {
             accessToken: string;
             expiresInSec: number;
+            csrfToken?: string;
         };
     }>;
     trustDevice(userId: string, res: Response, label: string): Promise<void>;
     refresh(req: Request, res: Response): Promise<{
         accessToken: string;
         expiresInSec: number;
+        csrfToken?: string;
     }>;
     logout(req: Request, res: Response, sid: string): Promise<void>;
     listActiveMethods(userId: string): Promise<Method[]>;

package/dist/index.js

@@ -88,6 +88,17 @@ 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),
   /** 2-Step Verification state for users who have not chosen one yet. */
   twoStepDefault: z.boolean().default(false),
   limits: limitSchema.default({}),
@@ -793,13 +804,42 @@ var AuthService = class {
       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 +850,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
     });
@@ -860,7 +902,8 @@ var AuthService = class {
     const bundle = await this.tokens.issueTokens(userId, amr, ctx);
     const refreshDays = opts.rememberMe ? this.config.ttl.refreshTokenDays : Math.min(this.config.ttl.refreshTokenDays, 1);
     setCookie(res, this.config, REFRESH_COOKIE, bundle.refreshToken, refreshDays * 864e5);
-    setCookie(res, this.config, CSRF_COOKIE, randomToken(), this.config.ttl.refreshTokenDays * 864e5, false);
+    const csrfToken = randomToken();
+    setCookie(res, this.config, CSRF_COOKIE, csrfToken, this.config.ttl.refreshTokenDays * 864e5, false);
     if (opts.rememberDevice) {
       await this.trustDevice(userId, res, opts.deviceLabel ?? "This device");
     }
@@ -868,7 +911,7 @@ var AuthService = class {
     return {
       status: "AUTHENTICATED",
       user: { id: userId, username: user?.username, email: user?.email },
-      tokens: { accessToken: bundle.accessToken, expiresInSec: bundle.expiresInSec }
+      tokens: { accessToken: bundle.accessToken, expiresInSec: bundle.expiresInSec, csrfToken }
     };
   }
   async trustDevice(userId, res, label) {
@@ -894,7 +937,7 @@ var AuthService = class {
     if (!raw) throw apiError(401, "INVALID_CREDENTIALS", "No refresh token.");
     const bundle = await this.tokens.rotateRefreshToken(raw, ctxOf(req));
     setCookie(res, this.config, REFRESH_COOKIE, bundle.refreshToken, this.config.ttl.refreshTokenDays * 864e5);
-    return { accessToken: bundle.accessToken, expiresInSec: bundle.expiresInSec };
+    return { accessToken: bundle.accessToken, expiresInSec: bundle.expiresInSec, csrfToken: csrfCookie };
   }
   async logout(req, res, sid) {
     await this.tokens.revokeSession(sid);
@@ -1041,7 +1084,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
     });
@@ -1293,7 +1336,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
     });
@@ -1455,6 +1498,7 @@ var AuditService = class {
 import { Router } from "express";
 import {
   loginRequestSchema,
+  loginStartRequestSchema,
   mfaSendRequestSchema,
   mfaVerifyRequestSchema,
   passkeyLoginOptionsRequestSchema,
@@ -1489,6 +1533,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);