fluentcart-developer 2.0.2 → 2.3.1
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.
- package/README.md +59 -59
- package/dist/cards/fluentcart/tools.d.ts.map +1 -1
- package/dist/cards/fluentcart/tools.js +184 -18
- package/dist/cards/fluentcart/tools.js.map +1 -1
- package/dist/skills/fluentcart-developer/.claude-plugin/plugin.json +12 -12
- package/dist/skills/fluentcart-developer/.mcp.json +11 -11
- package/dist/skills/fluentcart-developer/examples/fluentcart-starter-child-theme/fluent-cart/checkout.php +32 -32
- package/dist/skills/fluentcart-developer/examples/fluentcart-starter-child-theme/functions.php +40 -40
- package/dist/skills/fluentcart-developer/examples/sample-fee-surcharge-plugin/fluentcart-fee-surcharge.php +38 -38
- package/dist/skills/fluentcart-developer/references/action-hooks-cart-checkout.md +1355 -1355
- package/dist/skills/fluentcart-developer/references/action-hooks-customers-users.md +266 -266
- package/dist/skills/fluentcart-developer/references/action-hooks-licenses.md +855 -855
- package/dist/skills/fluentcart-developer/references/action-hooks-orders.md +631 -631
- package/dist/skills/fluentcart-developer/references/action-hooks-payments-integrations.md +963 -963
- package/dist/skills/fluentcart-developer/references/action-hooks-products-coupons.md +585 -585
- package/dist/skills/fluentcart-developer/references/action-hooks-subscriptions.md +661 -661
- package/dist/skills/fluentcart-developer/references/database-models-query-builder.md +194 -194
- package/dist/skills/fluentcart-developer/references/database-models-reference.md +604 -604
- package/dist/skills/fluentcart-developer/references/engineering-notes.md +154 -154
- package/dist/skills/fluentcart-developer/references/fee-system-guide.md +449 -449
- package/dist/skills/fluentcart-developer/references/filter-hooks-cart-checkout.md +1202 -1202
- package/dist/skills/fluentcart-developer/references/filter-hooks-integrations-advanced.md +1598 -1598
- package/dist/skills/fluentcart-developer/references/filter-hooks-products-pricing.md +628 -628
- package/dist/skills/fluentcart-developer/references/filter-hooks-settings-configuration.md +1177 -1177
- package/dist/skills/fluentcart-developer/references/fluentcart-developer-guide.md +154 -154
- package/dist/skills/fluentcart-developer/references/ghost-product-selling.md +458 -458
- package/dist/skills/fluentcart-developer/references/modules-and-extensions-reference.md +224 -224
- package/dist/skills/fluentcart-developer/references/payment-gateway-integration.md +761 -761
- package/dist/skills/fluentcart-developer/references/rest-api-customer-profile.md +190 -190
- package/dist/skills/fluentcart-developer/references/rest-api-customers.md +1121 -1121
- package/dist/skills/fluentcart-developer/references/rest-api-dashboard-utilities.md +219 -219
- package/dist/skills/fluentcart-developer/references/rest-api-email-notifications.md +619 -619
- package/dist/skills/fluentcart-developer/references/rest-api-files.md +290 -290
- package/dist/skills/fluentcart-developer/references/rest-api-integrations.md +324 -324
- package/dist/skills/fluentcart-developer/references/rest-api-labels-attributes.md +321 -321
- package/dist/skills/fluentcart-developer/references/rest-api-order-bumps.md +200 -200
- package/dist/skills/fluentcart-developer/references/rest-api-overview.md +131 -131
- package/dist/skills/fluentcart-developer/references/rest-api-public-shop.md +172 -172
- package/dist/skills/fluentcart-developer/references/rest-api-reference.md +552 -552
- package/dist/skills/fluentcart-developer/references/rest-api-reports.md +377 -377
- package/dist/skills/fluentcart-developer/references/rest-api-roles-permissions.md +147 -147
- package/dist/skills/fluentcart-developer/references/rest-api-settings.md +528 -528
- package/dist/skills/fluentcart-developer/references/rest-api-shipping.md +799 -799
- package/dist/skills/fluentcart-developer/references/rest-api-tax.md +356 -356
- package/dist/skills/fluentcart-developer/references/subscription-customization.md +197 -197
- package/dist/skills/fluentcart-developer/scripts/cli.js +1 -1
- package/dist/version.d.ts +1 -1
- package/dist/version.js +1 -1
- package/package.json +65 -65
- package/dist/skills/fluentcart-developer/references/client-integration-contract.md +0 -299
- package/dist/skills/fluentcart-developer/references/device-licensing-and-hardware-tracking.md +0 -241
- package/dist/skills/fluentcart-developer/references/trial-abuse-prevention.md +0 -304
|
@@ -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.
|