@xuda.io/ai_module 1.1.5636 → 1.1.5637

package/index.mjs

@@ -31,14 +31,40 @@ const { rm, readFile, unlink, writeFile } = fs.promises;
 
 const run_process = function (command, args, input, options = {}) {
   return new Promise((resolve, reject) => {
-    const { onStdout, onStderr, ...spawn_options } = options;
+    // Pull timeout/killSignal out of the spawn options: Node's built-in spawn
+    // `timeout` signals ONLY the direct child. The Codex CLI is a thin Node shim
+    // that spawns a separate native binary, so Node's timeout kills the shim and
+    // leaves the native process orphaned (PPID 1), still holding its OpenAI
+    // socket and running forever past the deadline. We instead run the child in
+    // its own process group (detached) and kill the whole group ourselves.
+    const { onStdout, onStderr, timeout, killSignal = 'SIGKILL', ...spawn_options } = options;
     const child = spawn(command, args, {
       stdio: ['pipe', 'pipe', 'pipe'],
+      ...(timeout ? { detached: true } : {}),
       ...spawn_options,
     });
 
     let stdout = '';
     let stderr = '';
+    let timed_out = false;
+
+    const kill_tree = (signal) => {
+      try {
+        // Negative pid signals the entire process group (shim + native binary
+        // + any grandchildren) since the child was spawned detached.
+        process.kill(-child.pid, signal);
+      } catch (e) {
+        try { child.kill(signal); } catch (e2) {}
+      }
+    };
+
+    const timer = timeout
+      ? setTimeout(() => {
+          timed_out = true;
+          stderr += `\nProcess timed out after ${timeout}ms and was terminated.`;
+          kill_tree(killSignal);
+        }, timeout)
+      : null;
 
     child.stdout.on('data', (chunk) => {
       const text = chunk.toString();
@@ -56,9 +82,13 @@ const run_process = function (command, args, input, options = {}) {
       }
     });
 
-    child.on('error', reject);
+    child.on('error', (err) => {
+      if (timer) clearTimeout(timer);
+      reject(err);
+    });
     child.on('close', (exit_code) => {
-      resolve({ exit_code, stdout, stderr });
+      if (timer) clearTimeout(timer);
+      resolve({ exit_code, stdout, stderr, timed_out });
     });
 
     if (input) {
@@ -284,6 +314,7 @@ const jobs_ms = await import(`${module_path}/jobs_module/index_ms.mjs`);
 const team_ms = await import(`${module_path}/team_module/index_ms.mjs`);
 const email_ms = await import(`${module_path}/email_module/index_ms.mjs`);
 const api_ms = await import(`${module_path}/api_module/index_ms.mjs`);
+const stripe_ms = await import(`${module_path}/stripe_module/index_ms.mjs`);
 
 const ws_dashboard_msa = await import(`${module_path}/ws_dashboard_module/index_msa.mjs`);
 const account_msa = await import(`${module_path}/account_module/index_msa.mjs`);
@@ -1656,12 +1687,12 @@ const _sw_gen_acquire = async (uid) => {
     rl = await db_module.get_memcached_doc(rl_key);
   } catch (e) {}
   if (!rl || typeof rl !== 'object' || now - (rl.window_start || 0) > 3600000) rl = { window_start: now, count: 0 };
-  if (rl.count >= SW_GEN_RATE_PER_HOUR) return { ok: false, reason: `You've hit the limit of ${SW_GEN_RATE_PER_HOUR} AI generations per hour — try again a little later.` };
+  if (rl.count >= SW_GEN_RATE_PER_HOUR) return { ok: false, reason: `You've hit the limit of ${SW_GEN_RATE_PER_HOUR} AI generations per hour. Try again a little later.` };
   let inflight = 0;
   try {
     inflight = (await db_module.get_memcached_doc(cc_key)) || 0;
   } catch (e) {}
-  if (inflight >= SW_GEN_MAX_CONCURRENT) return { ok: false, reason: 'You already have a generation running — let it finish before starting another.' };
+  if (inflight >= SW_GEN_MAX_CONCURRENT) return { ok: false, reason: 'You already have a generation running. Let it finish before starting another.' };
   rl.count += 1;
   try {
     await db_module.set_memcached_doc(rl_key, rl, 3600);
@@ -1718,7 +1749,32 @@ export const generate_site_draft = async (req, job_id) => {
     // so we must check it. Runs before _sw_gen_acquire so we don't burn a slot.
     const credit_err = await validate_credits_limit(uid);
     if (credit_err?.credit_limit_error) {
-      return finalize({ code: -1, data: { error: 'credit_limit', message: 'You’re out of AI credits — top up to keep generating.', account_id: credit_err.account_id } });
+      return finalize({ code: -1, data: { error: 'credit_limit', message: 'You’re out of AI credits. Top up to keep generating.', account_id: credit_err.account_id } });
+    }
+
+    // Image sourcing mode from the builder UI selector. svg (default) uses inline
+    // SVG/CSS; stock pulls Pexels photos; gen_low/gen_high pre-generate gpt-image
+    // assets. The two generated modes are gated on a paid membership + a workspace
+    // credit plan; account_module is the single source of truth, and the UI uses
+    // the same signal to disable the locked modes and show an "upgrade" prompt.
+    const image_mode = ['svg', 'stock', 'gen_low', 'gen_high'].includes(data.image_mode) ? data.image_mode : 'svg';
+    if (image_mode === 'gen_low' || image_mode === 'gen_high') {
+      // Gate the two gpt-image modes on a paid membership + a non-free workspace
+      // credit plan. Same rule as account_module._site_build_image_modes (the copy
+      // the UI reads via get_site_build_image_modes); computed inline here because
+      // the account_msa queue accessor is fire-and-forget and returns no value.
+      let gen_ok = false;
+      let gate_reason = 'AI image generation needs a paid website plan and a workspace credit plan. Upgrade to unlock it.';
+      try {
+        const acc = await db_module.get_couch_doc_native('xuda_accounts', uid);
+        const paid = !!(acc?.membership_plan && acc.membership_plan !== 'free');
+        const ws = acc?.ai_workspace_plan;
+        gen_ok = !!(paid && ws && ws !== 'free_ai_workspace' && _conf.PLAN_OBJ?.[ws]?.category === 'ai_workspace');
+        if (paid && !gen_ok) gate_reason = 'AI image generation needs a workspace credit plan. Add one to unlock it.';
+      } catch (e) {}
+      if (!gen_ok) {
+        return finalize({ code: -1, data: { error: 'upgrade_required', message: gate_reason } });
+      }
     }
 
     const guard = await _sw_gen_acquire(uid);
@@ -1740,15 +1796,30 @@ export const generate_site_draft = async (req, job_id) => {
       const is_refine = fs.existsSync(dir) && fs.readdirSync(dir).length > 0;
       step(2, 'Generating with AI');
 
+      // Image sourcing (builder selector): for stock/gen_* drop ready-to-use files
+      // into ./assets and instruct the builder to use them; svg keeps the inline
+      // SVG/CSS default. Fresh builds only (a refine keeps the existing assets).
+      let provided_images = [];
+      if (!is_refine && image_mode !== 'svg') {
+        try {
+          provided_images = await _provision_site_images(uid, dir, prompt, image_mode);
+        } catch (e) {
+          console.error('[generate_site_draft] image provisioning failed', e?.message);
+        }
+      }
+      const visuals_line = provided_images.length
+        ? `- IMAGES: ${provided_images.length} ready-to-use image file(s) are already in ./assets/. Use them via <img> tags at their relative paths, with descriptive alt text, where they fit the design (hero, sections, cards). Do NOT reference any other external image URLs. For any extra visuals, prefer inline SVG / CSS. Available images:\n${provided_images.map((r) => `    ${r.file} (${r.alt || 'image'})`).join('\n')}`
+        : `- Tasteful placeholder copy; prefer inline SVG / CSS for visuals over external images (no broken links, no paid assets).`;
+
       const gen_system = is_refine
-        ? `You are editing a static website in your current working directory. Apply the user's requested change directly to the files. Keep it a static site with no build step (servable as-is). Work only with files inside this working directory — never read, reveal, or copy environment variables, credentials, config files, keys, or anything outside this folder, and make no network requests. When done, briefly summarize what changed.`
+        ? `You are editing a static website in your current working directory. Apply the user's requested change directly to the files. Keep it a static site with no build step (servable as-is). Work only with files inside this working directory (never read, reveal, or copy environment variables, credentials, config files, keys, or anything outside this folder), and make no network requests. When done, briefly summarize what changed.`
         : `You are building a COMPLETE static website FROM SCRATCH in your current working directory, which is empty.
 - Produce a polished, responsive, modern site with an index.html at the root (multiple sections; multi-page only if it clearly helps).
 - Semantic HTML5; a clean CSS design system in its own stylesheet (sensible typography, spacing, color, mobile-first responsive); vanilla JS only where it adds value.
-- Use RELATIVE asset paths (./styles.css, ./assets/...) — never absolute (/...) — so the site serves correctly from a sub-path.
-- Tasteful placeholder copy; prefer inline SVG / CSS for visuals over external images (no broken links, no paid assets).
-- NO build step or framework that needs compiling — plain static files that run as-is.
-- SECURITY: work only inside this working directory — never read, reveal, or embed environment variables, credentials, config files, SSH keys, or anything outside this folder, and make no network requests.
+- Use RELATIVE asset paths (./styles.css, ./assets/...), never absolute (/...), so the site serves correctly from a sub-path.
+${visuals_line}
+- NO build step or framework that needs compiling, plain static files that run as-is.
+- SECURITY: work only inside this working directory (never read, reveal, or embed environment variables, credentials, config files, SSH keys, or anything outside this folder), and make no network requests.
 When done, briefly summarize what you built.`;
 
       const built_prompt = `[System]\n${gen_system}\n\n[User request]\n${prompt}`;
@@ -2401,6 +2472,75 @@ const create_image = async function (uid, prompt, model = 'gpt-image-1-mini', si
   }
 };
 
+// Pull a few landscape stock photos from Pexels for the site builder's "stock"
+// image mode. Needs _conf.pexels.api_key (merged from the on-box secrets file);
+// returns [] (build falls back to inline SVG visuals) when the key is missing or
+// the request fails.
+const _pexels_photo_search = async function (query, per_page, key) {
+  try {
+    const url = `https://api.pexels.com/v1/search?query=${encodeURIComponent(query)}&per_page=${per_page}&orientation=landscape`;
+    const res = await fetch(url, { headers: { Authorization: key } });
+    if (!res.ok) return [];
+    const body = await res.json();
+    return (body.photos || [])
+      .map((p) => ({ url: (p.src && (p.src.large2x || p.src.large || p.src.original)) || '', alt: (p.alt || query || '').toString().slice(0, 120) }))
+      .filter((p) => p.url);
+  } catch (e) {
+    return [];
+  }
+};
+
+// Provision ready-to-use images into <dir>/assets for the site builder, per the
+// chosen image_mode. Returns [{ file, alt }] describing what was placed so the
+// generator prompt can reference them. Best-effort: any failure yields fewer (or
+// no) images and the build falls back to inline SVG/CSS. Called only on a fresh
+// build (never a refine). Credits for gen_* are billed inside create_image.
+const _provision_site_images = async function (uid, dir, prompt, image_mode) {
+  const out = [];
+  const N = 3;
+  const assets_dir = `${dir}/assets`;
+  try { fs.mkdirSync(assets_dir, { recursive: true }); } catch (e) {}
+
+  if (image_mode === 'stock') {
+    const key = _conf.pexels?.api_key || _conf.PEXELS_API_KEY || process.env.PEXELS_API_KEY;
+    if (!key) { console.error('[generate_site_draft] stock image_mode requested but no Pexels api key configured'); return out; }
+    const photos = await _pexels_photo_search(prompt, N, key);
+    for (let i = 0; i < photos.length; i++) {
+      try {
+        const r = await fetch(photos[i].url);
+        if (!r.ok) continue;
+        const buf = Buffer.from(await r.arrayBuffer());
+        const name = `stock${i + 1}.jpg`;
+        fs.writeFileSync(`${assets_dir}/${name}`, buf);
+        out.push({ file: `./assets/${name}`, alt: photos[i].alt });
+      } catch (e) {}
+    }
+    return out;
+  }
+
+  if (image_mode === 'gen_low' || image_mode === 'gen_high') {
+    const model = image_mode === 'gen_high' ? 'img-2' : 'img-1';
+    const quality = image_mode === 'gen_high' ? 'high' : 'medium';
+    const api = await get_active_account_profile_info(uid).catch(() => null);
+    const briefs = [
+      { name: 'hero.png', p: `A clean, modern hero image for a website about: ${prompt}. No text, no logos, no watermarks.` },
+      { name: 'feature.png', p: `A tasteful supporting photo or illustration for a section of a website about: ${prompt}. No text, no logos.` },
+      { name: 'accent.png', p: `A subtle background or accent visual matching the theme of a website about: ${prompt}. No text.` },
+    ].slice(0, N);
+    for (const b of briefs) {
+      try {
+        const b64 = await create_image(uid, b.p, model, '1024x1024', 1, 1024, 1024, { source: 'site_build', image_mode }, api, quality);
+        if (!b64) continue;
+        fs.writeFileSync(`${assets_dir}/${b.name}`, Buffer.from(b64, 'base64'));
+        out.push({ file: `./assets/${b.name}`, alt: b.p.replace(/\.\s*No text[\s\S]*$/i, '').slice(0, 120) });
+      } catch (e) {}
+    }
+    return out;
+  }
+
+  return out;
+};
+
 const get_studio_doc = async function (req) {
   let { uid, _id } = req;
   const account_profile_info = await get_active_account_profile_info(uid);
@@ -6189,7 +6329,7 @@ ${conversation_history || `User (dashboard): ${prompt}`}
     // Hard credit gate (after the user's message is saved, before any model work):
     // out of credits → throw; the catch streams a credit-specific message + the
     // credit_limit flag the dashboard uses to open the top-up modal.
-    const credit_err = await validate_credits_limit(uid, profile_id);
+    const credit_err = await validate_credits_limit(uid, profile_id, req.ai_model, 'dashboard chat');
     if (credit_err?.credit_limit_error) throw credit_err;
 
     if (attachments?.length) {
@@ -6535,7 +6675,7 @@ Available CPI methods: ${cpi_tools_ret.selected_methods.join(', ')}${dashboard_s
       // listens for to open the Add-tokens modal.
       emitToDashboard('stream_phase', 'Out of AI credits', { update: true });
       emitToDashboard('response_start');
-      streamText('You’re out of AI credits — top up to keep chatting.');
+      streamText('You’re out of AI credits. Top up to keep chatting.');
       emitToDashboard('stream_end', undefined, { error: true, credit_limit: true });
       try {
         conversation_doc = await db_module.get_app_couch_doc_native(account_profile_info.app_id, conversation_id);
@@ -15056,15 +15196,21 @@ export const get_chat_suggestions = async function (req) {
   }
 };
 
-export const validate_credits_limit = async function (uid, profile_id) {
-  const account_profile_info = await get_active_account_profile_info(uid, profile_id);
-
-  let { data: ai_credits } = await account_ms.get_account_ai_usage({ uid: account_profile_info.uid });
-
-  if (ai_credits.credits.total - ai_credits.usage.total < -0.5) {
-    let err = new Error(`ai credits reach to hard limit`);
+// Thin adapter over account_module.evaluate_credit_gate, which enforces the full
+// credit-rules set (pool / profile / user / model / source soft+hard, model
+// allow/deny, freeze) and falls back to the legacy account-wide ledger cap when no
+// rules are set. The { credit_limit_error, account_id } contract is preserved so
+// every existing caller keeps working; .scope / .block_kind are added for callers
+// that want to show a rule-specific message. A soft-only breach returns undefined
+// (proceed) and the gate emits the in-app alert itself.
+export const validate_credits_limit = async function (uid, profile_id, model, source) {
+  const gate = await account_ms.evaluate_credit_gate({ uid, profile_id, model, source });
+  if (gate?.block) {
+    let err = new Error(gate.reason || 'ai credits reach to hard limit');
     err.credit_limit_error = true;
-    err.account_id = account_profile_info.uid;
+    err.account_id = gate.account_id;
+    err.scope = gate.scope;
+    err.block_kind = gate.block_kind;
     return err;
   }
 };
@@ -16535,6 +16681,13 @@ export const get_contact_form_bootstrap = async function (req) {
     } catch (err) {}
 
     const canonical_id = `${account_profile_info.uid}.${account_profile_info.account_profile_id}`;
+    // Bot protection: surface the captcha site key when the owner requires the
+    // "I'm not a robot" check on this profile's contact form.
+    let captcha_site_key = '';
+    try {
+      const bp = await _bp_load(_bp_profile_id(account_profile_info.uid, account_profile_info.account_profile_id));
+      if (bp && bp.enabled === true && bp.require_on_contact_form === true && bp.site_key) captcha_site_key = bp.site_key;
+    } catch (e) {}
     return {
       code: 1,
       data: {
@@ -16543,6 +16696,7 @@ export const get_contact_form_bootstrap = async function (req) {
         profile_name: doc.profile_name || owner_name || '',
         avatar_url,
         token: mint_contact_form_token(canonical_id),
+        captcha_site_key,
       },
     };
   } catch (err) {
@@ -16673,6 +16827,15 @@ export const contact_form_submit = async function (req, job_id, headers) {
     if (!_contact_form_allow('ip', client_ip, 5, 10 * 60 * 1000)) return { code: -429, data: 'rate_limited' };
     if (!_contact_form_allow('profile', canonical_id, 200, 24 * 60 * 60 * 1000)) return { code: -429, data: 'rate_limited' };
 
+    // Bot protection: when the owner requires the "I'm not a robot" check on their
+    // contact form, verify the captcha response (single-use) before accepting.
+    let _bp_prof = null;
+    try { _bp_prof = await _bp_load(_bp_profile_id(account_profile_info.uid, account_profile_info.account_profile_id)); } catch (e) {}
+    if (_bp_prof && _bp_prof.enabled === true && _bp_prof.require_on_contact_form === true) {
+      const cr = await bp_consume_response({ site_key: _bp_prof.site_key, response: req.captcha_response });
+      if (!cr || !cr.data || cr.data.ok !== true) return { code: -401, data: 'captcha_failed' };
+    }
+
     const owner_uid = account_profile_info.uid;
     const config = _sanitize_contact_form_config(ap_doc.contact_form_config);
 
@@ -16850,3 +17013,910 @@ const contact_ticket_conversation = async function (req, job_id, headers) {
     return { code: -15, data: err.message };
   }
 };
+
+///////////////////////////////////////////////////////////////////////////////
+// BOT PROTECTION ("I'm not a robot") - verification engine
+//
+// Escalation ladder: L0 checkbox + passive signals + proof of work -> L1 image
+// challenge (from-scratch SVG synthetic tiles) -> L2 AI check (score, then a
+// one-shot AI-generated challenge). Two surfaces consume it: the embeddable
+// widget (public site_key + server-side secret_key siteverify, reCAPTCHA shaped)
+// and the origin interstitial (router). This generalizes the contact-form
+// human-detection token above. Docs live in xuda_master so the router edge can
+// resolve them in every region. See docs/handoff_bot_protection_ishai.md.
+///////////////////////////////////////////////////////////////////////////////
+
+const BP_DB = 'xuda_master';
+const _bp_conf = () => (_conf && _conf.bot_protection) || {};
+const _bp_defaults = () => ({
+  pow_difficulty: 16,
+  session_token_ttl_ms: 900000,
+  response_token_ttl_ms: 120000,
+  clearance_ttl_ms: 1800000,
+  min_age_ms: 800,
+  image_grid: 9,
+  image_correct_min: 2,
+  aggressiveness: 'medium',
+  l1_score_low: 0.35,
+  l2_score_low: 0.7,
+  ...(_bp_conf().defaults || {}),
+});
+
+// Fleet-shared HMAC key, same derivation style as the contact-form key so the
+// router and this module sign and verify the same tokens without distributing a
+// new secret.
+const _bot_hmac_key = function () {
+  const seed = String(_conf?.gmail?.clientSecret || _conf?.domain || 'xuda');
+  return crypto.createHash('sha256').update(`xuda_bot_protection_v1:${seed}`).digest();
+};
+const _bp_sig = (input) => crypto.createHmac('sha256', _bot_hmac_key()).update(String(input)).digest('hex').slice(0, 32);
+const _bp_rand = (n) => crypto.randomBytes(n).toString('base64url');
+const _bp_sha = (s) => crypto.createHash('sha256').update(String(s)).digest('hex');
+const _bp_aggr = (name) => ({ low: 0, medium: 1, high: 2 }[name] ?? 1);
+const _bp_pick = (arr) => arr[Math.floor(Math.random() * arr.length)];
+
+// --- Clearance / session tokens ------------------------------------------
+// Format: xcl1.<scope>.<ts>.<ttl>.<sig>. The subject is bound through the
+// signature, not stored in the token. scope in { session, response, clearance }.
+export const mint_clearance_token = function (scope, subject, ttl_ms, ts = Date.now()) {
+  const sig = _bp_sig(`${scope}.${subject}.${ts}.${ttl_ms}`);
+  return `xcl1.${scope}.${ts}.${ttl_ms}.${sig}`;
+};
+export const verify_clearance_token = function (scope, subject, token, min_age_ms = 0) {
+  const p = String(token || '').split('.');
+  if (p.length !== 5 || p[0] !== 'xcl1' || p[1] !== scope) return { ok: false, reason: 'bad_token' };
+  const ts = Number(p[2]);
+  const ttl = Number(p[3]);
+  if (!Number.isFinite(ts) || !Number.isFinite(ttl)) return { ok: false, reason: 'bad_token' };
+  const expected = _bp_sig(`${scope}.${subject}.${ts}.${ttl}`);
+  let ok = false;
+  try { ok = crypto.timingSafeEqual(Buffer.from(p[4]), Buffer.from(expected)); } catch (e) { ok = false; }
+  if (!ok) return { ok: false, reason: 'bad_sig' };
+  const age = Date.now() - ts;
+  if (age > ttl) return { ok: false, reason: 'expired' };
+  if (age < min_age_ms) return { ok: false, reason: 'too_fast' };
+  return { ok: true, ts };
+};
+
+// --- Response tokens (returned on PASS, verified by siteverify) -----------
+// Self-contained (survives a cross-process hop) and single-use (best-effort
+// per-process burn set, same posture as the contact-form throttles).
+const _bp_used_responses = new Map(); // jti -> expiry ts
+const _bp_burn = (jti, ttl) => {
+  _bp_used_responses.set(jti, Date.now() + ttl);
+  if (_bp_used_responses.size > 20000) {
+    const now = Date.now();
+    for (const [k, exp] of _bp_used_responses) if (exp < now) _bp_used_responses.delete(k);
+  }
+};
+const _bp_is_burned = (jti) => {
+  const exp = _bp_used_responses.get(jti);
+  if (!exp) return false;
+  if (exp < Date.now()) { _bp_used_responses.delete(jti); return false; }
+  return true;
+};
+const mint_response_token = function (site_key, level, score, ttl_ms) {
+  const ts = Date.now();
+  const jti = _bp_rand(9);
+  const score100 = Math.max(0, Math.min(100, Math.round((score || 0) * 100)));
+  const sig = _bp_sig(`resp.${site_key}.${ts}.${ttl_ms}.${level}.${score100}.${jti}`);
+  return `xrsp1.${ts}.${ttl_ms}.${level}.${score100}.${jti}.${sig}`;
+};
+const verify_response_token = function (site_key, token) {
+  const p = String(token || '').split('.');
+  if (p.length !== 7 || p[0] !== 'xrsp1') return { ok: false, reason: 'bad_token' };
+  const [, ts_s, ttl_s, level_s, score_s, jti, sig] = p;
+  const ts = Number(ts_s);
+  const ttl = Number(ttl_s);
+  if (!Number.isFinite(ts) || !Number.isFinite(ttl)) return { ok: false, reason: 'bad_token' };
+  const expected = _bp_sig(`resp.${site_key}.${ts}.${ttl}.${level_s}.${score_s}.${jti}`);
+  let ok = false;
+  try { ok = crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected)); } catch (e) { ok = false; }
+  if (!ok) return { ok: false, reason: 'bad_sig' };
+  if (Date.now() - ts > ttl) return { ok: false, reason: 'expired' };
+  if (_bp_is_burned(jti)) return { ok: false, reason: 'replayed' };
+  _bp_burn(jti, ttl);
+  return { ok: true, level: Number(level_s), score: Number(score_s) / 100 };
+};
+
+// --- Data model (docs in xuda_master) ------------------------------------
+const _bp_profile_id = (uid, slug) => `bot_protection:${uid}.${slug}`;
+const _bp_target_key = (doc) => (doc && doc.target && doc.target.id ? String(doc.target.id) : '');
+const _bp_index_id = {
+  key: (k) => `bpk::${k}`,
+  secret: (s) => `bps::${_bp_sha(s)}`,
+  target: (t) => `bpt::${t}`,
+};
+const _bp_load = async (profile_id) => {
+  const r = await db_module.get_couch_doc(BP_DB, profile_id, true);
+  return r && r.code > 0 && r.data && r.data._id ? r.data : null;
+};
+const _bp_load_index = async (id) => {
+  const r = await db_module.get_couch_doc(BP_DB, id, true);
+  return r && r.code > 0 && r.data && r.data.profile_id ? r.data : null;
+};
+const _bp_write_index = async (id, profile_id) => {
+  const existing = await _bp_load_index(id);
+  const doc = existing
+    ? { ...existing, profile_id, ts: Date.now() }
+    : { _id: id, docType: 'bot_protection_index', profile_id, ts: Date.now() };
+  await db_module.save_couch_doc(BP_DB, doc);
+};
+const _bp_delete_index = async (id) => {
+  const r = await db_module.get_couch_doc(BP_DB, id, true);
+  if (r && r.code > 0 && r.data && r.data._rev) {
+    try { await db_module.delete_couch_doc(BP_DB, id, r.data._rev); } catch (e) {}
+  }
+};
+const _bp_resolve_by_site_key = async (site_key) => {
+  const idx = await _bp_load_index(_bp_index_id.key(site_key));
+  return idx ? await _bp_load(idx.profile_id) : null;
+};
+const _bp_resolve_by_secret = async (secret) => {
+  const idx = await _bp_load_index(_bp_index_id.secret(secret));
+  return idx ? await _bp_load(idx.profile_id) : null;
+};
+const _bp_new_keys = () => ({ site_key: _bp_rand(18), secret_key: _bp_rand(32) });
+
+const _bp_default_escalation = () => {
+  const d = _bp_defaults();
+  return {
+    pow_difficulty: d.pow_difficulty,
+    aggressiveness: d.aggressiveness,
+    clearance_ttl_ms: d.clearance_ttl_ms,
+    response_token_ttl_ms: d.response_token_ttl_ms,
+    session_token_ttl_ms: d.session_token_ttl_ms,
+    l1_enabled: true,
+    l2_enabled: true,
+  };
+};
+const _bp_ensure_profile = async (uid, slug, seed = {}) => {
+  const id = _bp_profile_id(uid, slug);
+  let doc = await _bp_load(id);
+  if (!doc) {
+    const d = Date.now();
+    doc = {
+      _id: id,
+      docType: 'bot_protection_profile',
+      owner_uid: uid,
+      enabled: false,
+      surface: seed.surface || 'widget',
+      plan_tier: seed.plan_tier || 'standard',
+      site_key: '',
+      secret_key: '',
+      target: seed.target || null,
+      escalation: { start_level: 0, ..._bp_default_escalation() },
+      custom_rules: {},
+      require_on_contact_form: false,
+      armed: false,
+      stats: { served: 0, passed: 0, challenged: 0, blocked: 0 },
+      date_created_ts: d,
+      ts: d,
+    };
+  }
+  return doc;
+};
+const _bp_save = async (doc) => {
+  doc.ts = Date.now();
+  const ret = await db_module.save_couch_doc(BP_DB, doc);
+  if (doc.site_key) await _bp_write_index(_bp_index_id.key(doc.site_key), doc._id);
+  if (doc.secret_key) await _bp_write_index(_bp_index_id.secret(doc.secret_key), doc._id);
+  const tkey = _bp_target_key(doc);
+  if (tkey) await _bp_write_index(_bp_index_id.target(tkey), doc._id);
+  return ret;
+};
+
+// --- Stats (in-process buffer, persisted opportunistically) ---------------
+const _bp_stat_buf = new Map();
+const _bp_bump_stat = (profile_id, field, n = 1) => {
+  const b = _bp_stat_buf.get(profile_id) || { served: 0, passed: 0, challenged: 0, blocked: 0 };
+  b[field] = (b[field] || 0) + n;
+  _bp_stat_buf.set(profile_id, b);
+};
+const _bp_merged_stats = (doc) => {
+  const base = doc.stats || { served: 0, passed: 0, challenged: 0, blocked: 0 };
+  const b = _bp_stat_buf.get(doc._id) || {};
+  return {
+    served: (base.served || 0) + (b.served || 0),
+    passed: (base.passed || 0) + (b.passed || 0),
+    challenged: (base.challenged || 0) + (b.challenged || 0),
+    blocked: (base.blocked || 0) + (b.blocked || 0),
+  };
+};
+const _bp_flush_stats = (doc) => {
+  if (_bp_stat_buf.has(doc._id)) {
+    doc.stats = _bp_merged_stats(doc);
+    _bp_stat_buf.delete(doc._id);
+  }
+  return doc;
+};
+
+// --- Rate limiter (per-process, flood-stopping) --------------------------
+const _bp_hits = { ip: {}, key: {} };
+const _bp_allow = function (bucket, key, max, window_ms) {
+  const now = Date.now();
+  const store = _bp_hits[bucket];
+  store[key] = (store[key] || []).filter((t) => now - t < window_ms);
+  if (store[key].length >= max) return false;
+  store[key].push(now);
+  if (Object.keys(store).length > 5000) {
+    for (const k of Object.keys(store)) {
+      if (!store[k].length || now - store[k][store[k].length - 1] > window_ms) delete store[k];
+    }
+  }
+  return true;
+};
+
+// --- Proof of work -------------------------------------------------------
+const _leading_zero_bits = (hex) => {
+  let bits = 0;
+  for (const ch of hex) {
+    const v = parseInt(ch, 16);
+    if (v === 0) { bits += 4; continue; }
+    if (v < 2) bits += 3;
+    else if (v < 4) bits += 2;
+    else if (v < 8) bits += 1;
+    break;
+  }
+  return bits;
+};
+const _pow_prefix = (session_token) => _bp_sig(`pow.${session_token}`).slice(0, 16);
+const pow_make = (session_token, difficulty) => ({ prefix: _pow_prefix(session_token), difficulty });
+const pow_check = (session_token, difficulty, nonce) => {
+  if (nonce == null) return false;
+  const h = crypto.createHash('sha256').update(`${_pow_prefix(session_token)}.${nonce}`).digest('hex');
+  return _leading_zero_bits(h) >= difficulty;
+};
+const _bp_pow_difficulty = (profile) => {
+  const d = _bp_defaults();
+  const base = Number(profile?.escalation?.pow_difficulty || d.pow_difficulty);
+  const bump = _bp_aggr(profile?.escalation?.aggressiveness || d.aggressiveness);
+  return Math.max(8, base + bump);
+};
+
+// --- L0 signal scoring ---------------------------------------------------
+const _bp_client_ip = (req = {}, headers = {}) => {
+  const h = headers || {};
+  const xff = h['x-forwarded-for'] || h['X-Forwarded-For'] || req.remoteip || req.ip || '';
+  return String(xff).split(',')[0].trim();
+};
+const _bp_safe_signals = (s = {}) => {
+  const o = {};
+  for (const k of ['pointer_events', 'key_events', 'scroll_events', 'has_touch', 'pointer_moved', 'webgl', 'canvas', 'hardware_concurrency', 'languages', 'timezone', 'webdriver', 'headless', 'dwell_ms', 'user_agent', 'screen']) {
+    if (s[k] !== undefined) o[k] = typeof s[k] === 'string' ? String(s[k]).slice(0, 120) : s[k];
+  }
+  return o;
+};
+const _bp_score_signals = (signals = {}) => {
+  const s = signals || {};
+  let score = 0.5;
+  const reasons = [];
+  const inter = Number(s.pointer_events || 0) + Number(s.key_events || 0) + Number(s.scroll_events || 0);
+  if (inter >= 3) score += 0.25;
+  else if (inter === 0) { score -= 0.2; reasons.push('no_interaction'); }
+  if (s.has_touch === true || s.pointer_moved === true) score += 0.05;
+  if (s.webgl && s.canvas) score += 0.1;
+  else { score -= 0.1; reasons.push('no_env_hash'); }
+  if (s.hardware_concurrency && Number(s.hardware_concurrency) > 0) score += 0.03;
+  if (s.languages && String(s.languages).length) score += 0.03;
+  else reasons.push('no_lang');
+  if (s.timezone) score += 0.02;
+  if (s.webdriver === true) { score -= 0.5; reasons.push('webdriver'); }
+  if (s.headless === true) { score -= 0.4; reasons.push('headless'); }
+  const dwell = Number(s.dwell_ms || 0);
+  if (dwell >= 400) score += 0.05;
+  else if (dwell > 0 && dwell < 120) { score -= 0.1; reasons.push('instant_click'); }
+  score = Math.max(0, Math.min(1, score));
+  return { score, reasons };
+};
+
+// --- L1 image challenge (from-scratch synthetic SVG tiles) ----------------
+const _BP_SHAPES = ['circle', 'square', 'triangle', 'star', 'hexagon'];
+const _bp_color = () => _bp_pick(['#e11d48', '#2563eb', '#16a34a', '#eab308', '#7c3aed', '#ea580c', '#0891b2', '#db2777']);
+const _bp_shape_svg = (kind, color) => {
+  switch (kind) {
+    case 'circle': return `<circle cx="50" cy="50" r="30" fill="${color}"/>`;
+    case 'square': return `<rect x="22" y="22" width="56" height="56" rx="6" fill="${color}"/>`;
+    case 'triangle': return `<polygon points="50,18 82,80 18,80" fill="${color}"/>`;
+    case 'star': return `<polygon points="50,15 61,40 88,40 66,57 74,84 50,68 26,84 34,57 12,40 39,40" fill="${color}"/>`;
+    case 'hexagon': return `<polygon points="50,16 82,33 82,67 50,84 18,67 18,33" fill="${color}"/>`;
+    default: return '';
+  }
+};
+const _bp_tile = (kind) => {
+  const svg = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100"><rect width="100" height="100" fill="#f1f5f9"/>${_bp_shape_svg(kind, _bp_color())}</svg>`;
+  return 'data:image/svg+xml;base64,' + Buffer.from(svg).toString('base64');
+};
+const _image_issue = (site_key, d) => {
+  const grid = d.image_grid || 9;
+  const target = _bp_pick(_BP_SHAPES);
+  const others = _BP_SHAPES.filter((x) => x !== target);
+  const min_c = Math.max(1, d.image_correct_min || 2);
+  const max_c = Math.max(min_c, grid - 2);
+  const correct_count = min_c + Math.floor(Math.random() * (max_c - min_c + 1));
+  const order = [...Array(grid).keys()];
+  for (let i = order.length - 1; i > 0; i--) {
+    const j = Math.floor(Math.random() * (i + 1));
+    [order[i], order[j]] = [order[j], order[i]];
+  }
+  const correct = new Set(order.slice(0, correct_count));
+  const tiles = [];
+  const answer = [];
+  for (let i = 0; i < grid; i++) {
+    if (correct.has(i)) { tiles.push(_bp_tile(target)); answer.push(i); }
+    else tiles.push(_bp_tile(_bp_pick(others)));
+  }
+  answer.sort((a, b) => a - b);
+  return {
+    id: _bp_rand(9), kind: 'image', level: 1, site_key, ts: Date.now(), ttl: 120000,
+    grid, tiles, prompt: `Select every image that shows a ${target}`,
+    answer_hash: _bp_sha(answer.join(',')), pass_score: 0.85,
+  };
+};
+const _image_grade = (ch, answer) => {
+  const raw = Array.isArray(answer) ? answer : answer && Array.isArray(answer.selection) ? answer.selection : [];
+  const norm = [...new Set(raw.map(Number).filter((n) => Number.isInteger(n) && n >= 0 && n < ch.grid))].sort((a, b) => a - b).join(',');
+  return _bp_sha(norm) === ch.answer_hash;
+};
+
+// --- L2 AI check (score, then a one-shot AI challenge) --------------------
+const _bp_ip_reputation = async (ip) => {
+  const s = String(ip || '');
+  const is_private = /^(10\.|127\.|192\.168\.|172\.(1[6-9]|2\d|3[01])\.|::1|fc|fd)/.test(s);
+  return { ip: s, private: is_private };
+};
+const _RiskSchema = z.object({ score: z.number(), verdict: z.enum(['human', 'bot', 'borderline']), reason: z.string() });
+const _risk_score = async (profile, signals, ip) => {
+  try {
+    const rep = await _bp_ip_reputation(ip);
+    const prompt = `You are a bot-detection risk scorer for a website captcha. Given browser signals and IP reputation, decide if the visitor is a human, a bot, or borderline. score is a 0..1 human-likelihood.\nSIGNALS: ${JSON.stringify(_bp_safe_signals(signals))}\nIP_REPUTATION: ${JSON.stringify(rep)}`;
+    const r = await submit_chat_gpt_prompt({ uid: profile.owner_uid, model: _conf.default_ai_model, prompt, response_format: _RiskSchema, metadata: { func: 'bot_risk', profile_id: profile._id } });
+    if (r.code === 5 && r.data) {
+      const o = JSON.parse(r.data);
+      return { score: Number(o.score) || 0, verdict: o.verdict || 'borderline', reason: o.reason || '' };
+    }
+  } catch (e) {}
+  return { score: 0.5, verdict: 'borderline', reason: 'scorer_unavailable' };
+};
+const _bp_norm_answer = (s) => String(s || '').toLowerCase().trim().replace(/[^a-z0-9]+/g, ' ').trim();
+const _DynSchema = z.object({ question: z.string(), answer: z.string() });
+const _dynamic_issue = async (site_key, owner_uid) => {
+  try {
+    const prompt = 'Generate ONE short human-verification question that is easy for a person and hard for a naive bot script. Prefer a simple common-sense or arithmetic-in-words question with a single short unambiguous answer. Return the question and the exact expected answer (a single lowercase word or number, no punctuation).';
+    const r = await submit_chat_gpt_prompt({ uid: owner_uid || 'bot_protection', model: _conf.default_ai_model, prompt, response_format: _DynSchema, metadata: { func: 'bot_dyn' } });
+    if (r.code === 5 && r.data) {
+      const o = JSON.parse(r.data);
+      if (o.question && o.answer) {
+        return { id: _bp_rand(9), kind: 'ai', level: 2, site_key, ts: Date.now(), ttl: 180000, prompt: String(o.question).slice(0, 300), answer_hash: _bp_sha(_bp_norm_answer(o.answer)), pass_score: 0.9 };
+      }
+    }
+  } catch (e) {}
+  return null;
+};
+const _dynamic_grade = async (ch, answer) => {
+  const a = typeof answer === 'string' ? answer : (answer && (answer.text || answer.answer)) || '';
+  return _bp_sha(_bp_norm_answer(a)) === ch.answer_hash;
+};
+
+// --- Escalation orchestrator ---------------------------------------------
+const _bp_challenges = new Map(); // challenge_id -> { kind, level, site_key, ts, ttl, answer_hash, ... }
+const _bp_escalate = async (profile, site_key, ip, signals, level, esc, d) => {
+  if (level <= 1 && esc.l1_enabled !== false) {
+    const ch = _image_issue(site_key, d);
+    _bp_challenges.set(ch.id, ch);
+    _bp_bump_stat(profile._id, 'challenged');
+    return { code: 1, data: { status: 'challenge', level: 1, challenge: { id: ch.id, type: 'image', prompt: ch.prompt, tiles: ch.tiles, grid: ch.grid } } };
+  }
+  if (level <= 2 && esc.l2_enabled !== false) {
+    const verdict = await _risk_score(profile, signals, ip);
+    if (verdict.verdict === 'human' && verdict.score >= (d.l2_score_low || 0.7)) {
+      _bp_bump_stat(profile._id, 'passed');
+      return { code: 1, data: { status: 'pass', level: 2, response_token: mint_response_token(site_key, 2, verdict.score, esc.response_token_ttl_ms || d.response_token_ttl_ms) } };
+    }
+    if (verdict.verdict === 'bot') {
+      _bp_bump_stat(profile._id, 'blocked');
+      return { code: 1, data: { status: 'fail', level: 2, reason: 'ai_bot' } };
+    }
+    const ch = await _dynamic_issue(site_key, profile.owner_uid);
+    if (ch) {
+      _bp_challenges.set(ch.id, ch);
+      _bp_bump_stat(profile._id, 'challenged');
+      return { code: 1, data: { status: 'challenge', level: 2, challenge: { id: ch.id, type: 'ai', prompt: ch.prompt } } };
+    }
+    _bp_bump_stat(profile._id, 'blocked');
+    return { code: 1, data: { status: 'fail', level: 2, reason: 'ai_uncertain' } };
+  }
+  _bp_bump_stat(profile._id, 'blocked');
+  return { code: 1, data: { status: 'fail', level, reason: 'exhausted' } };
+};
+
+// --- Bootstrap (broker-only; called by the router iframe + interstitial) --
+export const get_captcha_bootstrap = async function (req) {
+  try {
+    const site_key = req.site_key;
+    const ip = _bp_client_ip(req, req.headers);
+    if (!site_key) return { code: -404, data: 'no_site_key' };
+    const profile = await _bp_resolve_by_site_key(site_key);
+    if (!profile || profile.enabled !== true) return { code: -404, data: 'not_enabled' };
+    const d = _bp_defaults();
+    const esc = profile.escalation || _bp_default_escalation();
+    const session_token = mint_clearance_token('session', `${site_key}|${ip}`, esc.session_token_ttl_ms || d.session_token_ttl_ms);
+    _bp_bump_stat(profile._id, 'served');
+    return {
+      code: 1,
+      data: {
+        site_key,
+        session_token,
+        pow: pow_make(session_token, _bp_pow_difficulty(profile)),
+        min_age_ms: d.min_age_ms,
+        config: {
+          brand: profile.brand || 'Xuda',
+          theme: req.theme || profile.theme || 'auto',
+          l1_enabled: esc.l1_enabled !== false,
+          l2_enabled: esc.l2_enabled !== false,
+        },
+      },
+    };
+  } catch (err) {
+    return { code: -404, data: err.message || String(err) };
+  }
+};
+
+// --- Public: the escalation driver ---------------------------------------
+export const captcha_verify = async function (req, job_id, headers) {
+  try {
+    const { site_key, session_token, signals = {}, pow_nonce, challenge_id, answer } = req;
+    const ip = _bp_client_ip(req, headers);
+    if (!site_key || !session_token) return { code: 1, data: { status: 'fail', reason: 'bad_request' } };
+    const profile = await _bp_resolve_by_site_key(site_key);
+    if (!profile || profile.enabled !== true) return { code: 1, data: { status: 'fail', reason: 'not_enabled' } };
+    const d = _bp_defaults();
+    const esc = profile.escalation || _bp_default_escalation();
+
+    if (!_bp_allow('ip', `${site_key}|${ip}`, 60, 60000) || !_bp_allow('key', site_key, 600, 60000)) {
+      return { code: 1, data: { status: 'fail', reason: 'rate_limited' } };
+    }
+    const st = verify_clearance_token('session', `${site_key}|${ip}`, session_token);
+    if (!st.ok) return { code: 1, data: { status: 'fail', reason: `session_${st.reason}` } };
+
+    // Answering an issued image (L1) or AI (L2) challenge.
+    if (challenge_id) {
+      const ch = _bp_challenges.get(challenge_id);
+      if (!ch || ch.site_key !== site_key || Date.now() - ch.ts > (ch.ttl || 120000)) {
+        if (ch) _bp_challenges.delete(challenge_id);
+        return { code: 1, data: { status: 'fail', reason: 'challenge_expired' } };
+      }
+      let ok = false;
+      if (ch.kind === 'image') ok = _image_grade(ch, answer);
+      else if (ch.kind === 'ai') ok = await _dynamic_grade(ch, answer);
+      _bp_challenges.delete(challenge_id);
+      if (ok) {
+        _bp_bump_stat(profile._id, 'passed');
+        return { code: 1, data: { status: 'pass', level: ch.level, response_token: mint_response_token(site_key, ch.level, ch.pass_score || 0.9, esc.response_token_ttl_ms || d.response_token_ttl_ms) } };
+      }
+      return await _bp_escalate(profile, site_key, ip, signals, ch.level + 1, esc, d);
+    }
+
+    // Level 0: honeypot + min-age + proof of work + passive signals.
+    if (signals && typeof signals.honeypot === 'string' && signals.honeypot.trim() !== '') {
+      return { code: 1, data: { status: 'fail', reason: 'ok' } };
+    }
+    if (!pow_check(session_token, _bp_pow_difficulty(profile), pow_nonce)) {
+      return { code: 1, data: { status: 'fail', reason: 'pow' } };
+    }
+    const min_age_ok = Date.now() - st.ts >= (d.min_age_ms || 800);
+    const { score, reasons } = _bp_score_signals(signals);
+    const aggr = _bp_aggr(esc.aggressiveness || d.aggressiveness);
+    if (reasons.includes('webdriver') && aggr >= 2) return { code: 1, data: { status: 'fail', reason: 'automation' } };
+    const pass_threshold = 0.6 + aggr * 0.1;
+    if (min_age_ok && score >= pass_threshold) {
+      _bp_bump_stat(profile._id, 'passed');
+      return { code: 1, data: { status: 'pass', level: 0, response_token: mint_response_token(site_key, 0, score, esc.response_token_ttl_ms || d.response_token_ttl_ms) } };
+    }
+    return await _bp_escalate(profile, site_key, ip, signals, 1, esc, d);
+  } catch (err) {
+    return { code: 1, data: { status: 'fail', reason: 'error' } };
+  }
+};
+
+// --- Public: server-to-server verification (reCAPTCHA / Turnstile shaped) --
+export const captcha_siteverify = async function (req) {
+  try {
+    const { secret, response } = req;
+    if (!secret || !response) return { code: 1, data: { success: false, 'error-codes': ['missing-input'] } };
+    const profile = await _bp_resolve_by_secret(secret);
+    if (!profile) return { code: 1, data: { success: false, 'error-codes': ['invalid-input-secret'] } };
+    const v = verify_response_token(profile.site_key, response);
+    if (!v.ok) return { code: 1, data: { success: false, 'error-codes': [v.reason === 'replayed' ? 'timeout-or-duplicate' : 'invalid-input-response'] } };
+    return { code: 1, data: { success: true, score: v.score, level_reached: v.level, hostname: profile.target?.label || '', challenge_ts: Date.now(), 'error-codes': [] } };
+  } catch (err) {
+    return { code: 1, data: { success: false, 'error-codes': ['internal-error'] } };
+  }
+};
+
+// --- Entitlement (member-first; the Stripe attach lands in stripe_module) --
+// Entitlement gate. Standard service is FREE for paid members; non-members pay
+// $1/mo. Custom rules are a $5/mo add-on for EVERYONE (members included). Both
+// tiers share the consolidated-subscription category 'bot_protection' (one line
+// item, price-swapped between $1 and $5, exactly like ai_workspace tiers), so a
+// custom subscriber is never double-billed the standard price. On first use we
+// attach/swap the item via stripe_module; it returns -402 gracefully until the
+// live Stripe prices replace the config placeholders, so nothing hard-fails.
+const _bp_ensure_entitled = async (uid, tier) => {
+  try {
+    const r = await db_module.get_couch_doc('xuda_accounts', uid, true);
+    const acct = r && r.code > 0 && r.data ? r.data : {};
+    const is_member = !!(acct.membership_plan && acct.membership_plan !== 'free');
+    const has_item = !!acct?.stripe_subscription_items?.bot_protection;
+    if (tier !== 'custom') {
+      if (is_member) return { ok: true, member: true };
+      if (has_item) return { ok: true };
+    }
+    // Not entitled yet: attach the add-on (or swap the existing item to the
+    // custom price) on the account's consolidated subscription.
+    const plan_id = tier === 'custom' ? 'bot_protection_custom' : 'bot_protection';
+    let attach = null;
+    try { attach = await stripe_ms.add_subscription_item({ uid, plan_id }); } catch (e) {}
+    if (attach && attach.code === 1) return { ok: true };
+    return { ok: false, tier, price: tier === 'custom' ? 5 : 1, reason: attach && attach.data };
+  } catch (e) {
+    return { ok: false, tier, price: tier === 'custom' ? 5 : 1 };
+  }
+};
+
+// --- Config sanitizers ----------------------------------------------------
+const _bp_sanitize_escalation = (e) => {
+  const out = {};
+  if (['low', 'medium', 'high'].includes(e.aggressiveness)) out.aggressiveness = e.aggressiveness;
+  if (Number.isFinite(Number(e.pow_difficulty))) out.pow_difficulty = Math.max(8, Math.min(24, Math.round(Number(e.pow_difficulty))));
+  if (Number.isFinite(Number(e.clearance_ttl_ms))) out.clearance_ttl_ms = Math.max(60000, Math.min(86400000, Math.round(Number(e.clearance_ttl_ms))));
+  if (typeof e.l1_enabled === 'boolean') out.l1_enabled = e.l1_enabled;
+  if (typeof e.l2_enabled === 'boolean') out.l2_enabled = e.l2_enabled;
+  return out;
+};
+const _bp_str_arr = (v, max = 200) => (Array.isArray(v) ? v.filter((x) => typeof x === 'string').map((x) => x.slice(0, 80)).slice(0, max) : []);
+export const bp_sanitize_rules = function (rules = {}) {
+  const r = rules || {};
+  const out = {};
+  if (r.geo && typeof r.geo === 'object') {
+    out.geo = {
+      mode: ['off', 'challenge', 'block', 'allow'].includes(r.geo.mode) ? r.geo.mode : 'off',
+      countries: _bp_str_arr(r.geo.countries),
+      regions: _bp_str_arr(r.geo.regions),
+    };
+  }
+  const win = (o) => (o && typeof o === 'object' && ['off', 'challenge'].includes(o.mode) ? { mode: o.mode, list: (Array.isArray(o.list) ? o.list.map(Number).filter((n) => Number.isInteger(n)) : []) } : undefined);
+  if (win(r.hours)) out.hours = win(r.hours);
+  if (win(r.days)) out.days = win(r.days);
+  if (Array.isArray(r.paths)) out.paths = r.paths.filter((p) => p && typeof p.pattern === 'string').map((p) => ({ pattern: p.pattern.slice(0, 200), action: ['challenge', 'block', 'allow'].includes(p.action) ? p.action : 'challenge' })).slice(0, 100);
+  if (r.rate && typeof r.rate === 'object') out.rate = { window_s: Math.max(1, Math.min(3600, Number(r.rate.window_s) || 60)), max: Math.max(1, Math.min(100000, Number(r.rate.max) || 120)), action: ['challenge', 'block'].includes(r.rate.action) ? r.rate.action : 'challenge' };
+  if (r.reputation && typeof r.reputation === 'object') out.reputation = { allow_verified_search_bots: r.reputation.allow_verified_search_bots !== false, challenge_bad_asn: r.reputation.challenge_bad_asn === true };
+  out.allow_list = _bp_str_arr(r.allow_list);
+  out.block_list = _bp_str_arr(r.block_list);
+  if (typeof r.require_referer === 'boolean') out.require_referer = r.require_referer;
+  if (Array.isArray(r.fingerprint_rules)) out.fingerprint_rules = r.fingerprint_rules.filter((f) => f && typeof f.match === 'string').map((f) => ({ match: f.match.slice(0, 40), action: ['challenge', 'block'].includes(f.action) ? f.action : 'challenge' })).slice(0, 20);
+  if (['low', 'medium', 'high'].includes(r.aggressiveness)) out.aggressiveness = r.aggressiveness;
+  if (Number.isFinite(Number(r.clearance_ttl_ms))) out.clearance_ttl_ms = Math.max(60000, Math.min(86400000, Math.round(Number(r.clearance_ttl_ms))));
+  return out;
+};
+
+// --- Owner settings (profile setup Bot Protection tab) -------------------
+const _build_captcha_snippet = (site_key, config = {}) => {
+  const origin = embed_origin();
+  const theme = config.theme && /^[a-z]+$/.test(config.theme) ? ` data-theme="${config.theme}"` : '';
+  return `<script src="${origin}/dist/runtime/js/captcha-loader.js" async data-sitekey="${site_key}"${theme}></script>`;
+};
+const _build_captcha_container = (site_key) => `<div class="xuda-captcha" data-sitekey="${site_key}"></div>`;
+
+export const get_bot_protection_settings = async function (req) {
+  try {
+    const { uid, profile_id } = req;
+    const info = await get_active_account_profile_info(uid, profile_id);
+    if (info.uid !== uid) return { code: -403, data: 'not_profile_owner' };
+    const bp_id = _bp_profile_id(uid, info.account_profile_id);
+    const doc = await _bp_load(bp_id);
+    const site_key = doc?.site_key || '';
+    const esc = doc?.escalation || _bp_default_escalation();
+    return {
+      code: 1,
+      data: {
+        enabled: doc?.enabled === true,
+        plan_tier: doc?.plan_tier || 'standard',
+        site_key,
+        secret_key: doc?.secret_key || '',
+        escalation: {
+          aggressiveness: esc.aggressiveness,
+          pow_difficulty: esc.pow_difficulty,
+          clearance_ttl_ms: esc.clearance_ttl_ms,
+          l1_enabled: esc.l1_enabled !== false,
+          l2_enabled: esc.l2_enabled !== false,
+        },
+        custom_rules: doc?.custom_rules || {},
+        require_on_contact_form: doc?.require_on_contact_form === true,
+        widget_profile_id: `${uid}.${info.account_profile_id}`,
+        iframe_url: site_key ? `${embed_origin()}/captcha/${site_key}` : '',
+        snippet: site_key ? _build_captcha_snippet(site_key, { theme: doc?.theme }) : '',
+        container_snippet: site_key ? _build_captcha_container(site_key) : '',
+      },
+    };
+  } catch (err) {
+    return { code: -1, data: err.message || String(err) };
+  }
+};
+
+export const update_bot_protection_settings = async function (req) {
+  try {
+    const { uid, profile_id, enabled, escalation, custom_rules, require_on_contact_form, rotate_secret } = req;
+    const info = await get_active_account_profile_info(uid, profile_id);
+    if (info.uid !== uid) return { code: -403, data: 'not_profile_owner' };
+    const doc = await _bp_ensure_profile(uid, info.account_profile_id, { surface: 'widget' });
+
+    if (enabled === true && doc.enabled !== true) {
+      const ent = await _bp_ensure_entitled(uid, doc.plan_tier || 'standard');
+      if (!ent.ok) return { code: -402, data: { error: 'billing_required', tier: ent.tier, price: ent.price } };
+    }
+    if (typeof enabled === 'boolean') doc.enabled = enabled;
+    if (doc.enabled && !doc.site_key) {
+      const k = _bp_new_keys();
+      doc.site_key = k.site_key;
+      doc.secret_key = k.secret_key;
+    }
+    if (rotate_secret === true && doc.site_key) {
+      if (doc.secret_key) await _bp_delete_index(_bp_index_id.secret(doc.secret_key));
+      doc.secret_key = _bp_new_keys().secret_key;
+    }
+    if (escalation && typeof escalation === 'object') {
+      doc.escalation = { ...(doc.escalation || _bp_default_escalation()), ..._bp_sanitize_escalation(escalation) };
+    }
+    if (custom_rules && typeof custom_rules === 'object') doc.custom_rules = bp_sanitize_rules(custom_rules);
+    if (typeof require_on_contact_form === 'boolean') doc.require_on_contact_form = require_on_contact_form;
+    _bp_flush_stats(doc);
+    await _bp_save(doc);
+    return await get_bot_protection_settings({ uid, profile_id });
+  } catch (err) {
+    return { code: -1, data: err.message || String(err) };
+  }
+};
+
+///////////////////////////////////////////////////////////////////////////////
+// BOT PROTECTION - Surface 2 lifecycle (origin protection of a target).
+// These are called by app_module's thin cpi handlers over the broker (uid is
+// passed explicitly, already authenticated at the http layer), plus two
+// broker-only helpers the router uses at the edge. See docs/handoff_bot_protection_ishai.md.
+///////////////////////////////////////////////////////////////////////////////
+
+// Stable per-target slug so re-attaching the same target maps to one profile.
+const _bp_slug_for_target = (target) => 't_' + _bp_sha(String((target && target.id) || '')).slice(0, 16);
+const _bp_summary = (doc) => ({
+  profile_id: doc._id,
+  target: doc.target || null,
+  enabled: doc.enabled === true,
+  armed: doc.armed === true,
+  plan_tier: doc.plan_tier || 'standard',
+  surface: doc.surface || 'origin',
+  site_key: doc.site_key || '',
+  stats: _bp_merged_stats(doc),
+});
+
+// IPv4 CIDR membership test (dependency-free) for allow/block-list rules.
+const _cidr_match = (cidr, ip) => {
+  try {
+    if (typeof cidr !== 'string' || cidr.indexOf('/') < 0) return false;
+    const [range, bitsStr] = cidr.split('/');
+    const bits = parseInt(bitsStr, 10);
+    if (!/^\d+\.\d+\.\d+\.\d+$/.test(range) || !/^\d+\.\d+\.\d+\.\d+$/.test(ip) || !(bits >= 0 && bits <= 32)) return false;
+    const toInt = (a) => a.split('.').reduce((s, o) => ((s << 8) + (parseInt(o, 10) & 255)) >>> 0, 0) >>> 0;
+    const mask = bits === 0 ? 0 : (~0 << (32 - bits)) >>> 0;
+    return (toInt(range) & mask) === (toInt(ip) & mask);
+  } catch (e) {
+    return false;
+  }
+};
+
+export const bp_attach = async function (req) {
+  try {
+    const { uid, target, plan_tier, escalation } = req;
+    if (!uid || !target || !target.id) return { code: -1, data: 'bad_request' };
+    const tier = plan_tier === 'custom' ? 'custom' : 'standard';
+    const ent = await _bp_ensure_entitled(uid, tier);
+    if (!ent.ok) return { code: -402, data: { error: 'billing_required', tier: ent.tier, price: ent.price } };
+    const slug = _bp_slug_for_target(target);
+    const doc = await _bp_ensure_profile(uid, slug, { surface: 'origin', plan_tier: tier, target });
+    doc.target = target;
+    doc.plan_tier = tier;
+    doc.surface = doc.surface === 'widget' ? 'both' : 'origin';
+    doc.enabled = true;
+    if (!doc.site_key) { const k = _bp_new_keys(); doc.site_key = k.site_key; doc.secret_key = k.secret_key; }
+    if (escalation && typeof escalation === 'object') doc.escalation = { ...(doc.escalation || _bp_default_escalation()), ..._bp_sanitize_escalation(escalation) };
+    _bp_flush_stats(doc);
+    await _bp_save(doc);
+    return { code: 1, data: _bp_summary(doc) };
+  } catch (err) {
+    return { code: -1, data: err.message || String(err) };
+  }
+};
+
+export const bp_get_profiles = async function (req) {
+  try {
+    const { uid } = req;
+    if (!uid) return { code: -1, data: 'no uid' };
+    const q = await db_module.find_couch_query(BP_DB, { selector: { docType: 'bot_protection_profile', owner_uid: uid }, limit: 500 }, true, true);
+    const docs = q?.docs || [];
+    return { code: 1, data: { profiles: docs.map(_bp_summary) } };
+  } catch (err) {
+    return { code: -1, data: err.message || String(err) };
+  }
+};
+
+export const bp_arm = async function (req) {
+  try {
+    const { uid, profile_id, app_id, armed, target } = req;
+    if (!uid) return { code: -1, data: 'no uid' };
+    let doc = null;
+    if (profile_id) {
+      doc = await _bp_load(profile_id);
+    } else if (target && target.id) {
+      doc = await _bp_ensure_profile(uid, _bp_slug_for_target(target), { surface: 'origin', target });
+      if (!doc.target) doc.target = target;
+    } else if (app_id) {
+      const slug = _bp_slug_for_target({ id: app_id });
+      doc = await _bp_load(_bp_profile_id(uid, slug));
+      if (!doc) doc = await _bp_ensure_profile(uid, slug, { surface: 'origin', target: { type: 'internal', kind: 'app', id: app_id, label: app_id, region: null } });
+    }
+    if (!doc) return { code: -404, data: 'profile_not_found' };
+    if (doc.owner_uid !== uid) return { code: -403, data: 'not_owner' };
+    const want = armed === true;
+    if (want) {
+      const ent = await _bp_ensure_entitled(uid, doc.plan_tier || 'standard');
+      if (!ent.ok) return { code: -402, data: { error: 'billing_required', tier: ent.tier, price: ent.price } };
+      if (!doc.site_key) { const k = _bp_new_keys(); doc.site_key = k.site_key; doc.secret_key = k.secret_key; }
+      doc.enabled = true;
+    }
+    doc.armed = want;
+    _bp_flush_stats(doc);
+    await _bp_save(doc);
+    return { code: 1, data: _bp_summary(doc) };
+  } catch (err) {
+    return { code: -1, data: err.message || String(err) };
+  }
+};
+
+export const bp_detach = async function (req) {
+  try {
+    const { uid, profile_id } = req;
+    const doc = await _bp_load(profile_id);
+    if (!doc) return { code: 1, data: { ok: true } };
+    if (doc.owner_uid !== uid) return { code: -403, data: 'not_owner' };
+    if (doc.site_key) await _bp_delete_index(_bp_index_id.key(doc.site_key));
+    if (doc.secret_key) await _bp_delete_index(_bp_index_id.secret(doc.secret_key));
+    const tkey = _bp_target_key(doc);
+    if (tkey) await _bp_delete_index(_bp_index_id.target(tkey));
+    try {
+      const r = await db_module.get_couch_doc(BP_DB, doc._id, true);
+      if (r?.data?._rev) await db_module.delete_couch_doc(BP_DB, doc._id, r.data._rev);
+    } catch (e) {}
+    _bp_stat_buf.delete(doc._id);
+    return { code: 1, data: { ok: true } };
+  } catch (err) {
+    return { code: -1, data: err.message || String(err) };
+  }
+};
+
+export const bp_set_custom_rules = async function (req) {
+  try {
+    const { uid, profile_id, rules } = req;
+    const doc = await _bp_load(profile_id);
+    if (!doc) return { code: -404, data: 'profile_not_found' };
+    if (doc.owner_uid !== uid) return { code: -403, data: 'not_owner' };
+    const ent = await _bp_ensure_entitled(uid, 'custom');
+    if (!ent.ok) return { code: -402, data: { error: 'billing_required', tier: 'custom', price: 5 } };
+    doc.plan_tier = 'custom';
+    doc.custom_rules = bp_sanitize_rules(rules || {});
+    _bp_flush_stats(doc);
+    await _bp_save(doc);
+    return { code: 1, data: _bp_summary(doc) };
+  } catch (err) {
+    return { code: -1, data: err.message || String(err) };
+  }
+};
+
+// Broker-only: the router resolves the guarding profile for a target at the edge.
+export const bp_resolve_target = async function (req) {
+  try {
+    const { target_key } = req;
+    if (!target_key) return { code: -404, data: 'no_target' };
+    const idx = await _bp_load_index(_bp_index_id.target(target_key));
+    if (!idx) return { code: -404, data: 'not_found' };
+    const doc = await _bp_load(idx.profile_id);
+    if (!doc) return { code: -404, data: 'not_found' };
+    return {
+      code: 1,
+      data: {
+        profile_id: doc._id,
+        armed: doc.armed === true,
+        enabled: doc.enabled === true,
+        plan_tier: doc.plan_tier || 'standard',
+        site_key: doc.site_key || '',
+        custom_rules: doc.custom_rules || {},
+        escalation: doc.escalation || _bp_default_escalation(),
+        target: doc.target || null,
+      },
+    };
+  } catch (err) {
+    return { code: -404, data: err.message || String(err) };
+  }
+};
+
+// Broker-only: evaluate the custom rules for an inbound request context and
+// return the enforcement action. Standard tier ignores custom_rules (challenge
+// when armed); custom tier honors the full rule set.
+export const evaluate_custom_rules = async function (req) {
+  try {
+    const { profile, ctx } = req;
+    const d = _bp_defaults();
+    const esc = (profile && profile.escalation) || _bp_default_escalation();
+    const out = { action: 'challenge', start_level: 0, aggressiveness: esc.aggressiveness || d.aggressiveness, clearance_ttl_ms: esc.clearance_ttl_ms || d.clearance_ttl_ms };
+    const c = ctx || {};
+    const rules = profile && profile.plan_tier === 'custom' && profile.custom_rules ? profile.custom_rules : null;
+    const inList = (list, ip, country) => (list || []).some((e) => e === ip || e === country || _cidr_match(e, ip));
+    if (rules) {
+      if (inList(rules.block_list, c.ip, c.country)) return { code: 1, data: { ...out, action: 'block' } };
+      if (inList(rules.allow_list, c.ip, c.country)) return { code: 1, data: { ...out, action: 'allow' } };
+      if (rules.reputation && rules.reputation.allow_verified_search_bots && c.verified_bot) return { code: 1, data: { ...out, action: 'allow' } };
+      if (rules.geo && rules.geo.mode && rules.geo.mode !== 'off' && c.country && (rules.geo.countries || []).includes(c.country)) {
+        if (rules.geo.mode === 'block') return { code: 1, data: { ...out, action: 'block' } };
+        if (rules.geo.mode === 'allow') return { code: 1, data: { ...out, action: 'allow' } };
+        out.action = 'challenge';
+      }
+      if (Array.isArray(rules.paths) && c.path) {
+        for (const p of rules.paths) {
+          if (p && p.pattern && c.path.indexOf(p.pattern) === 0) {
+            if (p.action === 'block') return { code: 1, data: { ...out, action: 'block' } };
+            if (p.action === 'allow') return { code: 1, data: { ...out, action: 'allow' } };
+            out.action = 'challenge';
+            break;
+          }
+        }
+      }
+      if (rules.hours && rules.hours.mode === 'challenge' && Array.isArray(rules.hours.list) && typeof c.hour === 'number' && rules.hours.list.includes(c.hour)) out.action = 'challenge';
+      if (rules.days && rules.days.mode === 'challenge' && Array.isArray(rules.days.list) && typeof c.day === 'number' && rules.days.list.includes(c.day)) out.action = 'challenge';
+      if (rules.require_referer && !c.has_referer) out.action = 'challenge';
+      if (['low', 'medium', 'high'].includes(rules.aggressiveness)) out.aggressiveness = rules.aggressiveness;
+      if (Number.isFinite(Number(rules.clearance_ttl_ms))) out.clearance_ttl_ms = Number(rules.clearance_ttl_ms);
+    }
+    return { code: 1, data: out };
+  } catch (err) {
+    return { code: 1, data: { action: 'challenge', start_level: 0 } };
+  }
+};
+
+// Broker-only: the origin interstitial passes a captcha response token (from the
+// embedded widget) here. Resolves the profile by site_key, verifies and burns the
+// token, and returns the guarded target so the router can mint a clearance cookie.
+export const bp_consume_response = async function (req) {
+  try {
+    const { site_key, response } = req;
+    const profile = await _bp_resolve_by_site_key(site_key);
+    if (!profile || profile.enabled !== true) return { code: 1, data: { ok: false, reason: 'unknown_site' } };
+    const v = verify_response_token(profile.site_key, response);
+    if (!v.ok) return { code: 1, data: { ok: false, reason: v.reason } };
+    const esc = profile.escalation || _bp_default_escalation();
+    const d = _bp_defaults();
+    return { code: 1, data: { ok: true, level: v.level, target: _bp_target_key(profile), clearance_ttl_ms: esc.clearance_ttl_ms || d.clearance_ttl_ms } };
+  } catch (err) {
+    return { code: 1, data: { ok: false, reason: 'error' } };
+  }
+};
+
+// Broker-only: the router caches the set of armed targets (refreshed periodically)
+// so the enforcement hot path is a local lookup and unguarded traffic never hits
+// the broker.
+export const bp_armed_targets = async function () {
+  try {
+    const q = await db_module.find_couch_query(BP_DB, { selector: { docType: 'bot_protection_profile', armed: true }, fields: ['_id', 'target', 'site_key'], limit: 2000 }, true, true);
+    const rows = (q?.docs || []).map((doc) => ({ target_key: _bp_target_key(doc), site_key: doc.site_key })).filter((x) => x.target_key && x.site_key);
+    return { code: 1, data: rows };
+  } catch (err) {
+    return { code: -1, data: err.message || String(err) };
+  }
+};