=== UnlockForge ===
Contributors: shivaacharjee
Tags: content protection, content unlock, social login, email unlock, oauth
Tested up to: 7.1
Stable tag: 0.3.0
Requires at least: 6.8
Requires PHP: 7.2
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Protect WordPress content with Social Login, Email Unlock, previews, full locks, custom unlock messages, bulk protection, and analytics.

== Description ==

UnlockForge is a WordPress content protection and content unlocking plugin that gives site owners control over how visitors access protected posts and pages.

Version 0.3.0 provides Social Login, Email Unlock, configurable protection modes, preview controls, custom Unlock Messages, bulk protection, analytics, and external identity management.

Whether you want visitors to sign in with Google, Facebook, X, LinkedIn, or GitHub, verify their email using a one-time code, show a preview before unlocking the rest of the content, or completely lock content until authentication is completed, UnlockForge provides the tools to build that experience.

UnlockForge is designed for publishers, membership sites, blogs, educational websites, documentation sites, resource websites, and other WordPress sites that need controlled access to their content.

### What can you do with UnlockForge?

* Protect posts and pages with configurable protection modes.
* Show a configurable preview before requiring authentication.
* Completely lock content until the visitor completes the unlock flow.
* Let visitors unlock content using Social Login.
* Let visitors unlock content using Email Unlock.
* Customize the unlock gate with titles, messages, images, and emoji.
* Target different Unlock Messages by WordPress category.
* Schedule Unlock Messages for specific periods.
* Protect content in bulk.
* View authentication and content-unlock analytics.
* Manage external authentication identities separately from WordPress content access.
* Use multiple authentication methods without coupling authentication directly to content protection.

UnlockForge keeps authentication and content access as separate concepts, providing a flexible foundation for different ways of unlocking content.

== Features ==

= Content Protection =

UnlockForge provides three protection modes for WordPress posts and pages:

* **Disabled** - Content is displayed normally.
* **Preview** - Display a configurable portion of the content before showing the unlock experience.
* **Full Lock** - Hide protected content until the visitor completes the configured unlock flow.

Preview content can be configured using:

* Paragraphs
* Words
* Excerpt

Preview settings can be configured globally, with per-content overrides where supported.

= Social Login =

Allow visitors to unlock protected content using familiar social-login providers.

Supported providers:

* Google
* Facebook
* X
* LinkedIn
* GitHub

OAuth credentials are configured from the WordPress admin settings.

UnlockForge establishes the visitor's external identity and associates it with a WordPress user account.

Multiple external identities can be associated with the same WordPress user.

This allows a visitor to authenticate using a supported provider while keeping external identity information separate from content-access decisions.

= Email Unlock =

Give visitors another way to unlock protected content without requiring a social-login provider.

Email Unlock uses a temporary one-time verification code.

The visitor flow is:

1. Enter an email address.
2. Request a verification code.
3. Receive the code by email.
4. Enter the verification code.
5. Unlock the protected content after successful verification.

Email Unlock provides configurable email settings including:

* OTP email subject.
* OTP email message.
* OTP expiration.
* Supported email placeholders.

Supported placeholders include:

* `{{otp}}` - The verification code.
* `{{expires_in}}` - The number of minutes before the code expires.
* `{{site_name}}` - The WordPress site name.

Email delivery uses the WordPress mail system, allowing site administrators to use their preferred SMTP or transactional email configuration.

= Custom Unlock Messages =

Create customized unlock experiences for your visitors.

Unlock Messages support:

* Custom title.
* Custom message.
* Emoji.
* Image.
* WordPress category targeting.
* Start date and time.
* End date and time.
* Multiple categories.

Different content can therefore display different unlock messages based on category and scheduling rules.

If no matching Unlock Message exists, UnlockForge uses the normal content protection flow.

= Bulk Protection =

Protect multiple existing posts or pages without opening each item individually.

Bulk Protection supports:

* Posts.
* Pages.
* All content.
* Category-based filtering.
* Protection mode selection.
* Batch processing.
* Operation progress tracking.

Bulk operations are processed in batches to avoid unnecessarily large requests.

Administrators can choose:

* Disabled.
* Preview.
* Full Lock.

Existing protection settings may be overwritten when applying a bulk operation.

= Analytics =

Understand how visitors interact with protected content and authentication.

The Analytics dashboard provides information about:

* Unlocks.
* Unique Users.
* Successful Logins.
* Login to Unlock conversion.
* Unlock Activity.
* Login Providers.
* Login Failures.
* Top Protected Content.
* Unlock Message Performance.

Analytics can be viewed using:

* Today.
* Last 7 Days.
* Last 30 Days.
* Last 90 Days.
* Custom Date Range.

Analytics timestamps are handled using the WordPress site timezone for date-range selection.

= External Identity Management =

UnlockForge maintains external authentication identity information separately from WordPress user accounts.

This allows a WordPress user to have multiple supported external identities while keeping authentication identity data separate from content-access decisions.

This architecture also provides flexibility for adding additional authentication and access methods over time.

== How It Works ==

A simplified protected-content flow:

1. A visitor opens protected content.
2. UnlockForge checks the configured protection mode.
3. If the content requires authentication, the visitor sees the configured unlock experience.
4. The visitor chooses an available authentication method.
5. The visitor authenticates using Social Login or verifies their email using a one-time verification code.
6. UnlockForge establishes the authentication identity.
7. The visitor can access the protected content.

Authentication and content access are separate concepts in the plugin architecture.

This means the authentication method can evolve independently from the content-protection system.

== Installation ==

1. Upload the `unlockforge` folder to the `/wp-content/plugins/` directory.
2. Activate UnlockForge from the WordPress Plugins screen.
3. Open **Settings → UnlockForge**.
4. Configure the required content protection settings.
5. Configure Social Login, Email Unlock, or both.
6. Protect a post or page using the UnlockForge protection settings.

== Configuration ==

After activation, open:

**Settings → UnlockForge**

UnlockForge provides dedicated settings for:

* Preview.
* Social Login.
* Email Unlock.
* Unlock Messages.
* Bulk Protection.
* Analytics.
* About & Help.

Each area is designed to configure a specific part of the content protection and unlocking experience.

== Social Login Setup ==

To configure Social Login:

1. Open **Settings → UnlockForge → Social Login**.
2. Enable the required provider.
3. Create an OAuth application with the selected provider.
4. Enter the required client credentials.
5. Configure the provider's OAuth callback URL using the URL displayed by UnlockForge.
6. Save the settings.
7. Test the login flow using a protected post or page.

Supported providers:

* Google
* Facebook
* X
* LinkedIn
* GitHub

Keep OAuth client secrets private and never expose them in client-side code.

== Email Unlock Setup ==

To configure Email Unlock:

1. Open **Settings → UnlockForge → Email Unlock**.
2. Enable Email Unlock.
3. Configure the OTP email subject.
4. Configure the OTP email message.
5. Configure WordPress email delivery.
6. Protect a post or page using UnlockForge.
7. Test the Email Unlock flow from the visitor-facing content gate.

For production websites, a reliable SMTP or transactional email configuration is recommended to ensure verification emails are delivered consistently.

== Security ==

UnlockForge applies multiple layers of protection across its authentication and content-unlock flows.

= WordPress Security =

UnlockForge uses standard WordPress security mechanisms including:

* WordPress nonces for protected administrative and AJAX actions.
* WordPress capability checks for administrative operations.
* Sanitization of submitted values.
* Escaping of output.
* Protected storage of provider credentials.

= OAuth Security =

Social Login uses OAuth state validation to protect the authentication callback flow.

UnlockForge also uses:

* Server-side OAuth state storage.
* Browser-bound nonce validation.
* Single-use OAuth state values.
* Secure cookies when HTTPS is enabled.
* HttpOnly cookies.
* SameSite cookie protection.

OAuth client secrets should never be exposed publicly or included in client-side JavaScript.

= Email OTP Security =

Email Unlock includes multiple protections around the verification process:

* Temporary OTP challenges.
* OTP expiration.
* Hashed OTP storage.
* Browser-bound verification challenges.
* Email-based rate limiting.
* IP-based rate limiting.
* WordPress nonce validation.
* Server-side content context resolution.
* Temporary challenge consumption during verification.

OTP values are not stored as plaintext in the temporary verification challenge.

Rate limiting helps reduce repeated OTP requests and automated abuse.

= Server-Side Content Context =

UnlockForge does not rely solely on a visitor-supplied content identifier when establishing an Email Unlock challenge.

The content context is resolved server-side before the verification challenge is created.

This helps prevent a visitor from changing a client-side content identifier and associating a valid verification flow with unrelated protected content.

= Privacy & Data Handling =

UnlockForge may store information required to establish and associate authentication identities with WordPress user accounts.

The information stored depends on the authentication method and configuration of the site.

UnlockForge also provides privacy erasure handling for stored identity information and anonymizes associated analytics user references where applicable.

Site administrators are responsible for configuring their site and privacy policies appropriately for the data collected through enabled authentication methods.

== Screenshots ==

1. Preview Settings for configuring protected content previews.
2. Bulk Protection for applying protection to multiple posts or pages.
3. Category-based content protection management.
4. Social Login settings for configuring supported OAuth providers.
5. Unlock Messages for creating customized and scheduled unlock experiences.
6. Analytics dashboard showing authentication and content-unlock activity.
7. User-facing content lock gate with authentication options and customized unlock message.
8. Email Unlock Settings with Configurable Email Template.
9. User-Facing Email Unlock Gate for Protected Content
10. User-Facing OTP Verification for Content Unlock

== Unlock Messages ==

Unlock Messages allow site administrators to customize the experience visitors see when they encounter protected content.

A message can include:

* Title.
* Message.
* Emoji.
* Image.
* Categories.
* Start date and time.
* End date and time.

Messages can be targeted to specific WordPress categories and scheduled for specific periods.

When multiple messages match the same content, UnlockForge uses the applicable message based on its configured matching and scheduling rules.

== Analytics ==

UnlockForge records authentication and content-unlock events to provide administrators with useful visibility into protected-content activity.

Analytics events include:

* Login Started.
* Login Successful.
* Login Failed.
* Content Unlock.

Login failures are grouped by failure reason to help administrators identify problems with the authentication flow.

The Analytics dashboard provides both activity information and aggregated metrics such as unique users and login-to-unlock conversion.

== Bulk Protection ==

Bulk Protection allows administrators to apply protection settings to multiple existing posts and pages.

You can select:

* Posts or Pages.
* All content or selected categories.
* Disabled, Preview, or Full Lock.

Bulk operations are processed in batches and display their progress while running.

Existing protection settings may be overwritten when applying a bulk operation.

== Testing & Troubleshooting ==

If an OAuth callback does not work after configuring a provider, visit:

**Settings → Permalinks**

and click **Save Changes** to refresh WordPress rewrite rules.

When testing Social Login:

* Confirm the provider is enabled.
* Confirm the OAuth client ID and secret are correct.
* Confirm the configured callback URL matches the provider configuration.
* Confirm the WordPress site URL is correct.
* Test using a protected post or page.

When testing Email Unlock:

* Confirm Email Unlock is enabled.
* Confirm the OTP email subject and message are configured.
* Confirm WordPress email delivery is working.
* Confirm the SMTP or transactional email configuration is working.
* Confirm the verification email is being delivered.
* Test the complete flow from the protected content gate.

== Privacy ==

UnlockForge may store information required to establish and associate external social-login identities and email-based authentication with WordPress user accounts.

The information stored depends on the authentication method, provider, and configuration of the site.

Analytics may store authentication and content-unlock activity for reporting purposes.

UnlockForge provides privacy erasure handling for stored identity information and anonymizes associated analytics user references where applicable.

Site administrators are responsible for configuring their site and privacy policies appropriately for the data collected through enabled authentication methods and third-party providers.

== External Services ==

UnlockForge uses third-party OAuth services when a site administrator enables the corresponding Social Login provider.

These services are used to authenticate visitors and retrieve identity information required to create or associate an external identity with a WordPress user.

No external OAuth service is contacted for Social Login when its provider is disabled.

= Google =

UnlockForge uses Google OAuth to authenticate users and retrieve basic account information required for authentication and identity association.

Data sent to Google:

* OAuth authorization requests.
* OAuth authorization code during the authentication flow.

Data received from Google may include:

* Google account identifier.
* Name.
* Email address.
* Profile information made available through the configured Google OAuth scopes.

Google is contacted when a visitor chooses Google as their login provider.

Terms of Service: https://policies.google.com/terms
Privacy Policy: https://policies.google.com/privacy

= Facebook =

UnlockForge uses Facebook Login to authenticate users and retrieve account information required for authentication and identity association.

Data sent to Facebook:

* OAuth authorization requests.
* OAuth authorization code during the authentication flow.

Data received from Facebook may include:

* Facebook user identifier.
* Name.
* Email address.
* Profile information made available through the configured permissions.

Facebook is contacted when a visitor chooses Facebook as their login provider.

Terms of Service: https://www.facebook.com/legal/terms
Privacy Policy: https://www.facebook.com/privacy/policy

= LinkedIn =

UnlockForge uses LinkedIn OAuth to authenticate users and retrieve account information required for authentication and identity association.

Data sent to LinkedIn:

* OAuth authorization requests.
* OAuth authorization code during the authentication flow.

Data received from LinkedIn may include:

* LinkedIn member identifier.
* Name.
* Email address.
* Profile information made available through the configured scopes.

LinkedIn is contacted when a visitor chooses LinkedIn as their login provider.

Terms of Service: https://www.linkedin.com/legal/user-agreement
Privacy Policy: https://www.linkedin.com/legal/privacy-policy

= X =

UnlockForge uses X OAuth to authenticate users and retrieve account information required for authentication and identity association.

Data sent to X:

* OAuth authorization requests.
* OAuth authorization code during the authentication flow.

Data received from X may include:

* X user identifier.
* Name.
* Username.
* Email address when available through the configured access permissions.

X is contacted when a visitor chooses X as their login provider.

Terms of Service: https://x.com/en/tos
Privacy Policy: https://x.com/en/privacy

= GitHub =

UnlockForge uses GitHub OAuth to authenticate users and retrieve account information required for authentication and identity association.

Data sent to GitHub:

* OAuth authorization requests.
* OAuth authorization code during the authentication flow.

Data received from GitHub may include:

* GitHub user identifier.
* Name.
* Username.
* Email address.

GitHub is contacted when a visitor chooses GitHub as their login provider.

Terms of Service: https://docs.github.com/en/site-policy/github-terms/github-terms-of-service
Privacy Statement: https://docs.github.com/en/site-policy/privacy-policies/github-general-privacy-statement

== Email Delivery ==

UnlockForge Email Unlock uses the WordPress mail delivery system to send verification emails.

UnlockForge does not require a specific email provider.

Site administrators can configure WordPress email delivery using an SMTP plugin or transactional email provider of their choice.

The configured email delivery provider may process:

* Recipient email address.
* Email subject.
* Email message.
* Verification code contained in the email.

The privacy policy and terms of the configured email delivery provider should be reviewed by the site administrator.

== Frequently Asked Questions ==

= Does UnlockForge support paid content? =

Not in the current version.

Payment-based content unlocking is planned for a future version.

= Does logging in automatically provide access to paid content? =

Payment-based access is not part of the current version.

Future versions are intended to keep authentication and content entitlement separate.

= Can visitors unlock content using email? =

Yes.

Email Unlock allows visitors to verify an email address using a temporary one-time verification code.

= Can I use Social Login and Email Unlock together? =

Yes.

Site administrators can enable and configure the authentication methods supported by their site.

= Can a WordPress user have multiple social-login providers? =

Yes.

UnlockForge is designed to allow multiple external identities to be associated with the same WordPress user.

= Can I protect both posts and pages? =

Yes.

UnlockForge supports protection for WordPress posts and pages.

= Can I show a preview instead of completely locking content? =

Yes.

Preview mode can display a configurable portion of the content before the visitor is required to unlock it.

= Can I customize the unlock message? =

Yes.

Unlock Messages support custom titles, messages, emoji, images, categories, and scheduling.

= Can I protect content in bulk? =

Yes.

Bulk Protection allows administrators to apply Disabled, Preview, or Full Lock protection to multiple posts and pages.

= Does UnlockForge require a specific email provider? =

No.

Email Unlock uses the WordPress mail system. Site administrators can configure their preferred SMTP or transactional email delivery solution.

== Planned / Future ==

Payment-based content unlocking is planned for a future version.

Future development may include:

* Payment-based content access.
* Per-content payment entitlement.
* Additional payment providers.
* "Pay once, see all" access.
* Additional access methods.
* Expanded analytics and event tracking.

Payment functionality is intentionally not included in the current version.

== Open Source ==

UnlockForge is being developed as an open-source WordPress plugin.

If you find UnlockForge useful, you can support its development by:

* Sharing feedback.
* Reporting issues.
* Suggesting improvements.
* Contributing code.
* Starring the project on GitHub.

== Changelog ==

= 0.3.0 =

* Added Email Unlock with one-time email verification codes.
* Added configurable OTP email subject and message.
* Added configurable OTP email placeholders.
* Added OTP expiration and temporary verification challenges.
* Added hashed OTP storage.
* Added browser-bound OTP verification.
* Added email-based OTP rate limiting.
* Added IP-based OTP rate limiting.
* Added improved authentication request validation.
* Improved OAuth security with browser-bound state validation.
* Improved privacy handling for stored identity information and analytics data.
* Added Email Unlock configuration and documentation.
* Improved authentication and content-unlock flows.

= 0.2.0 =

* Improved Preview Settings with clearer preview method controls and visual representations.
* Improved Bulk Protection with clearer content scope selection, protection mode guidance, and action summaries.
* Improved Social Login settings with a cleaner provider configuration interface and OAuth integration guidance.
* Improved Unlock Messages with an improved management interface.
* Improved admin interface styling, usability, and responsive layouts.
* Added basic guidance and visual improvements across plugin settings.

= 0.1.0 =

* Initial development release.
* Added content protection for posts and pages.
* Added Disabled, Preview, and Full Lock protection modes.
* Added social login support.
* Added Google, Facebook, X, LinkedIn, and GitHub OAuth providers.
* Added external identity management.
* Added Unlock Messages.
* Added Unlock Message scheduling and category targeting.
* Added configurable preview controls.
* Added bulk protection.
* Added analytics.
* Added About & Help documentation.
* Added RTL support.
* Added translation-ready strings.

== Upgrade Notice ==

= 0.3.0 =

* Added Email Unlock with OTP verification.
* Added OTP rate limiting and verification security improvements.
* Added browser-bound authentication protections.
* Improved OAuth and privacy security.