warterbili/auto_reverse/castle-reverse

Castle.io Reverse-Engineering Skill

Castle.io is a device-fingerprint / anti-bot SDK. The client SDK emits a per-request header `X-Castle-Request-Token` (+ a stable `x-castle-client-id` / `__cuid`), which the protected backend forwards to Castle's Risk API for scoring.

Two SDK families, same token container, different fingerprint payload + crypto:

When to trigger

A target (app or site) sends X-Castle-Request-Token, loads castle.browser*.js, calls Castle.createRequestToken(), or bundles io.castle.android. You need to read, decode, or reproduce the token.

Assets

• tools/gen_v311.py — full Android v3.1.1 token generator (device fields → token). python gen_v311.py verify runs the byte-exact self-tests.
• tools/decode_v311.py — Android v3.1.1 token decoder (recovers pk / version / cuid / timestamp / fingerprint; peels the 3 XOR layers).
• source-castleio-gen/ — archived open-source web v11 reimpl (yubie-re/castleio-gen): GenerateToken/DecodeToken/TEA(xxtea)/CastleEncoding/CastleFP*. Reference baseline + the web algorithm.
• scripts/hook_castle.js — frida: hook Castle.createRequestToken / u.g() / f.a() / d.c() to capture a real token + intermediate fingerprint.
• scripts/hook_capture_one.js — frida: dump ONE complete u.g() call (pk/uuid/fp_main/b_part/motion/token) as JSON for byte-exact verification.
• scripts/hook_flow_all.js — frida: log every OkHttp request + which carry the Castle header + status (find the allowlisted endpoints).
• references/algorithm-v3.1.1-android.md — the full reversed Android algorithm (entry chain, primitives, token layout, 24-field f.a() + 14-field r.a() maps).
• references/opensource-vs-v311.md — web-v11 vs android-v3.1.1 diff (what carried over, what changed).

Workflow (Android)

1. Locate: jadx the APK → io.castle.android.Castle.createRequestToken() → Highwind.token() → u.g(); the engine is io.castle.highwind.android (obfuscated single-letter classes). Read references/algorithm-v3.1.1-android.md.
2. Capture: frida scripts/hook_castle.js (token + fp) and hook_capture_one.js (one full call as JSON).
3. Decode: decode_v311.py <token_file> → recovers pk / version / cuid / fp. (The open-source web decoder will FAIL on v3.1.1 — it expects XXTEA.)
4. Generate: gen_v311.py builds a token from device fields; verify proves it reproduces a real token byte-for-byte and round-trips through the decoder.
5. Version-drift check: confirm io.castle.android.BuildConfig.VERSION_NAME. If ≠ 3.1.1, re-diff u.g() and the f.a() field list — Castle changes the fingerprint fields and occasionally the container across versions (this is exactly why the open-source v11 reverse is outdated).

Workflow (Web)

castle.browser.js calls Castle.createRequestToken() in JS. Use cdp-browser to capture the token + hook the SDK; the algorithm (token v11) is in source-castleio-gen/. For a clean, accepted token, Castle's web SDK reads browser fingerprints + behavior, so an anti-detect browser (nodriver / cdp-browser) + residential IP + human-like behavior is the practical path — or generate the token directly from the v11 algorithm with a coherent fingerprint.

Gotchas (learned on the DailyPay case — see cases/dailypay-castleio-android)

• v3.1.1 dropped XXTEA entirely. SBA fields are plaintext UTF-8; the whole-token TEA wrap is gone. The open-source DecodeToken will mis-parse a v3.1.1 token at the xxtea step (post-XOR leading byte is 0x0a, not v11's 0x0b).
• Android replaces web mouse/touch datapoints with real device motion sensors (d.c(): accel/gyro/magnetic/rotation/gravity/user-accel). Stationary device → zeros.
• The token is assembled as a HEX STRING (each byte = 2 hex chars), y.c() = hex→bytes at the very end, then base64url flag 11 (URL_SAFE|NO_PAD|NO_WRAP).
• pk is `pk_`+32 chars (len 35), embedded as pk.substring(3) inside the token — you can recover it by decoding.
• The header is allowlist-gated (Castle.isUrlAllowlisted / baseURLAllowList): the token only attaches to specific backend URLs, which often fire only after login. Use hook_flow_all.js to find them.
• Token validity ~120s; regenerate per request.
• The token being accepted server-side also depends on non-Castle gates (CDN/edge IP & policy filters, business eligibility) that sit in front of Castle — don't attribute a request rejection to Castle without capturing the response (the DailyPay case's signup 403 was a CloudFront Lambda@Edge gate, not Castle).