WebMe Carding Shield Documentation

    V1 Plan

    Documentation for WebMe Carding Shield.

    WebMe Carding Shield V1 Plan

    Goal

    Build a narrow WooCommerce checkout abuse shield that reduces card-testing, fake checkout, and failed/draft order floods by evaluating local risk before order/payment damage wherever WooCommerce allows it.

    Scope

    • Local-only detection by default.
    • Store API checkout protection and rate-limit fingerprinting.
    • Classic shortcode checkout validation.
    • Velocity counters by IP, email hash, and lightweight request fingerprint.
    • Configurable actions: block, hold/manual review, monitor.
    • HPOS-compatible order metadata for risk score, level, triggered rules, and decision.
    • Dedicated event table for compact checkout-abuse events.
    • Admin settings, incident log, and order risk display.

    Non-goals

    • Broad anti-fraud platform.
    • Payment gateway orchestration.
    • External fraud API dependency.
    • CAPTCHA replacement for every WordPress form.
    • Chargeback management.
    • CRM, ERP, accounting, or tax record cleanup.
    • Global shared threat-intelligence network.
    • Automatic deletion of failed or draft orders.

    Target user / buyer

    WooCommerce operators and agencies supporting stores that receive card-testing attempts, fake orders, failed order floods, Store API abuse, gateway decline-ratio risk, or inventory holds caused by automated checkout submissions.

    Product wedge

    Block or slow suspicious WooCommerce checkout submissions before they create order clutter or hit the payment processor. Keep all checks local, fast, explainable, and easy to disable per rule.

    Existing WebMe overlap

    • Existing plugin overlap: none found in this repository.
    • Adjacent plugins: none found locally.
    • Reuse/shared code opportunities: WebMe admin shell, settings model, plugin metadata, docs manifests, updater bootstrap, test/security/release workflows.
    • Must not duplicate: Carticy Checkout Shield browser-session proof, generic blacklist managers, cloud anti-fraud APIs, large rule-weight suites.

    Market evidence

    Key user stories

    • As a store owner, I want checkout bots blocked before failed orders are created so my orders screen and database stay usable.
    • As an agency, I want a local, explainable shield I can install quickly during an attack without handing customer data to another service.
    • As a store owner, I want risky attempts logged compactly so I can see what was blocked without storing raw sensitive data.
    • As an operator, I want suspicious but not certain orders marked for review instead of silently blocked.
    • As a developer, I want Store API protection that works with Checkout Blocks and does not disable legitimate Store API usage.

    Functional requirements

    • Activation creates a compact custom event table with indexed timestamp, IP hash/plain normalized IP as appropriate, email hash, fingerprint hash, event type, decision, score, and rule IDs.
    • Uninstall cleanup is explicit and opt-in.
    • Store API rate limiting integrates with WooCommerce filters for checkout endpoint limits and rate-limit identity.
    • Classic checkout validates via WooCommerce checkout validation hooks before order creation where possible.
    • Rules include IP velocity, email hash velocity, failed-attempt velocity, low-value repeated attempts, suspicious missing headers, impossible country mismatch when data is locally available, disposable-looking email/domain patterns, and repeated carding-like checkout cadence.
    • Rules produce a deterministic risk score and explainable triggered rule list.
    • Decisions support block, hold/manual review, monitor, and bypass.
    • Admin settings expose presets: Conservative, Balanced, Aggressive, Monitoring only.
    • Trusted bypasses support user roles, user IDs, email/domain allowlist, IP allowlist, and payment method allowlist where safely known.
    • Order metadata stores risk score, risk level, triggered rules, decision, and plugin version using HPOS-compatible CRUD methods.
    • Admin order screen shows a compact risk panel.
    • Incident log supports filtering by date, decision, rule, IP hash/fingerprint hash, and email hash.
    • No raw card data is read, stored, logged, or displayed.
    • No external service call is required for core protection.

    Technical approach

    • Create plugins/webme-carding-shield/ as the plugin root.
    • Bootstrap services through a small dependency container or service registry consistent with existing WebMe conventions after project normalization.
    • Use WooCommerce feature detection before registering checkout hooks.
    • Store API:
      • Use woocommerce_store_api_rate_limit_options for checkout-specific throttling defaults.
      • Use woocommerce_store_api_rate_limit_id for a local fingerprint composed from normalized IP, user agent, accept language, and safe request traits.
      • Add server-side request validation at the earliest stable WooCommerce Store API checkout hook available in the installed version.
      • Use woocommerce_store_api_checkout_order_processed only for order annotation/hold flows after an order exists.
    • Classic checkout:
      • Use woocommerce_after_checkout_validation for pre-order validation.
      • Add generic, sanitized customer-facing errors.
    • Data:
      • Dedicated table for events and velocity windows.
      • HPOS-compatible order meta through WC_Order CRUD.
      • Use one-way hashing for email and request fingerprints.
    • Admin:
      • Settings under WooCommerce or WebMe menu.
      • Use nonces, capabilities, sanitization, and escaping for every admin action.
    • Privacy:
      • Add clear local-only privacy notes in docs.
      • Avoid raw request-body logging.

    Files likely involved

    • .webme/plugin.json
    • .webme/sync-state.json
    • docs/shared/docs-manifest.json
    • docs/shared/release-artifacts.json
    • docs/shared/rollout-status.md
    • plugins/webme-carding-shield/webme-carding-shield.php
    • plugins/webme-carding-shield/includes/Plugin.php
    • plugins/webme-carding-shield/includes/Checkout/StoreApiProtection.php
    • plugins/webme-carding-shield/includes/Checkout/ClassicCheckoutProtection.php
    • plugins/webme-carding-shield/includes/Risk/RiskEngine.php
    • plugins/webme-carding-shield/includes/Risk/Rules/*
    • plugins/webme-carding-shield/includes/Storage/EventRepository.php
    • plugins/webme-carding-shield/includes/Storage/Installer.php
    • plugins/webme-carding-shield/includes/Admin/SettingsPage.php
    • plugins/webme-carding-shield/includes/Admin/IncidentLogPage.php
    • plugins/webme-carding-shield/includes/Admin/OrderRiskPanel.php
    • plugins/webme-carding-shield/tests/*

    Phase breakdown

    1. Project normalization
      • Run webme-plugin-orchestrator.
      • Run webme-project-normalizer.
      • Create canonical metadata and shared docs files.
    2. Plugin scaffold
      • Add main plugin file, service bootstrap, activation/deactivation handlers, and WooCommerce guards.
      • Add settings defaults and preset model.
    3. Storage
      • Add event table installer/migrator.
      • Add repository with indexed velocity queries and retention cleanup.
    4. Risk engine
      • Implement deterministic rule contracts, score aggregation, and decision policy.
      • Add initial V1 rules and bypass handling.
    5. Checkout integration
      • Add Store API rate-limit options/identity.
      • Add Store API validation and processed-order annotation/hold handling.
      • Add classic checkout validation.
    6. Admin UI
      • Add settings page, incident log, and order risk panel.
      • Add privacy/export/delete notes if required by WordPress privacy tools.
    7. Tests and security
      • Run webme-test-builder.
      • Add unit/integration coverage for rules, storage, settings sanitization, capabilities, and checkout decisions.
      • Run webme-security-auditor and fix blocker/high findings.
    8. Product/release
      • Run webme-info-pack.
      • Run webme-updater-integrator after stable product/store identity exists.
      • Run webme-release-manager.
      • Run webme-docs-sync.
      • Run webme-website-publisher only after explicit approval and target config.

    Validation

    • PHPUnit tests for risk scoring, rule thresholds, bypasses, event repository, settings sanitization, and retention cleanup.
    • WooCommerce integration tests for classic checkout block/allow/hold decisions.
    • Store API tests for checkout request validation, rate-limit identity generation, and order annotation.
    • HPOS compatibility smoke test.
    • Manual checkout smoke tests:
      • normal guest checkout allowed
      • repeated low-value attempts blocked/throttled
      • monitor mode logs without blocking
      • hold mode creates order with risk metadata
      • allowlisted role bypasses rules
    • Security validation:
      • nonces and capabilities on admin screens
      • SQL prepared statements
      • no raw card data or raw request body logging
      • escaped admin output
      • sanitized settings and filters

    Risks

    • False positives can block legitimate buyers during high-traffic events.
    • Store API hook surfaces vary by WooCommerce version; version guards and tests are required.
    • Proxy/CDN IP handling can block real customers if configured incorrectly.
    • Aggressive logging can create the same database bloat the plugin is meant to prevent.
    • Competitor saturation is rising; positioning must stay narrow and operational.
    • Payment-gateway-specific behavior cannot be promised in V1.

    Pricing

    • Recommendation: paid annual premium launch.
    • Launch tiers: Single Site $59/year; Agency 5-Site $149/year.
    • Free tier: none for V1 launch. A monitoring-only or basic rate-limit edition can be considered later if acquisition strategy needs it.
    • Rationale: recurring value is high because checkout abuse and gateway health are ongoing operational risks. Annual pricing matches WooCommerce Marketplace buyer expectations and funds compatibility/security maintenance. Avoid monthly SaaS positioning because the V1 value is local-first and low-friction.

    WebMe skill routing

    • Start lifecycle with webme-plugin-orchestrator; update docs/shared/rollout-status.md.
    • Run webme-project-normalizer before implementation.
    • Run webme-test-builder after implementation surfaces exist.
    • Run webme-security-auditor before release; block active blocker/high findings unless fixed or explicitly waived with expiry.
    • Run webme-info-pack before product/release handoff.
    • Run webme-updater-integrator after stable slug, main file, version, and store identity exist.
    • Run webme-release-manager after tests/security pass.
    • Run webme-docs-sync after info pack/docs are ready.
    • Run webme-website-publisher only after release artifacts exist and publishing approval/target config are present.

    WebMe Lifecycle Completion Checklist

    • webme-plugin-orchestrator run and docs/shared/rollout-status.md updated
    • webme-project-normalizer run successfully
    • .webme/plugin.json canonical and uses webme-* slug
    • docs/shared/docs-manifest.json canonical
    • docs/shared/release-artifacts.json canonical
    • Plugin implemented under plugins/webme-carding-shield/
    • webme-test-builder inventory written
    • Targeted tests created
    • Tests run, or blocked with exact reason
    • webme-security-auditor run
    • Active blocker/high findings fixed or waived with expiry and reason
    • webme-info-pack generated/refreshed
    • webme-updater-integrator run or blocked with exact store/product reason
    • webme-release-manager run and release zip/metadata generated
    • webme-docs-sync run or blocked with exact reason
    • webme-website-publisher run or blocked pending approval/target config
    • Plan updated with implementation notes, validation, pricing, and residual risk

    Acceptance criteria

    • V1 blocks or throttles suspicious checkout abuse before order creation where WooCommerce hooks allow.
    • V1 never stores raw card data and does not send order/customer data to external services.
    • V1 supports Checkout Blocks/Store API and classic checkout.
    • V1 stores persistent order risk metadata through HPOS-compatible order CRUD.
    • V1 has focused tests and documented manual smoke coverage.
    • V1 has no active blocker/high security findings before release unless a dated waiver is explicitly accepted.
    • Release, docs, updater, and publishing lifecycle gates are either complete or blocked with exact reasons.

    Implementation notes

    2026-05-21 milestone: scaffold through targeted tests

    • Project normalized with .webme/plugin.json, .webme/sync-state.json, and shared docs/release manifests.
    • Plugin scaffold added under plugins/webme-carding-shield/ with activation table install, WooCommerce guard, local risk engine, velocity rules, Store API integration, classic checkout validation, admin settings, incident log, order risk panel, and opt-in uninstall cleanup.
    • Store API integration uses WooCommerce rate-limit filters and woocommerce_store_api_checkout_update_customer_from_request so block decisions happen before draft/order creation in the normal POST checkout flow. Blocking uses WooCommerce Store API RouteException when available, with a generic exception fallback.
    • Event logging stores compact hashed identifiers and rule IDs; raw card data and raw request bodies are not logged.
    • Test-builder inventory written to tests/.webme-test-inventory.json; targeted local harness added at tests/run.php.
    • Validation run: php tests/run.php passed 4 tests; PHP syntax validation passed for all plugin/test PHP files.
    • Known validation gap: full WooCommerce Store API, HPOS, and admin capability integration tests need a WordPress/WooCommerce test bootstrap that is not present in this repo.

    2026-05-21 milestone: lifecycle gates and release artifact

    • Security auditor run. Initial medium review on uninstall table drop was patched to use a prepared identifier. Rerun reported no active findings.
    • Info pack generated under docs/info-pack/, including product info, user docs, developer docs, technical specs, pricing/positioning, release readiness, site payload, media prompts, blog ideas, and SVG placeholder assets.
    • Updater integration is blocked because no real store URL, product identity, or license/update endpoint contract exists. Added .webme/updater.example.json with exact blocked reason.
    • Standard release contract installed with release-manifest.json and scripts/*.
    • Release ZIP generated at build/releases/webme-carding-shield-0.1.0.zip; size 16833; SHA-256 558bded3912b3f42685863edde1a4dc1f8f182e73f0eea5ee13b78330855b60d.
    • A compatibility copy is also written to releases/webme-carding-shield-0.1.0.zip with the same checksum.
    • Release metadata written to build/releases/webme-carding-shield-0.1.0.json, docs/shared/release-artifacts.json, and docs/info-pack/site-payload.json.
    • Docs sync is blocked because no website target config exists and external website writes require approval. See docs/shared/docs-sync-status.md.
    • Website/store publishing is blocked pending explicit approval, target config, and store product identity. Pricing confirmation is now resolved. See docs/shared/website-publishing-status.md.

    2026-05-23 milestone: launch pricing confirmed

    • Launch pricing set to Single Site $59/year and Agency 5-Site $149/year.
    • V1 launch remains paid-only because the codebase has no feature gating and the product value is incident-response checkout protection, not a freemium utility.
    • Updated info-pack pricing, release readiness, site payload, WebMe integration brief, inventory, website publishing status, and website product-page pricing handoff.
    • Remaining commercial blockers are store product identity, updater/license records, and final publishing approval.

    2026-05-22 milestone: active website directory integration and screenshot assets

    • Website integration was promoted from hidden draft onboarding to active catalog visibility in /home/vas/sites/node/wooamigos-ecommerce-forge.
    • src/data/plugins.ts now marks webme-carding-shield as an active premium plugin and flags it for the premium directory.
    • scripts/seo-routes.mjs now includes /plugins/webme-carding-shield, so the product page is prerendered and included in dist/sitemap.xml.
    • The product page no longer carries the temporary noindex setting.
    • The three In Action SVGs were replaced with static WordPress/WooCommerce-admin-style screenshots: protection settings, Store API fingerprinting, and the risk log.
    • The improved SVGs were synced to both the website repo and docs/info-pack/imgs/.
    • Validation run: npm run build passed in the website repo; generated /plugins, /plugins/premium, /plugins/webme-carding-shield, and dist/sitemap.xml include webme-carding-shield.
    • npm run lint still fails on pre-existing website lint errors in src/components/ui/command.tsx, src/components/ui/textarea.tsx, src/lib/shortcodes.tsx, and tailwind.config.ts; no lint failures were reported in the Carding Shield files.

    2026-05-22 milestone: Admin Shot Lab concept-first In Action assets

    • Admin Shot Lab rendered concept-first WebP product visuals for Carding Shield at 1200x750.
    • Product-page mockups now use:
      • webme-carding-shield-blocked-before-payment.webp
      • webme-carding-shield-why-blocked.webp
      • webme-carding-shield-tune-safely.webp
    • The visual set now follows an action/reason/control arc:
      • suspicious checkout blocked before payment
      • rule trail explains why it was blocked
      • protection can be tuned with last-24h impact context
    • The previous SVG-style In Action assets remain in the repo but are no longer used by the product page.
    • Follow-up correction: the first concept renders mixed too much explanatory copy into the image and lost detail at product-page thumbnail size. Admin Shot Lab specs/CSS were adjusted for spotlight thumbnail rendering: less internal copy, hidden fine-print descriptions, larger focal decisions/metrics, and no duplicated explanatory prose inside the visual.
    • Follow-up correction: Why It Was Blocked initially duplicated the Blocked Before Payment visual because both centered the same Blocked decision card. Admin Shot Lab now supports a rule-first rule-outcome-map variant, and the asset was regenerated with the rule trail as the dominant visual.

    2026-05-22 milestone: Admin Shot Lab set-first refresh

    • Re-read the upgraded Admin Shot Lab README and used the reusable set workflow instead of one-off screenshot specs.
    • Regenerated the three Carding Shield In Action assets from /home/vas/sites/node/admin-shot-lab/examples/webme-carding-shield/in-action-set.json.
    • The refreshed set uses distinct compositions for the small website cards:
      • action: signal stack plus large blocked decision before payment contact
      • evidence: rule trail plus attempt details and audit state
      • control: impact metrics plus protection controls
    • Synced regenerated WebP assets into both the website repo and docs/info-pack/imgs/.
    • Admin Shot Lab render CSS was tuned so freeform/set-first shots keep badges visible, hide low-value fine print, enlarge focal UI states, and reduce duplicated sales-copy-like text inside the screenshots.
    • Validation run: Admin Shot Lab npm run build passed, Admin Shot Lab npm run validate:set -- examples/webme-carding-shield/in-action-set.json passed, Admin Shot Lab npm test passed, and website npm run build passed.

    2026-05-22 milestone: concept-template renderer refresh

    • Re-read the latest Admin Shot Lab README after the concept-template upgrade.
    • Regenerated the Carding Shield In Action WebP assets through the upgraded set renderer output at /home/vas/sites/node/admin-shot-lab/output/webme-carding-shield/concept-template-run/.
    • The current source set already includes concept templates:
      • checkout-intercept for the action shot
      • rule-explainer for the evidence shot
      • safe-tuning for the control shot
    • Because FreeformGrid now routes set shots with conceptTemplate into ConceptTemplateRenderer, the render uses the purpose-built concept compositions instead of the older generic block grid.
    • Synced the regenerated WebP files into both /home/vas/sites/node/wooamigos-ecommerce-forge/public/plugin-screenshots/ and docs/info-pack/imgs/.
    • Attempted a fresh direct agy:plugin-set candidate, but the returned JSON used loose/legacy field names and failed the strict set schema. The synced assets therefore came from the existing valid set file rendered through the upgraded concept-template path.
    • Validation run: Admin Shot Lab npm run validate:set -- examples/webme-carding-shield/in-action-set.json passed, Admin Shot Lab npm run lint:set -- examples/webme-carding-shield/in-action-set.json passed, Admin Shot Lab npm run build passed, Admin Shot Lab npm test passed, and website npm run build passed.

    2026-05-22 milestone: blocked-before-payment replacement

    • Replaced only webme-carding-shield-blocked-before-payment.webp; the why-blocked and tune-safely assets were left unchanged.
    • The action shot source was changed from checkout-intercept to attack-cluster so the concept is centered on repeated checkout attempts from one fingerprint and a blocked/payment-not-sent verdict.
    • Synced the replacement WebP into both the website repo and docs/info-pack/imgs/.
    • Validation run: Admin Shot Lab npm run validate:set -- examples/webme-carding-shield/in-action-set.json passed, Admin Shot Lab npm run lint:set -- examples/webme-carding-shield/in-action-set.json passed, Admin Shot Lab npm run build passed, and website npm run build passed.

    2026-05-22 milestone: skeleton/atom action candidate refresh

    • Re-read the updated Admin Shot Lab README after the skeleton/atom scene-composer upgrade.
    • Ran the new multi-candidate workflow with npm run agy:plugin-set -- ... --out output/webme-carding-shield/skeleton-candidates --candidates 6.
    • Candidate-generation result: 1 candidate validated against the strict set schema; 5 candidates failed and wrote debug captures.
    • Used only the valid candidate's action shot, keeping the existing evidence and control shots unchanged.
    • The accepted action shot uses a focused-modal skeleton with a Store API checkout-attempt table behind a dominant blocked/gateway-untouched modal state.
    • Synced only webme-carding-shield-blocked-before-payment.webp into both the website repo and docs/info-pack/imgs/.
    • Updated Admin Shot Lab tests to match the current focused-modal action skeleton and lowered the freeform smoke-test byte-size threshold from 20_000 to 15_000 because the simpler WebP render is still non-empty but smaller.
    • Validation run: Admin Shot Lab npm run validate:set -- examples/webme-carding-shield/in-action-set.json passed, Admin Shot Lab npm run lint:set -- examples/webme-carding-shield/in-action-set.json passed, Admin Shot Lab npm run build passed, Admin Shot Lab npm test passed, and website npm run build passed.

    2026-05-22 milestone: admin-interface-centric In Action redo

    • Re-read the updated Admin Shot Lab README and prompt guidance after the utility shifted back toward fuller admin-interface compositions.
    • Regenerated all three Carding Shield In Action WebP assets from the block-based set source at /home/vas/sites/node/admin-shot-lab/examples/webme-carding-shield/in-action-set.json.
    • The current source set uses WooCommerce/admin block compositions rather than skeleton atoms:
      • action: center-hero with signal stack, large blocked decision, and outcome strip
      • evidence: left-hero with rule trail, attempt detail, and native notice
      • control: top-metrics with impact counters and protection controls
    • Synced rendered outputs from /home/vas/sites/node/admin-shot-lab/output/webme-carding-shield/admin-centric-redo/ into both the website repo and docs/info-pack/imgs/.
    • Validation run: Admin Shot Lab npm run validate:set -- examples/webme-carding-shield/in-action-set.json passed, Admin Shot Lab npm run lint:set -- examples/webme-carding-shield/in-action-set.json passed, Admin Shot Lab npm run build passed, Admin Shot Lab npm test passed, and website npm run build passed.

    2026-05-23 milestone: strict single-shot admin In Action redo

    • Re-read the latest Admin Shot Lab README after the utility moved back toward the stricter admin-first workflow.
    • Regenerated all three Carding Shield In Action WebP assets from the current recommended single-shot admin specs rather than the optional set workflow:
      • /home/vas/sites/node/admin-shot-lab/examples/webme-carding-shield/blocked-before-payment.json
      • /home/vas/sites/node/admin-shot-lab/examples/webme-carding-shield/why-blocked.json
      • /home/vas/sites/node/admin-shot-lab/examples/webme-carding-shield/tune-safely.json
    • Rendered outputs to /home/vas/sites/node/admin-shot-lab/output/webme-carding-shield/strict-admin-redo/.
    • Synced the three rendered WebP assets into both /home/vas/sites/node/wooamigos-ecommerce-forge/public/plugin-screenshots/ and docs/info-pack/imgs/.
    • Validation run: all three specs passed Admin Shot Lab npm run validate and npm run lint:spec; Admin Shot Lab npm run build passed; Admin Shot Lab npm test passed; website npm run build passed.

    2026-05-23 milestone: metadata/visible UI label separation

    • Updated Admin Shot Lab so product-page metadata no longer has to be rendered as screenshot UI:
      • title, description, promise, and set adjacentCopyIntent are treated as planning/product-page context.
      • screenTitle, visibleHeader, and visibleSubheader are used for operational screenshot UI labels.
    • Updated Admin Shot Lab header rendering so PageHeader and ConceptHeader prefer visibleHeader / screenTitle and only render visibleSubheader when explicitly provided.
    • Added lint warnings for visible UI text that too closely repeats metadata, plus warnings when specs/sets omit screenTitle or visibleHeader.
    • Updated prompts and README to tell agents not to reuse marketing headlines or promises inside screenshots.
    • Updated Carding Shield specs so rendered admin labels are operational:
      • Checkout Risk Log
      • Rule Evaluation
      • Protection Settings
    • Updated the Why It Was Blocked spec to use rule-trail-first composition so it is less visually redundant with the blocked decision shot.
    • Regenerated all three WebP assets to /home/vas/sites/node/admin-shot-lab/output/webme-carding-shield/metadata-separated-redo/ and synced them into both the website repo and docs/info-pack/imgs/.
    • Validation run: all three updated specs passed Admin Shot Lab npm run validate; all three passed npm run lint:spec; the Carding Shield set passed npm run lint:set; Admin Shot Lab npm run build passed; Admin Shot Lab npm test passed; website npm run build passed.