@vsaas/loopback 12.1.1 → 12.2.1

package/docs/two-factor-authenticator-loss-runbook.md

@@ -0,0 +1,117 @@
+# Lost authenticator recovery runbook
+
+This runbook covers a user who cannot produce either a valid TOTP code or an
+unused recovery code. It is intentionally an application-owned support
+workflow: LoopBack cannot decide how an organization proves identity or who may
+approve account recovery.
+
+Password reset does not disable two-factor authentication. This prevents an
+attacker who compromises email or a password-reset channel from silently
+removing the second factor.
+
+Do not enable 2FA in production until the application has implemented and
+tested the workflow below.
+
+## Normal recovery comes first
+
+Use the ordinary user-facing operations whenever possible:
+
+1. If the user still has a recovery code, use it to sign in.
+2. Regenerate recovery codes or disable and re-enroll 2FA using the documented
+   management endpoint.
+3. Treat support recovery as the last path, not as a more convenient login.
+
+Support must never ask the user to send a TOTP secret, current TOTP code,
+recovery code, password, access token, or encrypted database value.
+
+## Decisions the application must make
+
+Before implementation, document:
+
+- which roles may open, approve, and execute a recovery;
+- the out-of-band evidence required to prove account ownership;
+- whether two different operators must approve the action;
+- the mandatory delay or notification window for high-value accounts;
+- accounts that cannot use support recovery, such as break-glass
+  administrators;
+- the audit retention period and alerting destination;
+- the session policy after recovery. Revoking all sessions is the recommended
+  default.
+
+Identity proof must not rely only on the same email channel used for password
+reset. Prefer previously verified organizational records, a known support
+contract, an in-person process, or another independent channel appropriate to
+the application's risk.
+
+## Required application operation
+
+Implement a programmatic administrative operation that is not remotely exposed
+by LoopBack by default. The operation receives the concrete User model,
+principal ID, support case ID, executing operator, approving operator, and the
+already-completed identity-proof result.
+
+The application authorization layer must reject the operation before any data
+change unless all required approvals are present. Do not accept a client body
+boolean such as `identityVerified: true` as proof.
+
+After authorization, perform this sequence:
+
+1. Load the user and the enabled `TwoFactorCredential` using both
+   `principalType` and canonical string `principalId`.
+2. Record a durable recovery operation with a unique case ID and `pending`
+   state. A repeated case ID must return the original result.
+3. Revoke every access token, reset token, remembered device, and application
+   session for that principal. Confirm revocation instead of assuming a delete
+   succeeded.
+4. Disable the credential with compare-and-set on its `id`, `status`, and
+   `version`. Increment `version`, clear the encrypted secret and active
+   recovery-set fields, and set `disabledAt`.
+5. Expire pending or verifying challenges for the same credential and remove
+   its recovery codes.
+6. Mark the recovery operation completed only after the credential transition
+   and session revocation are confirmed.
+7. Emit a security audit event and notify the account through every previously
+   verified channel. The notification must explain how to report an
+   unauthorized recovery.
+8. Require password authentication and a completely new 2FA enrollment on the
+   next login. Never restore or disclose the old TOTP secret.
+
+Use a datasource transaction when the connector can include the credential,
+sessions, challenges, recovery codes, and recovery-operation record in one
+transaction. Otherwise use durable states and idempotent compare-and-set
+transitions. A partial result must fail closed.
+
+Do not implement recovery by directly changing `status` in a database console.
+That skips session revocation, challenge invalidation, versioning, recovery-code
+cleanup, and audit requirements.
+
+## Failure handling
+
+| Failure                                                           | Required result                                                                                                                       |
+| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| Identity proof or approval fails                                  | Make no security-state change. Record only the rejected case metadata allowed by policy.                                              |
+| Session revocation is unavailable or ambiguous                    | Keep 2FA enabled, mark the case for reconciliation, and return no success.                                                            |
+| Credential CAS loses to another transition                        | Reload state. Complete only if the same recovery case already produced the required terminal state; otherwise stop for review.        |
+| Challenge or recovery-code cleanup fails after credential disable | The old factor remains unusable because credential status/version changed. Emit an operational alert and retry cleanup.               |
+| Audit persistence fails                                           | Do not execute recovery. Audit is part of the authorization boundary.                                                                 |
+| User reports an unauthorized recovery                             | Lock the account according to incident policy, revoke all sessions again, preserve evidence, and start the security incident process. |
+
+## Verification before rollout
+
+Test at least:
+
+- password reset leaves an enabled credential enabled;
+- support cannot recover an account without the required approvals;
+- operator and approver cannot be the same person when dual control is enabled;
+- recovery revokes all existing tokens and sessions;
+- an outstanding challenge fails after recovery;
+- old TOTP counters and recovery codes cannot be used;
+- retrying the same case is idempotent;
+- concurrent disable, enrollment, and support recovery cannot overwrite each
+  other;
+- failures in every write leave the account fail-closed and generate an alert;
+- two concrete User models cannot recover each other's principals;
+- logs and audit records contain no authentication secrets.
+
+Keep an application-specific copy of this runbook with real role names,
+escalation contacts, identity-proof rules, dashboards, and incident links.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vsaas/loopback",
-  "version": "12.1.1",
+  "version": "12.2.1",
   "description": "Fork of LoopBack 3 framework for building APIs and microservices in Node.js",
   "keywords": [
     "StrongLoop",
@@ -36,21 +36,56 @@
   "files": [
     "dist",
     "common/models",
+    "docs",
     "templates",
     "favicon.ico",
     "README.md",
     "LICENSE"
   ],
   "main": "dist/index.cjs",
+  "types": "dist/index.d.cts",
   "exports": {
-    ".": "./dist/index.cjs",
+    ".": {
+      "types": "./dist/index.d.cts",
+      "require": "./dist/index.cjs",
+      "default": "./dist/index.cjs"
+    },
+    "./rate-limit": {
+      "types": "./dist/lib/rate-limit/types.d.cts",
+      "require": "./dist/lib/rate-limit/types.cjs",
+      "default": "./dist/lib/rate-limit/types.cjs"
+    },
     "./common/models/*.json": "./common/models/*.json",
-    "./common/models/*.js": "./dist/common/models/*.cjs",
-    "./common/models/*": "./dist/common/models/*.cjs",
-    "./lib/*.js": "./dist/lib/*.cjs",
-    "./lib/*": "./dist/lib/*.cjs",
-    "./server/middleware/*.js": "./dist/server/middleware/*.cjs",
-    "./server/middleware/*": "./dist/server/middleware/*.cjs",
+    "./common/models/*.js": {
+      "types": "./dist/common/models/*.d.cts",
+      "require": "./dist/common/models/*.cjs",
+      "default": "./dist/common/models/*.cjs"
+    },
+    "./common/models/*": {
+      "types": "./dist/common/models/*.d.cts",
+      "require": "./dist/common/models/*.cjs",
+      "default": "./dist/common/models/*.cjs"
+    },
+    "./lib/*.js": {
+      "types": "./dist/lib/*.d.cts",
+      "require": "./dist/lib/*.cjs",
+      "default": "./dist/lib/*.cjs"
+    },
+    "./lib/*": {
+      "types": "./dist/lib/*.d.cts",
+      "require": "./dist/lib/*.cjs",
+      "default": "./dist/lib/*.cjs"
+    },
+    "./server/middleware/*.js": {
+      "types": "./dist/server/middleware/*.d.cts",
+      "require": "./dist/server/middleware/*.cjs",
+      "default": "./dist/server/middleware/*.cjs"
+    },
+    "./server/middleware/*": {
+      "types": "./dist/server/middleware/*.d.cts",
+      "require": "./dist/server/middleware/*.cjs",
+      "default": "./dist/server/middleware/*.cjs"
+    },
     "./package.json": "./package.json"
   },
   "publishConfig": {
@@ -58,7 +93,7 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@aws-sdk/client-sesv2": "3.1034.0",
+    "@aws-sdk/client-sesv2": "^3.1115.0",
     "bcryptjs": "^2.4.3",
     "debug": "^2.6.9",
     "depd": "^1.1.2",
@@ -66,11 +101,12 @@
     "express": "4.22.2",
     "isemail": "^3.2.0",
     "loopback-filters": "^1.1.1",
-    "nodemailer": "^9.0.1",
+    "nodemailer": "^9.0.5",
+    "otplib": "13.4.1",
     "serve-favicon": "^2.5.1",
-    "@vsaas/loopback-datasource-juggler": "^12.1.1",
-    "@vsaas/loopback-connector-remote": "^12.0.0",
-    "@vsaas/remoting": "^12.0.1"
+    "@vsaas/loopback-connector-remote": "^12.0.1",
+    "@vsaas/remoting": "^13.0.0",
+    "@vsaas/loopback-datasource-juggler": "^12.1.2"
   },
   "devDependencies": {
     "@types/node": "25.5.0",
@@ -79,17 +115,17 @@
     "dirty-chai": "^2.0.1",
     "express-session": "^1.19.0",
     "loopback-context": "^1.0.0",
-    "oxfmt": "0.42.0",
-    "oxlint": "1.57.0",
-    "sinon": "22.0.0",
+    "oxfmt": "0.64.0",
+    "oxlint": "1.79.0",
+    "sinon": "22.1.0",
     "sinon-chai": "^3.7.0",
     "strong-task-emitter": "^0.0.8",
     "supertest": "7.2.2",
-    "tsdown": "0.21.7",
+    "tsdown": "0.22.14",
     "typescript": "6.0.2",
-    "vitest": "4.1.4",
-    "@vsaas/loopback-boot": "^12.0.1",
-    "@vsaas/error-handler": "^12.0.0"
+    "vitest": "4.1.11",
+    "@vsaas/error-handler": "^12.0.0",
+    "@vsaas/loopback-boot": "^12.0.2"
   },
   "engines": {
     "node": ">=24"