clearcote 0.20.0 → 0.22.0

package/dist/profileauto.js

@@ -0,0 +1,150 @@
+// `profile: "auto"` — resolve a persona from the best source available.
+//
+// ORDER: the licensed clearcote service first, a local imported directory as backup.
+//
+// The service is preferred because its corpus is fresher, larger and curated. But it can be
+// unreachable for reasons that are none of the caller's fault — no license, an exhausted daily
+// budget, a rate limit, a network blip, an outage — and in every one of those cases a local
+// profile is enormously better than no persona. So the fallback is by design, not a patch.
+//
+// THE FALLBACK IS ALWAYS ANNOUNCED. A silent downgrade would leave a caller believing they are
+// on a fresh service profile while they are on a stale local one, and the whole product is about
+// knowing exactly what identity you are presenting. `source` is returned on every result and a
+// one-line reason is written to stderr unless `quiet`.
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { PROFILE_DIR } from "./profile.js";
+import { importDirectory, loadImportedProfile } from "./profileimport.js";
+import { selectProfile } from "./profilelib.js";
+import { fetchIndex, fetchProfile } from "./profilesource.js";
+/** Where an imported (e.g. converted chrome-fingerprints) directory is looked for by default. */
+export const DEFAULT_LOCAL_DIR = process.env.CLEARCOTE_PROFILE_SOURCE ?? join(homedir(), ".clearcote", "profiles", "imported");
+function localCachePath() {
+    const d = join(PROFILE_DIR, "library");
+    if (!existsSync(d))
+        mkdirSync(d, { recursive: true });
+    return join(d, "local-index.json");
+}
+export function loadLocalIndex(dir) {
+    const mtimeMs = statSync(dir).mtimeMs;
+    const path = localCachePath();
+    if (existsSync(path)) {
+        try {
+            const c = JSON.parse(readFileSync(path, "utf8"));
+            if (c.dir === dir && c.mtimeMs === mtimeMs)
+                return c.index;
+        }
+        catch {
+            /* fall through and re-index */
+        }
+    }
+    const { index } = importDirectory(dir);
+    try {
+        writeFileSync(path, JSON.stringify({ dir, mtimeMs, index }));
+    }
+    catch {
+        /* a cache write failure must never fail a launch */
+    }
+    return index;
+}
+function note(quiet, msg) {
+    if (!quiet)
+        process.stderr.write(`[clearcote] [profile] ${msg}\n`);
+}
+/** The optional-backup tip is worth saying once, not on every launch. */
+let hintedThisProcess = false;
+/** Test seam: reset the once-per-process tip. */
+export function _resetHint() {
+    hintedThisProcess = false;
+}
+/**
+ * How to populate a local backup directory. Printed when the service is unavailable and no local
+ * directory exists — the moment the caller actually needs it.
+ *
+ * OPTIONAL, AND NOT SOMETHING WE SHIP. Clearcote redistributes no third-party fingerprints; the
+ * dataset is fetched by the user from its own repository under its own terms, and we only read
+ * the converted format. Any directory of clearcote-profile JSON works just as well, which is
+ * why this is phrased as one example rather than the required path.
+ */
+export function localSetupHint(dir) {
+    return [
+        `A local profile directory is optional, and gives "auto" a backup when the service is`,
+        `unavailable. Any folder of clearcote-profile JSON works — your own captures, or a`,
+        `third-party dataset you convert yourself. For example, using the open chrome-fingerprints`,
+        `dataset (fetched by you, from its own repo, under its own licence):`,
+        ``,
+        `    pip install chrome-fingerprints`,
+        `    python tools/fingerprint-collect/convert_dataset.py --out "${dir}" --count 500`,
+        ``,
+        `Or capture your own with tools/fingerprint-collect (collect.html), or point`,
+        `CLEARCOTE_PROFILE_SOURCE at a directory you already have.`,
+    ].join("\n");
+}
+/** Resolve a persona from the local imported directory. */
+export function resolveLocal(host, opts = {}) {
+    const dir = opts.localDir ?? DEFAULT_LOCAL_DIR;
+    if (!existsSync(dir)) {
+        throw new Error(`no local profile directory at ${dir}\n\n${localSetupHint(dir)}`);
+    }
+    const index = loadLocalIndex(dir);
+    if (index.length === 0) {
+        throw new Error(`local profile directory ${dir} contains no usable clearcote-profile JSON`);
+    }
+    const selection = selectProfile(index, host, opts);
+    return { profile: loadImportedProfile(dir, selection.entry.id), selection, source: "local" };
+}
+/**
+ * Resolve `profile: "auto"`: service first, local directory as backup.
+ *
+ * Any service failure falls back — including 401 (no license) and 429 (rate limited or daily
+ * distinct budget exhausted), because in all of those a local persona is better than none and
+ * far better than a hard launch failure.
+ */
+export async function resolveAuto(host, opts = {}) {
+    if (opts.preferLocal) {
+        const r = resolveLocal(host, opts);
+        note(opts.quiet, `using local profile ${r.selection.entry.id} (preferLocal)`);
+        return r;
+    }
+    try {
+        const index = await fetchIndex(host, opts);
+        if (index.length === 0)
+            throw new Error("service returned no candidates for this host");
+        const selection = selectProfile(index, host, opts);
+        const profile = await fetchProfile(selection.entry.id, opts);
+        note(opts.quiet, `using service profile ${selection.entry.id} ` +
+            `(score ${selection.score.toFixed(2)}, pool ${selection.poolSize}, mode ${selection.mode})`);
+        // Mention the optional backup ONCE per process, and only while there is none configured.
+        // The useful moment to learn about a fallback is before you need it — but repeating it on
+        // every launch would be noise, and nagging someone who already set one up would be wrong.
+        if (!hintedThisProcess && !existsSync(opts.localDir ?? DEFAULT_LOCAL_DIR)) {
+            hintedThisProcess = true;
+            note(opts.quiet, `tip: no local backup directory configured. If the service is ever rate limited or
+unreachable, "auto" fails rather than falling back. Setting one up is optional:
+${localSetupHint(opts.localDir ?? DEFAULT_LOCAL_DIR)}`);
+        }
+        return { profile, selection, source: "service" };
+    }
+    catch (serviceErr) {
+        const reason = String(serviceErr instanceof Error ? serviceErr.message : serviceErr).slice(0, 200);
+        try {
+            const r = resolveLocal(host, opts);
+            // Both halves of the story: what failed, and what is being used instead.
+            note(opts.quiet, `service unavailable (${reason}) — falling back to local profile ${r.selection.entry.id}`);
+            return { ...r, fallbackReason: reason };
+        }
+        catch (localErr) {
+            const dir = opts.localDir ?? DEFAULT_LOCAL_DIR;
+            const noLocalDir = !existsSync(dir);
+            const lr = String(localErr instanceof Error ? localErr.message : localErr);
+            // Report BOTH failures. Surfacing only the local one would send the caller to go and fix
+            // a directory when the real problem was an expired license.
+            throw new Error(`profile: "auto" could not resolve a persona.\n` +
+                `  service: ${reason}\n` +
+                `  local:   ${noLocalDir ? `no directory at ${dir}` : lr}\n\n` +
+                (noLocalDir ? localSetupHint(dir) : ""));
+        }
+    }
+}
+//# sourceMappingURL=profileauto.js.map

package/dist/profileauto.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"profileauto.js","sourceRoot":"","sources":["../src/profileauto.ts"],"names":[],"mappings":"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"}

package/dist/profileimport.d.ts

@@ -0,0 +1,22 @@
+import { type ProfileIndexEntry } from "./profilelib.js";
+/** Parse a clearcote-profile blob into an index entry. Returns null when the file is not one. */
+export declare function indexEntryFromProfile(id: string, profile: Record<string, unknown>): ProfileIndexEntry | null;
+export interface ImportResult {
+    index: ProfileIndexEntry[];
+    /** Files that were not usable, with the reason — surfaced rather than silently dropped, so a
+     *  half-converted directory is visible instead of quietly producing a thin pool. */
+    skipped: {
+        file: string;
+        reason: string;
+    }[];
+}
+/**
+ * Index every `*.json` in a directory.
+ *
+ * Reads each file once. For 10k profiles this is a few seconds and a lot of I/O, so callers
+ * should cache the result (`writeIndex`) rather than re-scanning per launch.
+ */
+export declare function importDirectory(dir: string): ImportResult;
+/** Load one profile from an imported directory, by the id `importDirectory` assigned it. */
+export declare function loadImportedProfile(dir: string, id: string): Record<string, unknown>;
+//# sourceMappingURL=profileimport.d.ts.map

package/dist/profileimport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"profileimport.d.ts","sourceRoot":"","sources":["../src/profileimport.ts"],"names":[],"mappings":"AAoBA,OAAO,EAAkB,KAAK,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEzE,iGAAiG;AACjG,wBAAgB,qBAAqB,CACnC,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,iBAAiB,GAAG,IAAI,CA4C1B;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,iBAAiB,EAAE,CAAC;IAC3B;wFACoF;IACpF,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC7C;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,CA8BzD;AAED,4FAA4F;AAC5F,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CASpF"}

package/dist/profileimport.js

@@ -0,0 +1,116 @@
+// Generic profile importer: turn a DIRECTORY of clearcote-profile JSON into a selectable index.
+//
+// WE ARE AN IMPORTER, NOT A HOST. Clearcote ships no third-party fingerprints and redistributes
+// none. A source is just a folder of clearcote-profile JSON on the user's own machine, however
+// it got there:
+//
+//   * the open chrome-fingerprints dataset (Vinyzu), converted locally with
+//     tools/fingerprint-collect/convert_dataset.py — the dataset is fetched by the USER from the
+//     original repository, so nothing is re-published here and its terms are unaffected;
+//   * your own captures from tools/fingerprint-collect (collect.html / snippet.js);
+//   * the licensed clearcote profile service (see profilesource.ts);
+//   * any other producer that emits the same schema.
+//
+// Keeping the format as the ONLY contract is what makes this generic. There is no adapter per
+// vendor, no vendored data, and no decompressor for someone else's archive format baked into
+// three SDKs — a directory of JSON is something every source can produce and every SDK can read.
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { gzipSync } from "node:zlib";
+import { gpuVendorClass } from "./profilelib.js";
+/** Parse a clearcote-profile blob into an index entry. Returns null when the file is not one. */
+export function indexEntryFromProfile(id, profile) {
+    const nav = (profile.navigator ?? {});
+    const screen = (profile.screen ?? {});
+    const webgl = (profile.webgl ?? {});
+    const gl1 = (webgl.webgl1 ?? {});
+    const debug = (gl1.debug ?? {});
+    const meta = (profile.meta ?? {});
+    const ua = String(nav.user_agent ?? "");
+    const platform = String(nav.platform ?? "");
+    // OS family from navigator.platform first (stable across UA reduction), UA as a fallback.
+    let os;
+    if (/win/i.test(platform) || /Windows/i.test(ua))
+        os = "windows";
+    else if (/mac/i.test(platform) || /Mac OS X/i.test(ua))
+        os = "macos";
+    else if (/linux|x11/i.test(platform) || /Linux/i.test(ua))
+        os = "linux";
+    else if (/android/i.test(ua))
+        os = "android";
+    else
+        return null; // unclassifiable: better to skip than to mislabel and mis-serve it
+    // Version is OPTIONAL by design. Hardware-only imports (e.g. converted chrome-fingerprints
+    // records) carry no browser version and inherit the engine's — see profilelib's browser_major.
+    const m = ua.match(/Chrome\/(\d+)/);
+    const browserMajor = m ? Number(m[1]) : null;
+    const renderer = debug.UNMASKED_RENDERER_WEBGL ?? null;
+    // The launch cost, measured the same way fingerprint.ts encodes it — so an entry that would
+    // blow the argv limit is excluded at selection time rather than failing at spawn.
+    const encodedSize = gzipSync(Buffer.from(JSON.stringify(profile)), { level: 9 }).toString("base64").length;
+    return {
+        id,
+        os_family: os,
+        browser_major: browserMajor,
+        gpu_vendor: gpuVendorClass(renderer),
+        renderer: renderer ?? undefined,
+        screen_width: screen.width,
+        screen_height: screen.height,
+        device_pixel_ratio: screen.device_pixel_ratio,
+        hardware_concurrency: profile.hardware_concurrency,
+        device_memory: profile.device_memory,
+        encoded_size: encodedSize,
+        captured_at: typeof meta.captured_at === "string" ? meta.captured_at : undefined,
+    };
+}
+/**
+ * Index every `*.json` in a directory.
+ *
+ * Reads each file once. For 10k profiles this is a few seconds and a lot of I/O, so callers
+ * should cache the result (`writeIndex`) rather than re-scanning per launch.
+ */
+export function importDirectory(dir) {
+    if (!existsSync(dir) || !statSync(dir).isDirectory()) {
+        throw new Error(`profile source is not a directory: ${dir}`);
+    }
+    const index = [];
+    const skipped = [];
+    for (const f of readdirSync(dir)) {
+        if (!f.endsWith(".json"))
+            continue;
+        const path = join(dir, f);
+        let parsed;
+        try {
+            parsed = JSON.parse(readFileSync(path, "utf8"));
+        }
+        catch (e) {
+            skipped.push({ file: f, reason: `unreadable JSON: ${String(e).slice(0, 80)}` });
+            continue;
+        }
+        // A clearcote-profile always has navigator; without it this is some other kind of file.
+        if (!parsed || typeof parsed !== "object" || !parsed.navigator) {
+            skipped.push({ file: f, reason: "not a clearcote-profile (no navigator)" });
+            continue;
+        }
+        const entry = indexEntryFromProfile(f.replace(/\.json$/, ""), parsed);
+        if (!entry) {
+            skipped.push({ file: f, reason: "could not classify os_family" });
+            continue;
+        }
+        index.push(entry);
+    }
+    return { index, skipped };
+}
+/** Load one profile from an imported directory, by the id `importDirectory` assigned it. */
+export function loadImportedProfile(dir, id) {
+    // The id is a filename stem this module produced, but it can reach here from a cached index,
+    // so treat it as untrusted: reject anything that could escape the source directory.
+    if (id.includes("/") || id.includes("\\") || id.includes("..")) {
+        throw new Error(`invalid profile id '${id}'`);
+    }
+    const path = join(dir, `${id}.json`);
+    if (!existsSync(path))
+        throw new Error(`profile '${id}' not found in ${dir}`);
+    return JSON.parse(readFileSync(path, "utf8"));
+}
+//# sourceMappingURL=profileimport.js.map

package/dist/profileimport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"profileimport.js","sourceRoot":"","sources":["../src/profileimport.ts"],"names":[],"mappings":"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"}

package/dist/profilelib.d.ts

@@ -0,0 +1,100 @@
+/** One row of the profile index. Deliberately slim: selection never touches a blob until it has
+ *  picked a winner, so the index stays cheap to hold in memory and to ship. */
+export interface ProfileIndexEntry {
+    id: string;
+    os_family: "windows" | "macos" | "linux" | "android" | (string & {});
+    os_major?: string;
+    /**
+     * Chromium major of the capture, HARD-filtered against the engine's own major.
+     *
+     * `null`/absent means VERSION-AGNOSTIC and matches any engine. That is not a loophole — it is
+     * the correct description of a hardware-only profile. Imports from the chrome-fingerprints
+     * dataset deliberately drop the browser version (its records are Chrome ~114/115) and carry
+     * only version-independent identity: GPU, screen, fonts, voices, audio, CPU/memory, keyboard.
+     * Such a profile inherits the running engine's version, so it cannot contradict it.
+     *
+     * A profile that DOES pin a version and gets it wrong is a real contradiction — UA says 138
+     * while the engine behaves like 150 — which is why a mismatched number is still rejected.
+     */
+    browser_major?: number | null;
+    /** Coarse vendor class parsed from the renderer string: nvidia | amd | intel | apple | other. */
+    gpu_vendor: string;
+    /** Rough capability tier (0 = integrated, 1 = mainstream, 2 = high-end). */
+    gpu_tier?: number;
+    renderer?: string;
+    screen_width?: number;
+    screen_height?: number;
+    device_pixel_ratio?: number;
+    hardware_concurrency?: number;
+    device_memory?: number;
+    /** gzip+base64 length of the encoded profile — used to keep the launch under the argv limit. */
+    encoded_size?: number;
+    /** ISO date of capture; newer is mildly preferred. */
+    captured_at?: string;
+}
+/** What we know about the machine actually doing the rendering. */
+export interface HostFacts {
+    os_family: string;
+    browser_major: number;
+    gpu_vendor?: string;
+    gpu_tier?: number;
+    screen_width?: number;
+    screen_height?: number;
+    device_pixel_ratio?: number;
+    hardware_concurrency?: number;
+    device_memory?: number;
+}
+export type SelectMode = "best" | "rotate" | "random";
+export interface SelectOptions {
+    /** `"rotate"` (default) sticky-per-key; `"best"` always top-scoring; `"random"` fresh each call. */
+    mode?: SelectMode;
+    /** Stickiness key for `"rotate"` — an account id, proxy session, or profile name. */
+    key?: string;
+    /** Candidate pool the mode picks from. Wide enough to avoid herding, narrow enough to stay coherent. */
+    topN?: number;
+    /** Override the target OS (defaults to the host's). */
+    os?: string;
+    /** Hard ceiling on encoded size; entries above it cannot be launched on Windows. */
+    maxEncodedSize?: number;
+}
+/** Windows caps a process command line at 32767 chars. The profile rides on argv as
+ *  `--fingerprint-profile=<gzip+base64>`, and the rest of the switches need room too, so keep a
+ *  wide margin. Exceeding this is not a soft failure — Chromium refuses to spawn and Playwright
+ *  surfaces it as an opaque `spawn UNKNOWN`, which is why this is enforced at selection time. */
+export declare const DEFAULT_MAX_ENCODED = 24000;
+/** Coarse GPU vendor class from a renderer string (works for ANGLE and raw GL strings). */
+export declare function gpuVendorClass(renderer: string | undefined | null): string;
+/**
+ * Score a candidate against the host. Higher is better; the maximum is 1.
+ *
+ * Weights encode what a detector can actually catch, in descending order of how cheaply it can
+ * be caught:
+ *  - GPU class (0.45): string-vs-render mismatch is a single-call contradiction.
+ *  - Screen (0.25): a persona whose screen cannot contain the real window is the documented
+ *    "reliable block trigger"; a profile *larger* than the host display is the dangerous
+ *    direction, so it is penalised harder than a smaller one.
+ *  - DPR (0.10): interacts with screen and with CSS pixel math.
+ *  - Cores/memory (0.10): weakly checkable against measured worker parallelism.
+ *  - Freshness (0.10): a recent capture is likelier to match current Chrome behaviour.
+ */
+export declare function scoreProfile(entry: ProfileIndexEntry, host: HostFacts): number;
+/** Hard filters. A candidate failing any of these is not merely low-scoring — it is incoherent,
+ *  and no weight should be able to promote it back into the pool. */
+export declare function eligible(entry: ProfileIndexEntry, host: HostFacts, opts?: SelectOptions): boolean;
+export interface Selection {
+    entry: ProfileIndexEntry;
+    score: number;
+    /** How many candidates survived the hard filters — useful for spotting an over-narrow index. */
+    poolSize: number;
+    mode: SelectMode;
+}
+/**
+ * Pick a profile for this host.
+ *
+ * Throws when nothing is eligible rather than silently falling back to an incoherent profile —
+ * a wrong persona is worse than no persona, because it converts a clean browser into a
+ * contradictory one.
+ */
+export declare function selectProfile(index: ProfileIndexEntry[], host: HostFacts, opts?: SelectOptions): Selection;
+export declare function defaultStickyKey(): string;
+//# sourceMappingURL=profilelib.d.ts.map

package/dist/profilelib.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"profilelib.d.ts","sourceRoot":"","sources":["../src/profilelib.ts"],"names":[],"mappings":"AAyBA;+EAC+E;AAC/E,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,SAAS,GAAG,OAAO,GAAG,OAAO,GAAG,SAAS,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;IACrE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;;;;;;;OAWG;IACH,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,iGAAiG;IACjG,UAAU,EAAE,MAAM,CAAC;IACnB,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gGAAgG;IAChG,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,sDAAsD;IACtD,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,mEAAmE;AACnE,MAAM,WAAW,SAAS;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAEtD,MAAM,WAAW,aAAa;IAC5B,oGAAoG;IACpG,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,qFAAqF;IACrF,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,wGAAwG;IACxG,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,oFAAoF;IACpF,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;iGAGiG;AACjG,eAAO,MAAM,mBAAmB,QAAQ,CAAC;AAIzC,2FAA2F;AAC3F,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM,CAU1E;AASD;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,iBAAiB,EAAE,IAAI,EAAE,SAAS,GAAG,MAAM,CA2C9E;AAED;qEACqE;AACrE,wBAAgB,QAAQ,CACtB,KAAK,EAAE,iBAAiB,EACxB,IAAI,EAAE,SAAS,EACf,IAAI,GAAE,aAAkB,GACvB,OAAO,CAWT;AAOD,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,iBAAiB,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,gGAAgG;IAChG,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,UAAU,CAAC;CAClB;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,iBAAiB,EAAE,EAC1B,IAAI,EAAE,SAAS,EACf,IAAI,GAAE,aAAkB,GACvB,SAAS,CAmCX;AAID,wBAAgB,gBAAgB,IAAI,MAAM,CAKzC"}

package/dist/profilelib.js

@@ -0,0 +1,181 @@
+// Profile library: index, host-coherence scoring, and selection.
+//
+// The persona path this serves is `--fingerprint-profile` WITHOUT `--fingerprint`. That
+// distinction is load-bearing and is why this module exists: measured against a strict
+// anti-bot device check, a seed persona failed 13/13 while a profile-only persona passed. With no
+// seed the farbling machinery never engages, so canvas/WebGL/audio readbacks come back
+// byte-identical to an unmodified browser — the profile is static value substitution over a
+// real, coherent capture rather than perturbation of this machine's.
+//
+// SELECTION IS ABOUT COHERENCE WITH *THIS HOST*, NOT ABOUT MATCHING AN OS STRING.
+// A profile claiming an RTX 3080 on an Intel UHD host says NVIDIA in the strings and paints
+// Intel pixels — a contradiction a detector reads in one call. So the GPU term dominates the
+// score, and `browser_major` is a HARD filter: a Chrome-138 capture on a 150 engine reports
+// UA 138 while the engine behaves like 150, which is self-contradictory in a way no scoring
+// weight should be able to outvote.
+//
+// ROTATION IS PER-IDENTITY, NOT PER-LAUNCH. Always serving the single best profile makes every
+// customer on similar hardware converge on one identity, and that shared fingerprint becomes its
+// own signal. But re-rolling every launch is worse: an account whose device changes on every
+// visit is a harder tell than a slightly-suboptimal stable one. So the default ("rotate") is
+// sticky-per-key — same key always resolves to the same profile, different keys spread across
+// the top-N.
+import { createHash } from "node:crypto";
+/** Windows caps a process command line at 32767 chars. The profile rides on argv as
+ *  `--fingerprint-profile=<gzip+base64>`, and the rest of the switches need room too, so keep a
+ *  wide margin. Exceeding this is not a soft failure — Chromium refuses to spawn and Playwright
+ *  surfaces it as an opaque `spawn UNKNOWN`, which is why this is enforced at selection time. */
+export const DEFAULT_MAX_ENCODED = 24000;
+const DEFAULT_TOP_N = 25;
+/** Coarse GPU vendor class from a renderer string (works for ANGLE and raw GL strings). */
+export function gpuVendorClass(renderer) {
+    const r = (renderer ?? "").toLowerCase();
+    if (!r)
+        return "unknown";
+    if (r.includes("nvidia") || r.includes("geforce") || r.includes("quadro"))
+        return "nvidia";
+    if (r.includes("amd") || r.includes("radeon") || r.includes("ati "))
+        return "amd";
+    if (r.includes("intel"))
+        return "intel";
+    if (r.includes("apple"))
+        return "apple";
+    if (r.includes("swiftshader") || r.includes("llvmpipe") || r.includes("software"))
+        return "software";
+    if (r.includes("mali") || r.includes("adreno") || r.includes("powervr"))
+        return "mobile";
+    return "other";
+}
+/** Ratio-based closeness in [0,1] — 1 when equal, decaying as the values diverge. */
+function closeness(a, b) {
+    if (a === undefined || b === undefined || a <= 0 || b <= 0)
+        return 0.5; // unknown: neutral
+    const hi = Math.max(a, b), lo = Math.min(a, b);
+    return lo / hi;
+}
+/**
+ * Score a candidate against the host. Higher is better; the maximum is 1.
+ *
+ * Weights encode what a detector can actually catch, in descending order of how cheaply it can
+ * be caught:
+ *  - GPU class (0.45): string-vs-render mismatch is a single-call contradiction.
+ *  - Screen (0.25): a persona whose screen cannot contain the real window is the documented
+ *    "reliable block trigger"; a profile *larger* than the host display is the dangerous
+ *    direction, so it is penalised harder than a smaller one.
+ *  - DPR (0.10): interacts with screen and with CSS pixel math.
+ *  - Cores/memory (0.10): weakly checkable against measured worker parallelism.
+ *  - Freshness (0.10): a recent capture is likelier to match current Chrome behaviour.
+ */
+export function scoreProfile(entry, host) {
+    let score = 0;
+    // -- GPU: exact vendor match dominates. A software renderer on either side is disqualifying
+    //    in practice (the pixels can never match a claimed discrete GPU), so it scores 0.
+    const hv = host.gpu_vendor ?? "unknown";
+    const ev = entry.gpu_vendor ?? "unknown";
+    let gpu;
+    if (ev === "software" || hv === "software")
+        gpu = 0;
+    else if (ev === hv)
+        gpu = 1;
+    else if (hv === "unknown" || ev === "unknown")
+        gpu = 0.5;
+    else
+        gpu = 0.15; // different real vendor: strings and pixels disagree
+    // tier proximity refines a same-vendor match
+    if (gpu === 1 && entry.gpu_tier !== undefined && host.gpu_tier !== undefined) {
+        gpu = 1 - Math.min(1, Math.abs(entry.gpu_tier - host.gpu_tier) / 3) * 0.4;
+    }
+    score += 0.45 * gpu;
+    // -- Screen. Asymmetric on purpose: claiming a LARGER display than the host has is the
+    //    contradiction that gets caught (the window cannot be contained), so penalise it more.
+    const ew = entry.screen_width, eh = entry.screen_height;
+    const hw = host.screen_width, hh = host.screen_height;
+    let screen = 0.5;
+    if (ew && eh && hw && hh) {
+        const fits = ew <= hw && eh <= hh;
+        const areaRatio = closeness(ew * eh, hw * hh);
+        screen = fits ? 0.7 + 0.3 * areaRatio : 0.25 * areaRatio;
+    }
+    score += 0.25 * screen;
+    score += 0.10 * closeness(entry.device_pixel_ratio, host.device_pixel_ratio);
+    score += 0.05 * closeness(entry.hardware_concurrency, host.hardware_concurrency);
+    score += 0.05 * closeness(entry.device_memory, host.device_memory);
+    // -- Freshness: full credit inside 6 months, decaying to zero at ~2 years.
+    let fresh = 0.5;
+    if (entry.captured_at) {
+        const days = (Date.now() - Date.parse(entry.captured_at)) / 86_400_000;
+        fresh = Number.isFinite(days) ? Math.max(0, Math.min(1, 1 - (days - 180) / 550)) : 0.5;
+    }
+    score += 0.10 * fresh;
+    return score;
+}
+/** Hard filters. A candidate failing any of these is not merely low-scoring — it is incoherent,
+ *  and no weight should be able to promote it back into the pool. */
+export function eligible(entry, host, opts = {}) {
+    const os = (opts.os ?? host.os_family).toLowerCase();
+    if (entry.os_family.toLowerCase() !== os)
+        return false;
+    // A version-agnostic profile (no browser_major) carries hardware identity only and inherits
+    // the engine's version, so it cannot contradict it — those pass. A profile that PINS a
+    // version and gets it wrong is a genuine contradiction: the UA would claim 138 while the
+    // engine's observable behaviour is 150. Those are rejected however well they score.
+    if (entry.browser_major != null && entry.browser_major !== host.browser_major)
+        return false;
+    const max = opts.maxEncodedSize ?? DEFAULT_MAX_ENCODED;
+    if (entry.encoded_size !== undefined && entry.encoded_size > max)
+        return false;
+    return true;
+}
+/** Stable 32-bit hash — used to map a stickiness key onto the candidate pool. */
+function keyHash(key) {
+    return parseInt(createHash("sha256").update(key).digest("hex").slice(0, 8), 16);
+}
+/**
+ * Pick a profile for this host.
+ *
+ * Throws when nothing is eligible rather than silently falling back to an incoherent profile —
+ * a wrong persona is worse than no persona, because it converts a clean browser into a
+ * contradictory one.
+ */
+export function selectProfile(index, host, opts = {}) {
+    const mode = opts.mode ?? "rotate";
+    const candidates = index.filter((e) => eligible(e, host, opts));
+    if (candidates.length === 0) {
+        const os = opts.os ?? host.os_family;
+        throw new Error(`no profile matches host (os=${os}, chromium major=${host.browser_major}). ` +
+            `The index has ${index.length} entries; none passed the os/major/size filters. ` +
+            `Sync a newer index, or pass an explicit fingerprintProfile.`);
+    }
+    const scored = candidates
+        .map((entry) => ({ entry, score: scoreProfile(entry, host) }))
+        // tie-break by id so the ordering is deterministic across runs and machines
+        .sort((a, b) => b.score - a.score || (a.entry.id < b.entry.id ? -1 : 1));
+    const poolSize = scored.length;
+    const n = Math.max(1, Math.min(opts.topN ?? DEFAULT_TOP_N, poolSize));
+    const pool = scored.slice(0, n);
+    let chosen;
+    if (mode === "best") {
+        chosen = pool[0];
+    }
+    else if (mode === "random") {
+        chosen = pool[Math.floor(Math.random() * pool.length)];
+    }
+    else {
+        // "rotate": sticky per key. With no key the caller still gets a STABLE profile rather than a
+        // new one each launch — an identity whose device changes every visit is a worse tell than a
+        // slightly-suboptimal fixed one. Callers wanting spread should pass a key.
+        const key = opts.key ?? defaultStickyKey();
+        chosen = pool[keyHash(key) % pool.length];
+    }
+    return { entry: chosen.entry, score: chosen.score, poolSize, mode };
+}
+/** A stable per-machine key, so keyless `"rotate"` is consistent rather than random. */
+let cachedStickyKey = null;
+export function defaultStickyKey() {
+    if (cachedStickyKey)
+        return cachedStickyKey;
+    const bits = [process.env.CLEARCOTE_PROFILE_KEY, process.env.USERNAME ?? process.env.USER, process.platform];
+    cachedStickyKey = createHash("sha256").update(bits.filter(Boolean).join("|")).digest("hex").slice(0, 16);
+    return cachedStickyKey;
+}
+//# sourceMappingURL=profilelib.js.map

package/dist/profilelib.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"profilelib.js","sourceRoot":"","sources":["../src/profilelib.ts"],"names":[],"mappings":"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"}

package/dist/profilesource.d.ts

@@ -0,0 +1,29 @@
+import { type HostFacts, type ProfileIndexEntry, type SelectOptions, type Selection } from "./profilelib.js";
+export interface ProfileSourceOptions extends SelectOptions {
+    licenseKey?: string;
+    apiBase?: string;
+    /** Skip the network entirely and use only what is already cached. */
+    offline?: boolean;
+}
+/** Map a Node platform string onto the os_family values the corpus stores. */
+export declare function hostOsFamily(): string;
+export declare function readCachedHost(exe: string): HostFacts | null;
+export declare function writeCachedHost(exe: string, facts: HostFacts): void;
+/** Read the host's real GPU/display by rendering in the engine itself, with no persona applied. */
+export declare function measureHost(launchFn: (opts: Record<string, unknown>) => Promise<{
+    newContext: () => Promise<{
+        newPage: () => Promise<unknown>;
+    }>;
+    close: () => Promise<void>;
+}>, exe: string, browserMajor: number): Promise<HostFacts>;
+/** Candidate index for a described host. Cached briefly so repeated launches do not re-ask. */
+export declare function fetchIndex(host: HostFacts, opts?: ProfileSourceOptions): Promise<ProfileIndexEntry[]>;
+/** Fetch one profile by id, preferring the on-disk copy — a repeat costs no distinct budget,
+ *  but not spending a request at all is better still. */
+export declare function fetchProfile(id: string, opts?: ProfileSourceOptions): Promise<Record<string, unknown>>;
+/** Resolve a persona end to end: index -> score against this host -> fetch the winner. */
+export declare function resolveAutoProfile(host: HostFacts, opts?: ProfileSourceOptions): Promise<{
+    profile: Record<string, unknown>;
+    selection: Selection;
+}>;
+//# sourceMappingURL=profilesource.d.ts.map