@stopnetic/js 0.1.2 → 0.1.3

package/README.md

@@ -1,5 +1,34 @@
 # @stopnetic/js - JavaScript and TypeScript website guard
 
+## First-party automation mode (unreleased)
+
+Repository server option `botProtection: 'monitor' | 'block'` defaults to `'off'`.
+Environment-based server helpers also support `STOPNETIC_BOT_PROTECTION`.
+This requires the matching service and a new SDK release after 0.1.2. Client
+automation evidence can be hidden; stealth agents may still pass. Public routes
+stay public. No external detection provider is used.
+See [configuration, tests and limits](../../docs/bot-protection.md).
+
+Prepared protocol 2 adds browser-report consistency, fresh server-verified SHA-256
+work and a per-binding verification budget. Modern secure-context Web Crypto is
+required for block mode. Fully concealed browsers doing valid work may still
+pass; monitor records evidence without these additional denials.
+
+Additional prepared hardening observes non-native webdriver getter replacements.
+For Vercel-hosted server guards, optional `botClientSource: 'vercel'` adds shared
+network budgets that survive cookie clearing and SDK worker changes. Use monitor
+first. It needs actual trusted Vercel ingress and the matching service; missing
+metadata withholds private access. The raw IP remains on the customer server;
+a daily, site-scoped HMAC key is used only for short-lived counters, not events.
+Server helpers accept `STOPNETIC_BOT_CLIENT_SOURCE=vercel`. Default source is `none`; no customer database or external detector is required.
+Native-looking low-volume stealth and network rotation can still pass. See the
+linked protection guide for thresholds, shared-network risks and test results.
+
+Prepared `requireApprovedAccount: true` plus a server-side authorizeVisitor
+callback can additionally require the customer's currently approved account for
+every protected request. This is an integration contract, not a login/passkey
+service. See [approved access](../../docs/approved-access.md).
+
 ## Verification screen update (unreleased)
 
 The shared guard now prepares a centered Stopnetic-branded verification screen,

package/dist/bot-protection.js

@@ -0,0 +1,51 @@
+import { createHmac } from 'node:crypto';
+import { isIP } from 'node:net';
+
+// Coarse, spoofable observations. No raw user-agent, IP or fingerprint leaves
+// the installation. An empty list is never evidence of a human visitor.
+/** @param {Request} request @param {boolean | null} [webdriver] @param {boolean} [inconsistent] @param {boolean} [tampered] */
+export function automationSignals(request, webdriver = null, inconsistent = false, tampered = false) {
+  const ua = (request.headers.get('user-agent') || '').slice(0, 1024);
+  const signals = [];
+  if (/bot|crawler|spider/i.test(ua)) signals.push('ua_bot');
+  if (/\b(?:curl|wget|python|httpclient|node-fetch|undici|go-http-client|postmanruntime)\b/i.test(ua)) signals.push('ua_script');
+  if (/headless/i.test(ua)) signals.push('ua_headless');
+  if (webdriver === true) signals.push('webdriver');
+  if (inconsistent) signals.push('webdriver_inconsistent');
+  if (tampered) signals.push('webdriver_tampered');
+  return signals;
+}
+
+export function sameBotControl(actual, expected) {
+  return actual?.version === 2 && actual.mode === expected.mode
+    && Array.isArray(actual.signals) && actual.signals.length === expected.signals.length
+    && actual.signals.every((signal, index) => signal === expected.signals[index]);
+}
+
+// Trust only an explicitly configured Vercel ingress. Never fall back to
+// arbitrary X-Forwarded-For, country, cookies or browser-supplied identifiers.
+export function botClientContext(request, source, secret, scope) {
+  if (source === 'none') return {};
+  let network = null;
+  if (process.env.VERCEL === '1') {
+    const raw = (request.headers.get('x-vercel-forwarded-for') || '').trim();
+    const family = raw.length <= 45 && !raw.includes('%') ? isIP(raw) : 0;
+    if (family === 4) network = 'v4:' + raw;
+    if (family === 6) {
+      const canonical = new URL(`http://[${raw}]/`).hostname.slice(1, -1);
+      const [left, right] = canonical.split('::');
+      const head = left ? left.split(':') : [];
+      const tail = right ? right.split(':') : [];
+      const groups = right !== undefined ? [...head, ...Array(8 - head.length - tail.length).fill('0'), ...tail] : head;
+      const words = groups.map(value => parseInt(value, 16));
+      // IPv4-mapped IPv6 must share its IPv4 budget; ordinary IPv6 groups use
+      // /64 so rotating addresses inside one network cannot reset the budget.
+      network = words.slice(0, 5).every(value => value === 0) && words[5] === 65535
+        ? 'v4:' + [words[6] >> 8, words[6] & 255, words[7] >> 8, words[7] & 255].join('.')
+        : 'v6:' + words.slice(0, 4).map(value => value.toString(16).padStart(4, '0')).join(':');
+    }
+  }
+  const epoch = Math.floor(Date.now() / 86400000);
+  return { bot_client: { version: 1, source, key: network === null ? null
+    : createHmac('sha256', secret).update(`stopnetic-network-v1:${scope}:${epoch}:${network}`).digest('hex') } };
+}

package/dist/browser-check.js

@@ -0,0 +1,55 @@
+export const botWorkChallenge = { version: 1, algorithm: 'sha256', difficulty: 12, max_nonce: 1_048_575 };
+
+export function validBotWork(value) {
+  return value && Object.keys(value).length === 4
+    && Object.entries(botWorkChallenge).every(([key, expected]) => value[key] === expected);
+}
+
+// This function is serialized into the nonce-authorized challenge script.
+// These observations can be forged; server-verified work is a separate check.
+export function collectBrowserEvidence() {
+  let webdriver = null;
+  let prototypeValue = null;
+  let webdriverTampered = false;
+  try { if (typeof navigator.webdriver === 'boolean') webdriver = navigator.webdriver; } catch { /* Unavailable, not a bot verdict. */ }
+  try {
+    let prototype = Object.getPrototypeOf(navigator);
+    for (let depth = 0; prototype && depth < 4; depth++, prototype = Object.getPrototypeOf(prototype)) {
+      const descriptor = Object.getOwnPropertyDescriptor(prototype, 'webdriver');
+      if (typeof descriptor?.get === 'function') {
+        // A replaced getter is an observation, not proof of automation.
+        const source = Function.prototype.toString.call(descriptor.get);
+        const value = descriptor.get.call(navigator);
+        if (typeof value === 'boolean') {
+          prototypeValue = value;
+          webdriverTampered = webdriver !== null && !/\{\s*\[native code\]\s*\}/.test(source);
+        }
+        break;
+      }
+    }
+  } catch { /* Privacy tooling and unsupported APIs are not denial evidence. */ }
+  return { webdriver, webdriverInconsistent: webdriver !== null && prototypeValue !== null && webdriver !== prototypeValue, webdriverTampered };
+}
+
+// A bounded, transparent work factor, not proof of humanity. No custom crypto,
+// third-party script, persistent fingerprint or hidden background worker.
+export async function solveBrowserWork(challengeId, signal) {
+  const encoder = new TextEncoder();
+  const started = performance.now();
+  for (let first = 0; first <= 1_048_575; first += 32) {
+    if (signal.aborted || performance.now() - started > 8000) return null;
+    const values = await Promise.all(Array.from({ length: 32 }, async (_, offset) => {
+      const nonce = first + offset;
+      const digest = new Uint8Array(await crypto.subtle.digest('SHA-256', encoder.encode(`stopnetic-work-v1:${challengeId}:${nonce}`)));
+      return digest[0] === 0 && (digest[1] & 240) === 0 ? nonce : null;
+    }));
+    const result = values.find(value => value !== null);
+    if (result !== undefined) return result;
+  }
+  return null;
+}
+
+export function verificationScript(ticket, verifyPath, enabled, challengeId) {
+  const evidence = enabled ? `body.browser=(${collectBrowserEvidence.toString()})();try{const nonce=await (${solveBrowserWork.toString()})(${JSON.stringify(challengeId)},controller.signal);if(nonce!==null)body.proof={version:1,nonce}}catch{}` : '';
+  return `const controller=new AbortController();const timeout=setTimeout(()=>{controller.abort();failed()},12000);document.getElementById('check-retry').addEventListener('click',()=>location.reload());function failed(){document.getElementById('check-spinner').hidden=true;document.getElementById('check-title').textContent='Unable to complete the check';document.getElementById('check-message').textContent='Please try again. If the problem continues, contact the website owner.';document.getElementById('check-retry').hidden=false}async function run(){const body={ticket:${JSON.stringify(ticket)}};${evidence};const result=await fetch(${JSON.stringify(verifyPath)},{method:'POST',credentials:'same-origin',signal:controller.signal,headers:{'content-type':'application/json'},body:JSON.stringify(body)});if(result.ok)location.reload();else failed()}run().catch(failed).finally(()=>clearTimeout(timeout))`;
+}

package/dist/guard.d.ts

@@ -13,6 +13,19 @@ export type StopneticOptions = {
   timeoutMs?: number;
   publicPaths?: string[];
   reportEvents?: boolean;
+  /** Require the customer's server-validated approved account on protected routes.
+   * Rechecked on each request; independent of bot detection. */
+  requireApprovedAccount?: boolean;
+  /** Must validate an active session and explicit approval using trusted server
+   * data. Only literal true grants approval. Never trust a visitor header/flag. */
+  authorizeVisitor?: (request: Request) => boolean | Promise<boolean>;
+  /** First-party, spoofable automation signals on protected routes. Default off.
+   * Monitor records evidence; block requires bounded server-verified work and
+   * rejects detected signals. Neither establishes human identity. */
+  botProtection?: 'off' | 'monitor' | 'block';
+  /** Optional shared network traffic budgets. Vercel-only trusted ingress; raw IP
+   * stays on the customer server. Missing metadata withholds private access. */
+  botClientSource?: 'none' | 'vercel';
   /** Optional coarse request analytics. No raw visitor IP or user-agent is sent. */
   trafficInsights?: boolean;
   /** Opt into country controls; requires trusted countrySource and no publicPaths. */
@@ -25,6 +38,8 @@ export type StopneticOptions = {
 };
 export function parseAdditionalDecisionPublicKeys(value?: string): string[];
 export function createStopnetic(options: StopneticOptions): {
+  /** Local configured capability declaration, not a deployment attestation. */
+  readonly capabilities: { readonly approvedAccountGate: boolean; readonly botProtocol: 2 };
   check(request: Request): Promise<Response | null>;
   verify(request: Request): Promise<Response>;
 };

package/dist/guard.js

@@ -2,6 +2,8 @@ import { createHash, createHmac, randomBytes, timingSafeEqual, verify as verifyS
 import { trustedSigningKeys } from './signing-keys.js';
 import { trafficContext } from './traffic-context.js';
 import { verificationPage } from './verification-page.js';
+import { automationSignals, sameBotControl, botClientContext } from './bot-protection.js';
+import { validBotWork, verificationScript } from './browser-check.js';
 export { parseAdditionalDecisionPublicKeys } from './signing-keys.js';
 
 const unavailable = retryAfter => new Response(null, { status: 503, headers: {
@@ -51,10 +53,9 @@ async function limitedBody(request, maxBytes) {
   return Buffer.concat(chunks, length).toString('utf8');
 }
 
-function bootstrap(ticket, verifyPath) {
+function bootstrap(ticket, verifyPath, botProtection, challengeId) {
   const nonce = randomBytes(16).toString('base64');
-  const script = `const controller=new AbortController();const timeout=setTimeout(()=>controller.abort(),12000);document.getElementById('check-retry').addEventListener('click',()=>location.reload());function failed(){document.getElementById('check-spinner').hidden=true;document.getElementById('check-title').textContent='Unable to complete the check';document.getElementById('check-message').textContent='Please try again. If the problem continues, contact the website owner.';document.getElementById('check-retry').hidden=false}fetch(${JSON.stringify(verifyPath)}, {method:'POST', credentials:'same-origin', signal:controller.signal, headers:{'content-type':'application/json'}, body:JSON.stringify({ticket:${JSON.stringify(ticket)}})}).then(r=>{if(r.ok)location.reload();else failed()}).catch(failed).finally(()=>clearTimeout(timeout))`;
-  const html = verificationPage(nonce, script);
+  const html = verificationPage(nonce, verificationScript(ticket, verifyPath, botProtection !== 'off', challengeId));
   return new Response(html, { status: 404, headers: {
     'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store', 'vary': 'Cookie',
     'content-security-policy': `default-src 'none'; script-src 'nonce-${nonce}'; style-src 'nonce-${nonce}'; img-src data:; connect-src 'self'; base-uri 'none'; form-action 'none'`,
@@ -64,7 +65,7 @@ function bootstrap(ticket, verifyPath) {
 
 /** Pilot guard for server-side Next.js Proxy and Route Handlers. */
 export function createStopnetic({ siteId, apiUrl, apiToken, decisionPublicKey, additionalDecisionPublicKeys = [], cookieSecret, verifyPath = '/__stopnetic/verify',
-  cookieName = 'stopnetic_pilot_session', secureCookie = true, fetchImpl = fetch, timeoutMs = 2000, publicPaths = [], reportEvents = true, guardMode = 'selected', trafficInsights = false, countrySource = 'none', countryBlocking = false }) {
+  cookieName = 'stopnetic_pilot_session', secureCookie = true, fetchImpl = fetch, timeoutMs = 2000, publicPaths = [], reportEvents = true, guardMode = 'selected', trafficInsights = false, countrySource = 'none', countryBlocking = false, botProtection = 'off', botClientSource = 'none', requireApprovedAccount = false, authorizeVisitor }) {
   if (!/^[a-z0-9][a-z0-9_-]{0,63}$/.test(siteId || '')) throw new Error('Invalid siteId');
   const credential = typeof apiToken === 'string' ? apiToken.match(/^[a-z]{1,32}_([a-f0-9]{32})\.[A-Za-z0-9_-]{43}$/) : null;
   if (!credential) throw new Error('apiToken must be an issued installation key');
@@ -86,6 +87,13 @@ export function createStopnetic({ siteId, apiUrl, apiToken, decisionPublicKey, a
   if (!Array.isArray(publicPaths) || publicPaths.some(path => typeof path !== 'string' || !/^\/[a-zA-Z0-9_\-/.]*(?:\*)?$/.test(path))) throw new Error('Invalid publicPaths');
   if (!['selected', 'site'].includes(guardMode)) throw new Error('Invalid guardMode');
   if (typeof countryBlocking !== 'boolean') throw new Error('Invalid countryBlocking');
+  if (typeof requireApprovedAccount !== 'boolean') throw new Error('Invalid requireApprovedAccount');
+  if (requireApprovedAccount && typeof authorizeVisitor !== 'function') throw new Error('requireApprovedAccount requires a server-side authorizeVisitor function');
+  if (!requireApprovedAccount && authorizeVisitor !== undefined) throw new Error('authorizeVisitor requires requireApprovedAccount');
+  if (requireApprovedAccount && publicPaths.length) throw new Error('requireApprovedAccount requires no publicPaths bypasses');
+  if (!['none', 'vercel'].includes(botClientSource) || (botClientSource !== 'none' && botProtection === 'off')) throw new Error('botClientSource requires an enabled botProtection mode and supported ingress');
+  if (!['off', 'monitor', 'block'].includes(botProtection)) throw new Error('Invalid botProtection');
+  if (botProtection !== 'off' && publicPaths.length) throw new Error('botProtection requires no publicPaths bypasses');
   if (countryBlocking && (countrySource === 'none' || publicPaths.length)) throw new Error('countryBlocking requires an explicit countrySource and no publicPaths bypasses');
   const publicKeys = trustedSigningKeys(decisionPublicKey, additionalDecisionPublicKeys);
   const verifyEndpoint = new URL('./verify', endpoint);
@@ -135,6 +143,39 @@ export function createStopnetic({ siteId, apiUrl, apiToken, decisionPublicKey, a
         || (country.result !== 'disabled' && country.revision === null)
         || (!['disabled', 'pass'].includes(country.result) && payload.action !== 'block')) throw new Error('Invalid country decision');
     }
+    if (botProtection !== 'off') {
+      const bot = payload.bot_decision;
+      if (!sameBotControl(payload.bot_control, input.bot_control) || !sameBotControl(bot, input.bot_control)
+        || !Array.isArray(bot.server_signals) || bot.server_signals.length > 5
+        || new Set(bot.server_signals).size !== bot.server_signals.length
+        || !bot.server_signals.every(signal => ['work_missing', 'work_invalid', 'verification_rate', 'request_rate', 'network_verification_rate'].includes(signal))
+        || typeof bot.work_verified !== 'boolean'
+        || !['observe', 'continue', 'block', 'public'].includes(bot.result)
+        || (botProtection === 'monitor' && bot.result !== 'observe')
+        || (botProtection === 'block' && (bot.result === 'observe'
+          || ((input.bot_control.signals.length > 0 || bot.server_signals.length > 0) && bot.result === 'continue')
+          || (purpose === 'verify' && payload.action === 'verified' && !bot.work_verified)))
+        || (bot.result === 'block' && payload.action !== 'block')
+        || (bot.result === 'public' && payload.action !== 'public'
+          && !(payload.action === 'block' && payload.country_decision
+            && !['disabled', 'pass'].includes(payload.country_decision.result)))) throw new Error('Invalid automation decision');
+    }
+    if (botClientSource !== 'none') {
+      const client = payload.bot_client;
+      if (client?.version !== 1 || client.source !== botClientSource || client.key !== input.bot_client?.key) throw new Error('Invalid client rate context');
+    }
+    if (requireApprovedAccount) {
+      const control = payload.approved_access;
+      const approval = payload.approval_decision;
+      const deniedCountry = payload.country_decision && !['disabled', 'pass'].includes(payload.country_decision.result);
+      if (control?.version !== 1 || control.required !== true || control.status !== input.approved_access.status
+        || approval?.version !== 1 || !['public', 'approved', 'required', 'unavailable'].includes(approval.result)
+        || (approval.result === 'approved' && control.status !== 'approved')
+        || (approval.result === 'required' && (control.status !== 'unapproved' || payload.action !== 'block'))
+        || (approval.result === 'unavailable' && (control.status !== 'unavailable' || !deniedCountry || payload.action !== 'block'))
+        || (approval.result === 'public' && payload.action !== 'public' && !(deniedCountry && payload.action === 'block'))
+        || (purpose === 'verify' && payload.action === 'verified' && approval.result !== 'approved')) throw new Error('Invalid account approval decision');
+    }
     return { ...payload, receipt: envelope.decision };
   }
 
@@ -155,6 +196,11 @@ export function createStopnetic({ siteId, apiUrl, apiToken, decisionPublicKey, a
     const payload = verified(value, cookieSecret);
     const binding = browserBinding(request);
     return payload?.kind === 'session' && payload.site === siteId && payload.installation === installation
+      && (botProtection === 'off' || (payload.bot_mode === botProtection && payload.bot_version === 2
+        && (typeof payload.webdriver === 'boolean' || payload.webdriver === null)
+        && typeof payload.webdriver_inconsistent === 'boolean' && typeof payload.webdriver_tampered === 'boolean'
+        && (botProtection !== 'block' || payload.work_verified === true)))
+      && (botClientSource === 'none' || (payload.bot_client_key && payload.bot_client_key === clientContext(request).bot_client.key))
       && binding && payload.browser_hash === hash(binding) ? payload : null;
   }
 
@@ -163,6 +209,27 @@ export function createStopnetic({ siteId, apiUrl, apiToken, decisionPublicKey, a
       country: trafficContext(request, true, countrySource).country } } : {};
   }
 
+  function clientContext(request) { return botClientContext(request, botClientSource, cookieSecret, `${siteId}:${installationId}`); }
+
+  function botControl(request, webdriver = null, inconsistent = false, tampered = false) {
+    return botProtection === 'off' ? {} : { bot_control: { version: 2, mode: botProtection,
+      signals: automationSignals(request, webdriver, inconsistent, tampered) } };
+  }
+
+  async function approvedAccess(request) {
+    if (!requireApprovedAccount) return {};
+    let status;
+    let timer;
+    try {
+      const result = await Promise.race([Promise.resolve().then(() => authorizeVisitor(request)),
+        new Promise((_, reject) => { timer = setTimeout(() => reject(new Error('Approval unavailable')), timeoutMs); })]);
+      status = result === true ? 'approved' : 'unapproved';
+    }
+    catch { status = 'unavailable'; }
+    finally { clearTimeout(timer); }
+    return { approved_access: { version: 1, required: true, status } };
+  }
+
   async function check(request) {
     const path = new URL(request.url).pathname;
     if (path === verifyPath) return null;
@@ -179,7 +246,7 @@ export function createStopnetic({ siteId, apiUrl, apiToken, decisionPublicKey, a
     let policy;
     try {
       const context = trafficContext(request, trafficInsights, countrySource);
-      policy = await remote('decision', { path, method: request.method, ...countryControl(request), ...(context ? { traffic_context: context } : {}), ...(guardMode === 'site' ? { guard_mode: 'site' } : {}), ...(binding ? { browser_binding: binding } : {}),
+      policy = await remote('decision', { path, method: request.method, ...countryControl(request), ...await approvedAccess(request), ...botControl(request, session?.webdriver, session?.webdriver_inconsistent, session?.webdriver_tampered), ...clientContext(request), ...(context ? { traffic_context: context } : {}), ...(guardMode === 'site' ? { guard_mode: 'site' } : {}), ...(binding ? { browser_binding: binding } : {}),
         ...(challenge ? { session_challenge: challenge } : {}) });
     } catch (error) { return unavailable(error?.retryAfter); }
     if (!policy || !['public', 'block', 'human', 'verified', 'entitled', 'default'].includes(policy.action)) return unavailable();
@@ -190,9 +257,13 @@ export function createStopnetic({ siteId, apiUrl, apiToken, decisionPublicKey, a
     if (session) { await report(policy, 'ALLOW', true); return null; }
     if (policy.action === 'verified' || !eligible) { await report(policy, 'BLOCK'); return concealed(); }
     if (!/^[A-Za-z0-9_-]{43}$/.test(policy.challenge_id || '')) return unavailable();
+    if (botProtection !== 'off' && !validBotWork(policy.bot_work)) return unavailable();
     const ticket = signed({ v: 1, kind: 'challenge', site: siteId, path, exp: Date.now() + 60_000,
+      ...(requireApprovedAccount ? { approval_required: true } : {}),
+      ...(botClientSource !== 'none' ? { bot_client_key: clientContext(request).bot_client.key } : {}),
+      ...(botProtection !== 'off' ? { bot_mode: botProtection, bot_version: 2 } : {}),
       challenge_id: policy.challenge_id, browser_hash: hash(binding), installation }, cookieSecret);
-    const response = bootstrap(ticket, verifyPath);
+    const response = bootstrap(ticket, verifyPath, botProtection, policy.challenge_id);
     response.headers.set('set-cookie', cookie(browserCookieName, signed({ v: 1, kind: 'browser', site: siteId,
       binding, installation, exp: Date.now() + 600_000 }, cookieSecret), 600));
     await report(policy, 'CHALLENGE');
@@ -213,22 +284,51 @@ export function createStopnetic({ siteId, apiUrl, apiToken, decisionPublicKey, a
     let body;
     try { body = await limitedBody(request, 4096); } catch { return concealed(); }
     let ticket;
-    try { ticket = JSON.parse(body).ticket; } catch { return concealed(); }
+    let browser;
+    let proof;
+    try { const input = JSON.parse(body); ticket = input.ticket; browser = input.browser; proof = input.proof; } catch { return concealed(); }
     const payload = verified(ticket, cookieSecret);
     const binding = browserBinding(request);
     if (payload?.kind !== 'challenge' || payload.site !== siteId || payload.installation !== installation
       || typeof payload.path !== 'string' || !/^\/[^\s?#]*$/.test(payload.path) || !binding
       || payload.browser_hash !== hash(binding) || !/^[A-Za-z0-9_-]{43}$/.test(payload.challenge_id || '')) return concealed();
+    if (requireApprovedAccount && payload.approval_required !== true) return concealed();
+    if (botProtection !== 'off' && (payload.bot_mode !== botProtection || payload.bot_version !== 2 || !browser
+      || !Object.hasOwn(browser, 'webdriver') || Object.keys(browser).length !== 3
+      || typeof browser.webdriverTampered !== 'boolean'
+      || typeof browser.webdriverInconsistent !== 'boolean'
+      || !(typeof browser.webdriver === 'boolean' || browser.webdriver === null))) return concealed();
+    if (botProtection !== 'off' && proof !== undefined && (!proof || Object.keys(proof).length !== 2
+      || proof.version !== 1 || !Number.isSafeInteger(proof.nonce) || proof.nonce < 0 || proof.nonce > 1_048_575)) return concealed();
+    if (botClientSource !== 'none') {
+      const client = clientContext(request).bot_client;
+      if (!client.key) return unavailable();
+      if (payload.bot_client_key !== client.key) return concealed();
+    }
+    let workVerified = false;
     try {
-      const result = await remote('verify', { path: payload.path, method: 'POST', challenge_id: payload.challenge_id, browser_binding: binding, ...countryControl(request) });
+      const result = await remote('verify', { path: payload.path, method: 'POST', challenge_id: payload.challenge_id, browser_binding: binding, ...countryControl(request), ...await approvedAccess(request), ...botControl(request, browser?.webdriver, browser?.webdriverInconsistent, browser?.webdriverTampered), ...clientContext(request),
+        ...(botProtection !== 'off' && proof ? { bot_proof: proof } : {}) });
       if (result.action === 'block' && result.country_decision && !['disabled', 'pass'].includes(result.country_decision.result)) {
         await report(result, 'BLOCK');
         return concealed();
       }
+      if (result.action === 'block' && result.bot_decision?.result === 'block') {
+        await report(result, 'BLOCK');
+        return concealed();
+      }
+      if (result.action === 'block' && result.approval_decision?.result === 'required') {
+        await report(result, 'BLOCK');
+        return concealed();
+      }
       if (result.action !== 'verified' || result.challenge_id !== payload.challenge_id) return unavailable();
+      workVerified = result.bot_decision?.work_verified === true;
       await report(result, 'VERIFIED');
     } catch (error) { return unavailable(error?.retryAfter); }
     const session = signed({ v: 1, kind: 'session', site: siteId, installation,
+      ...(botProtection !== 'off' ? { bot_mode: botProtection, bot_version: 2, webdriver: browser.webdriver,
+        webdriver_inconsistent: browser.webdriverInconsistent, webdriver_tampered: browser.webdriverTampered, work_verified: workVerified } : {}),
+      ...(botClientSource !== 'none' ? { bot_client_key: clientContext(request).bot_client.key } : {}),
       browser_hash: hash(binding), challenge_id: payload.challenge_id, challenge_path: payload.path,
       exp: Date.now() + 300_000 }, cookieSecret);
     return new Response(null, { status: 204, headers: {
@@ -237,5 +337,5 @@ export function createStopnetic({ siteId, apiUrl, apiToken, decisionPublicKey, a
     } });
   }
 
-  return { check, verify };
+  return { check, verify, capabilities: Object.freeze({ approvedAccountGate: requireApprovedAccount, botProtocol: 2 }) };
 }

package/dist/server.js

@@ -4,6 +4,7 @@ export const accessBase = '/api/stopnetic';
 
 /** Server environment only. Never import this module into browser code. */
 export function optionsFromEnv(env = process.env) {
+  if (env.STOPNETIC_REQUIRE_APPROVED_ACCOUNT && !['true', 'false'].includes(env.STOPNETIC_REQUIRE_APPROVED_ACCOUNT)) throw new Error('Invalid STOPNETIC_REQUIRE_APPROVED_ACCOUNT');
   return {
     origin: env.STOPNETIC_WEBSITE_ORIGIN,
     siteId: env.STOPNETIC_SITE_ID,
@@ -16,6 +17,9 @@ export function optionsFromEnv(env = process.env) {
     cookieSecret: env.STOPNETIC_COOKIE_SECRET,
     guardMode: 'site',
     trafficInsights: env.STOPNETIC_TRAFFIC_INSIGHTS === 'true',
+    botProtection: env.STOPNETIC_BOT_PROTECTION || 'off',
+    botClientSource: env.STOPNETIC_BOT_CLIENT_SOURCE || 'none',
+    requireApprovedAccount: env.STOPNETIC_REQUIRE_APPROVED_ACCOUNT === 'true',
     countryBlocking: env.STOPNETIC_COUNTRY_BLOCKING === 'true',
     countrySource: env.STOPNETIC_COUNTRY_SOURCE || 'none',
     verifyPath: `${accessBase}/verify`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stopnetic/js",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Server-side Stopnetic guard for JavaScript websites, Node.js and Express-compatible servers.",
   "type": "module",
   "license": "MIT",