SumnCap

Sumnatic Client-Side CAPTCHA & Bot Mitigation

SumnCap is a lightweight, privacy-friendly, 100% client-side CAPTCHA and bot-mitigation library developed by Sumnatic.

It is designed to make automated interactions significantly harder while keeping the experience for legitimate users fast, lightweight and frictionless.

No backend. No external API. No tracking. No mandatory server communication.

✨ Features

🚀 100% client-side
⚡ Extremely lightweight and fast
🔒 Multi-layer bot mitigation
🧩 Adaptive challenges
🧠 Behavioral analysis
🎲 Randomized challenges and execution flow
🛡️ Client-side tamper detection
🔄 Anti-replay mechanisms
📊 Risk scoring
👻 Invisible mode
⚙️ Managed mode
🧱 Visible CAPTCHA mode
♿ Accessibility support
🌙 Light / Dark / Auto themes
🌎 Internationalization-ready
📦 Zero heavy dependencies
📡 Works offline after loading
🪶 Vanilla JavaScript
🔌 Simple API
📦 CDN and npm support

🚀 Quick Start

The simplest integration requires only a few lines.

1. Include SumnCap

<script
    defer
    src="https://captcha.sumnatic.xyz/sumncap.min.js">
</script>

2. Create a container

<div id="sumncap"></div>

3. Initialize

<script>
    SumnCap.render("#sumncap", {
        mode: "managed"
    });
</script>

That's it.

🧩 Modes

SumnCap supports different levels of interaction.

Managed

Recommended mode.

SumnCap decides whether the user needs to interact with a challenge.

SumnCap.render("#sumncap", {
    mode: "managed"
});

Typical flow:

                    ┌──► Pass silently
                    │
User ──► Analysis ──┼──► Simple challenge
                    │
                    └──► Stronger challenge

The goal is to minimize friction for legitimate users.

Invisible

Attempts to perform verification without displaying a traditional CAPTCHA interface.

SumnCap.render("#sumncap", {
    mode: "invisible"
});

This mode is particularly useful for:

login forms
registration
contact forms
background actions
APIs with browser-facing interfaces

Visible

Displays the SumnCap interface immediately.

SumnCap.render("#sumncap", {
    mode: "visible"
});

Useful when you want users to explicitly see that a verification step exists.

Challenge

Forces an interactive challenge.

SumnCap.render("#sumncap", {
    mode: "challenge"
});

This mode is useful for testing or situations where an explicit challenge is desirable.

🧠 How It Works

SumnCap does not rely on a single "human detection" trick.

Instead, it uses multiple layers of client-side analysis.

Conceptually:

                 SumnCap
                    │
          ┌─────────┴─────────┐
          │                   │
    Environment          Interaction
      analysis             analysis
          │                   │
          └─────────┬─────────┘
                    │
              Risk evaluation
                    │
          ┌─────────┴─────────┐
          │                   │
       Low risk           High risk
          │                   │
      Pass / token        Challenge
                              │
                         Verification

Depending on the implementation and context, SumnCap can analyze signals such as:

interaction timing
pointer movement
pointer velocity
acceleration
direction changes
keyboard timing
focus behavior
touch interaction
scrolling behavior
event sequences
repeated patterns
execution timing
browser capabilities
automation indicators
challenge behavior

No individual signal should be considered definitive.

SumnCap uses defense in depth.

📊 Risk Score

SumnCap can expose a risk score representing the confidence of the local analysis.

Example:

{
    success: true,
    score: 0.94
}

Conceptually:

Score	Interpretation
`0.00`	Extremely suspicious
`0.25`	Suspicious
`0.50`	Uncertain
`0.75`	Probably legitimate
`1.00`	High confidence

The score is not a cryptographic proof of humanity.

It is an estimate generated by the client-side detection engine.

🎯 Actions

Applications can specify the context in which SumnCap is being used.

SumnCap.render("#sumncap", {
    mode: "managed",
    action: "login"
});

Examples:

login
register
password_reset
comment
contact
download
vote
checkout
api

This allows SumnCap to adapt its behavior to the context.

🔐 Anti-Tampering

SumnCap is designed with the assumption that an attacker can inspect the JavaScript.

Therefore, the library uses multiple layers intended to make casual modification and straightforward bypasses more difficult.

Depending on the build, these may include:

private internal state
closures
encapsulation
state machines
integrity checks
randomized execution
randomized challenges
distributed validation
anti-replay mechanisms
protected internal references
production minification
optional obfuscation

The goal is not to make JavaScript impossible to reverse engineer.

The goal is to increase the effort required to reliably automate or tamper with the verification process.

🎲 Randomization

SumnCap avoids relying on a completely deterministic challenge flow.

Challenge parameters can be randomized using secure browser randomness where appropriate.

For security-sensitive randomness, SumnCap prefers:

crypto.getRandomValues()

over:

Math.random()

Randomization may be applied to elements such as:

challenge parameters
sequences
positions
timing windows
challenge selection
internal state

This makes simple recorded interaction scripts less reliable.

♿ Accessibility

SumnCap is designed to support accessible interaction.

The project aims to support:

keyboard navigation
visible focus
screen readers
ARIA semantics where appropriate
reduced motion
accessible alternatives to pointer-only challenges
appropriate contrast

A CAPTCHA should not require a specific physical interaction method whenever an accessible alternative is possible.

🎨 UI

SumnCap follows the Sumnatic design language.

The default visual system is inspired by:

Glassmorphism
Aurora UI
translucent surfaces
subtle gradients
blur
depth
soft lighting
micro-interactions

Available themes:

light
dark
auto

Example:

SumnCap.render("#sumncap", {
    mode: "managed",
    theme: "dark"
});

⚡ Performance

Performance is a core design principle.

SumnCap is designed to:

initialize quickly
minimize JavaScript execution
minimize memory usage
avoid unnecessary network requests
avoid heavy dependencies
lazy-load expensive challenge components where possible
clean up event listeners
avoid unnecessary polling
minimize layout work

The goal is for SumnCap to protect a website without becoming a performance problem itself.

🔒 Privacy

SumnCap is designed to be privacy-friendly.

The client-side engine does not require sending behavioral data to Sumnatic.

There is no mandatory:

tracking
analytics
third-party cookie
browsing-history collection
external verification API

The basic architecture is:

Browser
   │
   ▼
SumnCap
   │
   ▼
Local analysis
   │
   ▼
Local result

📦 Installation

CDN

<script
    defer
    src="https://captcha.sumnatic.xyz/sumncap.min.js">
</script>

NPM

npm install @sumnatic/sumncap

Then:

import SumnCap from "@sumnatic/sumncap";

🔌 API

`render()`

Create a SumnCap instance.

const captcha = SumnCap.render("#captcha", {
    mode: "managed",
    theme: "auto",
    action: "login"
});

`execute()`

Programmatically execute verification.

const result = await captcha.execute();

Example result:

{
    success: true,
    score: 0.91,
    token: "..."
}

`reset()`

Reset the current verification.

captcha.reset();

`destroy()`

Destroy the instance and clean up resources.

captcha.destroy();

📡 Events

SumnCap supports event callbacks such as:

SumnCap.render("#captcha", {
    mode: "managed",

    onReady() {
        console.log("SumnCap ready");
    },

    onChallenge() {
        console.log("Challenge required");
    },

    onSuccess(result) {
        console.log("Verification passed", result);
    },

    onFailure(error) {
        console.error("Verification failed", error);
    },

    onExpired() {
        console.log("Verification expired");
    }
});

📝 HTML Forms

SumnCap can automatically integrate with forms.

<form id="login">
    <input
        type="email"
        name="email"
        placeholder="Email"
    >

    <input
        type="password"
        name="password"
        placeholder="Password"
    >

    <div data-sumncap></div>

    <button type="submit">
        Login
    </button>
</form>

Then:

SumnCap.auto();

SumnCap can automatically manage its verification state and expose the resulting token to the form.

🧪 Security Testing

SumnCap should be tested against adversarial scenarios, including attempts to:

bypass the public API
modify internal state
manipulate the DOM
replace exposed functions
alter timers
replay challenges
automate pointer interactions
automate keyboard interactions
manipulate browser APIs
skip challenge states
directly trigger success callbacks
modify scores
run the library through browser automation

Security testing should be treated as an ongoing process rather than a one-time feature.

⚠️ Security Model

Important

SumnCap is 100% client-side.

That means it cannot provide cryptographic proof that a person is human.

A sufficiently capable attacker who controls the browser can ultimately inspect, modify, instrument or replace client-side code.

Therefore:

SumnCap is bot mitigation, not an absolute security boundary.

For highly sensitive operations, SumnCap should be combined with additional server-side security mechanisms such as:

authentication
authorization
rate limiting
server-side validation
WAF
abuse detection
account protections

SumnCap itself does not provide these mechanisms.

🏗️ Architecture

A simplified architecture:

┌──────────────────────────────────────┐
│              Web Page               │
│                                      │
│  ┌────────────────────────────────┐  │
│  │           SumnCap              │  │
│  │                                │  │
│  │  ┌──────────┐  ┌────────────┐ │  │
│  │  │ Behavior │  │ Environment│ │  │
│  │  │ Analysis │  │  Analysis  │ │  │
│  │  └────┬─────┘  └──────┬─────┘ │  │
│  │       │               │       │  │
│  │       └───────┬───────┘       │  │
│  │               ▼               │  │
│  │        Risk Evaluation        │  │
│  │               │               │  │
│  │        ┌──────┴──────┐        │  │
│  │        ▼             ▼        │  │
│  │      PASS         CHALLENGE   │  │
│  │                      │        │  │
│  │                      ▼        │  │
│  │                  Validation   │  │
│  └────────────────────────────────┘  │
└──────────────────────────────────────┘

🤝 Contributing

Contributions are welcome.

Before submitting a pull request:

Keep the library lightweight.
Avoid unnecessary dependencies.
Preserve backwards compatibility when possible.
Add tests for new functionality.
Consider accessibility.
Consider privacy implications.
Benchmark performance-sensitive changes.
Never introduce a security feature without documenting its threat model.

📄 License

See LICENSE for the license governing this project.

Sumnatic

SumnCap is part of the Sumnatic ecosystem — a collection of privacy-conscious, developer-focused and user-friendly technology products.

SumnCap — CAPTCHA shouldn't be annoying.

Simple. Fast. Lightweight. Private.

Name		Name	Last commit message	Last commit date
LICENSE		LICENSE
README.md		README.md

Latest commit

History

Folders and files

Repository files navigation