@strav/captcha 0.4.10

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@strav/captcha",
+  "version": "0.4.10",
+  "type": "module",
+  "description": "Built-in CAPTCHA for the Strav framework — honeypot, proof-of-work, and SVG text challenges with no external dependencies",
+  "license": "MIT",
+  "exports": {
+    ".": "./src/index.ts",
+    "./*": "./src/*.ts"
+  },
+  "strav": {
+    "islands": {
+      "namespace": "captcha",
+      "dir": "./src/islands"
+    }
+  },
+  "files": [
+    "src/",
+    "package.json",
+    "tsconfig.json"
+  ],
+  "peerDependencies": {
+    "@strav/kernel": "0.4.10",
+    "@strav/http": "0.4.10",
+    "@strav/view": "0.4.10"
+  },
+  "scripts": {
+    "test": "bun test tests/",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/challenges/honeypot.ts

@@ -0,0 +1,24 @@
+import type { ChallengeType } from '../types.ts'
+
+/**
+ * Invisible-field honeypot. The middleware injects a hidden input that
+ * humans never see; bots that auto-fill every field on the page will
+ * trip it. Free, zero UX, layer it under everything else.
+ *
+ * The honeypot field name is checked at the middleware layer — this
+ * type just establishes the token shape so the protection still
+ * surfaces a `pow_insufficient`/`token_*` error path consistent with
+ * other types when the form is submitted without a token.
+ */
+export const honeypotChallenge: ChallengeType = {
+  name: 'honeypot',
+  issue() {
+    return { props: {} }
+  },
+  // Honeypot's "answer" is the absence of a value in the trap field. The
+  // middleware checks `body[honeypotField]` directly before getting here,
+  // so by the time we run the body has already passed the trap.
+  verify() {
+    return { ok: true }
+  },
+}

package/src/challenges/pow.ts

@@ -0,0 +1,63 @@
+import { encrypt } from '@strav/kernel'
+import type { ChallengeType } from '../types.ts'
+import { DEFAULTS } from '../types.ts'
+
+/**
+ * Hashcash-style proof of work. The client must find a nonce such that
+ * `sha256(salt + ':' + nonce)` has at least `difficulty` leading zero
+ * bits. Verification is a single sha256 — no DB, no chain of trust.
+ *
+ * The salt IS the challenge — exposed in props so the client can hash
+ * against the same value the server will check. No separate `answer`:
+ * the proof IS the work, not a secret.
+ *
+ * Difficulty 18 ≈ 100–500 ms on a modern laptop; halving (16) makes it
+ * comfortable on phones, +2 (20) is a noticeable pause.
+ */
+export const powChallenge: ChallengeType = {
+  name: 'pow',
+  issue(opts) {
+    const difficulty = opts.difficulty ?? DEFAULTS.difficulty
+    return {
+      props: { challenge: opts.salt, difficulty },
+      extra: { d: difficulty },
+    }
+  },
+  verify(payload, response) {
+    if (typeof response !== 'string' || response.length === 0) {
+      return { ok: false, reason: 'pow_insufficient' }
+    }
+    const difficulty = payload.d ?? DEFAULTS.difficulty
+
+    // Cap nonce length so a malicious client can't ship megabyte payloads
+    // through our hash function.
+    if (response.length > 64) return { ok: false, reason: 'pow_insufficient' }
+
+    const digest = encrypt.sha256(payload.s + ':' + response)
+    if (countLeadingZeroBits(digest) < difficulty) {
+      return { ok: false, reason: 'pow_insufficient' }
+    }
+    return { ok: true }
+  },
+}
+
+/**
+ * Count leading zero bits in a hex digest. 4 bits per nibble — once we
+ * hit a non-zero nibble we add the leading zeros within it and stop.
+ */
+export function countLeadingZeroBits(hex: string): number {
+  let bits = 0
+  for (let i = 0; i < hex.length; i++) {
+    const nibble = parseInt(hex[i]!, 16)
+    if (nibble === 0) {
+      bits += 4
+      continue
+    }
+    // Count leading zeros in this nibble (1..3, since nibble != 0)
+    if (nibble < 0b0010) bits += 3
+    else if (nibble < 0b0100) bits += 2
+    else if (nibble < 0b1000) bits += 1
+    break
+  }
+  return bits
+}

package/src/challenges/svg.ts

@@ -0,0 +1,113 @@
+import { encrypt } from '@strav/kernel'
+import type { ChallengeType } from '../types.ts'
+import { hashAnswer, safeEqual } from '../token.ts'
+
+const ALPHABET = 'ABCDEFGHJKLMNPQRSTUVWXYZ23456789' // no 0/O/I/1
+const LENGTH = 6
+const WIDTH = 200
+const HEIGHT = 70
+const FONT_SIZE = 38
+
+/**
+ * Distorted-text challenge rendered as inline SVG — no canvas, no font
+ * files, no external requests. Each glyph gets a small per-character
+ * rotation and vertical jitter; a few decoy strokes cross the field to
+ * break naive segmentation.
+ *
+ * Defense level: better than no captcha, far weaker than reCAPTCHA. The
+ * point is to make scripted bulk submission expensive, not to stop a
+ * targeted attacker who'll route to a human solver. Layer with PoW for
+ * compounding cost.
+ */
+export const svgChallenge: ChallengeType = {
+  name: 'svg',
+  issue() {
+    const answer = randomCode(LENGTH)
+    return {
+      props: {},
+      answer,
+      html: renderSvg(answer),
+    }
+  },
+  verify(payload, response) {
+    if (typeof response !== 'string' || response.trim() === '') {
+      return { ok: false, reason: 'answer_mismatch' }
+    }
+    if (!payload.ah) return { ok: false, reason: 'token_invalid' }
+    const expected = hashAnswer(response, payload.s)
+    if (!safeEqual(expected, payload.ah)) {
+      return { ok: false, reason: 'answer_mismatch' }
+    }
+    return { ok: true }
+  },
+}
+
+/** Pick `n` characters from the confusables-pruned alphabet. */
+function randomCode(n: number): string {
+  const bytes = encrypt.randomBytes(n)
+  let out = ''
+  for (let i = 0; i < n; i++) {
+    out += ALPHABET[bytes[i]! % ALPHABET.length]
+  }
+  return out
+}
+
+/**
+ * Build the SVG body for a code. We seed RNG from the code so re-rendering
+ * the same answer (e.g. for caching) yields the same image — but since
+ * the salt + jti rotate per challenge issuance, the image still differs
+ * across requests.
+ */
+export function renderSvg(code: string): string {
+  // Bun's Math.random is fine for visual jitter — security comes from
+  // the answer hash, not from making the SVG unpredictable.
+  const glyphs: string[] = []
+  const stepX = (WIDTH - 30) / code.length
+  const baselineY = HEIGHT / 2 + FONT_SIZE / 3
+
+  for (let i = 0; i < code.length; i++) {
+    const ch = escapeXml(code[i]!)
+    const x = 20 + stepX * i
+    const y = baselineY + (Math.random() * 10 - 5)
+    const rot = Math.random() * 40 - 20
+    const skew = Math.random() * 16 - 8
+    const fill = `hsl(${Math.floor(Math.random() * 360)}, 60%, 35%)`
+    glyphs.push(
+      `<text x="${x.toFixed(1)}" y="${y.toFixed(1)}" font-size="${FONT_SIZE}" ` +
+        `font-family="Helvetica, Arial, sans-serif" font-weight="700" fill="${fill}" ` +
+        `transform="rotate(${rot.toFixed(1)} ${x.toFixed(1)} ${y.toFixed(1)}) skewX(${skew.toFixed(1)})">` +
+        `${ch}</text>`
+    )
+  }
+
+  // Two distractor strokes — cheap segmentation breaker.
+  const lines: string[] = []
+  for (let i = 0; i < 2; i++) {
+    const x1 = Math.random() * WIDTH
+    const x2 = Math.random() * WIDTH
+    const y1 = Math.random() * HEIGHT
+    const y2 = Math.random() * HEIGHT
+    const stroke = `hsl(${Math.floor(Math.random() * 360)}, 50%, 40%)`
+    lines.push(
+      `<line x1="${x1.toFixed(1)}" y1="${y1.toFixed(1)}" x2="${x2.toFixed(1)}" y2="${y2.toFixed(1)}" stroke="${stroke}" stroke-width="1.5" />`
+    )
+  }
+
+  return (
+    `<svg xmlns="http://www.w3.org/2000/svg" width="${WIDTH}" height="${HEIGHT}" viewBox="0 0 ${WIDTH} ${HEIGHT}" ` +
+    `role="img" aria-label="Type the characters shown">` +
+    `<rect width="100%" height="100%" fill="#f5f5f5"/>` +
+    lines.join('') +
+    glyphs.join('') +
+    `</svg>`
+  )
+}
+
+function escapeXml(s: string): string {
+  return s
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;')
+}

package/src/challenges.ts

@@ -0,0 +1,89 @@
+import { encrypt } from '@strav/kernel'
+import type {
+  ChallengeName,
+  IssueOptions,
+  IssuedChallenge,
+  CaptchaTokenPayload,
+  VerifyResult,
+} from './types.ts'
+import { DEFAULTS } from './types.ts'
+import { getChallengeType, registerChallengeType } from './registry.ts'
+import { sealToken, unsealToken, hashAnswer } from './token.ts'
+import { honeypotChallenge } from './challenges/honeypot.ts'
+import { powChallenge } from './challenges/pow.ts'
+import { svgChallenge } from './challenges/svg.ts'
+
+// Self-register built-ins on first import. Side-effect on import is the
+// same pattern the auth/flag drivers use — single source of truth, no
+// service-locator wiring required.
+registerChallengeType(honeypotChallenge)
+registerChallengeType(powChallenge)
+registerChallengeType(svgChallenge)
+
+/**
+ * Issue a fresh challenge. Synchronous — `encrypt.seal` and the built-in
+ * issuers all run without I/O. Caller embeds `token` in a hidden field
+ * and uses `props` (and `html` for SVG) to render the challenge.
+ */
+export function issueChallenge(type: ChallengeName, opts: IssueOptions = {}): IssuedChallenge {
+  const challenge = getChallengeType(type)
+  if (!challenge) throw new Error(`Unknown captcha challenge type: ${type}`)
+
+  const ttlMinutes = opts.ttlMinutes ?? DEFAULTS.ttlMinutes
+  // 16 bytes (32 hex chars) — salts double as the PoW challenge value, so
+  // give them enough entropy that a precomputed PoW table is impractical.
+  const salt = encrypt.random(16)
+
+  const issued = challenge.issue({
+    ...opts,
+    difficulty: opts.difficulty ?? DEFAULTS.difficulty,
+    salt,
+  })
+
+  const tokenData: Omit<CaptchaTokenPayload, 'v' | 'iat' | 'jti'> = {
+    t: type,
+    s: salt,
+    exp: ttlMinutes,
+    ...(issued.answer !== undefined ? { ah: hashAnswer(issued.answer, salt) } : {}),
+    ...(issued.extra ?? {}),
+  }
+
+  const { token } = sealToken(tokenData)
+
+  return {
+    token,
+    props: issued.props,
+    ...(issued.html !== undefined ? { html: issued.html } : {}),
+  }
+}
+
+/**
+ * Decode and verify a token + the user's response. Replay prevention
+ * happens upstream in the middleware (after we know verification passed)
+ * so that failed attempts don't burn the replay slot.
+ *
+ * Pure: no cache writes, no I/O. Easy to call from a custom validator
+ * or a JSON API handler.
+ */
+export function verifyChallenge(
+  token: string,
+  response: unknown,
+  body: Record<string, unknown> = {}
+): VerifyResult {
+  if (!token || typeof token !== 'string') {
+    return { ok: false, reason: 'token_missing' }
+  }
+
+  const decoded = unsealToken(token)
+  if (!decoded.ok) return decoded
+
+  const challenge = getChallengeType(decoded.payload.t)
+  if (!challenge) return { ok: false, reason: 'unknown_type' }
+
+  const result = challenge.verify(decoded.payload, response, body)
+  if (!result.ok) return result
+
+  return { ok: true, payload: decoded.payload }
+}
+
+export { honeypotChallenge, powChallenge, svgChallenge }

package/src/index.ts

@@ -0,0 +1,44 @@
+// Middleware
+export { captcha } from './middleware.ts'
+
+// Issue / verify primitives
+export { issueChallenge, verifyChallenge } from './challenges.ts'
+export { honeypotChallenge, powChallenge, svgChallenge } from './challenges.ts'
+
+// Registry — for custom challenge types
+export { registerChallengeType, getChallengeType, listChallengeTypes } from './registry.ts'
+
+// Validation rule
+export { captchaRule } from './validation_rule.ts'
+
+// Refresh route
+export { mountCaptchaRoutes } from './route.ts'
+
+// View helper / @captcha directive support
+export {
+  installCaptchaHelpers,
+  configureCaptchaHelper,
+  captchaHelper,
+} from './view_helper.ts'
+
+// Token utilities (exposed so consumers can build custom flows)
+export { sealToken, unsealToken, hashAnswer, safeEqual, consumeReplay } from './token.ts'
+
+// SVG renderer (exposed for users who want to render outside the directive)
+export { renderSvg } from './challenges/svg.ts'
+
+// PoW utilities (count leading zero bits — useful for testing)
+export { countLeadingZeroBits } from './challenges/pow.ts'
+
+// Types
+export { DEFAULTS } from './types.ts'
+export type {
+  ChallengeName,
+  ChallengeType,
+  CaptchaTokenPayload,
+  CaptchaOptions,
+  IssueOptions,
+  IssuedChallenge,
+  VerifyResult,
+  FailureReason,
+} from './types.ts'

package/src/islands/pow.vue

@@ -0,0 +1,109 @@
+<script setup lang="ts">
+import { onMounted, ref } from 'vue'
+
+interface Props {
+  challenge: string
+  difficulty: number
+  tokenField?: string
+  responseField?: string
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  tokenField: '_captcha',
+  responseField: '_captcha_answer',
+})
+
+const status = ref<'idle' | 'solving' | 'solved' | 'error'>('idle')
+const elapsedMs = ref(0)
+
+onMounted(() => {
+  void solve()
+})
+
+async function solve() {
+  status.value = 'solving'
+  const start = performance.now()
+
+  try {
+    const nonce = await findNonce(props.challenge, props.difficulty)
+    elapsedMs.value = Math.round(performance.now() - start)
+    writeAnswer(nonce)
+    status.value = 'solved'
+  } catch (err) {
+    console.error('[captcha/pow] failed', err)
+    status.value = 'error'
+  }
+}
+
+/**
+ * Find a nonce N such that sha256(challenge + ':' + N) has at least
+ * `difficulty` leading zero bits. We try a counter — simple and easy to
+ * verify on the server with the same construction.
+ *
+ * Yields back to the event loop every 256 attempts so the page stays
+ * responsive on phones / weaker CPUs.
+ */
+async function findNonce(challenge: string, difficulty: number): Promise<string> {
+  if (typeof crypto === 'undefined' || !crypto.subtle) {
+    throw new Error('Web Crypto API unavailable')
+  }
+
+  const encoder = new TextEncoder()
+  let nonce = 0
+
+  while (true) {
+    for (let i = 0; i < 256; i++) {
+      const candidate = String(nonce++)
+      const buffer = await crypto.subtle.digest(
+        'SHA-256',
+        encoder.encode(challenge + ':' + candidate)
+      )
+      if (leadingZeroBits(new Uint8Array(buffer)) >= difficulty) {
+        return candidate
+      }
+    }
+    // Yield to keep the UI alive
+    await new Promise(resolve => setTimeout(resolve, 0))
+  }
+}
+
+function leadingZeroBits(bytes: Uint8Array): number {
+  let bits = 0
+  for (let i = 0; i < bytes.length; i++) {
+    const b = bytes[i]!
+    if (b === 0) {
+      bits += 8
+      continue
+    }
+    let n = b
+    while ((n & 0x80) === 0) {
+      bits++
+      n <<= 1
+    }
+    break
+  }
+  return bits
+}
+
+/**
+ * Write the nonce into the form's hidden answer field. We look up the
+ * nearest enclosing form and find the input by name — robust against
+ * forms that re-render or move the widget around.
+ */
+function writeAnswer(nonce: string) {
+  const root = document.querySelector(`[data-vue="captcha/pow"]`)
+  const form = root?.closest('form')
+  if (!form) return
+  const input = form.querySelector(`input[name="${props.responseField}"]`)
+  if (input instanceof HTMLInputElement) input.value = nonce
+}
+</script>
+
+<template>
+  <div class="captcha-pow" :data-status="status">
+    <span v-if="status === 'idle'" aria-hidden="true">⋯</span>
+    <span v-else-if="status === 'solving'">Verifying you're human…</span>
+    <span v-else-if="status === 'solved'" aria-live="polite">✓ Verified ({{ elapsedMs }}ms)</span>
+    <span v-else class="captcha-pow-error">Verification failed</span>
+  </div>
+</template>

package/src/islands/refresh.vue

@@ -0,0 +1,43 @@
+<script setup lang="ts">
+interface Props {
+  tokenField?: string
+  refreshUrl?: string
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  tokenField: '_captcha',
+  refreshUrl: '/__captcha/svg',
+})
+
+async function refresh() {
+  const response = await fetch(props.refreshUrl, { headers: { Accept: 'image/svg+xml' } })
+  if (!response.ok) return
+  const newToken = response.headers.get('X-Captcha-Token')
+  const svgBody = await response.text()
+
+  // Find the SVG sibling — refresh button is a span inside the
+  // `.captcha-svg` wrapper that also holds the SSR-rendered SVG.
+  const root = document.querySelector('[data-vue="captcha/refresh"]')
+  const wrapper = root?.parentElement
+  const oldSvg = wrapper?.querySelector('svg')
+  if (oldSvg) {
+    const tmp = document.createElement('div')
+    tmp.innerHTML = svgBody
+    const newSvg = tmp.querySelector('svg')
+    if (newSvg) oldSvg.replaceWith(newSvg)
+  }
+
+  // Update the hidden token in the same <form>.
+  if (newToken) {
+    const form = wrapper?.closest('form')
+    const input = form?.querySelector(`input[name="${props.tokenField}"]`)
+    if (input instanceof HTMLInputElement) input.value = newToken
+  }
+}
+</script>
+
+<template>
+  <button type="button" class="captcha-refresh" @click="refresh" aria-label="Refresh challenge">
+    ↻
+  </button>
+</template>

package/src/middleware.ts

@@ -0,0 +1,125 @@
+import type { Middleware, Context, Session } from '@strav/http'
+import { CacheManager } from '@strav/kernel'
+import type { CacheStore } from '@strav/kernel'
+import type { CaptchaOptions, FailureReason, ChallengeName } from './types.ts'
+import { DEFAULTS } from './types.ts'
+import { verifyChallenge } from './challenges.ts'
+import { consumeReplay } from './token.ts'
+
+/**
+ * Form/JSON guard. Place after `csrf()` and (optionally) after `rateLimit()`
+ * so cheap rejections don't even attempt CAPTCHA verification.
+ *
+ * @example
+ * router.post('/register', [
+ *   rateLimit({ window: 60_000, max: 5 }),
+ *   csrf(),
+ *   captcha({ types: ['honeypot', 'pow'] }),
+ * ], handler)
+ */
+export function captcha(options: CaptchaOptions = {}): Middleware {
+  const types = (options.types ?? ['honeypot', 'pow']) as ChallengeName[]
+  const honeypotField = options.honeypotField ?? DEFAULTS.honeypotField
+  const tokenField = options.tokenField ?? DEFAULTS.tokenField
+  const responseField = options.responseField ?? DEFAULTS.responseField
+
+  // Lazy default — calling CacheManager.store at module-load would throw
+  // when the captcha import lands before the container is wired.
+  const resolveStore = (): CacheStore => options.store ?? CacheManager.store
+
+  const useHoneypot = types.includes('honeypot')
+
+  return async (ctx, next) => {
+    if (options.skip?.(ctx)) return next()
+
+    // Only guard state-changing methods. GET/HEAD shouldn't carry forms.
+    if (['GET', 'HEAD', 'OPTIONS'].includes(ctx.method)) return next()
+
+    const body = await readBody(ctx)
+
+    if (useHoneypot) {
+      const trap = body[honeypotField]
+      if (typeof trap === 'string' && trap.trim() !== '') {
+        return failure(ctx, 'honeypot_tripped', body, options)
+      }
+    }
+
+    // If honeypot is the only requested type, we're done.
+    const challengeTypes = types.filter(t => t !== 'honeypot')
+    if (challengeTypes.length === 0) return next()
+
+    const token = typeof body[tokenField] === 'string' ? (body[tokenField] as string) : ''
+    if (!token) return failure(ctx, 'token_missing', body, options)
+
+    const result = verifyChallenge(token, body[responseField], body)
+    if (!result.ok) return failure(ctx, result.reason, body, options)
+
+    if (!challengeTypes.includes(result.payload.t)) {
+      // Token is valid but for a type this guard wasn't asked to accept —
+      // could happen if a challenge was issued for a different form.
+      return failure(ctx, 'token_invalid', body, options)
+    }
+
+    const fresh = await consumeReplay(resolveStore(), result.payload)
+    if (!fresh) return failure(ctx, 'replayed', body, options)
+
+    return next()
+  }
+}
+
+/**
+ * Read the parsed body without crashing on text/plain or empty bodies.
+ * Returns `{}` so callers can index without null-checks.
+ */
+async function readBody(ctx: Context): Promise<Record<string, unknown>> {
+  try {
+    const body = await ctx.body<unknown>()
+    return body && typeof body === 'object' ? (body as Record<string, unknown>) : {}
+  } catch {
+    return {}
+  }
+}
+
+async function failure(
+  ctx: Context,
+  reason: FailureReason,
+  body: Record<string, unknown>,
+  options: CaptchaOptions
+): Promise<Response> {
+  if (options.onFailure) return options.onFailure(ctx, reason)
+
+  if (wantsJson(ctx)) {
+    return ctx.json({ errors: { _captcha: [reason] } }, 422)
+  }
+
+  // Form path: flash errors + old input, redirect back to the referer
+  // (or root). Mirrors the convention used by `validate()` consumers.
+  const session = ctx.get<Session | undefined>('session')
+  if (session) {
+    session.flash('errors', { _captcha: [reason] })
+    session.flash('old', stripCaptchaFields(body, options))
+    await session.save()
+  }
+
+  const referer = ctx.header('referer') ?? '/'
+  return ctx.redirect(referer, 303)
+}
+
+function wantsJson(ctx: Context): boolean {
+  const accept = ctx.header('accept') ?? ''
+  if (accept.includes('application/json')) return true
+  if (ctx.header('x-requested-with') === 'XMLHttpRequest') return true
+  const contentType = ctx.header('content-type') ?? ''
+  return contentType.includes('application/json')
+}
+
+function stripCaptchaFields(
+  body: Record<string, unknown>,
+  options: CaptchaOptions
+): Record<string, unknown> {
+  const out = { ...body }
+  delete out[options.honeypotField ?? DEFAULTS.honeypotField]
+  delete out[options.tokenField ?? DEFAULTS.tokenField]
+  delete out[options.responseField ?? DEFAULTS.responseField]
+  return out
+}

package/src/registry.ts

@@ -0,0 +1,29 @@
+import type { ChallengeName, ChallengeType } from './types.ts'
+
+const registry = new Map<string, ChallengeType>()
+
+/**
+ * Register a challenge type so `issueChallenge()` / `verifyChallenge()` can
+ * dispatch to it. Built-ins (honeypot, pow, svg) self-register on first
+ * import of `./challenges.ts` — call this only when adding custom types.
+ *
+ * @example
+ * registerChallengeType({
+ *   name: 'slider',
+ *   issue: () => ({ props: { ... }, answer: '...' }),
+ *   verify: (payload, response) => response === payload.ah ? { ok: true } : { ok: false, reason: 'answer_mismatch' },
+ * })
+ */
+export function registerChallengeType(type: ChallengeType): void {
+  registry.set(type.name, type)
+}
+
+/** Look up a registered challenge type. Returns `undefined` if not registered. */
+export function getChallengeType(name: ChallengeName): ChallengeType | undefined {
+  return registry.get(name)
+}
+
+/** All registered type names — used by validators and refresh route allow-listing. */
+export function listChallengeTypes(): ChallengeName[] {
+  return Array.from(registry.keys())
+}

package/src/route.ts

@@ -0,0 +1,73 @@
+import type { Router, Context } from '@strav/http'
+import { rateLimit } from '@strav/http'
+import { issueChallenge } from './challenges.ts'
+import { listChallengeTypes } from './registry.ts'
+import type { ChallengeName } from './types.ts'
+
+/**
+ * Mount a refresh endpoint at `<prefix>/:type` so client-side widgets
+ * (e.g. the SVG refresh button) can request a new challenge without a
+ * full page reload. Stateless, no session required.
+ *
+ * Auto-rate-limited per IP — 30 issuances/minute by default. Override
+ * by passing your own `rateLimit()` middleware in `extraMiddleware`,
+ * or set `rateLimit: false` to disable (not recommended in production).
+ *
+ * @example
+ * mountCaptchaRoutes(router)
+ * // → GET /__captcha/svg, GET /__captcha/pow
+ */
+export function mountCaptchaRoutes(
+  router: Router,
+  options: {
+    prefix?: string
+    rateLimit?: false | { window?: number; max?: number }
+    extraMiddleware?: ReturnType<typeof rateLimit>[]
+  } = {}
+): void {
+  const prefix = options.prefix ?? '/__captcha'
+
+  const middleware = []
+  if (options.extraMiddleware?.length) {
+    middleware.push(...options.extraMiddleware)
+  } else if (options.rateLimit !== false) {
+    middleware.push(
+      rateLimit({
+        window: options.rateLimit?.window ?? 60_000,
+        max: options.rateLimit?.max ?? 30,
+      })
+    )
+  }
+
+  router.group({ prefix, middleware }, r => {
+    r.get('/:type', async (ctx: Context) => {
+      const type = ctx.params.type as ChallengeName
+      if (!listChallengeTypes().includes(type)) {
+        return ctx.json({ error: 'Unknown challenge type' }, 404)
+      }
+
+      const issued = issueChallenge(type)
+
+      // SVG type returns the image directly — easy <img src=…> embed.
+      // Other types return JSON so the client can hydrate its own widget.
+      if (type === 'svg' && issued.html) {
+        return new Response(issued.html, {
+          status: 200,
+          headers: {
+            'Content-Type': 'image/svg+xml',
+            'Cache-Control': 'no-store',
+            // Pass the token via header so the client can stash it without
+            // re-parsing the SVG body. Browsers expose this on fetch responses.
+            'X-Captcha-Token': issued.token,
+          },
+        })
+      }
+
+      return ctx.json({
+        token: issued.token,
+        props: issued.props,
+        html: issued.html,
+      })
+    })
+  })
+}

package/src/token.ts

@@ -0,0 +1,95 @@
+import { encrypt } from '@strav/kernel'
+import type { CacheStore } from '@strav/kernel'
+import type { CaptchaTokenPayload, FailureReason } from './types.ts'
+
+const REPLAY_PREFIX = 'captcha:used:'
+
+/**
+ * Hash an answer with its per-challenge salt. The salt prevents a global
+ * rainbow-table on common SVG answers (`abcd12`, `1234`, …) and ensures
+ * two challenges with the same plaintext answer produce different hashes.
+ *
+ * Lowercase + trim is the canonical normalization — matches what the
+ * SVG/math verifiers do at compare time.
+ */
+export function hashAnswer(answer: string, salt: string): string {
+  return encrypt.sha256(answer.toLowerCase().trim() + salt)
+}
+
+/** Constant-time string equality on hex digests. */
+export function safeEqual(a: string, b: string): boolean {
+  if (a.length !== b.length) return false
+  let diff = 0
+  for (let i = 0; i < a.length; i++) {
+    diff |= a.charCodeAt(i) ^ b.charCodeAt(i)
+  }
+  return diff === 0
+}
+
+/**
+ * Seal a payload (sets iat/jti automatically). The salt and answer hash
+ * must already be in `data` — the caller (`challenges.ts`) computes them
+ * because only it knows the challenge type's normalize rules.
+ */
+export function sealToken(data: Omit<CaptchaTokenPayload, 'v' | 'iat' | 'jti'>): {
+  token: string
+  payload: CaptchaTokenPayload
+} {
+  const payload: CaptchaTokenPayload = {
+    v: 1,
+    iat: Date.now(),
+    jti: encrypt.random(16),
+    ...data,
+  }
+  return { token: encrypt.seal(payload), payload }
+}
+
+/**
+ * Decode a sealed token. Returns the payload, or a failure reason that
+ * the verifier can short-circuit on (invalid seal, expired).
+ *
+ * Replay prevention happens at `consumeReplay()` — splitting the steps
+ * lets the verifier check the answer first and only burn the replay slot
+ * on success.
+ */
+export function unsealToken(
+  token: string
+): { ok: true; payload: CaptchaTokenPayload } | { ok: false; reason: FailureReason } {
+  let payload: CaptchaTokenPayload
+  try {
+    payload = encrypt.unseal<CaptchaTokenPayload>(token)
+  } catch {
+    return { ok: false, reason: 'token_invalid' }
+  }
+
+  if (!payload || payload.v !== 1 || typeof payload.iat !== 'number') {
+    return { ok: false, reason: 'token_invalid' }
+  }
+
+  if (Date.now() > payload.iat + payload.exp * 60_000) {
+    return { ok: false, reason: 'token_expired' }
+  }
+
+  return { ok: true, payload }
+}
+
+/**
+ * Mark a token as used. Returns false if the slot was already taken
+ * (replay), true on the first successful use.
+ *
+ * The cache TTL matches the token's remaining lifetime so we don't keep
+ * dead replay keys around. After expiry the token is rejected by
+ * `unsealToken` regardless, so no leak.
+ */
+export async function consumeReplay(
+  store: CacheStore,
+  payload: CaptchaTokenPayload
+): Promise<boolean> {
+  const key = REPLAY_PREFIX + payload.jti
+  if (await store.has(key)) return false
+
+  const remainingMs = payload.iat + payload.exp * 60_000 - Date.now()
+  const ttlSeconds = Math.max(1, Math.ceil(remainingMs / 1000))
+  await store.set(key, 1, ttlSeconds)
+  return true
+}

package/src/types.ts

@@ -0,0 +1,135 @@
+import type { CacheStore } from '@strav/kernel'
+import type { Middleware } from '@strav/http'
+
+/** Built-in challenge type names. Extensible via `registerChallengeType()`. */
+export type ChallengeName = 'honeypot' | 'pow' | 'svg' | (string & {})
+
+/**
+ * Reasons a CAPTCHA verification can fail. Surfaced to `onFailure` and
+ * (when JSON) returned to the client so the form can display targeted help.
+ */
+export type FailureReason =
+  | 'token_missing'
+  | 'token_invalid'
+  | 'token_expired'
+  | 'answer_mismatch'
+  | 'replayed'
+  | 'honeypot_tripped'
+  | 'pow_insufficient'
+  | 'unknown_type'
+
+/**
+ * Sealed payload carried in the `_captcha` form field. Stateless — the
+ * server reconstructs everything from this token at verify time. The salt
+ * `s` makes brute-forcing the answer hash impractical even if the seal is
+ * cracked; `jti` is the replay cache key so a token can only succeed once.
+ */
+export interface CaptchaTokenPayload {
+  /** Schema version. Bump on breaking changes. */
+  v: 1
+  /** Challenge type — chooses the verifier. */
+  t: ChallengeName
+  /** sha256(normalize(answer) + salt) — omitted for honeypot. */
+  ah?: string
+  /** Random per-challenge salt (hex). Hashed with the answer. */
+  s: string
+  /** PoW difficulty in leading zero bits. Only set when `t === 'pow'`. */
+  d?: number
+  /** Issued-at, ms since epoch. */
+  iat: number
+  /** Expiry duration in minutes. */
+  exp: number
+  /** Replay cache key — a hex random per challenge. */
+  jti: string
+}
+
+/** What `issueChallenge()` hands back — token + render data for the form. */
+export interface IssuedChallenge {
+  /** Sealed token to embed in a hidden form field. */
+  token: string
+  /** Type-specific data the renderer needs (e.g. `{ challenge, difficulty }`). */
+  props: Record<string, unknown>
+  /** Optional pre-rendered HTML/SVG (used by `svg`). */
+  html?: string
+}
+
+/** Options passed to `issueChallenge()`. */
+export interface IssueOptions {
+  /** Override default expiry. */
+  ttlMinutes?: number
+  /** PoW only — leading zero bits. */
+  difficulty?: number
+}
+
+/** Result of `verifyChallenge()`. `ok: true` consumes the replay slot. */
+export type VerifyResult =
+  | { ok: true; payload: CaptchaTokenPayload }
+  | { ok: false; reason: FailureReason }
+
+/**
+ * A challenge type plugged into the registry. `verify` receives the
+ * decoded payload plus the user's response and the current cache, and
+ * returns either ok or a `FailureReason`.
+ */
+export interface ChallengeType {
+  name: ChallengeName
+  /**
+   * Build a fresh challenge. Returns the props the renderer needs and the
+   * data that gets sealed into the token (answer hash + any type-specific
+   * extras like PoW difficulty). Receives the per-challenge salt so types
+   * like PoW can expose it to the client as the challenge value (PoW
+   * verifies `sha256(payload.s + ':' + nonce)` so client and server need
+   * to agree on the salt).
+   */
+  issue(opts: IssueOptions & { salt: string }): {
+    props: Record<string, unknown>
+    /** Extra fields merged into the token payload (e.g. `{ d: difficulty }`). */
+    extra?: Partial<Pick<CaptchaTokenPayload, 'd'>>
+    /** Plaintext answer the user is expected to produce — hashed with salt before sealing. */
+    answer?: string
+    /** Optional pre-rendered HTML (e.g. SVG body). */
+    html?: string
+  }
+  /**
+   * Verify the response against the sealed payload. Pure function — replay
+   * prevention happens upstream, not here.
+   */
+  verify(
+    payload: CaptchaTokenPayload,
+    response: unknown,
+    body: Record<string, unknown>
+  ): { ok: true } | { ok: false; reason: FailureReason }
+}
+
+/** Options for the `captcha()` middleware. */
+export interface CaptchaOptions {
+  /** Challenge types accepted by this guard. @default ['honeypot', 'pow'] */
+  types?: ChallengeName[]
+  /** Hidden field bots fill in. @default 'website' */
+  honeypotField?: string
+  /** Form field carrying the sealed token. @default '_captcha' */
+  tokenField?: string
+  /** Form field carrying the user's answer / nonce. @default '_captcha_answer' */
+  responseField?: string
+  /** PoW difficulty in leading zero bits. @default 18 */
+  difficulty?: number
+  /** Token lifetime in minutes. @default 10 */
+  ttlMinutes?: number
+  /** Skip the guard for matching requests (e.g. internal health checks). */
+  skip?: (ctx: Parameters<Middleware>[0]) => boolean
+  /** Custom failure response. Falls back to JSON 422 / flash-redirect. */
+  onFailure?: (
+    ctx: Parameters<Middleware>[0],
+    reason: FailureReason
+  ) => Response | Promise<Response>
+  /** Cache store for replay prevention. Defaults to `CacheManager.store`. */
+  store?: CacheStore
+}
+
+export const DEFAULTS = {
+  honeypotField: 'website',
+  tokenField: '_captcha',
+  responseField: '_captcha_answer',
+  difficulty: 18,
+  ttlMinutes: 10,
+} as const

package/src/validation_rule.ts

@@ -0,0 +1,31 @@
+import type { Rule } from '@strav/http'
+import { verifyChallenge } from './challenges.ts'
+
+/**
+ * Validation rule for handlers that prefer `validate()` integration over
+ * the middleware. Bind the user's response (and optionally the full body
+ * for honeypot/extension checks) when constructing the rule — closure
+ * keeps it per-request, no shared mutable state.
+ *
+ * NOTE: this rule does not perform replay prevention — `validate()` is
+ * sync and has no place to read a cache store. For replay-safe checks
+ * use the `captcha()` middleware. The rule fits idempotent endpoints
+ * where double-submit is harmless.
+ *
+ * @example
+ * const body = await ctx.body<Record<string, unknown>>()
+ * const { errors } = validate(body, {
+ *   _captcha: [captchaRule(body._captcha_answer, body)],
+ *   email: [required(), email()],
+ * })
+ */
+export function captchaRule(response: unknown, body?: Record<string, unknown>): Rule {
+  return {
+    name: 'captcha',
+    validate(value) {
+      const token = typeof value === 'string' ? value : ''
+      const result = verifyChallenge(token, response, body ?? {})
+      return result.ok ? null : `captcha.${result.reason}`
+    },
+  }
+}

package/src/view_helper.ts

@@ -0,0 +1,105 @@
+import { ViewEngine } from '@strav/view'
+import { issueChallenge } from './challenges.ts'
+import { DEFAULTS } from './types.ts'
+
+/**
+ * Default field names. Kept on the helper itself so a single config
+ * point flows into both middleware and template rendering — change
+ * these and `@captcha` re-emits matching field names automatically.
+ */
+const config = {
+  honeypotField: DEFAULTS.honeypotField,
+  tokenField: DEFAULTS.tokenField,
+  responseField: DEFAULTS.responseField,
+  difficulty: DEFAULTS.difficulty,
+  ttlMinutes: DEFAULTS.ttlMinutes,
+}
+
+/**
+ * Optionally configure helper-side defaults so the markup matches the
+ * server-side `captcha()` middleware options. Required only when an app
+ * customizes field names — defaults match middleware defaults.
+ *
+ * @example
+ * configureCaptchaHelper({ honeypotField: 'phone_number' })
+ */
+export function configureCaptchaHelper(opts: Partial<typeof config>): void {
+  Object.assign(config, opts)
+}
+
+/**
+ * Render the form fragment for a challenge. Returns ready-to-emit HTML
+ * including the honeypot, the hidden token, and (for visible types) the
+ * answer input + island/SVG.
+ *
+ * Synchronous: `issueChallenge` is sync, the renderer just concatenates
+ * strings — safe to call from inside the template render loop.
+ */
+export function captchaHelper(variant?: string): string {
+  const honeypot = renderHoneypot()
+
+  if (!variant || variant === 'honeypot') return honeypot
+
+  if (variant === 'pow') {
+    const issued = issueChallenge('pow', { difficulty: config.difficulty, ttlMinutes: config.ttlMinutes })
+    const props = JSON.stringify({
+      ...issued.props,
+      tokenField: config.tokenField,
+      responseField: config.responseField,
+    }).replace(/'/g, '&#39;')
+    return (
+      honeypot +
+      `<input type="hidden" name="${attr(config.tokenField)}" value="${attr(issued.token)}">` +
+      `<input type="hidden" name="${attr(config.responseField)}" value="">` +
+      `<div data-vue="captcha/pow" data-props='${props}'></div>`
+    )
+  }
+
+  if (variant === 'svg') {
+    const issued = issueChallenge('svg', { ttlMinutes: config.ttlMinutes })
+    const refreshProps = JSON.stringify({ tokenField: config.tokenField }).replace(/'/g, '&#39;')
+    return (
+      honeypot +
+      `<input type="hidden" name="${attr(config.tokenField)}" value="${attr(issued.token)}">` +
+      `<div class="captcha-svg">` +
+      (issued.html ?? '') +
+      // Sibling-not-child: the Vue island replaces this element's content,
+      // but the SVG above stays untouched until the user clicks refresh.
+      `<span data-vue="captcha/refresh" data-props='${refreshProps}'></span>` +
+      `</div>` +
+      `<input type="text" name="${attr(config.responseField)}" autocomplete="off" ` +
+      `inputmode="latin" autocapitalize="characters" required aria-label="Type the characters shown">`
+    )
+  }
+
+  throw new Error(`@captcha: unknown variant "${variant}" (expected 'pow' | 'svg' | 'honeypot' or none)`)
+}
+
+function renderHoneypot(): string {
+  const name = attr(config.honeypotField)
+  // Triple defense: aria-hidden, tabindex=-1, off-screen via inline style.
+  // Don't use `display:none` — some bots skip those fields.
+  return (
+    `<div aria-hidden="true" style="position:absolute;left:-9999px;top:auto;width:1px;height:1px;overflow:hidden">` +
+    `<label for="${name}">Leave this field empty</label>` +
+    `<input type="text" id="${name}" name="${name}" tabindex="-1" autocomplete="off" value="">` +
+    `</div>`
+  )
+}
+
+function attr(s: string): string {
+  return s.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;')
+}
+
+/**
+ * Wire `__captcha(variant)` into the view engine so `@captcha` works.
+ * Call once at boot, after ViewEngine is constructed.
+ *
+ * @example
+ * import { installCaptchaHelpers } from '@strav/captcha'
+ * // …after ViewEngine is registered in the container
+ * installCaptchaHelpers()
+ */
+export function installCaptchaHelpers(): void {
+  ViewEngine.setGlobal('__captcha', captchaHelper)
+}

package/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "../../tsconfig.json",
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules", "tests"]
+}