ALTCHA Captcha

Proof-of-work captcha using altcha-lib. The client solves a CPU-bound puzzle; the server verifies the HMAC-signed payload. No third-party calls — the entire flow is self-hosted except for the Upstash replay store.

Environment Variables

Kill Switch: BOT_DETECTION_MODE

parseMode() in config.ts defaults to 'live' for any unrecognized value, so a missing env var is safe.

Fail-Closed: assertProductionConfig

config.ts calls assertProductionConfig() at module load. In NODE_ENV=production it throws — failing the build or cold start — if:

• BOT_DETECTION_MODE is not 'live'
• ALTCHA_HMAC_KEY is shorter than 32 characters
• ALTCHA_HMAC_KEY matches a placeholder pattern (test-*, dummy-*, example-*, changeme*, placeholder*)

This ensures misconfigured production deploys fail fast rather than silently allowing all traffic.

Server Library (#lib/server/abuse/altcha.ts)

// Algorithm
algorithm: 'PBKDF2/SHA-256'
cost: 100_000           // iterations — slow enough to deter bots, fast enough for humans

// Replay store
REPLAY_KEY_PREFIX = 'altcha:nonce:'
REPLAY_TTL_SECONDS = 600   // 10 minutes — auto-expired by Redis EX

The altcha instance is created via create() from altcha-lib/frameworks/sveltekit and is null when ALTCHA_HMAC_KEY is absent. Every downstream call guards on this.

verifyAltcha(payload)

Public function exported from #lib/server/abuse/. Wraps internal verification with BOT_DETECTION_MODE behavior:

import { verifyAltcha } from '#lib/server/abuse/index.ts';

const decision = await verifyAltcha(request.headers.get('x-altcha-token'));
if (!decision.allowed) return decisionResponse(decision);

Returns a Decision ({ allowed: true } or { allowed: false, layer: 'altcha', ... }).

Replay Protection

Each solved payload carries a nonce. On first verify, the nonce is written to Redis (altcha:nonce:{nonce}, TTL 600s). A second use of the same payload hits the key and is rejected. If Redis is unavailable the store's get returns null and set is a no-op — replay protection degrades gracefully in dev; assertProductionConfig ensures Redis is configured in production.

Challenge Endpoint (/api/captcha/challenge)

GET /api/captcha/challenge — issues a new challenge to the widget.

Per-IP rate limit: 30 requests per 60 seconds (rl:captcha:challenge prefix, createLimiter factory).

Returns 503 if BOT_DETECTION_MODE === 'off'.

<Altcha /> Composite

#lib/components/composites/altcha/Altcha.svelte wraps the <altcha-widget> custom element.

Props

Gotchas

challenge attribute, not challengeurl. The altcha v3 custom element renamed the attribute. The component uses challenge={challengeUrl} on the element directly.

hideFooter/hideLogo require configure(). These options are not HTML attributes in v3 — they must be passed through the widget's configure() method post-mount:

onMount(async () => {
    await import('altcha');
    widget?.configure?.({ hideFooter, hideLogo });
});

Setting them as HTML attributes has no effect.

Token is single-use. Re-mount the widget after the parent consumes the payload (e.g., {#key someVersion}<Altcha />{/key}).

Auth Hook Wiring

Captcha verification runs in the authCaptchaGate hook handler before Better Auth processes these paths:

• POST /api/auth/sign-in/magic-link
• POST /api/auth/email-otp/send-verification-otp
• POST /api/auth/two-factor/send-otp

The solved payload is expected in the x-altcha-token request header. The Better Auth client must attach it when calling signIn.magicLink() or signIn.emailOtp.sendOtp().

Related

• rate-limits.md — per-IP challenge limiter, per-email limiter wired alongside captcha
• Live showcase