@koloss777/nokk 0.1.21-alpha

package/README.md

@@ -0,0 +1,79 @@
+# nokk
+
+**Undetectable headless-browser engine, one `npm install` away.**
+
+`nokk` is a lightweight, Chrome-fingerprinted headless-browser engine (V8 + a
+minimal DOM, no rendering) that speaks the Chrome DevTools Protocol. Install it,
+call `launch()`, and connect your existing **Puppeteer** or **Playwright** script
+over CDP — no Chromium download.
+
+```bash
+npm install @koloss777/nokk
+```
+
+> **Alpha:** the prebuilt binary is fetched on install and is currently **Linux
+> x64** only. macOS/Windows are on the roadmap.
+
+## Puppeteer
+
+```js
+const nokk = require("@koloss777/nokk");
+const puppeteer = require("puppeteer");
+
+(async () => {
+  const server = await nokk.launch({ rotateFingerprint: true });
+  const browser = await puppeteer.connect({ browserWSEndpoint: server.wsEndpoint });
+  const page = await browser.newPage();
+  await page.goto("https://example.com");
+  console.log(await page.title());
+  await browser.close();
+  await server.close();
+})();
+```
+
+## Playwright
+
+```js
+const nokk = require("@koloss777/nokk");
+const { chromium } = require("playwright");
+
+(async () => {
+  const server = await nokk.launch();
+  const browser = await chromium.connectOverCDP(server.wsEndpoint);
+  const page = await browser.newPage();
+  await page.goto("https://example.com");
+  console.log(await page.title());
+  await browser.close();
+  await server.close();
+})();
+```
+
+## `launch(options)`
+
+Starts the CDP server on a free port and resolves to a `NokkServer`. Options
+(all optional): `host`, `port`, `workers`, `maxContexts`, `proxy`,
+`sessionStore`, `rotateFingerprint`, `geoipTimezone`, `allowTrackers`,
+`chromeVersion`, `args`, `env`, `timeout`.
+
+```js
+// Each browser context looks like a different machine, timezone matched to its proxy:
+const server = await nokk.launch({ rotateFingerprint: true, geoipTimezone: true });
+```
+
+`server.wsEndpoint` → hand to `puppeteer.connect` / `chromium.connectOverCDP`.
+`server.close()` stops it; it's also killed when the Node process exits.
+
+## CLI
+
+```bash
+npx @koloss777/nokk --port 9222 --workers 4      # run the CDP server directly
+```
+
+Point at a locally built binary during development with the `NOKK_BINARY`
+environment variable.
+
+## Links
+
+- Source & docs: <https://github.com/koloss777/nokk>
+
+Licensed under MIT OR Apache-2.0.

package/bin/nokk.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+// `npx nokk …` / the `nokk` bin — run the embedded binary, passing through args
+// (e.g. `nokk --port 9222` starts the CDP server).
+"use strict";
+
+const { spawn } = require("child_process");
+const { binaryPath } = require("../index.js");
+
+let bin;
+try {
+  bin = binaryPath();
+} catch (e) {
+  console.error("[nokk] " + e.message);
+  process.exit(1);
+}
+
+const child = spawn(bin, process.argv.slice(2), { stdio: "inherit" });
+child.on("exit", (code, signal) => {
+  if (signal) process.kill(process.pid, signal);
+  else process.exit(code == null ? 1 : code);
+});

package/index.d.ts

@@ -0,0 +1,47 @@
+export interface LaunchOptions {
+  /** Address to bind (default "127.0.0.1"). */
+  host?: string;
+  /** TCP port; 0 (default) picks a free one. */
+  port?: number;
+  /** Isolate worker threads. */
+  workers?: number;
+  /** Cap on concurrent live contexts before backpressure. */
+  maxContexts?: number;
+  /** Upstream proxy, e.g. "socks5://host:1080" or "http://user:pass@host:port". */
+  proxy?: string;
+  /** Directory for persistent named-session cookie jars. */
+  sessionStore?: string;
+  /** Give each browser context its own coherent fingerprint. */
+  rotateFingerprint?: boolean;
+  /** Derive each context's timezone/locale from its proxy's exit IP. */
+  geoipTimezone?: boolean;
+  /** Load ad/analytics/tracker subresources (blocked by default). */
+  allowTrackers?: boolean;
+  /** Chrome major version to emulate (TLS + JS together), e.g. 148. */
+  chromeVersion?: number;
+  /** Extra raw CLI arguments passed to the binary. */
+  args?: string[];
+  /** Extra environment variables for the server process. */
+  env?: Record<string, string>;
+  /** stdio option for the child process (default "inherit"). */
+  stdio?: any;
+  /** Milliseconds to wait for the server to become ready (default 30000). */
+  timeout?: number;
+}
+
+export declare class NokkServer {
+  readonly host: string;
+  readonly port: number;
+  /** browserWSEndpoint for puppeteer.connect / chromium.connectOverCDP. */
+  readonly wsEndpoint: string;
+  readonly httpEndpoint: string;
+  readonly pid: number;
+  /** Stop the server. Idempotent. */
+  close(): Promise<void>;
+}
+
+/** Start a nokk CDP server and resolve to a NokkServer. */
+export declare function launch(options?: LaunchOptions): Promise<NokkServer>;
+
+/** Absolute path to the bundled `nokk` binary (override with NOKK_BINARY). */
+export declare function binaryPath(): string;

package/index.js

@@ -0,0 +1,157 @@
+// nokk — launch the undetectable browser-engine CDP server and connect to it.
+//
+//   const nokk = require("nokk");
+//   const puppeteer = require("puppeteer");
+//   const server = await nokk.launch({ rotateFingerprint: true });
+//   const browser = await puppeteer.connect({ browserWSEndpoint: server.wsEndpoint });
+//   ...
+//   await server.close();
+"use strict";
+
+const { spawn } = require("child_process");
+const http = require("http");
+const net = require("net");
+const fs = require("fs");
+const path = require("path");
+
+const EXE = process.platform === "win32" ? "nokk.exe" : "nokk";
+const BUNDLED = path.join(__dirname, "vendor", EXE);
+
+/** Absolute path to the bundled `nokk` binary (override with NOKK_BINARY). */
+function binaryPath() {
+  const override = process.env.NOKK_BINARY;
+  if (override) {
+    if (fs.existsSync(override)) return override;
+    throw new Error(`NOKK_BINARY points at a missing file: ${override}`);
+  }
+  if (fs.existsSync(BUNDLED)) return BUNDLED;
+  throw new Error(
+    "the bundled `nokk` binary was not found — reinstall (`npm install nokk`). " +
+      "Prebuilt binaries are currently Linux x64 only."
+  );
+}
+
+function freePort(host) {
+  return new Promise((resolve, reject) => {
+    const s = net.createServer();
+    s.once("error", reject);
+    s.listen(0, host, () => {
+      const { port } = s.address();
+      s.close(() => resolve(port));
+    });
+  });
+}
+
+function ready(host, port) {
+  return new Promise((resolve) => {
+    const req = http.get(`http://${host}:${port}/json/version`, (r) => {
+      r.resume();
+      resolve(r.statusCode === 200);
+    });
+    req.on("error", () => resolve(false));
+    req.setTimeout(1000, () => {
+      req.destroy();
+      resolve(false);
+    });
+  });
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/** A running nokk CDP server. Returned by {@link launch}. */
+class NokkServer {
+  constructor(proc, host, port) {
+    this._proc = proc;
+    this.host = host;
+    this.port = port;
+  }
+  /** browserWSEndpoint for puppeteer.connect / chromium.connectOverCDP. */
+  get wsEndpoint() {
+    return `ws://${this.host}:${this.port}/devtools/browser/nokk`;
+  }
+  get httpEndpoint() {
+    return `http://${this.host}:${this.port}`;
+  }
+  get pid() {
+    return this._proc.pid;
+  }
+  /** Stop the server. Idempotent. */
+  async close() {
+    const p = this._proc;
+    if (p.exitCode !== null || p.signalCode) return;
+    p.kill("SIGTERM");
+    await new Promise((resolve) => {
+      const t = setTimeout(() => {
+        try {
+          p.kill("SIGKILL");
+        } catch (_) {}
+        resolve();
+      }, 5000);
+      p.once("exit", () => {
+        clearTimeout(t);
+        resolve();
+      });
+    });
+  }
+}
+
+/**
+ * Start a `nokk` CDP server and resolve to a {@link NokkServer}.
+ *
+ * @param {object} [opts]
+ * @param {string}  [opts.host="127.0.0.1"]
+ * @param {number}  [opts.port=0]                 0 = pick a free port
+ * @param {number}  [opts.workers]
+ * @param {number}  [opts.maxContexts]
+ * @param {string}  [opts.proxy]                  e.g. "socks5://host:1080"
+ * @param {string}  [opts.sessionStore]
+ * @param {boolean} [opts.rotateFingerprint]
+ * @param {boolean} [opts.geoipTimezone]
+ * @param {boolean} [opts.allowTrackers]
+ * @param {number}  [opts.chromeVersion]          e.g. 148
+ * @param {string[]}[opts.args]                    extra raw CLI args
+ * @param {object}  [opts.env]
+ * @param {number}  [opts.timeout=30000]          ms to wait for readiness
+ */
+async function launch(opts = {}) {
+  const host = opts.host || "127.0.0.1";
+  const port = opts.port || (await freePort(host));
+  const args = ["--host", host, "--port", String(port)];
+  if (opts.workers != null) args.push("--workers", String(opts.workers));
+  if (opts.maxContexts != null) args.push("--max-contexts", String(opts.maxContexts));
+  if (opts.proxy) args.push("--proxy", opts.proxy);
+  if (opts.sessionStore) args.push("--session-store", String(opts.sessionStore));
+  if (opts.rotateFingerprint) args.push("--rotate-fingerprint");
+  if (opts.geoipTimezone) args.push("--geoip-timezone");
+  if (opts.allowTrackers) args.push("--allow-trackers");
+  if (opts.chromeVersion != null) args.push("--chrome-version", String(opts.chromeVersion));
+  if (opts.args) args.push(...opts.args);
+
+  const proc = spawn(binaryPath(), args, {
+    stdio: opts.stdio || "inherit",
+    env: { ...process.env, ...(opts.env || {}) },
+  });
+  const server = new NokkServer(proc, host, port);
+
+  const timeout = opts.timeout != null ? opts.timeout : 30000;
+  const deadline = Date.now() + timeout;
+  const killOnExit = () => {
+    try {
+      proc.kill();
+    } catch (_) {}
+  };
+  while (Date.now() < deadline) {
+    if (proc.exitCode !== null) {
+      throw new Error(`nokk exited before becoming ready (code ${proc.exitCode})`);
+    }
+    if (await ready(host, port)) {
+      process.once("exit", killOnExit); // safety net
+      return server;
+    }
+    await sleep(50);
+  }
+  await server.close();
+  throw new Error(`nokk did not become ready within ${timeout}ms`);
+}
+
+module.exports = { launch, binaryPath, NokkServer };

package/install.js

@@ -0,0 +1,74 @@
+// postinstall: download the prebuilt `nokk` binary from the matching GitHub
+// Release and extract it into vendor/, so the package ships no binary in the
+// tarball (kept small) but `require('nokk')` / `npx nokk` work after install.
+// Linux x64 only for now (matches what the release workflow builds).
+"use strict";
+
+const https = require("https");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { execFileSync } = require("child_process");
+
+const pkg = require("./package.json");
+const REPO = "koloss777/nokk";
+const VENDOR = path.join(__dirname, "vendor");
+const BIN = path.join(VENDOR, "nokk");
+
+function fail(msg) {
+  console.error("[nokk] " + msg);
+  process.exit(1);
+}
+
+// Allow skipping (e.g. CI that provides NOKK_BINARY, or offline installs).
+if (process.env.NOKK_SKIP_DOWNLOAD || process.env.NOKK_BINARY) {
+  console.log("[nokk] skipping binary download (NOKK_BINARY / NOKK_SKIP_DOWNLOAD set)");
+  process.exit(0);
+}
+
+if (process.platform !== "linux" || process.arch !== "x64") {
+  fail(
+    `prebuilt binary is currently Linux x64 only (got ${process.platform}/${process.arch}). ` +
+      `See ${pkg.homepage} — macOS/Windows are on the roadmap.`
+  );
+}
+
+const tag = "v" + pkg.version; // 0.1.20-alpha -> v0.1.20-alpha
+const asset = `nokk-${tag}-linux-x86_64.tar.gz`;
+const url = `https://github.com/${REPO}/releases/download/${tag}/${asset}`;
+
+function download(from, dest, cb, redirects) {
+  redirects = redirects || 0;
+  https
+    .get(from, (res) => {
+      if ([301, 302, 303, 307, 308].includes(res.statusCode) && res.headers.location) {
+        res.resume();
+        if (redirects > 10) return cb(new Error("too many redirects"));
+        return download(res.headers.location, dest, cb, redirects + 1);
+      }
+      if (res.statusCode !== 200) {
+        res.resume();
+        return cb(new Error(`HTTP ${res.statusCode} for ${from}`));
+      }
+      const file = fs.createWriteStream(dest);
+      res.pipe(file);
+      file.on("finish", () => file.close(() => cb(null)));
+      file.on("error", cb);
+    })
+    .on("error", cb);
+}
+
+fs.mkdirSync(VENDOR, { recursive: true });
+const tmp = path.join(os.tmpdir(), asset);
+console.log(`[nokk] downloading ${asset} …`);
+download(url, tmp, (err) => {
+  if (err) fail(`download failed: ${err.message}\n  ${url}`);
+  try {
+    execFileSync("tar", ["-xzf", tmp, "-C", VENDOR, "nokk"]);
+    fs.chmodSync(BIN, 0o755);
+    fs.unlinkSync(tmp);
+    console.log("[nokk] installed " + BIN);
+  } catch (e) {
+    fail("extract failed: " + e.message);
+  }
+});

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@koloss777/nokk",
+  "version": "0.1.21-alpha",
+  "description": "Undetectable headless-browser engine — a lightweight, Chrome-fingerprinted CDP server for Puppeteer/Playwright scraping. npm install and connect, no browser download.",
+  "keywords": [
+    "scraping",
+    "web-scraping",
+    "puppeteer",
+    "playwright",
+    "cdp",
+    "chrome-devtools-protocol",
+    "headless-browser",
+    "browser-automation",
+    "stealth",
+    "anti-bot",
+    "fingerprint",
+    "ja3",
+    "cloudflare"
+  ],
+  "license": "(MIT OR Apache-2.0)",
+  "author": "koloss777",
+  "homepage": "https://github.com/koloss777/nokk",
+  "repository": { "type": "git", "url": "git+https://github.com/koloss777/nokk.git" },
+  "bugs": { "url": "https://github.com/koloss777/nokk/issues" },
+  "main": "index.js",
+  "types": "index.d.ts",
+  "bin": { "nokk": "bin/nokk.js" },
+  "files": ["index.js", "index.d.ts", "install.js", "bin/", "README.md"],
+  "scripts": { "postinstall": "node install.js" },
+  "engines": { "node": ">=16" },
+  "os": ["linux"],
+  "cpu": ["x64"]
+}