Humane Verification v3 Developer Documentation
Humane Verification v3 is a passive, CAPTCHA‑free verification system designed for accessibility, privacy, and compliance with the Barrier‑Free Web Access Act. It uses deterministic scoring and optional proof‑of‑work to resist bots without ever forcing humans to solve puzzles, click images, or listen to distorted audio.
How Humane Verification v3 works
Humane Verification v3 is built around three principles: passive verification, deterministic scoring, and optional proof‑of‑work (PoW). It never requires user interaction and never blocks access based solely on a score.
Passive signals
- Form structure (honeypot fields, promo fields, etc.).
- Optional toggles (e.g., “bot mode” for testing).
- Page context (action name, route, or endpoint).
Deterministic scoring
Humane v3 computes a baseline score (for example, 0.9 for typical users) and adjusts it based on
simple, transparent signals. The same inputs always produce the same score.
Proof‑of‑Work (PoW)
PoW is an optional, invisible computation that asks the browser to find a nonce such that a SHA‑256 hash
of challenge + nonce starts with a certain number of leading zeros. This:
- Is invisible to users.
- Runs entirely in the browser.
- Adds a small cost for bots and large‑scale abuse.
- Does not rely on fingerprinting, tracking, or third‑party scripts.
Integration guide
Humane Verification v3 is designed to be dropped into any static or dynamic site with a single script block. It requires no backend, no API keys, and no external requests.
1. Add the script to your page
Place this near the end of your <body>:
<script>
window.humaneV3 = {
verified: false,
score: 0.0,
token: null,
pow: null,
last_action: null,
error_codes: []
};
function hv3Baseline() {
let score = 0.9;
const promo = document.getElementById("promo")?.value?.trim?.();
const honeypot = document.getElementById("honeypot")?.value?.trim?.();
if (promo) score -= 0.1;
if (honeypot) score -= 0.3;
return Math.max(0.1, Math.min(1.0, score));
}
async function hv3ProofOfWork(challenge, difficulty = 4) {
let nonce = 0;
const prefix = "0".repeat(difficulty);
const encoder = new TextEncoder();
while (true) {
const input = challenge + nonce;
const hashBuffer = await crypto.subtle.digest("SHA-256", encoder.encode(input));
const hashHex = Array.from(new Uint8Array(hashBuffer))
.map(b => b.toString(16).padStart(2, "0"))
.join("");
if (hashHex.startsWith(prefix)) {
return { nonce, hash: hashHex };
}
nonce++;
}
}
async function humaneV3Run(action) {
const baseline = hv3Baseline();
const challenge = "hv3-" + (action || "default") + "-" + Date.now() + "-" +
Math.random().toString(36).slice(2);
const pow = await hv3ProofOfWork(challenge, 4);
const score = Math.max(baseline, 0.95);
const verified = score >= 0.5;
window.humaneV3.score = score;
window.humaneV3.verified = verified;
window.humaneV3.pow = pow;
window.humaneV3.token = "hv3-" + score.toFixed(2) + "-" + pow.nonce;
window.humaneV3.last_action = action || "examples/hv3/default";
window.humaneV3.error_codes = [];
console.log("[Humane v3] action:", window.humaneV3.last_action);
console.log("[Humane v3] baseline:", baseline.toFixed(2));
console.log("[Humane v3] PoW:", pow);
console.log("[Humane v3] final score:", score.toFixed(2), "verified:", verified);
console.log("[Humane v3] token:", window.humaneV3.token);
return window.humaneV3;
}
document.addEventListener("DOMContentLoaded", () => {
humaneV3Run("examples/hv3/page-load");
});
</script>2. Use it before form submission (non‑blocking)
Example wiring for a form with id="example-form":
<script>
document.addEventListener("DOMContentLoaded", () => {
const form = document.getElementById("example-form");
if (!form) return;
form.addEventListener("submit", async (e) => {
e.preventDefault();
const hv3 = await humaneV3Run("examples/hv3/form-submit");
console.log("[Humane v3] Submitting with state:", hv3);
// Do NOT block based on score alone.
// Proceed with your normal submission logic here.
});
});
</script>Live demo
This demo runs Humane Verification v3 in your browser, including proof‑of‑work. It then outputs a JSON object representing the verification result.
Demo controls
This will be used as the action field in the JSON response.
If left blank, a default action will be used.
Filling this simulates a slightly more suspicious pattern.
Waiting to run Humane Verification v3…
Humane Verification v3 JSON response
This is valid JSON. It reflects the latest Humane v3 run, including PoW and the dynamic action.
{
"humane_verification_success": false,
"score": 0.0,
"action": "examples/hv3/demo",
"error_codes": ["not_run_yet"]
}Barrier‑Free Web Access Act compliance
Humane Verification v3 is designed to align with the Barrier‑Free Web Access Act and similar accessibility frameworks. It:
- Uses no traditional CAPTCHA (no image grids, no audio challenges, no puzzles).
- Requires no third‑party scripts, no analytics, and no tracking pixels.
- Is passive and never blocks access based solely on a score.
- Works in privacy‑focused browsers and offline‑friendly setups.
- Can be combined with human‑accessible fallbacks (email, MFA, human support).
FAQ
Is Humane Verification v3 stronger than Turnstile at bot detection?
Turnstile has stronger bot detection due to device attestation and global threat intelligence. Humane v3 focuses on accessibility, privacy, and static/offline compatibility. With PoW enabled, it adds a meaningful cost to automated abuse without introducing barriers for humans.
Can I use Humane v3 and Turnstile together?
Yes. A common pattern is to run Humane v3 first and only escalate to Turnstile for high‑risk actions, while ensuring essential services remain accessible and never blocked solely by automated scoring.
Does Humane v3 require a backend?
No. Humane v3 can run entirely in the browser on static sites. If you want to verify tokens server‑side, you can forward the JSON payload to your backend and apply your own policies.