feat: add macOS platform support, GPG-signed release workflow

- Native macOS fingerprint config (platform=macos, skip GPU/concurrency spoofing)
- Enable darwin-arm64 and darwin-x64 in AVAILABLE_PLATFORMS (Python + JS)
- Update release workflow: multi-platform title, patch count, GPG key reference
- Update platform tables in both READMEs: macOS Intel now available
- Fix stealth test timeouts

.github/workflows/release-binary.yml

@@ -6,10 +6,14 @@ on:
       tag:
         description: 'Release tag (e.g. chromium-v145.0.7718.0)'
         required: true
-      platform:
-        description: 'Platform label (e.g. Linux x64)'
+      title:
+        description: 'Release title (e.g. Chromium v145 — Stealth Build)'
         required: true
-        default: 'Linux x64'
+        default: 'Stealth Chromium Build'
+      patch_count:
+        description: 'Number of fingerprint patches'
+        required: true
+        default: '16'
 
 jobs:
   release:
@@ -23,11 +27,11 @@ jobs:
         uses: softprops/action-gh-release@v2
         with:
           tag_name: ${{ github.event.inputs.tag }}
-          name: "${{ github.event.inputs.platform }} — ${{ github.event.inputs.tag }}"
+          name: "${{ github.event.inputs.title }}"
           body: |
             ## Stealth Chromium Build
 
-            Pre-built Chromium with 16 source-level fingerprint patches.
+            Pre-built Chromium with ${{ github.event.inputs.patch_count }} source-level fingerprint patches.
 
             ### Install
             ```bash
@@ -36,5 +40,6 @@ jobs:
             # Binary auto-downloads on first launch
             ```
 
-            ### Platforms
-            - ${{ github.event.inputs.platform }}
+            > Checksums and platform list will be added after binary uploads.
+            >
+            > Release signed with CloakHQ GPG key: `C60C0DDC9D0DE2DD`

README.md

@@ -292,15 +292,17 @@ Every launch automatically generates a **unique fingerprint**. A random seed (10
 
 ### Default Fingerprint
 
-Every `launch()` call sets these automatically:
+Every `launch()` call sets these automatically. Defaults are **platform-aware** — macOS runs as a native Mac browser, Linux spoofs Windows:
 
-| Flag | Default | Controls |
-|------|---------|----------|
-| `--fingerprint` | Random (10000–99999) | Master seed for canvas, WebGL, audio, fonts, client rects |
-| `--fingerprint-platform` | `windows` | `navigator.platform`, User-Agent OS |
-| `--fingerprint-hardware-concurrency` | `8` | `navigator.hardwareConcurrency` |
-| `--fingerprint-gpu-vendor` | `NVIDIA Corporation` | WebGL `UNMASKED_VENDOR_WEBGL` |
-| `--fingerprint-gpu-renderer` | `NVIDIA GeForce RTX 3070` | WebGL `UNMASKED_RENDERER_WEBGL` |
+| Flag | Linux Default | macOS Default | Controls |
+|------|--------------|---------------|----------|
+| `--fingerprint` | Random (10000–99999) | Random (10000–99999) | Master seed for canvas, WebGL, audio, fonts, client rects |
+| `--fingerprint-platform` | `windows` | `macos` | `navigator.platform`, User-Agent OS, GPU pool selection |
+| `--fingerprint-hardware-concurrency` | `8` | *(not set — uses real value)* | `navigator.hardwareConcurrency` |
+| `--fingerprint-gpu-vendor` | `NVIDIA Corporation` | *(not set — native Apple GPU)* | WebGL `UNMASKED_VENDOR_WEBGL` |
+| `--fingerprint-gpu-renderer` | `NVIDIA GeForce RTX 3070` | *(not set — native Metal renderer)* | WebGL `UNMASKED_RENDERER_WEBGL` |
+
+> **Important:** `--fingerprint-platform` must always be set. The binary defaults to `windows` internally when this flag is missing, which causes GPU/UA mismatches on non-Windows systems. The wrapper handles this automatically.
 
 ### Additional Flags
 
@@ -385,16 +387,14 @@ page.goto("https://example.com")
 
 ## Platforms
 
-> **CloakBrowser is in active development.** Pre-built binaries are currently Linux-only. macOS and Windows builds are coming soon.
-
 | Platform | Status |
 |---|---|
 | Linux x86_64 | ✅ Available |
-| macOS arm64 (Apple Silicon) | Coming soon |
-| macOS x86_64 (Intel) | Coming soon |
+| macOS arm64 (Apple Silicon) | ✅ Available |
+| macOS x86_64 (Intel) | ✅ Available |
 | Windows | Planned |
 
-**On macOS/Windows?** You can still use CloakBrowser via Docker or with your own Chromium binary by setting `CLOAKBROWSER_BINARY_PATH=/path/to/chrome`.
+**On Windows?** You can still use CloakBrowser via Docker or with your own Chromium binary by setting `CLOAKBROWSER_BINARY_PATH=/path/to/chrome`.
 
 ## Examples
 
@@ -413,14 +413,15 @@ page.goto("https://example.com")
 | Feature | Status |
 |---------|--------|
 | Linux x64 binary | ✅ Released |
-| macOS arm64 (Apple Silicon) | 🔜 In progress |
+| macOS arm64 (Apple Silicon) | ✅ Released |
+| macOS x64 (Intel) | ✅ Released |
 | Chromium 145 build | 🔜 In progress |
 | JavaScript/Puppeteer + Playwright support | ✅ Released |
 | Fingerprint rotation per session | ✅ Released |
 | Built-in proxy rotation | 📋 Planned |
 | Windows support | 📋 Planned |
 
-> ⭐ **Star this repo** to get notified when Chromium 145 and macOS builds drop.
+> ⭐ **Star this repo** to get notified when Chromium 145 and Windows builds drop.
 
 ## Docker
 

cloakbrowser/config.py

@@ -19,12 +19,28 @@ CHROMIUM_VERSION = "142.0.7444.175"
 # These activate source-level fingerprint patches compiled into the binary.
 # ---------------------------------------------------------------------------
 def get_default_stealth_args() -> list[str]:
-    """Build stealth args with a random fingerprint seed per launch."""
+    """Build stealth args with a random fingerprint seed per launch.
+
+    On macOS, skips platform/GPU spoofing — runs as a native Mac browser.
+    Spoofing Windows on Mac creates detectable mismatches (fonts, GPU, etc.).
+    """
     seed = random.randint(10000, 99999)
-    return [
+    system = platform.system()
+
+    base = [
         "--no-sandbox",
         "--disable-blink-features=AutomationControlled",
         f"--fingerprint={seed}",
+    ]
+
+    if system == "Darwin":
+        # Tell the fingerprint patches we're on macOS so GPU/UA match natively
+        return base + [
+            "--fingerprint-platform=macos",
+        ]
+
+    # Linux: spoof as Windows
+    return base + [
         "--fingerprint-platform=windows",
         "--fingerprint-hardware-concurrency=8",
         "--fingerprint-gpu-vendor=NVIDIA Corporation",
@@ -43,7 +59,7 @@ SUPPORTED_PLATFORMS: dict[tuple[str, str], str] = {
 
 # Platforms with pre-built binaries available for download.
 # Update this set as new platform builds are released.
-AVAILABLE_PLATFORMS: set[str] = {"linux-x64"}
+AVAILABLE_PLATFORMS: set[str] = {"linux-x64", "darwin-arm64", "darwin-x64"}
 
 
 def get_platform_tag() -> str:
@@ -106,8 +122,8 @@ def check_platform_available() -> None:
         import sys
         sys.exit(
             f"\n\033[1mCloakBrowser\033[0m — Pre-built binaries are currently only available for: {available}.\n"
-            f"macOS and Windows builds are coming soon.\n\n"
-            f"To use CloakBrowser now, run in Docker (see README)."
+            f"Windows builds are coming soon.\n\n"
+            f"To use CloakBrowser now, run in Docker (see README) or set CLOAKBROWSER_BINARY_PATH."
         )
 
 

examples/stealth_test.py

@@ -119,8 +119,8 @@ def test_deviceandbrowserinfo(page):
 
 def test_fingerprintjs(page):
     """demo.fingerprint.com/web-scraping — industry-standard bot detection."""
-    page.goto("https://demo.fingerprint.com/web-scraping", wait_until="networkidle", timeout=30000)
-    page.wait_for_timeout(5000)
+    page.goto("https://demo.fingerprint.com/web-scraping", wait_until="domcontentloaded", timeout=30000)
+    page.wait_for_timeout(8000)
 
     # Click search to trigger bot detection — bots get blocked, humans see flights
     try:

js/README.md

@@ -137,16 +137,14 @@ const page = await browser.newPage();
 
 ## Platforms
 
-> **CloakBrowser is in active development.** Pre-built binaries are currently Linux-only. macOS and Windows builds are coming soon.
-
 | Platform | Status |
 |---|---|
 | Linux x86_64 | ✅ Available |
-| macOS arm64 (Apple Silicon) | Coming soon |
-| macOS x86_64 (Intel) | Coming soon |
+| macOS arm64 (Apple Silicon) | ✅ Available |
+| macOS x86_64 (Intel) | ✅ Available |
 | Windows | Planned |
 
-**On macOS/Windows?** You can still use CloakBrowser via Docker or with your own Chromium binary by setting `CLOAKBROWSER_BINARY_PATH=/path/to/chrome`.
+**On Windows?** You can still use CloakBrowser via Docker or with your own Chromium binary by setting `CLOAKBROWSER_BINARY_PATH=/path/to/chrome`.
 
 ## Requirements
 

js/src/config.ts

@@ -24,7 +24,7 @@ const SUPPORTED_PLATFORMS: Record<string, string> = {
 
 // Platforms with pre-built binaries available for download.
 // Update this set as new platform builds are released.
-const AVAILABLE_PLATFORMS = new Set(["linux-x64"]);
+const AVAILABLE_PLATFORMS = new Set(["linux-x64", "darwin-arm64", "darwin-x64"]);
 
 export function getPlatformTag(): string {
   const platform = process.platform;
@@ -74,10 +74,9 @@ export function checkPlatformAvailable(): void {
   if (!AVAILABLE_PLATFORMS.has(tag)) {
     const available = [...AVAILABLE_PLATFORMS].sort().join(", ");
     throw new Error(
-      `CloakBrowser is in active development. ` +
-        `Pre-built binaries are currently only available for: ${available}.\n` +
-        `macOS and Windows builds are coming soon.\n\n` +
-        `To use CloakBrowser now, run in Docker (see README).`
+      `CloakBrowser — Pre-built binaries are currently only available for: ${available}.\n` +
+        `Windows builds are coming soon.\n\n` +
+        `To use CloakBrowser now, run in Docker (see README) or set CLOAKBROWSER_BINARY_PATH.`
     );
   }
 }
@@ -142,10 +141,22 @@ export function getLocalBinaryOverride(): string | undefined {
 // ---------------------------------------------------------------------------
 export function getDefaultStealthArgs(): string[] {
   const seed = Math.floor(Math.random() * 90000) + 10000; // 10000-99999
-  return [
+  const isMac = process.platform === "darwin";
+
+  const base = [
     "--no-sandbox",
     "--disable-blink-features=AutomationControlled",
     `--fingerprint=${seed}`,
+  ];
+
+  if (isMac) {
+    // macOS: run as native Mac browser — GPU/UA match natively
+    return [...base, "--fingerprint-platform=macos"];
+  }
+
+  // Linux: spoof as Windows
+  return [
+    ...base,
     "--fingerprint-platform=windows",
     "--fingerprint-hardware-concurrency=8",
     "--fingerprint-gpu-vendor=NVIDIA Corporation",