fluentcart-developer 2.0.2 → 2.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,304 +0,0 @@
1
- # Trial Abuse Prevention & Device Tracking (FluentCart Pro)
2
-
3
- How to make a free trial one-per-machine instead of one-per-email, and how to keep a license key from being shared mid-trial.
4
-
5
- This reference assumes the **Fastr Devices for FluentCart** add-on (v1.3.0+) is installed alongside FluentCart Pro. It is the device layer that FluentCart itself does not ship.
6
-
7
- ---
8
-
9
- ## 1. Why FluentCart trials leak
10
-
11
- FluentCart's native trial is **account-scoped**:
12
-
13
- | Mechanism | Where it lives |
14
- |---|---|
15
- | Trial length | `fct_product_variations.other_info.trial_days` |
16
- | Trial state | `fct_subscriptions.status = 'trialing'` (`Status::SUBSCRIPTION_TRIALING`) |
17
- | License expiry | `LicenseHelper::getExpirationDateByVariation()` — a trial *replaces* the first billing cycle |
18
-
19
- Nothing in that chain knows about the computer. Create a second account, buy the trial variation again, get a second trial. On a desktop app or Chrome extension, that is the whole abuse story.
20
-
21
- The fix is a **machine registry** that outlives the license, the order, and the customer.
22
-
23
- ---
24
-
25
- ## 2. The three gates
26
-
27
- | Gate | Hook | Stops |
28
- |---|---|---|
29
- | **Eligibility** | `fluent_cart_action_fastr_trial_eligibility` (pre-checkout) | Customer reaching payment before learning they already had a trial |
30
- | **Activation** | `fluent_cart/license/activate_license_response` (priority 20) | Second trial from a new account on the same machine |
31
- | **Heartbeat** | `fluent_cart/license/check_license_response` (priority 20) | Copying a key to another machine mid-trial |
32
-
33
- Priority 20 matters: `Fastr_Device_Repository::on_activate()` runs at 10 and has already written `site.other` by then.
34
-
35
- ### Failing open is deliberate
36
-
37
- Every gate returns early when the registry table is missing, when the license is not a trial, or when a legacy client sends no fingerprint. **A schema upgrade must never break a paying customer.**
38
-
39
- ---
40
-
41
- ## 3. Registry schema
42
-
43
- Table: `{$wpdb->prefix}fastr_trial_registry`
44
-
45
- | Column | Type | Notes |
46
- |---|---|---|
47
- | `id` | BIGINT UNSIGNED PK | |
48
- | `fingerprint_hash` | CHAR(64) | `hash_hmac('sha256', $raw, wp_salt('auth'))` |
49
- | `fingerprint_algo` | VARCHAR(16) | `v1` |
50
- | `product_id` | BIGINT UNSIGNED | 0 in global scope |
51
- | `scope_key` | BIGINT UNSIGNED | `product_id`, or `0` for global |
52
- | `first_license_id` | BIGINT UNSIGNED | Owner of the claim |
53
- | `first_customer_id` | BIGINT UNSIGNED | |
54
- | `first_order_id` | BIGINT UNSIGNED | |
55
- | `first_seen_at` / `last_seen_at` | DATETIME | GMT |
56
- | `last_ip_hash` | CHAR(64) | Hashed, never the raw address |
57
- | `ip_prefix` | VARCHAR(64) | `/24` or `/64`, for collision scoring |
58
- | `country` | CHAR(2) | |
59
- | `email_hash` | CHAR(64) | Normalized email hash |
60
- | `risk_score` | TINYINT UNSIGNED | 0–100 |
61
- | `risk_flags` | VARCHAR(191) | Comma-separated |
62
- | `status` | VARCHAR(20) | `trialed`, `reset` |
63
- | `reset_by` / `reset_at` | | Support reset audit |
64
- | `notes` | TEXT | e.g. `virtual_environment:VMware` |
65
-
66
- **Unique key:** `(fingerprint_hash, scope_key)`.
67
-
68
- `scope_key` exists because MySQL treats every `NULL` in a UNIQUE index as distinct — a nullable `product_id` would never enforce "one trial per machine" in global scope. Never make the unique column nullable.
69
-
70
- **Scope** is per product by default:
71
-
72
- ```php
73
- add_filter('fastr_trial/scope', fn() => 'global'); // one trial across the catalogue
74
- ```
75
-
76
- ### Why not `fct_license_sites.other`
77
-
78
- `site.other` dies with the site row. Deleting the license, the order, or the customer must not erase the fact that a machine consumed a trial. The registry is independent for exactly that reason.
79
-
80
- ---
81
-
82
- ## 4. Fingerprints
83
-
84
- ### Tier A — desktop (Tauri/Rust, Python, C++/VST)
85
-
86
- Collect and normalize, then join with `|`:
87
-
88
- | Component | Windows | macOS | Linux |
89
- |---|---|---|---|
90
- | Machine ID | `HKLM\SOFTWARE\Microsoft\Cryptography\MachineGuid` | `IOPlatformUUID` (`ioreg`) | `/etc/machine-id` |
91
- | Hardware UUID | SMBIOS `Win32_ComputerSystemProduct.UUID` | hardware serial | `/sys/class/dmi/id/product_uuid` |
92
- | Disk serial | `GetVolumeInformation` for `C:` | `diskutil info` | `lsblk -no SERIAL` |
93
- | CPU | brand string | `sysctl machdep.cpu.brand_string` | `/proc/cpuinfo` model name |
94
-
95
- Prefix with `v1|`, uppercase, strip whitespace runs, sort keys.
96
-
97
- **Stability contract:** must survive app updates, OS point updates, IP changes, and added hardware. May change on OS reinstall or disk replacement — that is a support reset, not abuse.
98
-
99
- **Persistence:** write the computed value to three places and require two to agree — OS keyring, app config file, and (Windows) `HKCU\Software\<App>`. Deleting one does not reset identity.
100
-
101
- **Never use the MAC address.** VPNs, docks, and randomisation break it.
102
-
103
- ### Tier B — Python/CLI
104
-
105
- Same sources; `winreg` on Windows, `/etc/machine-id` on Linux, `ioreg` via subprocess on macOS.
106
-
107
- ### Tier C — Chrome extension (weak by nature)
108
-
109
- `chrome.storage.local` install UUID + `chrome.runtime.id` + `navigator.hardwareConcurrency` + timezone + screen size.
110
-
111
- A user can clear extension storage in five seconds. **Do not claim device binding for browser trials.** Lean on account signals: normalized email, Paddle payment instrument, IP subnet.
112
-
113
- ### Virtual machines
114
-
115
- Cloned VMs share a fingerprint; fresh VMs do not. The add-on accepts `is_virtual` and `virtualization` and records them in `notes` and `site.other.environment`. It **never blocks** on them — otherwise every corporate VDI user is locked out. Review them manually.
116
-
117
- ---
118
-
119
- ## 5. Client contract
120
-
121
- ### 5a. Eligibility (before checkout)
122
-
123
- ```http
124
- POST /?fluent-cart=fastr_trial_eligibility
125
- Content-Type: application/x-www-form-urlencoded
126
-
127
- product_id=14
128
- &device_fingerprint=v1|MACHINEID=...|UUID=...|DISK=...
129
- &email=customer@example.com
130
- ```
131
-
132
- ```json
133
- {
134
- "eligible": true,
135
- "reason": "ok",
136
- "risk_score": 50,
137
- "flags": ["email_reused", "subnet_velocity"],
138
- "token": "...",
139
- "token_expires_at": 1793723400,
140
- "server_time": "2026-11-04T03:45:00Z",
141
- "server_time_unix": 1793721600,
142
- "success": true
143
- }
144
- ```
145
-
146
- | `reason` | HTTP | Meaning |
147
- |---|---|---|
148
- | `ok` | 200 | Eligible, token issued |
149
- | `trial_already_used` | 200 | Machine already claimed a trial for this product |
150
- | `high_risk` | 200 | Score crossed `fastr_trial/block_score` (off by default) |
151
- | `invalid_request` | 422 | Missing `product_id` or `device_fingerprint` |
152
- | `rate_limited` | 429 | More than 30 checks per hour per IP |
153
- | `registry_unavailable` | 200 | Table missing; eligible, never blocks a sale |
154
-
155
- The route is served through FluentCart's own `fluent_cart_action_*` dispatcher, so it behaves exactly like `?fluent-cart=activate_license`.
156
-
157
- ### 5b. Activation
158
-
159
- ```http
160
- POST /?fluent-cart=activate_license
161
-
162
- item_id=14
163
- &license_key=FCT-...
164
- &site_url=device://<uuid>
165
- &device_fingerprint=v1|MACHINEID=...|UUID=...|DISK=...
166
- &device_name=Workstation
167
- &device_type=Desktop (Tauri)
168
- &os=windows x86_64
169
- &arch=x86_64
170
- &cpu=AMD Ryzen 9 5900X
171
- &ram_gb=32
172
- &server_version=1.4.0
173
- &email=customer@example.com
174
- ```
175
-
176
- ### 5c. Heartbeat
177
-
178
- ```http
179
- POST /?fluent-cart=check_license
180
- item_id=14
181
- &license_key=FCT-...
182
- &site_url=device://<uuid>
183
- &device_fingerprint=v1|MACHINEID=...
184
- ```
185
-
186
- ### Error codes
187
-
188
- | `error_type` | HTTP | Meaning | Client action |
189
- |---|---|---|---|
190
- | `trial_already_used` | 422 | Machine consumed its trial | Show purchase page |
191
- | `trial_fingerprint_required` | 422 | Trial sent no fingerprint | Update the client |
192
- | `trial_device_mismatch` | 422 | Key checked from a machine that never claimed it | Treat as unlicensed |
193
- | `device_blocked` | 200 | Admin blocked this device | Contact support |
194
- | `invalid_activation` | 200 | FluentCart has no activation for that `site_url` | Activate first |
195
-
196
- Every refusal carries `success: false` and `server_time_unix`. FluentCart's `sendSuccessResponse()` forces `success = true` **after** the filter returns, so a filter callback must terminate with `wp_send_json($payload, 422)` to express a hard failure. Returning an array cannot.
197
-
198
- ---
199
-
200
- ## 6. Token verification
201
-
202
- Tokens are single-use, 30 minutes, HMAC-SHA256 over `hash|product|expires|nonce` with `wp_salt('auth')`. The nonce is stored as a transient and deleted on first verify.
203
-
204
- ```php
205
- $result = \Fastr_Trial_Eligibility::verify_token($token, $productId);
206
-
207
- if ($result !== true) {
208
- // invalid_token | token_expired | token_used | token_product_mismatch
209
- wp_send_json(['message' => 'Trial verification failed', 'reason' => $result], 422);
210
- }
211
- ```
212
-
213
- A token presented for the wrong product is **not** consumed — the product check runs before the transient is read.
214
-
215
- Tokens are advisory. Activation still enforces the registry, so a forged or replayed token cannot buy a second trial.
216
-
217
- ---
218
-
219
- ## 7. Risk scoring
220
-
221
- | Signal | Points |
222
- |---|---|
223
- | Normalized email already in the registry | 30 |
224
- | ≥2 trials from the same `/24` in 24 h | 20 |
225
- | ≥5 trials from the same `/24` in 30 days | 25 |
226
- | Virtual machine | 15 |
227
-
228
- Cap 100. Stored at claim time as `email_hash`, `risk_score`, `risk_flags`.
229
-
230
- **Heuristics never block by default.** `fastr_trial/block_score` defaults to 101. Opt in:
231
-
232
- ```php
233
- add_filter('fastr_trial/block_score', fn() => 60);
234
- ```
235
-
236
- Email normalization: lowercase, `googlemail.com` → `gmail.com`, strip dots from Gmail local parts, strip `+tags` everywhere.
237
-
238
- ```php
239
- add_filter('fastr_trial/risk_score', fn($score, $productId, $data) => $score, 10, 3);
240
- add_filter('fastr_trial/rate_limit', fn() => 60);
241
- ```
242
-
243
- ---
244
-
245
- ## 8. Operations
246
-
247
- ```bash
248
- wp fastr-trial inspect <row-id|license-id|hash|raw-fingerprint>
249
- wp fastr-trial reset <row-id|hash|raw-fingerprint> --yes
250
- wp fastr-trial stats
251
- ```
252
-
253
- A reset sets `status = reset`; the next activation on that machine re-arms the row and reassigns `first_license_id`.
254
-
255
- Actions for automation:
256
-
257
- | Hook | Fires |
258
- |---|---|
259
- | `fastr_trial/granted` | New claim, or a re-armed claim |
260
- | `fastr_trial/blocked` | Activation refused (`$license, $payload, $code`) |
261
- | `fastr_trial/mismatch` | Heartbeat refused |
262
- | `fastr_trial/reset` | Support reset (`$hash, $scopeKey, $adminId`) |
263
-
264
- Filters: `fastr_trial/scope`, `fastr_trial/require_fingerprint`, `fastr_trial/is_trial_license`, `fastr_trial/block_score`, `fastr_trial/risk_score`, `fastr_trial/rate_limit`.
265
-
266
- ---
267
-
268
- ## 9. Privacy
269
-
270
- - Raw hardware identifiers are **never stored**. Only the HMAC.
271
- - IP is stored as a hash plus a `/24` or `/64` prefix, never the full address.
272
- - Retention: 24 months is a reasonable default; purge with a cron.
273
- - Disclose in the store privacy policy: "We record a privacy-preserving device identifier to prevent repeated free trials."
274
- - Paddle is Merchant of Record, but device data is the merchant's, so GDPR access and deletion requests hit this table.
275
-
276
- ---
277
-
278
- ## 10. What this cannot do
279
-
280
- - A determined user can reinstall the OS or spoof SMBIOS. Nothing client-side prevents that.
281
- - Browser extensions have no durable device identity; treat browser trials as account-bound.
282
- - Corporate images and VDI collide. Manual review, not automatic denial.
283
- - The realistic goal is raising the cost from "new email" to "reinstall Windows or edit firmware strings".
284
-
285
- ---
286
-
287
- ## 11. Test checklist
288
-
289
- | # | Scenario | Expected |
290
- |---|---|---|
291
- | 1 | Fresh machine, new account | Trial granted |
292
- | 2 | Same machine, second account, new trial licence | `trial_already_used` |
293
- | 3 | Same machine, same account, reinstall | Granted |
294
- | 4 | Trial key activated on a second machine | `trial_device_mismatch` on heartbeat |
295
- | 5 | Support reset, then re-activate | Granted, row re-armed |
296
- | 6 | Trial converts to paid | Gate stops applying |
297
- | 7 | VM with a known UUID | Flagged, not denied |
298
- | 8 | Client omits the fingerprint | `trial_fingerprint_required` |
299
- | 9 | Chrome storage cleared | New fingerprint; account scoring decides |
300
- | 10 | Clock rolled back after a block | Still blocked, `server_time_unix` present |
301
- | 11 | Two products, same machine | Granted per product (product scope) |
302
- | 12 | Registry row exists, licence deleted | Still blocks |
303
-
304
- Staging verification of all of the above: `docs/TRIAL-GUARD-STAGING-TEST-REPORT.md` in the add-on workspace.