dsh-browser-playwright-codex 0.6.1 → 0.6.6

package/lib/challenge-signatures.d.ts

@@ -0,0 +1,114 @@
+/**
+ * 挑战页签名表：把「这页是不是拦截页」的判据放在厂商自有信号上，而不是页面文案上。
+ *
+ * 为什么分层，以及为什么是这个顺序（稳定性递减）：
+ *
+ * 1. 响应头是厂商对外的 API。Cloudflare 专门发文教用户读 `cf-mitigated: challenge`
+ *    来识别挑战页，AWS WAF 同理（`x-amzn-waf-action: challenge`）。厂商改一个字的代价
+ *    是打断所有客户的集成，不是打断我们一个插件。
+ * 2. 厂商控件的无障碍名是次稳的：reCAPTCHA / hCaptcha / Turnstile 的 iframe 标题就是
+ *    他们自己的产品名，出现在每一张用了他们的页面上。
+ * 3. 文案最脆。FlareSolverr 就是死在依赖页面 title 和元素 class 上（上游 issue #1734：
+ *    「元素的 class 和 id 被改过，所以现有的检测规则失效」）。
+ *
+ * 因此新增一家厂商 = 在这张表里加一条签名 + 在 tests/challenge.test.ts 加一条用例，
+ * 判定逻辑本身不用改。
+ * @module dsh-browser-playwright-codex/challenge-signatures
+ */
+/**
+ * How a signature was proven. `response-header` is the vendor's own API,
+ * `widget` is the vendor's own widget, `wording` is the fallback we trust least.
+ */
+export type ChallengeTier = 'response-header' | 'widget' | 'wording';
+/**
+ * One response-header rule. Matching is case-insensitive; a rule with neither
+ * `equals` nor `contains` fires on the header's presence alone.
+ */
+export interface HeaderRule {
+    /** Exact header name. Ignored when `namePrefix` is set. */
+    readonly name: string;
+    /** Exact value the header must carry. */
+    readonly equals?: string;
+    /** Substring the value must contain. */
+    readonly contains?: string;
+}
+/** One vendor's interception signature. */
+export interface ChallengeSignature {
+    /** Stable id, used in tests and diagnostics. */
+    readonly id: string;
+    /** Engine label shown to the model. */
+    readonly engine: string;
+    /** One-clause explanation of what is happening. */
+    readonly hint: string;
+    /**
+     * Header rules proven against the MAIN document response. These are the
+     * vendor's published detection contract, so they are checked first.
+     */
+    readonly headers?: readonly HeaderRule[];
+    /** Case-insensitive header-name prefixes (e.g. DataDome's `x-datadome*`). */
+    readonly headerPrefixes?: readonly string[];
+    /**
+     * Status codes this signature must be corroborated by. Needed for vendors whose
+     * header is *not* challenge-specific: DataDome adds `x-datadome*` to every
+     * response (their docs say so, and they return `NA` when detection is off), and
+     * Imperva adds `x-iinfo` to everything it fronts. Measured 2026-10-17: a normal
+     * DataDome-fronted page answered 200 with `x-datadome: protected`, which an
+     * ungated rule would have reported as a wall.
+     */
+    readonly statuses?: readonly number[];
+    /**
+     * Accessible-name tokens only this vendor's widget carries. On a non-iframe
+     * node a token must ALSO be corroborated by {@link WIDGET_CORROBORATION}.
+     */
+    readonly widgetTokens?: readonly RegExp[];
+    /**
+     * Wording this vendor puts in the TITLE of its own interstitial. Vendor
+     * wording is stronger than generic wording, so it is checked first and keeps
+     * the vendor's name on the result.
+     */
+    readonly titleWording?: readonly RegExp[];
+}
+/**
+ * Wording that corroborates a widget token found on a non-iframe node.
+ *
+ * Shared by every vendor on purpose, and it contains no vendor token: three of
+ * the tokens below ("reCAPTCHA", "FunCaptcha", "px-captcha") literally contain
+ * the word "captcha", so a list that accepted "captcha" would let the token
+ * corroborate itself and the guard would be vacuous.
+ */
+export declare const WIDGET_CORROBORATION: readonly RegExp[];
+/**
+ * Every vendor we can prove from machine signals. Adding a vendor here is the
+ * whole change: the detector walks the table, it does not know any of these names.
+ */
+export declare const CHALLENGE_SIGNATURES: readonly ChallengeSignature[];
+/**
+ * Wording a challenge page puts in its TITLE, with no vendor to attribute it to.
+ * A title is short and authored by the interceptor, so a match here is safe on
+ * its own. Kept combinatorial ("verification" + "human/safety/…") rather than
+ * one phrase per language, so a reworded page still matches without a new
+ * signature.
+ */
+export declare const WORDING_TITLE: readonly RegExp[];
+/**
+ * Wording a challenge page puts on a CONTROL (a button, a link, an input).
+ * Command forms only: a help page that explains captchas says "验证码说明",
+ * a challenge says "请输入验证码". The bare word for captcha is deliberately NOT
+ * here — it is gated on a control role in {@link CAPTCHA_ROLES} instead, so a
+ * link to the documentation cannot fire this tier.
+ */
+export declare const WORDING_COMMAND: readonly RegExp[];
+/**
+ * Controls that mention verification but are NOT a bot wall: sending yourself a
+ * code is an ordinary sign-in step, and labelling it an anti-bot challenge
+ * would send the user looking for a wall that is not there.
+ */
+export declare const WORDING_EXCLUDE: readonly RegExp[];
+/** The word for "captcha" itself; only counts on a {@link CAPTCHA_ROLES} node. */
+export declare const CAPTCHA_WORD: RegExp;
+/**
+ * Roles that make {@link CAPTCHA_WORD} count. A captcha input, image or button
+ * is a challenge; a link or heading named "验证码说明" is documentation, and
+ * firing on it would send the user chasing a wall that is not there.
+ */
+export declare const CAPTCHA_ROLES: ReadonlySet<string>;

package/lib/challenge-signatures.js

@@ -0,0 +1,157 @@
+/**
+ * 挑战页签名表：把「这页是不是拦截页」的判据放在厂商自有信号上，而不是页面文案上。
+ *
+ * 为什么分层，以及为什么是这个顺序（稳定性递减）：
+ *
+ * 1. 响应头是厂商对外的 API。Cloudflare 专门发文教用户读 `cf-mitigated: challenge`
+ *    来识别挑战页，AWS WAF 同理（`x-amzn-waf-action: challenge`）。厂商改一个字的代价
+ *    是打断所有客户的集成，不是打断我们一个插件。
+ * 2. 厂商控件的无障碍名是次稳的：reCAPTCHA / hCaptcha / Turnstile 的 iframe 标题就是
+ *    他们自己的产品名，出现在每一张用了他们的页面上。
+ * 3. 文案最脆。FlareSolverr 就是死在依赖页面 title 和元素 class 上（上游 issue #1734：
+ *    「元素的 class 和 id 被改过，所以现有的检测规则失效」）。
+ *
+ * 因此新增一家厂商 = 在这张表里加一条签名 + 在 tests/challenge.test.ts 加一条用例，
+ * 判定逻辑本身不用改。
+ * @module dsh-browser-playwright-codex/challenge-signatures
+ */
+/**
+ * Wording that corroborates a widget token found on a non-iframe node.
+ *
+ * Shared by every vendor on purpose, and it contains no vendor token: three of
+ * the tokens below ("reCAPTCHA", "FunCaptcha", "px-captcha") literally contain
+ * the word "captcha", so a list that accepted "captcha" would let the token
+ * corroborate itself and the guard would be vacuous.
+ */
+export const WIDGET_CORROBORATION = Object.freeze([
+    /verify|challenge|robot|human|verification/i,
+    /验证|校验|人机|真人/,
+]);
+/**
+ * Every vendor we can prove from machine signals. Adding a vendor here is the
+ * whole change: the detector walks the table, it does not know any of these names.
+ */
+export const CHALLENGE_SIGNATURES = Object.freeze([
+    {
+        id: 'cloudflare-challenge',
+        engine: 'Cloudflare',
+        hint: 'Cloudflare answered with a challenge page instead of the page itself',
+        headers: [{ name: 'cf-mitigated', equals: 'challenge' }],
+        // The interstitial's own title, in both languages. Only reached when the
+        // header is missing (a cached page, a prefetch, a client-side fetch).
+        titleWording: [
+            /just a moment|attention required|checking (your )?browser|enable javascript and cookies|cf-chl-/i,
+            /请稍候|验证你的浏览器|正在进行安全验证/,
+        ],
+    },
+    {
+        id: 'aws-waf',
+        engine: 'AWS WAF',
+        hint: 'AWS WAF answered with a challenge instead of the page itself',
+        headers: [{ name: 'x-amzn-waf-action', equals: 'challenge' }],
+    },
+    {
+        id: 'imperva-incapsula',
+        engine: 'Imperva',
+        hint: 'Imperva (Incapsula) blocked this request from its edge',
+        // Presence only: X-IInfo is an opaque per-response trace that Imperva adds to
+        // everything it fronts, so the header alone says nothing about a block — the
+        // status code has to agree.
+        headers: [{ name: 'x-iinfo' }],
+        statuses: [403, 429, 503],
+    },
+    {
+        id: 'datadome',
+        engine: 'DataDome',
+        hint: 'DataDome blocked this request',
+        headerPrefixes: ['x-datadome'],
+        statuses: [403, 429, 503],
+    },
+    {
+        id: 'recaptcha',
+        engine: 'captcha',
+        hint: 'the page embedded a reCAPTCHA widget, which automation must not attempt to solve',
+        widgetTokens: [/recaptcha/i],
+    },
+    {
+        id: 'hcaptcha',
+        engine: 'captcha',
+        hint: 'the page embedded an hCaptcha widget, which automation must not attempt to solve',
+        widgetTokens: [/hcaptcha/i],
+    },
+    {
+        id: 'turnstile',
+        engine: 'Cloudflare',
+        hint: 'Cloudflare Turnstile is asking the visitor to prove they are human',
+        widgetTokens: [/turnstile/i, /widget containing a cloudflare security challenge/i],
+    },
+    {
+        id: 'arkose-funcaptcha',
+        engine: 'captcha',
+        hint: 'the page embedded an Arkose / FunCaptcha challenge, which automation must not attempt to solve',
+        widgetTokens: [/arkoselabs/i, /funcaptcha/i, /arkose/i],
+    },
+    {
+        id: 'perimeterx-human',
+        engine: 'PerimeterX',
+        hint: 'PerimeterX is asking the visitor to press and hold, which automation must not attempt',
+        widgetTokens: [/px-captcha/i, /perimeterx/i, /press (and|&) hold/i],
+    },
+]);
+/**
+ * Wording a challenge page puts in its TITLE, with no vendor to attribute it to.
+ * A title is short and authored by the interceptor, so a match here is safe on
+ * its own. Kept combinatorial ("verification" + "human/safety/…") rather than
+ * one phrase per language, so a reworded page still matches without a new
+ * signature.
+ */
+export const WORDING_TITLE = Object.freeze([
+    /verify (you are|you're|that you are) (a )?human|are you a robot/i,
+    /人机验证|验证您(是|为)人类|真人验证|安全验证|身份验证|访客验证/,
+    /(滑块|拼图)(验证|校验)/,
+]);
+/**
+ * Wording a challenge page puts on a CONTROL (a button, a link, an input).
+ * Command forms only: a help page that explains captchas says "验证码说明",
+ * a challenge says "请输入验证码". The bare word for captcha is deliberately NOT
+ * here — it is gated on a control role in {@link CAPTCHA_ROLES} instead, so a
+ * link to the documentation cannot fire this tier.
+ */
+export const WORDING_COMMAND = Object.freeze([
+    /(请|点击|输入|拖动|按住|滑动|完成|进行|通过)[^。！？]{0,8}(验证|校验|拼图|滑块)/,
+    /(验证|校验)(您|你)(是|为)/,
+    /(是|为)(真人|人类)(吗|？|\?)?$/,
+    /(拖动|按住|滑动)[^。！？]{0,8}(滑块|拼图)/,
+    /(verify|click|press|complete|solve|check|confirm)[^.!?]{0,24}(human|robot|browser|captcha|challenge|you are)/i,
+    /i'?m not a robot|not a robot/i,
+]);
+/**
+ * Controls that mention verification but are NOT a bot wall: sending yourself a
+ * code is an ordinary sign-in step, and labelling it an anti-bot challenge
+ * would send the user looking for a wall that is not there.
+ */
+export const WORDING_EXCLUDE = Object.freeze([
+    /(获取|发送|重新获取|重新发送|接收)[^。！？]{0,4}(验证码|校验码|短信码)/,
+    /send (the )?(code|sms)|resend/i,
+]);
+/** The word for "captcha" itself; only counts on a {@link CAPTCHA_ROLES} node. */
+export const CAPTCHA_WORD = /captcha|验证码/i;
+/**
+ * Roles that make {@link CAPTCHA_WORD} count. A captcha input, image or button
+ * is a challenge; a link or heading named "验证码说明" is documentation, and
+ * firing on it would send the user chasing a wall that is not there.
+ */
+export const CAPTCHA_ROLES = new Set([
+    'textbox',
+    'searchbox',
+    'combobox',
+    'spinbutton',
+    'button',
+    'checkbox',
+    'radio',
+    'slider',
+    'img',
+    'image',
+    'iframe',
+    'figure',
+]);

package/lib/challenge.d.ts

@@ -1,15 +1,19 @@
 /**
- * 人机验证页识别：从快照里判断是否撞上 Cloudflare 之类的挑战页，并给出对应的提示文案。
+ * 挑战页识别与「无进展」兜底。
+ *
+ * 判定顺序 = 稳定性顺序：先读厂商自己的响应头（他们的公开 API），再看厂商控件的无障碍名，
+ * 最后才看文案。三层都不认识的时候不猜厂商，改问一个与厂商无关的问题——「这个动作之后
+ * 页面变了吗」。所以新出的验证方式没有签名也能被接住，代价只是多问用户一句。
  * @module dsh-browser-playwright-codex/challenge
  */
-import type { ChallengeMatch, ChallengeSnapshot } from './tool-types.ts';
+import type { ChallengeMatch, ChallengeNode, ChallengeSnapshot } from './tool-types.ts';
 /**
- * Detect anti-bot / human-verification challenge pages (Cloudflare
- * interstitial, Turnstile, reCAPTCHA-style) from a snapshot's title, url and
- * visible text. We do NOT try to solve them: the correct move for an agent is
- * to hand the challenge to the human who can see the open window. Returns the
- * engine name when matched, else null. Matching is conservative to avoid
- * false positives on ordinary pages.
+ * Detect an anti-bot / human-verification surface from the MAIN document
+ * response metadata, the page's accessible names and, as a last resort, its
+ * wording. We never try to solve one: the correct move for an agent is to hand
+ * it to the human who can see the open window.
+ * @param snapshot - title, url, accessible tree and (when available) the main document response.
+ * @returns the matched engine with its tier and the concrete evidence, else null.
  */
 export declare function detectChallenge(snapshot: ChallengeSnapshot): ChallengeMatch | null;
 /**
@@ -18,3 +22,59 @@ export declare function detectChallenge(snapshot: ChallengeSnapshot): ChallengeM
  * should pause and ask the user to complete it by hand, then re-snapshot.
  */
 export declare const CHALLENGE_NOTE = "[human verification] The page triggered an anti-bot challenge; it is NOT solvable by automation and must NOT be retried blindly. The browser window is open on the user's desktop \u2014 tell the user a verification appeared, wait for them to finish it (a few seconds), then call browser_snapshot again. The clearance cookie is saved to the profile automatically and keeps working for the session.";
+/**
+ * Appended after an action that left the page byte-for-byte unchanged on a page
+ * with almost nothing else to interact with. Worded as a guess, because that is
+ * what it is: it is the shape an unrecognised wall has, and the whole point of
+ * this tier is to cover the vendors we have no signature for.
+ */
+export declare const NO_PROGRESS_NOTE = "[no visible change] that action left the page identical \u2014 same URL, same title, same elements \u2014 and the page offers almost nothing else to click. This is a guess, not a diagnosis: it is what an unrecognised anti-bot wall looks like. Take one browser_snapshot to confirm; if the page still looks unchanged, stop and tell the user what you were trying to do and ask them to look at the open window, instead of retrying the same action.";
+/** A page with at most this many actionable elements counts as "nearly empty". */
+export declare const NO_PROGRESS_MAX_REFS = 3;
+/**
+ * Identity of one page state: URL, title, actionable-element count and the
+ * accessible labels. Two captures with the same fingerprint look the same to a
+ * human glancing at the window, which is exactly the question this tier asks.
+ * @param input - the slice of a snapshot the backstop compares.
+ * @returns an opaque fingerprint string.
+ */
+export declare function snapshotFingerprint(input: {
+    readonly url?: string | undefined;
+    readonly title?: string | undefined;
+    readonly refs?: number | undefined;
+    readonly nodes?: readonly ChallengeNode[] | undefined;
+}): string;
+/**
+ * The no-progress backstop: a vendor we have never seen leaves no signature, so
+ * we stop asking "which wall is this" and ask "did anything happen". Deliberately
+ * conservative — it needs an identical page AND (a nearly empty page, or a second
+ * identical result), so an ordinary click that is not meant to change anything
+ * stays quiet.
+ * @param input - whether an action just ran, the identical-capture streak, and the ref count.
+ * @returns the advisory note, or null when the page is still plausibly alive.
+ */
+export declare function detectNoProgress(input: {
+    readonly afterAction: boolean;
+    readonly unchangedStreak: number;
+    readonly refs: number;
+}): string | null;
+/**
+ * Appended when a page has nothing to click and almost nothing to read. This is
+ * the blind spot the no-progress backstop cannot cover: that tier needs an action
+ * to compare before and after, and on a page with zero actionable elements the
+ * agent has no action to take — so the emptiest, most wall-like pages used to
+ * produce no message at all. Measured 2026-10-17 on 微博's visitor gate: the model
+ * received 364 characters, all of them "URL / Title / Refs: 0 / (no visible
+ * elements)", and nothing said the page was a gate rather than an empty document.
+ */
+export declare const SILENT_PAGE_NOTE = "[nothing here] this page has no clickable elements and almost no text: it may be a gate or visitor check that resolves by itself, a page that is still loading, or a page that needs a person. Wait a moment and take one more browser_snapshot; if it still looks like this, tell the user what you were trying to open and ask them to look at the open window, instead of re-sending the same navigation.";
+/**
+ * Whether the page is a silent one: nothing to click and (almost) nothing to read.
+ * @param input - the action ref count and the accessible tree.
+ * @returns the advisory note, or null when the page has content worth reading.
+ */
+export declare function detectSilentPage(input: {
+    readonly refs: number;
+    readonly nodes?: readonly ChallengeNode[] | undefined;
+    readonly title?: string | undefined;
+}): string | null;