@vivinkv28/strapi-2fa-admin-plugin 0.1.0 → 0.1.2

package/README.md

@@ -2,49 +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](./docs/INTEGRATION.md)
-- [Architecture guide](./docs/ARCHITECTURE.md)
+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 full request and response flow in [docs/INTEGRATION.md](./docs/INTEGRATION.md).
-
 ## Requirements
 
 - Strapi 5
 - Node.js `20.x` or `22.x`
-- A configured Strapi email provider
-
-## Install In An Existing Strapi Project
+- a configured Strapi email provider
 
-### Option 1: Use as a published npm package
-
-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
+
+Add the plugin to your Strapi app config:
 
 ```ts
 // config/plugins.ts
@@ -76,73 +77,133 @@ const config = ({ env }: Core.Config.Shared.ConfigParams): Core.Config.Plugin =>
 export default config;
 ```
 
-### Option 2: Use as a local external plugin
+## Admin UI Integration
 
-If the plugin lives next to your Strapi app, point Strapi to it with `resolve`:
+Because this package does not inject the full login UI by itself, the host project must integrate the admin flow.
 
-```ts
-// config/plugins.ts
-import type { Core } from "@strapi/strapi";
+### Expected UI flow
 
-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),
-      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"
-      ),
-    },
-  },
-});
+#### 1. Credentials step
 
-export default config;
+- collect email and password
+- send them to `POST /api/admin-2fa/login`
+- if successful, store `challengeId` and switch to OTP mode
+
+#### 2. OTP step
+
+- 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`
+
+### Recommended UI behavior
+
+- 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
+
+## Integration Guide
+
+### Login request
+
+```http
+POST /api/admin-2fa/login
+Content-Type: application/json
+```
+
+Example payload:
+
+```json
+{
+  "email": "admin@example.com",
+  "password": "super-secret-password",
+  "rememberMe": true,
+  "deviceId": "browser-device-id"
+}
+```
+
+Example success response:
+
+```json
+{
+  "data": {
+    "challengeId": "0d3af6fd-b351-4d1e-bb81-2a8201d8a0f4",
+    "expiresAt": "2026-04-05T18:30:00.000Z",
+    "maskedEmail": "admin@example.com",
+    "rememberMe": true
+  }
+}
+```
+
+### Verify request
+
+```http
+POST /api/admin-2fa/verify
+Content-Type: application/json
 ```
 
-## Required Host App Setup
+Example payload:
 
-### 1. Configure an email provider
+```json
+{
+  "challengeId": "0d3af6fd-b351-4d1e-bb81-2a8201d8a0f4",
+  "code": "123456"
+}
+```
+
+Example success response:
+
+```json
+{
+  "data": {
+    "token": "<access-token>",
+    "accessToken": "<access-token>",
+    "user": {
+      "id": 1,
+      "email": "admin@example.com"
+    }
+  }
+}
+```
 
-The plugin uses Strapi's `email` plugin to send OTP emails. Your host project must configure an email provider in `config/plugins.ts`.
+### Resend request
 
-### 2. Add an admin login integration layer
+```http
+POST /api/admin-2fa/resend
+Content-Type: application/json
+```
+
+Example payload:
+
+```json
+{
+  "challengeId": "0d3af6fd-b351-4d1e-bb81-2a8201d8a0f4"
+}
+```
 
-This plugin is backend-only. To use it for real admin login 2FA, your project must:
+### UI error states to handle
 
-- 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`
+- invalid email or password
+- OTP expired
+- OTP session not found
+- invalid OTP code
+- too many authentication attempts
+- maximum resend attempts exceeded
 
-The expected frontend flow, payloads, and response handling are documented in [docs/INTEGRATION.md](./docs/INTEGRATION.md).
+## Host Project Requirements
 
-If you already maintain a patched Strapi admin login screen, point it to:
+### Email provider
 
-- `/api/admin-2fa/login`
-- `/api/admin-2fa/verify`
-- `/api/admin-2fa/resend`
+The plugin sends OTP emails through Strapi's email plugin, so the host project must configure an email provider.
 
-### 3. Ensure proxy / HTTPS settings are correct in production
+### Proxy and HTTPS
 
-If your Strapi app runs behind a proxy, make sure `config/server.ts` is configured correctly so secure admin cookies work.
+If the project runs behind a reverse proxy, configure `config/server.ts` 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 => ({
@@ -160,7 +221,7 @@ export default config;
 
 ## Environment Variables
 
-Suggested variables for the host Strapi project:
+Suggested defaults:
 
 ```env
 ADMIN_OTP_DIGITS=6
@@ -177,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.
 
-Verify publishable output:
+- `server/src/services/auth.js`
+  Core OTP logic: credential validation, challenge lifecycle, resend/verify rules, rate limiting, email sending, and final session creation.
 
-```bash
-npm run verify
-```
+- `server/src/utils/strapi-session-auth.js`
+  Runtime helper that resolves Strapi's internal admin session utility for final session creation.
 
-Link to a Strapi project with the SDK workflow:
+## Repo Docs
+
+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:
 
-Before publishing:
+- `npm run build`
+- `npm run watch`
+- `npm run watch:link`
+- `npm run verify`
+
+## 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.0",
+  "version": "0.1.2",
   "description": "Reusable Strapi admin 2FA plugin",
   "type": "commonjs",
   "keywords": [