Skip to content

📈 Open source, privacy-first web analytics — a cookie-less Google Analytics alternative with built-in error tracking and performance monitoring. Self-host it or use our cloud. Get started for free!

21.9 KB
Raw Blame
import { Injectable, BadRequestException } from '@nestjs/common'
import * as crypto from 'crypto'
import CryptoJS from 'crypto-js'
import { UAParser } from '@ua-parser-js/pro-business'
import _values from 'lodash/values'
import _includes from 'lodash/includes'
import dayjs from 'dayjs'
import utc from 'dayjs/plugin/utc'

import { ProjectService } from '../project/project.service'
import { AppLoggerService } from '../logger/logger.service'
import {
  redis,
  isValidPID,
  getRedisCaptchaKey,
  CAPTCHA_TOKEN_LIFETIME,
} from '../common/constants'
import { getIPDetails } from '../common/utils'
import { GeneratedChallenge } from './interfaces/generated-captcha'
import { eventTransformer } from '../analytics/utils/transformers'
import { clickhouse } from '../common/integrations/clickhouse'

dayjs.extend(utc)

// Default difficulty: number of leading hex zeros required (4 = ~65k iterations avg)
const DEFAULT_POW_DIFFICULTY = 4
const MIN_POW_DIFFICULTY = 2
const MAX_POW_DIFFICULTY = 6

// Challenge TTL in seconds (5 minutes)
const CHALLENGE_TTL = 300
const CAPTCHA_COUNTER_PREFIX = 'captcha:auto'

type CaptchaDifficultyMode = 'manual' | 'auto'
type CaptchaEventName =
  | 'generate'
  | 'pass'
  | 'verify_fail'
  | 'validation_fail'
  | 'replay'

interface CaptchaHeaders {
  [key: string]: string | string[] | undefined
}

interface CaptchaDifficultyDecision {
  difficulty: number
  mode: CaptchaDifficultyMode
  reasons: string[]
  score: number
}

interface ChallengePayload {
  pid?: string
  difficulty: number
  difficultyMode?: CaptchaDifficultyMode
  autoReasons?: string[]
  issuedAt?: number
}

interface PowVerificationResult extends ChallengePayload {
  valid: boolean
  solveMs?: number
  failureReason?: string
}

interface CaptchaEventMeta {
  difficulty?: number
  difficultyMode?: CaptchaDifficultyMode
  autoReasons?: string[]
  solveMs?: number
  failureReason?: string
}

export const DUMMY_PIDS = {
  ALWAYS_PASS: 'AP00000000000',
  ALWAYS_FAIL: 'FAIL000000000',
}

const DUMMY_SECRETS = {
  ALWAYS_PASS: 'PASS000000000000000000',
  ALWAYS_FAIL: 'FAIL000000000000000000',
  TOKEN_USED_FAIL: 'USED000000000000000000',
}

const isDummyPID = (pid: string): boolean => {
  return _includes(_values(DUMMY_PIDS), pid)
}

const encryptString = (text: string, key: string): string => {
  return CryptoJS.Rabbit.encrypt(text, key).toString()
}

const decryptString = (text: string, key: string): string => {
  const bytes = CryptoJS.Rabbit.decrypt(text, key)
  return bytes.toString(CryptoJS.enc.Utf8)
}

const getChallengeCacheKey = (challenge: string): string => {
  return `pow_challenge:${challenge}`
}

const getSpentChallengeCacheKey = (challenge: string): string => {
  return `pow_challenge_spent:${challenge}`
}

const parseChallengePayload = (storedData: string): ChallengePayload => {
  let parsed

  try {
    parsed = JSON.parse(storedData)
  } catch {
    return { difficulty: parseInt(storedData, 10) }
  }

  if (typeof parsed === 'object' && parsed !== null && 'difficulty' in parsed) {
    return parsed
  }

  return { difficulty: parseInt(storedData, 10) }
}

const clampDifficulty = (difficulty?: number | null): number => {
  if (!Number.isFinite(difficulty)) {
    return DEFAULT_POW_DIFFICULTY
  }

  return Math.min(
    MAX_POW_DIFFICULTY,
    Math.max(MIN_POW_DIFFICULTY, Number(difficulty)),
  )
}

const getHeaderValue = (
  headers: CaptchaHeaders | undefined,
  name: string,
): string => {
  const value = headers?.[name] ?? headers?.[name.toLowerCase()]
  if (Array.isArray(value)) {
    return value[0] || ''
  }

  return value ? String(value) : ''
}

const hasSuspiciousHeaders = (headers: CaptchaHeaders | undefined): boolean => {
  const required = ['accept', 'accept-language', 'accept-encoding']
  const missing = required.filter((header) => !getHeaderValue(headers, header))

  return missing.length >= 2
}

const hasHeadlessUserAgent = (headers: CaptchaHeaders | undefined): boolean => {
  return /HeadlessChrome|PhantomJS|SlimerJS|Selenium|WebDriver|Puppeteer|Playwright|Cypress|Nightmare|Splash/i.test(
    getHeaderValue(headers, 'user-agent'),
  )
}

const hashIP = (pid: string, ip: string): string => {
  return crypto
    .createHash('sha256')
    .update(`${pid}:${ip}`)
    .digest('hex')
    .slice(0, 16)
}

const getCounterKey = (
  pid: string,
  event: string,
  window: string,
  scope = 'project',
  bucket = 'all',
): string =>
  `${CAPTCHA_COUNTER_PREFIX}:${window}:${event}:${scope}:${pid}:${bucket}`

const incrCounter = async (key: string, ttl: number): Promise<number> => {
  const value = await redis.eval(
    "local value = redis.call('INCR', KEYS[1]); if value == 1 then redis.call('EXPIRE', KEYS[1], ARGV[1]); end; return value",
    1,
    key,
    ttl,
  )

  return Number(value)
}

const getCounter = async (key: string): Promise<number> => {
  const value = await redis.get(key)
  const parsed = Number(value || 0)

  return Number.isFinite(parsed) ? parsed : 0
}

const consumeChallenge = async (challenge: string): Promise<string | null> => {
  const result = await redis.eval(
    "local value = redis.call('GET', KEYS[1]); if value then redis.call('DEL', KEYS[1]); redis.call('SET', KEYS[2], value, 'EX', ARGV[1]); end; return value",
    2,
    getChallengeCacheKey(challenge),
    getSpentChallengeCacheKey(challenge),
    CHALLENGE_TTL,
  )

  return typeof result === 'string' ? result : null
}

const getSpentChallengePayload = async (
  challenge: string,
): Promise<ChallengePayload | null> => {
  const storedData = await redis.get(getSpentChallengeCacheKey(challenge))

  return storedData ? parseChallengePayload(storedData) : null
}

const signCaptchaCiphertext = (ciphertext: string, key: string): string => {
  // NOTE: Encryption alone (CryptoJS.Rabbit) is malleable; we add an HMAC to
  // prevent token tampering and replay-bypass via ciphertext bitflips.
  return crypto.createHmac('sha256', key).update(ciphertext).digest('base64url')
}

const timingSafeEqualString = (a: string, b: string): boolean => {
  try {
    const aBuf = Buffer.from(a)
    const bBuf = Buffer.from(b)
    if (aBuf.length !== bBuf.length) return false
    return crypto.timingSafeEqual(aBuf, bBuf)
  } catch {
    return false
  }
}

const isTokenAlreadyUsed = async (token: string): Promise<boolean> => {
  const captchaKey = getRedisCaptchaKey(token)
  const setResult = await redis.set(
    captchaKey,
    '1',
    'EX',
    CAPTCHA_TOKEN_LIFETIME / 1000,
    'NX',
  )

  // ioredis returns null when key already exists (i.e. token already used)
  return setResult === null
}

@Injectable()
export class CaptchaService {
  constructor(
    private readonly logger: AppLoggerService,
    private readonly projectService: ProjectService,
  ) {}

  // checks if captcha is enabled for pid (by checking if captchaSecretKey exists)
  async _isCaptchaEnabledForPID(pid: string) {
    const project = await this.projectService.getRedisProject(pid)

    if (!project) {
      return false
    }

    return !!project.captchaSecretKey
  }

  // Get project's configured PoW difficulty, or default
  async _getProjectDifficulty(pid: string): Promise<number> {
    if (isDummyPID(pid)) {
      return DEFAULT_POW_DIFFICULTY
    }

    const project = await this.projectService.getRedisProject(pid)

    return clampDifficulty(project?.captchaDifficulty)
  }

  // validates pid, checks if captcha is enabled and throws an error otherwise
  async validatePIDForCAPTCHA(pid: string) {
    if (isDummyPID(pid)) {
      return
    }

    if (!isValidPID(pid)) {
      throw new BadRequestException(
        'The provided Project ID (pid) is incorrect',
      )
    }

    if (!(await this._isCaptchaEnabledForPID(pid))) {
      throw new BadRequestException(
        'CAPTCHA not available for this project - please generate a secret key first in the project settings',
      )
    }
  }

  private async logCaptchaEvent(
    pid: string,
    event: CaptchaEventName,
    headers: CaptchaHeaders,
    timestamp: number,
    ip: string,
    meta: CaptchaEventMeta = {},
  ) {
    if (isDummyPID(pid)) {
      return
    }

    const ua = await UAParser(
      getHeaderValue(headers, 'user-agent'),
      undefined,
      headers,
    ).withClientHints()
    const deviceType = ua.device.type || 'desktop'
    const browserName = ua.browser.name
    const osName = ua.os.name

    const { country } = getIPDetails(ip)
    const eventMeta: Record<string, string> = {
      captcha_event: event,
    }

    if (meta.difficulty !== undefined) {
      eventMeta.captcha_difficulty = String(meta.difficulty)
    }

    if (meta.difficultyMode) {
      eventMeta.captcha_difficulty_mode = meta.difficultyMode
    }

    if (meta.autoReasons?.length) {
      eventMeta.captcha_reason = meta.autoReasons[0]
    }

    if (meta.solveMs !== undefined) {
      eventMeta.solve_ms = String(Math.max(0, Math.round(meta.solveMs)))
    }

    if (meta.failureReason) {
      eventMeta.failure_reason = meta.failureReason
    }

    const transformed = eventTransformer({
      type: 'captcha',
      pid,
      dv: deviceType,
      br: browserName,
      os: osName,
      cc: country,
      meta: eventMeta,
      timestamp,
    })

    try {
      await clickhouse.insert({
        table: 'events',
        format: 'JSONEachRow',
        values: [transformed],
        clickhouse_settings: {
          async_insert: 1,
        },
      })
    } catch (e) {
      this.logger.error(`[CaptchaService -> logCaptchaEvent] ${e}`)
    }
  }

  async logCaptchaPass(
    pid: string,
    headers: CaptchaHeaders,
    timestamp: number,
    ip: string,
    verification: PowVerificationResult,
  ) {
    await this.recordCaptchaOutcome(pid, 'pass', ip, verification)
    await this.logCaptchaEvent(pid, 'pass', headers, timestamp, ip, {
      difficulty: verification.difficulty,
      difficultyMode: verification.difficultyMode || 'manual',
      autoReasons: verification.autoReasons,
      solveMs: verification.solveMs,
    })
  }

  async logCaptchaFailure(
    pid: string,
    headers: CaptchaHeaders,
    timestamp: number,
    ip: string,
    verification: PowVerificationResult,
  ) {
    await this.recordCaptchaOutcome(pid, 'verify_fail', ip, verification)
    await this.logCaptchaEvent(pid, 'verify_fail', headers, timestamp, ip, {
      difficulty: verification.difficulty,
      difficultyMode: verification.difficultyMode || 'manual',
      autoReasons: verification.autoReasons,
      solveMs: verification.solveMs,
      failureReason: verification.failureReason || 'invalid_pow',
    })
  }

  async logCaptchaReplay(
    pid: string,
    headers: CaptchaHeaders,
    timestamp: number,
    ip: string,
    failureReason = 'expired_or_replayed',
    verification?: Partial<PowVerificationResult>,
  ) {
    await this.recordCaptchaOutcome(pid, 'replay', ip)
    await this.logCaptchaEvent(pid, 'replay', headers, timestamp, ip, {
      difficulty: verification?.difficulty,
      difficultyMode: verification?.difficultyMode,
      autoReasons: verification?.autoReasons,
      failureReason,
    })
  }

  async logCaptchaReplayForChallenge(
    challenge: string,
    requestPid: string,
    headers: CaptchaHeaders,
    timestamp: number,
    ip: string,
  ) {
    const payload = await getSpentChallengePayload(challenge)

    if (!payload?.pid || payload.pid !== requestPid) {
      return false
    }

    await this.logCaptchaReplay(
      payload.pid,
      headers,
      timestamp,
      ip,
      'replayed_challenge',
      payload,
    )

    return true
  }

  private async recordCaptchaOutcome(
    pid: string,
    event: CaptchaEventName,
    ip: string,
    verification?: Partial<PowVerificationResult>,
  ) {
    if (isDummyPID(pid)) {
      return
    }

    const ipHash = ip ? hashIP(pid, ip) : 'unknown'
    const promises = [
      incrCounter(getCounterKey(pid, event, '5m'), 300),
      incrCounter(getCounterKey(pid, event, '15m'), 900),
      incrCounter(getCounterKey(pid, event, '5m', 'ip', ipHash), 300),
    ]

    if (verification?.solveMs !== undefined) {
      promises.push(incrCounter(getCounterKey(pid, 'solve', '5m'), 300))
    }

    await Promise.all(promises)
  }

  async generateDummyToken() {
    return encryptString(
      'DUMMY_TOKEN00000111112222233333444445555566666777778888899999',
      DUMMY_SECRETS.ALWAYS_PASS,
    )
  }

  async generateToken(pid: string, challenge: string, timestamp: number) {
    if (isDummyPID(pid)) {
      return this.generateDummyToken()
    }

    const project = await this.projectService.getRedisProject(pid)

    if (!project) {
      throw new BadRequestException('Project not found')
    }

    if (!project.captchaSecretKey) {
      throw new BadRequestException('No secret key generated for this project')
    }

    const token = {
      challenge,
      timestamp,
      pid,
    }

    const ciphertext = encryptString(
      JSON.stringify(token),
      project.captchaSecretKey,
    )
    const signature = signCaptchaCiphertext(
      ciphertext,
      project.captchaSecretKey,
    )

    // Token format: <ciphertext>.<hmac_sha256(ciphertext)>
    return `${ciphertext}.${signature}`
  }

  private async isProjectCaptchaSecret(pid: string, secretKey: string) {
    try {
      const project = await this.projectService.getRedisProject(pid)
      const captchaSecretKey = project?.captchaSecretKey

      return Boolean(
        captchaSecretKey && timingSafeEqualString(secretKey, captchaSecretKey),
      )
    } catch {
      return false
    }
  }

  async validateToken(
    token: string,
    secretKey: string,
    headers: CaptchaHeaders = {},
    ip = '',
  ) {
    let parsed

    if (secretKey === DUMMY_SECRETS.ALWAYS_FAIL) {
      throw new BadRequestException('Could not decrypt token')
    }

    if (secretKey === DUMMY_SECRETS.TOKEN_USED_FAIL) {
      throw new BadRequestException('Token already used')
    }

    if (secretKey === DUMMY_SECRETS.ALWAYS_PASS) {
      return {
        challenge:
          'DUMMY_CHALLENGE00000111112222233333444445555566666777778888899999',
        timestamp: dayjs().unix() * 1000,
        pid: DUMMY_PIDS.ALWAYS_PASS,
      }
    }

    try {
      const parts = token.split('.')

      if (parts.length !== 2) {
        throw new BadRequestException('Invalid token format')
      }

      const [ciphertext, providedSignature] = parts
      const expectedSignature = signCaptchaCiphertext(ciphertext, secretKey)

      if (!timingSafeEqualString(providedSignature, expectedSignature)) {
        throw new BadRequestException('Invalid token signature')
      }

      const decrypted = decryptString(ciphertext, secretKey)
      parsed = JSON.parse(decrypted)
    } catch {
      throw new BadRequestException('Could not decrypt token')
    }

    if (
      !parsed ||
      typeof parsed !== 'object' ||
      typeof parsed.pid !== 'string'
    ) {
      throw new BadRequestException('Invalid token payload')
    }

    if (isDummyPID(parsed.pid) || !isValidPID(parsed.pid)) {
      throw new BadRequestException('Invalid token payload')
    }

    if (!(await this.isProjectCaptchaSecret(parsed.pid, secretKey))) {
      throw new BadRequestException('Could not decrypt token')
    }

    if (
      typeof parsed.challenge !== 'string' ||
      typeof parsed.timestamp !== 'number' ||
      !Number.isFinite(parsed.timestamp)
    ) {
      await this.logValidationFailure(
        parsed.pid,
        headers,
        ip,
        'invalid_payload',
      )

      throw new BadRequestException('Invalid token payload')
    }

    if (dayjs().unix() * 1000 - parsed.timestamp > CAPTCHA_TOKEN_LIFETIME) {
      await this.logValidationFailure(parsed.pid, headers, ip, 'token_expired')
      throw new BadRequestException('Token expired')
    }

    const tokenUsed = await isTokenAlreadyUsed(token)

    if (tokenUsed) {
      await this.recordCaptchaOutcome(parsed.pid, 'replay', ip)
      await this.logValidationFailure(parsed.pid, headers, ip, 'token_replay')
      throw new BadRequestException('Token already used')
    }

    return parsed
  }

  private async logValidationFailure(
    pid: string,
    headers: CaptchaHeaders,
    ip: string,
    failureReason: string,
  ) {
    if (isDummyPID(pid) || !isValidPID(pid)) {
      return
    }

    await this.recordCaptchaOutcome(pid, 'validation_fail', ip)
    await this.logCaptchaEvent(
      pid,
      'validation_fail',
      headers,
      dayjs.utc().unix() * 1000,
      ip,
      { failureReason },
    )
  }

  // Generate SHA-256 hash of the input
  sha256(input: string): string {
    return crypto.createHash('sha256').update(input).digest('hex')
  }

  // Check if hash has required number of leading zeros
  hasValidPrefix(hash: string, difficulty: number): boolean {
    const prefix = '0'.repeat(difficulty)
    return hash.startsWith(prefix)
  }

  private async selectDifficulty(
    pid: string,
    headers: CaptchaHeaders,
    ip: string,
  ): Promise<CaptchaDifficultyDecision> {
    const project = isDummyPID(pid)
      ? null
      : await this.projectService.getRedisProject(pid)
    const mode = (project?.captchaDifficultyMode ||
      'manual') as CaptchaDifficultyMode

    if (mode !== 'auto' || isDummyPID(pid)) {
      return {
        difficulty: clampDifficulty(project?.captchaDifficulty),
        mode: 'manual',
        reasons: ['manual'],
        score: 0,
      }
    }

    const { country, isHosting } = getIPDetails(ip)
    const countryBucket = country || 'xx'
    const ipHash = ip ? hashIP(pid, ip) : 'unknown'

    const [
      projectGenerate1m,
      projectGenerate5m,
      countryGenerate5m,
      ipGenerate1m,
    ] = await Promise.all([
      incrCounter(getCounterKey(pid, 'generate', '1m'), 60),
      incrCounter(getCounterKey(pid, 'generate', '5m'), 300),
      incrCounter(
        getCounterKey(pid, 'generate', '5m', 'country', countryBucket),
        300,
      ),
      incrCounter(getCounterKey(pid, 'generate', '1m', 'ip', ipHash), 60),
    ])

    const [
      projectPass5m,
      projectFail5m,
      projectReplay5m,
      projectValidationFail5m,
      ipFail5m,
      ipReplay5m,
    ] = await Promise.all([
      getCounter(getCounterKey(pid, 'pass', '5m')),
      getCounter(getCounterKey(pid, 'verify_fail', '5m')),
      getCounter(getCounterKey(pid, 'replay', '5m')),
      getCounter(getCounterKey(pid, 'validation_fail', '5m')),
      getCounter(getCounterKey(pid, 'verify_fail', '5m', 'ip', ipHash)),
      getCounter(getCounterKey(pid, 'replay', '5m', 'ip', ipHash)),
    ])

    const reasons: string[] = []
    let score = 0
    const passRatio =
      projectGenerate5m > 0 ? projectPass5m / projectGenerate5m : 1
    const verifyAttempts = projectPass5m + projectFail5m
    const failRatio = verifyAttempts > 0 ? projectFail5m / verifyAttempts : 0

    const addRisk = (condition: boolean, reason: string, weight = 1) => {
      if (!condition) {
        return
      }

      score += weight
      reasons.push(reason)
    }

    addRisk(isHosting, 'hosting_ip')
    addRisk(hasHeadlessUserAgent(headers), 'headless_browser', 2)
    addRisk(hasSuspiciousHeaders(headers), 'suspicious_headers')
    addRisk(projectGenerate1m >= 50, 'project_spike', 2)
    addRisk(countryGenerate5m >= 50, 'country_spike')
    addRisk(ipGenerate1m >= 8, 'ip_pressure', 2)
    addRisk(projectGenerate5m >= 30 && passRatio < 0.25, 'low_pass_ratio', 2)
    addRisk(verifyAttempts >= 20 && failRatio > 0.35, 'verify_failures', 2)
    addRisk(projectValidationFail5m >= 5, 'validation_failures', 2)
    addRisk(projectReplay5m >= 2 || ipReplay5m >= 1, 'replay_attempts', 2)
    addRisk(ipFail5m >= 3, 'ip_verify_failures', 2)

    const difficulty =
      score >= 8 ? 6 : score >= 5 ? 5 : score >= 2 ? 4 : score >= 1 ? 3 : 2

    return {
      difficulty,
      mode: 'auto',
      reasons: difficulty > 2 ? reasons.slice(0, 4) : ['baseline'],
      score,
    }
  }

  async generateChallenge(
    pid: string,
    headers: CaptchaHeaders = {},
    ip = '',
  ): Promise<GeneratedChallenge> {
    const decision = await this.selectDifficulty(pid, headers, ip)

    const challenge = crypto.randomBytes(32).toString('hex')
    const issuedAt = dayjs.utc().unix() * 1000

    const cacheKey = getChallengeCacheKey(challenge)
    const challengeData = JSON.stringify({
      pid,
      difficulty: decision.difficulty,
      difficultyMode: decision.mode,
      autoReasons: decision.reasons,
      issuedAt,
    })
    await redis.set(cacheKey, challengeData, 'EX', CHALLENGE_TTL)

    await this.logCaptchaEvent(pid, 'generate', headers, issuedAt, ip, {
      difficulty: decision.difficulty,
      difficultyMode: decision.mode,
      autoReasons: decision.reasons,
    })

    return {
      challenge,
      difficulty: decision.difficulty,
    }
  }

  async verifyPoW(
    challenge: string,
    nonce: number,
    solution: string,
    pid: string,
  ): Promise<PowVerificationResult> {
    const storedData = await consumeChallenge(challenge)

    if (!storedData) {
      throw new BadRequestException('Invalid or expired challenge')
    }

    const payload = parseChallengePayload(storedData)
    const difficulty = Number(payload.difficulty)

    if (
      !Number.isFinite(difficulty) ||
      difficulty < MIN_POW_DIFFICULTY ||
      difficulty > MAX_POW_DIFFICULTY
    ) {
      throw new BadRequestException('Invalid challenge difficulty')
    }

    if (payload.pid !== undefined && payload.pid !== pid) {
      throw new BadRequestException(
        'Challenge was issued for a different project',
      )
    }

    const input = `${challenge}:${nonce}`
    const computedHash = this.sha256(input)
    const solveMs = payload.issuedAt
      ? dayjs.utc().unix() * 1000 - payload.issuedAt
      : undefined
    const resultBase = {
      difficulty,
      difficultyMode: payload.difficultyMode || 'manual',
      autoReasons: payload.autoReasons || [],
      issuedAt: payload.issuedAt,
      solveMs,
    }

    if (computedHash !== solution) {
      return {
        ...resultBase,
        valid: false,
        failureReason: 'solution_mismatch',
      }
    }

    if (!this.hasValidPrefix(computedHash, difficulty)) {
      return {
        ...resultBase,
        valid: false,
        failureReason: 'difficulty_mismatch',
      }
    }

    return {
      ...resultBase,
      valid: true,
    }
  }
}