@swimmingliu/autovpn 1.8.0 → 2.0.2

package/dist/pipeline/apk-discovery.js

@@ -0,0 +1,504 @@
+import crypto from 'node:crypto';
+import zlib from 'node:zlib';
+const SEED_DOMAIN_PATTERN = /^(https?:\/\/www\.[a-z0-9]{3,14}\.(?:cc|info|com|net))(?::(\d+))?\/?$/;
+const PACKAGE_PATTERN = /^[a-zA-Z][\w]*(?:\.[\w]+){2,}$/;
+const VERSION_PATTERN = /^\d+\.\d+\.\d+$/;
+function readU16(buffer, offset) {
+    return offset + 2 <= buffer.length ? buffer.readUInt16LE(offset) : 0;
+}
+function readU32(buffer, offset) {
+    return offset + 4 <= buffer.length ? buffer.readUInt32LE(offset) : 0;
+}
+function decodeUleb128(buffer, start) {
+    let result = 0;
+    let shift = 0;
+    let offset = start;
+    while (offset < buffer.length) {
+        const byte = buffer[offset];
+        offset += 1;
+        result |= (byte & 0x7f) << shift;
+        if ((byte & 0x80) === 0) {
+            return { value: result >>> 0, next: offset };
+        }
+        shift += 7;
+        if (shift > 35) {
+            break;
+        }
+    }
+    return { value: result >>> 0, next: offset };
+}
+/** Reads the dex `string_ids` table: every string literal the app carries. */
+export function dexStrings(data) {
+    if (data.length < 0x70 || data.subarray(0, 4).toString('binary') !== 'dex\n') {
+        return [];
+    }
+    const stringIdsSize = readU32(data, 0x38);
+    const stringIdsOffset = readU32(data, 0x3c);
+    if (!stringIdsSize || stringIdsOffset + stringIdsSize * 4 > data.length) {
+        return [];
+    }
+    const out = [];
+    for (let index = 0; index < stringIdsSize; index += 1) {
+        const dataOffset = readU32(data, stringIdsOffset + index * 4);
+        if (!dataOffset || dataOffset >= data.length) {
+            continue;
+        }
+        const { next } = decodeUleb128(data, dataOffset);
+        const end = data.indexOf(0, next);
+        if (end < 0) {
+            continue;
+        }
+        out.push(data.subarray(next, end).toString('utf8'));
+    }
+    return out;
+}
+/** Reads selected zip entries by walking the central directory. */
+export function readZipEntries(zip, wanted) {
+    const out = new Map();
+    const minEocd = 22;
+    let eocd = -1;
+    for (let offset = zip.length - minEocd; offset >= Math.max(0, zip.length - 0xffff - minEocd); offset -= 1) {
+        if (readU32(zip, offset) === 0x06054b50) {
+            eocd = offset;
+            break;
+        }
+    }
+    if (eocd < 0) {
+        return out;
+    }
+    const entryCount = readU16(zip, eocd + 10);
+    let centralOffset = readU32(zip, eocd + 16);
+    for (let index = 0; index < entryCount; index += 1) {
+        if (centralOffset + 46 > zip.length || readU32(zip, centralOffset) !== 0x02014b50) {
+            break;
+        }
+        const method = readU16(zip, centralOffset + 10);
+        const compressedSize = readU32(zip, centralOffset + 20);
+        const uncompressedSize = readU32(zip, centralOffset + 24);
+        const nameLength = readU16(zip, centralOffset + 28);
+        const extraLength = readU16(zip, centralOffset + 30);
+        const commentLength = readU16(zip, centralOffset + 32);
+        const localOffset = readU32(zip, centralOffset + 42);
+        const name = zip.subarray(centralOffset + 46, centralOffset + 46 + nameLength).toString('utf8');
+        centralOffset += 46 + nameLength + extraLength + commentLength;
+        if (!wanted(name)) {
+            continue;
+        }
+        if (localOffset + 30 > zip.length || readU32(zip, localOffset) !== 0x04034b50) {
+            continue;
+        }
+        const dataStart = localOffset + 30 + readU16(zip, localOffset + 26) + readU16(zip, localOffset + 28);
+        const raw = zip.subarray(dataStart, dataStart + compressedSize);
+        if (raw.length !== compressedSize) {
+            continue;
+        }
+        if (method === 0) {
+            out.set(name, Buffer.from(raw));
+        }
+        else if (method === 8) {
+            try {
+                const inflated = zlib.inflateRawSync(raw, { maxOutputLength: Math.max(uncompressedSize, 1) });
+                if (inflated.length === uncompressedSize) {
+                    out.set(name, inflated);
+                }
+            }
+            catch {
+                // A corrupt entry must not abort discovery of the others.
+            }
+        }
+    }
+    return out;
+}
+/** AndroidManifest.xml is binary AXML; the string pool holds package and versionName. */
+export function axmlStrings(data) {
+    if (data.length < 8) {
+        return [];
+    }
+    if (readU16(data, 0) !== 0x0003) {
+        return [...data.toString('utf8').matchAll(/="([^"]*)"/g)].map((match) => match[1]);
+    }
+    const poolOffset = 8;
+    if (readU16(data, poolOffset) !== 0x0001) {
+        return [];
+    }
+    const stringCount = readU32(data, poolOffset + 8);
+    const flags = readU32(data, poolOffset + 16);
+    const stringsStart = readU32(data, poolOffset + 20);
+    const isUtf8 = (flags & 0x100) !== 0;
+    const base = poolOffset + stringsStart;
+    // `stringCount` comes from an untrusted file: a corrupt or hostile manifest
+    // can declare 0xFFFFFFFF entries and spin the loop for billions of
+    // iterations, which is synchronous and cannot be interrupted. The offset
+    // table is the real bound, so both must fit inside the buffer.
+    const maxStrings = Math.max(0, Math.floor((data.length - (poolOffset + 28)) / 4));
+    const boundedCount = Math.min(Number.isFinite(stringCount) ? stringCount : 0, maxStrings);
+    const out = [];
+    for (let index = 0; index < boundedCount; index += 1) {
+        const relative = readU32(data, poolOffset + 28 + index * 4);
+        let cursor = base + relative;
+        if (cursor >= data.length) {
+            continue;
+        }
+        try {
+            if (isUtf8) {
+                cursor = decodeUleb128(data, cursor).next;
+                const length = decodeUleb128(data, cursor);
+                cursor = length.next;
+                out.push(data.subarray(cursor, cursor + length.value).toString('utf8'));
+            }
+            else {
+                let length = readU16(data, cursor);
+                cursor += 2;
+                if (length & 0x8000) {
+                    length = ((length & 0x7fff) << 16) | readU16(data, cursor);
+                    cursor += 2;
+                }
+                out.push(data.subarray(cursor, cursor + length * 2).toString('utf16le'));
+            }
+        }
+        catch {
+            // Ignore malformed entries; the remaining pool is still usable.
+        }
+    }
+    return out;
+}
+/**
+ * The manifest string pool lists every literal, so the package name cannot be
+ * "the first com.* string" — permission constants and bundled SDK namespaces
+ * come first. The reliable source is the dex, which carries the package name
+ * itself (the `<manifest package>` value) as a plain literal, next to the
+ * `…action.activity` style prefixes it generates.
+ */
+export function manifestIdentity(axml, dexLiterals = []) {
+    const strings = axmlStrings(axml);
+    const versionName = strings.find((value) => VERSION_PATTERN.test(value)) ?? '';
+    // `<manifest package="x">` also appears in the manifest pool; prefer a value
+    // the dex independently repeats and that no permission constant shadows.
+    const manifestCandidates = strings.filter((value) => (PACKAGE_PATTERN.test(value)
+        && value.startsWith('com.')
+        && !/^com\.android\./.test(value)));
+    const dexSet = new Set(dexLiterals);
+    const confirmed = manifestCandidates
+        .filter((value) => dexSet.has(value) && dexLiterals.some((literal) => literal.startsWith(`${value}.action.`)))
+        .sort((left, right) => right.length - left.length);
+    if (confirmed.length > 0) {
+        return { package_name: confirmed[0], version_name: versionName };
+    }
+    // Second best: any dex literal shaped `com.<vendor>.<app><digits>`.
+    const shaped = dexLiterals
+        .filter((value) => /^com\.[a-z]+\.[a-z]+\d{6,}$/i.test(value))
+        .sort((left, right) => right.length - left.length);
+    if (shaped.length > 0) {
+        return { package_name: shaped[0], version_name: versionName };
+    }
+    return { package_name: manifestCandidates[0] ?? '', version_name: versionName };
+}
+/**
+ * Every 16-character ASCII literal in the dex is a control-plane key candidate.
+ *
+ * The key is not stored in plaintext (it is reassembled at runtime), but the
+ * constant it is assembled from is in the string pool, so the response itself
+ * decides which candidate is right: only the correct key turns the ciphertext
+ * into JSON. Trying the pool keeps discovery working when a vendor rotates the
+ * key, instead of relying on a hardcoded constant.
+ */
+export function controlPlaneKeyCandidates(strings) {
+    const out = [];
+    const seen = new Set();
+    for (const value of strings) {
+        if (value.length !== 16 || seen.has(value)) {
+            continue;
+        }
+        if (!/^[\x20-\x7e]{16}$/.test(value)) {
+            continue;
+        }
+        seen.add(value);
+        out.push(value);
+    }
+    return out;
+}
+export function certificateSha1(certificateDer) {
+    return crypto.createHash('sha1').update(certificateDer).digest('hex').toUpperCase();
+}
+/** Reads a DER TLV header, returning the value range and the total length. */
+function derTlv(buffer, offset) {
+    if (offset + 2 > buffer.length) {
+        return null;
+    }
+    const tag = buffer[offset];
+    let length = buffer[offset + 1];
+    let cursor = offset + 2;
+    if (length & 0x80) {
+        const lengthBytes = length & 0x7f;
+        if (lengthBytes === 0 || lengthBytes > 4 || cursor + lengthBytes > buffer.length) {
+            return null;
+        }
+        length = 0;
+        for (let index = 0; index < lengthBytes; index += 1) {
+            length = length * 256 + buffer[cursor + index];
+        }
+        cursor += lengthBytes;
+    }
+    const valueEnd = cursor + length;
+    if (valueEnd > buffer.length) {
+        return null;
+    }
+    return { tag, valueStart: cursor, valueEnd, next: valueEnd };
+}
+/**
+ * True when the DER value is structurally an X.509 Certificate:
+ *   Certificate ::= SEQUENCE { tbsCertificate SEQUENCE, signatureAlgorithm, signatureValue }
+ */
+function looksLikeX509(der) {
+    const outer = derTlv(der, 0);
+    if (!outer || outer.tag !== 0x30 || outer.valueEnd !== der.length) {
+        return false;
+    }
+    const tbs = derTlv(der, outer.valueStart);
+    if (!tbs || tbs.tag !== 0x30) {
+        return false;
+    }
+    // tbsCertificate is itself a SEQUENCE of at least version/serial/validity.
+    const first = derTlv(der, tbs.valueStart);
+    if (!first || tbs.valueEnd <= tbs.valueStart) {
+        return false;
+    }
+    // After tbsCertificate there must be two more elements (algorithm, signature).
+    const algorithm = derTlv(der, tbs.next);
+    const signature = algorithm ? derTlv(der, algorithm.next) : null;
+    return Boolean(algorithm && signature);
+}
+/**
+ * Extracts the signer certificate from a PKCS#7 SignedData blob.
+ *
+ * The blob nests several SEQUENCEs (SignedData, its `certificates` set, then the
+ * certificate itself), so picking by size is unreliable: at RSA-3072/4096 the
+ * SubjectPublicKeyInfo nested inside the certificate is longer than a smaller
+ * certificate and wins a "shortest" rule. The certificate is instead identified
+ * structurally — a DER SEQUENCE that parses exactly as `Certificate` with a
+ * TBSCertificate, an algorithm and a signature, all consuming the whole value.
+ * `certificates [0] IMPLICIT` means the set holds the certificates directly, so
+ * the first structural match in document order is the signer.
+ */
+export function firstCertificateFromPkcs7(pkcs7) {
+    const candidates = [];
+    const walk = (buffer, depth) => {
+        if (depth > 8) {
+            return;
+        }
+        for (let offset = 0; offset + 2 <= buffer.length; offset += 1) {
+            const tag = buffer[offset];
+            // Certificates are SEQUENCEs; skip everything else but keep scanning.
+            if (tag !== 0x30) {
+                continue;
+            }
+            const header = derTlv(buffer, offset);
+            if (!header || header.valueEnd <= header.valueStart) {
+                continue;
+            }
+            const candidate = buffer.subarray(offset, header.valueEnd);
+            if (candidate.length >= 0x80 && looksLikeX509(candidate)) {
+                candidates.push(Buffer.from(candidate));
+            }
+            walk(buffer.subarray(header.valueStart, header.valueEnd), depth + 1);
+            offset = header.valueEnd - 1;
+        }
+    };
+    walk(pkcs7, 0);
+    return candidates[0] ?? null;
+}
+/** Hosts shipped as documentation samples, never a control-plane seed. */
+const SAMPLE_HOSTS = new Set(['www.example.com', 'www.google.com', 'example.com', 'google.com']);
+/**
+ * Seed domains are the `https://www.<label>.<tld>:20000` literals the dex
+ * carries; they are what `getApiDomain()` picks between and what
+ * `/api/eversion` answers on. The control-plane port is the filter that
+ * separates them from the sample hosts bundled in third-party libraries.
+ */
+export function seedDomains(strings) {
+    const candidates = [];
+    for (const value of strings) {
+        const match = SEED_DOMAIN_PATTERN.exec(value.trim());
+        if (!match || SAMPLE_HOSTS.has(match[1].replace(/^https?:\/\//, ''))) {
+            continue;
+        }
+        const normalized = `${match[1]}:${match[2] ?? '20000'}`;
+        if (!candidates.includes(normalized)) {
+            candidates.push(normalized);
+        }
+    }
+    return candidates.filter((value) => value.endsWith(':20000'));
+}
+export function apkDiscoveryFromBytes(apk, apkUrl) {
+    const entries = readZipEntries(apk, (name) => (name === 'AndroidManifest.xml'
+        || name.endsWith('.dex')
+        || (name.startsWith('META-INF/') && /\.(RSA|DSA|EC)$/i.test(name))));
+    const manifest = entries.get('AndroidManifest.xml');
+    const strings = [];
+    for (const [name, data] of entries) {
+        if (name.endsWith('.dex')) {
+            // A spread here overflows the call stack: one dex routinely carries more
+            // literals than the argument limit allows.
+            for (const value of dexStrings(data)) {
+                strings.push(value);
+            }
+        }
+    }
+    const identity = manifest
+        ? manifestIdentity(manifest, strings)
+        : { package_name: '', version_name: '' };
+    const joined = strings.join('\n');
+    let certSha1 = '';
+    for (const [name, data] of [...entries].sort(([left], [right]) => left.localeCompare(right))) {
+        if (!/\.(RSA|DSA|EC)$/i.test(name)) {
+            continue;
+        }
+        const certificate = firstCertificateFromPkcs7(data);
+        if (certificate) {
+            certSha1 = certificateSha1(certificate);
+            break;
+        }
+    }
+    return {
+        apk_url: apkUrl,
+        key_candidates: controlPlaneKeyCandidates(strings),
+        package_name: identity.package_name,
+        version_name: identity.version_name,
+        cert_sha1: certSha1,
+        seed_domains: seedDomains(strings),
+        protocol: `v${/proto=v(\d+)/.exec(joined)?.[1] ?? '7'}`,
+        core_version: /&core=([\d.]+)/.exec(joined)?.[1] ?? '5.12.1',
+        lite_version: /lite=([\d.]+)/.exec(joined)?.[1] ?? '5.29.4'
+    };
+}
+/**
+ * The download page loads a per-brand `cdn.js` that declares `cdnurl` (and often
+ * `cdnurl2`) plus `apk_interval`. That interval is the archive cadence in minutes.
+ */
+export function parseCdnConfig(source) {
+    const hosts = [];
+    for (const name of ['cdnurl', 'cdnurl2']) {
+        const match = new RegExp(`(?:var|let|const)\\s+${name}\\s*=\\s*["']([^"']*)["']`).exec(source);
+        const value = match ? match[1].trim().replace(/\/+$/, '') : '';
+        if (value && !hosts.includes(value)) {
+            hosts.push(value);
+        }
+    }
+    const intervalMatch = /(?:var|let|const)\s+apk_interval\s*=\s*(\d+)/.exec(source);
+    return {
+        download_hosts: hosts,
+        apk_interval_minutes: intervalMatch ? Number.parseInt(intervalMatch[1], 10) : 0
+    };
+}
+/**
+ * The download page names its route chunks; Vite's dep map is the reliable list.
+ *
+ * Sites split their routes into lazy chunks (`TheAndriod`, `mf-pages-android`,
+ * …), so the Android downloader is not the page's own entry bundle. The dep map
+ * and the direct script tags together cover both shapes.
+ */
+export function androidChunkUrls(html, baseUrl) {
+    const urls = [];
+    const add = (reference) => {
+        try {
+            const absolute = new URL(reference, `${baseUrl.replace(/\/+$/, '')}/`).toString();
+            if (!urls.includes(absolute)) {
+                urls.push(absolute);
+            }
+        }
+        catch {
+            // Ignore references that cannot be resolved against the site.
+        }
+    };
+    const depMap = /m\.f=\[([^\]]+)\]/.exec(html);
+    if (depMap) {
+        for (const match of depMap[1].matchAll(/"([^"]+\.js)"/g)) {
+            add(match[1]);
+        }
+    }
+    for (const match of html.matchAll(/(?:src|href)="([^"]+\.js[^"]*)"/g)) {
+        add(match[1]);
+    }
+    return urls;
+}
+/** Sites whose `cdn.js` is served at the root and needs a cache-busting stamp. */
+export function cdnConfigUrls(baseUrl, timestampMs) {
+    const base = baseUrl.replace(/\/+$/, '');
+    return [`${base}/cdn.js?t=${Math.floor(timestampMs / 1000)}`, `${base}/cdn.js`];
+}
+/**
+ * Some sites inline the download formula in the Android chunk (fixed host and
+ * cadence), others load a separate `cdn.js`. Both shapes are recognised here.
+ */
+export function cdnReferencesFromChunk(source, chunkUrl) {
+    const references = [];
+    for (const match of source.matchAll(/["'`](\/assets\/[^"'`]*cdn[^"'`]*\.js[^"'`]*)["'`]/gi)) {
+        references.push({
+            url: new URL(match[1], chunkUrl).toString(),
+            apk_interval_minutes: 0
+        });
+    }
+    return references;
+}
+/**
+ * Fixed-host variant: the chunk hardcodes the download origin and computes the
+ * slot inline, e.g. `https://wpk.example.com/apks64/DATE_mfSLOT.apk`.
+ */
+export function inlineDownloadSpec(source) {
+    // The port is part of the origin: a brand publishing `http://cdn:8080/`
+    // would otherwise be reduced to a bare host that answers nothing.
+    const hostMatch = /(https?):\/\/([a-z0-9.-]+(?::\d+)?)\/apks64\//i.exec(source);
+    // The filename is assembled at runtime (`'…_mf'+index+'apk'`), so the prefix
+    // is read from the literal fragment rather than a complete `.apk` path.
+    const fileMatch = /apks64\/[^"'`+]*_([a-z]{2,6})["'`+]?\s*\+\s*index/i.exec(source)
+        ?? /apks64\/[^"'`]*_([a-z]{2,6})\d*\.apk/i.exec(source);
+    if (!hostMatch || !fileMatch) {
+        return null;
+    }
+    const intervalMatch = /getHours\(\)\s*\*\s*(\d+)\s*\+\s*Math\.floor\(\s*[^)]*getMinutes\(\)\s*\/\s*(\d+)\s*\)/.exec(source);
+    return {
+        host: `${hostMatch[1].toLowerCase()}://${hostMatch[2]}`,
+        prefix: fileMatch[1].toLowerCase(),
+        interval_minutes: intervalMatch ? Number.parseInt(intervalMatch[2], 10) : 0
+    };
+}
+/**
+ * Time-sliced archive slot for one moment.
+ *
+ * The apps publish a fresh APK every `interval` minutes; the archive index is
+ * `hours * (60 / interval) + floor(minutes / interval)`.
+ */
+export function apkSlot(now, intervalMinutes) {
+    const interval = Math.max(1, intervalMinutes);
+    return now.getHours() * Math.floor(60 / interval) + Math.floor(now.getMinutes() / interval);
+}
+export function apkFileName(now, prefix, slot) {
+    const pad = (value) => String(value).padStart(2, '0');
+    const day = `${now.getFullYear()}${pad(now.getMonth() + 1)}${pad(now.getDate())}`;
+    return `${day}_${prefix}${slot}.apk`;
+}
+/**
+ * Candidate URLs for now and the preceding slots.
+ *
+ * The newest slot is frequently not published yet, so the walk goes backwards;
+ * it also wraps to the previous day because slot numbering restarts at midnight.
+ */
+export function candidateApkUrls(hosts, prefix, now, intervalMinutes, lookbackSlots = 8) {
+    const interval = Math.max(1, intervalMinutes);
+    const urls = [];
+    for (let step = 0; step < lookbackSlots; step += 1) {
+        const stamp = new Date(now.getTime() - step * interval * 60_000);
+        const name = apkFileName(stamp, prefix, apkSlot(stamp, interval));
+        for (const host of hosts) {
+            urls.push(`${host.replace(/\/+$/, '')}/apks64/${name}`);
+        }
+        if (stamp.getHours() === 0 && stamp.getMinutes() < interval) {
+            const previous = new Date(stamp.getTime() - 60 * 60_000);
+            const tail = apkFileName(previous, prefix, apkSlot(previous, interval));
+            for (const host of hosts) {
+                urls.push(`${host.replace(/\/+$/, '')}/apks64/${tail}`);
+            }
+        }
+    }
+    return urls;
+}

package/dist/pipeline/brand-cache.js

@@ -0,0 +1,126 @@
+import fs from 'node:fs';
+import path from 'node:path';
+const DEFAULT_MAX_AGE_MS = 24 * 60 * 60 * 1000;
+/**
+ * File name for one brand's fingerprint.
+ *
+ * Brand keys are Chinese product names, which `[^\w.-]` would collapse to a
+ * single underscore; the code-point hex keeps them distinct and filesystem-safe.
+ */
+function cachePath(cacheDir, brand) {
+    const safe = [...String(brand)].map((char) => (/[\w.-]/.test(char) ? char : `u${char.codePointAt(0)?.toString(16)}`)).join('');
+    return path.join(cacheDir, `brand-${safe}.json`);
+}
+export /**
+ * A cache entry is only usable when every field the flow dereferences has the
+ * right shape. A parseable file with, say, `seed_domains: [12345]` would
+ * otherwise reach `String.prototype.replace` and crash the run before any
+ * network call — and keep crashing on every later run, since the cache is only
+ * invalidated when the seeds stop answering.
+ */ function isUsableFingerprint(payload) {
+    if (!payload || typeof payload !== 'object') {
+        return false;
+    }
+    const value = payload;
+    const seeds = value.seed_domains;
+    if (!Array.isArray(seeds) || seeds.length === 0) {
+        return false;
+    }
+    if (!seeds.every((seed) => typeof seed === 'string' && seed.trim().length > 0)) {
+        return false;
+    }
+    for (const field of ['package_name', 'version_name', 'cert_sha1', 'apk_url']) {
+        if (typeof value[field] !== 'string') {
+            return false;
+        }
+    }
+    return true;
+}
+export class FingerprintStore {
+    cacheDir;
+    now;
+    maxAgeMs;
+    constructor(options) {
+        this.cacheDir = options.cacheDir;
+        this.now = options.now ?? (() => new Date());
+        this.maxAgeMs = options.maxAgeMs ?? DEFAULT_MAX_AGE_MS;
+    }
+    read(brand) {
+        const file = cachePath(this.cacheDir, brand);
+        if (!fs.existsSync(file)) {
+            return null;
+        }
+        try {
+            const payload = JSON.parse(fs.readFileSync(file, 'utf8'));
+            return isUsableFingerprint(payload) ? payload : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Returns a fingerprint when it is present and still within its trust window. */
+    /**
+     * Returns the fingerprint when it is still inside its trust window.
+     *
+     * A stale entry still carries usable seed domains, so callers fall back to
+     * `read()` and only re-inspect the APK when the seeds stop answering.
+     */
+    readFresh(brand) {
+        const payload = this.read(brand);
+        if (!payload) {
+            return null;
+        }
+        const verifiedAt = Date.parse(String(payload.verified_at ?? ''));
+        if (!Number.isFinite(verifiedAt)) {
+            return null;
+        }
+        return this.now().getTime() - verifiedAt <= this.maxAgeMs ? payload : null;
+    }
+    write(brand, discovery) {
+        const payload = {
+            ...discovery,
+            brand,
+            verified_at: this.now().toISOString()
+        };
+        // The cache is an optimisation: a read-only or full directory, or a disk
+        // error, must not fail a run that already has a working fingerprint.
+        try {
+            fs.mkdirSync(this.cacheDir, { recursive: true });
+            // Write to a sibling and rename, so a crash mid-write cannot leave a
+            // truncated file that later parses as a broken fingerprint.
+            const target = cachePath(this.cacheDir, brand);
+            const temporary = `${target}.${process.pid}.${Date.now()}.tmp`;
+            fs.writeFileSync(temporary, `${JSON.stringify(payload, null, 2)}\n`, 'utf8');
+            fs.renameSync(temporary, target);
+        }
+        catch {
+            // Deliberately ignored; see above.
+        }
+        return payload;
+    }
+    /** Records that a cached fingerprint still works, without re-reading the APK. */
+    touch(brand) {
+        const payload = this.read(brand);
+        if (!payload) {
+            return;
+        }
+        this.write(brand, payload);
+    }
+    /** Drops a fingerprint so the next run re-inspects the APK. */
+    clear(brand) {
+        try {
+            fs.rmSync(cachePath(this.cacheDir, brand), { force: true });
+        }
+        catch {
+            // The cache is an optimisation; failing to delete it must not fail a run.
+        }
+    }
+}
+/**
+ * The cache lives under the runtime root, beside the profile but as its own
+ * directory. Nothing clears it automatically: an entry is replaced when a run
+ * re-inspects the APK, and dropped when a cached fingerprint stops working.
+ */
+export function resolveFingerprintCacheDir(runtimeRoot) {
+    return path.join(runtimeRoot, 'brand-fingerprints');
+}