@needmoretruth/nmts-cli 0.34.4 → 0.36.1

package/dist/upload-steps.js

@@ -70,14 +70,14 @@ export async function commitItem(input, fileKey, parts) {
     // Advisory only — the chain is the authority on a blob's life. 0 when this machine could not
     // read the epoch clock: a number we do not have is not a number to invent.
     const expiryEpoch = input.currentEpoch === null ? 0 : input.currentEpoch + input.epochs;
-    const previous = readItemRecord(fileKey);
+    const previous = await readItemRecord(fileKey);
     // ⛔ ALREADY COMMITTED IS NOT COMMITTED AGAIN. The record outlives the commit precisely so a run
     //    that died before writing the file list does not make a second file out of storage that is
     //    already named.
     if (previous?.itemId !== undefined)
         return previous.itemId;
     const attempt = previous?.attempt ?? 0;
-    writeItemRecord(fileKey, { attempt });
+    await writeItemRecord(fileKey, { attempt });
     let view;
     try {
         view = await input.api.createItem({
@@ -100,7 +100,7 @@ export async function commitItem(input, fileKey, parts) {
     // ⛔ Written down before returning: from here on the file EXISTS and is paid for, and the only
     //    thing still missing is the account's own list. Losing the record now would make it
     //    unreachable.
-    writeItemRecord(fileKey, { attempt, itemId: view.id });
+    await writeItemRecord(fileKey, { attempt, itemId: view.id });
     return view.id;
 }
 /**

package/dist/upload-store.d.ts

@@ -1,6 +1,6 @@
-import { type Hash } from "node:crypto";
-/** Where unfinished uploads live. */
-export declare function uploadsDir(): string;
+import { sha256 } from "@noble/hashes/sha2.js";
+/** The running hash a reservation key is built in. */
+export type ReservationHash = ReturnType<typeof sha256.create>;
 /**
  * A stable, account-scoped name for one file's upload attempt.
  *
@@ -36,9 +36,9 @@ export declare function reservationKeyStreamed(dataKey: Uint8Array, plaintextChu
  *    the SHA-256 the account checks its contents against; handing the caller the running hash is
  *    what lets both come out of a single pass instead of two reads of a very large file.
  */
-export declare function startReservationKey(dataKey: Uint8Array): Hash;
+export declare function startReservationKey(dataKey: Uint8Array): ReservationHash;
 /** Finish it. The name and the destination go in last, exactly as the one-shot form does. */
-export declare function finishReservationKey(hash: Hash, name: string, destination: string): string;
+export declare function finishReservationKey(hash: ReservationHash, name: string, destination: string): string;
 /**
  * The record name for ONE part of a file.
  *
@@ -131,7 +131,7 @@ export interface Reservation {
  *    resume that only needs to commit still reads every byte of a very large upload off the disk.
  *    They are fetched separately, by the one step that actually pushes them.
  */
-export declare function readReservationRecord(key: string): Reservation | null;
+export declare function readReservationRecord(key: string): Promise<Reservation | null>;
 /**
  * The sealed bytes a reservation bought.
  *
@@ -139,14 +139,14 @@ export declare function readReservationRecord(key: string): Reservation | null;
  *    different blob from the one the treasury registered — the relay refuses them, forever, and
  *    the credits are gone.
  */
-export declare function readReservationBytes(key: string): Uint8Array;
+export declare function readReservationBytes(key: string): Promise<Uint8Array>;
 /** The record and its bytes together, for the callers that need both. */
-export declare function readReservation(key: string): {
+export declare function readReservation(key: string): Promise<{
     record: Reservation;
     sealed: Uint8Array;
-} | null;
+} | null>;
 /** Write the record and its sealed bytes. Called BEFORE the reserve, and again after it answers. */
-export declare function writeReservation(key: string, record: Reservation, sealed: Uint8Array): void;
+export declare function writeReservation(key: string, record: Reservation, sealed: Uint8Array): Promise<void>;
 /**
  * Forget a reservation.
  *
@@ -154,7 +154,7 @@ export declare function writeReservation(key: string, record: Reservation, seale
  *   upload already succeeded" was not true of every caller. What IS true of all of them is that
  *   nothing further depends on the record, which is why it never throws.
  */
-export declare function clearReservation(key: string): void;
+export declare function clearReservation(key: string): Promise<void>;
 /**
  * The FILE-level half of an unfinished upload: what happened after every part was paid for.
  *
@@ -175,8 +175,8 @@ export interface ItemRecord {
     attempt: number;
 }
 /** What is known about this file's commit, or `null` when it has not been attempted. */
-export declare function readItemRecord(fileKey: string): ItemRecord | null;
+export declare function readItemRecord(fileKey: string): Promise<ItemRecord | null>;
 /** Write the file-level record. Called before the commit, and again once it has an id. */
-export declare function writeItemRecord(fileKey: string, record: ItemRecord): void;
+export declare function writeItemRecord(fileKey: string, record: ItemRecord): Promise<void>;
 /** Forget the file-level record. Never throws, for the same reason `clearReservation` does not. */
-export declare function clearItemRecord(fileKey: string): void;
+export declare function clearItemRecord(fileKey: string): Promise<void>;

package/dist/upload-store.js

@@ -9,25 +9,21 @@
 //
 //    So they are written down BEFORE the money moves. That ordering is the whole design.
 //
-// ⛔ WHAT IS ON DISK IS ALREADY PUBLIC. The `.bin` is the sealed NCF-3 stream — the exact bytes
-//    about to be handed to a public storage network. It is still written 0600, because "already
-//    public" is about the CONTENT and the file's presence would otherwise say which files this
-//    account uploaded and when.
+// ⛔ WHAT IS KEPT IS ALREADY PUBLIC. The `.bin` half is the sealed NCF-3 stream — the exact bytes
+//    about to be handed to a public storage network. The host still keeps it as privately as it
+//    can (0600 on this machine), because "already public" is about the CONTENT and the record's
+//    presence would otherwise say which files this account uploaded and when.
 //
-// ⛔ THE FILE NAME IS NOT A CONTENT FINGERPRINT. Keying by SHA-256 of the plaintext would leave a
-//    directory of hashes matchable against published hash sets — the very thing sealing the
-//    content hash avoids. The key mixes the account's data key in, so it identifies the file only
-//    to somebody who already holds the account.
-import { createHash } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-import { configDir, modesAreEnforced } from "./credentials.js";
-import { chmodSync } from "node:fs";
+// ⛔ THE KEY IS NOT A CONTENT FINGERPRINT. Keying by SHA-256 of the plaintext would leave a store
+//    of hashes matchable against published hash sets — the very thing sealing the content hash
+//    avoids. The key mixes the account's data key in, so it identifies the file only to somebody
+//    who already holds the account.
+import { sha256 } from "@noble/hashes/sha2.js";
+import { fromUtf8, toBase64Url, utf8 } from "./bytes.js";
 import { NmtsError } from "./errors.js";
-/** Where unfinished uploads live. */
-export function uploadsDir() {
-    return join(configDir(), "uploads");
-}
+import { host } from "./host.js";
+/** The area of the host's state these records live in. One key per file below it. */
+const AREA = "uploads";
 /**
  * A stable, account-scoped name for one file's upload attempt.
  *
@@ -71,12 +67,12 @@ export function reservationKeyStreamed(dataKey, plaintextChunks, name, destinati
  *    what lets both come out of a single pass instead of two reads of a very large file.
  */
 export function startReservationKey(dataKey) {
-    return createHash("sha256").update(dataKey);
+    return sha256.create().update(dataKey);
 }
 /** Finish it. The name and the destination go in last, exactly as the one-shot form does. */
 export function finishReservationKey(hash, name, destination) {
-    const digest = hash.update(new TextEncoder().encode(`\u0000${name}\u0000${destination}`)).digest();
-    return Buffer.from(digest).toString("base64url").slice(0, 32);
+    const digest = hash.update(utf8(`\u0000${name}\u0000${destination}`)).digest();
+    return toBase64Url(digest).slice(0, 32);
 }
 /**
  * The record name for ONE part of a file.
@@ -89,9 +85,9 @@ export function finishReservationKey(hash, name, destination) {
 export function partKey(fileKey, partIndex) {
     return `${fileKey}~p${partIndex}`;
 }
-function paths(key) {
-    const dir = uploadsDir();
-    return { json: join(dir, `${key}.json`), bin: join(dir, `${key}.bin`) };
+/** The two keys one part's reservation occupies: its record, and the sealed bytes it bought. */
+function keysFor(key) {
+    return { json: `${AREA}/${key}.json`, bin: `${AREA}/${key}.bin` };
 }
 function isReservation(value) {
     if (typeof value !== "object" || value === null)
@@ -114,23 +110,25 @@ function isReservation(value) {
  *    resume that only needs to commit still reads every byte of a very large upload off the disk.
  *    They are fetched separately, by the one step that actually pushes them.
  */
-export function readReservationRecord(key) {
-    const { json, bin } = paths(key);
-    if (!existsSync(json) || !existsSync(bin))
+export async function readReservationRecord(key) {
+    const { json, bin } = keysFor(key);
+    const state = host().state;
+    const held = await state.read(json);
+    if (held === undefined || (await state.read(bin)) === undefined)
         return null;
     let parsed;
     try {
-        parsed = JSON.parse(readFileSync(json, "utf8"));
+        parsed = JSON.parse(fromUtf8(held));
     }
     catch {
         // ⛔ Unreadable is not the same as absent, and treating it as absent would buy storage twice.
-        throw new NmtsError(`An unfinished upload record at ${json} could not be read.`, {
+        throw new NmtsError(`The unfinished upload record ${json} could not be read.`, {
             nextStep: "It names storage this account may already have paid for. Move it aside rather than " +
                 "deleting it if the upload matters, then try again.",
         });
     }
     if (!isReservation(parsed)) {
-        throw new NmtsError(`The unfinished upload record at ${json} is not in a shape this version knows.`, {
+        throw new NmtsError(`The unfinished upload record ${json} is not in a shape this version knows.`, {
             nextStep: "Move it aside and try again. Nothing was sent.",
         });
     }
@@ -143,38 +141,36 @@ export function readReservationRecord(key) {
  *    different blob from the one the treasury registered — the relay refuses them, forever, and
  *    the credits are gone.
  */
-export function readReservationBytes(key) {
-    const { bin } = paths(key);
-    return new Uint8Array(readFileSync(bin));
+export async function readReservationBytes(key) {
+    const { bin } = keysFor(key);
+    const held = await host().state.read(bin);
+    if (held === undefined) {
+        throw new NmtsError(`The sealed bytes of ${bin} are gone.`, {
+            nextStep: "Nothing was sent. The storage they bought cannot be filled by re-sealing — run the " +
+                "upload again to buy storage for a fresh sealing of the same file.",
+        });
+    }
+    return held;
 }
 /** The record and its bytes together, for the callers that need both. */
-export function readReservation(key) {
-    const record = readReservationRecord(key);
+export async function readReservation(key) {
+    const record = await readReservationRecord(key);
     if (record === null)
         return null;
-    return { record, sealed: readReservationBytes(key) };
+    return { record, sealed: await readReservationBytes(key) };
 }
 /** Write the record and its sealed bytes. Called BEFORE the reserve, and again after it answers. */
-export function writeReservation(key, record, sealed) {
-    const dir = uploadsDir();
-    mkdirSync(dir, { recursive: true, mode: 0o700 });
-    if (modesAreEnforced())
-        chmodSync(dir, 0o700);
-    const { json, bin } = paths(key);
-    // ⛔ WRITTEN ASIDE AND RENAMED OVER, never truncated in place. A rename within one directory is
-    //    atomic, so a reader sees the old record or the new one and never a half-written one. The
-    //    write that matters is the LAST one — the one that adds the item id — because a truncated
-    //    file there is the only local pointer to a file that is already paid for and committed, and
-    //    losing it makes that file invisible.
-    atomically(bin, sealed);
-    atomically(json, Buffer.from(`${JSON.stringify(record, null, 2)}\n`, "utf8"));
-}
-function atomically(target, bytes) {
-    const scratch = `${target}.${process.pid}.tmp`;
-    writeFileSync(scratch, bytes, { mode: 0o600 });
-    if (modesAreEnforced())
-        chmodSync(scratch, 0o600);
-    renameSync(scratch, target);
+export async function writeReservation(key, record, sealed) {
+    const { json, bin } = keysFor(key);
+    // ⛔ THE BYTES GO DOWN FIRST, AND THE RECORD IS WHAT MAKES THE PAIR COUNT. A reader treats a
+    //    record without its bytes as no reservation at all, so a run that stopped between these two
+    //    writes leaves nothing that can be resumed — rather than a record pointing at bytes that are
+    //    not there. Each write on its own is all-or-nothing; that is the host's promise, and the
+    //    write that matters most is the LAST one, because a half-written record is the only local
+    //    pointer to a file that is already paid for.
+    const state = host().state;
+    await state.write(bin, sealed);
+    await state.write(json, utf8(`${JSON.stringify(record, null, 2)}\n`));
 }
 /**
  * Forget a reservation.
@@ -183,11 +179,11 @@ function atomically(target, bytes) {
  *   upload already succeeded" was not true of every caller. What IS true of all of them is that
  *   nothing further depends on the record, which is why it never throws.
  */
-export function clearReservation(key) {
-    const { json, bin } = paths(key);
-    for (const path of [json, bin]) {
+export async function clearReservation(key) {
+    const { json, bin } = keysFor(key);
+    for (const name of [json, bin]) {
         try {
-            rmSync(path, { force: true });
+            await host().state.remove(name);
         }
         catch {
             // ⚠ A record that cannot be removed is left where it is. That is not free -- a record
@@ -197,8 +193,8 @@ export function clearReservation(key) {
         }
     }
 }
-function itemPath(fileKey) {
-    return join(uploadsDir(), `${fileKey}.item.json`);
+function itemKey(fileKey) {
+    return `${AREA}/${fileKey}.item.json`;
 }
 function isItemRecord(value) {
     if (typeof value !== "object" || value === null)
@@ -209,41 +205,38 @@ function isItemRecord(value) {
     return id === undefined || typeof id === "string";
 }
 /** What is known about this file's commit, or `null` when it has not been attempted. */
-export function readItemRecord(fileKey) {
-    const path = itemPath(fileKey);
-    if (!existsSync(path))
+export async function readItemRecord(fileKey) {
+    const path = itemKey(fileKey);
+    const held = await host().state.read(path);
+    if (held === undefined)
         return null;
     let parsed;
     try {
-        parsed = JSON.parse(readFileSync(path, "utf8"));
+        parsed = JSON.parse(fromUtf8(held));
     }
     catch {
         // ⛔ Same reasoning as an unreadable reservation: unreadable is not absent. This file is the
         //    only local pointer to storage that is already bought and possibly already committed.
-        throw new NmtsError(`An unfinished upload record at ${path} could not be read.`, {
+        throw new NmtsError(`The unfinished upload record ${path} could not be read.`, {
             nextStep: "It names a file this account may already have paid for. Move it aside rather than " +
                 "deleting it if the upload matters, then try again.",
         });
     }
     if (!isItemRecord(parsed)) {
-        throw new NmtsError(`The unfinished upload record at ${path} is not in a shape this version knows.`, {
+        throw new NmtsError(`The unfinished upload record ${path} is not in a shape this version knows.`, {
             nextStep: "Move it aside and try again. Nothing was sent.",
         });
     }
     return parsed;
 }
 /** Write the file-level record. Called before the commit, and again once it has an id. */
-export function writeItemRecord(fileKey, record) {
-    const dir = uploadsDir();
-    mkdirSync(dir, { recursive: true, mode: 0o700 });
-    if (modesAreEnforced())
-        chmodSync(dir, 0o700);
-    atomically(itemPath(fileKey), Buffer.from(`${JSON.stringify(record, null, 2)}\n`, "utf8"));
+export async function writeItemRecord(fileKey, record) {
+    await host().state.write(itemKey(fileKey), utf8(`${JSON.stringify(record, null, 2)}\n`));
 }
 /** Forget the file-level record. Never throws, for the same reason `clearReservation` does not. */
-export function clearItemRecord(fileKey) {
+export async function clearItemRecord(fileKey) {
     try {
-        rmSync(itemPath(fileKey), { force: true });
+        await host().state.remove(itemKey(fileKey));
     }
     catch {
         // ⚠ Left where it is. A stale one carrying an item id would be resumed rather than

package/dist/upload-wallet-chain.js

@@ -21,6 +21,7 @@ import { bcs } from "@mysten/sui/bcs";
 import { SuiJsonRpcClient } from "@mysten/sui/jsonRpc";
 import { Transaction } from "@mysten/sui/transactions";
 import { blobIdFromInt, blobIdToInt, MAINNET_WALRUS_PACKAGE_CONFIG, TESTNET_WALRUS_PACKAGE_CONFIG, walrus, } from "@mysten/walrus";
+import { fromBase64Url } from "./bytes.js";
 import { NmtsError } from "./errors.js";
 import { extendReads, netGasFee, readBlobLease } from "./extend-chain.js";
 import { readOwnedStorage, readStorageType } from "./shared/lib/storage-control/chain.js";
@@ -104,8 +105,8 @@ export function certifyTransaction(client, input) {
         deletable: true,
         certificate: {
             signers: input.certificate.signers,
-            serializedMessage: new Uint8Array(Buffer.from(input.certificate.serialized_message_b64, "base64url")),
-            signature: new Uint8Array(Buffer.from(input.certificate.signature_b64, "base64url")),
+            serializedMessage: fromBase64Url(input.certificate.serialized_message_b64),
+            signature: fromBase64Url(input.certificate.signature_b64),
         },
     });
 }

package/dist/upload-wallet-put.d.ts

@@ -0,0 +1,118 @@
+import type { OnCollision } from "./collision.ts";
+import { type CryptoGlue } from "./crypto.ts";
+import type { Network } from "./network.ts";
+import type { PaddingRule } from "./shared/lib/crypto/size-padding.ts";
+import { type FileUploadStep, type PlaintextSource } from "./upload-file.ts";
+import { type StorageChoice, type UploadBudget, type WalletUploadReads } from "./upload-wallet-plan.ts";
+import type { BlobProtocol, UploadApi } from "./upload-wire.ts";
+import type { Spend } from "./wallet-grant.ts";
+import type { SignBlobCertify, SignBlobRegister } from "./wallet-sign.ts";
+/** The account this upload belongs to, and how it seals. */
+export interface WalletPutContext {
+    /** ⛔ The NMTS key. It seals the file AND derives the wallet that pays. It is never written down. */
+    code: string;
+    apiKey: string;
+    server: string;
+    network: Network;
+    accountId: string;
+    crypt: CryptoGlue;
+    /** How much of the file goes into one part. */
+    partSize: number;
+    /** The rounding rule from the account's sealed list — it changes the stored size, so the price. */
+    rule: PaddingRule;
+    /** What to do about a name already in use. Absent = the machine's setting, as `addEntry` reads it. */
+    onCollision?: OnCollision | undefined;
+    /**
+     * Which of this key's wallets pays, by index (0 = the first one).
+     *
+     * ⛔ THE CALLER RESOLVES IT, BEFORE ANYTHING IS PRICED. It is the account's own number, kept in
+     *    the sealed file list (`wallet-pay-index.ts`), and a library that guessed at it here would
+     *    price one address and sign with another.
+     */
+    wallet: number;
+}
+/** One file and where it goes — already resolved, because a library resolves nothing by asking. */
+export interface WalletPutFile {
+    source: PlaintextSource;
+    name: string;
+    parentId: string | null;
+    /** The destination AS TYPED — part of the reservation key, so both runs of a resume agree. */
+    destination: string;
+}
+/** The chain, the signatures, the wire and the four things a caller may be told. */
+export interface WalletPutSeams {
+    /** How many of the storage network's epochs to buy. Default `DEFAULT_UPLOAD_EPOCHS`. */
+    epochs?: string | number | undefined;
+    /** `fit`, `whole`, or a held resource's object id. Absent = buy new storage. */
+    storage?: string | undefined;
+    /** Stop at the review. Nothing is sealed, signed or sent, and no signer is even loaded. */
+    dryRun?: boolean | undefined;
+    /** ⚠ A SEAM, NOT AN OPTION — what the chain is asked. */
+    readChain?: ((network: Network, relayUrl: string) => WalletUploadReads | Promise<WalletUploadReads>) | undefined;
+    /** ⛔ SEPARATE FROM THE READS so a caller can prove the review stops before this. */
+    sign?: {
+        register: SignBlobRegister;
+        certify: SignBlobCertify;
+    } | undefined;
+    /** ⚠ SEAMS, NOT OPTIONS — the storage-network protocol and the server calls. */
+    protocol?: ((network: Network, bodyBytes: number, onSent: (sent: number, total: number) => void) => BlobProtocol & {
+        relayUrl: string;
+    }) | undefined;
+    api?: UploadApi | undefined;
+    /** Told as sealed bytes leave for the relay. */
+    onProgress?: ((sent: number, total: number) => void) | undefined;
+    /** Told about each step as it starts. */
+    onStep?: ((step: FileUploadStep) => void) | undefined;
+    /** Told the numbers the moment they are known — before the dry run returns and before a refusal. */
+    onReview?: ((review: WalletPutReview) => void) | undefined;
+    /** ⛔ THE GATE. Throwing here stops the upload with nothing signed. See the module header. */
+    agree?: ((review: WalletPutReview) => void) | undefined;
+    /** Told what left the wallet, after each signature. */
+    onSpend?: ((spend: Spend) => void) | undefined;
+}
+/** What this upload would buy, in the order somebody deciding needs it. Base units throughout. */
+export interface WalletPutReview {
+    name: string;
+    /** Plaintext bytes. */
+    bytes: number;
+    /** Bytes the storage network holds, padding and sealing included. */
+    sealedBytes: number;
+    parts: number;
+    epochs: number;
+    /** The term in days, read from the network's own clock. */
+    days: string;
+    /** The epoch the storage runs to. */
+    endEpoch: number;
+    /** The relay's tip over every part, in MIST. Paid inside the register signatures. */
+    tipMist: bigint;
+    /** Where the storage comes from. */
+    storage: StorageChoice;
+    /** Free storage resources the wallet holds when none was asked for; null when unreadable. */
+    heldResources: number | null;
+    /** The wallet against the price: what is needed, what is held, and the shortfall if there is one. */
+    budget: UploadBudget;
+}
+/** A dry run's answer, or a finished upload's. The review is in both, so both report one price. */
+export type WalletPutOutcome = {
+    kind: "review";
+    review: WalletPutReview;
+} | {
+    kind: "uploaded";
+    review: WalletPutReview;
+    itemId: string;
+    /** The name it got — numbered if the one asked for was taken. */
+    savedAs: string;
+    /** The id of the file this one displaced into the trash, when the machine overwrites. */
+    replaced: string | null;
+    /** The file-list version this write produced. */
+    fileListVersion: number;
+    /** True when every part was already signed for by an earlier run: this call spent nothing. */
+    resumed: boolean;
+};
+/**
+ * Price, agree, sign, upload and record ONE file, paid from the wallet the NMTS key derives.
+ *
+ * ⛔ THE SIGNING MODULE IS LOADED ONLY AFTER `agree` HAS RETURNED. A dry run and a refusal never
+ *    bring the code that can spend into memory.
+ */
+export declare function walletPut(ctx: WalletPutContext, file: WalletPutFile, seams?: WalletPutSeams): Promise<WalletPutOutcome>;