1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
//! The chain's core `solve` orchestration: snapshot baseline → cache
//! short-circuit (oracle-verified) → ordered solver loop with per-solver
//! timeout, overclaim/token-shape/outcome gating, pattern + telemetry
//! recording, and token-cache persistence → terminal human-fallback with
//! optional screenshot + training-corpus capture.
//!
//! Split out of `chain.rs` (Law 5). `super` here is the `chain` module, so the
//! sibling `solver::oracle` / `solver::token_shapes` modules are reached via
//! their absolute `crate::solver::…` paths; everything else (the chain's
//! struct, fields, the `oracle_for_kind` / `detected_kind_canonical_name`
//! helpers, and the prelude imports) comes from the parent via `use super::*`.
use super::*;
impl CaptchaSolverChain {
/// Run the chain. Returns the first successful `CaptchaSolveResult`,
/// or an unsolved result (optionally with a screenshot) if all strategies are exhausted.
pub async fn solve(&self, page: &Page, captcha_info: &CaptchaInfo) -> CaptchaSolveResult {
let domain = extract_domain(&captcha_info.page_url);
let captcha_type = detected_to_type(&captcha_info.kind);
let t0 = Instant::now();
// Outcome-verification baseline. Snapshot the page BEFORE any
// solver runs so we can classify whether the page actually
// advanced after the solver claims success. Two cheap BiDi
// evals; skipped entirely when verify_outcome is off.
//
// Snapshot BEFORE the cache short-circuit so cache hits also
// get verified by the oracle. Previously `cached_solution`
// returned immediately without snapshotting, so cache hits
// were trusted on the cache's word alone, a stale token
// for a captcha that's since regenerated would silently
// "succeed" without any post-state evidence.
let baseline = if self.config.verify_outcome {
Some(crate::solver::oracle::take_snapshot(page).await)
} else {
None
};
// Cache short-circuit, see [`CaptchaSolverChain::cached_solution`] for
// the standalone path. Done here too so `solve()` is a complete
// top-level entry point.
if let Some(mut hit) = self.cached_solution(captcha_info) {
hit.time_ms = t0.elapsed().as_millis() as u64;
// Verify the cached result against fresh page state when
// verify_outcome is on. A stale cache that no longer
// matches the page (e.g. token expired, widget recycled)
// gets downgraded here instead of being trusted blindly.
if let Some(before) = &baseline {
let after = crate::solver::oracle::take_snapshot(page).await;
let outcome = crate::solver::oracle::classify(before, &after);
hit.verified_outcome = Some(outcome);
let is_verified = matches!(
outcome,
crate::solver::oracle::OutcomeClassification::Advanced
) || (self.config.allow_unknown_outcome
&& matches!(
outcome,
crate::solver::oracle::OutcomeClassification::Unknown
));
if !is_verified {
warn!(
outcome = ?outcome,
"token cache hit but oracle disagrees, not trusting cache"
);
hit.success = false;
// Fall through to the real solver chain below
// instead of returning the failed cache row.
} else {
return hit;
}
} else {
return hit;
}
}
// Re-order solvers so the historically-best method for this domain runs first.
let ordered = self.ordered_solvers(&domain, &captcha_type, &captcha_info.kind);
for solver in &ordered {
info!(solver = solver.name(), "attempting captcha solve");
let timeout = Duration::from_millis(self.config.per_solver_timeout_ms);
let result = tokio::time::timeout(timeout, solver.solve(page, captcha_info)).await;
match result {
Ok(Ok(mut r)) if r.success => {
// C046/C047 / Screwdriver, refuse a success that carries no
// token BEFORE any further processing. A solver reporting
// `success: true` with an empty `solution` has nothing to show
// for the solve; downgrade it loudly rather than let a fabricated
// success flow downstream. Legitimate sentinel proofs
// ("turnstile:passive", "datadome:cookie", …) are all non-empty,
// so this only ever catches the overclaim, never a real solve.
if r.claims_success_without_token() {
warn!(
solver = solver.name(),
"solver reported success with an empty token, refusing as an overclaim (C047)"
);
r.success = false;
self.patterns.record(
&domain,
&captcha_type,
false,
r.time_ms,
r.method.clone(),
);
self.telemetry.record(&SolveEvent {
solver: solver.name(),
captcha_type: &captcha_type,
kind: &captcha_info.kind,
domain: &domain,
outcome: SolveOutcome::Failure,
time_ms: r.time_ms,
confidence: None,
method: &r.method,
});
continue;
}
// Token-shape oracle (E2 wiring): when the
// detected captcha kind has a documented token
// shape, sanity-check the solver's returned
// string against it. Decoy = clearly malformed;
// soft-failure decoy tokens (vendors return
// these to make scrapers report success then
// bounce them at validation time) get
// intercepted HERE instead of two requests
// later when the token is rejected. Suspect =
// unrecognised but plausible (keep, log).
if let Some(oracle) = oracle_for_kind(&captcha_info.kind) {
match oracle.classify(&r.solution) {
crate::solver::token_shapes::TokenShape::Decoy => {
warn!(
solver = solver.name(),
vendor = oracle.vendor(),
solution_len = r.solution.len(),
"solver claimed success but token shape is decoy. \
downgrading (likely vendor soft-failure response)"
);
r.success = false;
self.patterns.record(
&domain,
&captcha_type,
false,
r.time_ms,
r.method.clone(),
);
self.telemetry.record(&SolveEvent {
solver: solver.name(),
captcha_type: &captcha_type,
kind: &captcha_info.kind,
domain: &domain,
outcome: SolveOutcome::Failure,
time_ms: r.time_ms,
confidence: None,
method: &r.method,
});
continue;
}
crate::solver::token_shapes::TokenShape::Suspect => {
tracing::debug!(
solver = solver.name(),
vendor = oracle.vendor(),
"token shape Suspect, keeping success but flagging for re-verification"
);
}
crate::solver::token_shapes::TokenShape::Plausible => {}
}
}
// Verify outcome, the solver claims success, but
// does the page state agree? A token in hand is
// not the same as a page past the challenge.
if let Some(before) = &baseline {
let after = crate::solver::oracle::take_snapshot(page).await;
let outcome = crate::solver::oracle::classify(before, &after);
r.verified_outcome = Some(outcome);
// Strict-by-default: only Advanced verifies
// success. `Unknown` is downgraded unless the
// operator explicitly opted in via
// `allow_unknown_outcome` (for BiDi-flaky test
// environments). Previously Unknown was
// implicitly trusted, which let solver
// attempts succeed against snapshots where
// we couldn't actually verify anything.
let is_verified = matches!(
outcome,
crate::solver::oracle::OutcomeClassification::Advanced
) || (self.config.allow_unknown_outcome
&& matches!(
outcome,
crate::solver::oracle::OutcomeClassification::Unknown
));
if !is_verified {
warn!(
solver = solver.name(),
outcome = ?outcome,
"solver claimed success but oracle disagrees, downgrading to failure"
);
r.success = false;
// Fall through to the failure-path arm below
// by re-binding via a continue. We can't
// mutate the match arm, so manually drive
// the failure-path side effects here:
self.patterns.record(
&domain,
&captcha_type,
false,
r.time_ms,
r.method.clone(),
);
self.telemetry.record(&SolveEvent {
solver: solver.name(),
captcha_type: &captcha_type,
kind: &captcha_info.kind,
domain: &domain,
outcome: SolveOutcome::Failure,
time_ms: r.time_ms,
confidence: None,
method: &r.method,
});
continue;
}
}
info!(
solver = solver.name(),
confidence = r.confidence,
time_ms = r.time_ms,
verified = ?r.verified_outcome,
"captcha solved"
);
self.patterns
.record(&domain, &captcha_type, true, r.time_ms, r.method.clone());
self.telemetry.record(&SolveEvent {
solver: solver.name(),
captcha_type: &captcha_type,
kind: &captcha_info.kind,
domain: &domain,
outcome: SolveOutcome::Success,
time_ms: r.time_ms,
confidence: Some(r.confidence),
method: &r.method,
});
if let Some(cache) = &self.cache {
// Persist the cookies alongside the token so a
// future cache hit replays the same trusted
// session, without this the cache layer
// returned only the token and the next request
// immediately re-triggered the captcha.
cache.put_full(
&domain,
&captcha_type,
r.solution.clone(),
solver.name(),
cache.ttl(),
r.cookies.clone(),
);
}
return r;
}
Ok(Ok(r)) => {
warn!(solver = solver.name(), "solver returned failure result");
self.patterns.record(
&domain,
&captcha_type,
false,
r.time_ms,
r.method.clone(),
);
self.telemetry.record(&SolveEvent {
solver: solver.name(),
captcha_type: &captcha_type,
kind: &captcha_info.kind,
domain: &domain,
outcome: SolveOutcome::Failure,
time_ms: r.time_ms,
confidence: None,
method: &r.method,
});
}
Ok(Err(e)) => {
warn!(solver = solver.name(), error = %e, "solver error");
let method = solver.method();
self.telemetry.record(&SolveEvent {
solver: solver.name(),
captcha_type: &captcha_type,
kind: &captcha_info.kind,
domain: &domain,
outcome: SolveOutcome::Error,
time_ms: 0,
confidence: None,
method: &method,
});
}
Err(_) => {
warn!(solver = solver.name(), "solver timed out");
self.patterns.record(
&domain,
&captcha_type,
false,
self.config.per_solver_timeout_ms,
solver.method(),
);
let method = solver.method();
self.telemetry.record(&SolveEvent {
solver: solver.name(),
captcha_type: &captcha_type,
kind: &captcha_info.kind,
domain: &domain,
outcome: SolveOutcome::Timeout,
time_ms: self.config.per_solver_timeout_ms,
confidence: None,
method: &method,
});
}
}
}
// All solvers exhausted (optionally grab a screenshot for human review).
warn!("all captcha solvers failed, human fallback required");
let screenshot = if self.config.screenshot_on_failure {
screenshot_b64(page).await.ok()
} else {
None
};
// Adversarial-training capture (H2): when a TrainingCorpus
// is configured, persist this terminal failure as a sample
// so downstream re-training pipelines see it. Best-effort
// disk failure logs at debug, never propagates.
if let Some(corpus) = &self.training_corpus {
let sample = crate::training_corpus::TrainingSample {
solver: "(chain-terminal)".into(),
vendor: detected_kind_canonical_name(&captcha_info.kind),
detected_kind: format!("{:?}", captcha_info.kind),
url: captcha_info.page_url.clone(),
outcome: "failure".into(),
confidence: None,
time_ms: t0.elapsed().as_millis() as u64,
screenshot_b64: screenshot.clone(),
dom_snapshot: None,
verified_outcome: None,
captured_at_unix: std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.map(|d| d.as_secs() as i64)
.unwrap_or(0),
};
if let Err(e) = corpus.append(&sample) {
// Law 10: a swallowed append silently drops a real training
// sample, the ML solver then trains on a biased slice. Surface
// it loudly (the solve still continues; only telemetry is lost).
tracing::warn!(error = %e, "captchaforge: training-corpus append failed (continuing); this solve's sample was NOT recorded");
}
}
CaptchaSolveResult::unsolved(t0.elapsed().as_millis() as u64, screenshot)
}
}