@membox-cloud/membox 0.1.0

package/dist/src/tools/result.d.ts

@@ -0,0 +1,7 @@
+export declare function jsonResult(payload: unknown): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    details: unknown;
+};

package/dist/src/tools/result.js

@@ -0,0 +1,6 @@
+export function jsonResult(payload) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+        details: payload,
+    };
+}

package/dist/src/tools/secret-file.d.ts

@@ -0,0 +1,10 @@
+export declare function readSecretFile(pathValue: string, options: {
+    label: string;
+    trimWhitespace?: boolean;
+}): Promise<{
+    value: string;
+    resolvedPath: string;
+}>;
+export declare function writeSecretFile(pathValue: string, value: string): Promise<{
+    resolvedPath: string;
+}>;

package/dist/src/tools/secret-file.js

@@ -0,0 +1,37 @@
+import { mkdir, readFile, rename, stat, writeFile, chmod } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+function ensurePrivatePermissions(mode, label, path) {
+    if (process.platform === "win32") {
+        return;
+    }
+    if ((mode & 0o077) !== 0) {
+        throw new Error(`${label} file must not be readable by group or others: ${path}. Run \`chmod 600 ${path}\` first.`);
+    }
+}
+export async function readSecretFile(pathValue, options) {
+    const resolvedPath = resolve(process.cwd(), pathValue);
+    const info = await stat(resolvedPath);
+    if (!info.isFile()) {
+        throw new Error(`${options.label} path is not a file: ${resolvedPath}`);
+    }
+    ensurePrivatePermissions(info.mode, options.label, resolvedPath);
+    const raw = await readFile(resolvedPath, "utf8");
+    const value = options.trimWhitespace
+        ? raw.trim()
+        : raw.replace(/[\r\n]+$/, "");
+    if (!value) {
+        throw new Error(`${options.label} file is empty: ${resolvedPath}`);
+    }
+    return { value, resolvedPath };
+}
+export async function writeSecretFile(pathValue, value) {
+    const resolvedPath = resolve(process.cwd(), pathValue);
+    const tmp = `${resolvedPath}.tmp.${Date.now()}`;
+    await mkdir(dirname(resolvedPath), { recursive: true });
+    await writeFile(tmp, value.endsWith("\n") ? value : `${value}\n`, {
+        mode: 0o600,
+    });
+    await rename(tmp, resolvedPath);
+    await chmod(resolvedPath, 0o600).catch(() => { });
+    return { resolvedPath };
+}

package/dist/src/tools/setup-finish.d.ts

@@ -0,0 +1,36 @@
+import type { memboxConfig } from "../config.js";
+export declare function createSetupFinishTool(cfg: memboxConfig): {
+    name: string;
+    label: string;
+    description: string;
+    parameters: {
+        type: "object";
+        properties: {
+            passphrase_file: {
+                type: "string";
+                description: string;
+            };
+            recovery_code_output_file: {
+                type: "string";
+                description: string;
+            };
+            enable_managed_unlock: {
+                type: "boolean";
+                description: string;
+            };
+        };
+        required: string[];
+        additionalProperties: boolean;
+    };
+    execute(_toolCallId?: string, params?: {
+        passphrase_file?: string;
+        recovery_code_output_file?: string;
+        enable_managed_unlock?: boolean;
+    }): Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        details: unknown;
+    }>;
+};

package/dist/src/tools/setup-finish.js

@@ -0,0 +1,108 @@
+import { readState } from "../store/local-state.js";
+import { authorizeDevice, pollPendingDeviceAuthorizationOnce, } from "../cli/bootstrap.js";
+import { finishAuthorizedSetup } from "../cli/setup.js";
+import { runWithProvisioningRollback } from "../cli/provisioning.js";
+import { jsonResult } from "./result.js";
+import { readSecretFile, writeSecretFile } from "./secret-file.js";
+export function createSetupFinishTool(cfg) {
+    return {
+        name: "membox_setup_finish",
+        label: "Membox Vault Setup Finish",
+        description: "Finish the authorized Membox Vault setup on this machine using a local passphrase file. Optionally writes the generated recovery code to a local file and can explicitly opt in to managed auto-unlock.",
+        parameters: {
+            type: "object",
+            properties: {
+                passphrase_file: {
+                    type: "string",
+                    description: "Path to a local file containing the new vault passphrase. On Unix, the file must not be readable by group or others.",
+                },
+                recovery_code_output_file: {
+                    type: "string",
+                    description: "Optional local output file for the recovery code. Required for first-device setup so the recovery code stays local to the machine.",
+                },
+                enable_managed_unlock: {
+                    type: "boolean",
+                    description: "When true, explicitly opt this machine into storing a managed local unlock secret so future sync/pull/grant commands can auto-unlock without another passphrase prompt.",
+                },
+            },
+            required: ["passphrase_file"],
+            additionalProperties: false,
+        },
+        async execute(_toolCallId, params) {
+            const state = await readState();
+            if (state?.setup_complete) {
+                return jsonResult({
+                    already_setup: true,
+                    message: "Vault is already set up on this machine. Use unlock/sync/pull/status instead of setup_finish.",
+                });
+            }
+            if (!params?.passphrase_file) {
+                return jsonResult({
+                    error: true,
+                    message: "Missing required parameter: `passphrase_file`.",
+                });
+            }
+            const authStatus = await pollPendingDeviceAuthorizationOnce(cfg);
+            if (authStatus.status === "not_started") {
+                return jsonResult({
+                    status: "not_started",
+                    error: true,
+                    message: "No pending setup exists. Call `membox_setup_start`, send the verification link to the user, then poll with `membox_setup_poll`.",
+                });
+            }
+            if (authStatus.status === "authorization_pending" ||
+                authStatus.status === "slow_down") {
+                return jsonResult({
+                    status: authStatus.status,
+                    user_code: authStatus.pendingSetup?.user_code,
+                    verification_uri_complete: authStatus.pendingSetup?.verification_uri_complete,
+                    retry_after_seconds: authStatus.retryAfterSeconds,
+                    message: authStatus.message ??
+                        "Still waiting for browser authorization before setup can finish.",
+                });
+            }
+            if (authStatus.status === "denied" || authStatus.status === "expired") {
+                return jsonResult({
+                    status: authStatus.status,
+                    error: true,
+                    message: authStatus.message,
+                });
+            }
+            try {
+                const { value: passphrase, resolvedPath: passphrasePath } = await readSecretFile(params.passphrase_file, {
+                    label: "Passphrase",
+                    trimWhitespace: false,
+                });
+                const auth = await authorizeDevice(cfg);
+                const result = await runWithProvisioningRollback(auth, async (markProvisioned) => {
+                    const completed = await finishAuthorizedSetup(cfg, auth, {
+                        passphrase,
+                        enableManagedUnlock: params.enable_managed_unlock === true,
+                        onRecoveryCode: params.recovery_code_output_file
+                            ? async (recoveryCode) => {
+                                await writeSecretFile(params.recovery_code_output_file, recoveryCode);
+                            }
+                            : undefined,
+                    });
+                    markProvisioned();
+                    return completed;
+                });
+                return jsonResult({
+                    ok: true,
+                    ...result,
+                    passphrase_file: passphrasePath,
+                    recovery_code_output_file: params.recovery_code_output_file,
+                    message: result.initialMode === "pull"
+                        ? "Setup finished. Existing encrypted memory was pulled to this machine."
+                        : "Setup finished. New vault initialized and initial sync completed.",
+                });
+            }
+            catch (err) {
+                return jsonResult({
+                    error: true,
+                    message: `Setup finish failed: ${err instanceof Error ? err.message : String(err)}`,
+                });
+            }
+        },
+    };
+}

package/dist/src/tools/setup-poll.d.ts

@@ -0,0 +1,27 @@
+import type { memboxConfig } from "../config.js";
+export declare function createSetupPollTool(cfg: memboxConfig): {
+    name: string;
+    label: string;
+    description: string;
+    parameters: {
+        type: "object";
+        properties: {
+            wait_seconds: {
+                type: "integer";
+                minimum: number;
+                maximum: number;
+                description: string;
+            };
+        };
+        additionalProperties: boolean;
+    };
+    execute(_toolCallId?: string, params?: {
+        wait_seconds?: number;
+    }): Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        details: unknown;
+    }>;
+};

package/dist/src/tools/setup-poll.js

@@ -0,0 +1,83 @@
+import { pollPendingDeviceAuthorizationOnce } from "../cli/bootstrap.js";
+import { readState } from "../store/local-state.js";
+function jsonResult(payload) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+        details: payload,
+    };
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export function createSetupPollTool(cfg) {
+    return {
+        name: "membox_setup_poll",
+        label: "Membox Vault Setup Poll",
+        description: "Poll the pending Membox Vault browser authorization until it completes or times out. Does not collect passphrases.",
+        parameters: {
+            type: "object",
+            properties: {
+                wait_seconds: {
+                    type: "integer",
+                    minimum: 0,
+                    maximum: 30,
+                    description: "Optional bounded wait window. The tool will keep polling within this window before returning the latest status.",
+                },
+            },
+            additionalProperties: false,
+        },
+        async execute(_toolCallId, params) {
+            const state = await readState();
+            if (state?.setup_complete) {
+                return jsonResult({
+                    already_setup: true,
+                    message: "Membox Vault is already set up.",
+                });
+            }
+            const waitSeconds = Math.max(0, Math.min(30, params?.wait_seconds ?? 0));
+            const deadline = Date.now() + waitSeconds * 1000;
+            let latest = await pollPendingDeviceAuthorizationOnce(cfg);
+            while (Date.now() < deadline &&
+                (latest.status === "authorization_pending" || latest.status === "slow_down")) {
+                const waitMs = Math.min(Math.max(1, latest.retryAfterSeconds ?? 1) * 1000, deadline - Date.now());
+                if (waitMs <= 0) {
+                    break;
+                }
+                await sleep(waitMs);
+                latest = await pollPendingDeviceAuthorizationOnce(cfg);
+            }
+            if (latest.status === "authorized") {
+                return jsonResult({
+                    status: "authorized",
+                    user_code: latest.pendingSetup?.user_code,
+                    verification_uri_complete: latest.pendingSetup?.verification_uri_complete,
+                    device_name: latest.pendingSetup?.device_name,
+                    message: latest.message ??
+                        "Browser authorization completed. This machine can now finish secure setup with `membox_setup_finish`.",
+                    next_action: "Call `membox_setup_finish` with a local `passphrase_file` to complete passphrase setup, recovery generation, and initial sync.",
+                });
+            }
+            if (latest.status === "not_started") {
+                return jsonResult({
+                    status: "not_started",
+                    message: "No pending setup authorization exists. Call `membox_setup_start` first.",
+                });
+            }
+            if (latest.status === "denied" || latest.status === "expired") {
+                return jsonResult({
+                    status: latest.status,
+                    message: latest.message,
+                });
+            }
+            return jsonResult({
+                status: latest.status,
+                user_code: latest.pendingSetup?.user_code,
+                verification_uri_complete: latest.pendingSetup?.verification_uri_complete,
+                expires_at: latest.pendingSetup?.expires_at,
+                retry_after_seconds: latest.retryAfterSeconds,
+                message: latest.message ??
+                    "Still waiting for browser authorization. Keep polling until it completes.",
+            });
+        },
+    };
+}

package/dist/src/tools/setup-start.d.ts

@@ -0,0 +1,18 @@
+import type { memboxConfig } from "../config.js";
+export declare function createSetupStartTool(cfg: memboxConfig): {
+    name: string;
+    label: string;
+    description: string;
+    parameters: {
+        type: "object";
+        properties: {};
+        additionalProperties: boolean;
+    };
+    execute(_toolCallId?: string): Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        details: unknown;
+    }>;
+};

package/dist/src/tools/setup-start.js

@@ -0,0 +1,49 @@
+import { ensurePendingDeviceAuthorization } from "../cli/bootstrap.js";
+import { readState } from "../store/local-state.js";
+function jsonResult(payload) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+        details: payload,
+    };
+}
+export function createSetupStartTool(cfg) {
+    return {
+        name: "membox_setup_start",
+        label: "Membox Vault Setup",
+        description: "Start Membox Vault browser authorization and return a clickable verification link. Does not collect the local vault passphrase.",
+        parameters: {
+            type: "object",
+            properties: {},
+            additionalProperties: false,
+        },
+        async execute(_toolCallId) {
+            const state = await readState();
+            if (state?.setup_complete) {
+                return jsonResult({
+                    already_setup: true,
+                    message: "Membox Vault is already set up.",
+                });
+            }
+            const { pendingSetup, created } = await ensurePendingDeviceAuthorization(cfg);
+            if (pendingSetup.status === "authorized") {
+                return jsonResult({
+                    status: "authorized",
+                    user_code: pendingSetup.user_code,
+                    verification_uri_complete: pendingSetup.verification_uri_complete,
+                    message: "Browser authorization is already complete. Call `membox_setup_finish` with a local `passphrase_file` to finish secure setup on this machine.",
+                });
+            }
+            return jsonResult({
+                status: "authorization_pending",
+                created,
+                user_code: pendingSetup.user_code,
+                verification_uri_complete: pendingSetup.verification_uri_complete,
+                expires_at: pendingSetup.expires_at,
+                interval_seconds: pendingSetup.interval_seconds,
+                clickable_link_markdown: `[Authorize Membox Vault](${pendingSetup.verification_uri_complete})`,
+                message: "Send this link to the user. After they finish login and device approval in a browser, call `membox_setup_poll` until it returns `authorized`.",
+                next_action: "When authorization completes, call `membox_setup_finish` with a local `passphrase_file` to finish secure setup on this machine.",
+            });
+        },
+    };
+}

package/dist/src/tools/status.d.ts

@@ -0,0 +1,17 @@
+export declare function createStatusTool(): {
+    name: string;
+    label: string;
+    description: string;
+    parameters: {
+        type: "object";
+        properties: {};
+        additionalProperties: boolean;
+    };
+    execute(): Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        details: unknown;
+    }>;
+};

package/dist/src/tools/status.js

@@ -0,0 +1,40 @@
+import { readState } from "../store/local-state.js";
+import { vaultSession } from "../store/session.js";
+import { getManagedUnlockStatus } from "../store/managed-unlock.js";
+function jsonResult(payload) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+        details: payload,
+    };
+}
+export function createStatusTool() {
+    return {
+        name: "membox_status",
+        label: "Membox Vault Status",
+        description: "Check Membox Vault sync status. Returns setup state, lock state, sync cursor, and file count.",
+        parameters: {
+            type: "object",
+            properties: {},
+            additionalProperties: false,
+        },
+        async execute() {
+            const state = await readState();
+            if (!state?.setup_complete) {
+                return jsonResult({
+                    status: "not_setup",
+                    message: "Membox Vault is not set up. Ask the user to run `openclaw membox setup` in their terminal.",
+                });
+            }
+            const managedUnlock = await getManagedUnlockStatus();
+            return jsonResult({
+                status: "ok",
+                unlocked: vaultSession.isUnlocked(),
+                managed_unlock: managedUnlock,
+                server: state.server_url,
+                device: state.device_name,
+                cursor: state.sync_cursor,
+                files: Object.keys(state.file_versions).length,
+            });
+        },
+    };
+}

package/dist/src/tools/sync.d.ts

@@ -0,0 +1,17 @@
+export declare function createSyncTool(): {
+    name: string;
+    label: string;
+    description: string;
+    parameters: {
+        type: "object";
+        properties: {};
+        additionalProperties: boolean;
+    };
+    execute(): Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        details: unknown;
+    }>;
+};

package/dist/src/tools/sync.js

@@ -0,0 +1,49 @@
+import { readState } from "../store/local-state.js";
+import { ensureVaultUnlocked } from "../cli/unlock.js";
+function jsonResult(payload) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+        details: payload,
+    };
+}
+export function createSyncTool() {
+    return {
+        name: "membox_sync",
+        label: "Membox Vault Sync",
+        description: "Sync local memory changes to Membox cloud. Uses the current unlocked session or an explicitly enabled managed local unlock secret.",
+        parameters: {
+            type: "object",
+            properties: {},
+            additionalProperties: false,
+        },
+        async execute() {
+            const state = await readState();
+            if (!state?.setup_complete) {
+                return jsonResult({
+                    error: true,
+                    message: "Vault not set up. Ask the user to run `openclaw membox setup` in their terminal.",
+                });
+            }
+            if (!(await ensureVaultUnlocked({
+                allowPrompt: false,
+                announceSuccess: true,
+            }))) {
+                return jsonResult({
+                    error: true,
+                    message: "Vault is locked. Call `membox_unlock` with a local `passphrase_file`, enable `membox_unlock_secret_enable`, or ask the user to run `openclaw membox unlock` in their terminal.",
+                });
+            }
+            try {
+                const { syncAction } = await import("../cli/sync.js");
+                await syncAction();
+                return jsonResult({ ok: true, message: "Sync complete." });
+            }
+            catch (err) {
+                return jsonResult({
+                    error: true,
+                    message: `Sync failed: ${err instanceof Error ? err.message : String(err)}`,
+                });
+            }
+        },
+    };
+}

package/dist/src/tools/unlock-secret.d.ts

@@ -0,0 +1,42 @@
+export declare function createUnlockSecretEnableTool(): {
+    name: string;
+    label: string;
+    description: string;
+    parameters: {
+        type: "object";
+        properties: {
+            passphrase_file: {
+                type: "string";
+                description: string;
+            };
+        };
+        required: string[];
+        additionalProperties: boolean;
+    };
+    execute(_toolCallId?: string, params?: {
+        passphrase_file?: string;
+    }): Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        details: unknown;
+    }>;
+};
+export declare function createUnlockSecretDisableTool(): {
+    name: string;
+    label: string;
+    description: string;
+    parameters: {
+        type: "object";
+        properties: {};
+        additionalProperties: boolean;
+    };
+    execute(): Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        details: unknown;
+    }>;
+};

package/dist/src/tools/unlock-secret.js

@@ -0,0 +1,87 @@
+import { readState } from "../store/local-state.js";
+import { jsonResult } from "./result.js";
+import { readSecretFile } from "./secret-file.js";
+import { disableManagedUnlockAction, enableManagedUnlockAction, } from "../cli/unlock.js";
+import { getManagedUnlockStatus } from "../store/managed-unlock.js";
+export function createUnlockSecretEnableTool() {
+    return {
+        name: "membox_unlock_secret_enable",
+        label: "Membox Managed Unlock Enable",
+        description: "Explicitly opt this machine into a managed local unlock secret by validating and storing the vault passphrase in the local keychain.",
+        parameters: {
+            type: "object",
+            properties: {
+                passphrase_file: {
+                    type: "string",
+                    description: "Path to a local file containing the current vault passphrase. On Unix, the file must not be readable by group or others.",
+                },
+            },
+            required: ["passphrase_file"],
+            additionalProperties: false,
+        },
+        async execute(_toolCallId, params) {
+            const state = await readState();
+            if (!state?.setup_complete) {
+                return jsonResult({
+                    error: true,
+                    message: "Vault not set up. Complete setup before enabling managed unlock.",
+                });
+            }
+            if (!params?.passphrase_file) {
+                return jsonResult({
+                    error: true,
+                    message: "Missing required parameter: `passphrase_file`.",
+                });
+            }
+            try {
+                const { value: passphrase, resolvedPath } = await readSecretFile(params.passphrase_file, {
+                    label: "Passphrase",
+                    trimWhitespace: false,
+                });
+                await enableManagedUnlockAction(passphrase);
+                const status = await getManagedUnlockStatus();
+                return jsonResult({
+                    ok: true,
+                    passphrase_file: resolvedPath,
+                    managed_unlock: status,
+                    message: "Managed unlock secret enabled on this machine.",
+                });
+            }
+            catch (err) {
+                return jsonResult({
+                    error: true,
+                    message: `Managed unlock enable failed: ${err instanceof Error ? err.message : String(err)}`,
+                });
+            }
+        },
+    };
+}
+export function createUnlockSecretDisableTool() {
+    return {
+        name: "membox_unlock_secret_disable",
+        label: "Membox Managed Unlock Disable",
+        description: "Disable and delete the managed local unlock secret on this machine.",
+        parameters: {
+            type: "object",
+            properties: {},
+            additionalProperties: false,
+        },
+        async execute() {
+            try {
+                await disableManagedUnlockAction();
+                const status = await getManagedUnlockStatus();
+                return jsonResult({
+                    ok: true,
+                    managed_unlock: status,
+                    message: "Managed unlock secret disabled on this machine.",
+                });
+            }
+            catch (err) {
+                return jsonResult({
+                    error: true,
+                    message: `Managed unlock disable failed: ${err instanceof Error ? err.message : String(err)}`,
+                });
+            }
+        },
+    };
+}

package/dist/src/tools/unlock.d.ts

@@ -0,0 +1,25 @@
+export declare function createUnlockTool(): {
+    name: string;
+    label: string;
+    description: string;
+    parameters: {
+        type: "object";
+        properties: {
+            passphrase_file: {
+                type: "string";
+                description: string;
+            };
+        };
+        required: string[];
+        additionalProperties: boolean;
+    };
+    execute(_toolCallId?: string, params?: {
+        passphrase_file?: string;
+    }): Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        details: unknown;
+    }>;
+};