@vivinkv28/strapi-2fa-admin-plugin 0.1.7 → 0.1.9

package/README.md

@@ -1,32 +1,25 @@
 # @vivinkv28/strapi-2fa-admin-plugin
 
-`@vivinkv28/strapi-2fa-admin-plugin` is a Strapi 5 plugin that adds the backend side of an OTP-based admin login flow.
+Strapi 5 plugin for OTP-based admin authentication.
 
-It gives your Strapi project:
+This package adds the backend flow for:
 
-- admin credential validation before OTP
+- admin email/password validation
 - OTP challenge creation
 - OTP resend and verification
 - rate limiting for login, verify, and resend
-- OTP delivery through Strapi's email plugin
 - final Strapi admin session creation only after OTP verification
 
-## What This Package Is
+## Important
 
-This package is a **backend/admin-auth plugin**.
+This package does not automatically replace the default Strapi admin login UI.
 
-It does **not** automatically replace the default Strapi admin login UI.
+You need two parts:
 
-To use it in a real project, you need two parts:
+1. this plugin for the backend OTP logic
+2. a host-project patch for the Strapi admin login UI
 
-1. this plugin for the backend OTP/auth logic
-2. an admin login screen integration in your Strapi project that calls the plugin endpoints
-
-That means this package is ideal if you want:
-
-- a reusable backend OTP engine
-- control over how the admin login UI looks
-- a project-level patch/customization for the Strapi admin login page
+The good part is that this npm package now includes the host patch source directly, so you can copy it into your Strapi project.
 
 ## Endpoints
 
@@ -48,9 +41,9 @@ After installation, the plugin exposes:
 npm install @vivinkv28/strapi-2fa-admin-plugin
 ```
 
-## Step 1: Enable The Plugin
+## Enable The Plugin
 
-In your Strapi project, update `config/plugins.ts`:
+Update `config/plugins.ts`:
 
 ```ts
 import type { Core } from "@strapi/strapi";
@@ -81,19 +74,17 @@ const config = ({ env }: Core.Config.Shared.ConfigParams): Core.Config.Plugin =>
 export default config;
 ```
 
-## Step 2: Configure Email
+## Email Provider
 
 This plugin sends OTP emails through Strapi's email plugin.
 
-Your project must have a working email provider configuration in `config/plugins.ts`.
-
-If email is not configured, login will fail when OTP delivery is attempted.
+If your email provider is not configured correctly, login will fail when OTP delivery is attempted.
 
-## Step 3: Make Sure Server/Proxy Settings Are Correct
+## Recommended Server Settings
 
-If your Strapi app runs behind a proxy, configure `config/server.ts` correctly so admin cookies work as expected.
+If your Strapi app runs behind a proxy, make sure `config/server.ts` is configured correctly so admin cookies work as expected.
 
-Typical example:
+Example:
 
 ```ts
 import type { Core } from "@strapi/strapi";
@@ -111,238 +102,59 @@ const config = ({ env }: Core.Config.Shared.ConfigParams): Core.Config.Server =>
 export default config;
 ```
 
-## Step 4: Add Admin Login UI Integration
-
-This package does not inject the login UI automatically.
-
-Your Strapi project must customize the admin login flow so it works like this:
+## Host Patch Files Included In The Package
 
-1. admin enters email and password
-2. frontend calls `POST /api/admin-2fa/login`
-3. frontend shows OTP screen
-4. admin enters OTP
-5. frontend calls `POST /api/admin-2fa/verify`
-6. optional resend button calls `POST /api/admin-2fa/resend`
-
-## Recommended Project Structure For The Admin Patch
-
-In your Strapi project, keep your admin patch files in your own `scripts` folder:
+This package includes the admin UI patch source under:
 
 ```text
-your-project/
-  scripts/
-    strapi-admin-2fa-patch/
-      services/
-        auth.js
-        auth.mjs
-      pages/
-        Auth/
-          components/
-            Login.js
-            Login.mjs
-    apply-strapi-admin-2fa-patch.js
+host-patch/
+  apply-strapi-admin-2fa-patch.js
+  strapi-admin-2fa-patch/
+    services/
+      auth.js
+      auth.mjs
+    pages/
+      Auth/
+        components/
+          Login.js
+          Login.mjs
 ```
 
-This keeps your admin customizations reproducible and easy to reapply after `npm install`.
-
-## Step 5: Patch The Strapi Admin Auth Service
-
-Create these files in your Strapi project:
+These are the files you can copy into your Strapi project to get the same admin OTP UI pattern.
 
-- `scripts/strapi-admin-2fa-patch/services/auth.js`
-- `scripts/strapi-admin-2fa-patch/services/auth.mjs`
+## What The UI Patch Does
 
-Start from the corresponding Strapi admin auth service file and add the OTP mutations below.
-
-### Add these mutations
-
-```js
-adminLoginWithOtp: builder.mutation({
-  query: (body) => ({
-    method: 'POST',
-    url: '/api/admin-2fa/login',
-    data: body,
-  }),
-  transformResponse(res) {
-    return res.data;
-  },
-}),
-
-verifyAdminLoginOtp: builder.mutation({
-  query: (body) => ({
-    method: 'POST',
-    url: '/api/admin-2fa/verify',
-    data: body,
-  }),
-  transformResponse(res) {
-    return res.data;
-  },
-  invalidatesTags: ['Me'],
-}),
-
-resendAdminLoginOtp: builder.mutation({
-  query: (body) => ({
-    method: 'POST',
-    url: '/api/admin-2fa/resend',
-    data: body,
-  }),
-  transformResponse(res) {
-    return res.data;
-  },
-}),
-```
-
-### Export these hooks
-
-```js
-const {
-  useAdminLoginWithOtpMutation,
-  useVerifyAdminLoginOtpMutation,
-  useResendAdminLoginOtpMutation,
-} = authService;
-```
+The bundled host patch changes the Strapi admin login flow to:
 
-## Step 6: Patch The Strapi Login Screen
+1. enter admin email and password
+2. call `POST /api/admin-2fa/login`
+3. show an OTP screen
+4. enter the OTP code
+5. call `POST /api/admin-2fa/verify`
+6. optionally resend OTP with `POST /api/admin-2fa/resend`
 
-Create these files in your Strapi project:
+The included login patch UI contains:
 
-- `scripts/strapi-admin-2fa-patch/pages/Auth/components/Login.js`
-- `scripts/strapi-admin-2fa-patch/pages/Auth/components/Login.mjs`
-
-This component must replace the normal one-step login with a two-step state:
-
-- credentials step
+- email and password step
 - OTP step
-
-### Minimum state you need
-
-```js
-const [otpStep, setOtpStep] = React.useState(null);
-const [apiError, setApiError] = React.useState();
-
-const [adminLoginWithOtp, { isLoading: isLoggingIn }] = useAdminLoginWithOtpMutation();
-const [verifyAdminLoginOtp, { isLoading: isVerifyingOtp }] = useVerifyAdminLoginOtpMutation();
-const [resendAdminLoginOtp, { isLoading: isResendingOtp }] = useResendAdminLoginOtpMutation();
-```
-
-### Credentials submit handler
-
-```js
-const handleLogin = async (body) => {
-  setApiError(undefined);
-
-  const res = await adminLoginWithOtp({
-    ...body,
-    deviceId: crypto.randomUUID(),
-  });
-
-  if ('error' in res) {
-    setApiError(res.error.message ?? 'Something went wrong');
-    return;
-  }
-
-  setOtpStep({
-    challengeId: res.data.challengeId,
-    expiresAt: res.data.expiresAt,
-    maskedEmail: res.data.maskedEmail,
-    rememberMe: body.rememberMe,
-  });
-};
-```
-
-### OTP verify handler
-
-```js
-const handleVerifyOtp = async ({ code }) => {
-  if (!otpStep) return;
-
-  setApiError(undefined);
-
-  const res = await verifyAdminLoginOtp({
-    challengeId: otpStep.challengeId,
-    code,
-  });
-
-  if ('error' in res) {
-    setApiError(res.error.message ?? 'Something went wrong');
-    return;
-  }
-
-  dispatch(
-    login({
-      token: res.data.token,
-      persist: otpStep.rememberMe,
-    })
-  );
-
-  navigate('/');
-};
-```
-
-### OTP resend handler
-
-```js
-const handleResendOtp = async () => {
-  if (!otpStep) return;
-
-  setApiError(undefined);
-
-  const res = await resendAdminLoginOtp({
-    challengeId: otpStep.challengeId,
-  });
-
-  if ('error' in res) {
-    setApiError(res.error.message ?? 'Something went wrong');
-    return;
-  }
-
-  setOtpStep((current) =>
-    current
-      ? {
-          ...current,
-          expiresAt: res.data.expiresAt,
-          maskedEmail: res.data.maskedEmail,
-        }
-      : current
-  );
-};
-```
-
-### OTP input handling
-
-At minimum:
-
-```js
-const OTP_LENGTH = 6;
-const sanitizeOtp = (value = '') => value.replace(/\D/g, '').slice(0, OTP_LENGTH);
-```
-
-The working implementation used in the companion project includes:
-
-- 6 digit boxes
+- 6-digit OTP box UI
 - paste support
-- backspace handling
-- auto focus
-- inline error state
-
-## Step 7: Add A Patch Apply Script
-
-Create:
-
-- `scripts/apply-strapi-admin-2fa-patch.js`
+- backspace and focus handling
+- resend OTP button
+- back button
+- inline error handling
 
-This script should:
+## How To Use The Included Host Patch
 
-1. copy `scripts/strapi-admin-2fa-patch/services/auth.js`
-2. copy `scripts/strapi-admin-2fa-patch/services/auth.mjs`
-3. copy `scripts/strapi-admin-2fa-patch/pages/Auth/components/Login.js`
-4. copy `scripts/strapi-admin-2fa-patch/pages/Auth/components/Login.mjs`
-5. overwrite the matching files in `node_modules/@strapi/admin/...`
-6. clear stale Strapi admin cache directories
+Copy these files from the package into your Strapi project:
 
-## Step 8: Wire The Patch Script In `package.json`
+- `host-patch/apply-strapi-admin-2fa-patch.js` -> `scripts/apply-strapi-admin-2fa-patch.js`
+- `host-patch/strapi-admin-2fa-patch/services/auth.js` -> `scripts/strapi-admin-2fa-patch/services/auth.js`
+- `host-patch/strapi-admin-2fa-patch/services/auth.mjs` -> `scripts/strapi-admin-2fa-patch/services/auth.mjs`
+- `host-patch/strapi-admin-2fa-patch/pages/Auth/components/Login.js` -> `scripts/strapi-admin-2fa-patch/pages/Auth/components/Login.js`
+- `host-patch/strapi-admin-2fa-patch/pages/Auth/components/Login.mjs` -> `scripts/strapi-admin-2fa-patch/pages/Auth/components/Login.mjs`
 
-In your Strapi project `package.json`, add:
+Then wire the patch script in your Strapi project's `package.json`:
 
 ```json
 {
@@ -355,12 +167,6 @@ In your Strapi project `package.json`, add:
 }
 ```
 
-This ensures the login patch is reapplied:
-
-- after dependency install
-- before build
-- before dev
-
 ## Request Flow
 
 ### Login
@@ -370,8 +176,6 @@ POST /api/admin-2fa/login
 Content-Type: application/json
 ```
 
-Example body:
-
 ```json
 {
   "email": "admin@example.com",
@@ -381,19 +185,6 @@ Example body:
 }
 ```
 
-Example response:
-
-```json
-{
-  "data": {
-    "challengeId": "***",
-    "expiresAt": "2026-04-05T18:30:00.000Z",
-    "maskedEmail": "admin@example.com",
-    "rememberMe": true
-  }
-}
-```
-
 ### Verify
 
 ```http
@@ -401,8 +192,6 @@ POST /api/admin-2fa/verify
 Content-Type: application/json
 ```
 
-Example body:
-
 ```json
 {
   "challengeId": "***",
@@ -417,8 +206,6 @@ POST /api/admin-2fa/resend
 Content-Type: application/json
 ```
 
-Example body:
-
 ```json
 {
   "challengeId": "***"
@@ -444,19 +231,17 @@ ADMIN_OTP_RESEND_EMAIL_LIMIT=5
 ADMIN_OTP_DEBUG_TIMINGS=false
 ```
 
-## Testing Checklist
+## Test Checklist
 
-After setup, test these cases:
+After setup, test:
 
 1. correct email/password shows OTP screen
-2. correct OTP logs into admin successfully
+2. correct OTP logs in successfully
 3. resend OTP works
 4. invalid OTP shows an error
 5. expired OTP restarts the flow properly
-6. wrong email/password still fails safely
+6. wrong email/password fails safely
 
-## Production Notes
+## Security Note
 
-- This improves admin security, but email OTP is still weaker than TOTP or WebAuthn.
-- If the admin email account is compromised, the second factor can still be bypassed.
-- For stronger future versions, consider TOTP, backup codes, trusted devices, or passkeys.
+Email OTP improves admin security, but it is still weaker than TOTP, WebAuthn, or passkeys.

package/host-patch/apply-strapi-admin-2fa-patch.js

@@ -0,0 +1,115 @@
+const fs = require("fs");
+const path = require("path");
+
+const rootDir = process.cwd();
+
+const patchFiles = [
+  {
+    source: path.join(
+      rootDir,
+      "scripts",
+      "strapi-admin-2fa-patch",
+      "pages",
+      "Auth",
+      "components",
+      "Login.js"
+    ),
+    target: path.join(
+      rootDir,
+      "node_modules",
+      "@strapi",
+      "admin",
+      "dist",
+      "admin",
+      "admin",
+      "src",
+      "pages",
+      "Auth",
+      "components",
+      "Login.js"
+    ),
+  },
+  {
+    source: path.join(
+      rootDir,
+      "scripts",
+      "strapi-admin-2fa-patch",
+      "pages",
+      "Auth",
+      "components",
+      "Login.mjs"
+    ),
+    target: path.join(
+      rootDir,
+      "node_modules",
+      "@strapi",
+      "admin",
+      "dist",
+      "admin",
+      "admin",
+      "src",
+      "pages",
+      "Auth",
+      "components",
+      "Login.mjs"
+    ),
+  },
+  {
+    source: path.join(rootDir, "scripts", "strapi-admin-2fa-patch", "services", "auth.js"),
+    target: path.join(
+      rootDir,
+      "node_modules",
+      "@strapi",
+      "admin",
+      "dist",
+      "admin",
+      "admin",
+      "src",
+      "services",
+      "auth.js"
+    ),
+  },
+  {
+    source: path.join(rootDir, "scripts", "strapi-admin-2fa-patch", "services", "auth.mjs"),
+    target: path.join(
+      rootDir,
+      "node_modules",
+      "@strapi",
+      "admin",
+      "dist",
+      "admin",
+      "admin",
+      "src",
+      "services",
+      "auth.mjs"
+    ),
+  },
+];
+
+const generatedCacheDirs = [
+  path.join(rootDir, "node_modules", ".strapi", "vite"),
+  path.join(rootDir, ".strapi", "client"),
+];
+
+const missing = patchFiles.find(
+  ({ source, target }) => !fs.existsSync(source) || !fs.existsSync(target)
+);
+
+if (missing) {
+  console.warn("[admin-2fa-patch] Skipping Strapi admin patch because a source or target file is missing.");
+  process.exit(0);
+}
+
+for (const { source, target } of patchFiles) {
+  fs.copyFileSync(source, target);
+}
+
+for (const generatedDir of generatedCacheDirs) {
+  if (fs.existsSync(generatedDir)) {
+    fs.rmSync(generatedDir, { recursive: true, force: true });
+  }
+}
+
+console.log(
+  "[admin-2fa-patch] Applied Strapi admin OTP login patch and cleared Strapi admin caches."
+);