Important: Custom HTML replaces the default challenge page. Your code must handle the verification flow for the selected challenge type.
🎯 Challenge Types Overview
Cookie Challenge - Simple auto-verification. Just POST to /__neptune_verify without parameters.
PoW Challenge - Browser computes hash with leading zeros. Send type, challenge, nonce, hash to verify.
Captcha Challenge - User enters displayed code. Send type, captcha_id, captcha_input to verify.
1️⃣ Cookie Challenge (Default)
Simple verification - just call the endpoint:
fetch('/__neptune_verify', { method: 'POST' })
.then(r => r.json())
.then(data => {
if (data.status === 'verified') window.location.reload();
});
2️⃣ PoW Challenge (Premium)
Your page receives placeholders {{CHALLENGE}} and {{DIFFICULTY}}:
const challenge = '{{CHALLENGE}}';
const difficulty = {{DIFFICULTY}};
const target = '0'.repeat(difficulty);
async function sha256(msg) {
const buf = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(msg));
return [...new Uint8Array(buf)].map(b => b.toString(16).padStart(2,'0')).join('');
}
async function solve() {
let nonce = 0;
while (true) {
const hash = await sha256(challenge + ':' + nonce);
if (hash.startsWith(target)) {
// Submit solution
fetch('/__neptune_verify', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ type: 'pow', challenge, nonce, hash })
}).then(r => r.json()).then(d => {
if (d.status === 'verified') window.location.reload();
});
break;
}
nonce++;
}
}
solve();
3️⃣ Captcha Challenge (Premium)
Your page receives placeholders {{CAPTCHA_ID}} and {{CAPTCHA_IMAGE}} (base64 PNG):
🔒 Security: The captcha text is NEVER sent to the client. Only a server-generated image (base64 data URL) is provided. The actual text stays securely on the server.
let captchaId = '{{CAPTCHA_ID}}';
// Display the server-generated captcha image
// {{CAPTCHA_IMAGE}} is a base64 data URL (data:image/png;base64,...)
document.getElementById('captcha-img').src = '{{CAPTCHA_IMAGE}}';
function verify(userInput) {
fetch('/__neptune_verify', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
type: 'captcha',
captcha_id: captchaId,
captcha_input: userInput.toUpperCase()
})
}).then(r => r.json()).then(d => {
if (d.status === 'verified') window.location.reload();
else refreshCaptcha(); // Get new captcha on failure
});
}
// Refresh captcha - gets new image from server
function refreshCaptcha() {
fetch('/__neptune_captcha_refresh', { method: 'POST' })
.then(r => r.json())
.then(d => {
captchaId = d.captcha_id;
document.getElementById('captcha-img').src = d.captcha_image;
});
}
HTML example: <img id="captcha-img" src="{{CAPTCHA_IMAGE}}" alt="Captcha">
🔑 Key Points
- Endpoint:
POST /__neptune_verify
- Success Response:
{"status":"verified","redirect":"/"}
- Error Response:
{"status":"error","error":"..."}
- Captcha Refresh:
POST /__neptune_captcha_refresh returns captcha_id + captcha_image (base64)
💡 Tip: The placeholders ({{CHALLENGE}}, {{CAPTCHA_ID}}, etc.) are replaced server-side before the page is sent. Make sure your custom HTML matches the challenge type selected above!