@membox-cloud/membox 0.1.0 → 0.1.1

package/README.md

@@ -10,9 +10,15 @@ Keep your local Markdown memory (`MEMORY.md`, `memory/*.md`) as the source of tr
 openclaw plugins install @membox-cloud/membox
 ```
 
+Optional skill install from ClawHub:
+
+```bash
+clawhub install membox-cloud-sync
+```
+
 ## Prerequisites
 
-- OpenClaw >= 2026.3.7
+- OpenClaw >= 2026.2.14
 - A [membox.cloud](https://membox.cloud) account (GitHub, Google, or email login)
 
 ## Quick Start
@@ -109,7 +115,8 @@ Security note:
 
 - Secret-bearing tools read from local files so the model does not need the vault passphrase or recovery code inline.
 - First-device tool-only setup should always provide a local `recovery_code_output_file` so the recovery code never needs to travel through the model.
-- Managed unlock is explicit opt-in. When enabled, the passphrase is kept in the local keychain for future auto-unlock on that machine.
+- Setup and restore now persist device secrets in a local passphrase-encrypted bundle, so published npm installs do not depend on native `keytar`.
+- Managed unlock is explicit opt-in. When enabled, the passphrase is kept only on the local machine, using the platform keychain when available or a private local fallback file when it is not.
 - On Unix-like systems, passphrase and recovery-code files should be private, for example `chmod 600 /path/to/file`.
 
 ## Configuration
@@ -145,8 +152,6 @@ For an agent-first install + pairing flow, see `./AGENT-WORKFLOW.md` and run `ba
 
 For release, production rollout, and final human-owned checks, see `./RELEASE-CHECKLIST.md`.
 
-If native `keytar` support is unavailable on your machine, setup/unlock will now fail closed by default instead of silently writing secrets in plaintext. For local sandbox testing only, you can opt into the old file-based fallback with `MEMBOX_ALLOW_INSECURE_FILE_KEYCHAIN=1`.
-
 ## Security Model
 
 - **Zero-knowledge**: encryption/decryption happens locally. The server never sees plaintext.

package/dist/src/cli/bootstrap.js

@@ -1,14 +1,14 @@
 import { execFile } from "node:child_process";
 import { hostname } from "node:os";
 import { API_PREFIX, PLUGIN_VERSION } from "../constants.js";
-import { deriveURK } from "../crypto/kdf.js";
-import { wrapAMK } from "../crypto/keys.js";
 import { generateDeviceKeyPair, } from "../crypto/device-keys.js";
 import { getAccountMe } from "../api/account.js";
 import { MemboxApiClient } from "../api/client.js";
 import { pollDeviceFlow, pollDeviceFlowOnce, startDeviceFlow, } from "../api/device-flow.js";
-import { ACCOUNTS, getBytes, getString, storeBytes, storeString, clearPendingSetupSecrets, } from "../store/keychain.js";
+import { clearPendingSetupSecrets, } from "../store/keychain.js";
+import { clearPendingSetupSecretsFile, getPendingSetupRefreshToken, loadPendingSetupDeviceKeys as loadPendingSetupDeviceKeysFile, storePendingSetupDeviceKeys as storePendingSetupDeviceKeysFile, storePendingSetupRefreshToken, } from "../store/pending-setup-secrets.js";
 import { deletePendingSetup, isPendingSetupExpired, readPendingSetup, writePendingSetup, } from "../store/pending-setup.js";
+import { persistVaultSecretsBundle } from "../store/vault-secrets.js";
 export function toB64(data) {
     return Buffer.from(data).toString("base64");
 }
@@ -55,7 +55,7 @@ function createAuthenticatedClient(params) {
     return new MemboxApiClient(params.baseUrl, async () => accessToken, async () => refreshToken, async (access, refresh) => {
         accessToken = access;
         refreshToken = refresh;
-        await storeString(params.refreshTokenAccount, refresh);
+        await params.onRefreshTokenPersist?.(refresh);
     });
 }
 function pendingSetupBaseUrl(cfg) {
@@ -65,37 +65,14 @@ function describeAccount(account) {
     return account.display_name ?? account.primary_email ?? account.user_id;
 }
 async function storePendingSetupDeviceKeys(deviceKeys) {
-    await storeBytes(ACCOUNTS.PENDING_SETUP_ED25519_PRIVATE, deviceKeys.ed25519.privateKey);
-    await storeBytes(ACCOUNTS.PENDING_SETUP_ED25519_PUBLIC, deviceKeys.ed25519.publicKey);
-    await storeBytes(ACCOUNTS.PENDING_SETUP_X25519_PRIVATE, deviceKeys.x25519.privateKey);
-    await storeBytes(ACCOUNTS.PENDING_SETUP_X25519_PUBLIC, deviceKeys.x25519.publicKey);
+    await storePendingSetupDeviceKeysFile(deviceKeys);
 }
 async function loadPendingSetupDeviceKeys() {
-    const [ed25519Private, ed25519Public, x25519Private, x25519Public,] = await Promise.all([
-        getBytes(ACCOUNTS.PENDING_SETUP_ED25519_PRIVATE),
-        getBytes(ACCOUNTS.PENDING_SETUP_ED25519_PUBLIC),
-        getBytes(ACCOUNTS.PENDING_SETUP_X25519_PRIVATE),
-        getBytes(ACCOUNTS.PENDING_SETUP_X25519_PUBLIC),
-    ]);
-    if (!ed25519Private ||
-        !ed25519Public ||
-        !x25519Private ||
-        !x25519Public) {
-        throw new Error("Pending setup secrets are incomplete. Start setup again to regenerate device authorization.");
-    }
-    return {
-        ed25519: {
-            privateKey: ed25519Private,
-            publicKey: ed25519Public,
-        },
-        x25519: {
-            privateKey: x25519Private,
-            publicKey: x25519Public,
-        },
-    };
+    return loadPendingSetupDeviceKeysFile();
 }
 export async function clearPendingSetupArtifacts() {
     await clearPendingSetupSecrets();
+    await clearPendingSetupSecretsFile();
     await deletePendingSetup();
 }
 async function loadActivePendingSetup(cfg) {
@@ -158,12 +135,12 @@ export async function ensurePendingDeviceAuthorization(cfg) {
     return { pendingSetup: created, created: true };
 }
 async function finalizePendingAuthorization(cfg, pendingSetup, tokens) {
-    await storeString(ACCOUNTS.PENDING_SETUP_REFRESH_TOKEN, tokens.refresh_token);
+    await storePendingSetupRefreshToken(tokens.refresh_token);
     const client = createAuthenticatedClient({
         baseUrl: pendingSetupBaseUrl(cfg),
         accessToken: tokens.access_token,
         refreshToken: tokens.refresh_token,
-        refreshTokenAccount: ACCOUNTS.PENDING_SETUP_REFRESH_TOKEN,
+        onRefreshTokenPersist: storePendingSetupRefreshToken,
     });
     const account = await getAccountMe(client);
     const authorizedSetup = {
@@ -239,7 +216,7 @@ async function buildAuthorizedContextFromPending(cfg, pendingSetup, options) {
         throw new Error("Device authorization has not completed yet. Finish browser authorization first.");
     }
     const refreshToken = options?.refreshToken ??
-        (await getString(ACCOUNTS.PENDING_SETUP_REFRESH_TOKEN));
+        (await getPendingSetupRefreshToken());
     if (!refreshToken) {
         throw new Error("Pending setup is missing its refresh token. Start setup again.");
     }
@@ -248,7 +225,7 @@ async function buildAuthorizedContextFromPending(cfg, pendingSetup, options) {
         baseUrl: pendingSetupBaseUrl(cfg),
         accessToken: options?.accessToken,
         refreshToken,
-        refreshTokenAccount: ACCOUNTS.PENDING_SETUP_REFRESH_TOKEN,
+        onRefreshTokenPersist: storePendingSetupRefreshToken,
     });
     const account = options?.account ?? (await getAccountMe(client));
     return {
@@ -307,20 +284,5 @@ export async function authorizeDevice(cfg) {
     return waitForPendingAuthorization(cfg, pendingSetup);
 }
 export async function persistVaultSecrets(params) {
-    const { urk, salt } = await deriveURK(params.passphrase);
-    try {
-        const wrappedAmk = wrapAMK(urk, params.amk);
-        await storeBytes(ACCOUNTS.ED25519_PRIVATE, params.deviceKeys.ed25519.privateKey);
-        await storeBytes(ACCOUNTS.ED25519_PUBLIC, params.deviceKeys.ed25519.publicKey);
-        await storeBytes(ACCOUNTS.X25519_PRIVATE, params.deviceKeys.x25519.privateKey);
-        await storeBytes(ACCOUNTS.X25519_PUBLIC, params.deviceKeys.x25519.publicKey);
-        await storeBytes(ACCOUNTS.WRAPPED_AMK, wrappedAmk.encrypted_amk);
-        await storeBytes(ACCOUNTS.WRAPPED_AMK_SALT, salt);
-        await storeBytes(ACCOUNTS.WRAPPED_AMK_IV, wrappedAmk.iv);
-        await storeBytes(ACCOUNTS.WRAPPED_AMK_TAG, wrappedAmk.tag);
-        await storeString(ACCOUNTS.REFRESH_TOKEN, params.refreshToken);
-    }
-    finally {
-        urk.fill(0);
-    }
+    await persistVaultSecretsBundle(params);
 }

package/dist/src/cli/grants.js

@@ -1,7 +1,6 @@
 import { createAuthenticatedClient } from "./helpers.js";
 import { vaultSession } from "../store/session.js";
 import { getState } from "../sync/state.js";
-import { ACCOUNTS, getBytes, } from "../store/keychain.js";
 import { createDeviceGrant } from "../crypto/grant.js";
 import { computeSha256Hex } from "../crypto/manifest.js";
 import { approveGrant, getPendingGrants, } from "../api/devices.js";
@@ -28,11 +27,7 @@ export async function approvePendingGrants() {
             approvedGrantIds: [],
         };
     }
-    const sourceEdPrivateKey = await getBytes(ACCOUNTS.ED25519_PRIVATE);
-    const sourceXPrivateKey = await getBytes(ACCOUNTS.X25519_PRIVATE);
-    if (!sourceEdPrivateKey || !sourceXPrivateKey) {
-        throw new Error("Device keypair missing from local keychain. Re-run setup on this device.");
-    }
+    const deviceKeys = vaultSession.getDeviceKeys();
     const amk = vaultSession.getAMK();
     let approved = 0;
     let skipped = 0;
@@ -44,8 +39,8 @@ export async function approvePendingGrants() {
             continue;
         }
         const { payloadBytes, signature } = createDeviceGrant({
-            sourceEdPrivateKey,
-            sourceXPrivateKey,
+            sourceEdPrivateKey: deviceKeys.ed25519.privateKey,
+            sourceXPrivateKey: deviceKeys.x25519.privateKey,
             sourceDeviceId: state.device_id,
             targetDeviceId: grant.target_device_id,
             targetKexPublicKey: fromB64(grant.target_device_kex_public_key_b64),

package/dist/src/cli/helpers.js

@@ -1,13 +1,25 @@
 import { MemboxApiClient } from "../api/client.js";
-import { getString, storeString, ACCOUNTS } from "../store/keychain.js";
 import { API_PREFIX } from "../constants.js";
+import { vaultSession } from "../store/session.js";
+import { persistVaultSecretsWithKey } from "../store/vault-secrets.js";
 let cachedAccessToken = null;
 /**
  * Create an authenticated API client using stored tokens.
  */
 export async function createAuthenticatedClient(state) {
-    return new MemboxApiClient(state.server_url + API_PREFIX, async () => cachedAccessToken, async () => getString(ACCOUNTS.REFRESH_TOKEN), async (access, refresh) => {
+    return new MemboxApiClient(state.server_url + API_PREFIX, async () => cachedAccessToken, async () => vaultSession.getRefreshToken(), async (access, refresh) => {
         cachedAccessToken = access;
-        await storeString(ACCOUNTS.REFRESH_TOKEN, refresh);
+        await vaultSession.updateRefreshToken(refresh);
+        const persistenceKey = vaultSession.getPersistenceKey();
+        const persistenceSalt = vaultSession.getPersistenceSalt();
+        if (persistenceKey && persistenceSalt) {
+            await persistVaultSecretsWithKey({
+                amk: vaultSession.getAMK(),
+                deviceKeys: vaultSession.getDeviceKeys(),
+                refreshToken: refresh,
+                persistenceKey,
+                salt: persistenceSalt,
+            });
+        }
     });
 }

package/dist/src/cli/provisioning.js

@@ -3,6 +3,8 @@ import { clearPendingSetupArtifacts, } from "./bootstrap.js";
 import { clearStoredSecrets } from "../store/keychain.js";
 import { deleteState } from "../store/local-state.js";
 import { vaultSession } from "../store/session.js";
+import { deleteVaultSecretsFile } from "../store/vault-secrets.js";
+import { disableManagedUnlock } from "../store/managed-unlock.js";
 export async function rollbackIncompleteProvisioning(auth) {
     vaultSession.lock();
     try {
@@ -12,6 +14,8 @@ export async function rollbackIncompleteProvisioning(auth) {
         console.warn("[membox] Failed to revoke incomplete device authorization:", error);
     }
     await clearStoredSecrets();
+    await deleteVaultSecretsFile();
+    await disableManagedUnlock().catch(() => { });
     await clearPendingSetupArtifacts();
     await deleteState();
 }

package/dist/src/cli/restore.js

@@ -10,6 +10,7 @@ import { pullAction } from "./pull.js";
 import { readPassphraseWithConfirm } from "./passphrase-input.js";
 import { authorizeDevice, clearPendingSetupArtifacts, persistVaultSecrets, } from "./bootstrap.js";
 import { runWithProvisioningRollback } from "./provisioning.js";
+import { loadVaultSecretsWithPassphrase } from "../store/vault-secrets.js";
 async function readRecoveryCode() {
     const rl = createInterface({ input, output });
     try {
@@ -54,7 +55,17 @@ export async function restoreAuthorizedDeviceFromRecovery(cfg, auth, params) {
             await writeState(state);
             await clearPendingSetupArtifacts();
             markProvisioned();
-            vaultSession.unlock(amk);
+            const loadedSecrets = await loadVaultSecretsWithPassphrase(params.passphrase);
+            if (!loadedSecrets) {
+                throw new Error("Persisted vault secrets are missing after restore.");
+            }
+            vaultSession.unlock({
+                amk: loadedSecrets.amk,
+                deviceKeys: loadedSecrets.deviceKeys,
+                refreshToken: loadedSecrets.refreshToken,
+                persistenceKey: loadedSecrets.persistenceKey,
+                persistenceSalt: loadedSecrets.salt,
+            });
             console.log("Recovery successful. Pulling encrypted memory...");
             await pullAction({ onConflict: "conflict-copy" });
             console.log("Restore complete! Vault is ready.");

package/dist/src/cli/setup.js

@@ -16,6 +16,7 @@ import { updateFileVersion } from "../sync/state.js";
 import { pullAction } from "./pull.js";
 import { authorizeDevice, clearPendingSetupArtifacts, fromB64, persistVaultSecrets, toB64, } from "./bootstrap.js";
 import { runWithProvisioningRollback } from "./provisioning.js";
+import { loadVaultSecretsWithPassphrase } from "../store/vault-secrets.js";
 export function selectGrantCapableDevices(devices, currentDeviceId) {
     return devices.filter((device) => device.device_id !== currentDeviceId &&
         device.status === "active" &&
@@ -131,7 +132,17 @@ export async function finishAuthorizedSetup(cfg, auth, params) {
             await enableManagedUnlock(params.passphrase);
         }
         await clearPendingSetupArtifacts();
-        vaultSession.unlock(amk);
+        const loadedSecrets = await loadVaultSecretsWithPassphrase(params.passphrase);
+        if (!loadedSecrets) {
+            throw new Error("Persisted vault secrets are missing after setup.");
+        }
+        vaultSession.unlock({
+            amk: loadedSecrets.amk,
+            deviceKeys: loadedSecrets.deviceKeys,
+            refreshToken: loadedSecrets.refreshToken,
+            persistenceKey: loadedSecrets.persistenceKey,
+            persistenceSalt: loadedSecrets.salt,
+        });
         if (initialMode === "pull") {
             console.log("Pulling existing encrypted memory...");
             const pullResult = await pullAction({ onConflict: "conflict-copy" });

package/dist/src/cli/unlock.js

@@ -1,15 +1,20 @@
 import { readState } from "../store/local-state.js";
 import { getBytes, ACCOUNTS } from "../store/keychain.js";
+import { getString } from "../store/keychain.js";
 import { deriveURK } from "../crypto/kdf.js";
 import { unwrapAMK } from "../crypto/keys.js";
 import { vaultSession } from "../store/session.js";
 import { disableManagedUnlock, enableManagedUnlock, getManagedUnlockPassphrase, getManagedUnlockStatus, } from "../store/managed-unlock.js";
 import { readPassphrase } from "./passphrase-input.js";
+import { hasPersistedVaultSecrets, loadVaultSecretsWithPassphrase, } from "../store/vault-secrets.js";
 async function canUnlockVault() {
     const state = await readState();
     if (!state?.setup_complete) {
         return false;
     }
+    if (await hasPersistedVaultSecrets()) {
+        return true;
+    }
     const wrappedAmk = await getBytes(ACCOUNTS.WRAPPED_AMK);
     const salt = await getBytes(ACCOUNTS.WRAPPED_AMK_SALT);
     const iv = await getBytes(ACCOUNTS.WRAPPED_AMK_IV);
@@ -27,11 +32,55 @@ export async function unlockWithPassphrase(passphrase, options) {
         }
         return false;
     }
+    if (await hasPersistedVaultSecrets()) {
+        if (options?.announceDeriving) {
+            console.log("Deriving key...");
+        }
+        try {
+            const loaded = await loadVaultSecretsWithPassphrase(passphrase);
+            if (!loaded) {
+                if (options?.announceFailure) {
+                    console.error("Encrypted local secrets are missing. Re-run setup or use recovery.");
+                }
+                return false;
+            }
+            vaultSession.unlock({
+                amk: loaded.amk,
+                deviceKeys: loaded.deviceKeys,
+                refreshToken: loaded.refreshToken,
+                persistenceKey: loaded.persistenceKey,
+                persistenceSalt: loaded.salt,
+            });
+            if (options?.announceSuccess) {
+                console.log("Vault unlocked.");
+            }
+            return true;
+        }
+        catch {
+            if (options?.announceFailure) {
+                console.error("Wrong passphrase.");
+            }
+            return false;
+        }
+    }
     const wrappedAmk = await getBytes(ACCOUNTS.WRAPPED_AMK);
     const salt = await getBytes(ACCOUNTS.WRAPPED_AMK_SALT);
     const iv = await getBytes(ACCOUNTS.WRAPPED_AMK_IV);
     const tag = await getBytes(ACCOUNTS.WRAPPED_AMK_TAG);
-    if (!wrappedAmk || !salt || !iv || !tag) {
+    const sourceEdPrivateKey = await getBytes(ACCOUNTS.ED25519_PRIVATE);
+    const sourceEdPublicKey = await getBytes(ACCOUNTS.ED25519_PUBLIC);
+    const sourceXPrivateKey = await getBytes(ACCOUNTS.X25519_PRIVATE);
+    const sourceXPublicKey = await getBytes(ACCOUNTS.X25519_PUBLIC);
+    const refreshToken = await getString(ACCOUNTS.REFRESH_TOKEN);
+    if (!wrappedAmk ||
+        !salt ||
+        !iv ||
+        !tag ||
+        !sourceEdPrivateKey ||
+        !sourceEdPublicKey ||
+        !sourceXPrivateKey ||
+        !sourceXPublicKey ||
+        !refreshToken) {
         if (options?.announceFailure) {
             console.error("Keychain data missing. Re-run setup or use recovery.");
         }
@@ -43,7 +92,20 @@ export async function unlockWithPassphrase(passphrase, options) {
     const { urk } = await deriveURK(passphrase, salt);
     try {
         const amk = unwrapAMK(urk, { encrypted_amk: wrappedAmk, iv, tag });
-        vaultSession.unlock(amk);
+        vaultSession.unlock({
+            amk,
+            deviceKeys: {
+                ed25519: {
+                    privateKey: sourceEdPrivateKey,
+                    publicKey: sourceEdPublicKey,
+                },
+                x25519: {
+                    privateKey: sourceXPrivateKey,
+                    publicKey: sourceXPublicKey,
+                },
+            },
+            refreshToken,
+        });
         if (options?.announceSuccess) {
             console.log("Vault unlocked.");
         }

package/dist/src/constants.d.ts

@@ -6,6 +6,9 @@ export declare const KEYCHAIN_SERVICE: string;
 export declare const STATE_DIR = ".membox";
 export declare const STATE_FILE = "state.json";
 export declare const PENDING_SETUP_FILE = "pending-setup.json";
+export declare const PENDING_SETUP_SECRETS_FILE = "pending-setup-secrets.json";
+export declare const VAULT_SECRETS_FILE = "vault-secrets.json";
+export declare const MANAGED_UNLOCK_FILE = "managed-unlock.json";
 export declare const STATE_ROOT_ENV = "MEMBOX_STATE_ROOT";
 export declare function resolveStateRoot(): string;
 export declare const MANIFEST_VERSION = 1;

package/dist/src/constants.js

@@ -8,6 +8,9 @@ export const KEYCHAIN_SERVICE = process.env.MEMBOX_KEYCHAIN_SERVICE || "membox.c
 export const STATE_DIR = ".membox";
 export const STATE_FILE = "state.json";
 export const PENDING_SETUP_FILE = "pending-setup.json";
+export const PENDING_SETUP_SECRETS_FILE = "pending-setup-secrets.json";
+export const VAULT_SECRETS_FILE = "vault-secrets.json";
+export const MANAGED_UNLOCK_FILE = "managed-unlock.json";
 export const STATE_ROOT_ENV = "MEMBOX_STATE_ROOT";
 export function resolveStateRoot() {
     return process.env[STATE_ROOT_ENV] || join(homedir(), STATE_DIR);

package/dist/src/store/managed-unlock.js

@@ -1,4 +1,7 @@
+import { chmod, mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
 import { ACCOUNTS, deleteSecret, getString, storeString, } from "./keychain.js";
+import { MANAGED_UNLOCK_FILE, resolveStateRoot } from "../constants.js";
 import { readState, writeState } from "./local-state.js";
 async function requireSetupState() {
     const state = await readState();
@@ -7,6 +10,52 @@ async function requireSetupState() {
     }
     return state;
 }
+function fallbackPath() {
+    return join(resolveStateRoot(), MANAGED_UNLOCK_FILE);
+}
+async function readFallbackPassphrase() {
+    try {
+        const raw = await readFile(fallbackPath(), "utf-8");
+        const parsed = JSON.parse(raw);
+        return parsed.passphrase;
+    }
+    catch {
+        return null;
+    }
+}
+async function writeFallbackPassphrase(passphrase) {
+    const path = fallbackPath();
+    await mkdir(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp.${Date.now()}`;
+    await writeFile(tmp, JSON.stringify({ version: 1, passphrase }, null, 2), { mode: 0o600 });
+    await rename(tmp, path);
+    await chmod(path, 0o600).catch(() => { });
+}
+async function deleteFallbackPassphrase() {
+    await unlink(fallbackPath()).catch(() => { });
+}
+async function loadManagedUnlockSecret() {
+    try {
+        return await getString(ACCOUNTS.MANAGED_UNLOCK_PASSPHRASE);
+    }
+    catch {
+        return readFallbackPassphrase();
+    }
+}
+async function persistManagedUnlockSecret(passphrase) {
+    try {
+        await storeString(ACCOUNTS.MANAGED_UNLOCK_PASSPHRASE, passphrase);
+    }
+    catch {
+        await writeFallbackPassphrase(passphrase);
+    }
+}
+async function removeManagedUnlockSecret() {
+    await Promise.allSettled([
+        deleteSecret(ACCOUNTS.MANAGED_UNLOCK_PASSPHRASE),
+        deleteFallbackPassphrase(),
+    ]);
+}
 export async function getManagedUnlockStatus() {
     const state = await readState();
     if (!state?.setup_complete) {
@@ -15,7 +64,7 @@ export async function getManagedUnlockStatus() {
             secret_present: false,
         };
     }
-    const secret = await getString(ACCOUNTS.MANAGED_UNLOCK_PASSPHRASE);
+    const secret = await loadManagedUnlockSecret();
     return {
         enabled: state.managed_unlock_enabled === true,
         secret_present: !!secret,
@@ -26,11 +75,11 @@ export async function getManagedUnlockPassphrase() {
     if (!status.enabled) {
         return null;
     }
-    return getString(ACCOUNTS.MANAGED_UNLOCK_PASSPHRASE);
+    return loadManagedUnlockSecret();
 }
 export async function enableManagedUnlock(passphrase) {
     const state = await requireSetupState();
-    await storeString(ACCOUNTS.MANAGED_UNLOCK_PASSPHRASE, passphrase);
+    await persistManagedUnlockSecret(passphrase);
     if (!state.managed_unlock_enabled) {
         state.managed_unlock_enabled = true;
         await writeState(state);
@@ -38,7 +87,7 @@ export async function enableManagedUnlock(passphrase) {
 }
 export async function disableManagedUnlock() {
     const state = await readState();
-    await deleteSecret(ACCOUNTS.MANAGED_UNLOCK_PASSPHRASE).catch(() => { });
+    await removeManagedUnlockSecret();
     if (state?.setup_complete && state.managed_unlock_enabled) {
         state.managed_unlock_enabled = false;
         await writeState(state);

package/dist/src/store/pending-setup-secrets.d.ts

@@ -0,0 +1,6 @@
+import type { DeviceKeyPair } from "../crypto/device-keys.js";
+export declare function storePendingSetupDeviceKeys(deviceKeys: DeviceKeyPair): Promise<void>;
+export declare function loadPendingSetupDeviceKeys(): Promise<DeviceKeyPair>;
+export declare function storePendingSetupRefreshToken(refreshToken: string): Promise<void>;
+export declare function getPendingSetupRefreshToken(): Promise<string | null>;
+export declare function clearPendingSetupSecretsFile(): Promise<void>;

package/dist/src/store/pending-setup-secrets.js

@@ -0,0 +1,73 @@
+import { chmod, mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { PENDING_SETUP_SECRETS_FILE, resolveStateRoot } from "../constants.js";
+function toB64(data) {
+    return Buffer.from(data).toString("base64");
+}
+function fromB64(data) {
+    return new Uint8Array(Buffer.from(data, "base64"));
+}
+function secretsPath() {
+    return join(resolveStateRoot(), PENDING_SETUP_SECRETS_FILE);
+}
+async function readFileState() {
+    try {
+        const raw = await readFile(secretsPath(), "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+async function writeFileState(state) {
+    const path = secretsPath();
+    await mkdir(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp.${Date.now()}`;
+    await writeFile(tmp, JSON.stringify(state, null, 2), { mode: 0o600 });
+    await rename(tmp, path);
+    await chmod(path, 0o600).catch(() => { });
+}
+export async function storePendingSetupDeviceKeys(deviceKeys) {
+    const existing = await readFileState();
+    await writeFileState({
+        version: 1,
+        ed25519_private_b64: toB64(deviceKeys.ed25519.privateKey),
+        ed25519_public_b64: toB64(deviceKeys.ed25519.publicKey),
+        x25519_private_b64: toB64(deviceKeys.x25519.privateKey),
+        x25519_public_b64: toB64(deviceKeys.x25519.publicKey),
+        refresh_token: existing?.refresh_token,
+    });
+}
+export async function loadPendingSetupDeviceKeys() {
+    const state = await readFileState();
+    if (!state) {
+        throw new Error("Pending setup secrets are missing. Start setup again to regenerate device authorization.");
+    }
+    return {
+        ed25519: {
+            privateKey: fromB64(state.ed25519_private_b64),
+            publicKey: fromB64(state.ed25519_public_b64),
+        },
+        x25519: {
+            privateKey: fromB64(state.x25519_private_b64),
+            publicKey: fromB64(state.x25519_public_b64),
+        },
+    };
+}
+export async function storePendingSetupRefreshToken(refreshToken) {
+    const state = await readFileState();
+    if (!state) {
+        throw new Error("Pending setup secrets are missing. Start setup again before storing the refresh token.");
+    }
+    await writeFileState({
+        ...state,
+        refresh_token: refreshToken,
+    });
+}
+export async function getPendingSetupRefreshToken() {
+    const state = await readFileState();
+    return state?.refresh_token ?? null;
+}
+export async function clearPendingSetupSecretsFile() {
+    await unlink(secretsPath()).catch(() => { });
+}

package/dist/src/store/session.d.ts

@@ -1,12 +1,28 @@
+import type { DeviceKeyPair } from "../crypto/device-keys.js";
 /**
  * In-memory vault session holding the unlocked AMK.
  * Exists for the lifetime of the gateway process.
  */
 export declare class VaultSession {
     private amk;
+    private deviceKeys;
+    private refreshToken;
+    private persistenceKey;
+    private persistenceSalt;
     isUnlocked(): boolean;
     getAMK(): Uint8Array;
-    unlock(amk: Uint8Array): void;
+    getDeviceKeys(): DeviceKeyPair;
+    getRefreshToken(): string;
+    updateRefreshToken(refreshToken: string): Promise<void>;
+    getPersistenceKey(): Uint8Array | null;
+    getPersistenceSalt(): Uint8Array | null;
+    unlock(params: {
+        amk: Uint8Array;
+        deviceKeys: DeviceKeyPair;
+        refreshToken: string;
+        persistenceKey?: Uint8Array;
+        persistenceSalt?: Uint8Array;
+    }): void;
     lock(): void;
 }
 /** Singleton session for the gateway process. */

package/dist/src/store/session.js

@@ -4,6 +4,10 @@
  */
 export class VaultSession {
     amk = null;
+    deviceKeys = null;
+    refreshToken = null;
+    persistenceKey = null;
+    persistenceSalt = null;
     isUnlocked() {
         return this.amk !== null;
     }
@@ -13,15 +17,76 @@ export class VaultSession {
         }
         return this.amk;
     }
-    unlock(amk) {
+    getDeviceKeys() {
+        if (!this.deviceKeys) {
+            throw new Error("Vault device keys are unavailable. Unlock the vault again or re-run setup.");
+        }
+        return {
+            ed25519: {
+                privateKey: new Uint8Array(this.deviceKeys.ed25519.privateKey),
+                publicKey: new Uint8Array(this.deviceKeys.ed25519.publicKey),
+            },
+            x25519: {
+                privateKey: new Uint8Array(this.deviceKeys.x25519.privateKey),
+                publicKey: new Uint8Array(this.deviceKeys.x25519.publicKey),
+            },
+        };
+    }
+    getRefreshToken() {
+        if (!this.refreshToken) {
+            throw new Error("Vault refresh token is unavailable. Unlock the vault again or re-run setup.");
+        }
+        return this.refreshToken;
+    }
+    async updateRefreshToken(refreshToken) {
+        this.refreshToken = refreshToken;
+    }
+    getPersistenceKey() {
+        return this.persistenceKey ? new Uint8Array(this.persistenceKey) : null;
+    }
+    getPersistenceSalt() {
+        return this.persistenceSalt ? new Uint8Array(this.persistenceSalt) : null;
+    }
+    unlock(params) {
         // Store a copy so the caller can zero their original
-        this.amk = new Uint8Array(amk);
+        this.amk = new Uint8Array(params.amk);
+        this.deviceKeys = {
+            ed25519: {
+                privateKey: new Uint8Array(params.deviceKeys.ed25519.privateKey),
+                publicKey: new Uint8Array(params.deviceKeys.ed25519.publicKey),
+            },
+            x25519: {
+                privateKey: new Uint8Array(params.deviceKeys.x25519.privateKey),
+                publicKey: new Uint8Array(params.deviceKeys.x25519.publicKey),
+            },
+        };
+        this.refreshToken = params.refreshToken;
+        this.persistenceKey = params.persistenceKey
+            ? new Uint8Array(params.persistenceKey)
+            : null;
+        this.persistenceSalt = params.persistenceSalt
+            ? new Uint8Array(params.persistenceSalt)
+            : null;
     }
     lock() {
         if (this.amk) {
             this.amk.fill(0);
             this.amk = null;
         }
+        if (this.deviceKeys) {
+            this.deviceKeys.ed25519.privateKey.fill(0);
+            this.deviceKeys.x25519.privateKey.fill(0);
+            this.deviceKeys = null;
+        }
+        this.refreshToken = null;
+        if (this.persistenceKey) {
+            this.persistenceKey.fill(0);
+            this.persistenceKey = null;
+        }
+        if (this.persistenceSalt) {
+            this.persistenceSalt.fill(0);
+            this.persistenceSalt = null;
+        }
     }
 }
 /** Singleton session for the gateway process. */

package/dist/src/store/vault-secrets.d.ts

@@ -0,0 +1,24 @@
+import type { DeviceKeyPair } from "../crypto/device-keys.js";
+export interface LoadedVaultSecrets {
+    amk: Uint8Array;
+    deviceKeys: DeviceKeyPair;
+    refreshToken: string;
+    persistenceKey: Uint8Array;
+    salt: Uint8Array;
+}
+export declare function hasPersistedVaultSecrets(): Promise<boolean>;
+export declare function persistVaultSecretsBundle(params: {
+    deviceKeys: DeviceKeyPair;
+    passphrase: string;
+    amk: Uint8Array;
+    refreshToken: string;
+}): Promise<void>;
+export declare function persistVaultSecretsWithKey(params: {
+    deviceKeys: DeviceKeyPair;
+    amk: Uint8Array;
+    refreshToken: string;
+    persistenceKey: Uint8Array;
+    salt: Uint8Array;
+}): Promise<void>;
+export declare function loadVaultSecretsWithPassphrase(passphrase: string): Promise<LoadedVaultSecrets | null>;
+export declare function deleteVaultSecretsFile(): Promise<void>;

package/dist/src/store/vault-secrets.js

@@ -0,0 +1,149 @@
+import { chmod, mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { decrypt, encrypt } from "../crypto/aes-gcm.js";
+import { deriveURK } from "../crypto/kdf.js";
+import { wrapAMK, unwrapAMK } from "../crypto/keys.js";
+import { VAULT_SECRETS_FILE, resolveStateRoot } from "../constants.js";
+function toB64(data) {
+    return Buffer.from(data).toString("base64");
+}
+function fromB64(data) {
+    return new Uint8Array(Buffer.from(data, "base64"));
+}
+function secretsPath() {
+    return join(resolveStateRoot(), VAULT_SECRETS_FILE);
+}
+async function writeFileState(state) {
+    const path = secretsPath();
+    await mkdir(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp.${Date.now()}`;
+    await writeFile(tmp, JSON.stringify(state, null, 2), { mode: 0o600 });
+    await rename(tmp, path);
+    await chmod(path, 0o600).catch(() => { });
+}
+async function readFileState() {
+    try {
+        const raw = await readFile(secretsPath(), "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+function serializePayload(params) {
+    return {
+        version: 1,
+        refresh_token: params.refreshToken,
+        wrapped_amk_b64: toB64(params.wrappedAmk.encrypted_amk),
+        wrapped_amk_iv_b64: toB64(params.wrappedAmk.iv),
+        wrapped_amk_tag_b64: toB64(params.wrappedAmk.tag),
+        ed25519_private_b64: toB64(params.deviceKeys.ed25519.privateKey),
+        ed25519_public_b64: toB64(params.deviceKeys.ed25519.publicKey),
+        x25519_private_b64: toB64(params.deviceKeys.x25519.privateKey),
+        x25519_public_b64: toB64(params.deviceKeys.x25519.publicKey),
+    };
+}
+async function persistPayload(params) {
+    const plaintext = new TextEncoder().encode(JSON.stringify(params.payload));
+    try {
+        const sealed = encrypt(params.urk, plaintext);
+        await writeFileState({
+            version: 1,
+            salt_b64: toB64(params.salt),
+            ciphertext_b64: toB64(sealed.ciphertext),
+            iv_b64: toB64(sealed.iv),
+            tag_b64: toB64(sealed.tag),
+        });
+    }
+    finally {
+        plaintext.fill(0);
+    }
+}
+function deserializePayload(params) {
+    const amk = unwrapAMK(params.urk, {
+        encrypted_amk: fromB64(params.payload.wrapped_amk_b64),
+        iv: fromB64(params.payload.wrapped_amk_iv_b64),
+        tag: fromB64(params.payload.wrapped_amk_tag_b64),
+    });
+    return {
+        amk,
+        refreshToken: params.payload.refresh_token,
+        deviceKeys: {
+            ed25519: {
+                privateKey: fromB64(params.payload.ed25519_private_b64),
+                publicKey: fromB64(params.payload.ed25519_public_b64),
+            },
+            x25519: {
+                privateKey: fromB64(params.payload.x25519_private_b64),
+                publicKey: fromB64(params.payload.x25519_public_b64),
+            },
+        },
+    };
+}
+export async function hasPersistedVaultSecrets() {
+    return (await readFileState()) !== null;
+}
+export async function persistVaultSecretsBundle(params) {
+    const { urk, salt } = await deriveURK(params.passphrase);
+    try {
+        const wrappedAmk = wrapAMK(urk, params.amk);
+        const payload = serializePayload({
+            deviceKeys: params.deviceKeys,
+            refreshToken: params.refreshToken,
+            wrappedAmk,
+        });
+        await persistPayload({
+            urk,
+            salt,
+            payload,
+        });
+    }
+    finally {
+        urk.fill(0);
+    }
+}
+export async function persistVaultSecretsWithKey(params) {
+    const wrappedAmk = wrapAMK(params.persistenceKey, params.amk);
+    const payload = serializePayload({
+        deviceKeys: params.deviceKeys,
+        refreshToken: params.refreshToken,
+        wrappedAmk,
+    });
+    await persistPayload({
+        urk: params.persistenceKey,
+        salt: params.salt,
+        payload,
+    });
+}
+export async function loadVaultSecretsWithPassphrase(passphrase) {
+    const state = await readFileState();
+    if (!state) {
+        return null;
+    }
+    const salt = fromB64(state.salt_b64);
+    const { urk } = await deriveURK(passphrase, salt);
+    try {
+        const plaintext = decrypt(urk, fromB64(state.ciphertext_b64), fromB64(state.iv_b64), fromB64(state.tag_b64));
+        try {
+            const payload = JSON.parse(new TextDecoder().decode(plaintext));
+            const loaded = deserializePayload({ payload, urk });
+            const persistenceKey = new Uint8Array(urk);
+            urk.fill(0);
+            return {
+                ...loaded,
+                persistenceKey,
+                salt: new Uint8Array(salt),
+            };
+        }
+        finally {
+            plaintext.fill(0);
+        }
+    }
+    catch {
+        urk.fill(0);
+        throw new Error("Wrong passphrase.");
+    }
+}
+export async function deleteVaultSecretsFile() {
+    await unlink(secretsPath()).catch(() => { });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@membox-cloud/membox",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -20,7 +20,7 @@
     "keytar": "^7.9.0"
   },
   "peerDependencies": {
-    "openclaw": ">=2026.3.7"
+    "openclaw": ">=2026.2.14"
   },
   "peerDependenciesMeta": {
     "openclaw": {