=== Kous Cash on Delivery Filter ===
Contributors: kouskouris
Donate link: https://www.paypal.com/donate/?hosted_button_id=VLPU3JJJKEVES
Tags: woocommerce, cash on delivery, cod, fraud prevention, blacklist
Requires at least: 6.4
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 1.1.5
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Restrict WooCommerce Cash on Delivery using email, international phone numbers, device fingerprints, and reference-only IP data.

== Description ==

Kous Cash on Delivery Filter helps store owners prevent repeat Cash on Delivery problems.

Main features:

* Block Cash on Delivery by exact email address.
* Block by normalized international phone number.
* Optional wildcard phone rules, such as `4477*`.
* Block by privacy-preserving SHA-256 device fingerprint.
* Store IP addresses for investigation and correlation without blocking by IP alone.
* Hide or restore Cash on Delivery instantly during checkout with AJAX.
* Add a customer's email, phone, IP address, and available device fingerprint from the WooCommerce order screen.
* Save the device fingerprint to new WooCommerce orders.
* Import and export blocklist entries as CSV.
* Export, clear, or delete individual attempt-history records.
* Search email and phone blocklists.
* Compatible with WooCommerce High-Performance Order Storage (HPOS).

= International phone handling =

Phone values are normalized without country-specific assumptions. Formatting characters are removed, and the international `00` access prefix is normalized so that `+44...` and `0044...` match.

To prevent accidental partial blocking:

* Exact phone entries must contain 6 to 15 digits.
* Wildcard phone entries must contain 4 to 15 digits.
* Phone matching is exact unless an administrator explicitly adds a wildcard.
* Substring matching is never used.

= IP address safety =

IP addresses are stored for reference, export, and investigation. An IP address never removes Cash on Delivery by itself. This avoids false positives on mobile networks, carrier-grade NAT, offices, hotels, and shared connections.

= Device fingerprints =

The plugin creates a browser/device signal and stores only its SHA-256 hash. New WooCommerce orders save the hash as order metadata when checkout provides it. Blocking an order can then add the saved device hash to the blocklist.

A device fingerprint is a probabilistic browser signal, not a guaranteed unique hardware identifier. Browser changes, privacy settings, or different browsers may produce a different hash.

== Installation ==

1. Upload the plugin ZIP through **Plugins > Add New > Upload Plugin**.
2. Activate **Kous Cash on Delivery Filter**.
3. Open **WooCommerce > Kous Cash on Delivery Filter**.
4. Add entries manually, import a CSV, or use the button on a WooCommerce order.

== Frequently Asked Questions ==

= Can an IP address block a customer by itself? =

No. IP addresses are stored only for reference and correlation.

= Why are very short phone entries rejected? =

To prevent partial values entered during typing, such as `697`, from becoming broad blocking rules. Exact international entries require 6-15 digits.

= Does the plugin support international numbers? =

Yes. It does not remove or assume a specific country code. `+` formatting and the `00` international prefix are normalized.

= Does it support HPOS? =

Yes. Order access and metadata use WooCommerce CRUD APIs, and HPOS compatibility is declared.

= Are device details stored in plain text? =

No. The browser signal is converted to a SHA-256 hash before storage.

== Privacy ==

Depending on configuration and use, this plugin can store:

* Customer email addresses.
* Customer phone numbers.
* IP addresses.
* Hashed browser/device fingerprints.
* User-agent strings in attempt history.

Store owners are responsible for providing appropriate privacy notices, determining a lawful basis, defining retention periods, and responding to data-subject requests under applicable laws.

== Changelog ==

= 1.1.5 =
* Replaced query-string admin notices with secure per-user transients.
* Documented WooCommerce checkout nonce verification for static analysis.
* Scoped uninstall variables inside a uniquely prefixed function.
* No blocking or checkout behavior changes.

= 1.1.4 =
* Removed the unnecessary manual text-domain loader.
* Improved checkout input sanitization without changing matching behavior.
* Added safe prepared identifier placeholders to custom-table queries.
* Prefixed uninstall variables to follow WordPress coding standards.

= 1.1.3 =
* Added checkout nonce validation and completed the security review fixes requested by the WordPress.org Plugin Review Team.

= 1.1.2 =
* Added explicit WooCommerce checkout nonce validation before processing checkout POST data that can write logs or update the device blocklist.
* Removed raw checkout POST reads from order creation and payment-gateway filtering; these paths now use normalized WooCommerce session/customer data.
* Removed database migration work from normal admin page rendering.

= 1.1.1 =
* Replaced direct CSV file handles with WordPress filesystem access.
* Replaced timezone-sensitive date() calls with gmdate().
* Updated CSV export generation without direct fopen()/fclose() calls.

= 1.1.0 =
* Added international-safe phone normalization and validation.
* Prevented storage and matching of clearly incomplete phone values.
* Removed substring phone matching.
* Changed IP addresses to reference-only data that cannot block by themselves.
* Added reliable device fingerprint persistence through WooCommerce checkout sessions and order metadata.
* Added device blocking from the WooCommerce order screen when a saved fingerprint is available.
* Added individual attempt-history deletion.
* Added device-copy controls in attempt history.
* Moved admin JavaScript and CSS to properly enqueued asset files.
* Declared WooCommerce HPOS compatibility.
* Updated documentation and privacy information.

= 1.0.0 =
* Initial release.
