@needmoretruth/nmts-cli 0.17.2 → 0.34.1

package/dist/recovery-map-file.js

@@ -14,7 +14,7 @@
 // ⛔ NOTHING SECRET IN THE HEADER, AND THAT INCLUDES SIZES. No file name, no count, no total. A
 //    leaked wrapper must not say what is inside it, or even how much.
 //
-// ⛔ THE ACCOUNT CODE IS NOT IN IT. This file plus the code is the account; the artefact that DOES
+// ⛔ THE NMTS KEY IS NOT IN IT. This file plus the code is the account; the artefact that DOES
 //    carry both is the recovery kit, and it says so about itself in every language it is written.
 //
 // ⚠ WHAT DIFFERS FROM THE BROWSER'S COPY, and none of it is a format difference:
@@ -79,13 +79,13 @@ export function minimumToolVersion(nrm) {
 const NOTE = [
     `This file is a recovery list from NMTS (nmts.me). Encrypted inside is the record of where ` +
         `this account's files are kept on the public storage network (Walrus).`,
-    `It opens only with the account code this list was made for. File names and counts are not ` +
+    `It opens only with the NMTS key this list was made for. File names and counts are not ` +
         `visible from the outside.`,
     `The original file list lives on the NMTS server. If the server can no longer be reached, this ` +
-        `list together with the account code carries the information needed to find the files still ` +
+        `list together with the NMTS key carries the information needed to find the files still ` +
         `on the storage network and open them.`,
     `A list with a higher number in its filename is newer — keep the newest. Store this file ` +
-        `somewhere other than the account code. The program that reads it is at ` +
+        `somewhere other than the NMTS key. The program that reads it is at ` +
         `github.com/needmoretruth/nmts-recovery.`,
 ];
 /** Build the on-disk document and the filename to offer it under. */

package/dist/recovery-map.d.ts

@@ -0,0 +1,197 @@
+import type { ArtifactAbout } from "./artifact-about.ts";
+import { NmtsError } from "./errors.ts";
+/** The newest NRM version this writer knows how to emit. */
+export declare const NRM_VERSION_LATEST = 4;
+/** The first NRM version in which every part carries `part_index`. */
+export declare const NRM_VERSION_WITH_PART_INDEX = 2;
+/** The first NRM version in which a quilt placement may be `{ identifier }` alone. */
+export declare const NRM_VERSION_WITH_OWN_QUILT = 3;
+/** The first NRM version in which a part may carry `padded_len`. */
+export declare const NRM_VERSION_WITH_PADDING = 4;
+/** Practical ceiling from RECOVERY-MANIFEST.md §1 — beyond this the format needs chunk framing. */
+export declare const MANIFEST_ITEM_SOFT_CAP = 100000;
+/** One stored piece of a file, in order. */
+export interface ManifestPart {
+    /**
+     * Where this part belongs: 0 for the first, and the position it must be concatenated at
+     * thereafter. Required from NRM-2.
+     *
+     * It is written down because array order alone cannot be CHECKED. A reader holds each fetched
+     * part's 72-byte NCF-3 header, which carries the index sealed under the file key, so with this
+     * field it can compare three things that must agree: the position it is writing at, what the
+     * list says belongs there, and what the bytes themselves say they are.
+     */
+    part_index: number;
+    /** Blob id holding this part's stream, in `network`'s own naming. */
+    blob_id?: string;
+    /** The REAL bytes this part contributes to the file. */
+    plaintext_len: number;
+    /**
+     * What the stored stream's header DECLARES, when the part was padded and that is larger.
+     * Absent means it was not padded. New in NRM-4.
+     *
+     * ⛔ THE TWO NUMBERS STAY APART so that "the parts sum to exactly `size`" keeps its exact
+     *    strength. Folded into one, the check softens to "at least", which accepts any size below
+     *    the real one: the file comes back short and nothing says so.
+     */
+    padded_len?: number;
+    /** On-chain blob object, when the uploading client captured it. Omitted, never null. */
+    sui_object_id?: string;
+    /**
+     * Which storage network holds `blob_id` — a NAME (`"walrus"`), not a code.
+     *
+     * A word rather than a number because whoever parses this may be doing so years from now with
+     * none of our code beside them, and a bare `1` is not something a stranger can look up.
+     */
+    network?: string;
+}
+/** As a writer hands one in: the position is the value, so `part_index` is filled by the encoder. */
+export interface ManifestPartInput extends Omit<ManifestPart, "part_index"> {
+    part_index?: number;
+}
+/** Quilt placement naming a quilt anywhere on the network. */
+export interface ManifestQuiltAbsolute {
+    quilt_blob_id: string;
+    patch_id: string;
+    identifier?: undefined;
+}
+/** The own-quilt form (NRM-3): "the quilt this document was read out of". */
+export interface ManifestQuiltOwn {
+    identifier: string;
+    quilt_blob_id?: undefined;
+    patch_id?: undefined;
+}
+export type ManifestQuilt = ManifestQuiltAbsolute | ManifestQuiltOwn;
+/** Which form a placement is. One narrowing point, so "exactly one of the two" is decided here. */
+export declare function isOwnQuilt(quilt: ManifestQuilt): quilt is ManifestQuiltOwn;
+/** One recoverable file. */
+export interface ManifestItem {
+    id: string;
+    name: string;
+    /** Logical folder path, e.g. `/photos/2026`. Root is `/`. */
+    path: string;
+    size: number;
+    /** The file key, base64url of 32 RAW bytes — the list IS the recovery key store. */
+    dek: string;
+    kind: "file";
+    /**
+     * When the file was created and last changed, RFC3339.
+     *
+     * ⚠ THE ONLY VALUES IN AN ITEM THAT NOTHING CHECKS. Everything else is either sealed under the
+     *   account key or constrained arithmetically by something that is; these two are simply what
+     *   the storage layer said. A reader may STAMP them onto restored files and must not order,
+     *   compare or decide anything with them.
+     */
+    created_at?: string;
+    updated_at?: string;
+    /** sha256 of the whole plaintext, base64url of 32 RAW bytes. Omitted when unrecorded. */
+    content_hash?: string;
+    parts: ManifestPart[];
+    quilt?: ManifestQuilt;
+}
+/** What a caller hands in for one file. */
+export interface ManifestItemInput {
+    id: string;
+    name: string;
+    path: string;
+    size: number;
+    dek: string;
+    contentHash?: string | undefined;
+    createdAt?: string | undefined;
+    updatedAt?: string | undefined;
+    parts: readonly ManifestPartInput[];
+    quilt?: ManifestQuilt | undefined;
+}
+/** Where the bytes this document points at actually live. */
+export interface StorageDescription {
+    network: string;
+    /** ⭐ WHICH chain issued the blob ids — the field that stops a reader guessing between two. */
+    chain: string;
+    /** Read endpoints this build was using. HINTS, read after a reader's own defaults. */
+    aggregators: readonly string[];
+    chain_rpc: string;
+}
+/**
+ * What the document says about ITSELF, sealed with it.
+ *
+ * ⚠ `totals` IS NOT AN INTEGRITY CHECK and a reader must not treat a disagreement as tampering.
+ *   The document is one authenticated envelope. It is for a RE-IMPLEMENTATION, which drops records
+ *   it does not recognise and otherwise has no way to notice it read 400 of 412 files.
+ */
+export interface RecoveryDocMeta {
+    product: string;
+    product_url: string;
+    app_version: string;
+    tool: string;
+    tool_url: string;
+    spec_url: string;
+    storage: StorageDescription;
+    totals: {
+        items: number;
+        bytes: number;
+    };
+}
+/** The document itself. */
+export interface RecoveryListDoc {
+    v: number;
+    /** Monotonic per account. Orders the chain — timestamps do not (device clocks lie). */
+    seq: number;
+    /** Blob id of the list this supersedes; explicitly `null` at the head of the chain. */
+    prev_manifest_blob_id: string | null;
+    generated_at: string;
+    account_id: string;
+    meta?: RecoveryDocMeta;
+    items: ManifestItem[];
+}
+export interface BuildRecoveryListDocInput {
+    seq: number;
+    prevBlobId: string | null;
+    generatedAt: string;
+    accountId: string;
+    meta?: RecoveryDocMeta | undefined;
+    items: readonly ManifestItemInput[];
+}
+/**
+ * Thrown when the input cannot produce a document a recovery tool could use.
+ *
+ * ⛔ IT IS AN `NmtsError`, NOT A BARE `Error`. Anything that reaches the top of this program as a
+ *    bare error prints its message with no next step and exits with the generic code — and the
+ *    generic code is the one an agent retries. A discrepancy here is never worth retrying: the
+ *    server has to change, or the account does. Exit 4 is "the command exists and could not do
+ *    it", which is exactly what happened.
+ */
+export declare class RecoveryListProblem extends NmtsError {
+    constructor(message: string);
+}
+/**
+ * The lowest `v` a document holding these items may honestly declare.
+ *
+ * ⛔ A WRITER STAMPS THIS, NOT THE NEWEST NUMBER IT KNOWS. People already hold copies of the
+ *    standalone recovery program, and a build only knows the forms that existed when it was made.
+ *    Every version number in this format is a CEILING in every published build: a document
+ *    declaring a number higher than a build knows is REFUSED, unread. So stamping `4` for no
+ *    reason other than the calendar would be a wall in front of a reader that would have
+ *    understood every byte of it.
+ */
+export declare function minimumVersion(items: readonly ManifestItem[]): number;
+/**
+ * Assemble the document.
+ *
+ * Rejects rather than emits a list that would mislead somebody in a recovery: a file with no parts
+ * has nothing to fetch, a part list that does not add up to the file's size is missing or repeating
+ * bytes, a part that says it is somewhere other than where it sits contradicts itself, and a
+ * `seq` below 1 is not a version at all. The hostile-input version of the middle two is caught one
+ * layer up, where the size being compared against comes from a source the server cannot write —
+ * but the cost of shipping any of them is that somebody believes they are covered when they are
+ * not, so they are checked here too rather than assumed.
+ */
+export declare function buildRecoveryListDoc(input: BuildRecoveryListDocInput): RecoveryListDoc;
+/** What this tool writes into a document's `meta`, minus the totals only the builder knows. */
+export type RecoveryDocMetaDraft = Omit<RecoveryDocMeta, "totals">;
+/** Finish a draft once the document's contents are known. */
+export declare function withTotals(draft: RecoveryDocMetaDraft, totals: {
+    items: number;
+    bytes: number;
+}): RecoveryDocMeta;
+/** The `meta` block for this build, minus the totals. */
+export declare function recoveryDocMeta(about: ArtifactAbout, storage: StorageDescription): RecoveryDocMetaDraft;

package/dist/recovery-release.d.ts

@@ -0,0 +1,104 @@
+/**
+ * The standalone program, by the name it is published under.
+ *
+ * ⛔ ONE SPELLING FOR THE WHOLE PACKAGE. It is the executable's file name, the prefix of every
+ *    asset in the table below, and the word the sealed file list writes into its own header so
+ *    that whoever finds that file years later knows what reads it. Two copies of this string is
+ *    how a rename lands in one of those places and not the others.
+ */
+export declare const RECOVERY_TOOL = "nmts-recovery";
+/**
+ * Where that program's source and its releases are.
+ *
+ * ⚠ Printed as text into a file that has no links, and used to build the download addresses. It
+ *   is the same one either way, so it is written down once.
+ */
+export declare const RECOVERY_TOOL_URL = "https://github.com/needmoretruth/nmts-recovery";
+/** One executable the release publishes. */
+export interface PublishedExecutable {
+    /** The `process.platform` it was built for. */
+    platform: string;
+    /** The `process.arch` it was built for. */
+    arch: string;
+    /** The file name the release attaches it under. */
+    asset: string;
+    /** How a person says that platform out loud, for the refusal a machine without one gets. */
+    label: string;
+}
+/**
+ * Every executable the release workflow attaches, in the order it builds them.
+ *
+ * ⚠ macOS carries the marketing word in brackets because "aarch64" and "x86_64" are not what
+ *   anybody's machine calls itself on that platform — the person reading a refusal has to be able
+ *   to tell whether their own machine is in this list.
+ */
+export declare const PUBLISHED: readonly PublishedExecutable[];
+/** The checksum file the release attaches beside the executables. */
+export declare const SUMS_FILE = "SHA256SUMS";
+/** The one this machine can run, or null when the release publishes nothing for it. */
+export declare function executableFor(platform: string, arch: string): PublishedExecutable | null;
+/** The published platforms, for telling somebody their own is not among them. */
+export declare function publishedLabels(): readonly string[];
+/**
+ * The exact commands that build this program from source.
+ *
+ * ⛔ EXACT, NOT "BUILD IT YOURSELF". Somebody reading this is on an unusual machine and has
+ *    already lost access to their files; "see the repository" is a research task, and three lines
+ *    they can paste is not.
+ */
+export declare function buildFromSource(sourceUrl: string): readonly string[];
+/**
+ * What checking the bytes against SHA256SUMS shows, and what it does not.
+ *
+ * ⛔ BOTH SENTENCES, ALWAYS TOGETHER, AND WORDED ONCE. They are printed by the command and
+ *    repeated in the help text, and if they were written twice one copy would eventually start
+ *    promising more than the other. There is no "verified", no "trusted" and no "safe" in either
+ *    of them on purpose: a checksum published by the same release as the file it describes proves
+ *    the two agree, and nothing whatsoever about who produced them.
+ */
+export declare const CHECK_PROVES: string;
+/** The other half. Never printed without the one above it. */
+export declare const CHECK_DOES_NOT_PROVE: string;
+/** `SHA256SUMS` for whatever the source repository's newest release is. */
+export declare function sumsUrl(sourceUrl: string): string;
+/** One asset of one NAMED release. Never "latest": the tag is resolved once and then reused. */
+export declare function assetUrl(sourceUrl: string, tag: string, asset: string): string;
+/**
+ * The release tag a URL names, or null when it does not name one.
+ *
+ * Split into segments rather than matched with a regex because the file name can contain the
+ * characters a regex cares about (`nmts-recovery-windows-x86_64.exe`), and an escaping mistake
+ * there would be a silently looser check.
+ */
+export declare function tagFromUrl(url: string, filename: string): string | null;
+/**
+ * The tag the redirect chain resolved to, or null.
+ *
+ * ⛔ THE WHOLE CHAIN, NOT THE LAST HOP. `…/releases/latest/download/SHA256SUMS` redirects to the
+ *    tagged address and that one redirects again to wherever the bytes are actually served from,
+ *    which carries no tag at all. Reading only where the chain ended would find nothing.
+ */
+export declare function tagFromChain(chain: readonly string[], filename: string): string | null;
+/** What a lookup in `SHA256SUMS` found, or why it found nothing usable. */
+export type SumsLookup = {
+    found: true;
+    hash: string;
+} | {
+    found: false;
+    why: "missing" | "repeated" | "malformed";
+};
+/**
+ * The hash `SHA256SUMS` gives for one asset.
+ *
+ * ⛔ TWO LINES FOR ONE NAME IS A REFUSAL, NOT A FIRST-WINS. A file listed twice with different
+ *    hashes has no answer, and picking one would mean this command decides which of two claims to
+ *    act on. It has no basis for that, so it says so instead.
+ */
+export declare function hashFromSums(sums: string, asset: string): SumsLookup;
+/**
+ * Break one long sentence into lines a terminal will not fold in the middle of a word.
+ *
+ * ⚠ The two sentences above are written once, as prose, so the help text and the command cannot
+ *   drift apart. Prose has to be wrapped somewhere, and doing it here keeps the wording out of it.
+ */
+export declare function wrapText(text: string, width?: number): string[];

package/dist/recovery-seq.d.ts

@@ -0,0 +1,10 @@
+/** The highest sequence this machine has offered for an account, or 0 when it has offered none. */
+export declare function lastOfferedSeq(accountId: string): number;
+/**
+ * Write down a sequence this machine OFFERED — whether or not the server took it.
+ *
+ * ⛔ OFFERED, NOT ACCEPTED, AND THAT IS THE POINT. Recording only the accepted ones would make a
+ *    refused number the number the next run offers again, and every run after it: the same
+ *    refusal for ever. Recording the attempt is what makes a second run get past it.
+ */
+export declare function rememberOfferedSeq(accountId: string, seq: number): void;

package/dist/recovery-source.d.ts

@@ -0,0 +1,50 @@
+/** `file_parts.storage_kind` for a quilt patch. 0 is a dedicated blob. */
+export declare const STORAGE_QUILT = 1;
+/** One stored piece of a file, as the server describes it. */
+export interface SourcePart {
+    part_index: number;
+    storage_kind: number;
+    /** Storage-network code. Absent means Walrus — a fact, not a fallback. */
+    network?: number;
+    blob_id: string;
+    patch_id?: string;
+    /** What the part OCCUPIES: the sealed stream, header and tags included. */
+    sealed_len: number;
+    sui_object_id?: string;
+    /**
+     * What this part's stored header DECLARES — the plaintext length behind `sealed_len`.
+     *
+     * ⚠ DERIVED HERE, NOT SENT: the server is told what a part occupies and nothing about the file
+     *   behind it. ⛔ NOT the file's own length either — a padded part declares more than the file
+     *   holds, and the real per-part lengths come from `keepLengths`.
+     */
+    streamPlaintextLen: number;
+}
+/** One stored file in the dump. It says what is stored, never how it is arranged. */
+export interface SourceItem {
+    id: string;
+    size: number;
+    /** Wrapped file key. The one thing here that cannot be recreated if it is lost. */
+    dekWrapped?: string;
+    /** Sealed whole-file content hash, when the file was committed with one. */
+    contentHashCt?: string;
+    createdAt: string;
+    updatedAt: string;
+    parts: SourcePart[];
+}
+export interface SourceWalkOptions {
+    server: string;
+    apiKey: string;
+    /** base64url of the 32-byte proof. Sent on every page. */
+    accountProof: string;
+    /** Ticks while paging, so a very large account does not look frozen. */
+    onProgress?: ((loaded: number) => void) | undefined;
+}
+/**
+ * Read every page of the dump, oldest cursor first.
+ *
+ * ⛔ A REPEATED CURSOR IS A REFUSAL, NOT A LOOP. The cursor is server-issued and strictly
+ *    increasing, but a bug — or a hand-edited answer — that repeated one would spin here forever
+ *    with nothing to show for it.
+ */
+export declare function readAllRecoverySource(options: SourceWalkOptions): Promise<SourceItem[]>;

package/dist/redact.d.ts

@@ -0,0 +1,70 @@
+/**
+ * One thing that is taken out, and how it is recognised.
+ *
+ * ⛔ DATA, NOT A CHAIN OF `if`s. The rules are read by a test one at a time, and a rule that
+ *    exists only inside a function body is a rule nobody can enumerate.
+ */
+export interface RedactionRule {
+    /** What replaces the match. Written in the report, so it says what stood there. */
+    readonly label: string;
+    /** ⚠ Global. `redact` relies on `replaceAll` semantics and resets nothing. */
+    readonly test: RegExp;
+    /**
+     * A second opinion on a match, for shapes a regular expression cannot decide alone.
+     *
+     * The NMTS key is the one that needs it: recognising it is "exactly thirty-three symbols
+     * once the separators are gone", which is a count and not a pattern.
+     */
+    readonly only?: (match: string) => boolean;
+    /**
+     * What the match becomes, when part of it has to stay.
+     *
+     * `token=…` is the case: the name is what makes the label readable, so the name stays and only
+     * the value goes.
+     */
+    readonly into?: (match: string, groups: readonly (string | undefined)[]) => string;
+}
+/**
+ * The rules, in the order they run.
+ *
+ * ⛔ ORDER IS PART OF EACH RULE. The narrow shapes go first so that the value gets the label that
+ *    names it — an API key becomes `[api-key]` and not the `[secret]` that the catch-all run of
+ *    key material would have given it. The catch-all rules go last, over a text where everything
+ *    recognisable has already become a label, and a label is too short for them to match.
+ */
+export declare const RULES: readonly RedactionRule[];
+/**
+ * The values this process is actually holding, whatever they look like.
+ *
+ * ⛔ READ AT REDACTION TIME, NOT AT IMPORT TIME. A command that sets a variable for a child, a
+ *    test that swaps one, and a shell that exported one after this module loaded would all defeat
+ *    a snapshot taken once.
+ *
+ * ⛔ EVERY `NMTS_*` VARIABLE, NOT THE THREE THAT ARE OBVIOUSLY SECRET. The cost of labelling a
+ *    server address is one word in a report; the cost of a variable added next year that nobody
+ *    thought to add here is the value itself.
+ *
+ * ⚠ LONGEST FIRST. Two variables holding one value inside the other would otherwise leave the
+ *   longer one half-labelled, which is a value partly in the clear.
+ */
+export declare function environmentRules(): RedactionRule[];
+/**
+ * Take the secrets out of a text.
+ *
+ * ⛔ THE ENVIRONMENT GOES FIRST. A value this process is holding is known to be a secret, and a
+ *    label naming the variable it came from (`[env:NMTS_API_KEY]`) says more to whoever reads the
+ *    report than the shape-based label would.
+ */
+export declare function redact(text: string): string;
+/** The label a value named with `--omit` becomes. */
+export declare const OMITTED = "[omitted]";
+/** Values shorter than this are refused: two characters match half a text. */
+export declare const SHORTEST_OMIT = 3;
+/**
+ * Replace values the caller named, on top of everything `redact` finds.
+ *
+ * ⛔ LITERAL, NOT A PATTERN. What is passed is a file name or a folder somebody typed, and
+ *    treating it as a regular expression would turn a dot into "any character" and a bracket into
+ *    a syntax error in somebody's report.
+ */
+export declare function omitLiterals(text: string, values: readonly string[]): string;

package/dist/redact.js

@@ -0,0 +1,212 @@
+// Taking out of a text the things that must never leave this machine.
+//
+// ⛔ IT RUNS BEFORE ANYTHING IS WRITTEN OR SENT, NOT AFTER. The run log is redacted on the way to
+//    the disk and a support message is redacted on the way to the wire, so a file somebody copies
+//    off this machine and a request somebody intercepts both carry labels rather than values. A
+//    filter applied at the last moment would still leave the real thing lying in a file.
+//
+// ⛔ IT ERRS TOWARD REPLACING. A label where an ordinary word stood costs the reader one word and
+//    is visible in the preview; a missed NMTS key costs the whole account and is visible to
+//    nobody. Every rule below is written on that side of the line, and the tests pin both
+//    directions — one text each rule must replace, one text it must leave alone.
+//
+// ⛔ THE MATCH IS REPLACED BY A LABEL, NOT BY STARS. `[account-code]` tells the person reading the
+//    report what stood there, which is often the useful half of the sentence ("I pasted
+//    [account-code] and it said ..."), and a row of asterisks does not.
+//
+// ⚠ WHAT IT CANNOT DO. It knows the SHAPES this product uses and the values this process can see.
+//   A secret belonging to something else, written in prose ("my password is hunter2"), is not a
+//   shape and is not in this process's environment, and nothing here will find it. That is why the
+//   text a person reads before sending asks them to keep personal details out: the machine covers
+//   what a machine can recognise, and the sentence covers the rest.
+/** An NMTS key is 32 data symbols and one check symbol. `crypto/src/codes.rs` is the origin. */
+const ACCOUNT_CODE_SYMBOLS = 33;
+/** Crockford base32, the data half: `0-9 A-H J-K M-N P-T V-Z`, either case. No `I L O U`. */
+const DATA_CLASS = "0-9A-HJKMNP-TV-Za-hjkmnp-tv-z";
+/** The check symbol may also be one of the five Crockford extras. */
+const CHECK_CLASS = `${DATA_CLASS}*~$=Uu`;
+const DATA_ONLY = new RegExp(`^[${DATA_CLASS}]+$`, "u");
+const CHECK_ONLY = new RegExp(`^[${CHECK_CLASS}]$`, "u");
+/**
+ * Is this run of symbols an NMTS key?
+ *
+ * ⛔ THE GROUPS MUST BE THREE SYMBOLS OR MORE. Without that, a hyphenated phrase of single letters
+ *    adding up to thirty-three would be replaced, and error sentences are exactly where hyphens
+ *    live. The display form the product prints is groups of four, so nothing real is excluded.
+ */
+function looksLikeAnAccountCode(candidate) {
+    const groups = candidate.split("-");
+    if (groups.some((group) => group.length < 3))
+        return false;
+    const symbols = groups.join("");
+    if (symbols.length !== ACCOUNT_CODE_SYMBOLS)
+        return false;
+    return DATA_ONLY.test(symbols.slice(0, -1)) && CHECK_ONLY.test(symbols.slice(-1));
+}
+/**
+ * The rules, in the order they run.
+ *
+ * ⛔ ORDER IS PART OF EACH RULE. The narrow shapes go first so that the value gets the label that
+ *    names it — an API key becomes `[api-key]` and not the `[secret]` that the catch-all run of
+ *    key material would have given it. The catch-all rules go last, over a text where everything
+ *    recognisable has already become a label, and a label is too short for them to match.
+ */
+export const RULES = [
+    {
+        // A whole PEM block, header to footer. Its body is standard base64, which the run rule below
+        // deliberately does not cover, so this has to take the block rather than the first line.
+        label: "[secret]",
+        test: /-----BEGIN[^\n-]*-----[\s\S]*?-----END[^\n-]*-----/g,
+    },
+    {
+        // A header with no footer: a key that was pasted half-way, which is still most of a key.
+        label: "[secret]",
+        test: /-----BEGIN[^\n]*/g,
+    },
+    {
+        // Sui's own spelling of a private key. It is bech32, so the tail is lower-case alphanumerics.
+        label: "[secret]",
+        test: /\bsuiprivkey1[0-9a-z]+/gi,
+    },
+    {
+        // `api-key.ts` has the exact shape: the prefix, a 12-symbol handle, `_`, and 43 more.
+        label: "[api-key]",
+        test: /nmts_ak1_[A-Za-z0-9_-]+/g,
+    },
+    {
+        // Hyphen-separated or run together — the two spellings a person copies. Whitespace grouping
+        // is the rule below, kept separate because a maximal run over spaces would swallow the
+        // sentence the code sits in and then fail to recognise it.
+        //
+        // ⚠ The five extended check symbols are allowed only at the END. Letting `=` stand inside the
+        //   run glued `--message=` to the code that followed it and the pair then matched nothing.
+        label: "[account-code]",
+        test: new RegExp(`(?<![0-9A-Za-z])[${DATA_CLASS}]{3,}(?:-[${DATA_CLASS}]{3,})*[*~$=Uu]?(?![0-9A-Za-z])`, "gu"),
+        only: looksLikeAnAccountCode,
+    },
+    {
+        // The display form with spaces where the dashes are: seven groups of four, then five.
+        label: "[account-code]",
+        test: new RegExp(`(?<![0-9A-Za-z])[${DATA_CLASS}]{4}(?: [${DATA_CLASS}]{4}){6} [${DATA_CLASS}]{4}[${CHECK_CLASS}](?![0-9A-Za-z])`, "gu"),
+    },
+    {
+        // ⛔ THE NAME STAYS AND THE VALUE GOES. `Authorization: [secret]` is still a sentence somebody
+        //    can act on; `[secret]` alone is not. The prefix is widened to anything ending in `token`
+        //    or `key` so that `api_key=` and `access_token=` are covered by one rule rather than three.
+        label: "[secret]",
+        // ⚠ `(?!\[)` KEEPS A LABEL A RULE ABOVE ALREADY PUT THERE. Without it `key=[api-key]` became
+        //   `key=[secret]`, which is not wrong but is less useful: the narrower label is the one that
+        //   says what stood there.
+        test: /\b(authorization\s*:\s*bearer|[A-Za-z0-9_]*(?:token|key)\s*=)\s*("?)(?!\[)[^\s"'&]+\2/gi,
+        into: (_match, groups) => {
+            const prefix = groups[0] ?? "";
+            return prefix.endsWith("=") ? `${prefix}[secret]` : `${prefix} [secret]`;
+        },
+    },
+    {
+        // Key material, session tokens, ciphertext: 43 symbols is the length of base64url over 32
+        // bytes, which is what every secret this product handles decodes to.
+        //
+        // ⛔ BOTH CASES REQUIRED, AND THAT IS WHAT KEEPS FILE NAMES. `screenshot-2026-09-04-at-...`
+        //    is base64url's alphabet too, and long names built out of hyphenated lower-case words are
+        //    ordinary. Random 43-symbol material without a single capital happens about once in ten
+        //    billion times; a lower-case file name happens every day.
+        label: "[secret]",
+        test: /(?<![A-Za-z0-9_-])(?=[A-Za-z0-9_-]*[A-Z])(?=[A-Za-z0-9_-]*[a-z])[A-Za-z0-9_-]{43,}(?![A-Za-z0-9_-])/g,
+    },
+    {
+        // Hex of the same weight — a hash, a chain digest, a raw key written out.
+        label: "[secret]",
+        test: /(?<![A-Za-z0-9])[0-9a-f]{43,}(?![A-Za-z0-9])/gi,
+    },
+    {
+        // ⛔ A SEED PHRASE, WHICH THIS TOOL NEVER HOLDS AND A PERSON MIGHT STILL PASTE. The wallet
+        //    here is derived from the NMTS key and there is no mnemonic anywhere in it — but
+        //    somebody reporting a wallet problem has another wallet open, and twelve words is what
+        //    that one shows them.
+        //
+        // ⛔ THE COUNT IS EXACT AND THE RUN IS MAXIMAL. Only a whole run of exactly twelve or
+        //    twenty-four short lower-case words is replaced, so a sentence that happens to contain
+        //    twelve of them among longer words, capitals, digits or punctuation is left alone.
+        label: "[words]",
+        test: /\b[a-z]{3,8}(?:\s+[a-z]{3,8})*\b/g,
+        only: (match) => {
+            const count = match.split(/\s+/u).length;
+            return count === 12 || count === 24;
+        },
+    },
+];
+/** Below this length a variable's value is too short to be a credential and too likely to be a word. */
+const SHORTEST_ENV_VALUE = 8;
+function escapeForRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * The values this process is actually holding, whatever they look like.
+ *
+ * ⛔ READ AT REDACTION TIME, NOT AT IMPORT TIME. A command that sets a variable for a child, a
+ *    test that swaps one, and a shell that exported one after this module loaded would all defeat
+ *    a snapshot taken once.
+ *
+ * ⛔ EVERY `NMTS_*` VARIABLE, NOT THE THREE THAT ARE OBVIOUSLY SECRET. The cost of labelling a
+ *    server address is one word in a report; the cost of a variable added next year that nobody
+ *    thought to add here is the value itself.
+ *
+ * ⚠ LONGEST FIRST. Two variables holding one value inside the other would otherwise leave the
+ *   longer one half-labelled, which is a value partly in the clear.
+ */
+export function environmentRules() {
+    const found = [];
+    for (const [name, value] of Object.entries(process.env)) {
+        if (!name.startsWith("NMTS_"))
+            continue;
+        if (value === undefined || value.length < SHORTEST_ENV_VALUE)
+            continue;
+        found.push({ name, value });
+    }
+    found.sort((a, b) => b.value.length - a.value.length);
+    return found.map((v) => ({ label: `[env:${v.name}]`, test: new RegExp(escapeForRegExp(v.value), "g") }));
+}
+function apply(text, rule) {
+    return text.replace(rule.test, (match, ...rest) => {
+        if (rule.only !== undefined && !rule.only(match))
+            return match;
+        const groups = rest.filter((v) => typeof v === "string" || v === undefined);
+        return rule.into === undefined ? rule.label : rule.into(match, groups);
+    });
+}
+/**
+ * Take the secrets out of a text.
+ *
+ * ⛔ THE ENVIRONMENT GOES FIRST. A value this process is holding is known to be a secret, and a
+ *    label naming the variable it came from (`[env:NMTS_API_KEY]`) says more to whoever reads the
+ *    report than the shape-based label would.
+ */
+export function redact(text) {
+    let out = text;
+    for (const rule of environmentRules())
+        out = apply(out, rule);
+    for (const rule of RULES)
+        out = apply(out, rule);
+    return out;
+}
+/** The label a value named with `--omit` becomes. */
+export const OMITTED = "[omitted]";
+/** Values shorter than this are refused: two characters match half a text. */
+export const SHORTEST_OMIT = 3;
+/**
+ * Replace values the caller named, on top of everything `redact` finds.
+ *
+ * ⛔ LITERAL, NOT A PATTERN. What is passed is a file name or a folder somebody typed, and
+ *    treating it as a regular expression would turn a dot into "any character" and a bracket into
+ *    a syntax error in somebody's report.
+ */
+export function omitLiterals(text, values) {
+    let out = text;
+    for (const value of values) {
+        if (value.length < SHORTEST_OMIT)
+            continue;
+        out = out.replace(new RegExp(escapeForRegExp(value), "g"), OMITTED);
+    }
+    return out;
+}