feat(widevine): auto-seed CDM hint file for persistent contexts (Linux)

Sideloaded Widevine works on the first launch of a persistent context
instead of needing a manual two-launch hint-file workaround. The wrapper
writes Chromium's CDM hint file into the profile before launch when a
WidevineCdm directory is present next to the binary.

- New cloakbrowser/widevine.py and js/src/widevine.ts: resolve a sideloaded
  CDM (CLOAKBROWSER_WIDEVINE_CDM env var, else next to the binary) and seed
  the hint file. Linux only; no-op elsewhere. CLOAKBROWSER_WIDEVINE=0 disables.
- Never bundles/downloads/copies the CDM (proprietary); seeds only when the
  user-provided CDM is already present.
- Wired into launch_persistent_context[_async] and launchPersistentContext.
- README + js/README: Widevine / DRM section, env vars, FPJS tradeoff note.
- Tests: tests/test_widevine.py, js/tests/widevine.test.ts, persistent-context
  integration assertions.

js/README.md

@@ -202,6 +202,18 @@ if (newVersion) console.log(`Updated to ${newVersion}`);
 | `CLOAKBROWSER_DOWNLOAD_URL` | `cloakbrowser.dev` | Custom download URL |
 | `CLOAKBROWSER_AUTO_UPDATE` | `true` | Set to `false` to disable background update checks |
 | `CLOAKBROWSER_SKIP_CHECKSUM` | `false` | Set to `true` to skip SHA-256 verification after download |
+| `CLOAKBROWSER_WIDEVINE_CDM` | — | Path to a sideloaded `WidevineCdm` directory (overrides auto-detection next to the binary) |
+| `CLOAKBROWSER_WIDEVINE` | `1` | Set to `0` to disable automatic Widevine hint-file seeding for persistent contexts |
+
+### Widevine / DRM
+
+The binary supports Widevine, but the CDM is proprietary and can't be redistributed. Sideload it once by copying a `WidevineCdm/` directory from a real Chrome install next to the binary (full steps in [#96](https://github.com/CloakHQ/CloakBrowser/issues/96)):
+
+```bash
+cp -r /opt/google/chrome/WidevineCdm ~/.cloakbrowser/chromium-<version>/WidevineCdm
+```
+
+With the CDM in place, `launchPersistentContext()` enables Widevine on the **first** launch — the wrapper auto-seeds the CDM hint file into the profile. This plays DRM-protected video (Netflix, Spotify Web) and makes a persistent profile present as a regular Chrome install to detection services that probe for DRM/EME support. **Linux only.** A sideloaded CDM is the opt-in (no flag); set `CLOAKBROWSER_WIDEVINE_CDM` for a custom path or `CLOAKBROWSER_WIDEVINE=0` to disable. See the [main README](https://github.com/CloakHQ/CloakBrowser#widevine--drm) for details.
 
 ## Migrate From Playwright
 

js/src/playwright.ts

@@ -10,6 +10,7 @@ import { buildArgs } from "./args.js";
 import { ensureBinary } from "./download.js";
 import { resolveProxyConfig } from "./proxy.js";
 import { maybeResolveGeoip, resolveWebrtcArgs } from "./geoip.js";
+import { seedWidevineHint } from "./widevine.js";
 
 /** @internal Accept both timezone and timezoneId — either works, no warning. Exported for testing. */
 export function resolveTimezone<T extends { timezone?: string; timezoneId?: string }>(options: T): T {
@@ -227,6 +228,8 @@ export async function launchPersistentContext(
   }
   const args = buildArgs({ ...options, ...resolved, args: [...(resolvedArgs ?? []), ...proxyArgs] });
 
+  seedWidevineHint(options.userDataDir, binaryPath);
+
   // locale and timezone are set via binary flags (--lang, --fingerprint-timezone)
   // — NOT via Playwright context kwargs which use detectable CDP emulation.
   const context = await chromium.launchPersistentContext(options.userDataDir, {

js/src/puppeteer.ts

@@ -11,6 +11,7 @@ import { buildArgs } from "./args.js";
 import { ensureBinary } from "./download.js";
 import { isSocksProxy, normalizeHttpStringUrl, parseProxyUrl, reconstructHttpUrl, resolveProxyConfig, supportsHttpProxyInlineAuth } from "./proxy.js";
 import { maybeResolveGeoip, resolveWebrtcArgs } from "./geoip.js";
+import { seedWidevineHint } from "./widevine.js";
 
 /** Resolve binary path, geoip, webrtc, and build final Chrome args. */
 async function resolveArgs(options: LaunchOptions): Promise<{ binaryPath: string; args: string[] }> {
@@ -155,6 +156,8 @@ export async function launchPersistentContext(
   const { binaryPath, args } = await resolveArgs(options);
   const proxyAuth = resolveProxy(options, args);
 
+  seedWidevineHint(options.userDataDir, binaryPath);
+
   const browser = await puppeteer.default.launch({
     ...options.launchOptions,
     executablePath: binaryPath,

js/src/widevine.ts

@@ -0,0 +1,111 @@
+/**
+ * Widevine CDM hint-file seeding for persistent contexts.
+ * Mirrors Python cloakbrowser/widevine.py.
+ *
+ * CloakBrowser's binary supports Widevine but ships no CDM (proprietary, can't
+ * redistribute). Users sideload it by copying a `WidevineCdm/` directory from a
+ * real Chrome install next to the binary (see issue #96). Chromium reads a
+ * "hint file" from the user-data-dir at early startup to register the CDM, but
+ * on a fresh profile it doesn't exist yet, and Playwright disables the component
+ * updater that would write it. This seeds the hint file before launch so a
+ * sideloaded CDM works on the first run. It never bundles, downloads, or copies
+ * the CDM — only writes the hint when a user-provided CDM is already present.
+ *
+ * Linux only: Chromium's hint-file mechanism is Linux/ChromeOS-specific.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+const HINT_FILENAME = "latest-component-updated-widevine-cdm";
+
+/** True if `file` exists and is a regular file (mirrors Python's Path.is_file()). */
+function isFile(file: string): boolean {
+  try {
+    return fs.statSync(file).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/** Absolute, symlink-resolved path (mirrors Python's Path.resolve()). */
+function realPath(p: string): string {
+  try {
+    return fs.realpathSync(p);
+  } catch {
+    return path.resolve(p);
+  }
+}
+
+function seedingDisabled(): boolean {
+  const val = (process.env.CLOAKBROWSER_WIDEVINE ?? "").trim().toLowerCase();
+  return val === "0" || val === "false" || val === "off" || val === "no";
+}
+
+/**
+ * Locate a sideloaded Widevine CDM directory, or null if absent.
+ *
+ * Resolution:
+ *   - If CLOAKBROWSER_WIDEVINE_CDM is set, it is used exclusively (overrides
+ *     auto-detection). An invalid value (no `manifest.json`) skips seeding.
+ *   - Otherwise, `<dir of the chrome binary>/WidevineCdm` — where a user naturally
+ *     drops it, and where it lives for both downloaded and CLOAKBROWSER_BINARY_PATH binaries.
+ *
+ * A directory counts only if it contains `manifest.json`. The returned path is
+ * absolute and symlink-resolved (mirrors Python's Path.resolve()).
+ * @internal Exported for testing.
+ */
+export function resolveWidevineCdmDir(binaryPath: string): string | null {
+  const custom = process.env.CLOAKBROWSER_WIDEVINE_CDM;
+  // `!== undefined` (not truthiness): a present-but-empty env var is "set" and
+  // used exclusively — it resolves to an invalid path and skips seeding.
+  const cdmDir = custom !== undefined ? custom : path.join(path.dirname(binaryPath), "WidevineCdm");
+  return isFile(path.join(cdmDir, "manifest.json")) ? realPath(cdmDir) : null;
+}
+
+/**
+ * Write the Widevine CDM hint file into a persistent profile before launch.
+ * `binaryPath` is the resolved chrome executable; the CDM is looked for next to
+ * it. No-op on non-Linux, when disabled via CLOAKBROWSER_WIDEVINE, or when no
+ * sideloaded CDM is present. Never throws — a failure must not break launch.
+ */
+export function seedWidevineHint(userDataDir: string, binaryPath: string): void {
+  if (process.platform !== "linux") return;
+  if (seedingDisabled()) return;
+  // Empty userDataDir = Playwright's ephemeral profile (its own temp dir);
+  // a persistent hint can't be placed there, and "" would pollute the CWD.
+  if (!userDataDir) return;
+
+  // Everything below is best-effort and must never break the browser launch,
+  // so the whole body (resolution + write) is guarded.
+  try {
+    const cdmDir = resolveWidevineCdmDir(binaryPath);
+    if (cdmDir === null) {
+      if (process.env.CLOAKBROWSER_WIDEVINE_CDM !== undefined) {
+        console.warn(
+          "[cloakbrowser] CLOAKBROWSER_WIDEVINE_CDM is set but has no manifest.json; " +
+            "skipping Widevine hint seeding",
+        );
+      }
+      return;
+    }
+
+    const hintDir = path.join(userDataDir, "WidevineCdm");
+    fs.mkdirSync(hintDir, { recursive: true });
+    const hintFile = path.join(hintDir, HINT_FILENAME);
+    // cdmDir is already absolute/resolved.
+    const content = JSON.stringify({ Path: cdmDir });
+
+    try {
+      if (isFile(hintFile) && fs.readFileSync(hintFile, "utf-8") === content) {
+        return; // already seeded correctly
+      }
+    } catch {
+      console.warn("[cloakbrowser] Existing Widevine hint unreadable; rewriting");
+    }
+    fs.writeFileSync(hintFile, content);
+  } catch (e) {
+    // Best-effort: never break the launch, but surface the failure.
+    console.warn("[cloakbrowser] Failed to seed Widevine CDM hint file:", e);
+  }
+}

js/tests/widevine-integration.test.ts

@@ -0,0 +1,57 @@
+import { describe, it, expect, vi, afterEach, beforeEach } from "vitest";
+
+// Assert the persistent-context launchers actually invoke seedWidevineHint,
+// so accidental removal of the wiring fails CI (parity with the Python
+// test_persistent_context_seeds_widevine tests).
+
+vi.mock("../src/widevine.js", () => ({
+  seedWidevineHint: vi.fn(),
+  resolveWidevineCdmDir: vi.fn(),
+}));
+vi.mock("../src/download.js", () => ({
+  ensureBinary: vi.fn().mockResolvedValue("/fake/chrome"),
+}));
+vi.mock("../src/geoip.js", () => ({
+  resolveProxyGeo: vi.fn().mockResolvedValue({ timezone: null, locale: null }),
+  maybeResolveGeoip: vi.fn().mockResolvedValue({}),
+  resolveWebrtcArgs: vi.fn().mockImplementation((opts: any) => Promise.resolve(opts.args)),
+}));
+vi.mock("playwright-core", () => ({ chromium: { launchPersistentContext: vi.fn() } }));
+vi.mock("puppeteer-core", () => ({ default: { launch: vi.fn() } }));
+
+describe("persistent context seeds Widevine (integration)", () => {
+  beforeEach(() => {
+    delete process.env.CLOAKBROWSER_BINARY_PATH;
+  });
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("Playwright launchPersistentContext seeds with (userDataDir, binaryPath)", async () => {
+    const pw = await import("playwright-core");
+    vi.mocked(pw.chromium.launchPersistentContext).mockResolvedValue({
+      close: vi.fn(),
+      pages: () => [],
+    } as any);
+
+    const { seedWidevineHint } = await import("../src/widevine.js");
+    const { launchPersistentContext } = await import("../src/playwright.js");
+    await launchPersistentContext({ userDataDir: "/tmp/profile" });
+
+    expect(seedWidevineHint).toHaveBeenCalledWith("/tmp/profile", "/fake/chrome");
+  });
+
+  it("Puppeteer launchPersistentContext seeds with (userDataDir, binaryPath)", async () => {
+    const pptr = await import("puppeteer-core");
+    vi.mocked(pptr.default.launch).mockResolvedValue({
+      newPage: vi.fn().mockResolvedValue({ authenticate: vi.fn() }),
+      close: vi.fn(),
+    } as any);
+
+    const { seedWidevineHint } = await import("../src/widevine.js");
+    const { launchPersistentContext } = await import("../src/puppeteer.js");
+    await launchPersistentContext({ userDataDir: "/tmp/profile" });
+
+    expect(seedWidevineHint).toHaveBeenCalledWith("/tmp/profile", "/fake/chrome");
+  });
+});

js/tests/widevine.test.ts

@@ -0,0 +1,160 @@
+import { describe, it, expect, afterEach, beforeEach, vi } from "vitest";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { resolveWidevineCdmDir, seedWidevineHint } from "../src/widevine.js";
+
+const HINT = "WidevineCdm/latest-component-updated-widevine-cdm";
+const tempDirs: string[] = [];
+const origPlatform = process.platform;
+
+function tmpDir(prefix: string): string {
+  const d = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+  tempDirs.push(d);
+  return d;
+}
+
+function makeCdm(dir: string): string {
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(dir, "manifest.json"), '{"version":"4.10.3050.0"}');
+  return dir;
+}
+
+/** A fake chrome binary path inside its own dir. */
+function fakeBinary(): string {
+  const bdir = path.join(tmpDir("cloak-bin-"), "bin");
+  fs.mkdirSync(bdir, { recursive: true });
+  return path.join(bdir, "chrome");
+}
+
+function setPlatform(value: string) {
+  Object.defineProperty(process, "platform", { value, configurable: true });
+}
+
+beforeEach(() => {
+  setPlatform("linux"); // seeding is Linux-only; default to Linux in tests
+  delete process.env.CLOAKBROWSER_WIDEVINE;
+  delete process.env.CLOAKBROWSER_WIDEVINE_CDM;
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  Object.defineProperty(process, "platform", { value: origPlatform, configurable: true });
+  delete process.env.CLOAKBROWSER_WIDEVINE;
+  delete process.env.CLOAKBROWSER_WIDEVINE_CDM;
+  for (const dir of tempDirs.splice(0)) fs.rmSync(dir, { recursive: true, force: true });
+});
+
+describe("resolveWidevineCdmDir", () => {
+  it("returns env-var dir when it has manifest.json", () => {
+    const cdm = makeCdm(path.join(tmpDir("cloak-wv-"), "WidevineCdm"));
+    process.env.CLOAKBROWSER_WIDEVINE_CDM = cdm;
+    expect(resolveWidevineCdmDir(fakeBinary())).toBe(fs.realpathSync(cdm));
+  });
+
+  it("returns null when dir lacks manifest.json", () => {
+    const bogus = path.join(tmpDir("cloak-wv-"), "WidevineCdm");
+    fs.mkdirSync(bogus, { recursive: true });
+    process.env.CLOAKBROWSER_WIDEVINE_CDM = bogus;
+    expect(resolveWidevineCdmDir(fakeBinary())).toBeNull();
+  });
+
+  it("falls back to <binary dir>/WidevineCdm", () => {
+    const binary = fakeBinary();
+    expect(resolveWidevineCdmDir(binary)).toBeNull(); // no CDM yet
+    const cdm = makeCdm(path.join(path.dirname(binary), "WidevineCdm"));
+    expect(resolveWidevineCdmDir(binary)).toBe(fs.realpathSync(cdm));
+  });
+
+  it("env var is exclusive — invalid env skips, no fallback to binary dir", () => {
+    const binary = fakeBinary();
+    makeCdm(path.join(path.dirname(binary), "WidevineCdm")); // valid CDM next to binary
+    const bogus = path.join(tmpDir("cloak-wv-"), "bogus");
+    fs.mkdirSync(bogus, { recursive: true }); // set but no manifest.json
+    process.env.CLOAKBROWSER_WIDEVINE_CDM = bogus;
+    expect(resolveWidevineCdmDir(binary)).toBeNull();
+  });
+
+  it("empty env var is exclusive — no fallback to binary dir", () => {
+    const binary = fakeBinary();
+    makeCdm(path.join(path.dirname(binary), "WidevineCdm")); // valid CDM next to binary
+    process.env.CLOAKBROWSER_WIDEVINE_CDM = ""; // set but empty
+    expect(resolveWidevineCdmDir(binary)).toBeNull();
+  });
+});
+
+describe("seedWidevineHint", () => {
+  it("writes the hint file with the absolute CDM path", () => {
+    const cdm = makeCdm(path.join(tmpDir("cloak-wv-"), "WidevineCdm"));
+    process.env.CLOAKBROWSER_WIDEVINE_CDM = cdm;
+    const profile = tmpDir("cloak-prof-");
+
+    seedWidevineHint(profile, fakeBinary());
+
+    const hint = path.join(profile, HINT);
+    expect(fs.existsSync(hint)).toBe(true);
+    expect(JSON.parse(fs.readFileSync(hint, "utf-8")).Path).toBe(fs.realpathSync(cdm));
+  });
+
+  it("no-ops when no CDM present", () => {
+    const profile = tmpDir("cloak-prof-");
+    seedWidevineHint(profile, fakeBinary());
+    expect(fs.existsSync(path.join(profile, HINT))).toBe(false);
+  });
+
+  it("kill switch CLOAKBROWSER_WIDEVINE=0 disables seeding", () => {
+    const cdm = makeCdm(path.join(tmpDir("cloak-wv-"), "WidevineCdm"));
+    process.env.CLOAKBROWSER_WIDEVINE_CDM = cdm;
+    process.env.CLOAKBROWSER_WIDEVINE = "0";
+    const profile = tmpDir("cloak-prof-");
+    seedWidevineHint(profile, fakeBinary());
+    expect(fs.existsSync(path.join(profile, HINT))).toBe(false);
+  });
+
+  it("is idempotent", () => {
+    const cdm = makeCdm(path.join(tmpDir("cloak-wv-"), "WidevineCdm"));
+    process.env.CLOAKBROWSER_WIDEVINE_CDM = cdm;
+    const profile = tmpDir("cloak-prof-");
+    seedWidevineHint(profile, fakeBinary());
+    seedWidevineHint(profile, fakeBinary());
+    expect(JSON.parse(fs.readFileSync(path.join(profile, HINT), "utf-8")).Path).toBe(
+      fs.realpathSync(cdm),
+    );
+  });
+
+  it("no-ops on non-Linux", () => {
+    setPlatform("win32");
+    const cdm = makeCdm(path.join(tmpDir("cloak-wv-"), "WidevineCdm"));
+    process.env.CLOAKBROWSER_WIDEVINE_CDM = cdm;
+    const profile = tmpDir("cloak-prof-");
+    seedWidevineHint(profile, fakeBinary());
+    expect(fs.existsSync(path.join(profile, HINT))).toBe(false);
+  });
+
+  it("skips empty userDataDir (no CWD pollution)", () => {
+    const cdm = makeCdm(path.join(tmpDir("cloak-wv-"), "WidevineCdm"));
+    process.env.CLOAKBROWSER_WIDEVINE_CDM = cdm;
+    seedWidevineHint("", fakeBinary());
+    expect(fs.existsSync(path.join(process.cwd(), "WidevineCdm"))).toBe(false);
+  });
+
+  it("never throws on write failure", () => {
+    const cdm = makeCdm(path.join(tmpDir("cloak-wv-"), "WidevineCdm"));
+    process.env.CLOAKBROWSER_WIDEVINE_CDM = cdm;
+    const profile = tmpDir("cloak-prof-");
+    // Block mkdir of <profile>/WidevineCdm by occupying that path with a file.
+    fs.writeFileSync(path.join(profile, "WidevineCdm"), "not a dir");
+    expect(() => seedWidevineHint(profile, fakeBinary())).not.toThrow();
+  });
+
+  it("rewrites a mismatched existing hint", () => {
+    const cdm = makeCdm(path.join(tmpDir("cloak-wv-"), "WidevineCdm"));
+    process.env.CLOAKBROWSER_WIDEVINE_CDM = cdm;
+    const profile = tmpDir("cloak-prof-");
+    const hint = path.join(profile, HINT);
+    fs.mkdirSync(path.dirname(hint), { recursive: true });
+    fs.writeFileSync(hint, '{"Path":"/stale/path"}');
+    seedWidevineHint(profile, fakeBinary());
+    expect(JSON.parse(fs.readFileSync(hint, "utf-8")).Path).toBe(fs.realpathSync(cdm));
+  });
+});