@vivinkv28/strapi-2fa-admin-plugin 0.1.6 → 0.1.8

package/README.md

@@ -145,6 +145,34 @@ your-project/
 
 This keeps your admin customizations reproducible and easy to reapply after `npm install`.
 
+## Full Host Patch Source Included In This Package
+
+This npm package now includes the ready-to-copy host-side admin patch source directly inside the package under:
+
+```text
+host-patch/
+  apply-strapi-admin-2fa-patch.js
+  strapi-admin-2fa-patch/
+      services/
+        auth.js
+        auth.mjs
+      pages/
+        Auth/
+          components/
+            Login.js
+            Login.mjs
+```
+
+Included files:
+
+- `host-patch/apply-strapi-admin-2fa-patch.js`
+- `host-patch/strapi-admin-2fa-patch/services/auth.js`
+- `host-patch/strapi-admin-2fa-patch/services/auth.mjs`
+- `host-patch/strapi-admin-2fa-patch/pages/Auth/components/Login.js`
+- `host-patch/strapi-admin-2fa-patch/pages/Auth/components/Login.mjs`
+
+These files are the exact host-side patch source for the admin login UI, OTP screen, and patch script, bundled in the npm package itself so you do not need a separate integration document.
+
 ## Step 5: Patch The Strapi Admin Auth Service
 
 Create these files in your Strapi project:
@@ -325,6 +353,156 @@ The working implementation used in the companion project includes:
 - auto focus
 - inline error state
 
+## Exact Admin UI Pieces You Need
+
+If you want the admin OTP screen to look and behave like the working portfolio backend, these are the UI pieces that must exist in your patched `Login` component:
+
+### 1. Shared OTP constants and helpers
+
+Use:
+
+```js
+const OTP_LENGTH = 6;
+const sanitizeOtp = (value = '') => value.replace(/\D/g, '').slice(0, OTP_LENGTH);
+const createOtpDigits = (value = '') =>
+  Array.from({ length: OTP_LENGTH }, (_, index) => value[index] ?? '');
+```
+
+Why this matters:
+
+- forces numeric-only OTP input
+- keeps the code fixed to 6 digits
+- makes the 6-box UI easy to control
+
+### 2. Two screen states inside one login component
+
+Your login screen should switch between:
+
+- credentials screen
+- OTP verification screen
+
+The state shape used in the working backend is:
+
+```js
+const [apiError, setApiError] = React.useState();
+const [otpStep, setOtpStep] = React.useState(null);
+```
+
+`otpStep` stores:
+
+- `challengeId`
+- `expiresAt`
+- `maskedEmail`
+- `rememberMe`
+
+When `otpStep` is `null`, show email/password fields.
+
+When `otpStep` exists, show the OTP UI.
+
+### 3. Patched auth hooks
+
+Your patched auth service must export:
+
+```js
+const {
+  useAdminLoginWithOtpMutation,
+  useVerifyAdminLoginOtpMutation,
+  useResendAdminLoginOtpMutation,
+} = authService;
+```
+
+Then the patched login screen uses:
+
+```js
+const [adminLoginWithOtp, { isLoading: isLoggingIn }] = useAdminLoginWithOtpMutation();
+const [verifyAdminLoginOtp, { isLoading: isVerifyingOtp }] =
+  useVerifyAdminLoginOtpMutation();
+const [resendAdminLoginOtp, { isLoading: isResendingOtp }] =
+  useResendAdminLoginOtpMutation();
+```
+
+### 4. Credentials form step
+
+In the first step, keep the normal Strapi fields:
+
+- `email`
+- `password`
+- `rememberMe`
+
+On submit:
+
+1. call the OTP login endpoint
+2. do not create a Strapi session yet
+3. store the returned `challengeId`, `expiresAt`, and `maskedEmail`
+4. switch to the OTP step
+
+### 5. OTP visual layout
+
+The working backend UI uses:
+
+- a heading such as `Enter your OTP code`
+- a subtitle showing the masked email
+- an expiry message
+- a centered 6-digit input row
+- a primary `Verify OTP` button
+- a secondary `Back` button
+- a tertiary `Resend OTP` button
+- an inline error message area
+
+### 6. OTP input box behavior
+
+The working UI is not a single text input. It is a 6-box OTP component with:
+
+- one visible input per digit
+- automatic focus movement
+- paste support for full OTP values
+- backspace support to move backward
+- left/right arrow key navigation
+- red error styling when validation fails
+
+That behavior lives inside a dedicated `OtpField` component inside the patched `Login.js` / `Login.mjs` files.
+
+### 7. Verify flow
+
+On OTP submit:
+
+1. call the verify endpoint with `challengeId` and `code`
+2. if it succeeds, dispatch the normal Strapi admin login action
+3. navigate to `/` or the `redirectTo` query target
+
+### 8. Resend flow
+
+On resend:
+
+1. call the resend endpoint with `challengeId`
+2. keep the user on the OTP screen
+3. update `expiresAt`
+4. update `maskedEmail` if needed
+5. show a success notification
+
+### 9. Back button behavior
+
+The working backend keeps a `Back` button on the OTP screen that simply resets:
+
+```js
+setOtpStep(null);
+```
+
+That sends the admin back to the email/password screen without refreshing the page.
+
+### 10. Why both `.js` and `.mjs` files are needed
+
+Strapi ships both CommonJS and ESM admin build files inside `node_modules/@strapi/admin/...`.
+
+To keep the admin patch stable, the same logic should be copied into both:
+
+- `Login.js`
+- `Login.mjs`
+- `auth.js`
+- `auth.mjs`
+
+If you patch only one side, the admin build can drift or break depending on how Strapi resolves the files.
+
 ## Step 7: Add A Patch Apply Script
 
 Create:
@@ -455,66 +633,20 @@ After setup, test these cases:
 5. expired OTP restarts the flow properly
 6. wrong email/password still fails safely
 
-## Code-Level Overview
-
-Main plugin files:
-
-```text
-admin/src/index.js
-server/src/index.js
-server/src/routes/index.js
-server/src/controllers/auth.js
-server/src/services/auth.js
-server/src/utils/strapi-session-auth.js
-```
-
-Responsibilities:
-
-- `admin/src/index.js`
-  Minimal admin plugin stub required by the Strapi Plugin SDK.
-
-- `server/src/routes/index.js`
-  Declares `/login`, `/verify`, and `/resend`.
-
-- `server/src/controllers/auth.js`
-  Extracts request data, resolves client IP, sets refresh cookies after verification.
-
-- `server/src/services/auth.js`
-  Core OTP engine: credentials, challenge lifecycle, rate limits, email sending, and session creation.
-
-- `server/src/utils/strapi-session-auth.js`
-  Resolves Strapi's internal admin session helper at runtime.
-
-## Deeper Docs
-
-If you want more detail from the repository:
-
-- `docs/INTEGRATION.md`
-- `docs/ARCHITECTURE.md`
-- `admin-screen.md`
-
-## Development
-
-```bash
-npm install
-npm run build
-```
-
-Useful commands:
-
-- `npm run build`
-- `npm run watch`
-- `npm run watch:link`
-- `npm run verify`
+## Admin UI Documentation Summary
 
-## Publishing Checklist
+If you want your project README or integration guide to document the admin UI clearly, include these sections in order:
 
-1. run `npm install`
-2. run `npm run build`
-3. run `npm run verify`
-4. test in a real Strapi app
-5. bump the version
-6. run `npm publish --access public`
+1. exact patch folder structure
+2. exact file names
+3. purpose of each file
+4. auth service mutations to add
+5. login component state you need
+6. OTP UI behavior details
+7. patch apply script behavior
+8. package.json hooks
+9. request/response examples
+10. testing checklist
 
 ## Production Notes
 

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."
+);