capiumbrowser 0.1.1 → 1.0.1

package/README.md

@@ -91,6 +91,28 @@ launch the SDK fetches the per-platform build from the license service (authenti
 checksum-verified) and caches it under `~/.capium` (`CAPIUM_HOME` overrides — it deliberately
 lives *outside* `node_modules`, so reinstalls never delete it).
 
+### Download the browser — just your license key
+
+The browser binary is fetched with **only your Capium license key** — no separate token, no
+manual download, no per-platform URL to figure out. Set the key once:
+
+```bash
+export CAPIUM_LICENSE_KEY=cap_your_key_here
+# or put a `KEY=cap_...` line in ~/.capium/license
+```
+
+Then the right build for your OS/arch downloads automatically — either **on first launch**, or
+ahead of time with the CLI:
+
+```bash
+npx capiumbrowser install     # ...or skip it: the first launch() downloads the binary for you.
+```
+
+That same key both **authorizes the download** and **licenses the browser**, and it's passed to
+the binary through the environment — never on argv. The download is checksum-verified before
+anything runs and cached, so it's fetched once and reused. Run `npx capiumbrowser` (the `info`
+check) to see your license, the installed build, and anything still missing.
+
 **Migrating?** It's a one-line change — the returned object is a standard Playwright /
 Puppeteer `Browser`:
 

package/lib/channels.json

@@ -1,12 +1,12 @@
 {
-  "_comment": "SINGLE SOURCE OF TRUTH for the current stable Capium browser build per OS/arch. Each OS reaches stable independently -- edit one entry without touching the others. This file ships inside the wheel (the SDK reads it to pick each host's stable build) AND is published to the download server by the release pipeline (so the server/website can resolve 'latest stable' without a new SDK release). `version` is the Chromium base of the immutable artifact folder; `revision` is the cap<N> re-spin counter. `published: false` means the tag is declared but no artifact exists yet -- the SDK raises a clear 'not published yet' error instead of a raw 404.",
+  "_comment": "SINGLE SOURCE OF TRUTH for the current stable Capium browser build per OS/arch. Each OS reaches stable independently -- edit one entry without touching the others. This file ships inside the wheel (the SDK reads it to pick each host's stable build) AND is published to the download server by the release pipeline. `version` is the Chromium base; `revision` is the re-spin counter -- the served R2 folder is chromium-v<version>/ for revision 1 (the base build) and chromium-v<version>-r<N>/ for a re-spin (N>=2), so publishing a re-spin never overwrites the base artifact older SDKs still fetch. `published: false` means the tag is declared but no artifact exists yet -- the SDK raises a clear 'not published yet' error instead of a raw 404.",
   "schema": 1,
-  "updated": "2026-09-01",
+  "updated": "2026-09-08",
   "channels": {
     "stable": {
-      "windows-x64": { "version": "152.0.7977.65", "revision": 1, "sha256": "c3cf933325907b36a157ed74db80c1acb1d3aca0faa93c3bb224fe735cafc4a5", "published": true },
-      "macos-arm64": { "version": "152.0.7977.65", "revision": 1, "sha256": "e328158c5a272594e01d2135eb418f649f46ee5b0a80fbc79f6923dcc809be01", "published": true },
-      "linux-x64":   { "version": "152.0.7977.64", "revision": 1, "sha256": "aeb36b509d26e40969d64502f0a2a3f0ad73c7cdd8c42c5fab8a54e953bc3b3a", "published": true },
+      "windows-x64": { "version": "152.0.7977.65", "revision": 2, "sha256": "1556ad4fd5fe555b3c427be5e868bcace705f271ec3bcd6be4674cae8163ffc6", "published": true },
+      "macos-arm64": { "version": "152.0.7977.65", "revision": 2, "sha256": "a71654da4b0e1b7ab2f8374e62ba5378decc5b7762953cdbe6946781d8e08c33", "published": true },
+      "linux-x64":   { "version": "152.0.7977.64", "revision": 2, "sha256": "cf26c55e86038eb33e1de607ade5619f0494188624b30bb508fa9429c0e98a17", "published": true },
       "linux-arm64": { "version": "152.0.7977.64", "revision": 1, "sha256": null, "published": false }
     }
   }

package/lib/download.js

@@ -41,9 +41,10 @@ const tar = require('tar');
 const config = require('./config');
 const license = require('./license');
 const { CapiumError, CapiumExpiredError, CapiumServerDownError } = require('./errors');
-const { binaryVersionFor, isPublished } = require('./version');
+const { SDK_VERSION, binaryVersionFor, binaryRevisionFor, buildId, isPublished } = require('./version');
 
 const NET_TIMEOUT_MS = 300000;
+const USER_AGENT = `capiumbrowser/${SDK_VERSION}`;
 
 // (normalized os, normalized arch) -> distro tag used in the filename/URL.
 const SUPPORTED = {
@@ -86,11 +87,16 @@ function downloadTag(system = null, machine = null) {
 }
 
 /**
- * The signed request path for a build. Filename is version-independent; only the folder
- * carries the version (per the '...end name will all be the same' contract).
+ * The signed request path for a build: version in the folder, tag in the filename
+ * (`/download/distro/chromium-v<version>/capiumbrowser-<tag>.tar.gz`). Per-OS versions work
+ * because each tag lives under its own chromium-v<version>/ folder (win/mac .65 while linux
+ * is .64). Key travels in the X-Capzy-License header, the path is HMAC-signed, and the bytes
+ * are verified against the response's X-Capzy-SHA256.
  */
-function distroPath(version, tag) {
-  return `/download/distro/chromium-v${version}/capiumbrowser-${tag}.tar.gz`;
+function distroPath(version, tag, revision = 1) {
+  // A same-engine re-spin (revision>=2) lands in its own immutable folder
+  // chromium-v<version>-r<N>/, so publishing it never overwrites the base artifact older SDKs fetch.
+  return `/download/distro/chromium-v${buildId(version, revision)}/capiumbrowser-${tag}.tar.gz`;
 }
 
 // ---- extraction ------------------------------------------------------------------------------
@@ -216,8 +222,12 @@ function removeInstalls(root) {
  */
 async function download(url, headers, dest, version, tag) {
   let res;
+  // Identify the SDK on every request. undici otherwise sends a default UA that Cloudflare's
+  // Browser Integrity Check rejects as a bot (403) before the request reaches the origin. A
+  // stable product UA is both correct hygiene and what the edge allows.
+  const h = Object.assign({ 'User-Agent': USER_AGENT }, headers || {});
   try {
-    res = await fetch(url, { headers: headers || {}, signal: AbortSignal.timeout(NET_TIMEOUT_MS) });
+    res = await fetch(url, { headers: h, signal: AbortSignal.timeout(NET_TIMEOUT_MS) });
   } catch (e) {
     throw new CapiumServerDownError(
       `could not reach the download server ${url}: ${e.cause?.message || e.message || e}`);
@@ -281,14 +291,23 @@ async function ensureBinary({ version = null, licenseKey = null, server = null }
         'Set CAPIUM_VERSION to pin a specific build if one exists.');
   }
 
-  version = version || process.env.CAPIUM_VERSION || binaryVersionFor(tag);
+  const envVer = process.env.CAPIUM_VERSION;
+  version = version || envVer || binaryVersionFor(tag);
+  // A same Chromium version can be re-spun (r2, r3, ...). CAPIUM_REVISION overrides; an explicit
+  // CAPIUM_VERSION pin defaults to the base (r1) unless a revision is given; otherwise the per-OS
+  // revision comes from channels.json.
+  let revision;
+  if (process.env.CAPIUM_REVISION) revision = parseInt(process.env.CAPIUM_REVISION, 10);
+  else if (envVer) revision = 1;
+  else revision = binaryRevisionFor(tag);
+  const bid = buildId(version, revision);
 
-  // Reuse the cached binary ONLY if it's already the target version. A different (older)
-  // version -- e.g. after `npm install capiumbrowser@latest` bumps this OS's pinned build --
-  // falls through to fetch the new build and drop the old one.
+  // Reuse the cached binary ONLY if it's already this exact build (version + revision). A
+  // different build -- e.g. after `npm install capiumbrowser@latest` bumps this OS's pinned build
+  // or re-spin -- falls through to fetch the new one and drop the old.
   try {
     const existing = config.findBinary();
-    if (readInstalledVersion(existing) === version) return existing;
+    if (readInstalledVersion(existing) === bid) return existing;
   } catch {}
 
   let url;
@@ -299,7 +318,7 @@ async function ensureBinary({ version = null, licenseKey = null, server = null }
   } else {
     // Signed path-based download: key in a header, PATH HMAC-signed, sha256-verified.
     const { key, server: srv } = license.resolve(licenseKey, server); // -> CapiumConfigError if no key
-    const p = distroPath(version, tag);
+    const p = distroPath(version, tag, revision);
     url = srv + p;
     headers = license.getHeaders(key, p);
   }
@@ -319,7 +338,7 @@ async function ensureBinary({ version = null, licenseKey = null, server = null }
     // marker files, and findBinary only accepts a bare chrome.exe next to one -- the
     // downloader vouches for the directory it just extracted.
     try {
-      fs.writeFileSync(path.join(distroDir, MARKER), String(version));
+      fs.writeFileSync(path.join(distroDir, MARKER), String(bid));
     } catch {}
   } finally {
     try {
@@ -335,7 +354,7 @@ async function ensureBinary({ version = null, licenseKey = null, server = null }
       `downloaded and extracted the ${tag} build but no launch target was found afterwards ` +
         `(unexpected archive layout under ${root}).`);
   }
-  stampVersion(binPath, version); // so a later version bump knows to re-download
+  stampVersion(binPath, bid); // so a later version/revision bump knows to re-download
   // Re-apply exec bits the wrapper + engine binaries need (zip drops unix perms).
   if (process.platform !== 'win32') {
     for (const p of [binPath, path.join(path.dirname(binPath), 'chrome')]) {

package/lib/license.js

@@ -14,8 +14,10 @@ const os = require('os');
 const path = require('path');
 
 const { CapiumConfigError, CapiumExpiredError, CapiumServerDownError } = require('./errors');
+const { SDK_VERSION } = require('./version');
 
 const DEFAULT_SERVER = 'https://license.capzy.ai';
+const USER_AGENT = `capiumbrowser/${SDK_VERSION}`;
 
 function licenseFile() {
   // CAPIUM_LICENSE_FILE is a test/deploy override; the contract path is ~/.capium/license.
@@ -167,6 +169,7 @@ async function status(key = null, server = null) {
         'X-Capzy-Device-Fp': fp,
         'X-Capzy-Signature': sig,
         'Content-Type': 'application/json',
+        'User-Agent': USER_AGENT,
       },
       signal: AbortSignal.timeout(10000),
     });

package/lib/version.js

@@ -62,6 +62,38 @@ function binaryVersionFor(tag) {
   return CAPIUM_BINARY_VERSIONS[tag] || DEFAULT_BINARY_VERSION;
 }
 
+function revisionsFromManifest() {
+  if (!STABLE) return {};
+  const out = {};
+  for (const [tag, entry] of Object.entries(STABLE)) {
+    if (entry && typeof entry === 'object' && Number.isInteger(entry.revision)) out[tag] = entry.revision;
+  }
+  return out;
+}
+
+// Re-spin variant per tag (>=1). Same Chromium version can be rebuilt (a stealth/fingerprint
+// change with no engine bump); each re-spin increments this. 1 = the base build.
+const CAPIUM_BINARY_REVISIONS = revisionsFromManifest();
+
+/**
+ * The re-spin variant (>=1) for a distro tag. 1 = the base build (suffix-less folder); 2,3,...
+ * are re-spins of the SAME Chromium version served from chromium-v<version>-r<N>/ (so a re-spin
+ * never overwrites the base artifact older SDKs still fetch). A version bump resets this to 1.
+ */
+function binaryRevisionFor(tag) {
+  return CAPIUM_BINARY_REVISIONS[tag] || 1;
+}
+
+/**
+ * Stable identity of one specific build = the R2 folder discriminator AND the install-cache key.
+ * revision 1 -> the version itself (chromium-v<version>/, the base build); N>=2 -> '<version>-r<N>'
+ * (chromium-v<version>-r<N>/). So a revision bump on an unchanged engine still re-downloads.
+ */
+function buildId(version, revision) {
+  const n = parseInt(revision, 10);
+  return !n || n < 2 ? version : `${version}-r${n}`;
+}
+
 /**
  * False only when the manifest declares the tag but marks it not-yet-published. Unknown
  * tags / missing manifest return true so the download layer's own error/404 speaks instead.
@@ -93,7 +125,10 @@ module.exports = {
   SDK_VERSION,
   CAPIUM_BINARY_VERSION,
   CAPIUM_BINARY_VERSIONS,
+  CAPIUM_BINARY_REVISIONS,
   binaryVersionFor,
+  binaryRevisionFor,
+  buildId,
   isPublished,
   hostTag,
   _FALLBACK_VERSIONS: FALLBACK_VERSIONS,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "capiumbrowser",
-  "version": "0.1.1",
+  "version": "1.0.1",
   "description": "Drop-in stealth browser SDK on top of Playwright or Puppeteer (Capium Chromium).",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Capzy (https://capzy.ai)",