cloakbrowser 0.1.0 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +153 -0
  2. package/package.json +1 -1
package/README.md ADDED
@@ -0,0 +1,153 @@
1
+ <p align="center">
2
+ <img src="https://raw.githubusercontent.com/CloakHQ/CloakBrowser/main/images/logo.png" width="500" alt="CloakBrowser">
3
+ </p>
4
+
5
+ # CloakBrowser
6
+
7
+ [![npm](https://img.shields.io/npm/v/cloakbrowser)](https://www.npmjs.com/package/cloakbrowser)
8
+ [![License](https://img.shields.io/github/license/CloakHQ/CloakBrowser)](https://github.com/CloakHQ/CloakBrowser/blob/main/LICENSE)
9
+
10
+ **Stealth Chromium that passes every bot detection test.**
11
+
12
+ Drop-in Playwright/Puppeteer replacement. Same API — just swap the import. Scores **0.9 on reCAPTCHA v3**, passes **Cloudflare Turnstile**, and clears **14/14** stealth detection tests.
13
+
14
+ - 🔒 **16 source-level C++ patches** — not JS injection, not config flags
15
+ - 🎯 **0.9 reCAPTCHA v3 score** — human-level, server-verified
16
+ - ☁️ **Passes Cloudflare Turnstile**, FingerprintJS, BrowserScan — 14/14 tests
17
+ - 🔄 **Drop-in replacement** — works with both Playwright and Puppeteer
18
+ - 📦 **`npm install cloakbrowser`** — binary auto-downloads, zero config
19
+
20
+ ## Install
21
+
22
+ ```bash
23
+ # With Playwright
24
+ npm install cloakbrowser playwright-core
25
+
26
+ # With Puppeteer
27
+ npm install cloakbrowser puppeteer-core
28
+ ```
29
+
30
+ On first launch, the stealth Chromium binary auto-downloads (~200MB, cached at `~/.cloakbrowser/`).
31
+
32
+ ## Usage
33
+
34
+ ### Playwright (default)
35
+
36
+ ```javascript
37
+ import { launch } from 'cloakbrowser';
38
+
39
+ const browser = await launch();
40
+ const page = await browser.newPage();
41
+ await page.goto('https://protected-site.com');
42
+ console.log(await page.title());
43
+ await browser.close();
44
+ ```
45
+
46
+ ### Puppeteer
47
+
48
+ ```javascript
49
+ import { launch } from 'cloakbrowser/puppeteer';
50
+
51
+ const browser = await launch();
52
+ const page = await browser.newPage();
53
+ await page.goto('https://protected-site.com');
54
+ console.log(await page.title());
55
+ await browser.close();
56
+ ```
57
+
58
+ ### Options
59
+
60
+ ```javascript
61
+ import { launch, launchContext } from 'cloakbrowser';
62
+
63
+ // With proxy
64
+ const browser = await launch({
65
+ proxy: 'http://user:pass@proxy:8080',
66
+ });
67
+
68
+ // Headed mode (visible browser window)
69
+ const browser = await launch({ headless: false });
70
+
71
+ // Extra Chrome args
72
+ const browser = await launch({
73
+ args: ['--window-size=1920,1080'],
74
+ });
75
+
76
+ // Browser + context in one call
77
+ const context = await launchContext({
78
+ userAgent: 'Custom UA',
79
+ viewport: { width: 1920, height: 1080 },
80
+ locale: 'en-US',
81
+ timezoneId: 'America/New_York',
82
+ });
83
+ ```
84
+
85
+ ### Utilities
86
+
87
+ ```javascript
88
+ import { ensureBinary, clearCache, binaryInfo } from 'cloakbrowser';
89
+
90
+ // Pre-download binary (e.g., during Docker build)
91
+ await ensureBinary();
92
+
93
+ // Check installation
94
+ console.log(binaryInfo());
95
+
96
+ // Force re-download
97
+ clearCache();
98
+ ```
99
+
100
+ ## Test Results
101
+
102
+ | Detection Service | Stock Browser | CloakBrowser |
103
+ |---|---|---|
104
+ | **reCAPTCHA v3** | 0.1 (bot) | **0.9** (human) |
105
+ | **Cloudflare Turnstile** | FAIL | **PASS** |
106
+ | **FingerprintJS** | DETECTED | **PASS** |
107
+ | **BrowserScan** | DETECTED | **NORMAL** (4/4) |
108
+ | **bot.incolumitas.com** | 13 fails | **1 fail** |
109
+ | `navigator.webdriver` | `true` | **`false`** |
110
+
111
+ ## Configuration
112
+
113
+ | Env Variable | Default | Description |
114
+ |---|---|---|
115
+ | `CLOAKBROWSER_BINARY_PATH` | — | Skip download, use a local Chromium binary |
116
+ | `CLOAKBROWSER_CACHE_DIR` | `~/.cloakbrowser` | Binary cache directory |
117
+ | `CLOAKBROWSER_DOWNLOAD_URL` | GitHub Releases | Custom download URL |
118
+
119
+ ## Migrate From Playwright
120
+
121
+ ```diff
122
+ - import { chromium } from 'playwright';
123
+ - const browser = await chromium.launch();
124
+ + import { launch } from 'cloakbrowser';
125
+ + const browser = await launch();
126
+
127
+ const page = await browser.newPage();
128
+ // ... rest of your code works unchanged
129
+ ```
130
+
131
+ ## Platforms
132
+
133
+ | Platform | Status |
134
+ |---|---|
135
+ | Linux x86_64 | ✅ Supported |
136
+ | macOS arm64 (Apple Silicon) | Coming soon |
137
+ | macOS x86_64 (Intel) | Coming soon |
138
+ | Windows | Planned |
139
+
140
+ ## Requirements
141
+
142
+ - Node.js >= 18
143
+ - One of: `playwright-core` >= 1.40 or `puppeteer-core` >= 21
144
+
145
+ ## License
146
+
147
+ MIT — see [LICENSE](https://github.com/CloakHQ/CloakBrowser/blob/main/LICENSE).
148
+
149
+ ## Links
150
+
151
+ - [GitHub](https://github.com/CloakHQ/CloakBrowser)
152
+ - [PyPI (Python package)](https://pypi.org/project/cloakbrowser/)
153
+ - [Full documentation](https://github.com/CloakHQ/CloakBrowser#readme)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "cloakbrowser",
3
- "version": "0.1.0",
3
+ "version": "0.1.2",
4
4
  "description": "Stealth Chromium that passes every bot detection test. Drop-in Playwright/Puppeteer replacement with source-level fingerprint patches.",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",