Skip to content

Commit 4bfc85f

Browse files
forgetsoforgetso
authored
Feat/better spam filter (#38)
1 parent b2d2134 commit 4bfc85f

5 files changed

Lines changed: 566 additions & 0 deletions

File tree

‎src/content/docs/en/advanced/api-keys.mdx‎

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
---
2+
title: API Keys
3+
description: Create and manage API keys for programmatic access to Prosopo services.
4+
i18nReady: true
5+
---
6+
7+
API keys allow you to interact with Prosopo services programmatically — for example, managing access control rules, querying traffic data, or verifying CAPTCHA solutions from your backend without using the portal UI.
8+
9+
API key management is available to accounts with the API feature enabled. Check your account's feature flags in the portal.
10+
11+
## Creating an API Key
12+
13+
1. Log in to the [Prosopo Portal](https://portal.prosopo.io)
14+
2. Navigate to **API Keys** from the main menu
15+
3. Click **Create API Key**
16+
4. Fill in the required fields:
17+
- **Name** (required): A descriptive label for the key, e.g. "Production Backend" or "CI/CD Pipeline"
18+
- **Expiration Time** (optional): Time in seconds until the key expires. Leave empty for a key that does not expire.
19+
- **Permissions** (required): Select which operations this key can perform (see below)
20+
5. Click **Create API Key**
21+
22+
After creation, the full API key is displayed once. Copy it immediately — it cannot be retrieved later.
23+
24+
## Permissions
25+
26+
Each API key is scoped to a specific set of permissions. Only grant the permissions the key actually needs.
27+
28+
### Access Rules
29+
30+
| Permission | Description |
31+
|-----------|-------------|
32+
| `getRules` | List access control rules |
33+
| `getSuggestion` | Get a single rule suggestion |
34+
| `getSuggestions` | List rule suggestions |
35+
| `applySuggestions` | Apply suggested rules |
36+
| `createRule` | Create a new access control rule |
37+
| `deleteRule` | Delete an access control rule |
38+
| `deleteRuleGroup` | Delete an access control rule group |
39+
40+
### Sites
41+
42+
| Permission | Description |
43+
|-----------|-------------|
44+
| `getSite` | Get a single site's details |
45+
| `getSites` | List all sites |
46+
| `createSite` | Create a new site |
47+
| `deleteSite` | Delete a site |
48+
| `updateSite` | Update site settings |
49+
50+
### API Keys
51+
52+
| Permission | Description |
53+
|-----------|-------------|
54+
| `getApiKeys` | List API keys |
55+
| `createApiKey` | Create a new API key |
56+
| `updateApiKey` | Update an existing API key |
57+
| `deleteApiKey` | Delete an API key |
58+
59+
### Users
60+
61+
| Permission | Description |
62+
|-----------|-------------|
63+
| `getUsers` | List team members |
64+
| `createUser` | Invite a new team member |
65+
| `updateUser` | Update a team member's role |
66+
| `deleteUser` | Remove a team member |
67+
68+
### Traffic
69+
70+
| Permission | Description |
71+
|-----------|-------------|
72+
| `getTraffic` | Query traffic analytics data |
73+
74+
### Verify
75+
76+
| Permission | Description |
77+
|-----------|-------------|
78+
| `verify` | Verify CAPTCHA solutions |
79+
80+
### Search Captcha Records
81+
82+
| Permission | Description |
83+
|-----------|-------------|
84+
| `searchCaptchaRecords` | Search and retrieve CAPTCHA audit records |
85+
86+
## Using an API Key
87+
88+
Include the API key in the `Authorization` header of your HTTP requests:
89+
90+
```bash
91+
curl -X GET https://api.prosopo.io/v1/prosopo/provider/admin/rules \
92+
-H "Authorization: Bearer YOUR_API_KEY" \
93+
-H "Content-Type: application/json"
94+
```
95+
96+
Or in code:
97+
98+
```javascript
99+
const response = await fetch('https://api.prosopo.io/v1/prosopo/provider/admin/rules', {
100+
headers: {
101+
'Authorization': `Bearer ${apiKey}`,
102+
'Content-Type': 'application/json',
103+
},
104+
});
105+
```
106+
107+
## Managing API Keys
108+
109+
### Viewing Keys
110+
111+
The API Keys page shows all keys for your account:
112+
113+
- **Name**: The label you gave the key
114+
- **Created**: When the key was created
115+
- **Expires**: When the key expires (or "Never" for non-expiring keys)
116+
- **Permissions**: Which operations the key can perform
117+
118+
### Deleting Keys
119+
120+
To revoke an API key, click the delete button next to it in the API Keys list. The key is immediately invalidated — any requests using it will be rejected.
121+
122+
Deletion is permanent and cannot be undone. If you delete a key by mistake, create a new one and update your application with the new key.
123+
124+
## Security Best Practices
125+
126+
### Principle of Least Privilege
127+
128+
Only grant the permissions each key actually needs. A key used solely for CAPTCHA verification should only have the `verify` permission — it does not need `createSite` or `deleteRule`.
129+
130+
### Use Expiring Keys for Temporary Access
131+
132+
When granting access to a contractor, CI/CD pipeline, or temporary integration, set an expiration time so the key is automatically invalidated.
133+
134+
### Rotate Keys Regularly
135+
136+
For long-lived production keys, rotate them periodically:
137+
138+
1. Create a new key with the same permissions
139+
2. Update your application to use the new key
140+
3. Verify the new key works
141+
4. Delete the old key
142+
143+
### Never Expose Keys Client-Side
144+
145+
API keys should only be used in server-side code. Never embed them in frontend JavaScript, mobile apps, or public repositories. For client-side CAPTCHA integration, use site keys instead — see [Client-side Rendering](/en/basics/client-side-rendering/).
146+
147+
### Monitor Usage
148+
149+
Review the Audit page and traffic analytics to detect any unexpected API key usage patterns that could indicate a compromised key.

‎src/content/docs/en/advanced/image-threshold.mdx‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
---
2+
title: Image Accuracy Threshold
3+
description: Configure how strict image CAPTCHA verification is by setting the accuracy threshold for correct answers.
4+
i18nReady: true
5+
---
6+
7+
The **Image Accuracy Threshold** controls how many image selections a user must get right for their CAPTCHA solution to be accepted. It applies whenever a user is presented with an image CAPTCHA challenge — either directly (image CAPTCHA mode) or as a fallback from frictionless mode when the bot score is above the safety threshold.
8+
9+
## How It Works
10+
11+
When a user submits an image CAPTCHA solution, the system compares their selections against the known correct answers and calculates an accuracy percentage. The threshold determines the minimum accuracy required for the solution to pass:
12+
13+
- **Accuracy >= Threshold**: Solution accepted
14+
- **Accuracy < Threshold**: Solution rejected — the user must try again
15+
16+
## Threshold Levels
17+
18+
The threshold is configured via a three-position slider in the portal:
19+
20+
| Level | Value | Description |
21+
|-------|-------|-------------|
22+
| **Low** | 70% | More lenient. Easier for humans but may allow some bots through. |
23+
| **Medium** | 80% | Balanced approach suitable for most websites. **Recommended.** |
24+
| **High** | 90% | More stringent. Better security but may be more challenging for legitimate users. |
25+
26+
### When to Use Low (70%)
27+
28+
- High-traffic sites where user friction must be minimized
29+
- Audiences that may struggle with image recognition (accessibility considerations)
30+
- Content sites where occasional incorrect solves are acceptable
31+
32+
### When to Use Medium (80%)
33+
34+
- General-purpose websites
35+
- E-commerce and SaaS applications
36+
- Most use cases — this is the recommended default
37+
38+
### When to Use High (90%)
39+
40+
- Sites under active bot attack
41+
- Financial or sensitive applications requiring strong verification
42+
- High-value form submissions (registrations, purchases, payments)
43+
44+
## Relationship to Other Settings
45+
46+
### Safety Threshold
47+
48+
The [Safety Threshold](/en/basics/safety-threshold/) determines *whether* a user sees an image CAPTCHA at all. The Image Accuracy Threshold determines *how accurately* they must solve it. These work together:
49+
50+
1. User arrives and the frictionless system calculates a bot score
51+
2. If the bot score is below the Safety Threshold, the user passes with an invisible PoW challenge (Image Accuracy Threshold is not involved)
52+
3. If the bot score is above the Safety Threshold, the user is presented with an image CAPTCHA
53+
4. The Image Accuracy Threshold then determines how many selections must be correct
54+
55+
### CAPTCHA Type
56+
57+
The Image Accuracy Threshold only applies when image CAPTCHAs are served. If your site is configured to use only Proof of Work CAPTCHAs, this setting has no effect. In frictionless mode, it applies to the image CAPTCHA fallback.
58+
59+
## Configuration
60+
61+
1. Log in to the [Prosopo Portal](https://portal.prosopo.io)
62+
2. Navigate to **Site Settings > General Settings**
63+
3. Find the **Image Accuracy Threshold** card
64+
4. Use the slider to select Low, Medium, or High
65+
5. Click **Save All Changes**
66+
67+
## Recommendations
68+
69+
- **Start with Medium** for most sites — it provides a good balance between security and usability.
70+
- If you see a high rate of legitimate users failing image CAPTCHAs, consider lowering to Low temporarily and investigating whether the issue is with the threshold or with the captcha content.
71+
- If you're under attack and bots are solving image CAPTCHAs, raise the threshold to High and consider combining with other measures (Traffic Filter, IP Validation Rules).
72+
- Monitor your verification analytics in the Audit page to understand how threshold changes affect pass/fail rates.

‎src/content/docs/en/advanced/spam-filter.mdx‎

Lines changed: 170 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,170 @@
1+
---
2+
title: Email Filter
3+
description: Block CAPTCHA verification requests that use suspicious email addresses, including Gmail dot/plus-tag tricks and custom regex patterns.
4+
i18nReady: true
5+
---
6+
7+
The Email Filter (configured under the Spam Filter in site settings) lets you reject CAPTCHA verifications whose associated email address matches suspicious patterns. It is designed to catch common signup-spam evasion techniques — particularly the Gmail dot and plus-tag tricks — while keeping false positives low.
8+
9+
Email filtering is available to Professional and Enterprise tier customers.
10+
11+
## Overview
12+
13+
When a dapp calls the Prosopo verification endpoint with an optional `email` field, the email address is evaluated against the configured rules before the CAPTCHA solution is checked. If any rule matches, verification is rejected immediately.
14+
15+
## Providing the Email Address
16+
17+
Pass the email in the `email` field when calling the server-side verification endpoint:
18+
19+
```json
20+
{
21+
"secret": "your_secret_key",
22+
"token": "PROCAPTCHA-RESPONSE",
23+
"email": "USER_EMAIL_ADDRESS"
24+
}
25+
```
26+
27+
If no email is provided, email filter rules are skipped.
28+
29+
## Filter Rules
30+
31+
### Maximum Dots in Local Part
32+
33+
Limits the number of dots allowed in the part of the email address before the `@` symbol. For example, with a limit of `2`:
34+
35+
- `alice@example.com` — allowed (0 dots)
36+
- `a.lice@example.com` — allowed (1 dot)
37+
- `a.l.ice@example.com` — allowed (2 dots)
38+
- `a.l.i.ce@example.com` — **blocked** (3 dots)
39+
40+
This is effective against the Gmail dot trick, where `a.l.i.c.e@gmail.com` and `alice@gmail.com` are the same Gmail inbox but appear as different addresses to most systems.
41+
42+
Leave blank to disable the dot limit.
43+
44+
### Default Patterns
45+
46+
A curated set of regex patterns targeting common evasion techniques:
47+
48+
- **Many-dots local part**: Catches addresses with excessive dots in the local part (more than 3), which are almost always evasion attempts.
49+
- **Gmail random plus-tag**: Catches addresses like `user+vkd38uoukd5@gmail.com` where a random alphanumeric suffix is appended via a plus tag.
50+
51+
Enable with the **Apply curated default patterns** toggle.
52+
53+
### Gmail Address Normalisation
54+
55+
When enabled, Gmail and Googlemail addresses are normalised before evaluating custom regex patterns:
56+
57+
1. Dots are stripped from the local part (`a.l.i.c.e` becomes `alice`)
58+
2. Plus-tag suffixes are removed (`alice+tag` becomes `alice`)
59+
3. `@googlemail.com` is rewritten to `@gmail.com`
60+
61+
This means a single custom regex pattern like `^alice@gmail\.com$` will match all of the following:
62+
63+
- `alice@gmail.com`
64+
- `a.l.i.c.e@gmail.com`
65+
- `alice+spam123@gmail.com`
66+
- `a.l.i.c.e+tag@googlemail.com`
67+
68+
Normalisation only affects Gmail/Googlemail addresses. Other domains are evaluated as-is.
69+
70+
### Custom Regex Blocklist
71+
72+
Add your own JavaScript regular expressions to block specific email patterns. Patterns are evaluated case-insensitively against the (optionally normalised) email address.
73+
74+
Examples:
75+
76+
| Pattern | What it catches |
77+
|---------|----------------|
78+
| `@disposable\.tld$` | Any address at `disposable.tld` |
79+
| `^spam@` | Any address starting with `spam@` |
80+
| `@(tempmail\|throwaway)\.` | Addresses at `tempmail.*` or `throwaway.*` domains |
81+
| `^test[0-9]+@` | Addresses like `test123@...`, `test99@...` |
82+
83+
Patterns are validated when saved:
84+
- Maximum 256 characters per pattern
85+
- Maximum 50 patterns per site
86+
- Lookahead, lookbehind, and large quantifiers are rejected to prevent regex-based denial of service
87+
- Invalid regex syntax is rejected at save time
88+
89+
### Spam Email Domain List
90+
91+
A separate toggle (`spamEmailDomainCheckEnabled`) checks the email domain against a maintained list of known disposable/spam email providers. This runs independently of the rules above.
92+
93+
## Evaluation Order
94+
95+
When the email filter is enabled and an email is provided, rules are evaluated in this order:
96+
97+
1. **Email validity** — malformed addresses are rejected
98+
2. **Maximum dots** — if configured, checked first
99+
3. **Default patterns** — if enabled, evaluated next
100+
4. **Custom regex blocklist** — each pattern is tested in order; first match wins
101+
102+
Evaluation stops at the first match. The rejection reason is recorded for audit purposes.
103+
104+
## Configuration via Portal
105+
106+
Email filter rules are configured in the [Prosopo Portal](https://portal.prosopo.io) under **Site Settings > Email Filter**:
107+
108+
1. **Enable Spam Filter** — master toggle for all email rules
109+
2. **Email pattern rules** — sub-toggle to activate pattern matching
110+
3. **Maximum dots in the local part** — numeric input
111+
4. **Apply curated default patterns** — toggle
112+
5. **Normalise Gmail addresses before matching** — toggle
113+
6. **Custom regex blocklist** — add/remove patterns with validation
114+
115+
All changes are saved together via the **Save All Changes** button.
116+
117+
## Verification Response
118+
119+
When an email rule blocks a request, the verification endpoint returns:
120+
121+
```json
122+
{
123+
"verified": false,
124+
"status": "API.SPAM_EMAIL_RULE"
125+
}
126+
```
127+
128+
Possible status codes:
129+
130+
| Status | Meaning |
131+
|--------|---------|
132+
| `API.SPAM_EMAIL_RULE` | Email matched a custom regex pattern |
133+
| `API.SPAM_EMAIL_DOMAIN` | Email domain is on the known-spam list |
134+
135+
## Use Cases
136+
137+
### Stopping Gmail Dot/Plus-Tag Abuse
138+
139+
A single Gmail account can generate thousands of apparent email addresses using dots and plus tags. To block this:
140+
141+
1. Enable **Email pattern rules**
142+
2. Enable **Apply curated default patterns** (catches random plus-tags and excessive dots automatically)
143+
3. Set **Maximum dots** to `2`
144+
4. Enable **Normalise Gmail addresses** if you also use custom patterns
145+
146+
### Blocking Disposable Email Domains
147+
148+
To block known throwaway email services:
149+
150+
1. Enable **Spam email domain checking** (uses the maintained domain list)
151+
2. Optionally add custom patterns for domains not yet on the list:
152+
```
153+
@(tempmail|throwaway|guerrillamail)\.
154+
```
155+
156+
### Organisation-Specific Patterns
157+
158+
If you see abuse from specific patterns unique to your service:
159+
160+
1. Add targeted custom regex patterns
161+
2. Monitor the `API.SPAM_EMAIL_RULE` status in your verification responses
162+
3. Adjust patterns based on what you observe
163+
164+
## Availability
165+
166+
| Tier | Email Filter |
167+
|------|-------------|
168+
| Free | Not available |
169+
| Professional | Full access |
170+
| Enterprise | Full access |

0 commit comments

Comments
 (0)