@strav/captcha 0.4.31 → 1.0.0-alpha.42

package/src/registry.ts

@@ -1,29 +1,33 @@
+import { CaptchaError } from './captcha_error.ts'
 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' },
- * })
+ * In-memory map of challenge name → implementation. Owned by a
+ * `CaptchaManager` — there's no module-level singleton in 1.x; each
+ * manager gets a fresh registry pre-loaded with the built-ins.
  */
-export function registerChallengeType(type: ChallengeType): void {
-  registry.set(type.name, type)
-}
+export class ChallengeRegistry {
+  private readonly entries = new Map<ChallengeName, ChallengeType>()
 
-/** Look up a registered challenge type. Returns `undefined` if not registered. */
-export function getChallengeType(name: ChallengeName): ChallengeType | undefined {
-  return registry.get(name)
-}
+  register(type: ChallengeType): void {
+    this.entries.set(type.name, type)
+  }
+
+  get(name: ChallengeName): ChallengeType {
+    const type = this.entries.get(name)
+    if (!type) {
+      throw new CaptchaError(`Unknown captcha challenge type: ${String(name)}`, {
+        context: { name },
+      })
+    }
+    return type
+  }
+
+  has(name: ChallengeName): boolean {
+    return this.entries.has(name)
+  }
 
-/** All registered type names — used by validators and refresh route allow-listing. */
-export function listChallengeTypes(): ChallengeName[] {
-  return Array.from(registry.keys())
+  list(): ChallengeName[] {
+    return Array.from(this.entries.keys())
+  }
 }

package/src/replay.ts

@@ -0,0 +1,25 @@
+/**
+ * Replay prevention — a thin wrapper over the cache `add` (put-if-absent)
+ * primitive. Splitting it from token-verification means failed attempts
+ * don't burn the replay slot: only a successful verify reaches here.
+ */
+
+import type { Cache } from '@strav/cache'
+import type { CaptchaTokenPayload } from './types.ts'
+
+const REPLAY_PREFIX = 'captcha:used:'
+
+/**
+ * Atomically mark a token as used. Returns `true` on the first successful
+ * use, `false` if the slot was already taken (replay).
+ *
+ * The cache TTL matches the token's remaining lifetime so dead replay
+ * keys don't accumulate. Once the token expires the signature path
+ * rejects it anyway, so a missed eviction has no security impact.
+ */
+export async function consumeReplay(cache: Cache, payload: CaptchaTokenPayload): Promise<boolean> {
+  const key = REPLAY_PREFIX + payload.jti
+  const remainingMs = payload.iat + payload.exp * 60_000 - Date.now()
+  const ttlSeconds = Math.max(1, Math.ceil(remainingMs / 1000))
+  return cache.add(key, 1, ttlSeconds)
+}

package/src/token.ts

@@ -1,8 +1,15 @@
-import { encrypt } from '@strav/kernel'
-import type { CacheStore } from '@strav/kernel'
-import type { CaptchaTokenPayload, FailureReason } from './types.ts'
+/**
+ * Token + answer-hash primitives.
+ *
+ * Tokens are HMAC-SHA256 signed JSON (`base64url(json).base64url(mac)`).
+ * The contents are not secret (an answer *hash* + salt + jti + difficulty)
+ * so encryption buys nothing extra over an integrity check. The signature
+ * stops the client from forging a token or tampering with difficulty,
+ * expiry, or the replay id.
+ */
 
-const REPLAY_PREFIX = 'captcha:used:'
+import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto'
+import type { CaptchaTokenPayload, FailureReason } from './types.ts'
 
 /**
  * Hash an answer with its per-challenge salt. The salt prevents a global
@@ -10,59 +17,102 @@ const REPLAY_PREFIX = 'captcha:used:'
  * 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.
+ * SVG verifier does at compare time.
  */
 export function hashAnswer(answer: string, salt: string): string {
-  return encrypt.sha256(answer.toLowerCase().trim() + salt)
+  return createHmac('sha256', salt).update(answer.toLowerCase().trim()).digest('hex')
 }
 
 /** 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
+  const ab = Buffer.from(a)
+  const bb = Buffer.from(b)
+  return timingSafeEqual(ab, bb)
+}
+
+/** Cryptographically-strong random hex string of `nBytes` bytes (2× chars). */
+export function randomHex(nBytes: number): string {
+  return randomBytes(nBytes).toString('hex')
+}
+
+const TEXT_ENCODER = new TextEncoder()
+
+function b64urlEncode(bytes: Buffer | Uint8Array): string {
+  return Buffer.from(bytes).toString('base64').replace(/=+$/, '').replace(/\+/g, '-').replace(/\//g, '_')
+}
+
+function b64urlDecode(s: string): Buffer {
+  const pad = s.length % 4 === 0 ? '' : '='.repeat(4 - (s.length % 4))
+  return Buffer.from(s.replace(/-/g, '+').replace(/_/g, '/') + pad, 'base64')
+}
+
+function normalizeSecret(secret: string | Uint8Array): Buffer {
+  if (typeof secret === 'string') return Buffer.from(secret, 'utf8')
+  return Buffer.from(secret)
 }
 
 /**
- * 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.
+ * Sign + encode a payload (sets `v`/`iat`/`jti` automatically). The salt
+ * and answer hash must already be in `data` — the caller (the manager)
+ * 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
-} {
+export function signToken(
+  secret: string | Uint8Array,
+  data: Omit<CaptchaTokenPayload, 'v' | 'iat' | 'jti'>,
+): { token: string; payload: CaptchaTokenPayload } {
   const payload: CaptchaTokenPayload = {
     v: 1,
     iat: Date.now(),
-    jti: encrypt.random(16),
+    jti: randomHex(16),
     ...data,
   }
-  return { token: encrypt.seal(payload), payload }
+  const body = b64urlEncode(TEXT_ENCODER.encode(JSON.stringify(payload)))
+  const mac = b64urlEncode(createHmac('sha256', normalizeSecret(secret)).update(body).digest())
+  return { token: `${body}.${mac}`, payload }
 }
 
 /**
- * Decode a sealed token. Returns the payload, or a failure reason that
- * the verifier can short-circuit on (invalid seal, expired).
+ * Verify the signature and decode a token. Returns the payload, or a
+ * failure reason that the verifier can short-circuit on (invalid
+ * signature, expired).
  *
  * Replay prevention happens at `consumeReplay()` — splitting the steps
- * lets the verifier check the answer first and only burn the replay slot
- * on success.
+ * lets the verifier check the answer first and only burn the replay
+ * slot on success.
  */
-export function unsealToken(
-  token: string
+export function verifyToken(
+  secret: string | Uint8Array,
+  token: string,
 ): { ok: true; payload: CaptchaTokenPayload } | { ok: false; reason: FailureReason } {
+  const dot = token.indexOf('.')
+  if (dot <= 0 || dot === token.length - 1) return { ok: false, reason: 'token_invalid' }
+  const body = token.slice(0, dot)
+  const mac = token.slice(dot + 1)
+
+  const expected = b64urlEncode(createHmac('sha256', normalizeSecret(secret)).update(body).digest())
+  // Constant-time compare on equal-length strings.
+  if (expected.length !== mac.length || !safeEqual(expected, mac)) {
+    return { ok: false, reason: 'token_invalid' }
+  }
+
   let payload: CaptchaTokenPayload
   try {
-    payload = encrypt.unseal<CaptchaTokenPayload>(token)
+    payload = JSON.parse(b64urlDecode(body).toString('utf8')) as CaptchaTokenPayload
   } catch {
     return { ok: false, reason: 'token_invalid' }
   }
 
-  if (!payload || payload.v !== 1 || typeof payload.iat !== 'number') {
+  if (
+    !payload ||
+    payload.v !== 1 ||
+    typeof payload.iat !== 'number' ||
+    typeof payload.exp !== 'number' ||
+    typeof payload.jti !== 'string' ||
+    typeof payload.s !== 'string' ||
+    typeof payload.t !== 'string'
+  ) {
     return { ok: false, reason: 'token_invalid' }
   }
 
@@ -72,24 +122,3 @@ export function unsealToken(
 
   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

@@ -1,12 +1,19 @@
-import type { CacheStore } from '@strav/kernel'
-import type { Middleware } from '@strav/http'
+/**
+ * Public types for `@strav/captcha`.
+ *
+ * The token payload is **signed, not encrypted** — its contents are not
+ * secret (answer *hash* + salt + replay id + difficulty). HMAC over the
+ * payload is enough: the client cannot forge a token or tamper with
+ * difficulty/expiry without invalidating the signature.
+ */
 
-/** Built-in challenge type names. Extensible via `registerChallengeType()`. */
+/** Built-in challenge type names. Extensible via `CaptchaManager.register()`. */
 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.
+ * (when JSON) returned to the client so the form can display targeted
+ * help.
  */
 export type FailureReason =
   | 'token_missing'
@@ -19,10 +26,11 @@ export type FailureReason =
   | '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.
+ * Signed 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
+ * payload is leaked; `jti` is the replay cache key so a token can only
+ * succeed once.
  */
 export interface CaptchaTokenPayload {
   /** Schema version. Bump on breaking changes. */
@@ -43,9 +51,9 @@ export interface CaptchaTokenPayload {
   jti: string
 }
 
-/** What `issueChallenge()` hands back — token + render data for the form. */
+/** What `issue()` hands back — token + render data for the form. */
 export interface IssuedChallenge {
-  /** Sealed token to embed in a hidden form field. */
+  /** Signed token to embed in a hidden form field. */
   token: string
   /** Type-specific data the renderer needs (e.g. `{ challenge, difficulty }`). */
   props: Record<string, unknown>
@@ -53,7 +61,7 @@ export interface IssuedChallenge {
   html?: string
 }
 
-/** Options passed to `issueChallenge()`. */
+/** Options passed to `issue()`. */
 export interface IssueOptions {
   /** Override default expiry. */
   ttlMinutes?: number
@@ -61,53 +69,56 @@ export interface IssueOptions {
   difficulty?: number
 }
 
-/** Result of `verifyChallenge()`. `ok: true` consumes the replay slot. */
+/** Result of `verify()`. `ok: true` means the cryptographic checks passed; replay consumption is a separate step. */
 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
+ * decoded payload plus the user's response and the parsed body, 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).
+   * Build a fresh challenge. Returns the props the renderer needs and
+   * the data that gets signed 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. */
+    /** Plaintext answer the user is expected to produce — hashed with salt before signing. */
     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 the response against the signed payload. Pure function —
+   * replay prevention happens upstream, not here.
    */
   verify(
     payload: CaptchaTokenPayload,
     response: unknown,
-    body: Record<string, 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[]
+/** Configuration consumed by `CaptchaManager` / `CaptchaProvider`. */
+export interface CaptchaConfig {
+  /**
+   * HMAC signing secret. Required. Must be at least 32 bytes of entropy
+   * — a typical APP_KEY (32-byte hex or base64) is exactly right.
+   */
+  secret: string | Uint8Array
   /** Hidden field bots fill in. @default 'website' */
   honeypotField?: string
-  /** Form field carrying the sealed token. @default '_captcha' */
+  /** Form field carrying the signed token. @default '_captcha' */
   tokenField?: string
   /** Form field carrying the user's answer / nonce. @default '_captcha_answer' */
   responseField?: string
@@ -115,17 +126,12 @@ export interface CaptchaOptions {
   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
 }
 
+/**
+ * Frozen defaults — exposed so the view helper and the middleware
+ * agree on field names without re-declaring them.
+ */
 export const DEFAULTS = {
   honeypotField: 'website',
   tokenField: '_captcha',

package/src/view/captcha_helper.ts

@@ -0,0 +1,77 @@
+/**
+ * Form-fragment helper. Wire into the view engine via `config.view.globals`:
+ *
+ *   import { makeCaptchaHelper } from '@strav/captcha/view'
+ *
+ *   // config/view.ts
+ *   export default {
+ *     globals: { __captcha: makeCaptchaHelper(app.resolve(CaptchaManager)) },
+ *   }
+ *
+ * Then in a template use `{{ raw __captcha('pow') }}` (or 'svg', or
+ * 'honeypot', or no arg for honeypot-only).
+ *
+ * Synchronous: `issue()` is sync, the renderer just concatenates
+ * strings — safe to call from inside the template render loop.
+ */
+
+import type { CaptchaManager } from '../captcha_manager.ts'
+import { CaptchaError } from '../captcha_error.ts'
+
+export type CaptchaHelper = (variant?: 'honeypot' | 'pow' | 'svg') => string
+
+export function makeCaptchaHelper(manager: CaptchaManager): CaptchaHelper {
+  return (variant?: 'honeypot' | 'pow' | 'svg') => {
+    const { honeypotField, tokenField, responseField } = manager.config
+    const honeypot = renderHoneypot(honeypotField)
+
+    if (!variant || variant === 'honeypot') return honeypot
+
+    if (variant === 'pow') {
+      const issued = manager.issue('pow')
+      const props = JSON.stringify({
+        ...issued.props,
+        tokenField,
+        responseField,
+      }).replace(/'/g, ''')
+      return (
+        honeypot +
+        `<input type="hidden" name="${attr(tokenField)}" value="${attr(issued.token)}">` +
+        `<input type="hidden" name="${attr(responseField)}" value="">` +
+        `<div data-captcha="pow" data-props='${props}'></div>`
+      )
+    }
+
+    if (variant === 'svg') {
+      const issued = manager.issue('svg')
+      return (
+        honeypot +
+        `<input type="hidden" name="${attr(tokenField)}" value="${attr(issued.token)}">` +
+        `<div class="captcha-svg">${issued.html ?? ''}</div>` +
+        `<input type="text" name="${attr(responseField)}" autocomplete="off" ` +
+        `inputmode="latin" autocapitalize="characters" required aria-label="Type the characters shown">`
+      )
+    }
+
+    throw new CaptchaError(
+      `captchaHelper: unknown variant "${String(variant)}" (expected 'pow' | 'svg' | 'honeypot' or none).`,
+      { code: 'captcha.unknown-variant', context: { variant } },
+    )
+  }
+}
+
+function renderHoneypot(name: string): string {
+  // Triple defense: aria-hidden, tabindex=-1, off-screen via inline
+  // style. Don't use `display:none` — some bots skip those fields.
+  const n = attr(name)
+  return (
+    `<div aria-hidden="true" style="position:absolute;left:-9999px;top:auto;width:1px;height:1px;overflow:hidden">` +
+    `<label for="${n}">Leave this field empty</label>` +
+    `<input type="text" id="${n}" name="${n}" tabindex="-1" autocomplete="off" value="">` +
+    `</div>`
+  )
+}
+
+function attr(s: string): string {
+  return s.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;')
+}

package/src/view/index.ts

@@ -0,0 +1,3 @@
+// `@strav/captcha/view` — form-fragment helper for view.globals.
+
+export { type CaptchaHelper, makeCaptchaHelper } from './captcha_helper.ts'

package/src/challenges.ts

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