@core / antispam

1.1.0 ▾

1.1.0

verifiziertMIT

GitHub

Spam-Schutz für öffentliche Formulare: Honeypot, signierte Zeitprüfung, Turnstile oder hCaptcha und Rate-Limits

Code9 DateienKontext~722 TokensPrüfung bestanden

~722 Tokens→ src/lib/antispam/AGENTS.md→ .cursor/rules/genpm-core-antispam.mdc

Genau das liest deine KI, wenn sie in src/lib/antispam arbeitet. Sonst wird ihrem Kontext nichts hinzugefügt.

@core/antispam — rules for AI agents

Purpose

Protects public endpoints that write (forms, comments, newsletter, login): honeypot field, signed minimum-time token, captcha (Cloudflare Turnstile or hCaptcha, optional) and fixed-window rate limits stored in Postgres with HMAC-hashed keys (no plain IPs or emails). Not a WAF or DDoS protection. Table: rate_limits.

Map

index.ts — public API: verifyHuman, rateLimit, formTimingToken, honeypotProps, verifyCaptcha, clientIp, pruneRateLimits.
verify.ts — the full check. checks.ts — individual checks. rate-limit.ts — limiter. schema.ts — table.
react.ts — <AntispamFields /> (async server component) with the honeypot and the signed timing field for HTML forms.

Integration

Env: ANTISPAM_SECRET (≥ 32 random chars). Optional captcha: TURNSTILE_SITE_KEY + TURNSTILE_SECRET_KEY (or HCAPTCHA_SECRET_KEY). Generate and apply migrations (see src/lib/db/AGENTS.md). Client IP source (rate limits): by default the right-most x-forwarded-for hop, skipping ANTISPAM_TRUSTED_PROXIES - 1 more hops (default 1: the address your last proxy saw). Behind a platform that sets a dedicated header, set ANTISPAM_IP_HEADER (cf-connecting-ip on Cloudflare, x-vercel-forwarded-for on Vercel, x-real-ip, fly-client-ip…). Platform headers are never trusted unless configured: clients can send them.
When rendering the form (server), add two fields: <input {...honeypotProps} /> and <input type="hidden" name="_ts" value={await formTimingToken()} />. With Turnstile, also render its widget (<div class="cf-turnstile" data-sitekey={TURNSTILE_SITE_KEY}> and its script).

In the handler, before doing anything else:

const check = await verifyHuman(request.headers, formData, { scope: 'forms:contact' });
if (!check.ok) return Response.json({ error: check.reason }, { status: check.reason === 'rate_limited' ? 429 : 400 });

Per-account limits (login, password reset): await rateLimit(login:${email}, { limit: 5, windowMs: 900_000 }).
Schedule pruneRateLimits() daily (e.g. with @core/jobs).
Verify: submitting within 2 s or with the honeypot filled is rejected; a normal submission passes.

Conventions

Every public write endpoint calls verifyHuman (or at least rateLimit) with its own scope.
Show users a generic error; don't reveal which check failed beyond "try again later".
clientIp is only as reliable as ANTISPAM_IP_HEADER / ANTISPAM_TRUSTED_PROXIES match your proxies; use it for limits, never for authorization.

Don't

Don't store raw IPs, emails or captcha tokens; rateLimit already hashes keys.
Don't hide the honeypot with type="hidden" (bots skip those); use honeypotProps.
Don't skip the captcha check when the provider is down: verifyCaptcha fails closed on purpose.

# @core/antispam — rules for AI agents

## Purpose
Protects public endpoints that write (forms, comments, newsletter, login): honeypot field, signed minimum-time token,
captcha (Cloudflare Turnstile or hCaptcha, optional) and fixed-window rate limits stored in Postgres with HMAC-hashed
keys (no plain IPs or emails). Not a WAF or DDoS protection. Table: `rate_limits`.

## Map
- `index.ts` — public API: `verifyHuman`, `rateLimit`, `formTimingToken`, `honeypotProps`, `verifyCaptcha`, `clientIp`, `pruneRateLimits`.
- `verify.ts` — the full check. `checks.ts` — individual checks. `rate-limit.ts` — limiter. `schema.ts` — table.
- `react.ts` — `<AntispamFields />` (async server component) with the honeypot and the signed timing field for HTML forms.

## Integration
1. Env: `ANTISPAM_SECRET` (≥ 32 random chars). Optional captcha: `TURNSTILE_SITE_KEY` + `TURNSTILE_SECRET_KEY`
   (or `HCAPTCHA_SECRET_KEY`). Generate and apply migrations (see `src/lib/db/AGENTS.md`).
   Client IP source (rate limits): by default the right-most `x-forwarded-for` hop, skipping
   `ANTISPAM_TRUSTED_PROXIES - 1` more hops (default `1`: the address your last proxy saw). Behind a platform that sets
   a dedicated header, set `ANTISPAM_IP_HEADER` (`cf-connecting-ip` on Cloudflare, `x-vercel-forwarded-for` on Vercel,
   `x-real-ip`, `fly-client-ip`…). Platform headers are never trusted unless configured: clients can send them.
2. When rendering the form (server), add two fields:
   `<input {...honeypotProps} />` and `<input type="hidden" name="_ts" value={await formTimingToken()} />`.
   With Turnstile, also render its widget (`<div class="cf-turnstile" data-sitekey={TURNSTILE_SITE_KEY}>` and its script).
3. In the handler, before doing anything else:
   ```ts
   const check = await verifyHuman(request.headers, formData, { scope: 'forms:contact' });
   if (!check.ok) return Response.json({ error: check.reason }, { status: check.reason === 'rate_limited' ? 429 : 400 });
   ```
4. Per-account limits (login, password reset): `await rateLimit(`login:${email}`, { limit: 5, windowMs: 900_000 })`.
5. Schedule `pruneRateLimits()` daily (e.g. with @core/jobs).
6. Verify: submitting within 2 s or with the honeypot filled is rejected; a normal submission passes.

## Conventions
- Every public write endpoint calls `verifyHuman` (or at least `rateLimit`) with its own `scope`.
- Show users a generic error; don't reveal which check failed beyond "try again later".
- `clientIp` is only as reliable as `ANTISPAM_IP_HEADER` / `ANTISPAM_TRUSTED_PROXIES` match your proxies; use it for limits, never for authorization.

## Don't
- Don't store raw IPs, emails or captcha tokens; `rateLimit` already hashes keys.
- Don't hide the honeypot with `type="hidden"` (bots skip those); use `honeypotProps`.
- Don't skip the captcha check when the provider is down: `verifyCaptcha` fails closed on purpose.

Der genaue Baum, der nach .genpmignore eingebunden wird. Gepinnt an

src/lib/antispam/LICENSEschreibgeschützt · 0328b98

MIT License

Copyright (c) 2026 GenPM

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.