@strav/captcha 0.4.31 → 1.0.0-alpha.43

package/README.md

@@ -0,0 +1,9 @@
+# @strav/captcha
+
+Stateless CAPTCHA primitives for Strav 1.0 — honeypot, proof-of-work,
+distorted-text SVG. HMAC-signed tokens, pluggable challenge registry,
+HTTP middleware + validation rule + refresh routes under
+`@strav/captcha/http`, view helper under `@strav/captcha/view`.
+
+See [docs/captcha/](../../docs/captcha/) for the full guide and API
+reference.

package/package.json

@@ -1,31 +1,40 @@
 {
   "name": "@strav/captcha",
-  "version": "0.4.31",
+  "version": "1.0.0-alpha.43",
+  "description": "Strav CAPTCHA primitive — stateless HMAC-signed tokens + pluggable challenge registry. Ships honeypot, hashcash-style proof of work, and inline-SVG distorted-text challenges in the root, with HTTP middleware + validation rule + refresh routes under @strav/captcha/http and a view helper under @strav/captcha/view.",
   "type": "module",
-  "description": "Built-in CAPTCHA for the Strav framework — honeypot, proof-of-work, and SVG text challenges with no external dependencies",
-  "license": "MIT",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
   "exports": {
     ".": "./src/index.ts",
-    "./*": "./src/*.ts"
-  },
-  "strav": {
-    "islands": {
-      "namespace": "captcha",
-      "dir": "./src/islands"
-    }
+    "./http": "./src/http/index.ts",
+    "./view": "./src/view/index.ts"
   },
   "files": [
-    "src/",
-    "package.json",
-    "tsconfig.json"
+    "src",
+    "README.md"
   ],
+  "engines": {
+    "bun": ">=1.3.14"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@strav/kernel": "1.0.0-alpha.43"
+  },
   "peerDependencies": {
-    "@strav/kernel": "0.4.31",
-    "@strav/http": "0.4.31",
-    "@strav/view": "0.4.31"
+    "@strav/cache": "1.0.0-alpha.43",
+    "@strav/http": "1.0.0-alpha.43",
+    "@types/bun": ">=1.3.14"
+  },
+  "peerDependenciesMeta": {
+    "@strav/cache": {
+      "optional": true
+    },
+    "@strav/http": {
+      "optional": true
+    }
   },
-  "scripts": {
-    "test": "bun test tests/",
-    "typecheck": "tsc --noEmit"
-  }
+  "devDependencies": null
 }

package/src/captcha_error.ts

@@ -0,0 +1,14 @@
+import { StravError, type StravErrorOptions } from '@strav/kernel'
+
+/**
+ * Misconfiguration of `@strav/captcha` — missing secret, unknown
+ * challenge type registered, etc.
+ *
+ * Verification *failures* are NOT exceptions — they return
+ * `{ ok: false, reason }` so callers can surface targeted form errors.
+ */
+export class CaptchaError extends StravError {
+  constructor(message: string, options: StravErrorOptions = {}) {
+    super(message, { code: 'captcha-error', status: 500 }, options)
+  }
+}

package/src/captcha_manager.ts

@@ -0,0 +1,132 @@
+/**
+ * `CaptchaManager` — the DI-resolved unit that holds the signing
+ * secret + challenge registry and exposes `issue`/`verify`. The HTTP
+ * middleware and validation rule (in `./http/`) and the view helper
+ * (in `./view/`) resolve it from the container.
+ *
+ * Replay prevention is a separate concern from verification: a cache is
+ * optional on the manager so apps that only use the validation rule
+ * (idempotent endpoints, single-shot tokens) don't need to wire one.
+ * The middleware DOES require it — see `./http/captcha_middleware.ts`.
+ */
+
+import { honeypotChallenge } from './challenges/honeypot_challenge.ts'
+import { powChallenge } from './challenges/pow_challenge.ts'
+import { svgChallenge } from './challenges/svg_challenge.ts'
+import { CaptchaError } from './captcha_error.ts'
+import { ChallengeRegistry } from './registry.ts'
+import { hashAnswer, randomHex, signToken, verifyToken } from './token.ts'
+import {
+  DEFAULTS,
+  type CaptchaConfig,
+  type CaptchaTokenPayload,
+  type ChallengeName,
+  type ChallengeType,
+  type IssueOptions,
+  type IssuedChallenge,
+  type VerifyResult,
+} from './types.ts'
+
+export interface CaptchaManagerOptions {
+  config: CaptchaConfig
+}
+
+export class CaptchaManager {
+  readonly registry = new ChallengeRegistry()
+  readonly config: Required<Omit<CaptchaConfig, 'secret'>> & { secret: string | Uint8Array }
+
+  constructor(opts: CaptchaManagerOptions) {
+    if (!opts.config?.secret) {
+      throw new CaptchaError(
+        'CaptchaManager: `config.secret` is required (HMAC signing key, ≥ 32 bytes of entropy).',
+        { code: 'captcha.missing-secret' },
+      )
+    }
+    this.config = {
+      secret: opts.config.secret,
+      honeypotField: opts.config.honeypotField ?? DEFAULTS.honeypotField,
+      tokenField: opts.config.tokenField ?? DEFAULTS.tokenField,
+      responseField: opts.config.responseField ?? DEFAULTS.responseField,
+      difficulty: opts.config.difficulty ?? DEFAULTS.difficulty,
+      ttlMinutes: opts.config.ttlMinutes ?? DEFAULTS.ttlMinutes,
+    }
+    this.registry.register(honeypotChallenge)
+    this.registry.register(powChallenge)
+    this.registry.register(svgChallenge)
+  }
+
+  /** Register a custom challenge type. */
+  register(type: ChallengeType): void {
+    this.registry.register(type)
+  }
+
+  /** All registered type names. */
+  listTypes(): ChallengeName[] {
+    return this.registry.list()
+  }
+
+  /**
+   * Issue a fresh challenge. Synchronous — sign + 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.
+   */
+  issue(type: ChallengeName, opts: IssueOptions = {}): IssuedChallenge {
+    const challenge = this.registry.get(type)
+    const ttlMinutes = opts.ttlMinutes ?? this.config.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 = randomHex(16)
+
+    const issued = challenge.issue({
+      ...opts,
+      difficulty: opts.difficulty ?? this.config.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 } = signToken(this.config.secret, tokenData)
+
+    return {
+      token,
+      props: issued.props,
+      ...(issued.html !== undefined ? { html: issued.html } : {}),
+    }
+  }
+
+  /**
+   * Decode and verify a token + the user's response. Pure: no cache
+   * writes, no I/O. Replay prevention happens upstream in the middleware
+   * (after we know verification passed) so failed attempts don't burn
+   * the replay slot.
+   */
+  verify(
+    token: string | undefined | null,
+    response: unknown,
+    body: Record<string, unknown> = {},
+  ): VerifyResult {
+    if (!token || typeof token !== 'string') {
+      return { ok: false, reason: 'token_missing' }
+    }
+
+    const decoded = verifyToken(this.config.secret, token)
+    if (!decoded.ok) return decoded
+
+    if (!this.registry.has(decoded.payload.t)) {
+      return { ok: false, reason: 'unknown_type' }
+    }
+    const challenge = this.registry.get(decoded.payload.t)
+    const result = challenge.verify(decoded.payload, response, body)
+    if (!result.ok) return result
+
+    return { ok: true, payload: decoded.payload }
+  }
+}

package/src/captcha_provider.ts

@@ -0,0 +1,49 @@
+/**
+ * `CaptchaProvider` — registers `CaptchaManager` under its own token,
+ * reading config from `config.captcha`. Apps that want to pre-register
+ * custom challenge types can pass a `define` hook.
+ *
+ *   new CaptchaProvider({
+ *     define(captcha) {
+ *       captcha.register(myCustomChallenge)
+ *     },
+ *   })
+ */
+
+import { type Application, ConfigRepository, ServiceProvider } from '@strav/kernel'
+import { CaptchaError } from './captcha_error.ts'
+import { CaptchaManager } from './captcha_manager.ts'
+import type { CaptchaConfig } from './types.ts'
+
+export interface CaptchaProviderOptions {
+  /** Hook invoked at boot, after the manager is created. */
+  define?: (captcha: CaptchaManager) => void | Promise<void>
+}
+
+export class CaptchaProvider extends ServiceProvider {
+  override readonly name = 'captcha'
+  override readonly dependencies = ['config']
+
+  constructor(private readonly options: CaptchaProviderOptions = {}) {
+    super()
+  }
+
+  override register(app: Application): void {
+    app.singleton(CaptchaManager, (c) => {
+      const cfg = c.resolve(ConfigRepository).get('captcha') as CaptchaConfig | undefined
+      if (!cfg) {
+        throw new CaptchaError(
+          'CaptchaProvider: missing `config.captcha`. Add a `captcha` config slice with at least `{ secret: env.required("APP_KEY") }`.',
+          { code: 'captcha.missing-config' },
+        )
+      }
+      return new CaptchaManager({ config: cfg })
+    })
+  }
+
+  override async boot(app: Application): Promise<void> {
+    if (this.options.define) {
+      await this.options.define(app.resolve(CaptchaManager))
+    }
+  }
+}

package/src/challenges/{honeypot.ts → honeypot_challenge.ts}

@@ -1,14 +1,14 @@
 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.
+ * Invisible-field honeypot. The view helper injects a hidden input that
+ * humans never see; bots that auto-fill every field on the page 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.
+ * 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',

package/src/challenges/{pow.ts → pow_challenge.ts}

@@ -1,6 +1,5 @@
-import { encrypt } from '@strav/kernel'
-import type { ChallengeType } from '../types.ts'
-import { DEFAULTS } from '../types.ts'
+import { createHash } from 'node:crypto'
+import { DEFAULTS, type ChallengeType } from '../types.ts'
 
 /**
  * Hashcash-style proof of work. The client must find a nonce such that
@@ -27,13 +26,12 @@ export const powChallenge: ChallengeType = {
     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)
+    const difficulty = payload.d ?? DEFAULTS.difficulty
+    const digest = createHash('sha256').update(`${payload.s}:${response}`).digest('hex')
     if (countLeadingZeroBits(digest) < difficulty) {
       return { ok: false, reason: 'pow_insufficient' }
     }
@@ -48,7 +46,9 @@ export const powChallenge: ChallengeType = {
 export function countLeadingZeroBits(hex: string): number {
   let bits = 0
   for (let i = 0; i < hex.length; i++) {
-    const nibble = parseInt(hex[i]!, 16)
+    const ch = hex[i]!
+    const nibble = Number.parseInt(ch, 16)
+    if (Number.isNaN(nibble)) break
     if (nibble === 0) {
       bits += 4
       continue

package/src/challenges/{svg.ts → svg_challenge.ts}

@@ -1,6 +1,6 @@
-import { encrypt } from '@strav/kernel'
-import type { ChallengeType } from '../types.ts'
+import { randomBytes } from 'node:crypto'
 import { hashAnswer, safeEqual } from '../token.ts'
+import type { ChallengeType } from '../types.ts'
 
 const ALPHABET = 'ABCDEFGHJKLMNPQRSTUVWXYZ23456789' // no 0/O/I/1
 const LENGTH = 6
@@ -44,7 +44,7 @@ export const svgChallenge: ChallengeType = {
 
 /** Pick `n` characters from the confusables-pruned alphabet. */
 function randomCode(n: number): string {
-  const bytes = encrypt.randomBytes(n)
+  const bytes = randomBytes(n)
   let out = ''
   for (let i = 0; i < n; i++) {
     out += ALPHABET[bytes[i]! % ALPHABET.length]
@@ -53,14 +53,11 @@ function randomCode(n: number): string {
 }
 
 /**
- * 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.
+ * Build the SVG body for a code. The jitter uses `Math.random()` — it's
+ * fine because security comes from the answer hash, not from making the
+ * SVG unpredictable.
  */
 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
@@ -76,7 +73,7 @@ export function renderSvg(code: string): string {
       `<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>`
+        `${ch}</text>`,
     )
   }
 
@@ -89,7 +86,7 @@ export function renderSvg(code: string): string {
     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" />`
+      `<line x1="${x1.toFixed(1)}" y1="${y1.toFixed(1)}" x2="${x2.toFixed(1)}" y2="${y2.toFixed(1)}" stroke="${stroke}" stroke-width="1.5" />`,
     )
   }
 

package/src/http/captcha_middleware.ts

@@ -0,0 +1,99 @@
+/**
+ * `captcha()` — form/JSON guard middleware. Place after `csrf()` and
+ * (optionally) after a rate limiter so cheap rejections never reach the
+ * CAPTCHA verifier.
+ *
+ *   router.post('/register', [
+ *     csrf(),
+ *     captcha({ types: ['honeypot', 'pow'] }),
+ *   ], handler)
+ *
+ * The middleware resolves a `CaptchaManager` and `Cache` from the
+ * request-scoped container. Apps that opt out of replay prevention
+ * (idempotent endpoints) should use the validation rule instead.
+ */
+
+import { Cache } from '@strav/cache'
+import type { HttpContext, MiddlewareFn } from '@strav/http'
+import { CaptchaManager } from '../captcha_manager.ts'
+import { consumeReplay } from '../replay.ts'
+import type { ChallengeName, FailureReason } from '../types.ts'
+
+export interface CaptchaMiddlewareOptions {
+  /** Challenge types accepted by this guard. @default ['honeypot', 'pow'] */
+  types?: ChallengeName[]
+  /** Override the field names from the manager config. */
+  honeypotField?: string
+  tokenField?: string
+  responseField?: string
+  /** Skip the guard for matching requests (e.g. internal health checks). */
+  skip?: (ctx: HttpContext) => boolean | Promise<boolean>
+  /** Custom failure response. Falls back to JSON 422. */
+  onFailure?: (ctx: HttpContext, reason: FailureReason) => Response | Promise<Response>
+}
+
+export function captcha(options: CaptchaMiddlewareOptions = {}): MiddlewareFn {
+  const types = (options.types ?? ['honeypot', 'pow']) as ChallengeName[]
+  const useHoneypot = types.includes('honeypot')
+  const challengeTypes = types.filter((t) => t !== 'honeypot')
+
+  return async (ctx, next) => {
+    if (await options.skip?.(ctx)) return next()
+
+    // Only guard state-changing methods. GET/HEAD shouldn't carry forms.
+    const method = ctx.request.method.toUpperCase()
+    if (method === 'GET' || method === 'HEAD' || method === 'OPTIONS') return next()
+
+    const manager = ctx.container.resolve(CaptchaManager)
+    const honeypotField = options.honeypotField ?? manager.config.honeypotField
+    const tokenField = options.tokenField ?? manager.config.tokenField
+    const responseField = options.responseField ?? manager.config.responseField
+
+    const body = await readBody(ctx)
+
+    if (useHoneypot) {
+      const trap = body[honeypotField]
+      if (typeof trap === 'string' && trap.trim() !== '') {
+        return failure(ctx, 'honeypot_tripped', options)
+      }
+    }
+
+    if (challengeTypes.length === 0) return next()
+
+    const token = typeof body[tokenField] === 'string' ? (body[tokenField] as string) : ''
+    if (!token) return failure(ctx, 'token_missing', options)
+
+    const result = manager.verify(token, body[responseField], body)
+    if (!result.ok) return failure(ctx, result.reason, options)
+
+    if (!challengeTypes.includes(result.payload.t)) {
+      // Token is valid but for a type this guard wasn't asked to accept —
+      // happens when a challenge was issued for a different form.
+      return failure(ctx, 'token_invalid', options)
+    }
+
+    const cache = ctx.container.resolve(Cache)
+    const fresh = await consumeReplay(cache, result.payload)
+    if (!fresh) return failure(ctx, 'replayed', options)
+
+    return next()
+  }
+}
+
+async function readBody(ctx: HttpContext): Promise<Record<string, unknown>> {
+  try {
+    const body = await ctx.request.input()
+    return body && typeof body === 'object' ? (body as Record<string, unknown>) : {}
+  } catch {
+    return {}
+  }
+}
+
+async function failure(
+  ctx: HttpContext,
+  reason: FailureReason,
+  options: CaptchaMiddlewareOptions,
+): Promise<Response> {
+  if (options.onFailure) return options.onFailure(ctx, reason)
+  return ctx.response.json({ errors: { _captcha: [reason] } }, { status: 422 })
+}

package/src/http/captcha_rule.ts

@@ -0,0 +1,49 @@
+/**
+ * Validation rule — `rule.custom('captcha')` integration for `FormRequest`.
+ *
+ * Register once at boot:
+ *
+ *   import { registerCaptchaRule } from '@strav/captcha/http'
+ *   registerCaptchaRule()
+ *
+ * Then reference in a `FormRequest`:
+ *
+ *   rules() {
+ *     return {
+ *       _captcha: rule.custom('captcha'),
+ *       email: rule.string().email(),
+ *     }
+ *   }
+ *
+ * NOTE: the rule does NOT perform replay prevention (`FormRequest`
+ * validation runs before route handlers and may be re-run on retry).
+ * For replay-safe checks use the `captcha()` middleware. The rule fits
+ * idempotent endpoints where double-submit is harmless.
+ */
+
+import { registerRule } from '@strav/http'
+import { CaptchaManager } from '../captcha_manager.ts'
+
+/**
+ * Register the `captcha` rule on the http rule registry. Idempotent —
+ * safe to call from boot in both production and tests.
+ */
+export function registerCaptchaRule(): void {
+  registerRule<unknown>('captcha', async (value, ctx) => {
+    const manager = ctx.container.resolve(CaptchaManager)
+    const token = typeof value === 'string' ? value : ''
+    const body = (await safeInput(ctx)) ?? {}
+    const responseField = manager.config.responseField
+    const result = manager.verify(token, body[responseField], body)
+    return result.ok ? true : `captcha.${result.reason}`
+  })
+}
+
+async function safeInput(ctx: Parameters<Parameters<typeof registerRule>[1]>[1]): Promise<Record<string, unknown> | undefined> {
+  try {
+    const body = await ctx.request.input()
+    return body && typeof body === 'object' ? (body as Record<string, unknown>) : undefined
+  } catch {
+    return undefined
+  }
+}

package/src/http/index.ts

@@ -0,0 +1,5 @@
+// `@strav/captcha/http` — middleware, validation rule, refresh routes.
+
+export { captcha, type CaptchaMiddlewareOptions } from './captcha_middleware.ts'
+export { registerCaptchaRule } from './captcha_rule.ts'
+export { mountCaptchaRoutes, type MountCaptchaRoutesOptions } from './refresh_routes.ts'

package/src/http/refresh_routes.ts

@@ -0,0 +1,59 @@
+/**
+ * `mountCaptchaRoutes(router)` — refresh endpoint at `<prefix>/:type` so
+ * client-side widgets can request a new challenge without a full page
+ * reload. Stateless, no session required.
+ *
+ *   mountCaptchaRoutes(router)
+ *   // → GET /__captcha/svg, GET /__captcha/pow
+ *
+ * The route handler resolves `CaptchaManager` from the per-request
+ * container. Layer your own rate-limit middleware on the group prefix —
+ * this package doesn't ship one (a leaky-bucket rate limiter is the
+ * caller's concern).
+ */
+
+import type { Router } from '@strav/http'
+import { CaptchaManager } from '../captcha_manager.ts'
+import type { ChallengeName } from '../types.ts'
+
+export interface MountCaptchaRoutesOptions {
+  /** URL prefix. @default '/__captcha' */
+  prefix?: string
+}
+
+export function mountCaptchaRoutes(router: Router, options: MountCaptchaRoutesOptions = {}): void {
+  const prefix = options.prefix ?? '/__captcha'
+
+  router.group({ prefix }, (r) => {
+    r.get('/:type', (ctx) => {
+      const manager = ctx.container.resolve(CaptchaManager)
+      const type = ctx.request.params.type as ChallengeName | undefined
+      if (!type || !manager.registry.has(type)) {
+        return ctx.response.json({ error: 'Unknown challenge type' }, { status: 404 })
+      }
+
+      const issued = manager.issue(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.
+            'X-Captcha-Token': issued.token,
+          },
+        })
+      }
+
+      return ctx.response.json({
+        token: issued.token,
+        props: issued.props,
+        html: issued.html,
+      })
+    })
+  })
+}

package/src/index.ts

@@ -1,44 +1,27 @@
-// 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
+// Public API of @strav/captcha.
+//
+// Root barrel exports the manager + provider + types + token + replay
+// + challenge primitives. Integrations ship under subpaths:
+//   - `@strav/captcha/http`  (middleware, validation rule, refresh routes)
+//   - `@strav/captcha/view`  (form-fragment helper for view.globals)
+
+export { honeypotChallenge } from './challenges/honeypot_challenge.ts'
+export { countLeadingZeroBits, powChallenge } from './challenges/pow_challenge.ts'
+export { renderSvg, svgChallenge } from './challenges/svg_challenge.ts'
+export { CaptchaError } from './captcha_error.ts'
+export { CaptchaManager, type CaptchaManagerOptions } from './captcha_manager.ts'
+export { CaptchaProvider, type CaptchaProviderOptions } from './captcha_provider.ts'
+export { ChallengeRegistry } from './registry.ts'
+export { consumeReplay } from './replay.ts'
+export { hashAnswer, randomHex, safeEqual, signToken, verifyToken } from './token.ts'
 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,
+  type CaptchaConfig,
+  type CaptchaTokenPayload,
+  type ChallengeName,
+  type ChallengeType,
+  DEFAULTS,
+  type FailureReason,
+  type IssueOptions,
+  type IssuedChallenge,
+  type VerifyResult,
 } from './types.ts'