@core / antispam

1.1.0 ▾

1.1.0

verificadoMIT

GitHub

Proteção antispam para formulários públicos: honeypot, tempo assinado, Turnstile ou hCaptcha e rate limit no Postgres

Código9 arquivosContexto~722 tokensanálise aprovada

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

Isto é exatamente o que sua IA lê quando trabalha em src/lib/antispam. Nada mais é adicionado ao contexto dela.

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

A árvore exata que será injetada, após o .genpmignore. Fixada em

src/lib/antispam/index.tssomente leitura · 0328b98

// @core/antispam — API pública. Importa desde aquí.
export {
  CAPTCHA_FIELD,
  type CaptchaConfig,
  type CaptchaProvider,
  captchaFromEnv,
  checkFormTiming,
  clientIp,
  formTimingToken,
  HONEYPOT_FIELD,
  honeypotProps,
  isHoneypotFilled,
  TIMING_FIELD,
  verifyCaptcha,
} from './checks.ts';
export { pruneRateLimits, type RateLimitResult, rateLimit } from './rate-limit.ts';
export { rateLimits } from './schema.ts';
export { type HumanCheckFailure, type HumanCheckOptions, type HumanCheckResult, verifyHuman } from './verify.ts';