@membox-cloud/membox 0.1.0

package/dist/src/cli/pull.js

@@ -0,0 +1,142 @@
+import { writeFile, mkdir, rename } from "node:fs/promises";
+import { dirname, resolve, relative, isAbsolute } from "node:path";
+import { vaultSession } from "../store/session.js";
+import { getState } from "../sync/state.js";
+import { computeSyncDiff } from "../sync/diff.js";
+import { scanLocalMemoryFiles } from "../sync/scanner.js";
+import { downloadAndDecrypt } from "../sync/downloader.js";
+import { getSyncChanges } from "../api/sync.js";
+import { updateCursor, updateFileVersion } from "../sync/state.js";
+import { createAuthenticatedClient } from "./helpers.js";
+import { computeSha256Hex } from "../crypto/manifest.js";
+import { resolveConflict } from "../sync/conflict.js";
+import { ensureVaultUnlocked } from "./unlock.js";
+export async function pullAction(options) {
+    if (!(await ensureVaultUnlocked({ announceSuccess: true }))) {
+        return {
+            status: "locked",
+            message: "Vault is locked. Unlock it first with `openclaw membox unlock`.",
+        };
+    }
+    const amk = vaultSession.getAMK();
+    const state = await getState();
+    const client = await createAuthenticatedClient(state);
+    const remote = await getSyncChanges(client, state.sync_cursor);
+    if (remote.changes.length === 0) {
+        console.log("Already up to date.");
+        return {
+            status: "up_to_date",
+            cursor: state.sync_cursor,
+        };
+    }
+    const localFiles = await scanLocalMemoryFiles(process.cwd());
+    const diff = computeSyncDiff(localFiles, remote.changes, state);
+    const strategy = options?.onConflict ?? "conflict-copy";
+    // Preview mode: show what would happen without executing
+    if (options?.preview) {
+        // Build objectId → logicalPath lookup from known file versions
+        const objectToPath = new Map();
+        for (const [path, entry] of Object.entries(state.file_versions)) {
+            objectToPath.set(entry.object_id, path);
+        }
+        console.log("Pull preview:");
+        if (diff.toDownload.length > 0) {
+            console.log(`  ${diff.toDownload.length} file(s) to download:`);
+            for (const item of diff.toDownload) {
+                const label = item.changeType === "delete" ? "[delete]" : "[upsert]";
+                const name = objectToPath.get(item.objectId) ?? item.objectId;
+                console.log(`    ${label} ${name}`);
+            }
+        }
+        else {
+            console.log("  No files to download.");
+        }
+        if (diff.conflicts.length > 0) {
+            console.log(`  ${diff.conflicts.length} conflict(s) (strategy: ${strategy}):`);
+            for (const c of diff.conflicts) {
+                console.log(`    - ${c.logicalPath}`);
+            }
+        }
+        return {
+            status: "preview",
+            cursor: remote.cursor,
+            strategy,
+            toDownload: diff.toDownload.map((item) => ({
+                logicalPath: objectToPath.get(item.objectId) ?? item.objectId,
+                objectId: item.objectId,
+                version: item.version,
+                changeType: item.changeType,
+            })),
+            conflicts: diff.conflicts.map((item) => ({
+                logicalPath: item.logicalPath,
+                objectId: item.objectId,
+            })),
+        };
+    }
+    // Handle conflicts with chosen strategy
+    if (diff.conflicts.length > 0) {
+        console.log(`${diff.conflicts.length} conflict(s) detected (strategy: ${strategy}):`);
+        for (const c of diff.conflicts) {
+            const localFile = localFiles.get(c.logicalPath);
+            const existing = state.file_versions[c.logicalPath];
+            const result = await resolveConflict({
+                logicalPath: c.logicalPath,
+                objectId: c.objectId,
+                localFile,
+                existingVersion: existing?.version,
+            }, strategy, {
+                amk,
+                client,
+                userId: state.user_id,
+                deviceId: state.device_id,
+                workspaceDir: process.cwd(),
+            });
+            if (result.fileVersionUpdate) {
+                await updateFileVersion(result.fileVersionUpdate.path, result.fileVersionUpdate.entry);
+            }
+        }
+    }
+    let downloaded = 0;
+    const conflictsResolved = diff.conflicts.length;
+    const base = process.cwd();
+    for (const item of diff.toDownload) {
+        if (item.changeType === "delete") {
+            console.log(`  Tombstone for ${item.objectId} (skip local delete in V0.1)`);
+            continue;
+        }
+        console.log(`  Downloading ${item.objectId}...`);
+        const result = await downloadAndDecrypt({
+            amk,
+            objectId: item.objectId,
+            client,
+            version: item.version,
+        });
+        // Path traversal guard: ensure logicalPath stays within workspace
+        const outPath = resolve(base, result.logicalPath);
+        const rel = relative(base, outPath);
+        if (rel.startsWith("..") || isAbsolute(rel)) {
+            console.log(`  Skipping unsafe path: ${result.logicalPath}`);
+            continue;
+        }
+        await mkdir(dirname(outPath), { recursive: true });
+        // Atomic write: temp file then rename
+        const tmp = outPath + ".tmp." + Date.now();
+        await writeFile(tmp, result.content);
+        await rename(tmp, outPath);
+        console.log(`  -> ${result.logicalPath}`);
+        await updateFileVersion(result.logicalPath, {
+            object_id: item.objectId,
+            version: result.version,
+            content_sha256: computeSha256Hex(result.content),
+        });
+        downloaded++;
+    }
+    await updateCursor(remote.cursor);
+    console.log(`Pull complete. ${downloaded} file(s) downloaded.`);
+    return {
+        status: "ok",
+        cursor: remote.cursor,
+        downloaded,
+        conflictsResolved,
+    };
+}

package/dist/src/cli/restore.d.ts

@@ -0,0 +1,12 @@
+import type { memboxConfig } from "../config.js";
+import { type AuthorizedDeviceContext } from "./bootstrap.js";
+export declare function restoreAuthorizedDeviceFromRecovery(cfg: memboxConfig, auth: AuthorizedDeviceContext, params: {
+    recoveryCode: string;
+    passphrase: string;
+}): Promise<{
+    ok: boolean;
+    restored: boolean;
+    reason?: "no_recovery_bundle";
+    message: string;
+}>;
+export declare function restoreAction(cfg: memboxConfig): Promise<void>;

package/dist/src/cli/restore.js

@@ -0,0 +1,90 @@
+import { createInterface } from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+import { createInitialState, writeState } from "../store/local-state.js";
+import { readState } from "../store/local-state.js";
+import { downloadRecoveryBundle, getRecoveryStatus } from "../api/recovery.js";
+import { restoreFromRecoveryBundle } from "../crypto/recovery.js";
+import { computeSha256Hex } from "../crypto/manifest.js";
+import { vaultSession } from "../store/session.js";
+import { pullAction } from "./pull.js";
+import { readPassphraseWithConfirm } from "./passphrase-input.js";
+import { authorizeDevice, clearPendingSetupArtifacts, persistVaultSecrets, } from "./bootstrap.js";
+import { runWithProvisioningRollback } from "./provisioning.js";
+async function readRecoveryCode() {
+    const rl = createInterface({ input, output });
+    try {
+        const code = await rl.question("Recovery code: ");
+        return code.trim();
+    }
+    finally {
+        rl.close();
+    }
+}
+export async function restoreAuthorizedDeviceFromRecovery(cfg, auth, params) {
+    const recoveryStatus = await getRecoveryStatus(auth.client);
+    if (!recoveryStatus.has_recovery_bundle) {
+        return {
+            ok: false,
+            restored: false,
+            reason: "no_recovery_bundle",
+            message: "No recovery bundle is stored for this account. If another trusted device still has access, run `openclaw membox setup` on this device and approve the grant from the trusted device.",
+        };
+    }
+    return runWithProvisioningRollback(auth, async (markProvisioned) => {
+        const downloaded = await downloadRecoveryBundle(auth.client);
+        const bundleBytes = Buffer.from(downloaded.encrypted_payload_b64, "base64");
+        if (computeSha256Hex(bundleBytes) !== downloaded.payload_checksum) {
+            throw new Error("Downloaded recovery bundle checksum mismatch.");
+        }
+        const bundle = JSON.parse(bundleBytes.toString("utf-8"));
+        const amk = await restoreFromRecoveryBundle(params.recoveryCode, bundle);
+        try {
+            await persistVaultSecrets({
+                deviceKeys: auth.deviceKeys,
+                passphrase: params.passphrase,
+                amk,
+                refreshToken: auth.tokens.refresh_token,
+            });
+            const state = createInitialState({
+                serverUrl: cfg.serverUrl,
+                deviceId: auth.tokens.device_id,
+                deviceName: auth.deviceName,
+                userId: auth.account.user_id,
+            });
+            await writeState(state);
+            await clearPendingSetupArtifacts();
+            markProvisioned();
+            vaultSession.unlock(amk);
+            console.log("Recovery successful. Pulling encrypted memory...");
+            await pullAction({ onConflict: "conflict-copy" });
+            console.log("Restore complete! Vault is ready.");
+            return {
+                ok: true,
+                restored: true,
+                message: "Restore complete! Vault is ready.",
+            };
+        }
+        finally {
+            amk.fill(0);
+        }
+    });
+}
+export async function restoreAction(cfg) {
+    const existing = await readState();
+    if (existing?.setup_complete) {
+        console.log("Vault already set up. Use `openclaw membox status` to check.");
+        return;
+    }
+    const auth = await authorizeDevice(cfg);
+    console.log("\nRestore this device from your recovery bundle.");
+    const recoveryCode = await readRecoveryCode();
+    const passphrase = await readPassphraseWithConfirm("New vault passphrase: ");
+    const result = await restoreAuthorizedDeviceFromRecovery(cfg, auth, {
+        recoveryCode,
+        passphrase,
+    });
+    if (result.reason === "no_recovery_bundle") {
+        console.log("No recovery bundle is stored for this account.");
+        console.log("If another trusted device still has access, run `openclaw membox setup` on this device and approve the grant from the trusted device.");
+    }
+}

package/dist/src/cli/setup.d.ts

@@ -0,0 +1,17 @@
+import type { memboxConfig } from "../config.js";
+import type { DeviceSummary } from "../contract-types.js";
+import { authorizeDevice } from "./bootstrap.js";
+export declare function selectGrantCapableDevices(devices: DeviceSummary[], currentDeviceId: string): DeviceSummary[];
+export interface SetupCompletionResult {
+    initialMode: "upload" | "pull";
+    uploadedFiles: string[];
+    downloadedFiles: number;
+    recoveryCodeGenerated: boolean;
+    managedUnlockEnabled: boolean;
+}
+export declare function finishAuthorizedSetup(cfg: memboxConfig, auth: Awaited<ReturnType<typeof authorizeDevice>>, params: {
+    passphrase: string;
+    enableManagedUnlock?: boolean;
+    onRecoveryCode?: (recoveryCode: string) => Promise<void>;
+}): Promise<SetupCompletionResult>;
+export declare function setupAction(cfg: memboxConfig): Promise<void>;

package/dist/src/cli/setup.js

@@ -0,0 +1,209 @@
+import { writeState, createInitialState } from "../store/local-state.js";
+import { readState } from "../store/local-state.js";
+import { generateAMK } from "../crypto/keys.js";
+import { generateRecoveryCode, createRecoveryBundle, } from "../crypto/recovery.js";
+import { receiveDeviceGrant } from "../crypto/grant.js";
+import { requestGrant, getGrant, listDevices } from "../api/devices.js";
+import { getRecoveryStatus, uploadRecoveryMaterial, } from "../api/recovery.js";
+import { getSyncStatus } from "../api/sync.js";
+import { readPassphraseWithConfirm } from "./passphrase-input.js";
+import { vaultSession } from "../store/session.js";
+import { enableManagedUnlock } from "../store/managed-unlock.js";
+import { computeSha256Hex } from "../crypto/manifest.js";
+import { scanLocalMemoryFiles } from "../sync/scanner.js";
+import { uploadFile } from "../sync/uploader.js";
+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";
+export function selectGrantCapableDevices(devices, currentDeviceId) {
+    return devices.filter((device) => device.device_id !== currentDeviceId &&
+        device.status === "active" &&
+        device.grant_capable === true);
+}
+async function receiveApprovedGrant(params) {
+    const grantRequest = await requestGrant(params.client, params.deviceId);
+    const fallbackDeadline = Date.now() + 20 * 60 * 1000;
+    const deadline = Number.isFinite(Date.parse(grantRequest.expires_at))
+        ? Date.parse(grantRequest.expires_at)
+        : fallbackDeadline;
+    console.log("Trusted device approval required.");
+    console.log("On an existing unlocked device, run `openclaw membox grants approve-pending`.");
+    console.log("Waiting for device grant approval...");
+    while (Date.now() < deadline) {
+        await new Promise((resolve) => setTimeout(resolve, 2000));
+        const grant = await getGrant(params.client, grantRequest.grant_id);
+        if (grant.status === "pending") {
+            continue;
+        }
+        if (grant.status === "rejected") {
+            throw new Error("Trusted-device approval was rejected.");
+        }
+        if (grant.status === "expired") {
+            throw new Error("Trusted-device approval expired before it was approved.");
+        }
+        if (grant.status !== "approved") {
+            throw new Error(`Unexpected grant status: ${grant.status}`);
+        }
+        if (!grant.encrypted_grant_payload_b64 ||
+            !grant.grant_signature_b64 ||
+            !grant.source_device_sign_public_key_b64 ||
+            !grant.source_device_kex_public_key_b64) {
+            throw new Error("Approved grant response is missing encrypted payload or source device public keys.");
+        }
+        return receiveDeviceGrant({
+            targetXPrivateKey: params.deviceKeys.x25519.privateKey,
+            targetDeviceId: params.deviceId,
+            sourceKexPublicKey: fromB64(grant.source_device_kex_public_key_b64),
+            sourceSigningPublicKey: fromB64(grant.source_device_sign_public_key_b64),
+            payloadBytes: fromB64(grant.encrypted_grant_payload_b64),
+            signature: fromB64(grant.grant_signature_b64),
+        });
+    }
+    throw new Error("Timed out waiting for trusted-device approval.");
+}
+export async function finishAuthorizedSetup(cfg, auth, params) {
+    const recoveryStatus = await getRecoveryStatus(auth.client).catch(() => null);
+    const syncStatus = await getSyncStatus(auth.client).catch(() => null);
+    const devices = await listDevices(auth.client).catch(() => []);
+    const otherGrantCapableDevices = selectGrantCapableDevices(devices, auth.tokens.device_id);
+    let amk = null;
+    let initialMode = "upload";
+    try {
+        if (otherGrantCapableDevices.length > 0) {
+            amk = await receiveApprovedGrant({
+                client: auth.client,
+                deviceId: auth.tokens.device_id,
+                deviceKeys: auth.deviceKeys,
+            });
+            initialMode = "pull";
+        }
+        else if (recoveryStatus?.has_recovery_bundle) {
+            console.log("Recovery materials already exist for this account, but no active trusted device is available.");
+            console.log("Run `openclaw membox restore` on this device instead.");
+            throw new Error("Recovery materials already exist for this account, but no active trusted device is available. Use restore on this device instead.");
+        }
+        else if ((syncStatus?.object_count ?? 0) > 0) {
+            console.log("This account already has encrypted sync objects but no active trusted device or recovery bundle is available.");
+            console.log("Refusing to generate a new account master key because that would orphan existing server-side data.");
+            throw new Error("Encrypted sync objects already exist, but no active trusted device or recovery bundle is available. Refusing to generate a replacement account master key.");
+        }
+        else {
+            console.log("No existing vault detected. Creating a new account master key.");
+            amk = generateAMK();
+        }
+        await persistVaultSecrets({
+            deviceKeys: auth.deviceKeys,
+            passphrase: params.passphrase,
+            amk,
+            refreshToken: auth.tokens.refresh_token,
+        });
+        let recoveryCodeGenerated = false;
+        if (initialMode === "upload") {
+            if (!params.onRecoveryCode) {
+                throw new Error("First-device setup requires a local recovery-code destination so the recovery code can stay on the machine.");
+            }
+            console.log("\nGenerating recovery materials...");
+            const recoveryCode = generateRecoveryCode();
+            const bundle = await createRecoveryBundle(recoveryCode, amk);
+            const bundleBytes = new TextEncoder().encode(JSON.stringify(bundle));
+            await uploadRecoveryMaterial(auth.client, {
+                material_type: "recovery_bundle",
+                encrypted_payload_b64: toB64(bundleBytes),
+                payload_checksum: computeSha256Hex(bundleBytes),
+                algorithm: "aes-256-gcm",
+                crypto_version: 1,
+            });
+            await params.onRecoveryCode(recoveryCode);
+            recoveryCodeGenerated = true;
+        }
+        const state = createInitialState({
+            serverUrl: cfg.serverUrl,
+            deviceId: auth.tokens.device_id,
+            deviceName: auth.deviceName,
+            userId: auth.account.user_id,
+        });
+        if (params.enableManagedUnlock) {
+            state.managed_unlock_enabled = true;
+        }
+        await writeState(state);
+        if (params.enableManagedUnlock) {
+            await enableManagedUnlock(params.passphrase);
+        }
+        await clearPendingSetupArtifacts();
+        vaultSession.unlock(amk);
+        if (initialMode === "pull") {
+            console.log("Pulling existing encrypted memory...");
+            const pullResult = await pullAction({ onConflict: "conflict-copy" });
+            const downloadedFiles = pullResult.status === "ok" ? pullResult.downloaded : 0;
+            console.log("Setup complete! Existing vault material is now available.");
+            return {
+                initialMode,
+                uploadedFiles: [],
+                downloadedFiles,
+                recoveryCodeGenerated,
+                managedUnlockEnabled: params.enableManagedUnlock === true,
+            };
+        }
+        console.log("Running initial sync...");
+        const localFiles = await scanLocalMemoryFiles(process.cwd());
+        const uploadedFiles = [];
+        for (const [path, file] of localFiles) {
+            console.log(`  Uploading ${path}...`);
+            const result = await uploadFile({
+                amk,
+                content: file.content,
+                logicalPath: path,
+                fileKind: file.fileKind,
+                userId: state.user_id,
+                deviceId: state.device_id,
+                client: auth.client,
+            });
+            await updateFileVersion(path, {
+                object_id: result.objectId,
+                version: result.version,
+                content_sha256: file.sha256,
+            });
+            uploadedFiles.push(path);
+        }
+        console.log("Setup complete! Vault is ready.");
+        return {
+            initialMode,
+            uploadedFiles,
+            downloadedFiles: 0,
+            recoveryCodeGenerated,
+            managedUnlockEnabled: params.enableManagedUnlock === true,
+        };
+    }
+    finally {
+        amk?.fill(0);
+    }
+}
+export async function setupAction(cfg) {
+    const existing = await readState();
+    if (existing?.setup_complete) {
+        console.log("Vault already set up. Use `openclaw membox status` to check.");
+        return;
+    }
+    const auth = await authorizeDevice(cfg);
+    await runWithProvisioningRollback(auth, async (markProvisioned) => {
+        console.log("\nSet your vault passphrase (this encrypts your memory locally):");
+        console.log("Warning: This passphrase is NEVER sent to the server. If lost, use recovery materials.");
+        const passphrase = await readPassphraseWithConfirm("Vault passphrase: ");
+        const result = await finishAuthorizedSetup(cfg, auth, {
+            passphrase,
+            onRecoveryCode: async (recoveryCode) => {
+                console.log("\n========================================");
+                console.log("  SAVE YOUR RECOVERY CODE NOW!");
+                console.log("");
+                console.log(`  ${recoveryCode}`);
+                console.log("");
+                console.log("  Store it in a password manager or print.");
+                console.log("  Without it + passphrase, data is lost.");
+                console.log("========================================\n");
+            },
+        });
+        markProvisioned();
+        return result;
+    });
+}

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

@@ -0,0 +1 @@
+export declare function statusAction(): Promise<void>;

package/dist/src/cli/status.js

@@ -0,0 +1,31 @@
+import { readState } from "../store/local-state.js";
+import { vaultSession } from "../store/session.js";
+import { getManagedUnlockStatus } from "../store/managed-unlock.js";
+export async function statusAction() {
+    const state = await readState();
+    if (!state?.setup_complete) {
+        console.log("Membox Vault: not set up");
+        console.log("  Run `openclaw membox setup` to get started.");
+        return;
+    }
+    const fileCount = Object.keys(state.file_versions).length;
+    const managedUnlock = await getManagedUnlockStatus();
+    console.log("Membox Vault Status");
+    console.log("-------------------");
+    console.log(`  Server:    ${state.server_url}`);
+    console.log(`  Device:    ${state.device_name} (${state.device_id.slice(0, 8)}...)`);
+    console.log(`  User:      ${state.user_id.slice(0, 8)}...`);
+    console.log(`  Unlocked:  ${vaultSession.isUnlocked() ? "yes" : "no"}`);
+    console.log(`  Managed:   ${managedUnlock.enabled
+        ? managedUnlock.secret_present
+            ? "enabled"
+            : "enabled (secret missing)"
+        : "disabled"}`);
+    console.log(`  Cursor:    ${state.sync_cursor}`);
+    console.log(`  Files:     ${fileCount}`);
+    if (fileCount > 0) {
+        for (const [path, v] of Object.entries(state.file_versions)) {
+            console.log(`    ${path} (v${v.version})`);
+        }
+    }
+}

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

@@ -0,0 +1,4 @@
+import { type ConflictStrategy } from "../sync/conflict.js";
+export declare function syncAction(options?: {
+    onConflict?: ConflictStrategy;
+}): Promise<void>;

package/dist/src/cli/sync.js

@@ -0,0 +1,124 @@
+import { writeFile, mkdir, rename } from "node:fs/promises";
+import { dirname, resolve, relative, isAbsolute } from "node:path";
+import { vaultSession } from "../store/session.js";
+import { getState } from "../sync/state.js";
+import { scanLocalMemoryFiles } from "../sync/scanner.js";
+import { computeSyncDiff } from "../sync/diff.js";
+import { uploadFile } from "../sync/uploader.js";
+import { downloadAndDecrypt } from "../sync/downloader.js";
+import { getSyncChanges } from "../api/sync.js";
+import { updateCursor, updateFileVersion } from "../sync/state.js";
+import { createAuthenticatedClient } from "./helpers.js";
+import { computeSha256Hex } from "../crypto/manifest.js";
+import { readState, writeState } from "../store/local-state.js";
+import { resolveConflict } from "../sync/conflict.js";
+import { ensureVaultUnlocked } from "./unlock.js";
+function isSafePath(base, logicalPath) {
+    const resolved = resolve(base, logicalPath);
+    const rel = relative(base, resolved);
+    return !rel.startsWith("..") && !isAbsolute(rel);
+}
+export async function syncAction(options) {
+    if (!(await ensureVaultUnlocked({ announceSuccess: true }))) {
+        return;
+    }
+    const amk = vaultSession.getAMK();
+    const state = await getState();
+    const client = await createAuthenticatedClient(state);
+    // Scan local files
+    const localFiles = await scanLocalMemoryFiles(process.cwd());
+    console.log(`Scanned ${localFiles.size} local memory files.`);
+    // Check remote changes
+    const remote = await getSyncChanges(client, state.sync_cursor);
+    const diff = computeSyncDiff(localFiles, remote.changes, state);
+    const strategy = options?.onConflict ?? "conflict-copy";
+    // Handle conflicts with chosen strategy
+    if (diff.conflicts.length > 0) {
+        console.log(`${diff.conflicts.length} conflict(s) detected (strategy: ${strategy}):`);
+        for (const c of diff.conflicts) {
+            const localFile = localFiles.get(c.logicalPath);
+            const existing = state.file_versions[c.logicalPath];
+            const result = await resolveConflict({
+                logicalPath: c.logicalPath,
+                objectId: c.objectId,
+                localFile,
+                existingVersion: existing?.version,
+            }, strategy, {
+                amk,
+                client,
+                userId: state.user_id,
+                deviceId: state.device_id,
+                workspaceDir: process.cwd(),
+            });
+            if (result.fileVersionUpdate) {
+                await updateFileVersion(result.fileVersionUpdate.path, result.fileVersionUpdate.entry);
+            }
+        }
+    }
+    // Upload changed files
+    for (const item of diff.toUpload) {
+        console.log(`  Uploading ${item.logicalPath}...`);
+        const result = await uploadFile({
+            amk,
+            content: item.file.content,
+            logicalPath: item.logicalPath,
+            fileKind: item.file.fileKind,
+            userId: state.user_id,
+            deviceId: state.device_id,
+            objectId: item.existingObjectId,
+            objectVersion: item.existingVersion,
+            client,
+        });
+        await updateFileVersion(item.logicalPath, {
+            object_id: result.objectId,
+            version: result.version,
+            content_sha256: item.file.sha256,
+        });
+    }
+    // Download remote changes
+    let downloaded = 0;
+    const base = process.cwd();
+    for (const item of diff.toDownload) {
+        if (item.changeType === "delete") {
+            console.log(`  Tombstone for ${item.objectId} (skip local delete in V0.1)`);
+            continue;
+        }
+        console.log(`  Downloading ${item.objectId}...`);
+        const result = await downloadAndDecrypt({
+            amk,
+            objectId: item.objectId,
+            client,
+            version: item.version,
+        });
+        if (!isSafePath(base, result.logicalPath)) {
+            console.log(`  Skipping unsafe path: ${result.logicalPath}`);
+            continue;
+        }
+        const outPath = resolve(base, result.logicalPath);
+        await mkdir(dirname(outPath), { recursive: true });
+        const tmp = outPath + ".tmp." + Date.now();
+        await writeFile(tmp, result.content);
+        await rename(tmp, outPath);
+        console.log(`  -> ${result.logicalPath}`);
+        await updateFileVersion(result.logicalPath, {
+            object_id: item.objectId,
+            version: result.version,
+            content_sha256: computeSha256Hex(result.content),
+        });
+        downloaded++;
+    }
+    await updateCursor(remote.cursor);
+    // Update last_sync_at timestamp
+    const currentState = await readState();
+    if (currentState) {
+        currentState.last_sync_at = new Date().toISOString();
+        await writeState(currentState);
+    }
+    const uploaded = diff.toUpload.length;
+    if (uploaded === 0 && downloaded === 0 && diff.conflicts.length === 0) {
+        console.log("Already up to date.");
+    }
+    else {
+        console.log(`Sync complete. ${uploaded} uploaded, ${downloaded} downloaded, ${diff.conflicts.length} conflict(s) resolved.`);
+    }
+}

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

@@ -0,0 +1,19 @@
+export declare function unlockWithPassphrase(passphrase: string, options?: {
+    announceSuccess?: boolean;
+    announceFailure?: boolean;
+    announceDeriving?: boolean;
+}): Promise<boolean>;
+export declare function tryManagedUnlock(options?: {
+    announceDeriving?: boolean;
+    announceSuccess?: boolean;
+    announceFailure?: boolean;
+}): Promise<boolean>;
+export declare function ensureVaultUnlocked(options?: {
+    announceAlreadyUnlocked?: boolean;
+    announceSuccess?: boolean;
+    allowPrompt?: boolean;
+    allowManagedUnlock?: boolean;
+}): Promise<boolean>;
+export declare function unlockAction(): Promise<void>;
+export declare function enableManagedUnlockAction(passphrase: string): Promise<void>;
+export declare function disableManagedUnlockAction(): Promise<void>;