Peyvast Auth

Peyvast Auth is a WordPress authentication plugin with phone and email OTP login, password authentication, registration, password recovery, optional Google Sign-In, Iranian SMS and WordPress email providers, and integrations for WooCommerce, Bricks, and Blocks.

Version: 1.0.0 / License: GPL-2.0-or-later / PHP: 8.1+ / WordPress: 6.7+ / WooCommerce: 8.0+ (optional) / Bricks: 2.0+ (optional)

What the plugin does

The plugin renders an authentication interface and exposes the peyvast-auth/v1 REST API. A visitor submits an identifier, receives a time-limited OTP through the configured provider, verifies it, and then either signs in or completes registration. Existing users can also sign in with a password. Password reset requires a verified reset OTP and never signs the user in automatically.

Authentication flows

Phone or email OTP login

1. The browser submits send-otp with an identifier and purpose otp_login.
2. The server normalizes the identifier, checks configured capabilities, resolves existing identity data, evaluates server-side security buckets, and applies the resend cooldown.
3. A challenge stores only an HMAC OTP digest, expiry, purpose, identity hash, delivery channels, and an opaque guest-session binding.
4. The configured SMS or email adapter delivers the code.
5. The browser submits verify-otp with the challenge ID and code.
6. Successful verification creates a short-lived, single-use verification token.
7. otp-login consumes that token and creates the WordPress session. If no account exists, register consumes the registration token instead.

Password login

password-login resolves a phone, email, or username according to settings, checks the WordPress password, runs wp_authenticate_user, applies the plugin login policy, optionally rehashes the password, and creates the WordPress session.

Registration

Registration requires a verified phone OTP. The service acquires phone, email, and username locks, rechecks identity ownership, validates enabled fields, creates the WordPress user, stores the canonical phone metadata, synchronizes the phone identity index, finalizes the OTP token, and logs the result. Failed post-creation checks attempt compensating deletion.

Password recovery

send-otp with purpose password_reset only proceeds for an existing phone or email identity. The verified reset token is bound to the intended user, consumed during password update, and all existing WordPress sessions are revoked. The user must then sign in separately.

Google sign-in

When enabled, google-login verifies the Google ID token locally: JWT structure, algorithm, signature, issuer, audience, subject, email claims, and key retrieval are checked. Google JWKS data is fetched through the WordPress HTTP API, size-limited, and cached.

Security model

• State-changing REST requests require a WordPress nonce and same-origin validation.
• Guest challenges are bound to a random HttpOnly, SameSite cookie.
• OTPs and verification tokens are stored as hashes, not plaintext.
• Challenges expire, have bounded attempts, and are single-use.
• Server-side IP, network, identifier, and combination security buckets provide rate limiting and progressive blocking.
• Redirect settings are host-validated.
• Provider credentials are sanitized and are not returned by success responses.
• Operational logs redact sensitive values and support retention cleanup.
• HTTPS is strongly recommended, especially for authentication and provider credentials.

Installation and configuration

1. Place the repository in wp-content/plugins/peyvast-auth.
2. Activate Peyvast Auth.
3. Open Peyvast Authentication → Settings.
4. Configure at least one SMS provider or WordPress email delivery.
5. Add the Peyvast Auth Blocks or Bricks element to a page.
6. Test all enabled flows on staging before production use.

Activation creates four InnoDB tables using the WordPress database prefix:

• {prefix}peyvast_auth_otp_challenges
• {prefix}peyvast_auth_phone_identity
• {prefix}peyvast_auth_logs
• {prefix}peyvast_auth_security_state

The plugin stores its settings and operational keys under the peyvast_auth_ namespace. Uninstall cleanup is conditional on the administrator's delete data on uninstall setting.

REST endpoints

Public endpoints: send-otp, verify-otp, otp-login, register, password-login, reset-password, google-login, logout, and security-status. Administrative endpoints: settings, security-blocks, migrate-user-phone, migration-status, migration-notice, validate-phone-meta, and test-provider.

All endpoints are POST routes. Public permission callbacks intentionally allow routing to the controller; nonce, origin, guest-session, identity, and security checks are performed by the controller/service layer. Administrative routes additionally require manage_options.

Integrations

• Blocks: authentication and back-button blocks with server rendering.
• Bricks: authentication/back-button elements and dynamic tags.
• WooCommerce: optional customer phone synchronization, account/checkout/order-receipt redirects, notices, and HPOS compatibility declaration.
• WordPress Privacy: phone export and erasure, related OTP/index/log cleanup.

Phone data and privacy

Phone numbers are normalized into a canonical Iranian mobile representation. The primary phone is stored in _peyvast_auth_phone; a keyed canonical hash is stored in _peyvast_auth_phone_canonical; the identity table accelerates lookup. Privacy erasure removes these values and related plugin-owned rows.

See ARCHITECTURE.md for detailed components and data flow, STRUCTURE.md for the repository map, SECURITY.md for vulnerability reporting, CONTRIBUTING.md for development rules.#