DOCSEARCHbyAlgolia
Submit Docs

Cap Documentation

repository·main·Indexed 27 days ago

https://github.com/tiagozip/cap

A lightweight, privacy-preserving, open-source CAPTCHA alternative that replaces visual puzzles with proof-of-work and instrumentation challenges. The capjs-core package provides a stateless server-side challenge generator and verifier (version 0.1.1) supporting multiple challenge formats, including SHA256-PoW and RSW (RSA-style squaring). It features a small footprint (~20kb), zero dependencies, and is designed for easy deployment via Docker.

Tokens
29.9K
Snippets
58
Records
166
Agent score
91%

What's inside capjs-core

  1. Overview of Cap features and architecture

    main

    Cap is an open-source, self-hosted CAPTCHA alternative designed to replace visual puzzles with proof-of-work and instrumentation challenges. It consists of four main components:

    • Widget: A ~20 KB client-side component that renders a single checkbox.
    • Standalone Server: A single Docker container that includes a dashboard and supports multi-site-key configurations.
    • Server Libraries: Packages like @cap.js/server (and community ports) used to verify challenges within your backend.
    • siteverify API: A verification API that is compatible with reCAPTCHA and hCaptcha, allowing for migration via a simple URL swap.

  2. Overview of Cap

    main

    Cap is a lightweight, modern, open-source CAPTCHA alternative designed to replace visual captchas with privacy-preserving challenges. It utilizes proof-of-work and instrumentation challenges instead of visual puzzles, making it accessible and fast.

    Key features include:

    • Small Footprint: ~20kb with zero dependencies.
    • Privacy-first: No telemetry is sent back to servers.
    • Customizable: Styling via CSS variables (colors, size, position, icons).
    • Seamless UX: Supports background challenge solving without user interaction.
    • Standalone Mode: Can be run anywhere using a Docker container.

  4. Understand Cap's security and privacy model

    main
    Cap is designed to be fully self-hosted, meaning no data is collected or stored on central servers by default. It does not use cookies or telemetry. For security, Cap provides built-in replay protection and signature-based challenge tokens.

  5. Commonalities between Cap and FriendlyCaptcha

    main

    Both Cap and FriendlyCaptcha share several architectural and UX characteristics:

    • Mechanism: Both utilize proof-of-work (PoW) as the primary defense mechanism.
    • Privacy: Both are designed to be GDPR and CCPA compliant.
    • User Experience: Both provide clean, accessible widget interfaces that avoid traditional image-based puzzles.

  6. Understand Cap Instrumentation Challenges

    main
    Instrumentation challenges serve as Cap's second layer of verification, running silently alongside the core proof-of-work (PoW) system. While PoW proves computational effort, instrumentation challenges prove the presence of a genuine browser environment. They work by executing server-generated JavaScript that performs complex operations, including bitwise arithmetic, prototype-chain manipulations, and DOM-based arithmetic. The server validates the results of these operations to ensure they were executed within a real rendering engine rather than a headless script or a non-browser runtime.

  7. RSW Protocol Overview

    main

    The RSW protocol provides a sequential puzzle designed to resist GPU acceleration.

    Server Setup

    The server generates a 2048-bit RSA-style modulus N = p·q. Because keypair generation takes ~0.5–3 seconds, the server should persist the result and reuse it across processes.

    Challenge Minting

    To avoid expensive re-computation, the server uses a short-exponent trick:

    1. At setup, the server precomputes h = g^(2^t) mod N using the trapdoor φ(N) = (p-1)(q-1).
    2. For each challenge, the server picks a random 256-bit scalar r and computes x = g^r mod N and y = h^r mod N.
    3. The client receives (N, x, t) and must compute y.

    Verification

    Verification is a constant-time BigInt comparison. The server's encrypted-state token contains the expected y value (placed there during minting), so no re-derivation is required during verification.

  8. Compare CAPTCHA alternatives for 2026

    main

    When choosing a CAPTCHA alternative, consider your priorities regarding hosting, privacy, cost, and user experience.

    • Cap: Best for full control, privacy-first protection (no cookies/fingerprinting), and $0 cost at scale. It is open-source (Apache 2.0) and self-hosted via Docker.
    • Cloudflare Turnstile: Best for Cloudflare-native stacks requiring zero hosting. It is free but relies on fingerprinting and is closed source.
    • ALTCHA: Best for developers wanting a minimal, open-source (MIT) proof-of-work library without a standalone server.
    • FriendlyCaptcha: Best for teams requiring a managed, paid, EU-hosted proof-of-work service.
    • SilentShield: Best for WordPress sites wanting plug-and-play invisible protection (behavioral-based).
    • hCaptcha/reCAPTCHA: Best for enterprise-scale or Google-integrated stacks, though they often rely on image puzzles which can impact UX and conversion rates.

  9. Compare Cap and Cloudflare Turnstile

    main

    When choosing between Cap and Cloudflare Turnstile, consider the following trade-offs:

    | Feature | Cap | Cloudflare Turnstile | | :--- | :--- | : | | Hosting | Self-hosted on your servers | Fully managed by Cloudflare | | Control | You own the policy and difficulty knob | Cloudflare's algorithm decides | | Privacy | No telemetry, no cookies, no 'phoning home' | Communicates with challenges.cloudflare.com | | Open Source | Apache 2.0 | Closed-source | | Customization | High (CSS variables for colors, size, shape) | Low (mostly fixed iframe) | | Fingerprinting | Uses Proof-of-Work (works with hardened browsers) | Heavy reliance on browser fingerprinting |

  10. Compare Cap against CAPTCHA alternatives

    main

    Cap is an open-source, self-hosted CAPTCHA that uses proof-of-work (PoW) and instrumentation challenges instead of image puzzles. Use the following comparison to determine if Cap fits your requirements compared to other services like Cloudflare Turnstile, reCAPTCHA, or hCAPTCHA.

    Key Comparison Criteria

    • Open-source & Free: Cap is both open-source and free to use at any volume when self-hosted.
    • Privacy: Cap is GDPR compliant and does not track users or collect data, unlike reCAPTCHA or GeeTest.
    • User Experience: Cap avoids the "Puzzle Tax" (high drop-off rates from image puzzles) found in hCAPTCHA and MTCaptcha by using PoW.
    • Self-Hosting: Cap requires you to run your own infrastructure. If you require a fully managed service with no infrastructure management, consider Cloudflare Turnstile or FriendlyCaptcha.
    • Bot Resistance: Cap uses PoW and dynamic instrumentation to resist commodity automation (headless browsers, scripted attacks).
    | CAPTCHA              | Open-source | Free | Private | Fast to solve | Easy for humans | Small error rate | GDPR compliant | Customizable | Hard for bots | Instrumentation | RSW support | Easy to integrate |
| :------------------- | :---------- | :--- | :------ | :------------ | :-------------- | :--------------- | :------------- | :----------- | :------------ | :-------------- | :---------- | :---------------- |
| **Cap**              | ✅          | ✅   | ✅      | ✅            | ✅              | ✅               | ✅             | ✅           | ✅            | ✅              | ✅          | ✅                |
| Cloudflare Turnstile | ❌          | ✅   | 🟨      | 🟨            | ✅              | ❌               | ✅             | ❌             | ✅            | ✅              | 🟨             | ✅                |
| reCAPTCHA            | ❌          | 🟨   | ❌      | ❌            | ❌              | 🟨               | 🟨             | ❌             | 🟨            | ✅              | 🟨             | ✅                |
| hCAPTCHA             | ❌          | 🟨   | 🟨      | ❌            | ❌              | 🟨               | 🟨             | ❌             | 🟨            | ✅              | 🟨             | ✅                |
| Altcha               | ✅          | ✅   | ✅      | ✅            | ✅              | ✅               | ✅             | ✅           | 🟨            | ❌              | ❌            | 🟨                |
| FriendlyCaptcha      | ❌          | ❌   | ✅      | ✅            | ✅              | ✅               | ✅             | ✅           | ❌            | ❌              | ❌            | 🟨                |
| SilentShield         | ❌          | 🟨   | 🟨      | ✅            | ✅              | 🟨               | ✅             | ❌             | 🟨            | ✅              | ❌            | ✅                |
| MTCaptcha            | ❌          | 🟨   | 🟨      | ❌            | ❌              | 🟨               | ✅             | ❌             | ❌            | ❌              | ❌            | 🟨                |
| GeeTest              | ❌          | ❌   | ❌      | 🟨            | 🟨              | 🟨               | ✅             | ❌             | 🟨            | ❌              | ❌            | 🟨                |
| Arkose Labs          | ❌          | ❌   | ❌      | ❌            | ❌              | ❌               | ✅             | 🟨           | 🟨            | 🟨              | 🟨             | 🟨                |

  11. Understand Cap's Proof-of-Work (PoW) mechanism

    main
    Cap uses Proof-of-Work to increase the computational cost of automated abuse. Instead of relying solely on human verification (which bots can mimic), Cap requires attackers to expend computational effort. This is designed to make large-scale spamming or automated attacks financially unprofitable by increasing the cost per action.

  12. Compliance and Privacy Overview

    main

    Cap is designed to be privacy-first and self-hosted. Because it is self-hosted, user data remains within your own infrastructure. The verification flow is designed to meet GDPR, CCPA, and WCAG 2.2 standards through the following characteristics:

    • No Third-Party Calls: The verification flow does not make calls to external services.
    • No Tracking: There are no cookies or tracking mechanisms used for end users.
    • Local Execution: The proof-of-work process runs entirely within the visitor's browser.