Protección antispam para formularios públicos: honeypot, tiempo firmado, Turnstile o hCaptcha y rate limit en Postgres
Instalar
genpm add @core/antispamQué obtienes
- Código en src/lib/antispam/, 9 archivos. (16,2 kB)
- Reglas de IA en src/lib/antispam/AGENTS.md, más archivos de reglas para tu IDE.
- Variables añadidas a .env.example: ANTISPAM_SECRET, TURNSTILE_SITE_KEY, TURNSTILE_SECRET_KEY, ANTISPAM_IP_HEADER, ANTISPAM_TRUSTED_PROXIES.
- Resuelve @core/db por ti.
README
Este paquete no tiene README.
Esto es exactamente lo que lee tu IA cuando trabaja en src/lib/antispam. No se añade nada más a su contexto.
@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(orHCAPTCHA_SECRET_KEY). Generate and apply migrations (seesrc/lib/db/AGENTS.md). Client IP source (rate limits): by default the right-mostx-forwarded-forhop, skippingANTISPAM_TRUSTED_PROXIES - 1more hops (default1: the address your last proxy saw). Behind a platform that sets a dedicated header, setANTISPAM_IP_HEADER(cf-connecting-ipon Cloudflare,x-vercel-forwarded-foron 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 leastrateLimit) with its ownscope. - Show users a generic error; don't reveal which check failed beyond "try again later".
clientIpis only as reliable asANTISPAM_IP_HEADER/ANTISPAM_TRUSTED_PROXIESmatch your proxies; use it for limits, never for authorization.
Don't
- Don't store raw IPs, emails or captcha tokens;
rateLimitalready hashes keys. - Don't hide the honeypot with
type="hidden"(bots skip those); usehoneypotProps. - Don't skip the captcha check when the provider is down:
verifyCaptchafails 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.
El árbol exacto que se inyectará, tras aplicar .genpmignore. Anclado a
// Utilidades criptográficas con Web Crypto (Node, Workers y navegador).
const enc = new TextEncoder();
const hex = (buf: ArrayBuffer) => [...new Uint8Array(buf)].map((b) => b.toString(16).padStart(2, '0')).join('');
export async function sha256Hex(data: string): Promise<string> {
return hex(await crypto.subtle.digest('SHA-256', enc.encode(data)));
}
export async function hmacHex(secret: string, data: string): Promise<string> {
const key = await crypto.subtle.importKey('raw', enc.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
return hex(await crypto.subtle.sign('HMAC', key, enc.encode(data)));
}
export function safeEqual(a: string, b: string): boolean {
let d = a.length ^ b.length;
for (let i = 0; i < Math.max(a.length, b.length); i++) d |= (a.charCodeAt(i) || 0) ^ (b.charCodeAt(i) || 0);
return d === 0;
}
Este paquete no declara servidores MCP.
| Versión | Commit | Publicado | Escaneo |
|---|---|---|---|
| 1.1.0 | 0328b98 | hace 7 horas | escaneo superado |
- genpm
- @core/db ^1.0.0
- propuesta
- GenPM propone el comando npm y solo lo ejecuta si dices que sí.
- escaneo
- escaneo superado · 0 hallazgos
- commit
- v1.1.0 → 0328b9831cf65db04ab02f0af62b93edbe95d6ac · verificado tras la descarga
- scripts
- Ninguno. GenPM nunca ejecuta código del paquete.
- licencia
- MIT
- Calidad
- 100/100
- Licencia reconocidacumplido
- AGENTS.md explica su propósitocumplido
- AGENTS.md tiene pasos de integracióncumplido
- AGENTS.md lista convenciones o prohibicionescumplido
- Incluye testscumplido
- Escaneo de seguridad superadocumplido
- Publicado en los últimos 6 mesescumplido
- Publicador verificadocumplido
- Resumen y palabras clavecumplido
- reporte
- ¿Ves algo raro?