@memlab/core 2.0.3 → 2.0.5

package/dist/lib/HeapAnonymizer.d.ts

@@ -0,0 +1,362 @@
+/**
+ * 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
+ */
+import type { IHeapSnapshot, RawHeapSnapshot } from './Types';
+/**
+ * Remove user data from a heap snapshot while leaving it analyzable.
+ *
+ * A heap snapshot is a verbatim dump of everything the page had in memory, so
+ * it carries message bodies, tokens, contact ids and serialized DOM. Sharing
+ * one — with a colleague, in a task, with a model — publishes all of it. The
+ * goal here is a capture that can be shared and still answers the questions
+ * snapshots are taken to answer.
+ *
+ * **What makes that possible is that the format separates values from labels.**
+ * Every entry in the shared `strings` table is reached in one of two ways:
+ *
+ * - as the `name` of a `string` / `concatenated string` / `sliced string` node
+ *   — that is the CONTENT of a JS string living on the heap, i.e. data;
+ * - as an edge name, or the `name` of an object / closure / code / native node
+ *   — that is a LABEL: a class name, a function name, a property key.
+ *
+ * A retainer trace is built entirely out of labels. So redacting exactly the
+ * first kind is a type test, not a heuristic, and it leaves every trace,
+ * histogram, dominator and shape analysis fully readable.
+ *
+ * Two things that clean split does NOT cover, both of which this module also
+ * handles, because a real capture leaks through both:
+ *
+ * 1. **A label can itself be data.** An object keyed by account id, order id or
+ *    session id turns user identifiers into property names — structurally a
+ *    label, semantically a payload. No node-type test can tell `.addListener`
+ *    from a key a database row supplied, so those are matched by shape against
+ *    internet-standard formats. For identifier schemes private to one
+ *    application, which no pattern list can anticipate, the report names what
+ *    it could not classify and {@link AnonymizeOptions.shouldRedact} is the
+ *    seam for acting on it.
+ * 2. **`native` node names can hold serialized DOM.** Browser engines write
+ *    element descriptions that on one measured capture reached 78 KB of
+ *    `outerHTML`, base64-inlined images and user-visible text included.
+ *
+ * @internal
+ */
+/**
+ * How redacted text is generated.
+ *
+ * - `stable` — length-preserving, and derived from the value, so equal inputs
+ *   stay equal and distinct inputs stay distinct. Duplication, interning and
+ *   dedup analyses therefore keep reporting the truth.
+ * - `uniform` — length-preserving fill with a single repeated character. Leaks
+ *   strictly less (not even equality), but it collapses every distinct value of
+ *   the same length into one, which MANUFACTURES string duplication: on one
+ *   measured capture 272,234 distinct values collapsed to 607, and duplication
+ *   tools then reported tens of megabytes of savings that do not exist.
+ */
+export type AnonymizationMode = 'stable' | 'uniform';
+/**
+ * Options accepted by {@link anonymizeHeapSnapshot}.
+ */
+export type AnonymizeOptions = {
+    /**
+     * how replacement text is generated, defaults to `stable`
+     * (see {@link AnonymizationMode})
+     */
+    mode?: AnonymizationMode;
+    /**
+     * salt mixed into `stable` replacements. The default is the empty string,
+     * which is deterministic ACROSS FILES — the same value anonymizes to the
+     * same token in every capture, so a ladder of snapshots stays diffable. That
+     * also means a deterministic token is confirmable by anyone holding a
+     * candidate value; pass an explicit salt for anything leaving your trust
+     * boundary, and reuse that one salt across every file in the set.
+     */
+    salt?: string;
+    /**
+     * also redact node names that look like serialized DOM, defaults to `true`
+     */
+    redactDomText?: boolean;
+    /**
+     * also redact string table entries whose CONTENT looks like an identifier,
+     * wherever they are referenced — including as property names, defaults to
+     * `true`
+     */
+    redactIdentifierKeys?: boolean;
+    /**
+     * how many consecutive digits make a string an identifier rather than an
+     * array index, defaults to `9`. Chosen from the data: V8 emits exhaustive
+     * runs of short numeric index names (10 one-digit, 90 two-digit, 900
+     * three-digit ... 138,432 six-digit on one capture) and then the count falls
+     * off a cliff, so a floor in that gap separates indices from ids.
+     */
+    minDigitRunLength?: number;
+    /** extra patterns to redact, matched against the string table entry */
+    extraPatterns?: RegExp[];
+    /** patterns that must NEVER be redacted; these win over every built-in rule */
+    keepPatterns?: RegExp[];
+    /**
+     * the final say on any entry, consulted BEFORE every built-in rule.
+     *
+     * No fixed rule set can know an identifier scheme private to one application,
+     * and guessing at one inside memlab would mean shipping other people's
+     * formats to everybody. This is the seam for that instead: return `true` to
+     * redact, `false` to protect, or `undefined` to let the built-in rules
+     * decide. `AnonymizeReport.unclassifiedLabelFamilies` is the companion — it
+     * names the shapes still in the clear, which is where a caller finds out what
+     * their own scheme looks like.
+     *
+     * ```typescript
+     * anonymizeHeapSnapshot(heap, {
+     *   // this app keys caches by order id: ORD-<digits>
+     *   shouldRedact: (value, ctx) =>
+     *     ctx.isLabel && value.startsWith('ORD-') ? true : undefined,
+     * });
+     * ```
+     */
+    shouldRedact?: (value: string, context: RedactionContext) => boolean | undefined;
+};
+/**
+ * A family of labels left in the clear that share one machine-generated shape.
+ *
+ * This is how the tool generalizes past its own pattern list. No fixed set of
+ * formats can know an identifier scheme private to one application, so rather
+ * than guess, the report names what it could not classify and lets the caller
+ * decide. A family here is a prompt to look, not a finding: `d.d.d` is a
+ * version number in one app and an account id in another.
+ */
+export type UnclassifiedLabelFamily = {
+    /**
+     * character-class shape with runs collapsed, e.g. `d@a` for `4155551234@ex`
+     */
+    shape: string;
+    /** how many distinct labels in the string table share it */
+    count: number;
+    /** up to three of them, verbatim, so the shape can be recognized */
+    examples: string[];
+};
+/**
+ * What is known about one string table entry when {@link AnonymizeOptions.shouldRedact}
+ * is asked to judge it.
+ */
+export type RedactionContext = {
+    /**
+     * true when this entry is the CONTENT of a string on the heap. Redacting one
+     * of these is what the node-type rule already does by default.
+     */
+    isValue: boolean;
+    /**
+     * true when this entry is used as a class name, function name, property key,
+     * closure variable or context slot — i.e. as part of the vocabulary a
+     * retainer trace is written in. Redacting one of these costs debuggability,
+     * so it is the decision worth thinking about.
+     */
+    isLabel: boolean;
+    /**
+     * how many edges in the whole snapshot use this entry as their name. A
+     * programmer-written property name is reused; an identifier minted per record
+     * is used once or twice. Useful for telling one from the other without
+     * knowing the format.
+     */
+    labelUseCount: number;
+    /**
+     * character-class shape with runs collapsed, e.g. `d@a` for `4155551234@ex`
+     * or `dadada-ada-da` for a UUID prefix. Lets a caller match a scheme by shape
+     * instead of writing a precise regex.
+     */
+    shape: string;
+};
+/** One rule's contribution, as reported by {@link AnonymizeReport}. */
+export type AnonymizeRuleCount = {
+    /** the rule that matched, e.g. `dom-text` or `digit-run` */
+    rule: string;
+    /** how many distinct string table entries it matched */
+    count: number;
+};
+/**
+ * What {@link anonymizeHeapSnapshot} did, and — just as importantly — what it
+ * left behind.
+ */
+export type AnonymizeReport = {
+    /** the mode that was applied */
+    mode: AnonymizationMode;
+    /** whether a non-empty salt was used */
+    salted: boolean;
+    /** number of entries in the string table before anonymization */
+    stringTableSize: number;
+    /** string values redacted because they are the content of a string node */
+    valuesRedacted: number;
+    /**
+     * how many redacted values were written to an APPENDED table entry rather
+     * than over the original. The string table is deduplicated, so one entry can
+     * be both a string's value and a property name; splitting is what keeps
+     * redaction from destroying the label.
+     */
+    entriesSplit: number;
+    /** entries redacted everywhere because their content looked sensitive */
+    contentRedacted: number;
+    /** the per-rule breakdown of `contentRedacted` */
+    contentRedactedByRule: AnonymizeRuleCount[];
+    /**
+     * machine-generated-looking labels still in the clear, most common first.
+     * Review these: anything here that is an identifier in YOUR application is a
+     * residual leak, and the fix is to pass it as an `extraPatterns` entry. See
+     * {@link UnclassifiedLabelFamily}.
+     */
+    unclassifiedLabelFamilies: UnclassifiedLabelFamily[];
+};
+/**
+ * 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');
+ * })();
+ * ```
+ */
+export declare function anonymizeHeapSnapshot(snapshot: IHeapSnapshot, options?: AnonymizeOptions): AnonymizeReport;
+/**
+ * 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
+ */
+export declare function anonymizeRawHeapSnapshot(raw: RawHeapSnapshot, options?: AnonymizeOptions): AnonymizeReport;
+/**
+ * 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
+ */
+export declare function readRawHeapSnapshot(file: string): Promise<RawHeapSnapshot>;
+/**
+ * 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}`);
+ *   }
+ * })();
+ * ```
+ */
+export declare function anonymizeHeapSnapshotFile(inputFile: string, outputFile: string, options?: AnonymizeOptions): Promise<AnonymizeReport>;
+/**
+ * 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);
+ * })();
+ * ```
+ */
+export declare function auditHeapSnapshotFile(inputFile: string, options?: AnonymizeOptions): Promise<AnonymizeReport>;
+/**
+ * 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
+ */
+export declare function resolveForComparison(file: string): string;
+//# sourceMappingURL=HeapAnonymizer.d.ts.map

package/dist/lib/HeapAnonymizer.d.ts.map

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