@vivinkv28/strapi-2fa-admin-plugin 0.1.1 → 0.1.4

package/README.md

@@ -2,84 +2,50 @@
 
 `@vivinkv28/strapi-2fa-admin-plugin` is a Strapi 5 plugin that provides the backend side of an OTP-based 2FA flow for Strapi admin authentication.
 
-This package handles:
+## What This Plugin Handles
 
-- admin credential check
+- admin credential validation
 - OTP challenge generation and hashing
 - OTP resend and verification
 - rate limiting for login, verify, and resend
 - OTP delivery through Strapi's email plugin
 - final Strapi admin session creation after OTP verification
 
-This package does **not** replace the Strapi admin login UI by itself. You still need a frontend/admin integration layer that calls the plugin endpoints.
+## Important Scope
 
-## Documentation
+This package is a backend/admin-auth engine.
 
-- [Integration Guide](#integration-guide)
-- [Architecture Guide](#architecture-guide)
-- [Admin UI Integration](#admin-ui-integration)
+It does **not** replace the Strapi admin login UI by itself. Your host project still needs an admin-side integration layer that:
+
+1. collects admin email and password
+2. calls the plugin login endpoint
+3. shows an OTP input UI
+4. calls the plugin verify endpoint
+5. optionally calls the resend endpoint
 
 ## Endpoints
 
-The plugin exposes these content API routes:
+The plugin exposes these routes:
 
 - `POST /api/admin-2fa/login`
 - `POST /api/admin-2fa/verify`
 - `POST /api/admin-2fa/resend`
 
-See the detailed request and response flow in the `Integration Guide` section below.
-
 ## Requirements
 
 - Strapi 5
 - Node.js `20.x` or `22.x`
-- A configured Strapi email provider
-
-## Install In An Existing Strapi Project
-
-### Option 1: Use as a published npm package
+- a configured Strapi email provider
 
-Install the package in your Strapi app:
+## Install
 
 ```bash
 npm install @vivinkv28/strapi-2fa-admin-plugin
 ```
 
-Then enable it in your Strapi app plugin config:
+## Enable In A Strapi Project
 
-```ts
-// config/plugins.ts
-import type { Core } from "@strapi/strapi";
-
-const config = ({ env }: Core.Config.Shared.ConfigParams): Core.Config.Plugin => ({
-  "admin-2fa": {
-    enabled: true,
-    config: {
-      otpDigits: env.int("ADMIN_OTP_DIGITS", 6),
-      otpTtlSeconds: env.int("ADMIN_OTP_TTL_SECONDS", 300),
-      maxAttempts: env.int("ADMIN_OTP_MAX_ATTEMPTS", 5),
-      maxResends: env.int("ADMIN_OTP_MAX_RESENDS", 3),
-      rateLimitWindowSeconds: env.int("ADMIN_OTP_RATE_LIMIT_WINDOW_SECONDS", 900),
-      loginIpLimit: env.int("ADMIN_OTP_LOGIN_IP_LIMIT", 10),
-      loginEmailLimit: env.int("ADMIN_OTP_LOGIN_EMAIL_LIMIT", 5),
-      verifyIpLimit: env.int("ADMIN_OTP_VERIFY_IP_LIMIT", 20),
-      verifyEmailLimit: env.int("ADMIN_OTP_VERIFY_EMAIL_LIMIT", 10),
-      resendIpLimit: env.int("ADMIN_OTP_RESEND_IP_LIMIT", 10),
-      resendEmailLimit: env.int("ADMIN_OTP_RESEND_EMAIL_LIMIT", 5),
-      debugTimings: env.bool(
-        "ADMIN_OTP_DEBUG_TIMINGS",
-        env("NODE_ENV", "development") !== "production"
-      ),
-    },
-  },
-});
-
-export default config;
-```
-
-### Option 2: Use as a local external plugin
-
-If the plugin lives next to your Strapi app, point Strapi to it with `resolve`:
+Add the plugin to your Strapi app config:
 
 ```ts
 // config/plugins.ts
@@ -88,7 +54,6 @@ import type { Core } from "@strapi/strapi";
 const config = ({ env }: Core.Config.Shared.ConfigParams): Core.Config.Plugin => ({
   "admin-2fa": {
     enabled: true,
-    resolve: "../strapi-2fa-admin-plugin",
     config: {
       otpDigits: env.int("ADMIN_OTP_DIGITS", 6),
       otpTtlSeconds: env.int("ADMIN_OTP_TTL_SECONDS", 300),
@@ -112,36 +77,33 @@ const config = ({ env }: Core.Config.Shared.ConfigParams): Core.Config.Plugin =>
 export default config;
 ```
 
-## Required Host App Setup
-
-### 1. Configure an email provider
+## Admin UI Integration
 
-The plugin uses Strapi's `email` plugin to send OTP emails. Your host project must configure an email provider in `config/plugins.ts`.
+Because this package does not inject the full login UI by itself, the host project must integrate the admin flow.
 
-### 2. Add an admin login integration layer
+### Expected UI flow
 
-This plugin is backend-only. To use it for real admin login 2FA, your project must:
+#### 1. Credentials step
 
-- intercept the normal admin login flow
-- call `POST /api/admin-2fa/login`
-- show an OTP input step
-- call `POST /api/admin-2fa/verify`
-- optionally call `POST /api/admin-2fa/resend`
+- collect email and password
+- send them to `POST /api/admin-2fa/login`
+- if successful, store `challengeId` and switch to OTP mode
 
-The expected frontend flow, payloads, and response handling are documented in [docs/INTEGRATION.md](./docs/INTEGRATION.md).
-The expected frontend flow, payloads, and response handling are documented in the `Integration Guide` and `Admin UI Integration` sections below.
+#### 2. OTP step
 
-## Integration Guide
+- collect the OTP code
+- send it to `POST /api/admin-2fa/verify`
+- if successful, continue the normal authenticated admin flow
+- provide a resend action that calls `POST /api/admin-2fa/resend`
 
-This plugin is intended to be used as the backend engine for an admin OTP login flow.
+### Recommended UI behavior
 
-The normal integration flow is:
+- keep login and OTP as separate form states
+- do not treat password validation as a completed login
+- complete the login only after `/verify` succeeds
+- restart from the credentials step if the challenge expires
 
-1. collect admin email and password
-2. call `POST /api/admin-2fa/login`
-3. display an OTP entry screen
-4. call `POST /api/admin-2fa/verify`
-5. optionally call `POST /api/admin-2fa/resend`
+## Integration Guide
 
 ### Login request
 
@@ -227,102 +189,21 @@ Example payload:
 - OTP session not found
 - invalid OTP code
 - too many authentication attempts
-- resend limit exceeded
-
-## Admin UI Integration
-
-This package is backend-focused. To make it usable in a real Strapi admin login flow, the host project must provide an admin-side integration.
-
-A typical admin UI integration has two screens or states:
-
-### 1. Credentials step
-
-- collect email and password
-- send them to `/api/admin-2fa/login`
-- if successful, store `challengeId` in memory and switch the UI into OTP mode
-
-### 2. OTP step
-
-- collect the OTP code
-- submit it to `/api/admin-2fa/verify`
-- if successful, continue the normal authenticated admin flow
-- provide a resend button that calls `/api/admin-2fa/resend`
-
-### Recommended UI behavior
-
-- keep login and OTP as separate form states
-- do not create a session after password validation alone
-- only treat the login as complete after `/verify` succeeds
-- if resend or verify says the challenge expired, restart from the credentials step
-
-### Current integration approach used by the example project
-
-In the companion Strapi app used during development, the admin login UI is integrated by patching Strapi's admin login screen and auth service so they call:
+- maximum resend attempts exceeded
 
-- `/api/admin-2fa/login`
-- `/api/admin-2fa/verify`
-- `/api/admin-2fa/resend`
+## Host Project Requirements
 
-This plugin itself does not inject that UI automatically. That choice is left to the host app because Strapi admin login customization is more app-specific than the backend OTP engine.
+### Email provider
 
-## Architecture Guide
+The plugin sends OTP emails through Strapi's email plugin, so the host project must configure an email provider.
 
-The plugin has a minimal admin entry and a backend-focused server implementation.
+### Proxy and HTTPS
 
-### Main files
+If the project runs behind a reverse proxy, configure `config/server.ts` correctly so secure admin cookies work.
 
-```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 the plugin routes for login, verify, and resend.
-
-- `server/src/controllers/auth.js`
-  Reads requests, extracts client IP, delegates to the service, and sets the admin refresh cookie after successful verification.
-
-- `server/src/services/auth.js`
-  Core OTP logic: credential validation, challenge lifecycle, resend/verify rules, rate limiting, email sending, and final session creation.
-
-- `server/src/utils/strapi-session-auth.js`
-  Runtime helper that resolves Strapi's internal admin session utility needed to create the final admin session.
-
-### Security model
-
-- password-only login is not enough
-- raw OTP values are never stored
-- OTPs expire
-- verify/resend/login are rate-limited
-- the final Strapi admin session is created only after OTP verification
-
-### Important limitation
-
-This is email OTP, not TOTP or WebAuthn. It improves admin security substantially, but it is still weaker than authenticator-app or passkey-based 2FA.
-
-If you already maintain a patched Strapi admin login screen, point it to:
-
-- `/api/admin-2fa/login`
-- `/api/admin-2fa/verify`
-- `/api/admin-2fa/resend`
-
-### 3. Ensure proxy / HTTPS settings are correct in production
-
-If your Strapi app runs behind a proxy, make sure `config/server.ts` is configured correctly so secure admin cookies work.
-
-Example:
+Typical example:
 
 ```ts
-// config/server.ts
 import type { Core } from "@strapi/strapi";
 
 const config = ({ env }: Core.Config.Shared.ConfigParams): Core.Config.Server => ({
@@ -340,7 +221,7 @@ export default config;
 
 ## Environment Variables
 
-Suggested variables for the host Strapi project:
+Suggested defaults:
 
 ```env
 ADMIN_OTP_DIGITS=6
@@ -357,51 +238,68 @@ ADMIN_OTP_RESEND_EMAIL_LIMIT=5
 ADMIN_OTP_DEBUG_TIMINGS=false
 ```
 
-## Plugin Development
+## Code-Level Architecture
 
-Install dependencies:
+Main files:
 
-```bash
-npm install
+```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
 ```
 
-Build the plugin:
+Responsibilities:
 
-```bash
-npm run build
-```
+- `admin/src/index.js`
+  Minimal admin plugin stub required by the Strapi Plugin SDK.
 
-Watch during development:
+- `server/src/routes/index.js`
+  Declares the login, verify, and resend routes.
 
-```bash
-npm run watch
-```
+- `server/src/controllers/auth.js`
+  Reads the request, extracts client IP, delegates to the service, and sets the admin refresh cookie after successful OTP verification.
+
+- `server/src/services/auth.js`
+  Core OTP logic: credential validation, challenge lifecycle, resend/verify rules, rate limiting, email sending, and final session creation.
 
-Verify publishable output:
+- `server/src/utils/strapi-session-auth.js`
+  Runtime helper that resolves Strapi's internal admin session utility for final session creation.
 
-```bash
-npm run verify
-```
+## Repo Docs
 
-Link to a Strapi project with the SDK workflow:
+If you are reading the source repository directly, deeper docs are also available in:
+
+- `docs/INTEGRATION.md`
+- `docs/ARCHITECTURE.md`
+
+## Development
 
 ```bash
-npm run watch:link
+npm install
+npm run build
 ```
 
-## Publishing Checklist
+Useful commands:
+
+- `npm run build`
+- `npm run watch`
+- `npm run watch:link`
+- `npm run verify`
 
-Before publishing:
+## Publishing Checklist
 
-1. Run `npm install`
-2. Run `npm run build`
-3. Run `npm run verify`
-4. Confirm the host Strapi app works with the built package
-5. Update the package version
-6. Publish with `npm publish`
+1. run `npm install`
+2. run `npm run build`
+3. run `npm run verify`
+4. verify the plugin in a real Strapi app
+5. bump the version
+6. publish with `npm publish --access public`
 
 ## Production Notes
 
-- Email OTP is a practical 2FA improvement, but it is weaker than TOTP or WebAuthn.
-- If an attacker controls the admin email inbox, they can still complete the second factor.
-- For stronger security, consider adding trusted devices, backup codes, TOTP, or passkeys in a future version.
+- Email OTP is better than password-only login, but weaker than TOTP or WebAuthn.
+- If the admin mailbox is compromised, the second factor can still be bypassed.
+- For stronger security later, consider TOTP, backup codes, trusted devices, or passkeys.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vivinkv28/strapi-2fa-admin-plugin",
-  "version": "0.1.1",
+  "version": "0.1.4",
   "description": "Reusable Strapi admin 2FA plugin",
   "type": "commonjs",
   "keywords": [