zevairouter 1.0.35 → 1.0.36

package/src/lib/oauth/services/codebuddyCnPhoneAutomation.js

@@ -0,0 +1,1029 @@
+/**
+ * Playwright automation for CodeBuddy CN (Tencent Cloud Code Assistant) phone-number
+ * registration at www.codebuddy.cn.
+ *
+ * VERIFIED DOM STRUCTURE (live probe 2026-07-09):
+ *   - Main page is a SPA that renders a "手机号" (phone) tab.
+ *   - Clicking the phone tab reveals <div class="login-phone-box"> containing
+ *     <iframe id="phone-iframe"> — a Keycloak login form.
+ *   - The iframe src is https://www.codebuddy.cn/auth/realms/copilot/protocol/openid-connect/auth?...
+ *   - Inside the iframe:
+ *       Phone input:    input#phoneNumber.kc-phone-number-input (placeholder "请输入你的手机号")
+ *       Country selector: .kc-country-selector (default +86 China)
+ *       Country options:  .kc-country-option (text "中国香港" = +852 Hong Kong)
+ *       Code input:     input#code.pf-c-form-control (placeholder "请输入验证码")
+ *       Send code btn:  input.btn-lg.code-btn (value "获取验证码")
+ *       Submit button:  input#kc-login[type=submit] (value "登录")
+ *       Form:           form#kc-form-login
+ *
+ * This function is PURE page-interaction — it does not call 5sim or OAuth. The manager
+ * owns those concerns and passes the SMS code via `pollSmsPromise`.
+ *
+ * Flow:
+ *   1. Navigate to www.codebuddy.cn/login
+ *   2. Switch to phone-number tab (手机号)
+ *   3. Wait for iframe #phone-iframe to load
+ *   4. Select country (Hong Kong +852 if phone starts with +852, else leave default)
+ *   5. Enter the phone number (local portion, without country code)
+ *   6. Click "获取验证码" (send SMS code)
+ *   7. Await the SMS code from pollSmsPromise
+ *   8. Enter the code into #code input
+ *   9. Click #kc-login (submit)
+ *  10. Probe for captcha → if found, return needs_manual
+ *  11. Confirm registration success (URL change / logged-in indicator)
+ *
+ * Returns: { status: "success" | "needs_manual" | "failed", error?, captcha? }
+ */
+
+// Trailing slash required — without it the CDN returns 301 and SPA may not boot
+const CODEBUDDY_CN_LOGIN_URL = "https://www.codebuddy.cn/login/";
+const CODEBUDDY_CN_LOGIN_URL_FALLBACKS = [
+  "https://www.codebuddy.cn/login/",
+  "https://www.codebuddy.cn/login",
+  "https://www.codebuddy.cn/register/",
+  "https://copilot.tencent.com/login/",
+];
+const NAV_MAX_ATTEMPTS = 5;
+const NAV_TIMEOUT_MS = 60_000;
+const SPA_TIMEOUT_MS = 60_000;
+
+// Main page selectors (outside iframe)
+const PHONE_TAB_SELECTORS = [
+  "text=手机号",
+  "div:has-text('手机号')",
+  "span:has-text('手机号')",
+  "[class*='phone']:has-text('手机号')",
+  "div.kc-phone-tab:has-text('手机号')",
+];
+// Any of these means the login SPA finished booting
+const SPA_READY_SELECTORS = [
+  "text=手机号",
+  "text=其他登录方式",
+  "text=微信",
+  "#phone-iframe",
+  ".login-phone-box",
+];
+
+// Iframe selector
+const PHONE_IFRAME_SELECTOR = "#phone-iframe";
+
+// ─── Iframe-internal selectors (Keycloak form) ──────────────────────────────
+const IFRAME_PHONE_INPUT = "#phoneNumber";
+const IFRAME_COUNTRY_SELECTOR = ".kc-country-selector";
+const IFRAME_COUNTRY_OPTIONS = ".kc-country-option";
+const IFRAME_COUNTRY_CODE_TEXT = ".kc-country-code-text";
+const IFRAME_CODE_INPUT = "#code";
+const IFRAME_SEND_CODE_BTN = "input.btn-lg.code-btn";
+const IFRAME_SEND_CODE_BTN_ALT = ".code-btn";
+const IFRAME_SUBMIT_BTN = "#kc-login";
+const IFRAME_FORM = "#kc-form-login";
+
+// Captcha detection indicators (Tencent TCaptcha + common widgets)
+const CAPTCHA_SELECTORS = [
+  'iframe[src*="captcha"]',
+  'iframe[src*="tcaptcha"]',
+  "#tcaptcha",
+  "#tcaptcha_transform",
+  ".nc_iconfont",
+  ".nc_wrapper",
+  '[class*="captcha"]',
+  '[id*="captcha"]',
+  'text=滑块',
+  'text=拖动',
+];
+
+// Logged-in success indicators (post-registration, check both main page and iframe)
+const LOGGED_IN_SELECTORS = [
+  '[class*="avatar"]',
+  '[class*="user-info"]',
+  '[class*="logout"]',
+  'text=退出登录',
+  'text=Logout',
+  'text=Sign out',
+];
+
+// Error message selectors inside the iframe
+const IFRAME_ERROR_SELECTORS = [
+  "#input-error",
+  ".pf-c-form__helper-text.pf-m-error",
+  ".kc-feedback-text",
+];
+
+/**
+ * Run the phone-number registration automation.
+ *
+ * @param {object} opts
+ * @param {import('playwright').Page} opts.page             Playwright page (from createFreshContext)
+ * @param {string} [opts.phone]                             Pre-ordered phone (legacy). Prefer resolvePhone.
+ * @param {function} [opts.resolvePhone]                    async () => phone — called ONLY after login form
+ *   is ready so 5sim is not billed if proxy/nav fails.
+ * @param {Promise<string>} [opts.pollSmsPromise]           Legacy: pre-started SMS poll (discouraged —
+ *   timer races navigation). Prefer waitForSms.
+ * @param {function} [opts.waitForSms]                      async () => code — called ONLY after "send
+ *   code" click so the 90s window is full for OTP delivery.
+ * @param {function} [opts.onStep]                          (step, message) => void — progress reporting
+ * @param {function} [opts.phoneFormatter]                  (phone) => formattedPhone — adapt format for the form
+ * @param {object} [opts.timeouts]
+ * @param {number} [opts.timeouts.nav=45000]                Navigation timeout
+ * @param {number} [opts.timeouts.action=15000]             Per-action (locator/click/fill) timeout
+ * @param {number} [opts.timeouts.codeWait=900000]          Max wait for SMS code (overridden by 5sim 60s timeout)
+ * @param {number} [opts.timeouts.postSubmit=10000]         Wait after submit before captcha/success probe
+ * @returns {Promise<{status:string, error?:string, captcha?:boolean}>}
+ */
+export async function runCodeBuddyCnPhoneRegistration({
+  page,
+  phone: phoneOpt,
+  resolvePhone,
+  pollSmsPromise,
+  waitForSms,
+  onStep,
+  phoneFormatter = (p) => p,
+  timeouts = {},
+}) {
+  const nav = timeouts.nav ?? 90_000;
+  const action = timeouts.action ?? 15_000;
+  const codeWait = timeouts.codeWait ?? 900_000;
+  const postSubmit = timeouts.postSubmit ?? 10_000;
+
+  const reportStep = (step, message) => onStep?.(step, message);
+
+  try {
+    // Step 1: Navigate — rotating proxy often fails first try; retry until SPA boots
+    reportStep("cn_opening_login_page", "Opening CodeBuddy CN login page");
+
+    // ponytail: China residential proxies hang on Google tracker CONNECT; abort them so SPA can boot
+    try {
+      await page.context().route("**/*", (route) => {
+        const u = route.request().url();
+        if (/googletagmanager|googleadservices|google-analytics|doubleclick|facebook|hotjar|clarity\.ms|hm\.baidu|google\.com\/rmkt/i.test(u)) {
+          return route.abort();
+        }
+        return route.continue();
+      });
+    } catch {
+      // route may already be set on retries
+    }
+
+    let phoneFrame = null;
+    for (let navAttempt = 1; navAttempt <= NAV_MAX_ATTEMPTS; navAttempt++) {
+      try {
+        const targetUrl = CODEBUDDY_CN_LOGIN_URL_FALLBACKS[(navAttempt - 1) % CODEBUDDY_CN_LOGIN_URL_FALLBACKS.length];
+        reportStep("cn_nav_attempt", `Navigation attempt ${navAttempt}/${NAV_MAX_ATTEMPTS} → ${targetUrl}`);
+
+        // Between retries, hard-reload by clearing cookies for codebuddy so CDN/session glitches reset
+        if (navAttempt > 1) {
+          await page.context().clearCookies().catch(() => {});
+          await page.waitForTimeout(1_500);
+        }
+
+        // commit only — domcontentloaded stalls when any subresource (ads/CDN) hangs via proxy
+        await page.goto(targetUrl, {
+          waitUntil: "commit",
+          timeout: NAV_TIMEOUT_MS,
+        });
+
+        // Give the SPA a short moment to mount React/Vue after document commit
+        await page.waitForTimeout(2_500);
+
+        // SPA shell loads first; wait for any login UI marker (not networkidle — long-lived sockets)
+        const spaReady = await waitForAnyVisible(page, SPA_READY_SELECTORS, SPA_TIMEOUT_MS);
+        if (!spaReady) {
+          const bodyText = await page.locator("body").innerText().catch(() => "");
+          const htmlLen = await page.evaluate(() => document.documentElement?.outerHTML?.length || 0).catch(() => 0);
+          reportStep(
+            "cn_spa_not_ready",
+            `SPA not ready after ${SPA_TIMEOUT_MS / 1000}s (url=${page.url()}, body=${String(bodyText).slice(0, 80)}, html=${htmlLen})`,
+          );
+          // If the page is completely empty, proxy likely blackholed the response
+          if (!bodyText && htmlLen < 200) {
+            reportStep("cn_proxy_empty_page", "Empty page body — proxy may be blocking codebuddy.cn");
+          }
+          continue;
+        }
+        reportStep("cn_spa_ready", "Login SPA ready");
+
+        // Step 2: Switch to phone-number tab
+        reportStep("cn_selecting_phone_tab", "Selecting phone-number tab");
+        const phoneTab = await waitForFirstVisibleLocator(page, PHONE_TAB_SELECTORS, { timeout: 15_000 });
+        if (phoneTab) {
+          await phoneTab.click().catch(() => {});
+          reportStep("cn_phone_tab_selected", "Phone tab selected");
+          await page.waitForTimeout(1_000);
+        } else {
+          reportStep("cn_phone_tab_not_found", "Phone tab not found — checking if iframe already present");
+        }
+
+        // Step 3: Wait for Keycloak phone iframe
+        reportStep("cn_waiting_for_iframe", "Waiting for phone iframe to load");
+        await page.locator(PHONE_IFRAME_SELECTOR).waitFor({ state: "attached", timeout: 25_000 }).catch(() => {});
+        phoneFrame = await getPhoneFrame(page);
+        if (phoneFrame) {
+          // Confirm phone input is actually inside the iframe
+          const phoneInputReady = await phoneFrame
+            .waitForSelector(IFRAME_PHONE_INPUT, { state: "visible", timeout: 20_000 })
+            .then(() => true)
+            .catch(() => false);
+          if (phoneInputReady) {
+            reportStep("cn_iframe_ready", "Phone iframe + #phoneNumber ready");
+            break;
+          }
+          reportStep("cn_iframe_empty", "Iframe found but #phoneNumber not visible yet");
+          phoneFrame = null;
+        } else {
+          reportStep("cn_iframe_missing", `No #phone-iframe (attempt ${navAttempt}/${NAV_MAX_ATTEMPTS})`);
+        }
+      } catch (navErr) {
+        reportStep(
+          "cn_nav_retry",
+          `Navigation attempt ${navAttempt}/${NAV_MAX_ATTEMPTS} failed: ${String(navErr.message || navErr).slice(0, 120)}`,
+        );
+      }
+    }
+
+    if (!phoneFrame) {
+      return {
+        status: "failed",
+        error: `Could not load CodeBuddy CN phone form after ${NAV_MAX_ATTEMPTS} attempts (proxy/SPA)`,
+      };
+    }
+
+    // Wait for the form to render inside the iframe
+    await phoneFrame.waitForSelector(iframeSelector(IFRAME_FORM), { timeout: action }).catch(() => {});
+    await phoneFrame.waitForSelector(iframeSelector(IFRAME_PHONE_INPUT), { state: "visible", timeout: action }).catch(() => {});
+
+    // Step 3b: Order phone ONLY after form is ready (saves balance if nav/proxy failed above).
+    let phone = phoneOpt;
+    if (typeof resolvePhone === "function") {
+      reportStep("cn_ordering_after_form", "Login form ready — ordering 5sim number now (not before nav)");
+      phone = await resolvePhone();
+    }
+    if (!phone) {
+      return {
+        status: "failed",
+        error: "No phone number available (resolvePhone/phone missing)",
+      };
+    }
+
+    // Step 4: Select country if needed (Hong Kong +852 for HK numbers)
+    const formattedPhone = phoneFormatter(phone);
+    const { countryCode, localNumber } = parsePhoneNumber(formattedPhone);
+    reportStep("cn_selecting_country", `Selecting country code ${countryCode} for phone ${formattedPhone}`);
+
+    await selectCountry(phoneFrame, countryCode, action, reportStep);
+
+    // Step 5: Enter the phone number (local portion without country code)
+    reportStep("cn_entering_phone", `Entering phone number: ${localNumber}`);
+    const phoneInput = phoneFrame.locator(iframeSelector(IFRAME_PHONE_INPUT)).first();
+    try {
+      await phoneInput.waitFor({ state: "visible", timeout: action });
+    } catch {
+      return {
+        status: "failed",
+        error: "Could not find the phone number input (#phoneNumber) inside the iframe",
+      };
+    }
+    await fillInputResilient(phoneInput, localNumber);
+    reportStep("cn_phone_entered", `Phone number entered: ${localNumber}`);
+
+    // Step 5b: Agreement checkbox is under "我已阅读并同意" — use last .t-checkbox
+    // (first one is often the WeChat tab state, not the phone-login consent).
+    try {
+      const agreementCheckbox = page.locator(".t-checkbox").last();
+      if (await agreementCheckbox.isVisible({ timeout: 3_000 }).catch(() => false)) {
+        await agreementCheckbox.click().catch(() => {});
+        reportStep("cn_agreement_checked", "Agreement checkbox checked");
+      }
+    } catch {
+      // Non-fatal — checkbox may not be present in all flows
+    }
+
+    // Step 6: Click "获取验证码" (send SMS code)
+    reportStep("cn_clicking_send_code", "Clicking send SMS code button");
+    const sendBtn = phoneFrame.locator(iframeSelector(IFRAME_SEND_CODE_BTN)).first();
+    let sendBtnVisible = false;
+    try {
+      await sendBtn.waitFor({ state: "visible", timeout: 5_000 });
+      sendBtnVisible = true;
+    } catch {
+      // Try alternate selector
+      const sendBtnAlt = phoneFrame.locator(iframeSelector(IFRAME_SEND_CODE_BTN_ALT)).first();
+      try {
+        await sendBtnAlt.waitFor({ state: "visible", timeout: 5_000 });
+        sendBtnVisible = true;
+      } catch {
+        sendBtnVisible = false;
+      }
+    }
+    if (!sendBtnVisible) {
+      return {
+        status: "failed",
+        error: "Could not find the send-SMS-code button (.code-btn) inside the iframe",
+      };
+    }
+    await sendBtn.click().catch(() => {});
+    reportStep("cn_send_code_clicked", "Send code button clicked");
+
+    // Check for immediate error (e.g. invalid phone, rate limit) — wait for error or code input to be ready
+    await phoneFrame.waitForSelector(IFRAME_CODE_INPUT, { state: "visible", timeout: 5_000 }).catch(() => {});
+    const iframeError = await checkIframeError(phoneFrame);
+    if (iframeError) {
+      return {
+        status: "failed",
+        error: `Form error after sending code: ${iframeError}`,
+      };
+    }
+
+    // Step 7: Wait for the SMS code from 5sim — start clock AFTER send-code click.
+    // Previously pollSmsPromise started at order time; slow China-proxy nav burned the
+    // whole 90s before OTP was even requested → false sms_timeout + banned numbers.
+    reportStep("cn_waiting_for_sms", "Waiting for SMS verification code from 5sim (timer starts now)");
+    let smsCode;
+    try {
+      let smsPromise;
+      if (typeof waitForSms === "function") {
+        smsPromise = Promise.resolve().then(() => waitForSms());
+      } else if (pollSmsPromise) {
+        smsPromise = pollSmsPromise;
+      } else {
+        throw new Error("No waitForSms/pollSmsPromise provided");
+      }
+      const codeTimeoutPromise = new Promise((_, reject) =>
+        setTimeout(() => reject(new Error("Timed out waiting for SMS code")), codeWait),
+      );
+      smsCode = await Promise.race([smsPromise, codeTimeoutPromise]);
+    } catch (err) {
+      // Re-throw FiveSimTimeoutError so processAccount can BAN the number
+      if (err && err.name === "FiveSimTimeoutError") throw err;
+      return {
+        status: "failed",
+        error: `Failed to receive SMS code: ${err.message}`,
+      };
+    }
+
+    if (!smsCode) {
+      return {
+        status: "failed",
+        error: "Received empty SMS code from 5sim",
+      };
+    }
+    reportStep("cn_sms_received", `SMS code received: ${smsCode}`);
+
+    // Step 8: Enter the OTP code into #code input
+    reportStep("cn_entering_code", "Entering SMS verification code");
+    const codeInput = phoneFrame.locator(iframeSelector(IFRAME_CODE_INPUT)).first();
+    try {
+      await codeInput.waitFor({ state: "visible", timeout: action });
+    } catch {
+      return {
+        status: "failed",
+        error: "Could not find the verification code input (#code) inside the iframe",
+      };
+    }
+    await fillInputResilient(codeInput, smsCode);
+    reportStep("cn_code_entered", "Verification code entered");
+
+    // Step 9: Click submit (#kc-login)
+    // Retry up to 3 times if "account restricted" (账号访问受限) is shown —
+    // refresh + re-enter phone + code each time (SMS code valid for 5 min).
+    // After a clean submit, poll up to SESSION_WAIT_MS for Keycloak cookies —
+    // China residential proxies often leave a blank SPA shell for 5–15s before
+    // the OIDC handoff sets KEYCLOAK_IDENTITY (previous 2s check was too short).
+    const MAX_SUBMIT_RETRIES = 3;
+    const SESSION_WAIT_MS = Math.max(postSubmit, 20_000);
+    let submitSuccess = false;
+    for (let retry = 0; retry < MAX_SUBMIT_RETRIES; retry++) {
+      reportStep("cn_submitting", `Clicking submit button (attempt ${retry + 1}/${MAX_SUBMIT_RETRIES})`);
+
+      // Re-get the phone frame (it may have changed after refresh)
+      let currentFrame = await getPhoneFrame(page);
+      if (!currentFrame) {
+        // Iframe may already be gone if submit on a previous attempt started redirect
+        const earlySession = await waitForKeycloakSession(page, { timeoutMs: 5_000, reportStep });
+        if (earlySession.ok) {
+          reportStep("cn_session_cookies", `Keycloak session after iframe detach (${earlySession.cookie})`);
+          return { status: "success" };
+        }
+        return { status: "failed", error: "Lost phone iframe after submit" };
+      }
+
+      // Check if form is still on the login page (needs re-input) or already submitted
+      const hasPhoneInput = await currentFrame.locator(iframeSelector(IFRAME_PHONE_INPUT)).first().isVisible({ timeout: 3_000 }).catch(() => false);
+
+      if (hasPhoneInput && retry > 0) {
+        // Re-enter phone number and code after refresh
+        reportStep("cn_re_entering_after_refresh", `Re-entering phone + code after refresh (retry ${retry})`);
+        await selectCountry(currentFrame, countryCode, action, reportStep);
+        const phoneInputRetry = currentFrame.locator(iframeSelector(IFRAME_PHONE_INPUT)).first();
+        await fillInputResilient(phoneInputRetry, localNumber);
+
+        // Re-check agreement checkbox
+        try {
+          const cb = page.locator(".t-checkbox").first();
+          if (await cb.isVisible({ timeout: 2_000 }).catch(() => false)) {
+            await cb.click().catch(() => {});
+          }
+        } catch {
+          // non-fatal
+        }
+
+        // Re-enter code
+        const codeInputRetry = currentFrame.locator(iframeSelector(IFRAME_CODE_INPUT)).first();
+        if (await codeInputRetry.isVisible({ timeout: 3_000 }).catch(() => false)) {
+          await fillInputResilient(codeInputRetry, smsCode);
+        }
+      }
+
+      // Prefer real form submit over a bare button click (Keycloak listens to form submit).
+      await submitLoginForm(currentFrame, action);
+      reportStep("cn_submitted", `Registration form submitted (attempt ${retry + 1})`);
+
+      // Brief settle then poll for session / errors / captcha / restriction
+      await page.waitForLoadState("domcontentloaded", { timeout: 5_000 }).catch(() => {});
+      await page.waitForTimeout(1_000);
+
+      // Live re-fetch frame — redirect may replace the iframe mid-flight
+      currentFrame = (await getPhoneFrame(page)) || currentFrame;
+
+      // Check for "account restricted" (账号访问受限)
+      const restrictionDetected = await checkAccountRestricted(currentFrame);
+      if (restrictionDetected) {
+        reportStep("cn_account_restricted", `Account restricted (attempt ${retry + 1}) — refreshing page and retrying`);
+        await page.reload({ waitUntil: "domcontentloaded", timeout: nav }).catch(() => {});
+        await waitForAnyVisible(page, SPA_READY_SELECTORS, 20_000);
+        const phoneTabRetry = await waitForFirstVisibleLocator(page, PHONE_TAB_SELECTORS, { timeout: action });
+        if (phoneTabRetry) {
+          await phoneTabRetry.click().catch(() => {});
+          await page.locator(PHONE_IFRAME_SELECTOR).waitFor({ state: "attached", timeout: 10_000 }).catch(() => {});
+        }
+        continue; // Retry submit
+      }
+
+      // Captcha
+      reportStep("cn_checking_captcha", "Checking for captcha");
+      const captchaDetected = await detectCaptcha(page, currentFrame, 3_000);
+      if (captchaDetected) {
+        reportStep("cn_captcha_detected", "Captcha appeared during registration — manual assist needed");
+        return {
+          status: "needs_manual",
+          error: "A captcha appeared during registration. Please complete it manually in the opened browser window.",
+          captcha: true,
+        };
+      }
+
+      // Form errors (wrong OTP, rate limit, etc.)
+      const postSubmitError = await checkIframeError(currentFrame);
+      if (postSubmitError) {
+        return {
+          status: "failed",
+          error: `Form error after submit: ${postSubmitError}`,
+        };
+      }
+
+      // Poll for Keycloak session cookies (slow China proxy / blank SPA shell)
+      reportStep("cn_waiting_session", `Waiting up to ${Math.round(SESSION_WAIT_MS / 1000)}s for Keycloak session cookies`);
+      const session = await waitForKeycloakSession(page, {
+        timeoutMs: SESSION_WAIT_MS,
+        reportStep,
+        alsoCheckFrame: () => getPhoneFrame(page),
+      });
+      if (session.ok) {
+        reportStep("cn_session_cookies", `Keycloak session cookies present (${session.cookie}) — registration success`);
+        return { status: "success" };
+      }
+
+      // Still on login form? Click may not have submitted — retry
+      const stillOnForm = await isLoginFormStillVisible(page);
+      if (stillOnForm && retry < MAX_SUBMIT_RETRIES - 1) {
+        reportStep("cn_submit_no_effect", "Login form still visible after submit — retrying");
+        continue;
+      }
+
+      // Blank SPA / mid-redirect: try landing on home to finish OIDC handoff
+      reportStep("cn_session_nudge", "No session yet — navigating to home to complete OIDC handoff");
+      await page.goto("https://www.codebuddy.cn/", { waitUntil: "domcontentloaded", timeout: nav }).catch(() => {});
+      await page.waitForTimeout(2_000);
+      const sessionAfterHome = await waitForKeycloakSession(page, { timeoutMs: 10_000, reportStep });
+      if (sessionAfterHome.ok) {
+        reportStep("cn_session_cookies", `Keycloak session after home nudge (${sessionAfterHome.cookie})`);
+        return { status: "success" };
+      }
+
+      submitSuccess = true;
+      break;
+    }
+
+    if (!submitSuccess) {
+      reportStep("cn_submit_retries_exhausted", `Account restricted after ${MAX_SUBMIT_RETRIES} retries — needs manual`);
+      return {
+        status: "needs_manual",
+        error: `Account restricted after ${MAX_SUBMIT_RETRIES} refresh retries. Please try with a different VPN/proxy or complete manually.`,
+      };
+    }
+
+    // Step 11: Final confirmation (UI markers OR session cookies)
+    reportStep("cn_confirming_success", "Confirming registration success");
+    const sessionFinal = await waitForKeycloakSession(page, { timeoutMs: 5_000 });
+    if (sessionFinal.ok) {
+      reportStep("cn_registration_success", `Phone registration completed (Keycloak session: ${sessionFinal.cookie})`);
+      return { status: "success" };
+    }
+
+    const success = await confirmRegistrationSuccess(page, phoneFrame, 10_000);
+    if (success) {
+      reportStep("cn_registration_success", "Phone registration completed successfully (UI markers)");
+      return { status: "success" };
+    }
+
+    // Ambiguous: submit happened, blank SPA, no cookies — keep headed browser for operator.
+    // Hard-failing here burned working numbers when the handoff was just slow / captcha-soft.
+    const diag = await collectPostLoginDiagnostics(page);
+    reportStep("cn_success_unconfirmed", `No Keycloak session after submit — ${diag.summary}`);
+    return {
+      status: "needs_manual",
+      error: `Login submit finished but no Keycloak session yet (${diag.summary}). Complete login in the headed browser or retry with a fresh China proxy.`,
+    };
+  } catch (err) {
+    // Re-throw FiveSimTimeoutError so processAccount can BAN the number
+    if (err && err.name === "FiveSimTimeoutError") throw err;
+    reportStep("cn_automation_error", `Phone registration automation error: ${err.message}`);
+    return {
+      status: "failed",
+      error: err.message || "Unexpected error during phone registration",
+    };
+  }
+}
+
+// ─── Helper functions ─────────────────────────────────────────────────────
+
+/**
+ * Get the phone iframe's Frame object from the page.
+ * The iframe id is #phone-iframe, src contains /auth/realms/copilot/.
+ */
+async function getPhoneFrame(page) {
+  // Prefer locator contentFrame (waits for attach) over scanning frames too early
+  try {
+    await page.locator(PHONE_IFRAME_SELECTOR).waitFor({ state: "attached", timeout: 5_000 });
+    const iframeElement = await page.locator(PHONE_IFRAME_SELECTOR).elementHandle({ timeout: 2_000 });
+    if (iframeElement) {
+      const frame = await iframeElement.contentFrame();
+      if (frame) return frame;
+    }
+  } catch {
+    // fall through
+  }
+
+  const frames = page.frames();
+  for (const frame of frames) {
+    const url = frame.url();
+    if (url.includes("codebuddy.cn/auth/realms/copilot") || url.includes("protocol/openid-connect")) {
+      return frame;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Prefix a selector for use inside a frame (frames don't need special prefixing,
+ * but this keeps the code explicit about which context we're querying).
+ */
+function iframeSelector(sel) {
+  return sel;
+}
+
+/**
+ * Parse a phone number into country code and local number.
+ * Handles +852XXXXXXXX, +86XXXXXXXX, etc.
+ * @returns {{countryCode: string, localNumber: string}}
+ */
+function parsePhoneNumber(phone) {
+  // Normalize: strip spaces/dashes/parens, ensure leading +
+  let cleaned = String(phone).replace(/[\s\-()]/g, "");
+  if (!cleaned.startsWith("+") && /^\d+$/.test(cleaned)) {
+    cleaned = "+" + cleaned;
+  }
+
+  // +852 (Hong Kong)
+  if (cleaned.startsWith("+852")) {
+    return { countryCode: "+852", localNumber: cleaned.slice(4) };
+  }
+  // +86 (China)
+  if (cleaned.startsWith("+86")) {
+    return { countryCode: "+86", localNumber: cleaned.slice(3) };
+  }
+  // +1 (US/Canada)
+  if (cleaned.startsWith("+1")) {
+    return { countryCode: "+1", localNumber: cleaned.slice(2) };
+  }
+  // No recognizable country code — assume the number is already local
+  return { countryCode: "", localNumber: cleaned.replace(/^\+/, "") };
+}
+
+/**
+ * Select the country code in the Keycloak form dropdown.
+ * If the current country code already matches, do nothing.
+ */
+async function selectCountry(frame, targetCountryCode, actionTimeout, reportStep) {
+  if (!targetCountryCode) return; // No specific country to select
+
+  try {
+    // Check current country code
+    const currentCodeEl = frame.locator(iframeSelector(IFRAME_COUNTRY_CODE_TEXT)).first();
+    const currentCode = await currentCodeEl.textContent({ timeout: 5_000 }).catch(() => "");
+    const trimmedCode = String(currentCode).trim();
+
+    if (trimmedCode === targetCountryCode) {
+      reportStep?.("cn_country_already_selected", `Country code already ${targetCountryCode}`);
+      return;
+    }
+
+    // Click the country selector to open dropdown
+    reportStep?.("cn_opening_country_dropdown", `Opening country dropdown (current: ${trimmedCode}, target: ${targetCountryCode})`);
+    const selector = frame.locator(iframeSelector(IFRAME_COUNTRY_SELECTOR)).first();
+    await selector.waitFor({ state: "visible", timeout: actionTimeout });
+    await selector.click().catch(() => {});
+    // Wait for dropdown options to appear
+    await frame.locator(iframeSelector(IFRAME_COUNTRY_OPTIONS)).first()
+      .waitFor({ state: "visible", timeout: 5_000 }).catch(() => {});
+
+    // Find the option matching the target country code
+    const options = frame.locator(iframeSelector(IFRAME_COUNTRY_OPTIONS));
+    const count = await options.count();
+
+    for (let i = 0; i < count; i++) {
+      const option = options.nth(i);
+      const optionText = await option.textContent().catch(() => "");
+      if (String(optionText).includes(targetCountryCode)) {
+        await option.click().catch(() => {});
+        // Confirm selection applied
+        await frame.locator(iframeSelector(IFRAME_COUNTRY_CODE_TEXT))
+          .filter({ hasText: targetCountryCode })
+          .first()
+          .waitFor({ state: "visible", timeout: 3_000 })
+          .catch(() => {});
+        reportStep?.("cn_country_selected", `Country selected: ${String(optionText).trim()}`);
+        return;
+      }
+    }
+
+    // If no matching option found, close dropdown by clicking elsewhere
+    reportStep?.("cn_country_not_found", `Country code ${targetCountryCode} not found in dropdown; using default`);
+    await frame.locator("body").click().catch(() => {});
+  } catch (err) {
+    reportStep?.("cn_country_select_error", `Country selection error: ${err.message}`);
+    // Non-fatal — continue with default country
+  }
+}
+
+/**
+ * Try a list of selectors and return the first visible locator, or null.
+ */
+async function waitForFirstVisibleLocator(page, selectors, { timeout = 10_000 } = {}) {
+  for (const sel of selectors) {
+    try {
+      const locator = page.locator(sel).first();
+      await locator.waitFor({ state: "visible", timeout: Math.min(timeout, 5_000) });
+      return locator;
+    } catch {
+      // Try next selector
+    }
+  }
+  return null;
+}
+
+/** Wait until ANY of the selectors becomes visible (parallel race). */
+async function waitForAnyVisible(page, selectors, timeout = 15_000) {
+  const deadline = Date.now() + timeout;
+  while (Date.now() < deadline) {
+    for (const sel of selectors) {
+      try {
+        const locator = page.locator(sel).first();
+        if (await locator.isVisible().catch(() => false)) return true;
+      } catch {
+        // next
+      }
+    }
+    // tiny yield so we don't busy-spin; not a page-load wait
+    await new Promise((r) => setTimeout(r, 250));
+  }
+  return false;
+}
+
+/**
+ * Fill an input resiliently (some SPAs need focus + clear before fill).
+ */
+async function fillInputResilient(locator, value) {
+  try {
+    await locator.click();
+    await locator.fill("");
+    await locator.fill(value);
+    return true;
+  } catch {
+    try {
+      // Fallback: type character by character
+      await locator.click();
+      await locator.press("Control+a");
+      await locator.type(value, { delay: 50 });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}
+
+/** Cookie names that prove a real Keycloak login session on codebuddy.cn */
+const KEYCLOAK_SESSION_COOKIE_NAMES = [
+  "KEYCLOAK_IDENTITY",
+  "KEYCLOAK_SESSION",
+  "KEYCLOAK_IDENTITY_LEGACY",
+  "KEYCLOAK_SESSION_LEGACY",
+];
+
+function findKeycloakSessionCookie(cookies = []) {
+  for (const name of KEYCLOAK_SESSION_COOKIE_NAMES) {
+    if (cookies.some((c) => c.name === name)) return name;
+  }
+  // Any KEYCLOAK_* identity-ish cookie (defensive against renames)
+  const loose = cookies.find(
+    (c) => c.name.startsWith("KEYCLOAK_") && !/locale|theme|restart/i.test(c.name),
+  );
+  return loose?.name || null;
+}
+
+/**
+ * Poll until Keycloak session cookies appear, or timeout.
+ * Also bails early if captcha / account-restricted / form error show up.
+ */
+async function waitForKeycloakSession(page, { timeoutMs = 20_000, reportStep, alsoCheckFrame } = {}) {
+  const deadline = Date.now() + timeoutMs;
+  let lastReport = 0;
+  while (Date.now() < deadline) {
+    const cookies = await page.context().cookies().catch(() => []);
+    const hit = findKeycloakSessionCookie(cookies);
+    if (hit) return { ok: true, cookie: hit, cookies };
+
+    // Soft success only for strong app tokens — NOT bare "session" / AUTH_SESSION_ID
+    // (those appear mid-OIDC and caused false positives + wasted numbers).
+    try {
+      const url = page.url();
+      if (url && !url.includes("/login") && !url.includes("/auth/realms")) {
+        const appSession = cookies.find((c) =>
+          /^(access_token|cb_token|codebuddy)/i.test(c.name)
+          || (c.name === "token" && c.domain?.includes("codebuddy")),
+        );
+        if (appSession) return { ok: true, cookie: appSession.name, cookies };
+      }
+    } catch {
+      // ignore
+    }
+
+    if (alsoCheckFrame) {
+      const frame = await alsoCheckFrame().catch(() => null);
+      if (frame) {
+        if (await checkAccountRestricted(frame)) {
+          return { ok: false, cookies, reason: "restricted" };
+        }
+        const err = await checkIframeError(frame);
+        if (err) return { ok: false, cookies, reason: `form_error:${err}` };
+      }
+    }
+
+    if (reportStep && Date.now() - lastReport > 4_000) {
+      lastReport = Date.now();
+      const remaining = Math.max(0, Math.round((deadline - Date.now()) / 1000));
+      reportStep("cn_waiting_session", `Still waiting for Keycloak session… ${remaining}s left`);
+    }
+    await page.waitForTimeout(500);
+  }
+  const cookies = await page.context().cookies().catch(() => []);
+  return { ok: false, cookies };
+}
+
+/**
+ * Submit Keycloak login form robustly (click #kc-login + form.requestSubmit fallback).
+ */
+async function submitLoginForm(frame, actionTimeout = 15_000) {
+  const submitBtn = frame.locator(iframeSelector(IFRAME_SUBMIT_BTN)).first();
+  try {
+    await submitBtn.waitFor({ state: "visible", timeout: actionTimeout });
+    await submitBtn.click({ timeout: 5_000 }).catch(() => {});
+  } catch {
+    // fall through to form submit
+  }
+
+  // Explicit form submit — more reliable than button click on some Keycloak themes
+  try {
+    await frame.evaluate(() => {
+      const form = document.querySelector("#kc-form-login") || document.querySelector("form");
+      if (!form) return;
+      if (typeof form.requestSubmit === "function") {
+        const btn = form.querySelector("#kc-login") || form.querySelector('[type="submit"]');
+        if (btn) form.requestSubmit(btn);
+        else form.requestSubmit();
+      } else {
+        form.submit();
+      }
+    });
+  } catch {
+    await frame.locator(iframeSelector(IFRAME_CODE_INPUT)).first().press("Enter").catch(() => {});
+  }
+}
+
+async function isLoginFormStillVisible(page) {
+  const frame = await getPhoneFrame(page);
+  if (!frame) return false;
+  return frame.locator(iframeSelector(IFRAME_PHONE_INPUT)).first().isVisible({ timeout: 1_500 }).catch(() => false);
+}
+
+async function collectPostLoginDiagnostics(page) {
+  let url = "";
+  try {
+    url = page.url();
+  } catch {
+    url = "(unknown)";
+  }
+  const cookies = await page.context().cookies().catch(() => []);
+  const cookieNames = cookies.map((c) => c.name).slice(0, 20).join(",") || "(none)";
+  let bodySnippet = "";
+  try {
+    bodySnippet = await page.evaluate(() => (document.body?.innerText || "").replace(/\s+/g, " ").trim().slice(0, 120));
+  } catch {
+    bodySnippet = "";
+  }
+  const frame = await getPhoneFrame(page);
+  let frameHint = "no-iframe";
+  if (frame) {
+    try {
+      frameHint = (await frame.url()).slice(0, 80);
+    } catch {
+      frameHint = "iframe-detached";
+    }
+  }
+  const summary = `url=${url.slice(0, 60)} cookies=[${cookieNames}] frame=${frameHint}${bodySnippet ? ` text="${bodySnippet}"` : ""}`;
+  return { summary, url, cookieNames, bodySnippet };
+}
+
+/**
+ * Check for "account restricted" message in the iframe (and main page).
+ * Tencent shows "账号访问受限" when a virtual number / risk policy blocks login.
+ */
+async function checkAccountRestricted(frame) {
+  try {
+    const bodyText = await frame.evaluate(() => document.body?.innerText || "");
+    if (
+      bodyText.includes("账号访问受限")
+      || bodyText.includes("安全策略限制")
+      || bodyText.includes("访问受限")
+    ) {
+      return true;
+    }
+  } catch {
+    // Ignore
+  }
+  return false;
+}
+
+/**
+ * Check for error messages inside the iframe.
+ */
+async function checkIframeError(frame) {
+  for (const sel of IFRAME_ERROR_SELECTORS) {
+    try {
+      const el = frame.locator(iframeSelector(sel)).first();
+      const isVisible = await el.isVisible({ timeout: 1_500 }).catch(() => false);
+      if (isVisible) {
+        const text = await el.textContent().catch(() => "");
+        const trimmed = String(text).trim();
+        if (trimmed && trimmed.length > 1) {
+          return trimmed;
+        }
+      }
+    } catch {
+      // Try next
+    }
+  }
+  // Keycloak often dumps errors into body text without a dedicated error node
+  try {
+    const bodyText = await frame.evaluate(() => (document.body?.innerText || "").replace(/\s+/g, " ").trim());
+    const markers = [
+      "验证码错误",
+      "验证码已过期",
+      "验证码无效",
+      "请输入正确的验证码",
+      "手机号格式",
+      "发送过于频繁",
+      "Invalid",
+      "incorrect",
+    ];
+    for (const m of markers) {
+      if (bodyText.includes(m)) {
+        // Don't treat full page chrome as error — keep snippet short
+        const idx = bodyText.indexOf(m);
+        return bodyText.slice(Math.max(0, idx - 10), idx + m.length + 40).trim();
+      }
+    }
+  } catch {
+    // ignore
+  }
+  return null;
+}
+
+/**
+ * Probe the page and iframe for captcha widgets.
+ */
+async function detectCaptcha(page, frame, timeout = 5_000) {
+  // Check main page
+  for (const sel of CAPTCHA_SELECTORS) {
+    try {
+      const locator = page.locator(sel).first();
+      const isVisible = await locator.isVisible({ timeout: Math.min(timeout, 2_000) }).catch(() => false);
+      if (isVisible) return true;
+    } catch {
+      // Try next
+    }
+  }
+  // Check inside iframe
+  if (frame) {
+    for (const sel of CAPTCHA_SELECTORS) {
+      try {
+        const locator = frame.locator(sel).first();
+        const isVisible = await locator.isVisible({ timeout: Math.min(timeout, 2_000) }).catch(() => false);
+        if (isVisible) return true;
+      } catch {
+        // Try next
+      }
+    }
+  }
+  return false;
+}
+
+/**
+ * Confirm that registration succeeded by checking for strong logged-in signals.
+ * Do NOT accept bare `session` / AUTH_SESSION_ID alone — those appear mid-OIDC
+ * and previously caused false "UI markers" success → wasted 5sim numbers when
+ * API key capture then hard-failed on missing KEYCLOAK_IDENTITY.
+ */
+async function confirmRegistrationSuccess(page, frame, timeout = 15_000) {
+  // Strong: real Keycloak identity cookies
+  try {
+    const cookies = await page.context().cookies().catch(() => []);
+    if (findKeycloakSessionCookie(cookies)) return true;
+  } catch {
+    // Ignore
+  }
+
+  // Strong: logged-in UI chrome (avatar / logout)
+  for (const sel of LOGGED_IN_SELECTORS) {
+    try {
+      const locator = page.locator(sel).first();
+      const isVisible = await locator.isVisible({ timeout: Math.min(timeout, 2_000) }).catch(() => false);
+      if (isVisible) return true;
+    } catch {
+      // Try next
+    }
+  }
+
+  // Soft-but-useful: left /login AND has qcloud_uid (Tencent account cookie)
+  try {
+    const url = page.url();
+    const cookies = await page.context().cookies().catch(() => []);
+    const names = new Set(cookies.map((c) => c.name));
+    if (
+      url
+      && !url.includes("/login")
+      && !url.includes("/auth/realms")
+      && (names.has("qcloud_uid") || names.has("qcmainCSRFToken"))
+      && !names.has("login_risk_state") // risk state alone often means blocked/incomplete
+    ) {
+      // Still require login form gone
+      const formVisible = await isLoginFormStillVisible(page).catch(() => false);
+      if (!formVisible) return true;
+    }
+  } catch {
+    // Ignore
+  }
+
+  return false;
+}
+
+export const __test__ = {
+  waitForFirstVisibleLocator,
+  fillInputResilient,
+  detectCaptcha,
+  confirmRegistrationSuccess,
+  parsePhoneNumber,
+  selectCountry,
+  getPhoneFrame,
+  findKeycloakSessionCookie,
+  waitForKeycloakSession,
+  submitLoginForm,
+  PHONE_TAB_SELECTORS,
+  PHONE_IFRAME_SELECTOR,
+  IFRAME_PHONE_INPUT,
+  IFRAME_CODE_INPUT,
+  IFRAME_SEND_CODE_BTN,
+  IFRAME_SUBMIT_BTN,
+  CAPTCHA_SELECTORS,
+  LOGGED_IN_SELECTORS,
+  KEYCLOAK_SESSION_COOKIE_NAMES,
+};