@membox-cloud/membox 0.1.0

package/dist/src/crypto/device-keys.js

@@ -0,0 +1,25 @@
+import { ed25519, x25519 } from "@noble/curves/ed25519";
+import { randomBytes } from "@noble/hashes/utils";
+/** Generate a fresh device key pair (Ed25519 for signing, X25519 for KEX). */
+export function generateDeviceKeyPair() {
+    const edPriv = randomBytes(32);
+    const edPub = ed25519.getPublicKey(edPriv);
+    const xPriv = randomBytes(32);
+    const xPub = x25519.getPublicKey(xPriv);
+    return {
+        ed25519: { publicKey: edPub, privateKey: edPriv },
+        x25519: { publicKey: xPub, privateKey: xPriv },
+    };
+}
+/** Sign a message with Ed25519. */
+export function sign(privateKey, message) {
+    return ed25519.sign(message, privateKey);
+}
+/** Verify an Ed25519 signature. */
+export function verify(publicKey, message, signature) {
+    return ed25519.verify(signature, message, publicKey);
+}
+/** Compute X25519 shared secret for key exchange. */
+export function computeSharedSecret(privateKey, publicKey) {
+    return x25519.getSharedSecret(privateKey, publicKey);
+}

package/dist/src/crypto/grant.d.ts

@@ -0,0 +1,29 @@
+import type { DeviceGrantPayload } from "./types.js";
+/**
+ * Create a device grant: encrypt AMK for the target device using X25519 shared secret,
+ * and sign the payload with the source device's Ed25519 key.
+ */
+export declare function createDeviceGrant(params: {
+    sourceEdPrivateKey: Uint8Array;
+    sourceXPrivateKey: Uint8Array;
+    sourceDeviceId: string;
+    targetDeviceId: string;
+    targetKexPublicKey: Uint8Array;
+    amk: Uint8Array;
+}): {
+    payload: DeviceGrantPayload;
+    payloadBytes: Uint8Array;
+    signature: Uint8Array;
+};
+/**
+ * Receive and decrypt a device grant from a source device.
+ * Verifies signature, validates grant fields, then decrypts the AMK.
+ */
+export declare function receiveDeviceGrant(params: {
+    targetXPrivateKey: Uint8Array;
+    targetDeviceId: string;
+    sourceKexPublicKey: Uint8Array;
+    sourceSigningPublicKey: Uint8Array;
+    payloadBytes: Uint8Array;
+    signature: Uint8Array;
+}): Uint8Array;

package/dist/src/crypto/grant.js

@@ -0,0 +1,87 @@
+import { sha256 } from "@noble/hashes/sha256";
+import { computeSharedSecret, sign, verify } from "./device-keys.js";
+import { encrypt, decrypt } from "./aes-gcm.js";
+import { CRYPTO_VERSION } from "../constants.js";
+function toB64(d) {
+    return Buffer.from(d).toString("base64");
+}
+function fromB64(s) {
+    return new Uint8Array(Buffer.from(s, "base64"));
+}
+/**
+ * Create a device grant: encrypt AMK for the target device using X25519 shared secret,
+ * and sign the payload with the source device's Ed25519 key.
+ */
+export function createDeviceGrant(params) {
+    // Derive encryption key from X25519 shared secret
+    const shared = computeSharedSecret(params.sourceXPrivateKey, params.targetKexPublicKey);
+    // Guard against low-order X25519 points (all-zero shared secret)
+    if (shared.every((b) => b === 0)) {
+        throw new Error("X25519 shared secret is all-zero (invalid public key)");
+    }
+    const derivedKey = sha256(shared);
+    // Encrypt AMK with derived key
+    const { ciphertext, iv, tag } = encrypt(derivedKey, params.amk);
+    const now = new Date();
+    const expires = new Date(now.getTime() + 20 * 60 * 1000); // 20 min TTL
+    const payload = {
+        version: 1,
+        grant_type: "amk_transfer",
+        crypto_version: CRYPTO_VERSION,
+        source_device_id: params.sourceDeviceId,
+        target_device_id: params.targetDeviceId,
+        target_device_kex_public_key_b64: toB64(params.targetKexPublicKey),
+        encrypted_amk_b64: toB64(new Uint8Array([...ciphertext, ...tag])),
+        shared_secret_salt_b64: toB64(iv),
+        created_at: now.toISOString(),
+        expires_at: expires.toISOString(),
+    };
+    const payloadBytes = new TextEncoder().encode(JSON.stringify(payload));
+    const signature = sign(params.sourceEdPrivateKey, payloadBytes);
+    // Zero shared secret
+    derivedKey.fill(0);
+    shared.fill(0);
+    return { payload, payloadBytes, signature };
+}
+/**
+ * Receive and decrypt a device grant from a source device.
+ * Verifies signature, validates grant fields, then decrypts the AMK.
+ */
+export function receiveDeviceGrant(params) {
+    // Verify signature first
+    if (!verify(params.sourceSigningPublicKey, params.payloadBytes, params.signature)) {
+        throw new Error("Device grant signature verification failed");
+    }
+    const payload = JSON.parse(new TextDecoder().decode(params.payloadBytes));
+    // Validate grant fields to prevent replay/misdirection
+    if (payload.target_device_id !== params.targetDeviceId) {
+        throw new Error("Device grant target_device_id mismatch");
+    }
+    if (payload.crypto_version !== CRYPTO_VERSION) {
+        throw new Error(`Unsupported grant crypto_version: ${payload.crypto_version}`);
+    }
+    if (new Date(payload.expires_at).getTime() < Date.now()) {
+        throw new Error("Device grant has expired");
+    }
+    // Derive same shared secret using target's private key + source's public key
+    const shared = computeSharedSecret(params.targetXPrivateKey, params.sourceKexPublicKey);
+    // Guard against low-order X25519 points (all-zero shared secret)
+    if (shared.every((b) => b === 0)) {
+        throw new Error("X25519 shared secret is all-zero (invalid public key)");
+    }
+    const derivedKey = sha256(shared);
+    // Decrypt AMK
+    const encryptedData = fromB64(payload.encrypted_amk_b64);
+    const iv = fromB64(payload.shared_secret_salt_b64);
+    // The encrypted AMK includes ciphertext + tag appended
+    const tagLength = 16;
+    const ciphertext = encryptedData.subarray(0, encryptedData.length - tagLength);
+    const tag = encryptedData.subarray(encryptedData.length - tagLength);
+    try {
+        return decrypt(derivedKey, ciphertext, iv, tag);
+    }
+    finally {
+        derivedKey.fill(0);
+        shared.fill(0);
+    }
+}

package/dist/src/crypto/kdf.d.ts

@@ -0,0 +1,16 @@
+export interface KdfResult {
+    urk: Uint8Array;
+    salt: Uint8Array;
+}
+export interface KdfParams {
+    memoryKib: number;
+    iterations: number;
+    parallelism: number;
+    saltLength?: number;
+    outputLength?: number;
+}
+/**
+ * Derive URK (Unwrap Root Key) from a passphrase using Argon2id.
+ * If no salt is provided, a fresh random salt is generated.
+ */
+export declare function deriveURK(passphrase: string, existingSalt?: Uint8Array, params?: Partial<KdfParams>): Promise<KdfResult>;

package/dist/src/crypto/kdf.js

@@ -0,0 +1,24 @@
+import { argon2id } from "hash-wasm";
+import { randomBytes } from "@noble/hashes/utils";
+import { ARGON2_PARAMS } from "../constants.js";
+/**
+ * Derive URK (Unwrap Root Key) from a passphrase using Argon2id.
+ * If no salt is provided, a fresh random salt is generated.
+ */
+export async function deriveURK(passphrase, existingSalt, params) {
+    const effective = {
+        ...ARGON2_PARAMS,
+        ...params,
+    };
+    const salt = existingSalt ?? randomBytes(effective.saltLength);
+    const hash = await argon2id({
+        password: passphrase,
+        salt,
+        parallelism: effective.parallelism,
+        iterations: effective.iterations,
+        memorySize: effective.memoryKib,
+        hashLength: effective.outputLength,
+        outputType: "binary",
+    });
+    return { urk: new Uint8Array(hash), salt };
+}

package/dist/src/crypto/keys.d.ts

@@ -0,0 +1,14 @@
+import { type KeyEnvelope } from "./aes-gcm.js";
+import type { WrappedAMKBundle } from "./types.js";
+/** Generate a new Account Master Key (32 random bytes). */
+export declare function generateAMK(): Uint8Array;
+/** Generate a new Data Encryption Key (32 random bytes). */
+export declare function generateDEK(): Uint8Array;
+/** Wrap AMK with URK using AES-256-GCM. */
+export declare function wrapAMK(urk: Uint8Array, amk: Uint8Array): WrappedAMKBundle;
+/** Unwrap AMK from URK-protected bundle. Throws on wrong passphrase. */
+export declare function unwrapAMK(urk: Uint8Array, bundle: WrappedAMKBundle): Uint8Array;
+/** Wrap DEK with AMK using AES-256-GCM + AAD. */
+export declare function wrapDEK(amk: Uint8Array, dek: Uint8Array, aad: Uint8Array): KeyEnvelope;
+/** Unwrap DEK from AMK-protected envelope. Throws on wrong key. */
+export declare function unwrapDEK(amk: Uint8Array, envelope: KeyEnvelope, aad: Uint8Array): Uint8Array;

package/dist/src/crypto/keys.js

@@ -0,0 +1,35 @@
+import { randomBytes } from "@noble/hashes/utils";
+import { wrapKey, unwrapKey } from "./aes-gcm.js";
+/** Generate a new Account Master Key (32 random bytes). */
+export function generateAMK() {
+    return randomBytes(32);
+}
+/** Generate a new Data Encryption Key (32 random bytes). */
+export function generateDEK() {
+    return randomBytes(32);
+}
+/** Wrap AMK with URK using AES-256-GCM. */
+export function wrapAMK(urk, amk) {
+    const envelope = wrapKey(urk, amk);
+    return {
+        encrypted_amk: envelope.encrypted_key,
+        iv: envelope.iv,
+        tag: envelope.tag,
+    };
+}
+/** Unwrap AMK from URK-protected bundle. Throws on wrong passphrase. */
+export function unwrapAMK(urk, bundle) {
+    return unwrapKey(urk, {
+        encrypted_key: bundle.encrypted_amk,
+        iv: bundle.iv,
+        tag: bundle.tag,
+    });
+}
+/** Wrap DEK with AMK using AES-256-GCM + AAD. */
+export function wrapDEK(amk, dek, aad) {
+    return wrapKey(amk, dek, aad);
+}
+/** Unwrap DEK from AMK-protected envelope. Throws on wrong key. */
+export function unwrapDEK(amk, envelope, aad) {
+    return unwrapKey(amk, envelope, aad);
+}

package/dist/src/crypto/manifest.d.ts

@@ -0,0 +1,25 @@
+import type { EncryptedObjectManifest, AadDescriptor, BlobRef } from "../contract-types.js";
+export interface ManifestInput {
+    objectId: string;
+    objectVersion: number;
+    contentBlob: BlobRef;
+    metadataBlob: BlobRef;
+    dekEnvelope: {
+        encrypted_dek: Uint8Array;
+        iv: Uint8Array;
+        tag: Uint8Array;
+    };
+    aad: AadDescriptor;
+    ciphertextSize: number;
+    contentSha256: string;
+    metadataSha256: string;
+}
+/** Build an EncryptedObjectManifest matching the shared contract schema. */
+export declare function buildManifest(input: ManifestInput): EncryptedObjectManifest;
+/** Compute SHA-256 hex digest of binary data. */
+export declare function computeSha256Hex(data: Uint8Array): string;
+/**
+ * Serialize AAD descriptor to bytes for use as AES-GCM additional data.
+ * Keys are sorted alphabetically for cross-implementation canonical encoding.
+ */
+export declare function serializeAad(aad: AadDescriptor): Uint8Array;

package/dist/src/crypto/manifest.js

@@ -0,0 +1,41 @@
+import { sha256 } from "@noble/hashes/sha256";
+import { bytesToHex } from "@noble/hashes/utils";
+import { MANIFEST_VERSION, CIPHER_ALGORITHM, WRAP_ALGORITHM, CRYPTO_VERSION, } from "../constants.js";
+function toB64(data) {
+    return Buffer.from(data).toString("base64");
+}
+/** Build an EncryptedObjectManifest matching the shared contract schema. */
+export function buildManifest(input) {
+    return {
+        manifest_version: MANIFEST_VERSION,
+        cipher_algorithm: CIPHER_ALGORITHM,
+        wrap_algorithm: WRAP_ALGORITHM,
+        object_id: input.objectId,
+        object_version: input.objectVersion,
+        ciphertext_size: input.ciphertextSize,
+        content_sha256: input.contentSha256,
+        metadata_sha256: input.metadataSha256,
+        blob: input.contentBlob,
+        metadata: input.metadataBlob,
+        dek_envelope: {
+            version: CRYPTO_VERSION,
+            algorithm: CIPHER_ALGORITHM,
+            wrapped_for: "amk",
+            encrypted_dek_b64: toB64(input.dekEnvelope.encrypted_dek),
+            iv_b64: toB64(input.dekEnvelope.iv),
+            tag_b64: toB64(input.dekEnvelope.tag),
+        },
+        aad: input.aad,
+    };
+}
+/** Compute SHA-256 hex digest of binary data. */
+export function computeSha256Hex(data) {
+    return bytesToHex(sha256(data));
+}
+/**
+ * Serialize AAD descriptor to bytes for use as AES-GCM additional data.
+ * Keys are sorted alphabetically for cross-implementation canonical encoding.
+ */
+export function serializeAad(aad) {
+    return new TextEncoder().encode(JSON.stringify(aad, Object.keys(aad).sort()));
+}

package/dist/src/crypto/recovery.d.ts

@@ -0,0 +1,16 @@
+import type { RecoveryBundle } from "./types.js";
+/**
+ * Generate a high-entropy 24-character recovery code.
+ * Avoids ambiguous characters (0, O, 1, l, I).
+ */
+export declare function generateRecoveryCode(): string;
+/**
+ * Create a recovery bundle that wraps the AMK with a key derived from the recovery code.
+ */
+export declare function createRecoveryBundle(recoveryCode: string, amk: Uint8Array): Promise<RecoveryBundle>;
+/**
+ * Restore AMK from a recovery bundle using the recovery code.
+ * Validates checksum before attempting decryption.
+ * Throws on wrong code (AES-GCM auth failure) or tampered bundle.
+ */
+export declare function restoreFromRecoveryBundle(recoveryCode: string, bundle: RecoveryBundle): Promise<Uint8Array>;

package/dist/src/crypto/recovery.js

@@ -0,0 +1,94 @@
+import { randomBytes, bytesToHex } from "@noble/hashes/utils";
+import { sha256 } from "@noble/hashes/sha256";
+import { deriveURK } from "./kdf.js";
+import { encrypt, decrypt } from "./aes-gcm.js";
+import { ARGON2_PARAMS } from "../constants.js";
+function toB64(d) {
+    return Buffer.from(d).toString("base64");
+}
+function fromB64(s) {
+    return new Uint8Array(Buffer.from(s, "base64"));
+}
+function readBundleKdfParams(bundle) {
+    if (bundle.bundle_type !== "amk_recovery") {
+        throw new Error(`Unsupported recovery bundle type: ${bundle.bundle_type}`);
+    }
+    if (bundle.wrap_algorithm !== "aes-256-gcm") {
+        throw new Error(`Unsupported recovery wrap algorithm: ${bundle.wrap_algorithm}`);
+    }
+    if (bundle.kdf_algorithm !== "argon2id") {
+        throw new Error(`Unsupported recovery KDF: ${bundle.kdf_algorithm}`);
+    }
+    return {
+        memoryKib: bundle.kdf_params.memory_kib,
+        iterations: bundle.kdf_params.iterations,
+        parallelism: bundle.kdf_params.parallelism,
+    };
+}
+/**
+ * Generate a high-entropy 24-character recovery code.
+ * Avoids ambiguous characters (0, O, 1, l, I).
+ */
+export function generateRecoveryCode() {
+    const chars = "ABCDEFGHJKLMNPQRSTUVWXYZabcdefghjkmnpqrstuvwxyz23456789";
+    const bytes = randomBytes(24);
+    return Array.from(bytes)
+        .map((b) => chars[b % chars.length])
+        .join("");
+}
+/**
+ * Create a recovery bundle that wraps the AMK with a key derived from the recovery code.
+ */
+export async function createRecoveryBundle(recoveryCode, amk) {
+    const { urk: recoveryKey, salt } = await deriveURK(recoveryCode);
+    const { ciphertext, iv, tag } = encrypt(recoveryKey, amk);
+    // Checksum covers the encrypted payload for integrity
+    const payload = new Uint8Array([
+        ...ciphertext,
+        ...iv,
+        ...tag,
+    ]);
+    // Zero recovery key after use
+    recoveryKey.fill(0);
+    return {
+        version: 1,
+        bundle_type: "amk_recovery",
+        wrap_algorithm: "aes-256-gcm",
+        kdf_algorithm: "argon2id",
+        kdf_params: {
+            memory_kib: ARGON2_PARAMS.memoryKib,
+            iterations: ARGON2_PARAMS.iterations,
+            parallelism: ARGON2_PARAMS.parallelism,
+            salt_b64: toB64(salt),
+        },
+        encrypted_amk_b64: toB64(ciphertext),
+        iv_b64: toB64(iv),
+        tag_b64: toB64(tag),
+        checksum_sha256: bytesToHex(sha256(payload)),
+        created_at: new Date().toISOString(),
+    };
+}
+/**
+ * Restore AMK from a recovery bundle using the recovery code.
+ * Validates checksum before attempting decryption.
+ * Throws on wrong code (AES-GCM auth failure) or tampered bundle.
+ */
+export async function restoreFromRecoveryBundle(recoveryCode, bundle) {
+    // Validate checksum integrity before spending time on KDF
+    const ciphertext = fromB64(bundle.encrypted_amk_b64);
+    const iv = fromB64(bundle.iv_b64);
+    const tag = fromB64(bundle.tag_b64);
+    const payload = new Uint8Array([...ciphertext, ...iv, ...tag]);
+    const actualChecksum = bytesToHex(sha256(payload));
+    if (actualChecksum !== bundle.checksum_sha256) {
+        throw new Error("Recovery bundle checksum mismatch — data may be corrupted");
+    }
+    const salt = fromB64(bundle.kdf_params.salt_b64);
+    const { urk: recoveryKey } = await deriveURK(recoveryCode, salt, readBundleKdfParams(bundle));
+    try {
+        return decrypt(recoveryKey, ciphertext, iv, tag);
+    }
+    finally {
+        recoveryKey.fill(0);
+    }
+}

package/dist/src/crypto/types.d.ts

@@ -0,0 +1,34 @@
+export interface WrappedAMKBundle {
+    encrypted_amk: Uint8Array;
+    iv: Uint8Array;
+    tag: Uint8Array;
+}
+export interface RecoveryBundle {
+    version: number;
+    bundle_type: "amk_recovery";
+    wrap_algorithm: "aes-256-gcm";
+    kdf_algorithm: "argon2id";
+    kdf_params: {
+        memory_kib: number;
+        iterations: number;
+        parallelism: number;
+        salt_b64: string;
+    };
+    encrypted_amk_b64: string;
+    iv_b64: string;
+    tag_b64: string;
+    checksum_sha256: string;
+    created_at: string;
+}
+export interface DeviceGrantPayload {
+    version: number;
+    grant_type: "amk_transfer";
+    crypto_version: number;
+    source_device_id: string;
+    target_device_id: string;
+    target_device_kex_public_key_b64: string;
+    encrypted_amk_b64: string;
+    shared_secret_salt_b64: string;
+    created_at: string;
+    expires_at: string;
+}

package/dist/src/crypto/types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/debug-logger.d.ts

@@ -0,0 +1,32 @@
+export declare const debugLog: {
+    info(component: string, msg: string): void;
+    warn(component: string, msg: string): void;
+    error(component: string, msg: string): void;
+    /** Log an API request (never logs tokens or ciphertext). */
+    apiRequest(method: string, url: string): void;
+    /** Log an API response (status + timing). */
+    apiResponse(method: string, url: string, status: number, ms: number): void;
+    /** Log an API error. */
+    apiError(method: string, url: string, error: unknown): void;
+    /** Log a crypto operation (never log key material). */
+    crypto(op: string, detail?: string): void;
+    /** Log a sync event. */
+    sync(msg: string): void;
+    /** Log sync upload start/end. */
+    syncUploadStart(logicalPath: string, objectId: string): void;
+    syncUploadEnd(logicalPath: string, objectId: string, version: number): void;
+    /** Log sync download start/end. */
+    syncDownloadStart(objectId: string): void;
+    syncDownloadEnd(objectId: string, logicalPath: string, version: number): void;
+    /** Log sync diff results. */
+    syncDiff(toUpload: number, toDownload: number, conflicts: number): void;
+    /** Log KDF started (never log passphrase or key material). */
+    cryptoKdfStart(): void;
+    cryptoKdfEnd(ms: number): void;
+    /** Log encrypt/decrypt completed (never log key material). */
+    cryptoEncryptDone(objectId: string): void;
+    cryptoDecryptDone(objectId: string): void;
+    /** Log CLI command execution. */
+    cliCommand(command: string): void;
+    cliCommandEnd(command: string, success: boolean, ms: number): void;
+};

package/dist/src/debug-logger.js

@@ -0,0 +1,108 @@
+import { appendFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+const LOG_FILE = process.env.MEMBOX_LOG_FILE ?? "";
+let initialized = false;
+function ensureDir() {
+    if (initialized || !LOG_FILE)
+        return;
+    try {
+        mkdirSync(dirname(LOG_FILE), { recursive: true });
+    }
+    catch {
+        /* dir may already exist */
+    }
+    initialized = true;
+}
+function ts() {
+    return new Date().toISOString();
+}
+// Synchronous write is acceptable for debug/联调 use — keeps log ordering
+// deterministic and avoids async complexity. Not intended for production.
+function write(level, component, msg) {
+    if (!LOG_FILE)
+        return;
+    ensureDir();
+    const line = `[${ts()}] [${level}] [${component}] ${msg}\n`;
+    try {
+        appendFileSync(LOG_FILE, line);
+    }
+    catch {
+        /* best-effort file logging */
+    }
+}
+export const debugLog = {
+    info(component, msg) {
+        write("INFO", component, msg);
+    },
+    warn(component, msg) {
+        write("WARN", component, msg);
+    },
+    error(component, msg) {
+        write("ERROR", component, msg);
+    },
+    /** Log an API request (never logs tokens or ciphertext). */
+    apiRequest(method, url) {
+        // Strip auth tokens from URL if any query params
+        const safeUrl = url.replace(/access_token=[^&]+/g, "access_token=***");
+        write("INFO", "api-client", `→ ${method} ${safeUrl}`);
+    },
+    /** Log an API response (status + timing). */
+    apiResponse(method, url, status, ms) {
+        const safeUrl = url.replace(/access_token=[^&]+/g, "access_token=***");
+        write("INFO", "api-client", `← ${status} ${method} ${safeUrl} (${ms}ms)`);
+    },
+    /** Log an API error. */
+    apiError(method, url, error) {
+        const safeUrl = url.replace(/access_token=[^&]+/g, "access_token=***");
+        const msg = error instanceof Error ? error.message : String(error);
+        write("ERROR", "api-client", `✗ ${method} ${safeUrl} — ${msg}`);
+    },
+    /** Log a crypto operation (never log key material). */
+    crypto(op, detail) {
+        write("INFO", "crypto", detail ? `${op}: ${detail}` : op);
+    },
+    /** Log a sync event. */
+    sync(msg) {
+        write("INFO", "sync", msg);
+    },
+    /** Log sync upload start/end. */
+    syncUploadStart(logicalPath, objectId) {
+        write("INFO", "sync", `upload-start: ${logicalPath} (${objectId})`);
+    },
+    syncUploadEnd(logicalPath, objectId, version) {
+        write("INFO", "sync", `upload-end: ${logicalPath} (${objectId}) v${version}`);
+    },
+    /** Log sync download start/end. */
+    syncDownloadStart(objectId) {
+        write("INFO", "sync", `download-start: ${objectId}`);
+    },
+    syncDownloadEnd(objectId, logicalPath, version) {
+        write("INFO", "sync", `download-end: ${objectId} → ${logicalPath} v${version}`);
+    },
+    /** Log sync diff results. */
+    syncDiff(toUpload, toDownload, conflicts) {
+        write("INFO", "sync", `diff: upload=${toUpload} download=${toDownload} conflicts=${conflicts}`);
+    },
+    /** Log KDF started (never log passphrase or key material). */
+    cryptoKdfStart() {
+        write("INFO", "crypto", "KDF started (Argon2id)");
+    },
+    cryptoKdfEnd(ms) {
+        write("INFO", "crypto", `KDF completed (${ms}ms)`);
+    },
+    /** Log encrypt/decrypt completed (never log key material). */
+    cryptoEncryptDone(objectId) {
+        write("INFO", "crypto", `encrypt completed: ${objectId}`);
+    },
+    cryptoDecryptDone(objectId) {
+        write("INFO", "crypto", `decrypt completed: ${objectId}`);
+    },
+    /** Log CLI command execution. */
+    cliCommand(command) {
+        write("INFO", "cli", `command-start: ${command}`);
+    },
+    cliCommandEnd(command, success, ms) {
+        const status = success ? "ok" : "failed";
+        write("INFO", "cli", `command-end: ${command} [${status}] (${ms}ms)`);
+    },
+};

package/dist/src/hooks/gateway-lifecycle.d.ts

@@ -0,0 +1,6 @@
+import type { AutoSyncService } from "../sync/auto-sync.js";
+export declare function getAutoSync(): AutoSyncService | undefined;
+/** Create and register a new AutoSyncService (used by resume when none exists). */
+export declare function startAutoSync(): Promise<AutoSyncService>;
+export declare function onGatewayStart(): Promise<void>;
+export declare function onGatewayStop(): Promise<void>;

package/dist/src/hooks/gateway-lifecycle.js

@@ -0,0 +1,40 @@
+import { readState } from "../store/local-state.js";
+import { vaultSession } from "../store/session.js";
+import { getSyncStatus } from "../api/sync.js";
+import { createAuthenticatedClient } from "../cli/helpers.js";
+let autoSync;
+export function getAutoSync() {
+    return autoSync;
+}
+/** Create and register a new AutoSyncService (used by resume when none exists). */
+export async function startAutoSync() {
+    const { AutoSyncService } = await import("../sync/auto-sync.js");
+    autoSync = new AutoSyncService(process.cwd());
+    return autoSync;
+}
+export async function onGatewayStart() {
+    try {
+        const state = await readState();
+        if (!state?.setup_complete || !vaultSession.isUnlocked())
+            return;
+        // Remote status check: compare cursors
+        const client = await createAuthenticatedClient(state);
+        const remote = await getSyncStatus(client);
+        if (remote.cursor > state.sync_cursor) {
+            console.log(`[membox] Remote has updates (remote cursor ${remote.cursor} > local ${state.sync_cursor}). Run 'pull' to sync.`);
+        }
+        // Start auto-sync if not paused
+        if (!state.sync_paused) {
+            const { AutoSyncService } = await import("../sync/auto-sync.js");
+            autoSync = new AutoSyncService(process.cwd());
+            autoSync.start();
+        }
+    }
+    catch {
+        // Network unavailable — don't block startup
+    }
+}
+export async function onGatewayStop() {
+    autoSync?.stop();
+    autoSync = undefined;
+}

package/dist/src/hooks/prompt-inject.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Inject a brief vault status line into agent context.
+ * Called on before_prompt_build hook.
+ */
+export declare function injectVaultStatus(): Promise<{
+    appendSystemContext: string;
+}>;

package/dist/src/hooks/prompt-inject.js

@@ -0,0 +1,18 @@
+import { readState } from "../store/local-state.js";
+import { vaultSession } from "../store/session.js";
+/**
+ * Inject a brief vault status line into agent context.
+ * Called on before_prompt_build hook.
+ */
+export async function injectVaultStatus() {
+    const state = await readState();
+    if (!state?.setup_complete) {
+        return { appendSystemContext: "Membox Vault: not configured." };
+    }
+    const files = Object.keys(state.file_versions).length;
+    const locked = !vaultSession.isUnlocked();
+    const paused = state.sync_paused ? ", paused" : "";
+    return {
+        appendSystemContext: `Membox Vault: ${locked ? "locked" : "unlocked"}${paused}, ${files} synced file(s), cursor ${state.sync_cursor}.`,
+    };
+}