@needmoretruth/nmts-cli 0.38.1 → 0.39.0

package/AGENTS.md

@@ -42,25 +42,12 @@ once, for an unlock (`nmts help login`).
 
 ## What is built on it today
 
-Each of these works with what is published now. None of it is a plan.
-
-- **Storage for an agent.** Notes, datasets and build outputs that outlive a session or a machine,
-  encrypted before they leave it. This command does it, and so does [its MCP server](#if-your-client-speaks-mcp).
-- **Encrypted storage inside someone's product.** The [SDK](https://github.com/needmoretruth/nmts-sdk)
-  opens an NMTS account for each person who uses a product and keeps that person's files in it. The
-  NMTS key is held by the person (the product cannot read the files) or by the product
-  (`Nmts.managed`), and every SDK method works the same either way. The
-  [terms](https://nmts.me/terms) provide for it in 3.7, for commercial products too.
-- **An S3 endpoint.** `@needmoretruth/nmts-sdk/gateway` speaks S3 with a bucket and a key pair per
-  customer, so django-storages, Rails Active Storage, rclone and backup tools store into NMTS
-  unchanged.
-- **Files that come back without NMTS.** [nmts-recovery](https://github.com/needmoretruth/nmts-recovery)
-  rebuilds an account's files from Walrus with the NMTS key and the recovery list the person saved.
-  No NMTS server takes part.
-
-An account pays with credits or straight from its own wallet. From the wallet, WAL goes to Walrus
-and SUI to the chain, and NMTS takes no fee. NMTS does not inspect or certify products built with the SDK: who holds the
-keys in such a product is that product's own statement.
+- **Storage for an agent**, outliving a session or a machine: this command, or [its MCP server](#if-your-client-speaks-mcp).
+- **Encrypted storage inside a product.** The [SDK](https://github.com/needmoretruth/nmts-sdk) (`npm install @needmoretruth/nmts-sdk`; it has an `AGENTS.md` of its own) opens an account per user. The user holds the NMTS key, or the product does (`Nmts.managed`); every method works either way, and [terms](https://nmts.me/terms) 3.7 provides for it, commercially too.
+- **An S3 endpoint**, `@needmoretruth/nmts-sdk/gateway`: a bucket and a key pair per customer, so django-storages, Rails Active Storage, rclone and backup tools store into NMTS unchanged.
+- **Files that come back without NMTS.** [nmts-recovery](https://github.com/needmoretruth/nmts-recovery) rebuilds them from Walrus with the NMTS key and the recovery list the person saved. No NMTS server takes part.
+
+All of it works with what is published now. An account pays with credits or from its own wallet — WAL to Walrus, SUI to the chain, no fee to NMTS. NMTS does not inspect or certify products built with the SDK: who holds the keys in one is that product's own statement.
 
 ## What only a person can do, once
 
@@ -189,12 +176,10 @@ work around it. Setup and the sealed-code rule: `nmts help mcp`.
 
 ## Remembering this across sessions
 
-You will lose this context. The person has to put it somewhere your next session reads: the file
-your client loads from a repository root, holding the first section above and the two
-environment variable names; a saved instruction saying *the `nmts` command manages files in an
-NMTS account; run `nmts env` first, then `nmts --help`, and `nmts help <command>` before a command
-you have not used*; or, for an MCP client, the server entry. The smallest thing that works is one
-line pointing at this file.
+You will lose this context. The person has to put it somewhere your next session reads: the file your client
+loads from a repository root, holding the first section above and the two environment variable names; a saved
+instruction saying *the `nmts` command manages files in an NMTS account; run `nmts env` first, then `nmts --help`,
+and `nmts help <command>` before a command you have not used*; or, for an MCP client, the server entry. One line pointing at this file is the smallest thing that works.
 
 ## Reporting a problem or an idea
 
@@ -204,17 +189,11 @@ run at all, write to `nmts@nmts.me` with what you ran and what it said.
 
 ## Exit codes
 
-`0` done · `1` something went wrong · `2` the command line was wrong · `3` not signed in ·
-`4` the command exists but could not do it · `5` waiting on the person's agreement ·
-`130` cancelled.
+`0` done · `1` something went wrong · `2` the command line was wrong · `3` not signed in · `4` the command exists
+but could not do it · `5` waiting on the person's agreement · `130` cancelled.
 
-## Licence
+## Licence and source
 
 Apache-2.0 (it was AGPL-3.0-only until 2026-08-30). **Calling this program from your own code puts
 no obligation on your code at all.** See [LICENSING.md](https://github.com/needmoretruth/nmts-cli/blob/main/LICENSING.md) if you are asked.
-
-## Source
-
-<https://github.com/needmoretruth/nmts-cli> · The same operations as a library, for a program that calls
-NMTS from its own code: `npm install @needmoretruth/nmts-sdk` · <https://github.com/needmoretruth/nmts-sdk>
-(its own document for agents is `AGENTS.md` there).
+Source: <https://github.com/needmoretruth/nmts-cli>.

package/CHANGELOG.md

@@ -3,6 +3,15 @@
 Each version's entry is what changed for the person or the program using `nmts`. The product's own
 update history, which covers the site and the server too, is at https://nmts.me/updates.
 
+## 0.39.0 — 2026-09-20
+
+- The library surface has a new entry, `@needmoretruth/nmts-cli/drive-erase`: what `nmts erase` does,
+  without the prompt or the printing, so a program can erase files for good with the same order of
+  operations. `nmts erase` is unchanged: the same sentence to type, the same output, the same exit
+  codes. `nmts-sdk` 0.5.0 is built on it.
+- A delegation token can carry a fifth scope, `files_erase`. The server still asks for the NMTS
+  key's own proof on the two erase requests.
+
 ## 0.38.1 — 2026-09-20
 
 - The folder and trash functions behind `@needmoretruth/nmts-cli/drive-edit` no longer import

package/README.ko.md

@@ -50,7 +50,7 @@ nmts --help
 
 ```sh
 npm install -g github:needmoretruth/nmts-cli            # 기본 브랜치
-npm install -g github:needmoretruth/nmts-cli#v0.38.1    # 버전을 고정할 때
+npm install -g github:needmoretruth/nmts-cli#v0.39.0    # 버전을 고정할 때
 npm install -g https://github.com/needmoretruth/nmts-cli/releases/latest/download/nmts.tgz
 ```
 

package/README.md

@@ -51,7 +51,7 @@ default branch, from a pinned version, or from the tarball attached to the
 
 ```sh
 npm install -g github:needmoretruth/nmts-cli            # the default branch
-npm install -g github:needmoretruth/nmts-cli#v0.38.1    # a pinned version
+npm install -g github:needmoretruth/nmts-cli#v0.39.0    # a pinned version
 npm install -g https://github.com/needmoretruth/nmts-cli/releases/latest/download/nmts.tgz
 ```
 

package/dist/artifact-about.d.ts

@@ -11,7 +11,7 @@ export declare const CRYPTO_SPEC_URL = "https://github.com/needmoretruth/nmts-re
  *   is the field's own contract — what the writer says about itself — and a person holding two
  *   copies of one account's artefacts can then tell which program made each.
  */
-export declare const WRITTEN_BY = "nmts-cli 0.38.1";
+export declare const WRITTEN_BY = "nmts-cli 0.39.0";
 /** Which of the three artefacts a wrapper is. A reader holding several can sort them. */
 export type ArtifactKind = "recovery-list" | "file-list" | "recovery-kit";
 /**

package/dist/commands/erase.js

@@ -9,28 +9,21 @@
 //    with credits, `--release-storage` asks the server to destroy the treasury's storage under
 //    each file first, which it does on the chain one blob at a time and reports per file.
 //
-// ⛔ THE SERVER GOES FIRST, THE LIST LAST. A row erased before the list entry leaves a file the
-//    person can see and never open; that is the same order the trash keeps, for the same reason.
-//    A release that fails leaves the file whole — nothing is erased behind a failed release.
+// ⛔ THE ORDER, AND WHAT IT PROTECTS, ARE IN `drive-erase.ts` — the server first, the list last, a
+//    failed release erasing nothing behind it. This file is the terminal over that: the sentence
+//    that has to be typed, the lines a person reads, and the exit code. Nothing about what is
+//    destroyed is decided twice.
 //
 // ⛔ THE SENTENCE IS TYPED IN EVERY MODE BUT SKIP-PERMISSIONS, where the tier gate's `--reason`
 //    and `--yes` stand for it — the same rule as `delete-account`, because it is the same tier.
 import { accountProofFor } from "../account-proof.js";
-import { request, ServerError } from "../api.js";
 import { currentMode } from "../autonomy.js";
 import { CONFIRM_SENTENCE } from "./delete-account.js";
-import { buildIndex, fullPathOf, KIND_FILE } from "../drive-paths.js";
+import { eraseFiles, planErase } from "../drive-erase.js";
 import { NmtsError } from "../errors.js";
-import { readFileList } from "../manifest.js";
-import { applyToList, batchTargets } from "../manifest-write.js";
 import { BINARY_NAME } from "../product.js";
 import { promptLine, stdinIsATerminal } from "../prompt.js";
 import { openSession } from "../session.js";
-import { filesUnder } from "../drive-edit.js";
-/** The server takes at most this many ids in one erase (`ERASE_BATCH_MAX`). */
-const BATCH = 200;
-/** The refusal a no-deposit release gets when the balance cannot cover the doubled fee. */
-const FEE_INSUFFICIENT = "DEPOSIT_FEE_INSUFFICIENT";
 export async function erase(paths, options = {}) {
     const say = options.write ?? ((line) => process.stdout.write(`${line}\n`));
     if (paths.length === 0) {
@@ -48,20 +41,11 @@ export async function erase(paths, options = {}) {
         });
     }
     const session = await openSession(options);
-    const list = await readFileList(session.server, session.apiKey, session.code, session.accountId);
-    const entries = list.manifest?.entries ?? [];
-    const index = buildIndex(entries);
-    const targets = batchTargets(entries, paths, { includeTrashed: true, nothingHappened: "Nothing was erased." });
-    const files = uniqueById(targets.flatMap((t) => (t.kind === KIND_FILE ? [t] : filesUnder(entries, t.id))));
-    const going = uniqueById([...targets, ...files]);
-    if (files.length === 0) {
-        throw new NmtsError(`Nothing named holds a file; empty folders are removed with \`${BINARY_NAME} rm\`.`, {
-            exitCode: 4,
-        });
-    }
+    const plan = await planErase(session, paths);
+    const files = plan.files;
     say(`This erases ${files.length} file${files.length === 1 ? "" : "s"} for good. It cannot be undone, and not by the trash.`);
     for (const f of files)
-        say(`  ${fullPathOf(index, f)}`);
+        say(`  ${f.path}`);
     say(``);
     say(`  Erased:       the server's record of each file and this account's key to it, and its shares.`);
     if (options.releaseStorage === true) {
@@ -81,65 +65,12 @@ export async function erase(paths, options = {}) {
     }
     // ⛔ THE PROOF IS BUILT FOR THIS ONE RUN AND NOTHING KEEPS IT.
     const accountProof = await accountProofFor({ code: session.code, source: session.source });
-    const releases = [];
-    if (options.releaseStorage === true) {
-        for (const f of files) {
-            const path = fullPathOf(index, f);
-            try {
-                const reply = await request(session.server, `/v1/items/${encodeURIComponent(f.id)}/release-storage`, {
-                    method: "POST",
-                    body: {},
-                    token: session.apiKey,
-                    accountProof,
-                });
-                releases.push({ path, refused: null, ...counts(reply), ...fee(reply) });
-            }
-            catch (error) {
-                // ⛔ THE ONE REFUSAL THAT STOPS THE RUN. A file with no deposit pays twice the chain fee
-                //    out of the balance, and a balance that cannot cover it means the release did not
-                //    happen — erasing behind it would destroy the account's key to bytes that are still
-                //    being served and still being paid for. Nothing is erased, and the two numbers say
-                //    exactly how far short the balance is.
-                if (error instanceof ServerError && error.code === FEE_INSUFFICIENT) {
-                    throw new NmtsError(`${path}: releasing its storage costs ${amount(error, "needed_credits")} credits and this ` +
-                        `account has ${amount(error, "balance_credits")}. It has no deposit, so the fee comes out of the balance.`, {
-                        exitCode: 4,
-                        nextStep: `Nothing was erased. Buy credits and run this again, or leave --release-storage off ` +
-                            `to erase the file and let its storage run out on its own.`,
-                    });
-                }
-                // ⚠ "Not ours to destroy" is an answer, not a failure: the storage was bought by the
-                //   wallet, and the erase goes on. A refusal of the KEY or the proof, and anything the
-                //   server could not do, stops the run before a row is touched.
-                if (error instanceof ServerError && error.status !== 401 && error.status !== 403 && error.status < 500) {
-                    releases.push({ path, released: 0, alreadyReleased: 0, failed: 0, feeCredits: 0, fromDeposit: false, refused: error.message });
-                    continue;
-                }
-                throw error;
-            }
-        }
-    }
-    let erased = 0;
-    for (let i = 0; i < files.length; i += BATCH) {
-        const reply = await request(session.server, "/v1/items/erase", {
-            method: "POST",
-            body: { item_ids: files.slice(i, i + BATCH).map((f) => f.id) },
-            token: session.apiKey,
-            accountProof,
-        });
-        erased += typeof reply === "object" && reply !== null && typeof Reflect.get(reply, "erased") === "number"
-            ? Number(Reflect.get(reply, "erased"))
-            : 0;
-    }
-    // ⛔ THE LIST GOES LAST, and re-decided against the list as it is on this attempt: only the
-    //    ids this run erased leave it, whatever another device wrote in between.
-    const ids = new Set(going.map((e) => e.id));
-    const result = await applyToList(session, (current) => {
-        const still = current.filter((e) => ids.has(e.id)).map((e) => e.id);
-        return still.length === 0 ? null : { op: "purge", ids: still };
+    const outcome = await eraseFiles({ ...session, accountProof }, plan, {
+        releaseStorage: options.releaseStorage === true,
     });
+    const { erased, releases } = outcome;
     if (options.json) {
-        say(JSON.stringify({ erased, files: files.map((f) => ({ id: f.id, path: fullPathOf(index, f) })), releases, seq: result.seq }));
+        say(JSON.stringify({ erased, files: outcome.files, releases, seq: outcome.seq }));
         return 0;
     }
     say(`Erased ${erased} file${erased === 1 ? "" : "s"}. Their entries are out of the file list.`);
@@ -165,29 +96,3 @@ function feeLine(r) {
         ? `${credits} taken from that file's deposit — nothing came out of the balance`
         : `${credits} taken from the balance — that file had no deposit, so the fee is doubled`;
 }
-/** The three counts a release answers with, read defensively. */
-function counts(reply) {
-    const n = (name) => {
-        const v = typeof reply === "object" && reply !== null ? Reflect.get(reply, name) : undefined;
-        return typeof v === "number" ? v : 0;
-    };
-    return { released: n("released"), alreadyReleased: n("already_released"), failed: n("failed") };
-}
-/** What it cost, read the same defensive way. An older server says neither, which reads as 0. */
-function fee(reply) {
-    const at = (name) => typeof reply === "object" && reply !== null ? Reflect.get(reply, name) : undefined;
-    const charged = at("fee_credits");
-    return {
-        feeCredits: typeof charged === "number" ? charged : 0,
-        fromDeposit: at("from_deposit") === true,
-    };
-}
-/** One credit amount out of a refusal's details, or `?` when the server did not name it. */
-function amount(error, field) {
-    const value = error.details[field];
-    return typeof value === "number" ? String(value) : "?";
-}
-function uniqueById(list) {
-    const seen = new Set();
-    return list.filter((e) => (seen.has(e.id) ? false : (seen.add(e.id), true)));
-}

package/dist/drive-erase.d.ts

@@ -0,0 +1,83 @@
+import { type ListEditInput } from "./manifest-write.ts";
+/** What the erasing underneath takes: where to talk, what opens the list, and whose list it is. */
+export interface EraseInput extends ListEditInput {
+    /**
+     * The account code's own proof for this one run, base64url — what the two permanent doors ask
+     * for beside the credential (`x-nmts-account-proof`).
+     *
+     * ⛔ BUILT BY THE CALLER AND KEPT BY NOBODY. It is not the NMTS key and opens no file; what it
+     *    proves is possession of the code, which is exactly the question these two doors ask.
+     */
+    accountProof: string;
+}
+export interface EraseOptions {
+    /** Also destroy the treasury's storage under credit-paid files, before erasing them. */
+    releaseStorage?: boolean;
+}
+/** One thing this run acts on: its id, and where it sits in the list as it was read. */
+export interface ErasePath {
+    id: string;
+    path: string;
+}
+/** What one run will destroy, worked out before anything is sent. */
+export interface ErasePlan {
+    /** Every FILE going: the ones named, and every file under a folder that was named. */
+    readonly files: readonly ErasePath[];
+    /**
+     * The ids leaving the sealed list — the files above and the folders that were named.
+     *
+     * ⚠ WIDER THAN `files` ON PURPOSE. A named folder has no server row of its own, so nothing is
+     *   erased for it; its entry still has to go, or the list keeps a folder whose contents are gone.
+     */
+    readonly going: readonly string[];
+}
+/** What one file's storage release came back with. */
+export interface StorageRelease {
+    path: string;
+    released: number;
+    alreadyReleased: number;
+    failed: number;
+    /**
+     * Credits the release actually cost, and where they came from.
+     *
+     * ⛔ TWO FIELDS, NOT ONE, because "it cost nothing" and "it cost nothing OUT OF THE BALANCE" are
+     *    different answers and only one of them is true. A release paid out of the file's own
+     *    deposit charges the balance nothing; a file with no deposit pays twice the fee from the
+     *    balance, and somebody watching their credits needs to be able to tell which happened.
+     */
+    feeCredits: number;
+    fromDeposit: boolean;
+    /** The server's typed refusal when the storage was not the treasury's to destroy. */
+    refused: string | null;
+}
+/** What one run did. */
+export interface EraseOutcome {
+    /** How many server rows went. Lower than what was asked for when one was already gone. */
+    erased: number;
+    /** The files it acted on, with the paths they had. */
+    files: ErasePath[];
+    /** One per file whose storage was asked about — empty unless `releaseStorage` was asked for. */
+    releases: StorageRelease[];
+    /** The version of the sealed list after the entries left it. */
+    seq: number;
+}
+/**
+ * Work out what erasing these paths would destroy, without destroying anything.
+ *
+ * ⛔ ITS OWN STEP BECAUSE ONE CALLER HAS TO SHOW THE LIST BEFORE IT ASKS. `nmts erase` prints every
+ *    file it is about to destroy and then waits for a typed sentence; folding this into the act
+ *    would leave the terminal with nothing to print, and reading the list twice would leave the
+ *    two reads free to disagree about what is in it.
+ */
+export declare function planErase(input: ListEditInput, paths: readonly string[]): Promise<ErasePlan>;
+/**
+ * Destroy what the plan names. ⛔ Irreversible, and nothing below asks whether the caller meant it.
+ */
+export declare function eraseFiles(input: EraseInput, plan: ErasePlan, options?: EraseOptions): Promise<EraseOutcome>;
+/**
+ * Resolve these paths and destroy what they name, in one call.
+ *
+ * ⚠ FOR A CALLER THAT HAS ALREADY DECIDED. Anything that shows a person what is about to go should
+ *   use `planErase` first, so what it shows is what it then destroys.
+ */
+export declare function erasePaths(input: EraseInput, paths: readonly string[], options?: EraseOptions): Promise<EraseOutcome>;

package/dist/drive-erase.js

@@ -0,0 +1,161 @@
+// Erasing files for good, without a terminal: the targets resolved, the treasury's storage let go,
+// the server's records destroyed and the entries taken out of the sealed list — decided, done and
+// handed back rather than printed.
+//
+// ⛔ ONE IMPLEMENTATION, TWO CALLERS, WHICH IS THE WHOLE REASON THIS FILE EXISTS — the argument
+//    `drive-edit.ts` makes one verb family over. `commands/erase.ts` is a terminal's shape: it
+//    prints the list, asks for the typed sentence and answers an exit code. The SDK is somebody
+//    else's program and needs the same act with none of those. A second implementation of "what
+//    order do these three destructions happen in" would be a second place for the rules below to
+//    be got right, and the copy nobody re-reads is the one that quietly disagrees — about the one
+//    verb in this package that nothing can undo.
+//
+// ⛔ NOTHING HERE WRITES TO A STREAM, PICKS AN EXIT CODE OR ASKS ANYBODY ANYTHING. The confirmation
+//    is the caller's: a terminal types a sentence, a program passes one. This file is reached only
+//    after somebody decided, and it destroys what it is given.
+//
+// ⛔ THE SERVER GOES FIRST AND THE LIST LAST, which is the order the trash keeps and for the same
+//    reason: a row erased before its list entry leaves a file the person can see and never open.
+//    A release that FAILS stops the run before a single row is touched — nothing is erased behind
+//    one. A release the server REFUSES ("that storage was bought by the wallet, not by credits")
+//    is an answer rather than a failure: it is reported on that file and the erase goes on.
+//
+// ⛔ THE PROOF IS THE CALLER'S TO BUILD AND IS NOT DERIVED HERE. Both doors ask for the account
+//    code's own proof, and WHETHER this run may make one is a policy question with two different
+//    answers — the command line asks for an agreement first (`account-proof.ts`), a library caller
+//    has already made that decision by calling. So it arrives as a value. Nothing here reaches for
+//    `node:`: the SDK's browser entry bundles what this exports.
+//
+// ⚠ THE PIECES IT BORROWS COME FROM `drive-edit/` DIRECTLY, the way that folder's own files borrow
+//   from each other. This is a sibling of that family rather than an outside caller.
+import { request, ServerError } from "./api.js";
+import { DriveEditError, resolving } from "./drive-edit/errors.js";
+import { filesUnder, uniqueById } from "./drive-edit/tree.js";
+import { buildIndex, fullPathOf, KIND_FILE } from "./drive-paths.js";
+import { NmtsError } from "./errors.js";
+import { readFileList } from "./manifest.js";
+import { applyToList, batchTargets } from "./manifest-write.js";
+import { BINARY_NAME } from "./product.js";
+/** The server takes at most this many ids in one erase (`ERASE_BATCH_MAX`). */
+const BATCH = 200;
+/** The refusal a no-deposit release gets when the balance cannot cover the doubled fee. */
+const FEE_INSUFFICIENT = "DEPOSIT_FEE_INSUFFICIENT";
+/**
+ * Work out what erasing these paths would destroy, without destroying anything.
+ *
+ * ⛔ ITS OWN STEP BECAUSE ONE CALLER HAS TO SHOW THE LIST BEFORE IT ASKS. `nmts erase` prints every
+ *    file it is about to destroy and then waits for a typed sentence; folding this into the act
+ *    would leave the terminal with nothing to print, and reading the list twice would leave the
+ *    two reads free to disagree about what is in it.
+ */
+export async function planErase(input, paths) {
+    const list = await readFileList(input.server, input.apiKey, input.code, input.accountId);
+    const entries = list.manifest?.entries ?? [];
+    const index = buildIndex(entries);
+    const targets = resolving(() => batchTargets(entries, paths, { includeTrashed: true, nothingHappened: "Nothing was erased." }));
+    const files = uniqueById(targets.flatMap((t) => (t.kind === KIND_FILE ? [t] : filesUnder(entries, t.id))));
+    const going = uniqueById([...targets, ...files]);
+    if (files.length === 0) {
+        throw new DriveEditError("NOT_FOUND", `Nothing named holds a file; empty folders are removed with \`${BINARY_NAME} rm\`.`, {
+            exitCode: 4,
+        });
+    }
+    return {
+        files: files.map((f) => ({ id: f.id, path: fullPathOf(index, f) })),
+        going: going.map((e) => e.id),
+    };
+}
+/**
+ * Destroy what the plan names. ⛔ Irreversible, and nothing below asks whether the caller meant it.
+ */
+export async function eraseFiles(input, plan, options = {}) {
+    const releases = [];
+    if (options.releaseStorage === true) {
+        for (const f of plan.files) {
+            const path = f.path;
+            try {
+                const reply = await request(input.server, `/v1/items/${encodeURIComponent(f.id)}/release-storage`, {
+                    method: "POST",
+                    body: {},
+                    token: input.apiKey,
+                    accountProof: input.accountProof,
+                });
+                releases.push({ path, refused: null, ...counts(reply), ...fee(reply) });
+            }
+            catch (error) {
+                // ⛔ THE ONE REFUSAL THAT STOPS THE RUN. A file with no deposit pays twice the chain fee
+                //    out of the balance, and a balance that cannot cover it means the release did not
+                //    happen — erasing behind it would destroy the account's key to bytes that are still
+                //    being served and still being paid for. Nothing is erased, and the two numbers say
+                //    exactly how far short the balance is.
+                if (error instanceof ServerError && error.code === FEE_INSUFFICIENT) {
+                    throw new NmtsError(`${path}: releasing its storage costs ${amount(error, "needed_credits")} credits and this ` +
+                        `account has ${amount(error, "balance_credits")}. It has no deposit, so the fee comes out of the balance.`, {
+                        exitCode: 4,
+                        nextStep: `Nothing was erased. Buy credits and run this again, or leave --release-storage off ` +
+                            `to erase the file and let its storage run out on its own.`,
+                    });
+                }
+                // ⚠ "Not ours to destroy" is an answer, not a failure: the storage was bought by the
+                //   wallet, and the erase goes on. A refusal of the KEY or the proof, and anything the
+                //   server could not do, stops the run before a row is touched.
+                if (error instanceof ServerError && error.status !== 401 && error.status !== 403 && error.status < 500) {
+                    releases.push({ path, released: 0, alreadyReleased: 0, failed: 0, feeCredits: 0, fromDeposit: false, refused: error.message });
+                    continue;
+                }
+                throw error;
+            }
+        }
+    }
+    let erased = 0;
+    for (let i = 0; i < plan.files.length; i += BATCH) {
+        const reply = await request(input.server, "/v1/items/erase", {
+            method: "POST",
+            body: { item_ids: plan.files.slice(i, i + BATCH).map((f) => f.id) },
+            token: input.apiKey,
+            accountProof: input.accountProof,
+        });
+        erased += typeof reply === "object" && reply !== null && typeof Reflect.get(reply, "erased") === "number"
+            ? Number(Reflect.get(reply, "erased"))
+            : 0;
+    }
+    // ⛔ THE LIST GOES LAST, and re-decided against the list as it is on this attempt: only the
+    //    ids this run erased leave it, whatever another device wrote in between.
+    const ids = new Set(plan.going);
+    const result = await applyToList(input, (current) => {
+        const still = current.filter((e) => ids.has(e.id)).map((e) => e.id);
+        return still.length === 0 ? null : { op: "purge", ids: still };
+    });
+    return { erased, files: [...plan.files], releases, seq: result.seq };
+}
+/**
+ * Resolve these paths and destroy what they name, in one call.
+ *
+ * ⚠ FOR A CALLER THAT HAS ALREADY DECIDED. Anything that shows a person what is about to go should
+ *   use `planErase` first, so what it shows is what it then destroys.
+ */
+export async function erasePaths(input, paths, options = {}) {
+    return eraseFiles(input, await planErase(input, paths), options);
+}
+/** The three counts a release answers with, read defensively. */
+function counts(reply) {
+    const n = (name) => {
+        const v = typeof reply === "object" && reply !== null ? Reflect.get(reply, name) : undefined;
+        return typeof v === "number" ? v : 0;
+    };
+    return { released: n("released"), alreadyReleased: n("already_released"), failed: n("failed") };
+}
+/** What it cost, read the same defensive way. An older server says neither, which reads as 0. */
+function fee(reply) {
+    const at = (name) => typeof reply === "object" && reply !== null ? Reflect.get(reply, name) : undefined;
+    const charged = at("fee_credits");
+    return {
+        feeCredits: typeof charged === "number" ? charged : 0,
+        fromDeposit: at("from_deposit") === true,
+    };
+}
+/** One credit amount out of a refusal's details, or `?` when the server did not name it. */
+function amount(error, field) {
+    const value = error.details[field];
+    return typeof value === "number" ? String(value) : "?";
+}

package/dist/platform-sign.d.ts

@@ -25,14 +25,22 @@ export declare const DELEGATION_MAX_TTL_SECS = 2592000;
  * ⛔ THE FIRST THREE ARE AN API KEY'S OWN SCOPES, value for value. One vocabulary, so that a
  *    business asking for "read and write" asks for the number a person's key already means by it.
  *    `register` is the fourth and opens exactly one door: making the account the token names.
+ *
+ * ⛔ `files_erase` IS THE FIFTH, AND AN API KEY HAS NO BIT OF THAT NAME. It opens the two acts
+ *    nothing undoes: erasing a file's record and this account's key to it, and destroying the
+ *    treasury's storage under a file. Its own name rather than `files_write`, so a token minted so
+ *    an app can upload cannot destroy — and it does not stand alone: both doors also ask for the
+ *    account code's own proof on the same request, which is an act only whoever holds the code can
+ *    perform. The token is the business's permission; the proof is the key holder's.
  */
 export declare const SCOPE_BITS: {
     readonly files_read: 1;
     readonly files_write: 2;
     readonly storage_spend: 4;
     readonly register: 8;
+    readonly files_erase: 16;
 };
-/** One of the four names above. */
+/** One of the five names above. */
 export type ScopeName = keyof typeof SCOPE_BITS;
 /** Every bit a token may carry. */
 export declare const SCOPE_ALL: number;

package/dist/platform-sign.js

@@ -53,15 +53,23 @@ export const DELEGATION_MAX_TTL_SECS = 2_592_000;
  * ⛔ THE FIRST THREE ARE AN API KEY'S OWN SCOPES, value for value. One vocabulary, so that a
  *    business asking for "read and write" asks for the number a person's key already means by it.
  *    `register` is the fourth and opens exactly one door: making the account the token names.
+ *
+ * ⛔ `files_erase` IS THE FIFTH, AND AN API KEY HAS NO BIT OF THAT NAME. It opens the two acts
+ *    nothing undoes: erasing a file's record and this account's key to it, and destroying the
+ *    treasury's storage under a file. Its own name rather than `files_write`, so a token minted so
+ *    an app can upload cannot destroy — and it does not stand alone: both doors also ask for the
+ *    account code's own proof on the same request, which is an act only whoever holds the code can
+ *    perform. The token is the business's permission; the proof is the key holder's.
  */
 export const SCOPE_BITS = {
     files_read: 1,
     files_write: 2,
     storage_spend: 4,
     register: 8,
+    files_erase: 16,
 };
 /** Every bit a token may carry. */
-export const SCOPE_ALL = SCOPE_BITS.files_read | SCOPE_BITS.files_write | SCOPE_BITS.storage_spend | SCOPE_BITS.register;
+export const SCOPE_ALL = SCOPE_BITS.files_read | SCOPE_BITS.files_write | SCOPE_BITS.storage_spend | SCOPE_BITS.register | SCOPE_BITS.files_erase;
 /**
  * A new key pair, from the runtime's own random source.
  *

package/dist/product.d.ts

@@ -9,7 +9,7 @@ export declare const BINARY_NAME = "nmts";
  *    beside it. Here rather than in `main.ts` because the MCP server has to say it too, and a
  *    command importing the entry point is a cycle waiting to bite.
  */
-export declare const VERSION = "0.38.1";
+export declare const VERSION = "0.39.0";
 /** Where the product lives, for messages that need to send somebody somewhere real. */
 export declare const HOME_URL = "https://nmts.me";
 /** The source, so a person holding only the built program can find what it was built from. */

package/dist/product.js

@@ -18,7 +18,7 @@ export const BINARY_NAME = "nmts";
  *    beside it. Here rather than in `main.ts` because the MCP server has to say it too, and a
  *    command importing the entry point is a cycle waiting to bite.
  */
-export const VERSION = "0.38.1";
+export const VERSION = "0.39.0";
 /** Where the product lives, for messages that need to send somebody somewhere real. */
 export const HOME_URL = "https://nmts.me";
 /** The source, so a person holding only the built program can find what it was built from. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@needmoretruth/nmts-cli",
-  "version": "0.38.1",
+  "version": "0.39.0",
   "description": "Command-line and MCP access to NMTS (NeedMoreTruthStorage, https://nmts.me): open-source, end-to-end encrypted storage on the Walrus network. No fee to NMTS; you pay the network from your own wallet. For people and for their agents.",
   "license": "Apache-2.0",
   "publishConfig": {
@@ -81,6 +81,10 @@
       "types": "./dist/drive-edit.d.ts",
       "default": "./dist/drive-edit.js"
     },
+    "./drive-erase": {
+      "types": "./dist/drive-erase.d.ts",
+      "default": "./dist/drive-erase.js"
+    },
     "./s3-gateway": {
       "types": "./dist/s3-gateway.d.ts",
       "default": "./dist/s3-gateway.js"