@cairs-npm/express-auth-2fa 0.1.4 → 0.1.6

package/README.md

@@ -73,11 +73,20 @@ tokens and trusted-device tokens are stored as SHA-256 hashes only.
 - Per-IP and per-user rate limits backed by MongoDB (stateless across instances).
 - One error shape: `{ error, message, attemptsLeft?, retryAt? }`.
 
+## Compatibility
+
+- Node 20 and 24 (`>=20`; the mongodb 7 driver itself needs Node `>=20.19`).
+- `mongodb` driver 6 or 7 (peer `^6.0.0 || ^7.0.0`), or a mongoose 9 connection: pass
+  `connection.db` (and `connection.getClient()` as `client` for transactions). Ids are built with
+  the ObjectId class of the driver that owns `db`, so the app may run a different mongodb major
+  than the one this package resolves.
+
 ## Development
 
 ```sh
 npm install
 npm test          # vitest + mongodb-memory-server (replica set)
+npm run test:mongoose   # the same suite on a mongoose 9 connection (driver 7)
 npm run build     # tsup → ESM + CJS + d.ts
 npm run typecheck && npm run lint
 ```

package/dist/index.cjs

@@ -197,16 +197,16 @@ var configSchema = import_zod.z.object({
   ]).default(true),
   /** 2-Step Verification state for users who have not chosen one yet. */
   twoStepDefault: import_zod.z.boolean().default(false),
-  limits: limitSchema.default({}),
+  limits: limitSchema.prefault({}),
   /**
    * Set false to turn off every RATE_LIMITED check: the per-IP limits on login / code
    * verify / send / step-up and the code-send cooldown and caps. Account lockouts after
    * failed passwords or codes (LOCKED) still apply.
    */
   rateLimits: import_zod.z.boolean().default(true),
-  argon2: argon2Schema.default({}),
-  cookies: cookieSchema.default({}),
-  ttl: ttlSchema.default({}),
+  argon2: argon2Schema.prefault({}),
+  cookies: cookieSchema.prefault({}),
+  ttl: ttlSchema.prefault({}),
   /** Serve GET /auth/openapi.json (A.7 docs). */
   exposeDocs: import_zod.z.boolean().default(false)
 });
@@ -474,8 +474,28 @@ function clearCookie(res, config, name) {
   });
 }
 
-// src/services/method.service.ts
+// src/data/objectId.ts
 var import_mongodb = require("mongodb");
+var classes = /* @__PURE__ */ new WeakMap();
+function objectIdClass(db) {
+  let cls = classes.get(db);
+  if (!cls) {
+    cls = import_mongodb.ObjectId;
+    try {
+      const factory = db.s?.pkFactory;
+      const ctor = factory?.createPk?.()?.constructor;
+      if (typeof ctor === "function" && typeof ctor.isValid === "function") {
+        cls = ctor;
+      }
+    } catch {
+    }
+    classes.set(db, cls);
+  }
+  return cls;
+}
+var toObjectId = (db, id) => new (objectIdClass(db))(id);
+
+// src/services/method.service.ts
 var import_libphonenumber_js = require("libphonenumber-js");
 
 // src/crypto/encrypt.ts
@@ -622,6 +642,51 @@ async function deliverCode(config, encKey, method, code) {
   throw apiError(400, "VALIDATION_ERROR", "This method does not send codes.");
 }
 
+// src/middleware/rateLimit.ts
+function rateLimit(cols, config, bucket, max, windowMs) {
+  return async (req, _res, next) => {
+    if (!config.rateLimits) {
+      next();
+      return;
+    }
+    const now = config.clock().getTime();
+    const slot = Math.floor(now / windowMs);
+    const key = `${bucket}:${req.ip ?? "unknown"}:${slot}`;
+    const expiresAt = new Date((slot + 1) * windowMs + 6e4);
+    try {
+      const doc = await cols.rateLimits.findOneAndUpdate(
+        { _id: key },
+        { $inc: { count: 1 }, $setOnInsert: { expiresAt } },
+        { upsert: true, returnDocument: "after" }
+      );
+      const count = doc?.count ?? 1;
+      if (count > max) {
+        next(
+          apiError(429, "RATE_LIMITED", "Too many requests. Try again later.", {
+            retryAt: new Date((slot + 1) * windowMs)
+          })
+        );
+        return;
+      }
+      next();
+    } catch {
+      next();
+    }
+  };
+}
+async function consumeUserQuota(cols, config, bucket, userId, max, windowMs) {
+  const now = config.clock().getTime();
+  const slot = Math.floor(now / windowMs);
+  const key = `${bucket}:u:${userId}:${slot}`;
+  const retryAt = new Date((slot + 1) * windowMs);
+  const doc = await cols.rateLimits.findOneAndUpdate(
+    { _id: key },
+    { $inc: { count: 1 }, $setOnInsert: { expiresAt: new Date((slot + 1) * windowMs + 6e4) } },
+    { upsert: true, returnDocument: "after" }
+  );
+  return { allowed: (doc?.count ?? 1) <= max, retryAt };
+}
+
 // src/services/method.service.ts
 function toApiMethod(doc) {
   return {
@@ -651,7 +716,7 @@ var MethodService = class {
   encKey;
   objectId(id) {
     try {
-      return new import_mongodb.ObjectId(id);
+      return toObjectId(this.config.db, id);
     } catch {
       throw apiError(400, "VALIDATION_ERROR", "Invalid id.");
     }
@@ -738,6 +803,8 @@ var MethodService = class {
       phoneE164Enc: encryptString(e164, this.encKey, this.config.keyId),
       phoneLast4: last4,
       pendingCodeHash: sha256Hex(code),
+      pendingCodeSentAt: now,
+      pendingSendCount: 1,
       pendingExpiresAt,
       createdAt: now,
       lastUsedAt: null
@@ -747,6 +814,44 @@ var MethodService = class {
     await this.audit.record(userId, "method_add_started", { meta: { type: "SMS" } });
     return { pendingMethodId: insertedId.toString() };
   }
+  /**
+   * BR-6 for a phone being added: send a new code for a pending SMS method, with the same cooldown
+   * and caps as a sign-in code. The new code replaces the old one and the pending time restarts.
+   */
+  async resendCode(userId, methodId) {
+    const method = await this.cols.methods.findOne({ _id: this.objectId(methodId), userId, type: "SMS", status: "pending" });
+    if (!method) throw apiError(404, "VALIDATION_ERROR", "Unknown method.");
+    const now = this.config.clock();
+    const limits = this.config.limits;
+    const limited = this.config.rateLimits;
+    const sentAt = method.pendingCodeSentAt ?? method.createdAt;
+    if (limited && sentAt && now.getTime() - sentAt.getTime() < limits.smsResendSec * 1e3) {
+      throw apiError(429, "RATE_LIMITED", "Please wait before requesting another code.", {
+        retryAt: new Date(sentAt.getTime() + limits.smsResendSec * 1e3)
+      });
+    }
+    if (limited && (method.pendingSendCount ?? 1) >= limits.smsMaxPerChallenge) {
+      throw apiError(429, "RATE_LIMITED", "Too many codes sent for this number.", { retryAt: method.pendingExpiresAt });
+    }
+    const quota = limited ? await consumeUserQuota(this.cols, this.config, "sms_send", userId, limits.smsMaxPerUserHour, 36e5) : { allowed: true, retryAt: void 0 };
+    if (!quota.allowed) {
+      throw apiError(429, "RATE_LIMITED", "Too many codes sent. Try again later.", { retryAt: quota.retryAt });
+    }
+    const code = randomSmsCode();
+    await this.cols.methods.updateOne(
+      { _id: method._id },
+      {
+        $set: {
+          pendingCodeHash: sha256Hex(code),
+          pendingCodeSentAt: now,
+          pendingExpiresAt: new Date(now.getTime() + this.config.ttl.pendingMethodMin * 6e4)
+        },
+        $inc: { pendingSendCount: 1 }
+      }
+    );
+    await deliverCode(this.config, this.encKey, method, code);
+    return { resendAfterSec: limited ? limits.smsResendSec : 0 };
+  }
   /** BR-17 — confirm a pending method; first active method becomes default. */
   async confirmMethod(userId, methodId, code) {
     const method = await this.cols.methods.findOne({ _id: this.objectId(methodId), userId, status: "pending" });
@@ -769,7 +874,7 @@ var MethodService = class {
       { _id: method._id },
       {
         $set: { status: "active", isDefault: activeCount === 0, lastUsedAt: now },
-        $unset: { pendingCodeHash: "", pendingExpiresAt: "" }
+        $unset: { pendingCodeHash: "", pendingExpiresAt: "", pendingCodeSentAt: "", pendingSendCount: "" }
       }
     );
     await this.audit.record(userId, "method_added", { meta: { type: method.type } });
@@ -1068,55 +1173,7 @@ var AuthService = class {
 };
 
 // src/services/mfa.service.ts
-var import_mongodb2 = require("mongodb");
 init_hash();
-
-// src/middleware/rateLimit.ts
-function rateLimit(cols, config, bucket, max, windowMs) {
-  return async (req, _res, next) => {
-    if (!config.rateLimits) {
-      next();
-      return;
-    }
-    const now = config.clock().getTime();
-    const slot = Math.floor(now / windowMs);
-    const key = `${bucket}:${req.ip ?? "unknown"}:${slot}`;
-    const expiresAt = new Date((slot + 1) * windowMs + 6e4);
-    try {
-      const doc = await cols.rateLimits.findOneAndUpdate(
-        { _id: key },
-        { $inc: { count: 1 }, $setOnInsert: { expiresAt } },
-        { upsert: true, returnDocument: "after" }
-      );
-      const count = doc?.count ?? 1;
-      if (count > max) {
-        next(
-          apiError(429, "RATE_LIMITED", "Too many requests. Try again later.", {
-            retryAt: new Date((slot + 1) * windowMs)
-          })
-        );
-        return;
-      }
-      next();
-    } catch {
-      next();
-    }
-  };
-}
-async function consumeUserQuota(cols, config, bucket, userId, max, windowMs) {
-  const now = config.clock().getTime();
-  const slot = Math.floor(now / windowMs);
-  const key = `${bucket}:u:${userId}:${slot}`;
-  const retryAt = new Date((slot + 1) * windowMs);
-  const doc = await cols.rateLimits.findOneAndUpdate(
-    { _id: key },
-    { $inc: { count: 1 }, $setOnInsert: { expiresAt: new Date((slot + 1) * windowMs + 6e4) } },
-    { upsert: true, returnDocument: "after" }
-  );
-  return { allowed: (doc?.count ?? 1) <= max, retryAt };
-}
-
-// src/services/mfa.service.ts
 var MfaService = class {
   constructor(config, cols, tokens, audit, auth) {
     this.config = config;
@@ -1274,7 +1331,7 @@ var MfaService = class {
   }
   objectId(id) {
     try {
-      return new import_mongodb2.ObjectId(id);
+      return toObjectId(this.config.db, id);
     } catch {
       throw apiError(400, "VALIDATION_ERROR", "Invalid id.");
     }
@@ -1313,7 +1370,9 @@ var PasskeyService = class {
     return ch;
   }
   /** Step 1 of adding a passkey: WebAuthn creation options for the signed-in user. */
-  async registrationOptions(userId) {
+  // authenticator: suggest this device, a phone (QR code) or a security key. Passkeys already on
+  // the account are excluded, so a second passkey needs another authenticator.
+  async registrationOptions(userId, authenticator2) {
     const rp = this.rp();
     const now = this.config.clock();
     if (await this.cols.methods.countDocuments({ userId }) >= this.config.limits.maxMethods) {
@@ -1329,7 +1388,8 @@ var PasskeyService = class {
       userID: new TextEncoder().encode(userId),
       attestationType: "none",
       excludeCredentials: (await this.activePasskeys(userId)).map((m) => this.descriptor(m)),
-      authenticatorSelection: { residentKey: "preferred", userVerification: "preferred" }
+      authenticatorSelection: { residentKey: "preferred", userVerification: "preferred" },
+      ...authenticator2 ? { preferredAuthenticatorType: authenticator2 } : {}
     });
     await this.cols.challenges.deleteMany({ userId, purpose: "enroll" });
     await this.cols.challenges.insertOne({
@@ -1697,6 +1757,7 @@ function buildOpenApiDoc() {
       "/account/security/two-step": { put: { summary: "Enable/disable 2-Step Verification" } },
       "/account/security/methods": { post: { summary: "Add a pending TOTP or SMS method" } },
       "/account/security/methods/{id}/confirm": { post: { summary: "Confirm a pending method with a code" } },
+      "/account/security/methods/{id}/resend": { post: { summary: "Send a new code for a phone being added" } },
       "/account/security/methods/{id}": {
         patch: { summary: "Rename or set-default a method" },
         delete: { summary: "Remove a method" }
@@ -1724,7 +1785,8 @@ function buildAccountRouter(_config, _cols, services) {
     return services.methods.addMethod(req.auth.sub, input);
   }));
   router.post("/account/security/passkeys/options", auth, wrap2(async (req) => {
-    return services.passkeys.registrationOptions(req.auth.sub);
+    const input = parseBody(import_auth_2fa_contract2.passkeyRegisterOptionsRequestSchema, req.body ?? {});
+    return services.passkeys.registrationOptions(req.auth.sub, input.authenticator);
   }));
   router.post("/account/security/passkeys", auth, wrap2(async (req) => {
     const input = parseBody(import_auth_2fa_contract2.passkeyRegisterRequestSchema, req.body);
@@ -1734,6 +1796,9 @@ function buildAccountRouter(_config, _cols, services) {
     const input = parseBody(import_auth_2fa_contract2.confirmMethodRequestSchema, req.body);
     return services.methods.confirmMethod(req.auth.sub, req.params.id, input.code);
   }));
+  router.post("/account/security/methods/:id/resend", auth, wrap2(async (req) => {
+    return services.methods.resendCode(req.auth.sub, req.params.id);
+  }));
   router.patch("/account/security/methods/:id", auth, wrap2(async (req) => {
     const input = parseBody(import_auth_2fa_contract2.patchMethodRequestSchema, req.body);
     return services.methods.patchMethod(req.auth.sub, req.auth.sid, req.params.id, input);