@strav/captcha 0.4.31 → 1.0.0-alpha.42

package/src/islands/pow.vue

@@ -1,109 +0,0 @@
-<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

@@ -1,43 +0,0 @@
-<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

@@ -1,125 +0,0 @@
-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/route.ts

@@ -1,73 +0,0 @@
-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/validation_rule.ts

@@ -1,31 +0,0 @@
-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

@@ -1,105 +0,0 @@
-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

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