@zktx.io/sui-mcp 0.5.0 → 0.6.0

package/dist/core/session/cardSessionStore.js

@@ -8,6 +8,9 @@ import { assertNoForbiddenMcpFields } from "../action/forbiddenFields.js";
 import { cardSnapshotSchema } from "./cardSession.js";
 import { WorkflowConflict } from "./sqliteWalletWorkflowStore.js";
 import { parseWorkflowAction } from "./workflowView.js";
+import { randomUUID } from "node:crypto";
+import { settingsActionSchema, isSettingsDownloadFileAction, SettingsConflict } from "./settingsOperation.js";
+import { settingsInputError } from "./settingsInputError.js";
 export class CardError extends Error {
 }
 export class CardStore {
@@ -27,6 +30,8 @@ export class CardStore {
     async create(kind, input, execute = false) {
         this.assertCurrent();
         const business = kind === "connect" || kind === "review";
+        if (kind === "settings" && (!this.options.settings || execute || Object.keys(input).length))
+            throw new CardError("Settings cards are unavailable for this input.");
         if (business && (!this.options.workflow || execute))
             throw new CardError("This type of card is unavailable.");
         const parsed = execute ? parseCardInput(kind, input) : undefined;
@@ -49,13 +54,17 @@ export class CardStore {
         assertNoForbiddenMcpFields({ input, preparation });
         const { base, token } = createLocalSessionBase(this.now(), DEFAULT_SESSION_TTL_MS);
         const record = { ownerId: this.options.ownerId, tokenHash: base.tokenHash,
-            scope: kind === "connect" ? "connect" : kind === "review" ? input.mode === "manage" ? "review_manage" : "review" : "read",
+            scope: kind === "settings" ? "settings" : kind === "connect" ? "connect" : kind === "review" ? input.mode === "manage" ? "review_manage" : "review" : "read",
+            ...(kind === "settings" ? { operationId: randomUUID() } : {}),
             ...(kind === "review" && input.mode === "manage" && typeof input.attemptId === "string" ? { operationId: input.attemptId } : {}),
             state: { cardId: base.id, kind, state: preparation.status === "failed" ? "closed" : "ready", revision: 0,
                 createdAt: base.createdAt, expiresAt: base.expiresAt, input,
                 ...(preparation.status === "failed" ? { reason: "failed", error: preparation.error } :
                     preparation.data === undefined ? {} : { data: preparation.data }) } };
-        this.options.records.create(record);
+        if (kind === "settings")
+            this.options.settings.create(record);
+        else
+            this.options.records.create(record);
         if (preparation.status === "failed")
             this.reportFailure(record, "input_preparation");
         const result = parsed === undefined ? await this.describe(record, false) : await this.submit({
@@ -64,8 +73,24 @@ export class CardStore {
         return { ...result, permission: token };
     }
     async read(input) { return this.describe(this.require(input), true); }
+    async readSettingsFile(input, limit) {
+        const record = this.require(input);
+        if (record.state.kind !== "settings" || !this.options.settings)
+            throw new CardError("This card does not provide a backup file.");
+        if (record.operationId !== input.operationId)
+            throw new CardError("This backup does not match the Settings operation.");
+        return this.options.settings.readFile(record, input.fileId, input.offset, limit, input.attemptId);
+    }
     async readSaved(cardId) { return (await this.describe(this.current(cardId), false)).snapshot; }
     async describe(record, uiObservation) {
+        if (record.state.kind === "settings") {
+            if (!this.options.settings)
+                throw new CardError("Settings cards are unavailable.");
+            const described = await this.options.settings.describe(record);
+            return { snapshot: cardSnapshotSchema.parse({ ...described.record.state, data: described.data,
+                    inputRemainingMs: described.record.state.state === "ready" ? Math.max(0, Date.parse(described.record.state.expiresAt) - this.now().getTime()) : 0,
+                    pollAfterMs: EXECUTION_POLLING_INTERVAL_SECONDS * 1000 }) };
+        }
         if (record.state.kind !== "connect" && record.state.kind !== "review")
             return this.response(record);
         if (!this.options.workflow)
@@ -83,6 +108,31 @@ export class CardStore {
     }
     async act(input) {
         const record = this.require(input);
+        if (record.state.kind === "settings") {
+            if (!this.options.settings)
+                throw new CardError("Settings cards are unavailable.");
+            const parsed = settingsActionSchema.safeParse(input.input);
+            if (!parsed.success)
+                return { ...await this.describe(record, false), error: { code: "invalid_card_input", message: "This Settings action is not valid." } };
+            if ((parsed.data.action === "settings_confirm" || parsed.data.action === "settings_download_backup") && record.acceptedInput !== undefined && isDeepStrictEqual(record.acceptedInput, parsed.data))
+                return this.describe(record, false);
+            if (input.revision !== record.state.revision && !isSettingsDownloadFileAction(parsed.data))
+                return { ...await this.describe(record, false), error: { code: "card_conflict", message: "This Settings selection changed. Review the current selection before continuing." } };
+            const kind = parsed.data.action === "settings_select" ? parsed.data.draft.kind : this.options.settings.operationKind(record);
+            try {
+                await this.options.settings.act(record, parsed.data);
+            }
+            catch (error) {
+                const invalid = settingsInputError(error, kind);
+                if (!(error instanceof SettingsConflict) && invalid === undefined)
+                    throw error;
+                return { ...await this.describe(this.current(input.cardId), false), error: {
+                        code: invalid === undefined ? "card_conflict" : "invalid_card_input",
+                        message: invalid?.message ?? error.message
+                    } };
+            }
+            return this.describe(this.current(input.cardId), false);
+        }
         if ((record.state.kind !== "connect" && record.state.kind !== "review") || !this.options.workflow) {
             return this.conflict(record, "This card does not accept wallet workflow actions.");
         }
@@ -112,7 +162,7 @@ export class CardStore {
     }
     async submit(input) {
         const record = this.require(input);
-        if (record.state.kind === "connect" || record.state.kind === "review")
+        if (record.state.kind === "connect" || record.state.kind === "review" || record.state.kind === "settings")
             throw new CardError("This card does not accept data selections.");
         let parsed;
         try {

package/dist/core/session/sessionStore.js

@@ -16,7 +16,6 @@ import { isFinalSessionStatus } from "./status.js";
 import { parseSuiAddress } from "../suiAddress.js";
 import { cloneLocalSession, createLocalSessionBase, DEFAULT_SESSION_TTL_MS, isLocalSessionExpired, tokenMatchesHash } from "./localSession.js";
 import { SessionStoreError } from "./sessionErrors.js";
-import { SettingsSessionManager } from "./settingsSessions.js";
 const PRIVATE_DERIVED_REVIEW_FIELD_BINDINGS = [
     {
         field: "humanReadableReview",
@@ -51,7 +50,6 @@ export class LocalSessionStore {
     sessions;
     privateReviewArtifacts;
     ownerId;
-    settings;
     ttlMs;
     clock;
     eventLog;
@@ -65,11 +63,6 @@ export class LocalSessionStore {
         this.privateReviewArtifacts = options.artifacts;
         this.ttlMs = options.ttlMs ?? DEFAULT_SESSION_TTL_MS;
         this.ownerId = options.ownerId ?? randomUUID();
-        this.settings = new SettingsSessionManager({
-            ttlMs: this.ttlMs,
-            appendEventLog: (record) => this.appendEventLog(record),
-            ...(options.settingsStore ? { recordStore: options.settingsStore } : {})
-        });
         this.eventLog = options.eventLog ?? new NullEventLogSink();
         this.activityStore = options.activityStore;
         this.transactionMaterialStore = options.transactionMaterialStore;
@@ -327,15 +320,6 @@ export class LocalSessionStore {
         }
         return session;
     }
-    async createSettingsSession(now = new Date()) {
-        return this.settings.create(now);
-    }
-    async getSettingsSession(id, now = new Date()) {
-        return this.settings.get(id, now);
-    }
-    async validateSettingsToken(id, token, now = new Date()) {
-        return this.settings.validateToken(id, token, now);
-    }
     async prepareReviewedTransaction(id, planId, account, now = this.clock()) {
         const candidate = await this.inspectReview(id, now);
         if (!candidate)
@@ -360,7 +344,6 @@ export class LocalSessionStore {
             this.deleteReviewSessionTransactionMaterials(id);
         }
         this.sessions.clear();
-        this.settings.clear();
         await this.appendEventLog({
             type: "local_sessions.invalidated",
             sessionId: "all",

package/dist/core/session/settingsFileIdentity.js

@@ -0,0 +1,11 @@
+// Both the filesystem and replacement/cleanup journal use this exact private
+// namespace. A display name or an export role alone is never a download path.
+export function settingsDownloadPath(fileId) {
+    return `.settings-staging/${fileId}.download`;
+}
+export function settingsBackupPath(operationId) { return `backups/${operationId}.json`; }
+export function isSettingsDownloadFile(file) {
+    return file.role === "export" && file.relativePath === settingsDownloadPath(file.fileId);
+}
+export const SETTINGS_DOWNLOAD_FILE_SQL = "(role='export' AND relative_path=('.settings-staging/' || file_id || '.download'))";
+export const SETTINGS_FILE_CLEANUP_SQL = `(invalidated=1 OR (role='export' AND NOT ${SETTINGS_DOWNLOAD_FILE_SQL}))`;

package/dist/core/session/settingsFileProtocol.js

@@ -0,0 +1,25 @@
+// The existing internal card/HTTP limit applies to the complete JSON-RPC message.
+import { SETTINGS_IMPORT_MAX_SIZE } from "./settingsOperation.js";
+export const MAX_JSON_BODY_BYTES = 64 * 1024;
+export function settingsJsonSize(value) { return new TextEncoder().encode(JSON.stringify(value)).length; }
+export function settingsRawChunkBudget(envelopeWithEmptyBase64) {
+    const room = MAX_JSON_BODY_BYTES - settingsJsonSize(envelopeWithEmptyBase64);
+    return room > 0 ? 3 * Math.floor(room / 4) : 0;
+}
+// The actual request may carry additional Host metadata. Rejection happens
+// before dispatch; its independently measured room lets the same offset retry.
+export function settingsUploadMessageBudget(message) {
+    if (!message || typeof message !== "object")
+        return undefined;
+    const envelope = structuredClone(message);
+    if (envelope.method !== "tools/call" || envelope.params?.name !== "ui.act_card" ||
+        envelope.params.arguments?.input?.action !== "settings_upload_chunk")
+        return undefined;
+    // Safe-integer decimal maxima cover ids/revisions; upload offsets use the
+    // accepted raw-file limit.
+    envelope.id = Number.MAX_SAFE_INTEGER;
+    envelope.params.arguments.revision = Number.MAX_SAFE_INTEGER;
+    envelope.params.arguments.input.offset = SETTINGS_IMPORT_MAX_SIZE;
+    envelope.params.arguments.input.chunkBase64 = "";
+    return settingsRawChunkBudget(envelope);
+}

package/dist/core/session/settingsFileStore.js

@@ -0,0 +1,346 @@
+import { createHash } from "node:crypto";
+import { constants } from "node:fs";
+import { lstat, mkdir, open, link, unlink } from "node:fs/promises";
+import { join } from "node:path";
+import { isSettingsDownloadFile, settingsBackupPath } from "./settingsFileIdentity.js";
+import { SettingsConflict } from "./settingsOperation.js";
+export class SettingsDownloadPathExists extends SettingsConflict {
+}
+function fileCode(error, code) {
+    return !!error && typeof error === "object" && "code" in error && error.code === code;
+}
+export function settingsFileDigest(data) { return createHash("sha256").update(data).digest("hex"); }
+export function decodeSettingsChunk(value) {
+    if (!/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(value)) {
+        throw new SettingsConflict("Part of the file was not encoded correctly.");
+    }
+    const data = Buffer.from(value, "base64");
+    if (data.toString("base64") !== value)
+        throw new SettingsConflict("Part of the file was not encoded correctly.");
+    return data;
+}
+/** Private files are named from backend-generated identities only. SQLite owns
+ * reservations and progress; this class verifies the corresponding physical fact. */
+export class SettingsFileStore {
+    dataDirectory;
+    constructor(dataDirectory) {
+        this.dataDirectory = dataDirectory;
+    }
+    directory(role) {
+        return join(this.dataDirectory, role === "staging" ? ".settings-staging" : "backups");
+    }
+    assertId(id) {
+        if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(id)) {
+            throw new SettingsConflict("The selected file could not be identified.");
+        }
+    }
+    async prepareDirectory(role) {
+        const directory = this.directory(role);
+        await mkdir(directory, { mode: 0o700, recursive: true });
+        const info = await lstat(directory);
+        if (!info.isDirectory() || info.isSymbolicLink())
+            throw new SettingsConflict("The local file directory is unavailable.");
+        return directory;
+    }
+    stagingPath(file) {
+        this.assertId(file.fileId);
+        return join(this.directory("staging"), `${file.fileId}.${file.role === "upload" ? "upload" : isSettingsDownloadFile(file) ? "download" : "stage"}`);
+    }
+    finalPath(file) {
+        this.assertId(file.operationId);
+        if (file.role !== "export" || file.relativePath !== `backups/${file.operationId}.json`) {
+            throw new SettingsConflict("The backup location does not match this request.");
+        }
+        return join(this.directory("backups"), `${file.operationId}.json`);
+    }
+    exportPath(file) { return this.finalPath(file); }
+    localBackupPath(file) {
+        this.assertId(file.operationId);
+        if (!isSettingsDownloadFile(file))
+            throw new SettingsConflict("This request does not own a download snapshot.");
+        return join(this.dataDirectory, settingsBackupPath(file.operationId));
+    }
+    async verifiedIdentity(handle, path, file) {
+        const before = await handle.stat({ bigint: true });
+        if (!before.isFile() || before.size !== BigInt(file.totalSize))
+            throw new SettingsConflict("The backup file size changed.");
+        const hash = createHash("sha256");
+        for await (const chunk of handle.createReadStream({ start: 0, autoClose: false }))
+            hash.update(chunk);
+        const after = await handle.stat({ bigint: true }), atPath = await lstat(path, { bigint: true });
+        if (!atPath.isFile() || atPath.isSymbolicLink() || before.dev !== after.dev || before.ino !== after.ino ||
+            after.dev !== atPath.dev || after.ino !== atPath.ino || after.size !== before.size || atPath.size !== before.size ||
+            hash.digest("hex") !== file.sha256)
+            throw new SettingsConflict("The backup file changed while it was checked.");
+        return { device: before.dev.toString(), inode: before.ino.toString() };
+    }
+    sameFile(left, right) {
+        return left.device === right.device && left.inode === right.inode;
+    }
+    async downloadSourceIdentity(file) {
+        const directory = await lstat(this.directory("staging"));
+        if (!directory.isDirectory() || directory.isSymbolicLink())
+            throw new SettingsConflict("The backup staging directory changed.");
+        const path = this.stagingPath(file), handle = await this.handle(path, constants.O_RDONLY);
+        try {
+            return await this.verifiedIdentity(handle, path, file);
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    async publishDownload(file, rememberSource) {
+        if (!isSettingsDownloadFile(file) || !file.sealed || file.invalidated)
+            throw new SettingsConflict("The snapshot is not ready to save.");
+        await this.prepareDirectory("backups");
+        const source = this.stagingPath(file), destination = this.localBackupPath(file);
+        // Persist the verified source identity before the only effect. Recovery
+        // verifies this same inode; it never creates a missing destination.
+        const identity = await this.downloadSourceIdentity(file);
+        rememberSource(identity);
+        try {
+            await link(source, destination);
+        }
+        catch (error) {
+            if (fileCode(error, "EEXIST"))
+                return { status: "failed", reason: "target_conflict" };
+            throw error;
+        }
+        return this.inspectDownloadPublication(file, identity);
+    }
+    async inspectDownloadPublication(file, sourceIdentity) {
+        if (!isSettingsDownloadFile(file))
+            throw new SettingsConflict("The selected file is not a download snapshot.");
+        const path = this.localBackupPath(file);
+        let target;
+        try {
+            const directory = await lstat(this.directory("backups"));
+            if (!directory.isDirectory() || directory.isSymbolicLink())
+                return { status: "failed", reason: "target_conflict" };
+            target = await this.handle(path, constants.O_RDONLY);
+        }
+        catch (error) {
+            if (fileCode(error, "ENOENT")) {
+                try {
+                    await this.downloadSourceIdentity(file);
+                    return { status: "failed", reason: "not_published" };
+                }
+                catch (sourceError) {
+                    if (sourceError instanceof SettingsConflict || fileCode(sourceError, "ENOENT") || fileCode(sourceError, "ELOOP"))
+                        return { status: "failed", reason: "source_unavailable" };
+                    throw sourceError;
+                }
+            }
+            if (error instanceof SettingsConflict || fileCode(error, "ELOOP"))
+                return { status: "failed", reason: "target_conflict" };
+            throw error; // Unreadable is not absent; keep the admitted save unsettled.
+        }
+        try {
+            if (!sourceIdentity)
+                return { status: "failed", reason: "target_conflict" };
+            const actualTarget = await this.verifiedIdentity(target, path, file);
+            if (!this.sameFile(sourceIdentity, actualTarget))
+                return { status: "failed", reason: "target_conflict" };
+            const actualSource = await this.downloadSourceIdentity(file);
+            return this.sameFile(sourceIdentity, actualSource) ? { status: "saved" } : { status: "failed", reason: "source_unavailable" };
+        }
+        catch (error) {
+            if (error instanceof SettingsConflict || fileCode(error, "ENOENT") || fileCode(error, "ELOOP"))
+                return { status: "failed", reason: "source_unavailable" };
+            throw error;
+        }
+        finally {
+            await target.close();
+        }
+    }
+    async handle(path, flags) {
+        const file = await open(path, flags | constants.O_NOFOLLOW, 0o600);
+        try {
+            if (!(await file.stat()).isFile())
+                throw new SettingsConflict("The selected item is not a file that Sui MCP can read.");
+            return file;
+        }
+        catch (error) {
+            await file.close();
+            throw error;
+        }
+    }
+    async createUpload(file) {
+        if (file.role !== "upload" || file.invalidated || file.receivedSize !== 0 ||
+            file.relativePath !== `.settings-staging/${file.fileId}.upload`)
+            throw new SettingsConflict("This file transfer is no longer available. Choose the backup file again.");
+        await this.prepareDirectory("staging");
+        const handle = await this.handle(this.stagingPath(file), constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL);
+        try {
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    async writeReservedChunk(file, data) {
+        const reservation = file.reservation;
+        if (file.role !== "upload" || file.invalidated || file.sealed || !reservation || reservation.offset !== file.receivedSize ||
+            reservation.length !== data.length || reservation.sha256 !== settingsFileDigest(data) ||
+            reservation.offset + data.length > file.totalSize)
+            throw new SettingsConflict("The next part of the file does not match the expected content.");
+        await this.prepareDirectory("staging");
+        const handle = await this.handle(this.stagingPath(file), constants.O_RDWR);
+        try {
+            const length = (await handle.stat()).size;
+            if (length < reservation.offset || length > reservation.offset + data.length)
+                throw new SettingsConflict("The file size changed during transfer.");
+            // A crash may leave the beginning of this exact reserved chunk. Verify it
+            // before completing the remainder; never overwrite a different prefix.
+            const written = length - reservation.offset;
+            const prefix = Buffer.alloc(written);
+            const read = await handle.read(prefix, 0, written, reservation.offset);
+            if (read.bytesRead !== written || !prefix.equals(data.subarray(0, written)))
+                throw new SettingsConflict("The part of the file already received has changed.");
+            let offset = written;
+            while (offset < data.length) {
+                const result = await handle.write(data, offset, data.length - offset, reservation.offset + offset);
+                if (!result.bytesWritten)
+                    throw new Error("Sui MCP could not save the next part of the file.");
+                offset += result.bytesWritten;
+            }
+            await handle.sync();
+            const actual = Buffer.alloc(data.length);
+            const verified = await handle.read(actual, 0, data.length, reservation.offset);
+            if (verified.bytesRead !== data.length || !actual.equals(data))
+                throw new SettingsConflict("The received part of the file could not be checked.");
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    async readUpload(file) {
+        if (file.role !== "upload" || file.invalidated || file.receivedSize !== file.totalSize || file.reservation) {
+            throw new SettingsConflict("The complete file has not been received yet.");
+        }
+        await this.prepareDirectory("staging");
+        const handle = await this.handle(this.stagingPath(file), constants.O_RDONLY);
+        try {
+            if ((await handle.stat()).size !== file.totalSize)
+                throw new SettingsConflict("The received file size has changed.");
+            const data = Buffer.alloc(file.totalSize);
+            const actual = await handle.read(data, 0, data.length, 0);
+            if (actual.bytesRead !== data.length || settingsFileDigest(data) !== file.sha256)
+                throw new SettingsConflict("The received file has changed or is incomplete.");
+            return data;
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    async verifyUploadPrefix(file, offset, data) {
+        if (file.role !== "upload" || file.invalidated || offset < 0 || offset + data.length > file.receivedSize) {
+            throw new SettingsConflict("This part of the file has not been received.");
+        }
+        await this.prepareDirectory("staging");
+        const handle = await this.handle(this.stagingPath(file), constants.O_RDONLY);
+        try {
+            const actual = Buffer.alloc(data.length), read = await handle.read(actual, 0, data.length, offset);
+            if (read.bytesRead !== data.length || !actual.equals(data))
+                throw new SettingsConflict("Different file content was already received at this position.");
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    async createDownload(file, data) {
+        if (!isSettingsDownloadFile(file) || file.invalidated || data.length !== file.totalSize || settingsFileDigest(data) !== file.sha256) {
+            throw new SettingsConflict("The download snapshot does not match the selected records.");
+        }
+        await this.prepareDirectory("staging");
+        let handle;
+        try {
+            handle = await this.handle(this.stagingPath(file), constants.O_RDWR | constants.O_CREAT | constants.O_EXCL);
+        }
+        catch (error) {
+            if (error && typeof error === "object" && "code" in error && error.code === "EEXIST") {
+                throw new SettingsDownloadPathExists("The reserved backup location already contains a file.");
+            }
+            throw error;
+        }
+        try {
+            await handle.writeFile(data);
+            await handle.sync();
+            if ((await handle.stat()).size !== file.totalSize)
+                throw new SettingsConflict("The download snapshot length changed.");
+            const hash = createHash("sha256");
+            for await (const chunk of handle.createReadStream({ start: 0, autoClose: false }))
+                hash.update(chunk);
+            if (hash.digest("hex") !== file.sha256)
+                throw new SettingsConflict("The download snapshot content changed.");
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    async readDownloadRange(file, offset, length) {
+        if (!isSettingsDownloadFile(file))
+            throw new SettingsConflict("This file is not the private download snapshot.");
+        return this.readVerifiedRange(file, this.directory("staging"), this.stagingPath(file), offset, length);
+    }
+    async verifyExport(file) {
+        const directory = this.directory("backups");
+        const info = await lstat(directory);
+        if (!info.isDirectory() || info.isSymbolicLink())
+            throw new SettingsConflict("The local backup directory changed.");
+        const handle = await this.handle(this.finalPath(file), constants.O_RDONLY);
+        try {
+            if ((await handle.stat()).size !== file.totalSize)
+                throw new SettingsConflict("The local backup length changed.");
+            const hash = createHash("sha256");
+            for await (const chunk of handle.createReadStream({ autoClose: false }))
+                hash.update(chunk);
+            if (hash.digest("hex") !== file.sha256)
+                throw new SettingsConflict("The local backup content changed.");
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    async readExportRange(file, offset, length) {
+        return this.readVerifiedRange(file, this.directory("backups"), this.finalPath(file), offset, length);
+    }
+    async readVerifiedRange(file, directory, path, offset, length) {
+        if (!file.sealed || file.invalidated || !Number.isSafeInteger(offset) || !Number.isSafeInteger(length) ||
+            offset < 0 || length < 1 || offset + length > file.totalSize)
+            throw new SettingsConflict("This part of the backup is unavailable.");
+        // Verify the artifact on the same open descriptor used for this chunk, so
+        // path replacement cannot substitute unchecked content between two opens.
+        const info = await lstat(directory);
+        if (!info.isDirectory() || info.isSymbolicLink())
+            throw new SettingsConflict("The local backup directory changed.");
+        const handle = await this.handle(path, constants.O_RDONLY);
+        try {
+            if ((await handle.stat()).size !== file.totalSize)
+                throw new SettingsConflict("The local backup length changed.");
+            const hash = createHash("sha256");
+            for await (const chunk of handle.createReadStream({ autoClose: false }))
+                hash.update(chunk);
+            if (hash.digest("hex") !== file.sha256)
+                throw new SettingsConflict("The local backup content changed.");
+            const data = Buffer.alloc(length), actual = await handle.read(data, 0, length, offset);
+            if (actual.bytesRead !== length)
+                throw new SettingsConflict("The local backup read was incomplete.");
+            return data;
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    async cleanup(file) {
+        await this.prepareDirectory("staging");
+        try {
+            await unlink(this.stagingPath(file));
+        }
+        catch (error) {
+            if (!(error && typeof error === "object" && "code" in error && error.code === "ENOENT"))
+                throw error;
+        }
+        // The public backup is the user's artifact and is never removed here.
+    }
+}

package/dist/core/session/settingsInputError.js

@@ -0,0 +1,34 @@
+import { SuiEndpointError } from "../suiEndpoint.js";
+import { LocalSettingsError } from "../preferences/preferencesStore.js";
+import { LocalDataError } from "../activity/localDataTypes.js";
+export const SETTINGS_REPLACEMENT_BLOCKED_MESSAGE = "A wallet or transaction response is still pending, or the initial transaction-result waiting period has not ended. Local records cannot be replaced yet.";
+// Only authenticated Settings validation reaches this mapping. Return fixed
+// explanations and recovery categories, never imported values or exceptions.
+export function settingsInputError(error, kind) {
+    if (!(error instanceof SuiEndpointError) &&
+        !(error instanceof LocalSettingsError && error.kind === "input_invalid") &&
+        !(error instanceof LocalDataError && error.kind === "input_invalid"))
+        return undefined;
+    const reason = error instanceof SuiEndpointError ? error.kind : error.details.endpointReason ?? error.details.reason;
+    const failure = (restoreReason, message) => ({ restoreReason, message });
+    if (kind === "import_local_data") {
+        if (reason === "invalid_url" || reason === "chain_identifier_mismatch")
+            return failure("invalid_backup", "A network address saved in this backup could not be verified for Sui mainnet. Choose another Sui MCP backup with valid mainnet network settings.");
+        if (reason === "endpoint_timeout" || reason === "endpoint_unreachable")
+            return failure("check_failed", "Sui MCP could not reach a network address saved in this backup. Check that the service is reachable, then check this backup again.");
+    }
+    switch (reason) {
+        case "invalid_url": return failure("invalid_backup", "The network address is not a valid URL. Correct it and select it again.");
+        case "chain_identifier_mismatch": return failure("invalid_backup", "The network check did not confirm Sui mainnet at this address. Select a Sui mainnet network address.");
+        case "endpoint_timeout": return failure("check_failed", "The service at this network address did not respond in time. Check that it is reachable, then review the change again.");
+        case "endpoint_unreachable": return failure("check_failed", "The service at this network address could not be reached. Check the address and your connection, then review the change again.");
+        case "wallet_request_unsettled": return failure("wallet_request_unsettled", SETTINGS_REPLACEMENT_BLOCKED_MESSAGE);
+        case "invalid_backup_encoding": return failure("invalid_backup", "This backup contains text that Sui MCP cannot read. Choose another backup.");
+        case "invalid_backup_json": return failure("invalid_backup", "This backup's contents are incomplete or incorrectly formatted. Choose another backup.");
+    }
+    if (error instanceof LocalDataError)
+        return failure("invalid_backup", "This file is not a supported Sui MCP backup. Choose another backup.");
+    if (error instanceof LocalSettingsError)
+        return failure("check_failed", "This network address could not be checked. Check the address, then review the change again.");
+    return undefined;
+}