@zktx.io/sui-mcp 0.5.0 → 0.6.1

package/dist/core/session/settingsFileStore.js

@@ -0,0 +1,337 @@
+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;
+}
+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);
+        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;
+        }
+        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.");
+            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.");
+        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;
+        }
+    }
+}

package/dist/core/session/settingsInputError.js

@@ -0,0 +1,32 @@
+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.";
+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;
+}

package/dist/core/session/settingsOperation.js

@@ -0,0 +1,220 @@
+import { z } from "zod";
+import { assetReadAccountSchema, walletAvailabilitySchema } from "./walletConnection.js";
+import { LOCAL_DATA_EXPORT_FORMAT } from "../activity/localDataTypes.js";
+import { suiAddressStringSchema } from "../suiAddress.js";
+export const SETTINGS_IMPORT_MAX_SIZE = 16 * 1024 * 1024;
+const identity = z.string().uuid();
+const size = z.number().int().nonnegative().safe();
+const sha256 = z.string().regex(/^[a-f0-9]{64}$/);
+export const restoreCheckSchema = z.discriminatedUnion("status", [
+    z.object({ status: z.literal("no_file") }).strict(),
+    z.object({ status: z.literal("receiving") }).strict(),
+    z.object({ status: z.literal("checking") }).strict(),
+    z.object({ status: z.literal("check_required"), message: z.string().min(1) }).strict(),
+    z.object({ status: z.literal("can_restore") }).strict(),
+    z.object({ status: z.literal("cannot_restore"), reason: z.enum([
+            "invalid_backup", "file_unavailable", "wallet_request_unsettled", "operation_busy", "input_unavailable", "check_failed"
+        ]), message: z.string().min(1) }).strict()
+]);
+export const storedRestoreCheckSchema = z.object({ fileId: identity, sha256, totalSize: size, dataEpoch: size,
+    userDataRevision: size, check: restoreCheckSchema }).strict();
+export const settingsDraftSchema = z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("set_endpoint"), endpoint: z.enum(["grpc", "graphql"]), value: z.string().min(1) }).strict(),
+    z.object({ kind: z.literal("restore_endpoint"), endpoint: z.enum(["grpc", "graphql"]) }).strict(),
+    z.object({ kind: z.enum(["clear_read_address", "export_local_data", "download_backup", "import_local_data", "reset_local_data", "restart_wallet_service"]) }).strict()
+]);
+export const settingsDownloadReportSchema = z.enum(["acknowledged", "not_completed", "unconfirmed", "unsupported"]);
+export const settingsDownloadFailureSchema = z.object({ method: z.literal("ui/download-file"), code: z.literal(-32601) }).strict();
+export const settingsDownloadEndSchema = z.enum(["acknowledged", "cancelled", "expired", "server_restarted", "data_replaced", "source_unavailable", "stored_locally", "local_save_failed"]);
+export const settingsFileIdentitySchema = z.object({ device: z.string().regex(/^\d+$/), inode: z.string().regex(/^\d+$/) }).strict();
+const localSaveFailure = z.enum(["not_published", "target_conflict", "source_unavailable", "interrupted"]);
+const storedLocalSaveSchema = z.object({ status: z.enum(["needs_consent", "saving", "saved", "failed"]),
+    attemptId: identity, fileId: identity, sha256, totalSize: size, destination: z.string(), ownerId: z.string().min(1),
+    currentSaveAttemptId: identity.optional(),
+    attempts: z.array(z.object({ saveAttemptId: identity, previousSaveAttemptId: identity.optional(),
+        admittedAt: z.string().datetime(), allowPossibleCopy: z.boolean() }).strict()),
+    sourceIdentity: settingsFileIdentitySchema.optional(), savedAt: z.string().datetime().optional(), failure: localSaveFailure.optional()
+}).strict().superRefine((value, context) => {
+    if (value.status === "needs_consent" ? value.attempts.length !== 0 || value.currentSaveAttemptId !== undefined :
+        !value.currentSaveAttemptId || !value.attempts.some((a) => a.saveAttemptId === value.currentSaveAttemptId)) {
+        context.addIssue({ code: "custom", message: "A local save must identify its admitted attempt." });
+    }
+    if (new Set(value.attempts.map((a) => a.saveAttemptId)).size !== value.attempts.length ||
+        (value.status === "saved") !== (value.savedAt !== undefined) || value.status === "saved" && !value.sourceIdentity ||
+        (value.status === "failed") !== (value.failure !== undefined)) {
+        context.addIssue({ code: "custom", message: "Local save evidence must match its state." });
+    }
+});
+export const storedSettingsDownloadSchema = z.object({
+    currentAttemptId: identity,
+    attempts: z.array(z.object({ attemptId: identity, admittedAt: z.string().datetime(), previousAttemptId: identity.optional(),
+        hostReport: settingsDownloadReportSchema.optional(), failure: settingsDownloadFailureSchema.optional() }).strict()).min(1),
+    readyAt: z.string().datetime().optional(), expiresAt: z.string().datetime().optional(), endReason: settingsDownloadEndSchema.optional(),
+    localSave: storedLocalSaveSchema.optional()
+}).strict().superRefine((value, context) => {
+    if (new Set(value.attempts.map((attempt) => attempt.attemptId)).size !== value.attempts.length ||
+        !value.attempts.some((attempt) => attempt.attemptId === value.currentAttemptId) ||
+        (value.readyAt === undefined) !== (value.expiresAt === undefined)) {
+        context.addIssue({ code: "custom", message: "Download attempts and lifetime must identify one stored snapshot." });
+    }
+    if (value.endReason === "stored_locally" && value.localSave?.status !== "saved" ||
+        value.endReason === "local_save_failed" && value.localSave?.status !== "failed" ||
+        value.attempts.some((a) => (a.hostReport === "unsupported") !== (a.failure !== undefined)) ||
+        value.localSave && (value.localSave.attemptId !== value.currentAttemptId ||
+            !value.attempts.some((a) => a.attemptId === value.currentAttemptId && a.hostReport === "unsupported") ||
+            value.localSave.status === "saving" && value.endReason !== undefined ||
+            (value.localSave.status === "saved") !== (value.endReason === "stored_locally"))) {
+        context.addIssue({ code: "custom", message: "Local saving requires the current download's unsupported report." });
+    }
+});
+export const settingsDownloadFileActionSchema = z.enum(["settings_retry_download", "settings_report_download", "settings_cancel_download", "settings_store_backup"]);
+export const settingsActionSchema = z.discriminatedUnion("action", [
+    z.object({ action: z.literal("settings_download_backup"), operationId: identity, attemptId: identity }).strict(),
+    z.object({ action: z.literal("settings_retry_download"), operationId: identity, fileId: identity,
+        previousAttemptId: identity, attemptId: identity }).strict(),
+    z.object({ action: z.literal("settings_report_download"), operationId: identity, fileId: identity,
+        attemptId: identity, status: settingsDownloadReportSchema, failure: settingsDownloadFailureSchema.optional() }).strict().refine((value) => (value.status === "unsupported") === (value.failure !== undefined), "Only unsupported downloads require the exact method failure."),
+    z.object({ action: z.literal("settings_store_backup"), operationId: identity, fileId: identity, attemptId: identity,
+        saveAttemptId: identity, previousSaveAttemptId: identity.optional(), allowPossibleCopy: z.boolean() }).strict(),
+    z.object({ action: z.literal("settings_cancel_download"), operationId: identity, fileId: identity, attemptId: identity }).strict(),
+    z.object({ action: z.literal("settings_select"), draft: settingsDraftSchema }).strict(),
+    z.object({ action: z.literal("settings_prepare"), operationId: identity }).strict(),
+    z.object({ action: z.literal("settings_begin_upload"), operationId: identity,
+        name: z.string().min(1), totalSize: size.max(SETTINGS_IMPORT_MAX_SIZE), sha256 }).strict(),
+    z.object({ action: z.literal("settings_upload_chunk"), operationId: identity, fileId: identity,
+        offset: size.max(SETTINGS_IMPORT_MAX_SIZE), chunkBase64: z.string() }).strict(),
+    z.object({ action: z.literal("settings_seal_upload"), operationId: identity, fileId: identity }).strict(),
+    z.object({ action: z.literal("settings_confirm"), operationId: identity, preparationId: identity }).strict(),
+    z.object({ action: z.literal("settings_back"), operationId: identity }).strict(),
+    z.object({ action: z.literal("settings_cancel") }).strict()
+]);
+export function retainedBackupRejection(operation, file) {
+    const saved = storedRestoreCheckSchema.safeParse(operation.preparation?.restoreCheck);
+    if (operation.draft?.kind !== "import_local_data" || !file || operation.fileId !== file.fileId ||
+        file.operationId !== operation.operationId || file.role !== "upload" || file.invalidated || !file.sealed ||
+        file.receivedSize !== file.totalSize || file.reservation || !saved.success ||
+        saved.data.fileId !== file.fileId || saved.data.sha256 !== file.sha256 || saved.data.totalSize !== file.totalSize ||
+        saved.data.dataEpoch !== operation.dataEpoch || saved.data.check.status !== "cannot_restore" ||
+        saved.data.check.reason !== "invalid_backup")
+        return undefined;
+    return saved.data;
+}
+export function permitsBackupRecheck(check) {
+    return check.status === "check_required" || check.status === "cannot_restore" &&
+        ["wallet_request_unsettled", "operation_busy", "check_failed"].includes(check.reason);
+}
+export class SettingsConflict extends Error {
+}
+export const settingsResultSchema = z.object({
+    outcome: z.enum(["completed", "failed", "interrupted", "superseded"]), recordedAt: z.string().datetime(),
+    message: z.string().min(1), details: z.record(z.string(), z.unknown()).optional(), completionScope: z.literal("backup_snapshot").optional()
+}).strict();
+const endpointView = z.object({ storedValue: z.string(), effectiveValue: z.string(),
+    source: z.enum(["environment", "local_db", "builtin_default"]), pendingStoredValue: z.string().optional(),
+    appliesAfter: z.literal("mcp_server_restart").optional() }).strict();
+export const endpointPreparationSchema = z.object({ endpoint: z.enum(["grpc", "graphql"]),
+    key: z.enum(["suiGrpcUrl", "suiGraphqlUrl"]), value: z.string().min(1), status: z.enum(["saved", "reset"]),
+    storedValue: z.string(), effectiveValue: z.string(), source: endpointView.shape.source }).strict().refine((target) => target.key === (target.endpoint === "grpc" ? "suiGrpcUrl" : "suiGraphqlUrl"), "The endpoint kind and preference key must agree.");
+const count = z.number().int().nonnegative().safe();
+const localDataCounts = z.object({ accounts: count, reviewSessions: count, reviewStateSnapshots: count, reviewStatusTransitions: count,
+    reviewExecutions: count, reviewRequests: count, outcomeUnknownRequests: count, externalActivityScans: count,
+    externalActivityTransactions: count, localSettings: count }).strict();
+const importPreview = z.object({ status: z.literal("valid"), format: z.literal(LOCAL_DATA_EXPORT_FORMAT), network: z.literal("mainnet"),
+    exportedAt: z.string().datetime(), currentCounts: localDataCounts, incomingCounts: localDataCounts, willReplace: z.literal(true),
+    activeAccountChange: z.enum(["unchanged", "set", "cleared"]), currentReadAddress: suiAddressStringSchema.nullable(),
+    incomingReadAddress: suiAddressStringSchema.nullable(), restartRequiredAfterImport: z.boolean() }).strict();
+export const settingsViewSchema = z.object({
+    kind: z.literal("settings"), operationId: identity,
+    phase: z.enum(["draft", "uploading", "sealed", "prepared", "executing", "stopping", "starting", "terminal"]),
+    draft: settingsDraftSchema.optional(), preparationId: identity.optional(), preparation: z.record(z.string(), z.unknown()).optional(),
+    file: z.object({ fileId: identity, displayName: z.string(), totalSize: size, receivedSize: size, sha256,
+        sealed: z.boolean(), cleanup: z.enum(["pending", "complete", "failed"]) }).strict().optional(),
+    download: z.object({ availability: z.enum(["preparing", "available", "ended"]), currentAttemptId: identity,
+        hostReport: settingsDownloadReportSchema.optional(), previousUnconfirmed: z.boolean(),
+        endReason: settingsDownloadEndSchema.optional(), expiresAt: z.string().datetime().optional(), remainingMs: size.optional(),
+        localSave: z.object({ status: z.enum(["needs_consent", "saving", "saved", "failed"]), currentSaveAttemptId: identity.optional(),
+            failure: localSaveFailure.optional(), savedAt: z.string().datetime().optional() }).strict().optional(),
+        allowedFileActions: z.array(settingsDownloadFileActionSchema) }).strict().optional(),
+    restoreCheck: restoreCheckSchema.optional(),
+    backupLocation: z.object({ directory: z.string().min(1), filename: z.string().min(1) }).strict().optional(),
+    result: settingsResultSchema.optional(),
+    temporaryFileCleanup: z.enum(["pending", "complete", "failed"]).optional(),
+    priorRunId: identity.optional(), nextRunId: identity.optional(), supersedesOperationId: identity.optional(), supersededByOperationId: identity.optional(),
+    allowedActions: z.array(z.enum(settingsActionSchema.options.map((option) => option.shape.action.value))), observe: z.boolean(),
+    facts: z.object({ server: z.object({ name: z.string(), version: z.string(), network: z.literal("mainnet") }).strict(),
+        localSettings: z.object({ suiGrpcUrl: endpointView, suiGraphqlUrl: endpointView }).strict(), readAddress: z.string().optional(),
+        assetReadAccount: assetReadAccountSchema, walletAvailability: walletAvailabilitySchema,
+        connectionReconciliationRequired: z.literal(true).optional(), observedAt: z.string().datetime().optional(),
+        counts: localDataCounts }).strict().optional()
+}).strict().superRefine((value, context) => {
+    if (value.download && (value.draft?.kind !== "download_backup" || !value.file ||
+        value.download.availability === "available" && (!value.file.sealed || !value.result || value.download.endReason || !value.download.expiresAt) ||
+        value.download.availability === "ended" && !value.download.endReason)) {
+        context.addIssue({ code: "custom", message: "Download delivery must describe its own snapshot and lifetime." });
+    }
+    if (value.draft?.kind === "download_backup" && value.preparation !== undefined) {
+        context.addIssue({ code: "custom", message: "Private download preparation is not public preparation data." });
+    }
+    if (value.restoreCheck && (value.draft?.kind !== "import_local_data" || value.result)) {
+        context.addIssue({ code: "custom", message: "Restore checks belong to an uncompleted import preparation." });
+    }
+    if (value.restoreCheck?.status === "can_restore" && (value.phase !== "prepared" || !value.file?.sealed || !value.allowedActions.includes("settings_confirm"))) {
+        context.addIssue({ code: "custom", message: "Restore availability requires a sealed file and current confirmation." });
+    }
+    if (value.draft?.kind === "import_local_data" && value.restoreCheck?.status !== "can_restore" && value.allowedActions.includes("settings_confirm")) {
+        context.addIssue({ code: "custom", message: "An unchecked or blocked import cannot offer confirmation." });
+    }
+    if (value.restoreCheck?.status === "receiving" && (!value.file || value.file.sealed || !["draft", "uploading"].includes(value.phase))) {
+        context.addIssue({ code: "custom", message: "Receiving requires the selected unsealed upload." });
+    }
+    if (value.restoreCheck?.status === "check_required" && (!value.file?.sealed || value.phase !== "sealed")) {
+        context.addIssue({ code: "custom", message: "A new check requires the same complete sealed upload." });
+    }
+    if (value.restoreCheck?.status === "cannot_restore" && value.restoreCheck.reason === "invalid_backup" &&
+        (value.phase === "prepared" || value.allowedActions.includes("settings_prepare"))) {
+        context.addIssue({ code: "custom", message: "A rejected backup requires an explicit new selection." });
+    }
+    if (value.backupLocation && !(value.result?.outcome === "completed" && (value.draft?.kind === "export_local_data" ||
+        value.draft?.kind === "download_backup" && value.download?.localSave?.status === "saved" && value.download.endReason === "stored_locally"))) {
+        context.addIssue({ code: "custom", message: "A backup location requires its recorded successful export." });
+    }
+    if (value.download?.localSave?.status === "saved" && !value.backupLocation) {
+        context.addIssue({ code: "custom", message: "A saved backup must identify its verified location." });
+    }
+    if (value.draft?.kind === "export_local_data" && value.result?.outcome === "completed" &&
+        typeof value.result.details?.path === "string" && !value.backupLocation) {
+        context.addIssue({ code: "custom", message: "A recorded backup path must provide its folder and file name." });
+    }
+    if (value.temporaryFileCleanup && !value.result)
+        context.addIssue({ code: "custom", message: "Cleanup of an applied or ended operation requires its recorded result." });
+    if ((value.phase === "terminal") !== (value.result !== undefined) || value.phase === "terminal" && (value.observe || value.allowedActions.length)) {
+        context.addIssue({ code: "custom", message: "A terminal Settings result cannot grant input or observation." });
+    }
+    if (value.phase === "prepared" && (!value.preparationId || !value.draft || !value.preparation))
+        context.addIssue({ code: "custom", message: "Settings confirmation requires a prepared identity and facts." });
+    if (value.phase === "prepared" && value.draft?.kind === "import_local_data" && !importPreview.safeParse(value.preparation?.preview).success) {
+        context.addIssue({ code: "custom", path: ["preparation", "preview"], message: "Import confirmation requires the validated current and incoming read context and record counts." });
+    }
+    if (value.phase === "prepared" && (value.draft?.kind === "set_endpoint" || value.draft?.kind === "restore_endpoint")) {
+        const target = endpointPreparationSchema.safeParse(value.preparation?.endpoint);
+        if (!target.success || target.data.endpoint !== value.draft.endpoint ||
+            target.data.status !== (value.draft.kind === "set_endpoint" ? "saved" : "reset") ||
+            value.draft.kind === "set_endpoint" && target.data.value !== value.draft.value) {
+            context.addIssue({ code: "custom", path: ["preparation", "endpoint"], message: "Endpoint confirmation must name its exact prepared target." });
+        }
+    }
+    if (value.file && value.file.receivedSize > value.file.totalSize)
+        context.addIssue({ code: "custom", message: "Received content exceeds the selected file." });
+});
+export function settingsDownload(operation) {
+    if (operation.draft?.kind !== "download_backup")
+        return undefined;
+    const download = storedSettingsDownloadSchema.parse(operation.preparation?.download), save = download.localSave;
+    if (save && (save.fileId !== operation.fileId || save.destination !== `backups/${operation.operationId}.json`)) {
+        throw new SettingsConflict("The local save does not identify this request's backup.");
+    }
+    return download;
+}
+export function isSettingsDownloadFileAction(action) {
+    return settingsDownloadFileActionSchema.safeParse(action.action).success;
+}

package/dist/core/session/settingsPreparationSql.js

@@ -0,0 +1,13 @@
+export const SETTINGS_REUSABLE_UPLOAD_SQL = `
+  kind='import_local_data' AND EXISTS (
+    SELECT 1 FROM settings_files f
+    WHERE f.file_id=settings_operations.file_id
+      AND f.operation_id=settings_operations.operation_id AND f.role='upload'
+      AND f.sealed=1 AND f.invalidated=0 AND f.received_size=f.total_size
+      AND f.reservation_json IS NULL
+  )`;
+export const SETTINGS_RESET_PREPARATION_SQL = `
+  UPDATE settings_operations SET
+    phase=CASE WHEN ${SETTINGS_REUSABLE_UPLOAD_SQL} THEN 'sealed' ELSE 'draft' END,
+    preparation_id=NULL,fingerprint=NULL,preparation_json=NULL,
+    prepared_user_data_revision=NULL`;