# BodyCommerce Checkout Bot Defense - Implementation Plan

## Objective

Add low-friction checkout anti-bot protection to Divi BodyCommerce with:

1. Honeypot field + server validation
2. Minimum checkout time validation (configurable, e.g. block if `< 1s`)
3. Rate limiting + temporary lockouts (IP + email fingerprint)
4. Admin settings and user-friendly error messaging

This plan is split into small sessions so multiple agents can work in parallel safely.

---

## Constraints and architecture notes

- Canonical repo for this work: `divi-bodycommerce`.
- Keep UX friction low; do not force captcha/challenge for baseline.
- Time check must be server-side enforced (frontend signal can be bypassed).
- Follow existing BodyCommerce option patterns (`get_bodycommerce_option()`).
- Keep implementation modular so future Turnstile/Cloudflare challenge can be added as optional layer.

---

## Target files

- `divi-bodyshop-woocommerce.php` (bootstrap/load feature)
- `includes/core/woo-checkout.php` (checkout hooks + validation runtime)
- `includes/templates/woocommerce/checkout/form-checkout.php` (hidden fields in checkout form)
- `divi-bodycommerce-options.php` (admin settings UI/options schema)
- `functions.php` (option helper already exists, consume from runtime)
- `changelog.txt` (customer-facing changelog entry)

---

## Session breakdown

## Session 0 - Discovery + alignment (Required first)

**Goal**
- Confirm exact hook points in current checkout flow and avoid regressions with custom checkout styles.

**Tasks**
- Map checkout rendering path and confirm BodyCommerce template override is active.
- Identify best hook for server validation: `woocommerce_checkout_process` and/or `woocommerce_after_checkout_validation`.
- Confirm where to store transient keys and lockout metadata.

**Deliverable**
- Short note in PR description (or internal log) confirming exact hooks and execution order.

**Parallel?**
- No (foundation for all sessions).

---

## Session 1 - Settings contract (can start after Session 0)

**Goal**
- Define and register all settings required by runtime logic.

**Settings to add**
- `spam_protection_enabled` (on/off)
- `spam_honeypot_enabled` (on/off)
- `spam_min_time_enabled` (on/off)
- `spam_min_checkout_seconds` (int, default `1`)
- `spam_rate_limit_enabled` (on/off)
- `spam_rate_limit_attempts` (int, e.g. `5`)
- `spam_rate_limit_window_seconds` (int, e.g. `300`)
- `spam_lockout_minutes` (int, e.g. `15`)
- `spam_block_message` (text)

**Files**
- `divi-bodycommerce-options.php`

**Deliverable**
- Settings fields appear in admin and persist correctly.

**Parallel?**
- Yes, with Session 2 and Session 3 (minimal conflict risk if agents avoid same file edits at same time; otherwise serialize merges).

---

## Session 2 - Honeypot + render timestamp fields (can start after Session 0)

**Goal**
- Inject hidden anti-bot fields into checkout form.

**Tasks**
- Add hidden honeypot input field.
- Add hidden render-time field (Unix timestamp).
- Optional nonce/context field if needed for integrity.
- Keep field names clearly namespaced (e.g. `debc_spam_*`).

**Files**
- `includes/templates/woocommerce/checkout/form-checkout.php`

**Deliverable**
- Checkout HTML includes anti-bot hidden inputs.

**Parallel?**
- Yes, with Session 1 and Session 3.

---

## Session 3 - Server-side validators (can start after Session 0)

**Goal**
- Enforce honeypot + minimum time checks during checkout processing.

**Tasks**
- Add validation method(s) in checkout runtime:
  - If honeypot field is non-empty -> block.
  - If min-time enabled and `now - render_time < threshold` -> block.
- Return customer-safe WooCommerce notices.
- Ensure validation executes before order creation.

**Files**
- `includes/core/woo-checkout.php`

**Deliverable**
- Fast bot-style submissions and honeypot hits are blocked server-side.

**Parallel?**
- Yes, with Session 1 and Session 2 (merge carefully).

---

## Session 4 - Rate limit + lockout engine (after Session 3 baseline validation)

**Goal**
- Add transient-backed abuse throttling and temporary lockouts.

**Tasks**
- Build key strategy:
  - IP key
  - email fingerprint key (if email present)
  - optional combined key
- Increment attempts in sliding/fixed window.
- On threshold breach, set lockout transient for configured minutes.
- Check lockout before allowing checkout process.
- Reuse unified helper methods to keep logic testable.

**Files**
- `includes/core/woo-checkout.php` (or dedicated include if refactoring is cleaner)

**Deliverable**
- Repeated abusive attempts are throttled and temporarily blocked.

**Parallel?**
- Partially parallel with Session 5 (tests can be prepared), but implementation should follow Session 3 hooks.

---

## Session 5 - QA/test matrix + hardening (after Sessions 1-4)

**Goal**
- Validate all functional paths and prevent UX regressions.

**Test matrix**
- Guest checkout valid flow.
- Logged-in checkout valid flow.
- Honeypot filled -> blocked.
- Submit too fast (< threshold) -> blocked.
- Normal speed submit (> threshold) -> allowed.
- Repeated attempts exceed threshold -> lockout message shown.
- Lockout expires -> checkout works again.
- Works with BodyCommerce checkout styles/layout variants.

**Deliverable**
- Test notes with pass/fail list and any edge-case fixes.

**Parallel?**
- Can run in parallel with Session 6 documentation/changelog once core code is stable.

---

## Session 6 - Changelog + rollout notes

**Goal**
- Provide user-facing release notes.

**Tasks**
- Add concise customer-facing entries in `changelog.txt`:
  - new checkout spam protection
  - minimum checkout time guard
  - temporary lockout behavior

**Deliverable**
- Changelog updated in required format.

**Parallel?**
- Yes, after scope is finalized.

---

## Parallelization map

| Session | Can run in parallel with | Notes |
|---|---|---|
| 0 | None | Must run first |
| 1 | 2, 3 | Avoid same-file merge conflicts |
| 2 | 1, 3 | Template-only change |
| 3 | 1, 2 | Core runtime hooks |
| 4 | 5 (prep only) | Should build on Session 3 |
| 5 | 6 | QA + docs can overlap |
| 6 | 5 | After feature set is locked |

---

## Suggested agent assignment

### Agent A - Settings
- Own Session 1.
- Output: setting IDs, defaults, and screenshots/snippets.

### Agent B - Form fields
- Own Session 2.
- Output: hidden field names and render snippet.

### Agent C - Validation core
- Own Session 3.
- Output: hook names + validation function summary.

### Agent D - Rate limiting
- Own Session 4.
- Output: transient key format + lockout logic summary.

### Agent E - QA + changelog
- Own Sessions 5 and 6.
- Output: test matrix results and changelog text.

---

## Integration order for you (lead reviewer)

1. Merge Session 1 + Session 2 + Session 3 outputs.
2. Merge Session 4 on top.
3. Run Session 5 full QA.
4. Apply Session 6 changelog.
5. Final review pass: security + UX + backward compatibility.

---

## Review checklist (when agents finish)

- No validation bypass if JS disabled.
- No fatal errors when settings are missing/unset.
- Default config is safe and low-friction.
- Notices are user-friendly and non-technical.
- No leakage of internal lockout heuristics in messages.
- No impact on legitimate normal-speed checkout.
- Changelog entry is customer-facing (non-technical wording).

---

## Optional phase 2 (not in baseline)

- Optional Turnstile/Cloudflare challenge toggle.
- Admin analytics for blocked attempts.
- Per-country/per-user-role thresholds.