@memlab/core 2.0.3 → 2.0.5

package/dist/lib/HeapAnonymizer.js

@@ -0,0 +1,670 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @format
+ * @lightSyntaxTransform
+ * @oncall memory_lab
+ */
+'use strict';
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.anonymizeHeapSnapshot = anonymizeHeapSnapshot;
+exports.anonymizeRawHeapSnapshot = anonymizeRawHeapSnapshot;
+exports.readRawHeapSnapshot = readRawHeapSnapshot;
+exports.anonymizeHeapSnapshotFile = anonymizeHeapSnapshotFile;
+exports.auditHeapSnapshotFile = auditHeapSnapshotFile;
+exports.resolveForComparison = resolveForComparison;
+const crypto_1 = __importDefault(require("crypto"));
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const StringLoader_1 = __importDefault(require("./StringLoader"));
+const HeapSerializer_1 = require("./HeapSerializer");
+const DEFAULT_MIN_DIGIT_RUN = 9;
+/**
+ * Content rules applied to EVERY string table entry, label or not.
+ *
+ * Deliberately shape-based and application-agnostic: an anchored word list
+ * would be a list of the leaks someone already thought of. `\d{9,}` is
+ * unanchored on purpose — it is what catches an identifier embedded in a
+ * composite key, which is the common shape for a per-contact or per-session
+ * map key.
+ *
+ * URLs are NOT in this list. Script URLs are how `module attribution` and
+ * script census name the code that owns memory, so redacting them would remove
+ * a primary analysis while catching data that is, as a string VALUE, already
+ * redacted by the node-type rule. A URL carrying a token in its query string is
+ * a real residual; it is reported as such rather than silently handled.
+ */
+/**
+ * A caller's regex may carry `/g` or `/y`, whose `lastIndex` makes `test`
+ * alternate between true and false on identical input. Rebuilt without them so
+ * the same value always classifies the same way.
+ */
+function withoutStatefulFlags(pattern) {
+    return new RegExp(pattern.source, pattern.flags.replace(/[gy]/g, ''));
+}
+function buildContentRules(options) {
+    var _a, _b, _c;
+    const rules = [];
+    if (options.redactDomText !== false) {
+        rules.push({
+            name: 'dom-text',
+            // Blink element descriptions and any serialized markup.
+            test: v => /^\s*<[a-zA-Z!/]/.test(v),
+        });
+    }
+    if (options.redactIdentifierKeys !== false) {
+        const minRun = (_a = options.minDigitRunLength) !== null && _a !== void 0 ? _a : DEFAULT_MIN_DIGIT_RUN;
+        // Interpolated straight into a quantifier, so an out-of-range value is not
+        // a mild misconfiguration: `0` yields `\d{0,}`, which matches EVERY string
+        // and would redact the entire label vocabulary -- silently, since the run
+        // would look successful. A negative or fractional value throws a
+        // SyntaxError from deep inside RegExp construction instead of naming the
+        // option that was wrong. Rejecting here fails loudly and early.
+        if (!Number.isInteger(minRun) || minRun < 1) {
+            throw new Error(`minDigitRunLength must be a positive integer, got: ${String(minRun)}. ` +
+                `A value below 1 matches every string and would redact the whole ` +
+                `label vocabulary.`);
+        }
+        const digitRun = new RegExp(`\\d{${minRun},}`);
+        rules.push({
+            // Named for the shape, not for email: `local@domain.tld` is also the
+            // shape of a federated handle, and on one real capture that is what
+            // most of the matches were. Calling the rule `email` would have
+            // under-reported what it actually removed.
+            name: 'email-or-handle',
+            test: v => /^[^\s@]+@[^\s@]+\.[A-Za-z]{2,}$/.test(v),
+        }, {
+            name: 'credential',
+            test: v => /^(Bearer\s|eyJ[A-Za-z0-9_-]{8,}\.)/.test(v),
+        }, { name: 'data-uri', test: v => /^data:[\w.+-]+\/[\w.+-]+[;,]/i.test(v) }, {
+            name: 'long-base64',
+            // Mixed case AND a digit are required, not just the base64 character
+            // set. Real base64 of real bytes has both; a long single-case run is
+            // far more likely to be a module path segment, a minified identifier —
+            // or this tool's own replacement text, which must not re-match on a
+            // second pass or in an audit.
+            test: v => v.length >= 40 &&
+                /^[A-Za-z0-9+/]+={0,2}$/.test(v) &&
+                /[A-Z]/.test(v) &&
+                /[a-z]/.test(v) &&
+                /[0-9]/.test(v),
+        }, { name: 'digit-run', test: v => digitRun.test(v) });
+    }
+    for (let i = 0; i < ((_c = (_b = options.extraPatterns) === null || _b === void 0 ? void 0 : _b.length) !== null && _c !== void 0 ? _c : 0); ++i) {
+        // Compiled ONCE, here, not inside `test`. `test` runs for every entry in
+        // the string table -- 732,455 of them on one real capture -- so compiling
+        // inside the closure would recompile the same pattern once per entry per
+        // caller pattern.
+        const compiled = withoutStatefulFlags(options.extraPatterns[i]);
+        rules.push({
+            name: `extra-pattern-${i + 1}`,
+            test: v => compiled.test(v),
+        });
+    }
+    return rules;
+}
+/**
+ * Length-preserving replacement text.
+ *
+ * Length is preserved in UTF-16 code units so `self_size` keeps agreeing with
+ * the string it describes — V8 sizes a one-byte string at `align4(12 + length)`,
+ * and a reader that checks will otherwise see a corrupt capture. The output is
+ * ASCII, so it can never be longer in bytes than what it replaces.
+ */
+function redactedText(value, mode, salt) {
+    const len = value.length;
+    if (len === 0) {
+        return value;
+    }
+    if (mode === 'uniform') {
+        return '?'.repeat(len);
+    }
+    // Lowercase letters only, NOT hex. Replacement text is scanned by the very
+    // content rules that decide what is sensitive, so digit-bearing fill makes
+    // the tool's own output look like the thing it removes: with hex fill a real
+    // capture still reported 17,837 entries carrying a 9-digit run AFTER
+    // anonymization, essentially all of them replacements rather than leaks. A
+    // digit-free alphabet is what keeps a reported residual meaningful.
+    // Filled into a preallocated array and joined once, rather than accumulated
+    // with `+=`. The values being replaced include serialized DOM node names that
+    // reach tens of kilobytes, so this loop runs per character of the longest
+    // string in the capture; it also stops exactly at `len` instead of
+    // overshooting by up to a digest and slicing the remainder away.
+    const chars = new Array(len);
+    let filled = 0;
+    let counter = 0;
+    while (filled < len) {
+        const digest = crypto_1.default
+            .createHash('sha256')
+            .update(salt)
+            .update(' ')
+            .update(value)
+            .update(` ${counter++}`)
+            .digest();
+        for (let i = 0; i < digest.length && filled < len; ++i) {
+            chars[filled++] =
+                REDACTION_ALPHABET[digest[i] % REDACTION_ALPHABET.length];
+        }
+    }
+    return chars.join('');
+}
+const REDACTION_ALPHABET = 'abcdefghijklmnopqrstuvwxyz';
+/**
+ * Record width implied by the DATA, not by the declared field list.
+ *
+ * `HeapSnapshot._buildMetaData` appends `'invisible'` to `meta.edge_fields` in
+ * place while parsing, so a parsed snapshot claims one more edge field than its
+ * edge array actually carries. Striding by the declared count reads every edge
+ * misaligned — and silently, since the numbers still look like numbers.
+ */
+function fittedFieldCount(values, recordCount, declared) {
+    if (recordCount <= 0) {
+        return declared;
+    }
+    const width = values.length / recordCount;
+    return Number.isInteger(width) && width > 0 ? width : declared;
+}
+/** Rule name reported for entries the caller's own callback selected. */
+const CUSTOM_RULE = 'custom-callback';
+/** Kept distinct from the positional built-in rule indices. */
+const CUSTOM_RULE_ID = 1 << 30;
+const MAX_REPORTED_FAMILIES = 12;
+const MAX_FAMILY_EXAMPLES = 3;
+/**
+ * Coarse shape of a string: character classes, with runs collapsed.
+ *
+ * `7ac91e02-11bd-4c7f` and `0f31ba77-92cd-4e10` both reduce to `dada-dada-dada`
+ * -ish, while `enableFastPath` reduces to `aAaAa`. Separators survive
+ * literally, because they are what makes a generated format recognizable.
+ */
+function shapeSignature(value) {
+    let out = '';
+    let last = '';
+    const limit = Math.min(value.length, 48);
+    for (let i = 0; i < limit; ++i) {
+        const c = value[i];
+        let cls;
+        if (c >= '0' && c <= '9') {
+            cls = 'd';
+        }
+        else if (c >= 'a' && c <= 'z') {
+            cls = 'a';
+        }
+        else if (c >= 'A' && c <= 'Z') {
+            cls = 'A';
+        }
+        else {
+            cls = c;
+        }
+        if (cls !== last) {
+            out += cls;
+            last = cls;
+        }
+    }
+    return out;
+}
+/**
+ * Group the labels still in the clear into machine-generated-looking families.
+ *
+ * Two exclusions, both engine-level facts rather than judgements about any
+ * application:
+ *
+ * - **Pure digit strings.** V8 emits an exhaustive run of numeric index names
+ *   (`"0"`..`"9"`, `"10"`..`"99"`, and so on); they are array indices by
+ *   construction, and on one capture they were 133,226 of the labels, which
+ *   would bury everything else.
+ * - **Retainer descriptors.** Strings of the form `N / part of key (...) ->
+ *   value (...)` are written by the snapshot serializer to describe WeakMap
+ *   entries. They are diagnostics, never application data.
+ *
+ * What remains is filtered to shapes that carry a digit or a separator. A shape
+ * built only from letters, `_` and `$` is the shape of source-code vocabulary
+ * in every language, so surfacing those would make the report mostly noise —
+ * and unlike a redaction rule, being wrong here only costs a line of output.
+ */
+function collectUnclassifiedLabelFamilies(strings, isLabel, contentRule, limit) {
+    const families = new Map();
+    const vocabularyShape = /^[aA_$]+$/;
+    for (let i = 0; i < isLabel.length; ++i) {
+        if (!isLabel[i] || contentRule[i] >= 0) {
+            continue;
+        }
+        const value = strings[i];
+        if (value.length === 0 || /^\d+$/.test(value) || /^\d+ \/ /.test(value)) {
+            continue;
+        }
+        const shape = shapeSignature(value);
+        if (vocabularyShape.test(shape)) {
+            continue;
+        }
+        let entry = families.get(shape);
+        if (entry == null) {
+            entry = { count: 0, examples: [] };
+            families.set(shape, entry);
+        }
+        entry.count++;
+        if (entry.examples.length < MAX_FAMILY_EXAMPLES) {
+            entry.examples.push(value);
+        }
+    }
+    return [...families]
+        .map(([shape, { count, examples }]) => ({ shape, count, examples }))
+        .sort((a, b) => b.count - a.count)
+        .slice(0, limit);
+}
+/**
+ * Read the node layout out of the snapshot's own meta rather than assuming it.
+ *
+ * Field order and the node type list are both snapshot-declared and differ
+ * between engines and V8 versions (a browser capture has 6 node fields, a
+ * Node.js one has 7).
+ */
+function readLayout(raw) {
+    const meta = raw.snapshot.meta;
+    const nodeFields = meta.node_fields;
+    const nodeTypeOffset = nodeFields.indexOf('type');
+    const nodeTypes = meta.node_types[nodeTypeOffset];
+    const stringNodeTypes = new Set();
+    for (const name of ['string', 'concatenated string', 'sliced string']) {
+        const idx = nodeTypes.indexOf(name);
+        if (idx >= 0) {
+            stringNodeTypes.add(idx);
+        }
+    }
+    const edgeFields = meta.edge_fields;
+    const edgeTypeOffset = edgeFields.indexOf('type');
+    const edgeTypes = meta.edge_types[edgeTypeOffset];
+    // For `element` and `hidden` edges `name_or_index` is an integer index; for
+    // every other type it is an index into the string table.
+    const indexNamedEdgeTypes = new Set();
+    for (const name of ['element', 'hidden']) {
+        const idx = edgeTypes.indexOf(name);
+        if (idx >= 0) {
+            indexNamedEdgeTypes.add(idx);
+        }
+    }
+    return {
+        nodeFieldsCount: fittedFieldCount(raw.nodes, raw.snapshot.node_count, nodeFields.length),
+        nodeTypeOffset,
+        nodeNameOffset: nodeFields.indexOf('name'),
+        stringNodeTypes,
+        edgeFieldsCount: fittedFieldCount(raw.edges, raw.snapshot.edge_count, edgeFields.length),
+        edgeTypeOffset,
+        edgeNameOffset: edgeFields.indexOf('name_or_index'),
+        indexNamedEdgeTypes,
+    };
+}
+/**
+ * Rewrite a parsed heap snapshot in place so it no longer carries user data.
+ *
+ * Redacts the content of every string on the heap, plus any string table entry
+ * whose text looks like an identifier, a credential or serialized DOM. Class
+ * names, function names and ordinary property keys are left alone, so retainer
+ * traces, class histograms, dominator trees and shape analyses all still work
+ * on the result.
+ *
+ * The snapshot is modified in place and its parsed view updates with it — node
+ * names are read from the string table on each access rather than cached.
+ * Persist the result with {@link serializeHeapSnapshot}.
+ *
+ * This does not defeat a determined attacker who already knows what they are
+ * looking for: lengths are preserved exactly (they have to be, or `self_size`
+ * stops matching), and in `stable` mode equal values stay equal. It removes the
+ * content, not the shape of the content.
+ *
+ * @param snapshot the parsed heap snapshot to rewrite in place
+ * @param options see {@link AnonymizeOptions}
+ * @returns a summary of what was redacted, per rule; see
+ * {@link AnonymizeReport}
+ *
+ * * **Examples**:
+ * ```typescript
+ * import type {IHeapSnapshot} from '@memlab/core';
+ * import {
+ *   dumpNodeHeapSnapshot,
+ *   anonymizeHeapSnapshot,
+ *   serializeHeapSnapshot,
+ * } from '@memlab/core';
+ * import {getFullHeapFromFile} from '@memlab/heap-analysis';
+ *
+ * (async function () {
+ *   const file = dumpNodeHeapSnapshot();
+ *   const heap: IHeapSnapshot = await getFullHeapFromFile(file);
+ *
+ *   const report = anonymizeHeapSnapshot(heap);
+ *   console.log(`redacted ${report.valuesRedacted} string values`);
+ *
+ *   serializeHeapSnapshot(heap, '/tmp/shareable.heapsnapshot');
+ * })();
+ * ```
+ */
+function anonymizeHeapSnapshot(snapshot, options = {}) {
+    return anonymizeRawHeapSnapshot(snapshot.snapshot, options);
+}
+/**
+ * The in-place rewrite, against the raw snapshot data.
+ *
+ * @param raw the raw snapshot data to rewrite
+ * @param options see {@link AnonymizeOptions}
+ * @returns a summary of what was redacted; see {@link AnonymizeReport}
+ *
+ * @internal
+ */
+function anonymizeRawHeapSnapshot(raw, options = {}) {
+    var _a, _b, _c, _d, _e;
+    const mode = (_a = options.mode) !== null && _a !== void 0 ? _a : 'stable';
+    const salt = (_b = options.salt) !== null && _b !== void 0 ? _b : '';
+    const strings = raw.strings;
+    const layout = readLayout(raw);
+    const rules = buildContentRules(options);
+    // Same reason as the extra patterns: this is consulted once per string table
+    // entry, so the sanitized regexes are built here rather than in the loop.
+    const keep = ((_c = options.keepPatterns) !== null && _c !== void 0 ? _c : []).map(withoutStatefulFlags);
+    const { nodeFieldsCount, nodeTypeOffset, nodeNameOffset, stringNodeTypes, edgeFieldsCount, edgeTypeOffset, edgeNameOffset, indexNamedEdgeTypes, } = layout;
+    // Classify every string table entry by HOW IT IS REACHED. The table is
+    // deduplicated, so one entry can be reached both ways at once, and the two
+    // roles need opposite treatment.
+    const nodes = raw.nodes;
+    const isStringValue = new Uint8Array(strings.length);
+    const isLabel = new Uint8Array(strings.length);
+    for (let i = 0; i < nodes.length; i += nodeFieldsCount) {
+        const nameIdx = nodes[i + nodeNameOffset];
+        if (stringNodeTypes.has(nodes[i + nodeTypeOffset])) {
+            // the CONTENT of a JS string on the heap: data
+            isStringValue[nameIdx] = 1;
+        }
+        else {
+            // a class name, function name, or engine-internal name: a label
+            isLabel[nameIdx] = 1;
+        }
+    }
+    const edges = raw.edges;
+    const nameUseCount = new Uint32Array(strings.length);
+    for (let i = 0; i < edges.length; i += edgeFieldsCount) {
+        if (!indexNamedEdgeTypes.has(edges[i + edgeTypeOffset])) {
+            // a property key, closure variable, or context slot name: a label
+            const nameIdx = edges[i + edgeNameOffset];
+            isLabel[nameIdx] = 1;
+            if (nameUseCount[nameIdx] < 0xffffffff) {
+                nameUseCount[nameIdx]++;
+            }
+        }
+    }
+    const ruleCounts = new Map();
+    // -1 = not content-sensitive; CUSTOM_RULE_ID for the caller's callback;
+    // otherwise the index of the matching built-in rule.
+    const contentRule = new Int32Array(strings.length).fill(-1);
+    // Entries the caller explicitly protected. Tracked separately from
+    // `contentRule` because protection has to reach the string-VALUE pass below,
+    // which does not consult the content rules at all: `keepPatterns` promises
+    // an entry is NEVER redacted, and `shouldRedact` returning false promises the
+    // same, so honouring either only for content rules would break both
+    // contracts for exactly the entries a caller cared enough to name.
+    const protectedEntry = new Uint8Array(strings.length);
+    const shouldRedact = options.shouldRedact;
+    let contentRedacted = 0;
+    for (let i = 0; i < strings.length; ++i) {
+        const value = strings[i];
+        if (value.length === 0) {
+            continue;
+        }
+        if (shouldRedact != null) {
+            // Asked first, and its answer is final either way. The caller knows their
+            // own application; the built-in rules only know internet formats.
+            const verdict = shouldRedact(value, {
+                isValue: isStringValue[i] === 1,
+                isLabel: isLabel[i] === 1,
+                labelUseCount: nameUseCount[i],
+                shape: shapeSignature(value),
+            });
+            if (verdict === true) {
+                contentRule[i] = CUSTOM_RULE_ID;
+                contentRedacted++;
+                ruleCounts.set(CUSTOM_RULE, ((_d = ruleCounts.get(CUSTOM_RULE)) !== null && _d !== void 0 ? _d : 0) + 1);
+                continue;
+            }
+            if (verdict === false) {
+                protectedEntry[i] = 1;
+                continue;
+            }
+        }
+        if (keep.some(p => p.test(value))) {
+            protectedEntry[i] = 1;
+            continue;
+        }
+        for (let r = 0; r < rules.length; ++r) {
+            if (rules[r].test(value)) {
+                contentRule[i] = r;
+                contentRedacted++;
+                ruleCounts.set(rules[r].name, ((_e = ruleCounts.get(rules[r].name)) !== null && _e !== void 0 ? _e : 0) + 1);
+                break;
+            }
+        }
+    }
+    // Content matches are redacted where they stand, because the value is
+    // sensitive wherever it appears — including as a property name.
+    for (let i = 0; i < strings.length; ++i) {
+        if (contentRule[i] >= 0) {
+            strings[i] = redactedText(strings[i], mode, salt);
+        }
+    }
+    // Now the string values. Which of two treatments applies turns on whether
+    // the same entry is ALSO a label:
+    //
+    //   value only  -> redact the entry in place. Splitting here would be a leak,
+    //                  not a safeguard: repointing the node at a redacted twin
+    //                  leaves the original entry sitting in the table with the
+    //                  plaintext still in it. Nothing references it, but the
+    //                  bytes are in the file, which is all an attacker needs.
+    //   value+label -> append a redacted twin and repoint only the string node,
+    //                  so the label keeps its text. Overwriting in place would
+    //                  destroy a property or class name that merely happens to
+    //                  share the deduplicated entry.
+    const twinOf = new Int32Array(strings.length).fill(-1);
+    let valuesRedacted = 0;
+    let entriesSplit = 0;
+    const originalTableSize = strings.length;
+    for (let i = 0; i < originalTableSize; ++i) {
+        if (!isStringValue[i] ||
+            isLabel[i] ||
+            contentRule[i] >= 0 ||
+            protectedEntry[i]) {
+            continue;
+        }
+        if (strings[i].length === 0) {
+            continue;
+        }
+        strings[i] = redactedText(strings[i], mode, salt);
+        valuesRedacted++;
+    }
+    for (let i = 0; i < nodes.length; i += nodeFieldsCount) {
+        if (!stringNodeTypes.has(nodes[i + nodeTypeOffset])) {
+            continue;
+        }
+        const nameIdx = nodes[i + nodeNameOffset];
+        if (!isLabel[nameIdx] ||
+            contentRule[nameIdx] >= 0 ||
+            protectedEntry[nameIdx] ||
+            strings[nameIdx].length === 0) {
+            // redacted in place above, redacted by content, or nothing to redact
+            continue;
+        }
+        if (twinOf[nameIdx] < 0) {
+            twinOf[nameIdx] = strings.length;
+            strings.push(redactedText(strings[nameIdx], mode, salt));
+            valuesRedacted++;
+            entriesSplit++;
+        }
+        nodes[i + nodeNameOffset] = twinOf[nameIdx];
+    }
+    const contentRedactedByRule = [...ruleCounts]
+        .map(([rule, count]) => ({ rule, count }))
+        .sort((a, b) => b.count - a.count);
+    return {
+        mode,
+        salted: salt.length > 0,
+        stringTableSize: originalTableSize,
+        valuesRedacted,
+        entriesSplit,
+        contentRedacted,
+        contentRedactedByRule,
+        unclassifiedLabelFamilies: collectUnclassifiedLabelFamilies(strings, isLabel, contentRule, MAX_REPORTED_FAMILIES),
+    };
+}
+/**
+ * Read a snapshot file into its raw arrays, WITHOUT building the object graph.
+ *
+ * `HeapParser.parse` additionally computes referrers, dominators, detachedness
+ * and node indices — on a 7.1M-node capture that is the part that costs ~15
+ * seconds and several gigabytes. Anonymization needs none of it: it works off
+ * node types, edge names and the string table. Reading the arrays and stopping
+ * there is the difference between "shareable in a moment" and "load the whole
+ * heap first".
+ *
+ * @param file absolute path of the `.heapsnapshot` file to read
+ * @returns the snapshot's raw arrays
+ *
+ * @internal
+ */
+function readRawHeapSnapshot(file) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const [nodes, edges, locations, content] = yield Promise.all([
+            StringLoader_1.default.readFileAndExtractTypedArray(file, 'nodes'),
+            StringLoader_1.default.readFileAndExtractTypedArray(file, 'edges'),
+            StringLoader_1.default.readFileAndExtractTypedArray(file, 'locations'),
+            StringLoader_1.default.readFileAndExcludeTypedArray(file, [
+                'nodes',
+                'edges',
+                'locations',
+            ]),
+        ]);
+        const raw = JSON.parse(content);
+        raw.nodes = nodes;
+        raw.edges = edges;
+        raw.locations = locations;
+        return raw;
+    });
+}
+/**
+ * Anonymize a `.heapsnapshot` file and write the result to another file.
+ *
+ * The file-to-file form of {@link anonymizeHeapSnapshot}, and the one to reach
+ * for when the capture is only being shared rather than analyzed here: it skips
+ * building the object graph on the way in, and streams on the way out, so
+ * neither the input nor the output is ever held as one string.
+ *
+ * @param inputFile absolute path of the capture to read
+ * @param outputFile absolute path to write the anonymized capture to; an
+ * existing file at that path is overwritten
+ * @param options see {@link AnonymizeOptions}
+ * @returns a summary of what was redacted, and what was left in the clear; see
+ * {@link AnonymizeReport}
+ *
+ * * **Examples**:
+ * ```typescript
+ * import {anonymizeHeapSnapshotFile} from '@memlab/core';
+ *
+ * (async function () {
+ *   const report = await anonymizeHeapSnapshotFile(
+ *     '/tmp/capture.heapsnapshot',
+ *     '/tmp/shareable.heapsnapshot',
+ *   );
+ *   console.log(`redacted ${report.valuesRedacted} string values`);
+ *   for (const family of report.unclassifiedLabelFamilies) {
+ *     console.log(`still in the clear: ${family.count} x ${family.shape}`);
+ *   }
+ * })();
+ * ```
+ */
+function anonymizeHeapSnapshotFile(inputFile_1, outputFile_1) {
+    return __awaiter(this, arguments, void 0, function* (inputFile, outputFile, options = {}) {
+        if (resolveForComparison(inputFile) === resolveForComparison(outputFile)) {
+            throw new Error(`anonymizeHeapSnapshotFile: outputFile resolves to the same file as ` +
+                `inputFile (${inputFile}). Writing there would overwrite the only ` +
+                `unredacted copy of the capture.`);
+        }
+        const raw = yield readRawHeapSnapshot(inputFile);
+        const report = anonymizeRawHeapSnapshot(raw, options);
+        (0, HeapSerializer_1.serializeRawHeapSnapshot)(raw, outputFile);
+        return report;
+    });
+}
+/**
+ * Report what anonymizing a capture WOULD remove, and what it would leave,
+ * without writing anything.
+ *
+ * Point it at a capture someone already anonymized to find out whether they
+ * missed something: `unclassifiedLabelFamilies` names the identifier-shaped
+ * text still in the clear. Run against one already-anonymized capture, this is
+ * what showed its author had removed every string VALUE and left 26,303 account
+ * handles behind as property names.
+ *
+ * @param inputFile absolute path of the capture to inspect
+ * @param options see {@link AnonymizeOptions}
+ * @returns the same summary {@link anonymizeHeapSnapshotFile} returns, for a
+ * run that was not written to disk
+ *
+ * * **Examples**:
+ * ```typescript
+ * import {auditHeapSnapshotFile} from '@memlab/core';
+ *
+ * (async function () {
+ *   const report = await auditHeapSnapshotFile('/tmp/shared.heapsnapshot');
+ *   console.log(report.unclassifiedLabelFamilies);
+ * })();
+ * ```
+ */
+function auditHeapSnapshotFile(inputFile_1) {
+    return __awaiter(this, arguments, void 0, function* (inputFile, options = {}) {
+        const raw = yield readRawHeapSnapshot(inputFile);
+        return anonymizeRawHeapSnapshot(raw, options);
+    });
+}
+/**
+ * Canonical form of a path, for deciding whether two of them are the same file.
+ *
+ * A string comparison is not enough, and the cost of it being wrong here is the
+ * original capture: `a.heapsnapshot` and `./a.heapsnapshot`, an absolute and a
+ * relative spelling, or a symlink and its target are all distinct strings
+ * naming one file. `realpathSync` resolves all three.
+ *
+ * The output file usually does not exist yet, which makes `realpathSync` throw
+ * on it — so its DIRECTORY is canonicalized instead and the basename appended.
+ * That still catches a symlinked parent, which a plain `path.resolve` would
+ * miss. Falls back to `path.resolve` when even the directory is absent, since
+ * at that point the two cannot be the same existing file anyway.
+ *
+ * @param file the path to canonicalize
+ * @returns a path safe to compare against another canonicalized path
+ *
+ * @internal
+ */
+function resolveForComparison(file) {
+    const resolved = path_1.default.resolve(file);
+    try {
+        return fs_1.default.realpathSync(resolved);
+    }
+    catch (_a) {
+        try {
+            return path_1.default.join(fs_1.default.realpathSync(path_1.default.dirname(resolved)), path_1.default.basename(resolved));
+        }
+        catch (_b) {
+            return resolved;
+        }
+    }
+}