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

package/docs/ARCHITECTURE.md

@@ -0,0 +1,203 @@
+# Architecture Guide
+
+This guide explains the internal structure of `@vivinkv28/strapi-2fa-admin-plugin` for maintainers and contributors.
+
+## High-Level Design
+
+The plugin is a backend-focused Strapi 5 plugin with a minimal admin stub.
+
+Its responsibilities are:
+
+- validate Strapi admin credentials
+- create a temporary OTP challenge
+- send an OTP by email
+- verify the OTP
+- create the final Strapi admin session only after OTP verification
+
+Its non-responsibilities are:
+
+- replacing the Strapi admin login UI
+- rendering a custom OTP page inside the admin by itself
+
+## Folder Structure
+
+```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
+```
+
+## Entry Points
+
+### `admin/src/index.js`
+
+This is a minimal admin-side plugin entry required by the Strapi Plugin SDK.
+
+Right now it only provides:
+
+- `register()`
+- `bootstrap()`
+- `registerTrads()`
+
+It does not add real admin UI behavior.
+
+### `server/src/index.js`
+
+This is the server-side plugin entry. It wires together:
+
+- controllers
+- routes
+- services
+
+## Routes
+
+Defined in [`server/src/routes/index.js`](../server/src/routes/index.js).
+
+The plugin registers a `content-api` router with these logical paths:
+
+- `/login`
+- `/verify`
+- `/resend`
+
+Because Strapi prefixes plugin content-api routes with the plugin name, these become:
+
+- `/api/admin-2fa/login`
+- `/api/admin-2fa/verify`
+- `/api/admin-2fa/resend`
+
+## Controller Layer
+
+Defined in [`server/src/controllers/auth.js`](../server/src/controllers/auth.js).
+
+The controller is intentionally thin:
+
+- reads request body
+- reads client IP from proxy-aware request headers
+- calls the auth service
+- sets the Strapi admin refresh cookie after successful OTP verification
+- returns response data in Strapi-style `{ data: ... }` format
+
+### Client IP handling
+
+The controller checks:
+
+1. `x-forwarded-for`
+2. `ctx.request.ip`
+3. `ctx.ip`
+
+This is important because the service rate-limits by IP.
+
+## Service Layer
+
+Defined in [`server/src/services/auth.js`](../server/src/services/auth.js).
+
+This is the core of the plugin.
+
+### Main responsibilities
+
+- read plugin config from `strapi.config.get("plugin::admin-2fa")`
+- normalize and validate request input
+- call `strapi.service("admin::auth").checkCredentials(...)`
+- generate OTP codes
+- hash OTP values with `crypto.scrypt`
+- store challenge state in `strapi.store`
+- enforce resend/verify/login rate limits
+- send OTP email using Strapi email plugin
+- create the final Strapi admin session after OTP verification
+
+### Important internal helpers
+
+#### `getPluginConfig()`
+
+Builds the runtime configuration using plugin config values with defaults.
+
+#### `createOtpCode()`
+
+Generates a numeric OTP code with configurable length.
+
+#### `createOtpHash()`
+
+Hashes the OTP using:
+
+- `challengeId`
+- `code`
+- random `salt`
+
+The raw OTP is never stored.
+
+#### `registerRateLimitHit()`
+
+Stores rate-limit counters in `strapi.store`.
+
+Rate-limit keys are hashed with SHA-256 so raw identifiers are not used directly as store keys.
+
+#### `createSession()`
+
+Uses Strapi's internal admin session helpers to generate:
+
+- refresh token
+- cookie options
+- access token
+- sanitized admin user
+
+## Challenge Storage
+
+The plugin uses `strapi.store()` with:
+
+- type: `plugin`
+- name: `admin-otp-login`
+
+This is used for:
+
+- OTP challenges
+- rate-limit entries
+
+This keeps OTP state internal to Strapi rather than creating a public collection type.
+
+## Session Helper
+
+Defined in [`server/src/utils/strapi-session-auth.js`](../server/src/utils/strapi-session-auth.js).
+
+Strapi does not expose the needed admin session helper directly as a simple public import for this use case, so the plugin resolves the installed Strapi admin `session-auth.js` helper at runtime.
+
+This is one of the more sensitive parts of the implementation because it depends on Strapi internal package layout.
+
+## Security Model
+
+### Good properties
+
+- password alone does not create a final admin session
+- OTP is hashed, not stored in plain text
+- OTPs expire
+- resend attempts are limited
+- verify attempts are limited
+- login/verify/resend rate limits exist
+
+### Limitations
+
+- this is email OTP, not TOTP or WebAuthn
+- if the admin email account is compromised, the second factor can still be bypassed
+- session creation still depends on Strapi internal admin session utilities
+
+## Extension Points
+
+If you want to extend this plugin later, common directions are:
+
+- customizable email templates
+- audit logging
+- backup codes
+- trusted devices
+- TOTP support
+- WebAuthn/passkeys
+
+## Integration Boundary
+
+The clean boundary is:
+
+- plugin: backend 2FA engine
+- host app: admin login UI interception and OTP screen behavior
+
+That split is intentional and should stay explicit in docs and versioning.

package/docs/INTEGRATION.md

@@ -0,0 +1,246 @@
+# Integration Guide
+
+This guide explains how to use `@vivinkv28/strapi-2fa-admin-plugin` inside an existing Strapi 5 project.
+
+## What The Plugin Does
+
+The plugin provides the backend endpoints and auth logic for an OTP-based admin login flow.
+
+It does not replace the Strapi admin login UI by itself.
+
+Your host project must provide a login integration layer that:
+
+1. collects admin email and password
+2. calls the plugin login endpoint
+3. shows an OTP input screen
+4. calls the plugin verify endpoint
+5. optionally allows OTP resend
+
+## Endpoints
+
+The plugin registers these routes:
+
+- `POST /api/admin-2fa/login`
+- `POST /api/admin-2fa/verify`
+- `POST /api/admin-2fa/resend`
+
+## Install And Enable
+
+### Published npm package
+
+```bash
+npm install @vivinkv28/strapi-2fa-admin-plugin
+```
+
+### Local external plugin
+
+In your Strapi app:
+
+```ts
+// config/plugins.ts
+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),
+      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;
+```
+
+## Required Host App Setup
+
+### Email provider
+
+The plugin calls `strapi.plugin("email").service("email").send(...)`.
+
+Your Strapi project must configure an email provider or OTP delivery will fail.
+
+### Proxy and HTTPS
+
+If your project runs behind a reverse proxy, configure `config/server.ts` correctly so Strapi recognizes secure requests and admin cookies are set with the right options.
+
+Typical example:
+
+```ts
+import type { Core } from "@strapi/strapi";
+
+const config = ({ env }: Core.Config.Shared.ConfigParams): Core.Config.Server => ({
+  host: env("HOST", "0.0.0.0"),
+  port: env.int("PORT", 1337),
+  url: env("URL", "http://localhost:1337"),
+  proxy: env.bool("IS_PROXIED", env("NODE_ENV", "development") === "production"),
+  app: {
+    keys: env.array("APP_KEYS"),
+  },
+});
+
+export default config;
+```
+
+## Request Flow
+
+### 1. Start login
+
+Send admin email and password to:
+
+```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
+  }
+}
+```
+
+What happens here:
+
+- Strapi validates the admin credentials
+- the plugin creates an OTP challenge
+- the plugin emails the OTP
+- no final admin session is created yet
+
+### 2. Verify OTP
+
+Send the OTP code to:
+
+```http
+POST /api/admin-2fa/verify
+Content-Type: application/json
+```
+
+Example payload:
+
+```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"
+    }
+  }
+}
+```
+
+What happens here:
+
+- the plugin reloads the OTP challenge
+- the submitted code is hashed and compared
+- the real Strapi admin session is created only after OTP verification
+- the refresh cookie is set by the plugin controller
+
+### 3. Resend OTP
+
+Send:
+
+```http
+POST /api/admin-2fa/resend
+Content-Type: application/json
+```
+
+Example payload:
+
+```json
+{
+  "challengeId": "0d3af6fd-b351-4d1e-bb81-2a8201d8a0f4"
+}
+```
+
+This generates a new OTP for the same challenge and extends the expiry.
+
+## Error Cases To Handle In The UI
+
+Your login integration should handle these cases cleanly:
+
+- invalid email or password
+- OTP session not found
+- OTP expired
+- invalid OTP code
+- too many authentication attempts
+- maximum resend attempts exceeded
+
+These are returned as normal Strapi error responses, so the frontend should surface the message to the admin user in a safe and friendly way.
+
+## Recommended Frontend Behavior
+
+- Keep login and OTP entry as two separate UI states.
+- Store `challengeId` in memory for the current login attempt.
+- Do not create your own session after password validation; wait for `/verify`.
+- After successful OTP verification, treat the returned user/token exactly like a successful admin login.
+- If resend fails due to limits or expiry, restart the login flow.
+
+## Environment Variables
+
+Recommended defaults:
+
+```env
+ADMIN_OTP_DIGITS=6
+ADMIN_OTP_TTL_SECONDS=300
+ADMIN_OTP_MAX_ATTEMPTS=5
+ADMIN_OTP_MAX_RESENDS=3
+ADMIN_OTP_RATE_LIMIT_WINDOW_SECONDS=900
+ADMIN_OTP_LOGIN_IP_LIMIT=10
+ADMIN_OTP_LOGIN_EMAIL_LIMIT=5
+ADMIN_OTP_VERIFY_IP_LIMIT=20
+ADMIN_OTP_VERIFY_EMAIL_LIMIT=10
+ADMIN_OTP_RESEND_IP_LIMIT=10
+ADMIN_OTP_RESEND_EMAIL_LIMIT=5
+ADMIN_OTP_DEBUG_TIMINGS=false
+```
+
+## Production Notes
+
+- 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.
+- Use app passwords or provider-managed SMTP credentials for OTP delivery.
+- Make sure your host project sets `URL` and proxy settings correctly in production.

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@vivinkv28/strapi-2fa-admin-plugin",
+  "version": "0.1.0",
+  "description": "Reusable Strapi admin 2FA plugin",
+  "type": "commonjs",
+  "keywords": [
+    "strapi",
+    "strapi-plugin",
+    "strapi-v5",
+    "2fa",
+    "otp",
+    "admin-auth"
+  ],
+  "files": [
+    "dist",
+    "docs"
+  ],
+  "exports": {
+    "./package.json": "./package.json",
+    "./strapi-admin": {
+      "source": "./admin/src/index.js",
+      "import": "./dist/admin/index.mjs",
+      "require": "./dist/admin/index.js",
+      "default": "./dist/admin/index.js"
+    },
+    "./strapi-server": {
+      "source": "./server/src/index.js",
+      "import": "./dist/server/index.mjs",
+      "require": "./dist/server/index.js",
+      "default": "./dist/server/index.js"
+    }
+  },
+  "scripts": {
+    "build": "strapi-plugin build",
+    "watch": "strapi-plugin watch",
+    "watch:link": "strapi-plugin watch:link",
+    "verify": "strapi-plugin verify"
+  },
+  "engines": {
+    "node": ">=20.0.0 <=22.x.x",
+    "npm": ">=9.0.0"
+  },
+  "devDependencies": {
+    "@strapi/sdk-plugin": "^5.0.0",
+    "prettier": "^3.0.0"
+  },
+  "peerDependencies": {
+    "@strapi/strapi": "^5.0.0",
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0",
+    "react-router-dom": "^6.0.0",
+    "styled-components": "^6.0.0"
+  },
+  "strapi": {
+    "name": "admin-2fa",
+    "displayName": "Admin 2FA",
+    "description": "Adds OTP-based 2FA for Strapi admin authentication",
+    "kind": "plugin"
+  },
+  "license": "MIT"
+}