@membox-cloud/membox 0.1.0

package/dist/src/sync/diff.js

@@ -0,0 +1,75 @@
+function normalizeRemoteChangeType(changeType) {
+    return changeType === "delete" ? "delete" : "upsert";
+}
+/**
+ * Compute the diff between local files and remote changes.
+ * V0.1: conflicts (both sides changed) are flagged and skipped.
+ */
+export function computeSyncDiff(localFiles, remoteChanges, state) {
+    const diff = { toUpload: [], toDownload: [], conflicts: [] };
+    const latestRemoteChanges = new Map();
+    for (const change of remoteChanges) {
+        const existing = latestRemoteChanges.get(change.object_id);
+        if (!existing ||
+            change.version > existing.version ||
+            (change.version === existing.version && change.seq > existing.seq)) {
+            latestRemoteChanges.set(change.object_id, change);
+        }
+    }
+    const effectiveRemoteChanges = [...latestRemoteChanges.values()];
+    const remoteChangedObjectIds = new Set(effectiveRemoteChanges.map((c) => c.object_id));
+    // Check local files for changes since last sync
+    for (const [path, file] of localFiles) {
+        const existing = state.file_versions[path];
+        if (!existing) {
+            // New local file, upload it
+            diff.toUpload.push({ logicalPath: path, file });
+        }
+        else if (existing.content_sha256 !== file.sha256) {
+            // Local changed — check for conflict with remote
+            if (remoteChangedObjectIds.has(existing.object_id)) {
+                diff.conflicts.push({
+                    logicalPath: path,
+                    objectId: existing.object_id,
+                });
+            }
+            else {
+                diff.toUpload.push({
+                    logicalPath: path,
+                    file,
+                    existingObjectId: existing.object_id,
+                    existingVersion: existing.version,
+                });
+            }
+        }
+    }
+    // Check remote changes for new/updated objects to download
+    const conflictObjectIds = new Set(diff.conflicts.map((c) => c.objectId));
+    const uploadObjectIds = new Set(diff.toUpload.filter((u) => u.existingObjectId).map((u) => u.existingObjectId));
+    for (const change of effectiveRemoteChanges) {
+        // Skip if this object is already in conflicts or being uploaded
+        if (conflictObjectIds.has(change.object_id))
+            continue;
+        if (uploadObjectIds.has(change.object_id))
+            continue;
+        // Check if we already have this object locally
+        const localEntry = Object.entries(state.file_versions).find(([, v]) => v.object_id === change.object_id);
+        if (!localEntry) {
+            // New remote object we don't have
+            diff.toDownload.push({
+                objectId: change.object_id,
+                version: change.version,
+                changeType: normalizeRemoteChangeType(change.change_type),
+            });
+        }
+        else if (change.version > localEntry[1].version) {
+            // Remote has newer version and local hasn't changed
+            diff.toDownload.push({
+                objectId: change.object_id,
+                version: change.version,
+                changeType: normalizeRemoteChangeType(change.change_type),
+            });
+        }
+    }
+    return diff;
+}

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

@@ -0,0 +1,16 @@
+import type { MemboxApiClient } from "../api/client.js";
+/**
+ * Download and decrypt a synced object from the Membox service.
+ * Fetch manifest → download blobs → unwrap DEK → decrypt content → validate hash.
+ */
+export declare function downloadAndDecrypt(params: {
+    amk: Uint8Array;
+    objectId: string;
+    client: MemboxApiClient;
+    version?: number;
+}): Promise<{
+    logicalPath: string;
+    content: Uint8Array;
+    version: number;
+    fileKind: string;
+}>;

package/dist/src/sync/downloader.js

@@ -0,0 +1,73 @@
+import { unwrapDEK } from "../crypto/keys.js";
+import { decrypt } from "../crypto/aes-gcm.js";
+import { computeSha256Hex, serializeAad } from "../crypto/manifest.js";
+import { getManifest, downloadBlob } from "../api/sync.js";
+function fromB64(s) {
+    return new Uint8Array(Buffer.from(s, "base64"));
+}
+/**
+ * Download and decrypt a synced object from the Membox service.
+ * Fetch manifest → download blobs → unwrap DEK → decrypt content → validate hash.
+ */
+export async function downloadAndDecrypt(params) {
+    // Fetch manifest
+    const { manifest } = await getManifest(params.client, params.objectId, params.version);
+    const aadBytes = serializeAad(manifest.aad);
+    // Unwrap DEK from AMK
+    const dek = unwrapDEK(params.amk, {
+        encrypted_key: fromB64(manifest.dek_envelope.encrypted_dek_b64),
+        iv: fromB64(manifest.dek_envelope.iv_b64),
+        tag: fromB64(manifest.dek_envelope.tag_b64),
+    }, aadBytes);
+    try {
+        // Download and decrypt content blob
+        const contentBlobData = await downloadBlob(params.client, manifest.blob.blob_key);
+        const contentSealed = fromB64(contentBlobData.payload_b64);
+        // Verify blob-level integrity before decryption
+        const blobSha256 = computeSha256Hex(contentSealed);
+        if (contentBlobData.content_sha256 && blobSha256 !== contentBlobData.content_sha256) {
+            throw new Error(`Content blob hash mismatch (transport): expected ${contentBlobData.content_sha256}, got ${blobSha256}`);
+        }
+        // Cross-check: manifest.content_sha256 must also match the sealed blob
+        if (blobSha256 !== manifest.content_sha256) {
+            throw new Error(`Content blob hash mismatch (manifest): expected ${manifest.content_sha256}, got ${blobSha256}`);
+        }
+        const contentIv = fromB64(manifest.blob.iv_b64);
+        const contentTag = fromB64(manifest.blob.tag_b64);
+        // The sealed blob is ciphertext + tag; we need just ciphertext
+        const contentCiphertext = contentSealed.subarray(0, contentSealed.length - contentTag.length);
+        const content = decrypt(dek, contentCiphertext, contentIv, contentTag, aadBytes);
+        // Download and decrypt metadata blob
+        const metaBlobData = await downloadBlob(params.client, manifest.metadata.blob_key);
+        const metaSealed = fromB64(metaBlobData.payload_b64);
+        // Verify metadata blob integrity
+        const metaBlobSha256 = computeSha256Hex(metaSealed);
+        if (metaBlobData.content_sha256 && metaBlobSha256 !== metaBlobData.content_sha256) {
+            throw new Error(`Metadata blob hash mismatch (transport): expected ${metaBlobData.content_sha256}, got ${metaBlobSha256}`);
+        }
+        if (metaBlobSha256 !== manifest.metadata_sha256) {
+            throw new Error(`Metadata blob hash mismatch (manifest): expected ${manifest.metadata_sha256}, got ${metaBlobSha256}`);
+        }
+        const metaIv = fromB64(manifest.metadata.iv_b64);
+        const metaTag = fromB64(manifest.metadata.tag_b64);
+        const metaCiphertext = metaSealed.subarray(0, metaSealed.length - metaTag.length);
+        const metaPlain = decrypt(dek, metaCiphertext, metaIv, metaTag, aadBytes);
+        const metadata = JSON.parse(new TextDecoder().decode(metaPlain));
+        // Verify plaintext content hash against the value stored in encrypted metadata
+        if (metadata.content_sha256) {
+            const actualSha256 = computeSha256Hex(content);
+            if (actualSha256 !== metadata.content_sha256) {
+                throw new Error(`Content hash mismatch: expected ${metadata.content_sha256}, got ${actualSha256}`);
+            }
+        }
+        return {
+            logicalPath: metadata.logical_path,
+            content,
+            version: manifest.object_version,
+            fileKind: metadata.file_kind,
+        };
+    }
+    finally {
+        dek.fill(0);
+    }
+}

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

@@ -0,0 +1,12 @@
+export interface ScannedFile {
+    logicalPath: string;
+    absolutePath: string;
+    content: Uint8Array;
+    sha256: string;
+    fileKind: "memory_root" | "memory_daily";
+}
+/**
+ * Scan the workspace for memory files.
+ * Only returns MEMORY.md and memory/YYYY-MM-DD.md (V1 core coverage).
+ */
+export declare function scanLocalMemoryFiles(workspaceDir: string): Promise<Map<string, ScannedFile>>;

package/dist/src/sync/scanner.js

@@ -0,0 +1,52 @@
+import { readFile, readdir, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { computeSha256Hex } from "../crypto/manifest.js";
+import { MEMORY_ROOT_PATH, MEMORY_DAILY_PATTERN } from "../constants.js";
+/**
+ * Scan the workspace for memory files.
+ * Only returns MEMORY.md and memory/YYYY-MM-DD.md (V1 core coverage).
+ */
+export async function scanLocalMemoryFiles(workspaceDir) {
+    const result = new Map();
+    // MEMORY.md
+    const memoryPath = join(workspaceDir, MEMORY_ROOT_PATH);
+    try {
+        const content = new Uint8Array(await readFile(memoryPath));
+        result.set(MEMORY_ROOT_PATH, {
+            logicalPath: MEMORY_ROOT_PATH,
+            absolutePath: memoryPath,
+            content,
+            sha256: computeSha256Hex(content),
+            fileKind: "memory_root",
+        });
+    }
+    catch {
+        /* file doesn't exist yet — ok */
+    }
+    // memory/YYYY-MM-DD.md files
+    const memoryDir = join(workspaceDir, "memory");
+    try {
+        const entries = await readdir(memoryDir);
+        for (const entry of entries) {
+            const logicalPath = `memory/${entry}`;
+            if (!MEMORY_DAILY_PATTERN.test(logicalPath))
+                continue;
+            const absPath = join(memoryDir, entry);
+            const s = await stat(absPath);
+            if (!s.isFile())
+                continue;
+            const content = new Uint8Array(await readFile(absPath));
+            result.set(logicalPath, {
+                logicalPath,
+                absolutePath: absPath,
+                content,
+                sha256: computeSha256Hex(content),
+                fileKind: "memory_daily",
+            });
+        }
+    }
+    catch {
+        /* memory/ dir doesn't exist — ok */
+    }
+    return result;
+}

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

@@ -0,0 +1,4 @@
+import { type LocalState, type FileVersionEntry } from "../store/local-state.js";
+export declare function updateCursor(cursor: number): Promise<void>;
+export declare function updateFileVersion(path: string, entry: FileVersionEntry): Promise<void>;
+export declare function getState(): Promise<LocalState>;

package/dist/src/sync/state.js

@@ -0,0 +1,22 @@
+import { readState, writeState, } from "../store/local-state.js";
+export async function updateCursor(cursor) {
+    const state = await readState();
+    if (!state)
+        throw new Error("State not initialized");
+    state.sync_cursor = cursor;
+    await writeState(state);
+}
+export async function updateFileVersion(path, entry) {
+    const state = await readState();
+    if (!state)
+        throw new Error("State not initialized");
+    state.file_versions[path] = entry;
+    await writeState(state);
+}
+export async function getState() {
+    const state = await readState();
+    if (!state) {
+        throw new Error("Vault not set up. Run `openclaw membox setup` first.");
+    }
+    return state;
+}

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

@@ -0,0 +1,20 @@
+import type { MemboxApiClient } from "../api/client.js";
+/**
+ * Encrypt a local file and upload it to the Membox sync service.
+ * Full pipeline: genDEK → encrypt content → encrypt metadata → wrapDEK → buildManifest → upload blobs → commit.
+ */
+export declare function uploadFile(params: {
+    amk: Uint8Array;
+    content: Uint8Array;
+    logicalPath: string;
+    fileKind: "memory_root" | "memory_daily";
+    userId: string;
+    deviceId: string;
+    objectId?: string;
+    objectVersion?: number;
+    client: MemboxApiClient;
+}): Promise<{
+    objectId: string;
+    version: number;
+    seq: number;
+}>;

package/dist/src/sync/uploader.js

@@ -0,0 +1,86 @@
+import { randomUUID } from "node:crypto";
+import { generateDEK, wrapDEK } from "../crypto/keys.js";
+import { encrypt } from "../crypto/aes-gcm.js";
+import { buildManifest, computeSha256Hex, serializeAad } from "../crypto/manifest.js";
+import { uploadBlob, commitObject } from "../api/sync.js";
+function toB64(d) {
+    return Buffer.from(d).toString("base64");
+}
+/**
+ * Encrypt a local file and upload it to the Membox sync service.
+ * Full pipeline: genDEK → encrypt content → encrypt metadata → wrapDEK → buildManifest → upload blobs → commit.
+ */
+export async function uploadFile(params) {
+    const objectId = params.objectId ?? randomUUID();
+    const version = (params.objectVersion ?? 0) + 1;
+    const dek = generateDEK();
+    try {
+        const aad = {
+            user_id: params.userId,
+            object_id: objectId,
+            object_version: version,
+            created_by_device_id: params.deviceId,
+        };
+        const aadBytes = serializeAad(aad);
+        // Encrypt content blob
+        const contentResult = encrypt(dek, params.content, aadBytes);
+        const contentSealed = new Uint8Array([
+            ...contentResult.ciphertext,
+            ...contentResult.tag,
+        ]);
+        const contentSealedSha256 = computeSha256Hex(contentSealed);
+        const contentUpload = await uploadBlob(params.client, {
+            payload_b64: toB64(contentSealed),
+            content_sha256: contentSealedSha256,
+        });
+        // Encrypt metadata blob
+        const metadataPlain = new TextEncoder().encode(JSON.stringify({
+            logical_path: params.logicalPath,
+            file_kind: params.fileKind,
+            updated_at: new Date().toISOString(),
+            content_sha256: computeSha256Hex(params.content),
+        }));
+        const metaResult = encrypt(dek, metadataPlain, aadBytes);
+        const metaSealed = new Uint8Array([
+            ...metaResult.ciphertext,
+            ...metaResult.tag,
+        ]);
+        const metaSealedSha256 = computeSha256Hex(metaSealed);
+        const metaUpload = await uploadBlob(params.client, {
+            payload_b64: toB64(metaSealed),
+            content_sha256: metaSealedSha256,
+        });
+        // Wrap DEK with AMK
+        const dekEnvelope = wrapDEK(params.amk, dek, aadBytes);
+        // Build manifest
+        const manifest = buildManifest({
+            objectId,
+            objectVersion: version,
+            contentBlob: {
+                blob_key: contentUpload.blob_key,
+                iv_b64: toB64(contentResult.iv),
+                tag_b64: toB64(contentResult.tag),
+            },
+            metadataBlob: {
+                blob_key: metaUpload.blob_key,
+                iv_b64: toB64(metaResult.iv),
+                tag_b64: toB64(metaResult.tag),
+            },
+            dekEnvelope: {
+                encrypted_dek: dekEnvelope.encrypted_key,
+                iv: dekEnvelope.iv,
+                tag: dekEnvelope.tag,
+            },
+            aad,
+            ciphertextSize: contentResult.ciphertext.length,
+            contentSha256: contentSealedSha256,
+            metadataSha256: metaSealedSha256,
+        });
+        // Commit manifest
+        const commitResult = await commitObject(params.client, { manifest });
+        return { objectId: commitResult.object_id, version: commitResult.version, seq: commitResult.seq };
+    }
+    finally {
+        dek.fill(0);
+    }
+}

package/dist/src/tools/grants-approve-pending.d.ts

@@ -0,0 +1,17 @@
+export declare function createApprovePendingGrantsTool(): {
+    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/grants-approve-pending.js

@@ -0,0 +1,50 @@
+import { readState } from "../store/local-state.js";
+import { approvePendingGrants } from "../cli/grants.js";
+import { ensureVaultUnlocked } from "../cli/unlock.js";
+import { jsonResult } from "./result.js";
+export function createApprovePendingGrantsTool() {
+    return {
+        name: "membox_grants_approve_pending",
+        label: "Membox Approve Pending Grants",
+        description: "Approve pending trusted-device requests using the current unlocked vault session.",
+        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. Complete setup before approving trusted-device grants.",
+                });
+            }
+            if (!(await ensureVaultUnlocked({
+                allowPrompt: false,
+                announceSuccess: true,
+            }))) {
+                return jsonResult({
+                    error: true,
+                    message: "Vault is locked. Call `membox_unlock` with a local `passphrase_file`, or explicitly enable `membox_unlock_secret_enable` first.",
+                });
+            }
+            try {
+                const result = await approvePendingGrants();
+                return jsonResult({
+                    ok: true,
+                    ...result,
+                    message: result.total === 0
+                        ? "No pending trusted-device approvals."
+                        : `Grant approval complete. approved=${result.approved} skipped=${result.skipped}.`,
+                });
+            }
+            catch (err) {
+                return jsonResult({
+                    error: true,
+                    message: `Grant approval failed: ${err instanceof Error ? err.message : String(err)}`,
+                });
+            }
+        },
+    };
+}

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

@@ -0,0 +1,31 @@
+import type { ConflictStrategy } from "../sync/conflict.js";
+export declare function createPullTool(): {
+    name: string;
+    label: string;
+    description: string;
+    parameters: {
+        type: "object";
+        properties: {
+            preview: {
+                type: "boolean";
+                description: string;
+            };
+            on_conflict: {
+                type: "string";
+                enum: string[];
+                description: string;
+            };
+        };
+        additionalProperties: boolean;
+    };
+    execute(_toolCallId?: string, params?: {
+        preview?: boolean;
+        on_conflict?: ConflictStrategy;
+    }): Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        details: unknown;
+    }>;
+};

package/dist/src/tools/pull.js

@@ -0,0 +1,71 @@
+import { readState } from "../store/local-state.js";
+import { pullAction } from "../cli/pull.js";
+import { ensureVaultUnlocked } from "../cli/unlock.js";
+import { jsonResult } from "./result.js";
+export function createPullTool() {
+    return {
+        name: "membox_pull",
+        label: "Membox Vault Pull",
+        description: "Pull remote encrypted memory changes into the local workspace. Vault must already be unlocked.",
+        parameters: {
+            type: "object",
+            properties: {
+                preview: {
+                    type: "boolean",
+                    description: "When true, return a preview of pending downloads and conflicts without writing files.",
+                },
+                on_conflict: {
+                    type: "string",
+                    enum: ["local-wins", "remote-wins", "conflict-copy"],
+                    description: "Conflict strategy to apply when local and remote changes diverge.",
+                },
+            },
+            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 pulling remote memory.",
+                });
+            }
+            if (!(await ensureVaultUnlocked({
+                allowPrompt: false,
+                announceSuccess: true,
+            }))) {
+                return jsonResult({
+                    error: true,
+                    message: "Vault is locked. Call `membox_unlock` with a local `passphrase_file`, or explicitly enable `membox_unlock_secret_enable` first.",
+                });
+            }
+            try {
+                const result = await pullAction({
+                    preview: params?.preview,
+                    onConflict: params?.on_conflict,
+                });
+                if (result.status === "locked") {
+                    return jsonResult({
+                        error: true,
+                        message: result.message,
+                    });
+                }
+                return jsonResult({
+                    ok: true,
+                    ...result,
+                    message: result.status === "preview"
+                        ? "Pull preview complete."
+                        : result.status === "up_to_date"
+                            ? "Already up to date."
+                            : `Pull complete. ${result.downloaded} file(s) downloaded.`,
+                });
+            }
+            catch (err) {
+                return jsonResult({
+                    error: true,
+                    message: `Pull failed: ${err instanceof Error ? err.message : String(err)}`,
+                });
+            }
+        },
+    };
+}

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

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

package/dist/src/tools/restore.js

@@ -0,0 +1,96 @@
+import { readState } from "../store/local-state.js";
+import { authorizeDevice, pollPendingDeviceAuthorizationOnce, } from "../cli/bootstrap.js";
+import { restoreAuthorizedDeviceFromRecovery } from "../cli/restore.js";
+import { readSecretFile } from "./secret-file.js";
+import { jsonResult } from "./result.js";
+export function createRestoreTool(cfg) {
+    return {
+        name: "membox_restore",
+        label: "Membox Vault Restore",
+        description: "Restore vault access on a new machine using local recovery-code and passphrase files after browser authorization is complete.",
+        parameters: {
+            type: "object",
+            properties: {
+                recovery_code_file: {
+                    type: "string",
+                    description: "Path to a local file containing the recovery code.",
+                },
+                new_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.",
+                },
+            },
+            required: ["recovery_code_file", "new_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 pull/sync/status instead of restore.",
+                });
+            }
+            if (!params?.recovery_code_file || !params?.new_passphrase_file) {
+                return jsonResult({
+                    error: true,
+                    message: "Missing required parameters: `recovery_code_file` and `new_passphrase_file`.",
+                });
+            }
+            const authStatus = await pollPendingDeviceAuthorizationOnce(cfg);
+            if (authStatus.status === "not_started") {
+                return jsonResult({
+                    status: "not_started",
+                    error: true,
+                    message: "No authorized pending setup exists. Call `membox_setup_start`, send the verification link to the user, then poll with `membox_setup_poll` until authorization completes.",
+                });
+            }
+            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 restore can continue.",
+                });
+            }
+            if (authStatus.status === "denied" || authStatus.status === "expired") {
+                return jsonResult({
+                    status: authStatus.status,
+                    error: true,
+                    message: authStatus.message,
+                });
+            }
+            try {
+                const [{ value: recoveryCode, resolvedPath: recoveryCodePath }, { value: passphrase, resolvedPath: passphrasePath, }] = await Promise.all([
+                    readSecretFile(params.recovery_code_file, {
+                        label: "Recovery code",
+                        trimWhitespace: true,
+                    }),
+                    readSecretFile(params.new_passphrase_file, {
+                        label: "New passphrase",
+                        trimWhitespace: false,
+                    }),
+                ]);
+                const auth = await authorizeDevice(cfg);
+                const result = await restoreAuthorizedDeviceFromRecovery(cfg, auth, {
+                    recoveryCode,
+                    passphrase,
+                });
+                return jsonResult({
+                    ...result,
+                    recovery_code_file: recoveryCodePath,
+                    new_passphrase_file: passphrasePath,
+                });
+            }
+            catch (err) {
+                return jsonResult({
+                    error: true,
+                    message: `Restore failed: ${err instanceof Error ? err.message : String(err)}`,
+                });
+            }
+        },
+    };
+}