# Mersal OTP — Feature & Options Inventory

> Source-of-truth catalogue of everything the plugin does and every admin option it exposes.
> Intended for designing a marketing/landing page. Generated 2026-06-21 from plugin **v1.11.0**.
> Requirements: WordPress 5.8+, PHP 7.4+, WooCommerce optional, LearnPress optional.

---

## 1. One-line pitch
A passwordless / multi-factor login suite for WordPress & WooCommerce: sign in with **WhatsApp,
SMS, Email, or the Mersal Authenticator app**, with real phone-number handling, device & session
management, and an enterprise security layer — all driven by the connected **mersal.it** account for
message delivery.

---

## 2. Login & authentication methods (the headline features)

| Method | How it works | Notes |
|---|---|---|
| **Email** | OTP code, **Password**, or **Magic link** — admin picks the primary method and which are offered | Delivered via WordPress `wp_mail()` (with optional **custom SMTP**) or Mersal email gateways |
| **WhatsApp** | OTP delivered over WhatsApp via a connected gateway. 4 message styles (below) | Can offer several styles at once and let the user choose |
| **SMS** | OTP over SMS via a connected gateway | Can act as automatic fallback for WhatsApp |
| **Mersal Authenticator app** | (a) offline **6-digit TOTP** code, or (b) **push approval** — a confirm request appears in the app showing IP/location/browser/OS/time to Approve or Deny | Verified against the connected Mersal account; paired once via `/app/pair` |
| **Google sign-in** | One-click "Continue with Google" OAuth button | Optional; needs Client ID + Secret |
| **One-tap confirm link** | A short sign-in link inside the WhatsApp/SMS message; tapping it logs in without typing the code | Token+secret model, browser polls for approval |

### WhatsApp message styles
- **Standard** — plain 6-digit OTP text message.
- **Poll (Approve / Reject)** — a WhatsApp poll; tapping "Approve" logs the user in.
- **Confirm card (button)** — a "Login Confirmation" card with a tappable Confirm button (Wawp-style).
- **Confirmation link** — one-tap approval link embedded in the message.

### Login-screen presets
- **Phone-first**, **Email-first**, or **Show every method** (full picker).
- Optional **remember last method** per user; optional **sign-up** link.

---

## 3. Admin dashboard — information architecture (current)

**Overview**
- **Dashboard** — live stats (codes sent, delivery rate, channels), setup checklist, recent activity, connection banner, notification bell (announcements pulled from mersal.it).

**Authentication**
- **Code settings** — OTP length (4–8), type (numeric/alpha/alphanumeric), expiry, max attempts, lockout, one-active-code, case sensitivity, reuse-once.
- **General settings** — tabbed:
  - **General** — default login method preset, auto-redirect, sign-up link, remember last method, one-tap confirm link.
  - **Phone rules** — automatic WhatsApp→SMS fallback, number validation (format, country code, landline, HLR lookup), allowed-countries policy + default country + number display format, and **auto-correct** (intl-tel-input: enable, IP detection, carrier lookup, default country, flag alignment, allowed-countries whitelist, target field selectors).
  - **Sessions** — session length, remember-me length, logout on password change, device management, new-device email alert.
  - **Behavior** — auto-link by email, allow unverified email, sync mobile to WooCommerce billing.
  - Plus **Login page** auto-create/blank-template and **Force login** site gate.

**Login methods**
- **Email** (الإيميل) — tabbed: **Method** (OTP / Password / Magic link + which are available), **Provider** (sender name/email, WordPress vs Mersal gateways, **custom SMTP** host/port/encryption/credentials), **Verification** (require email verify, block checkout until verified).
- **Phone** (الهاتف) — tabbed by method:
  - **WhatsApp** — enable channel, gateway select, message style, methods the user can choose, message/poll/link content editors.
  - **SMS** — enable channel, gateway select, message body.
  - **Authenticator app** — allow app-code sign-in, push approval, pairing guidance.
- **Google** — enable, OAuth credentials, auto-link, ask-mobile-after-signup, restrict domains, button label.

**Appearance & pages**
- **Message templates** — per-event email/WhatsApp/SMS bodies with placeholders (`{{otp}}`, `{{site_name}}`, `{{expiry}}`, `{{user_name}}`, `{{ip}}`).
- **Identity & styling** — theme (green/cyan/light), light/dark, **start form in dark mode**, dark + language toggles on the form, UI font (10 fonts), button color, title/subtitle, 4 brand-logo variants (AR/EN × light/dark), logo height, custom CSS.
- **Login & signup pages** — auto-create auth page, blank canvas template, redirect rules, shortcodes.

**Data & security**
- **Users** — wp-admin Users list gets a Phone column (verified badge) + phone search.
- **OTP logs** — code sent/verified/login/signup/failed events, searchable.
- **Security** — see §5.
- **Updates** — self-update from mersal.it.

**Account**
- **Connect Mersal** — SSO link to mersal.it, gateway sync, connection status.

---

## 4. Phone number handling
- **intl-tel-input** auto-correct: country selector on phone fields, live normalization to international format, IP-based country detection, allowed-country whitelist, RTL/LTR flag alignment, custom target selectors.
- **Validation**: format check, require country code, block landlines, HLR reachability lookup, carrier lookup.
- **Display format**: international / local / E.164; default country.
- **Profile**: phone shown on the WP profile screen with verified badge; "confirm your number" bar (shortcode + WooCommerce My Account).
- **WooCommerce billing-phone sync** (bidirectional, opt-out).

---

## 5. Security layer
- **Rate limiting** — per-IP/hour, per-identifier/day, cooldown, master toggle.
- **Lockout** — after N failed attempts for a configurable duration; one active code option.
- **IP / country blocking** — blocklists, allow vs deny country policy.
- **VPN / proxy / datacenter** detection (fails open).
- **Disposable-number** detection — junk patterns, admin prefix blocklist, numverify line-type lookup.
- **CAPTCHA** — reCAPTCHA v3 / Cloudflare Turnstile / hCaptcha.
- **Privacy mode** (anti-enumeration), **honeypot**, **trust-proxy** for X-Forwarded-For/CF-Connecting-IP.
- **Forced 2FA for roles** (gated to wp-admin so it can't lock out the front end).
- **CSRF nonces** on all AJAX; OTP full-range entropy with leading zeros.

---

## 6. Devices, sessions & 2FA
- Device fingerprinting (UA+IP), up to 20 devices/user with metadata (browser, OS, location, first/last login).
- Revoke a single device or all-but-current; logout-everywhere on password change; optional new-device email alert.
- Mersal Authenticator pairing surfaces: `/app/pair`, WooCommerce My Account endpoint, LearnPress profile tab, `[mersal_authenticator]` shortcode.

---

## 7. Appearance & branding
- 3 color themes (green/cyan/light), light/dark, **dark-by-default** option, server-rendered (no CDN, RTL-aware).
- Font registry of 10 Arabic/Latin fonts (single source of truth, auto-loads Google Fonts).
- 4 brand-logo variants, configurable height, button color, custom CSS scoped to the form.
- Auth page blank-canvas template; per-event message templates.

---

## 8. Integrations & delivery
- **mersal.it SSO + gateways** — connect once; WhatsApp/SMS/Email gateways sync into the plugin; messages send via mersal.it APIs (and the Baileys node WhatsApp gateway).
- **WooCommerce** — OTP at checkout, cart restore on logout, billing-phone sync, My Account tabs (devices, authenticator, verify-phone bar), block checkout until email verified.
- **LearnPress** — authenticator pairing tab.
- **Custom SMTP** — outgoing mail (OTP + all WP mail) routes through admin-configured SMTP when a host is set.
- **Webhooks** — `auth.confirm` (Confirm-card approval), inbound poll votes / read receipts from the node gateway.

---

## 9. Shortcodes
- `[mersal_otp]` (alias `[motp_login]`) — login/signup form. Attributes: `theme="green|cyan|light"`, `lang="ar|en"`.
- `[mersal_authenticator]` — authenticator pairing UI.
- `[mersal_otp_verify_phone]` — "confirm your number" bar.
- `[mersal_otp_devices]` — device & session manager.

---

## 10. Self-update
- Pulls from `https://mersal.it/Wordpress-Plugins` (highest version auto-detected), integrates with the
  native WordPress Updates screen, supports auto-updates, 1-hour check throttle. Extensible to other
  Mersal plugins via the `motp_updater_plugins` filter.

---

## 11. Notes from the 2026-06-21 audit (what was fixed while compiling this)
- **WhatsApp tab scroll/layout bug** — fixed (hidden option inputs are now contained inside their
  `.opt` row so focusing them no longer scroll-jumps the page).
- **Custom SMTP** — was inert (entered but never used); now applied via a `phpmailer_init` hook.
- **"Start form in dark mode" (`form_dark`)** — was never read or exposed; now wired and given an
  admin switch under Identity & styling.
- **Redundant "OTP delivery channel" radio (`phone_channel`)** — duplicated the per-channel enable
  toggles and was never read; removed.
- **IA reorg** — Phone page split into WhatsApp / SMS / Authenticator tabs; Email relabelled الإيميل;
  shared/phone-number settings consolidated into a "Phone rules" tab under General settings.
