@core / antispam

1.1.0 ▾

1.1.0

verifiedMIT

GitHub

Spam protection for public forms: honeypot, signed timing, Turnstile or hCaptcha and Postgres rate limits

Code9 filesContext~722 tokensscan passed

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

This is exactly what your AI reads when it works in src/lib/antispam. Nothing else is added to its context.

@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.

The exact tree that will be injected, after .genpmignore. Pinned to

src/lib/antispam/react.tsread-only · 0328b98

// `<AntispamFields />`: campos ocultos para formularios HTML (trampa y hora firmada). Componente de servidor (async).
import { createElement as h, Fragment, type ReactNode } from 'react';
import { formTimingToken, HONEYPOT_FIELD, honeypotProps, TIMING_FIELD } from './checks.ts';

export async function AntispamFields(): Promise<ReactNode> {
  return h(Fragment, null, h('input', { ...honeypotProps, key: HONEYPOT_FIELD }), h('input', { type: 'hidden', name: TIMING_FIELD, value: await formTimingToken(), key: TIMING_FIELD }));
}