@raviolelabs/engram-mcp 0.2.0

package/dist/sync/cloud-saves.js

@@ -0,0 +1,182 @@
+// src/sync/cloud-saves.ts
+/**
+ * Cloud Saves — nightly encrypted snapshot of SQLite DB.
+ *
+ * Flow:
+ *   1. Checkpoint SQLite WAL and copy the DB file to a temp location.
+ *   2. Get the current Lamport timestamp from ops_log.
+ *   3. Encrypt the DB bytes with libsodium secretstream (master key).
+ *   4. PUT /saves/snapshot → engram-cloud (sends body).
+ *   5. Record snapshot in local snapshot_log table.
+ *   6. GC local temp files.
+ *
+ * Bootstrap (new PC):
+ *   1. GET /saves/snapshot → list available snapshots.
+ *   2. Download latest snapshot.
+ *   3. Decrypt → restore SQLite.
+ *   4. Fetch and replay ops_log deltas > snapshot lamport_ts (Plan N protocol).
+ */
+import sodium from 'libsodium-wrappers';
+import { createLogger } from '../logger.js';
+import { getDb } from '../db/index.js';
+import { loadConfig } from '../config/index.js';
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+const log = createLogger('cloud-saves');
+/** In-memory master key — set by the auth/pairing flow. */
+let _masterKey = null;
+let _jwt = null;
+let _cloudBaseUrl = 'https://api.engram-mcp.com';
+export function initCloudSaves(params) {
+    _masterKey = params.masterKey;
+    _jwt = params.jwt;
+    if (params.cloudBaseUrl)
+        _cloudBaseUrl = params.cloudBaseUrl;
+    log.info('Cloud Saves module initialized');
+}
+export function clearCloudSaves() {
+    if (_masterKey)
+        _masterKey.fill(0);
+    _masterKey = null;
+    _jwt = null;
+}
+/** Schedule the nightly snapshot at 03:00 local time. */
+export function scheduleNightlySnapshot() {
+    const now = new Date();
+    const next = new Date(now);
+    next.setHours(3, 0, 0, 0);
+    if (next <= now) {
+        next.setDate(next.getDate() + 1);
+    }
+    const msUntilFirst = next.getTime() - now.getTime();
+    const TWENTY_FOUR_HOURS = 24 * 60 * 60 * 1000;
+    log.info(`Nightly snapshot scheduled in ${Math.round(msUntilFirst / 60000)} minutes (03:00 local)`);
+    const timeout = setTimeout(async () => {
+        await takeSnapshot().catch((err) => log.error(`Nightly snapshot failed: ${err instanceof Error ? err.message : String(err)}`));
+        setInterval(async () => {
+            await takeSnapshot().catch((err) => log.error(`Nightly snapshot failed: ${err instanceof Error ? err.message : String(err)}`));
+        }, TWENTY_FOUR_HOURS);
+    }, msUntilFirst);
+    return timeout;
+}
+/**
+ * Take a snapshot now. Can be called manually (e.g., from a dashboard button).
+ */
+export async function takeSnapshot() {
+    if (!_masterKey || !_jwt) {
+        throw new Error('Cloud Saves not initialized — call initCloudSaves() first');
+    }
+    const config = loadConfig();
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'engram-snap-'));
+    try {
+        // 1. Checkpoint SQLite WAL and copy the DB file
+        const db = getDb();
+        db.pragma('wal_checkpoint(FULL)');
+        const dbPath = path.join(config.dataDir, 'engram.db');
+        const dbCopyPath = path.join(tmpDir, 'engram.db');
+        fs.copyFileSync(dbPath, dbCopyPath);
+        log.info(`DB copied to ${dbCopyPath}`);
+        // 2. Get current Lamport timestamp from ops_log
+        const lamportRow = db
+            .prepare(`SELECT MAX(lamport_ts) as max_ts FROM ops_log`)
+            .get();
+        const lamportTs = lamportRow?.max_ts ?? 0;
+        // 3. Read DB bytes
+        const dbBytes = fs.readFileSync(dbCopyPath);
+        // 4. Encrypt with libsodium secretstream
+        const encryptedBytes = await encryptBuffer(dbBytes, _masterKey);
+        log.info(`Snapshot encrypted: ${encryptedBytes.byteLength} bytes`);
+        // 5. Upload
+        const res = await fetch(`${_cloudBaseUrl}/saves/snapshot`, {
+            method: 'PUT',
+            headers: {
+                'Content-Type': 'application/octet-stream',
+                'Content-Length': String(encryptedBytes.byteLength),
+                Authorization: `Bearer ${_jwt}`,
+                'X-Lamport-Ts': String(lamportTs),
+            },
+            body: encryptedBytes,
+        });
+        if (!res.ok) {
+            const body = await res.text();
+            throw new Error(`Snapshot upload failed: ${res.status} — ${body}`);
+        }
+        const result = (await res.json());
+        const snapshotId = result.id;
+        // 6. Record in local snapshot_log
+        db.prepare(`INSERT INTO snapshot_log (id, r2_key, lamport_ts, size_bytes, created_at)
+       VALUES (?, ?, ?, ?, ?)`).run(snapshotId, result.r2_key, lamportTs, encryptedBytes.byteLength, Date.now());
+        log.info(`Snapshot complete: id=${snapshotId}, size=${encryptedBytes.byteLength} bytes`);
+        return { id: snapshotId, sizeBytes: encryptedBytes.byteLength };
+    }
+    finally {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+}
+/**
+ * Bootstrap a new PC from the latest cloud snapshot.
+ * Decrypts the snapshot and restores the SQLite DB in-place.
+ * After this, the caller should replay ops_log deltas > lamportTs from the cloud relay.
+ */
+export async function bootstrapFromSnapshot(params) {
+    const base = params.cloudBaseUrl ?? 'https://api.engram-mcp.com';
+    // List snapshots
+    const listRes = await fetch(`${base}/saves/snapshot`, {
+        headers: { Authorization: `Bearer ${params.jwt}` },
+    });
+    if (!listRes.ok)
+        throw new Error(`Snapshot list failed: ${listRes.status}`);
+    const { snapshots } = (await listRes.json());
+    if (!snapshots || snapshots.length === 0) {
+        log.info('No cloud snapshots found — fresh start');
+        return null;
+    }
+    const latest = snapshots[0]; // already ordered DESC by created_at
+    if (!latest.available) {
+        log.warn('Latest snapshot marked unavailable in R2');
+        return null;
+    }
+    log.info(`Bootstrapping from snapshot ${latest.id} (lamport_ts=${latest.lamport_ts})`);
+    // Download
+    const dlRes = await fetch(`${base}/saves/snapshot/${latest.id}/download`, {
+        headers: { Authorization: `Bearer ${params.jwt}` },
+    });
+    if (!dlRes.ok)
+        throw new Error(`Snapshot download failed: ${dlRes.status}`);
+    const encryptedBytes = Buffer.from(await dlRes.arrayBuffer());
+    // Decrypt
+    const plainBytes = await decryptBuffer(encryptedBytes, params.masterKey);
+    // Restore: write to a temp file then atomically move to dataDir/engram.db
+    const tmpPath = path.join(os.tmpdir(), `engram-restore-${Date.now()}.db`);
+    fs.writeFileSync(tmpPath, plainBytes);
+    const dbTarget = path.join(params.dataDir, 'engram.db');
+    if (fs.existsSync(dbTarget)) {
+        fs.copyFileSync(dbTarget, `${dbTarget}.bak-${Date.now()}`);
+    }
+    fs.renameSync(tmpPath, dbTarget);
+    log.info(`DB restored from snapshot. Replay ops > lamport_ts=${latest.lamport_ts}`);
+    return { lamportTs: latest.lamport_ts, sizeBytes: encryptedBytes.byteLength };
+}
+// ---------------------------------------------------------------------------
+// Encryption helpers (libsodium secretstream)
+// ---------------------------------------------------------------------------
+export async function encryptBuffer(plain, key) {
+    await sodium.ready;
+    const { state, header } = sodium.crypto_secretstream_xchacha20poly1305_init_push(new Uint8Array(key));
+    const cipherChunk = sodium.crypto_secretstream_xchacha20poly1305_push(state, new Uint8Array(plain), null, sodium.crypto_secretstream_xchacha20poly1305_TAG_FINAL);
+    // Format: header || ciphertext
+    return Buffer.concat([Buffer.from(header), Buffer.from(cipherChunk)]);
+}
+export async function decryptBuffer(encrypted, key) {
+    await sodium.ready;
+    const HEADER_LEN = sodium.crypto_secretstream_xchacha20poly1305_HEADERBYTES;
+    const header = encrypted.subarray(0, HEADER_LEN);
+    const cipher = encrypted.subarray(HEADER_LEN);
+    const state = sodium.crypto_secretstream_xchacha20poly1305_init_pull(new Uint8Array(header), new Uint8Array(key));
+    const result = sodium.crypto_secretstream_xchacha20poly1305_pull(state, new Uint8Array(cipher), null);
+    if (!result)
+        throw new Error('Snapshot decryption failed — wrong key or corrupted data');
+    return Buffer.from(result.message);
+}
+//# sourceMappingURL=cloud-saves.js.map

package/dist/sync/cloud-saves.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloud-saves.js","sourceRoot":"","sources":["../../src/sync/cloud-saves.ts"],"names":[],"mappings":"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"}

package/dist/sync/ed25519.d.ts

@@ -0,0 +1,54 @@
+import Database from 'better-sqlite3';
+import type { DeviceIdentity } from './types.js';
+/**
+ * Generate a new ed25519 keypair.
+ * Returns { pubkeyHex, privkeyHex } where both are raw key bytes as hex strings.
+ * Raw = the 32-byte public key and 32-byte private key seed.
+ */
+export declare function generateKeypair(): {
+    pubkeyHex: string;
+    privkeyHex: string;
+};
+/**
+ * Sign `data` with the ed25519 private key (raw 32-byte hex seed).
+ * Returns the 64-byte signature as a hex string.
+ *
+ * We reconstruct the PKCS8 DER key from the raw seed.
+ * PKCS8 DER for ed25519 private key is:
+ *   30 2e         SEQUENCE (46 bytes)
+ *     02 01 00    INTEGER 0 (version)
+ *     30 05       SEQUENCE (5 bytes)
+ *       06 03 2b 65 70  OID 1.3.101.112 (Ed25519)
+ *     04 22       OCTET STRING (34 bytes)
+ *       04 20     OCTET STRING (32 bytes) — the raw seed
+ *       <32 bytes seed>
+ */
+export declare function signBytes(data: Buffer, privkeyHex: string): string;
+/**
+ * Verify an ed25519 signature.
+ * @param data       - original bytes that were signed
+ * @param sigHex     - 64-byte signature as hex string
+ * @param pubkeyHex  - 32-byte public key as hex string
+ */
+export declare function verifySignature(data: Buffer, sigHex: string, pubkeyHex: string): boolean;
+/**
+ * Build the canonical bytes that are signed for an op.
+ * Format: `{op_id}|{device_id}|{lamport_ts}|{op_type}|{memory_id}|{payload_enc}|{nonce}`
+ * All fields are UTF-8. payload_enc and nonce are base64 strings here.
+ */
+export declare function opCanonicalBytes(fields: {
+    op_id: string;
+    device_id: string;
+    lamport_ts: number;
+    op_type: string;
+    memory_id: string;
+    payload_enc: string;
+    nonce: string;
+}): Buffer;
+/**
+ * Return the existing device identity or generate a new one and persist it.
+ * The private key is stored in the local SQLite DB (protected by filesystem perms + WAL).
+ * For higher assurance, this can be replaced with OS keychain calls via keytar.
+ */
+export declare function getOrCreateDeviceIdentity(db: Database.Database): DeviceIdentity;
+//# sourceMappingURL=ed25519.d.ts.map

package/dist/sync/ed25519.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ed25519.d.ts","sourceRoot":"","sources":["../../src/sync/ed25519.ts"],"names":[],"mappings":"AAQA,OAAO,QAAQ,MAAM,gBAAgB,CAAC;AAGtC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAKjD;;;;GAIG;AACH,wBAAgB,eAAe,IAAI;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAc3E;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAUlE;AAyBD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAcxF;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;CACf,GAAG,MAAM,CAWT;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,EAAE,EAAE,QAAQ,CAAC,QAAQ,GAAG,cAAc,CA0B/E"}

package/dist/sync/ed25519.js

@@ -0,0 +1,136 @@
+// src/sync/ed25519.ts
+import { createPrivateKey, createPublicKey, generateKeyPairSync, sign, verify, } from 'node:crypto';
+import { monotonicFactory } from 'ulid';
+import { createLogger } from '../logger.js';
+const log = createLogger('sync:ed25519');
+const ulid = monotonicFactory();
+/**
+ * Generate a new ed25519 keypair.
+ * Returns { pubkeyHex, privkeyHex } where both are raw key bytes as hex strings.
+ * Raw = the 32-byte public key and 32-byte private key seed.
+ */
+export function generateKeypair() {
+    const { privateKey, publicKey } = generateKeyPairSync('ed25519');
+    // Export raw bytes
+    const privRaw = privateKey.export({ type: 'pkcs8', format: 'der' });
+    const pubRaw = publicKey.export({ type: 'spki', format: 'der' });
+    // Last 32 bytes of PKCS8 DER = the private seed
+    // Last 32 bytes of SPKI DER  = the public key
+    const privHex = Buffer.from(privRaw).subarray(-32).toString('hex');
+    const pubHex = Buffer.from(pubRaw).subarray(-32).toString('hex');
+    log.debug('generated new ed25519 keypair', { pubHex: pubHex.slice(0, 8) + '…' });
+    return { pubkeyHex: pubHex, privkeyHex: privHex };
+}
+/**
+ * Sign `data` with the ed25519 private key (raw 32-byte hex seed).
+ * Returns the 64-byte signature as a hex string.
+ *
+ * We reconstruct the PKCS8 DER key from the raw seed.
+ * PKCS8 DER for ed25519 private key is:
+ *   30 2e         SEQUENCE (46 bytes)
+ *     02 01 00    INTEGER 0 (version)
+ *     30 05       SEQUENCE (5 bytes)
+ *       06 03 2b 65 70  OID 1.3.101.112 (Ed25519)
+ *     04 22       OCTET STRING (34 bytes)
+ *       04 20     OCTET STRING (32 bytes) — the raw seed
+ *       <32 bytes seed>
+ */
+export function signBytes(data, privkeyHex) {
+    const seed = Buffer.from(privkeyHex, 'hex');
+    if (seed.length !== 32)
+        throw new Error('privkeyHex must be 32 raw bytes (64 hex chars)');
+    // Build PKCS8 DER for ed25519 from raw seed
+    const pkcs8 = buildEd25519Pkcs8(seed);
+    const privKey = createPrivateKey({ key: pkcs8, format: 'der', type: 'pkcs8' });
+    const sig = sign(null, data, privKey);
+    return Buffer.from(sig).toString('hex');
+}
+/**
+ * Build a PKCS8 DER buffer for an ed25519 private key from a 32-byte seed.
+ * This is a fixed-layout encoding — no ASN.1 parser needed.
+ */
+function buildEd25519Pkcs8(seed) {
+    // PKCS8 structure for Ed25519:
+    // SEQUENCE {
+    //   INTEGER 0
+    //   SEQUENCE { OID 1.3.101.112 }
+    //   OCTET STRING { OCTET STRING { seed } }
+    // }
+    const oid = Buffer.from([0x06, 0x03, 0x2b, 0x65, 0x70]); // OID Ed25519
+    const innerOctet = Buffer.concat([Buffer.from([0x04, 0x20]), seed]); // OCTET STRING(seed)
+    const outerOctet = Buffer.concat([
+        Buffer.from([0x04, innerOctet.length]),
+        innerOctet,
+    ]);
+    const algSeq = Buffer.concat([Buffer.from([0x30, oid.length]), oid]);
+    const version = Buffer.from([0x02, 0x01, 0x00]); // INTEGER 0
+    const body = Buffer.concat([version, algSeq, outerOctet]);
+    return Buffer.concat([Buffer.from([0x30, body.length]), body]);
+}
+/**
+ * Verify an ed25519 signature.
+ * @param data       - original bytes that were signed
+ * @param sigHex     - 64-byte signature as hex string
+ * @param pubkeyHex  - 32-byte public key as hex string
+ */
+export function verifySignature(data, sigHex, pubkeyHex) {
+    try {
+        const pubKey = createPublicKey({
+            key: {
+                kty: 'OKP',
+                crv: 'Ed25519',
+                x: Buffer.from(pubkeyHex, 'hex').toString('base64url'),
+            },
+            format: 'jwk',
+        });
+        return verify(null, data, pubKey, Buffer.from(sigHex, 'hex'));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Build the canonical bytes that are signed for an op.
+ * Format: `{op_id}|{device_id}|{lamport_ts}|{op_type}|{memory_id}|{payload_enc}|{nonce}`
+ * All fields are UTF-8. payload_enc and nonce are base64 strings here.
+ */
+export function opCanonicalBytes(fields) {
+    const str = [
+        fields.op_id,
+        fields.device_id,
+        String(fields.lamport_ts),
+        fields.op_type,
+        fields.memory_id,
+        fields.payload_enc,
+        fields.nonce,
+    ].join('|');
+    return Buffer.from(str, 'utf8');
+}
+/**
+ * Return the existing device identity or generate a new one and persist it.
+ * The private key is stored in the local SQLite DB (protected by filesystem perms + WAL).
+ * For higher assurance, this can be replaced with OS keychain calls via keytar.
+ */
+export function getOrCreateDeviceIdentity(db) {
+    const existing = db
+        .prepare(`SELECT * FROM device_identity LIMIT 1`)
+        .get();
+    if (existing)
+        return existing;
+    const { pubkeyHex, privkeyHex } = generateKeypair();
+    const deviceId = pubkeyHex; // device_id IS the pubkey — no separate UUID needed
+    const createdAt = Date.now();
+    // Generate a stable ULID seed — not used here but keeps import alive
+    void ulid;
+    db.prepare(`INSERT INTO device_identity (device_id, pubkey_hex, privkey_hex, lamport_ts, created_at)
+     VALUES (?, ?, ?, 0, ?)`).run(deviceId, pubkeyHex, privkeyHex, createdAt);
+    log.info('created new device identity', { deviceId: deviceId.slice(0, 8) + '…' });
+    return {
+        device_id: deviceId,
+        pubkey_hex: pubkeyHex,
+        privkey_hex: privkeyHex,
+        lamport_ts: 0,
+        created_at: createdAt,
+    };
+}
+//# sourceMappingURL=ed25519.js.map

package/dist/sync/ed25519.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ed25519.js","sourceRoot":"","sources":["../../src/sync/ed25519.ts"],"names":[],"mappings":"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"}

package/dist/sync/ops-log.d.ts

@@ -0,0 +1,43 @@
+import Database from 'better-sqlite3';
+import type { DeviceIdentity, OpType, WireOp } from './types.js';
+/**
+ * Encrypt `plaintext` with a 256-bit master key.
+ * Returns { enc: Buffer, nonce: Buffer } where nonce is 12 bytes (GCM standard).
+ * The last 16 bytes of `enc` are the GCM auth tag.
+ */
+export declare function encryptPayload(plaintext: Buffer, masterKey: Buffer): {
+    enc: Buffer;
+    nonce: Buffer;
+};
+/**
+ * Decrypt an op payload.
+ * The last 16 bytes of `enc` are the GCM auth tag.
+ */
+export declare function decryptPayload(enc: Buffer, nonce: Buffer, masterKey: Buffer): Buffer;
+export declare class OpsLogger {
+    #private;
+    private db;
+    private identity;
+    private masterKey;
+    constructor(db: Database.Database, identity: DeviceIdentity, masterKey: Buffer);
+    /**
+     * Append one operation to the ops_log.
+     * - Increments the device Lamport clock.
+     * - Encrypts the JSON payload with the master key (AES-256-GCM).
+     * - Signs canonical bytes with the device private key.
+     * - Inserts the row; does NOT set sent_at (pending push).
+     * Returns the generated op_id (ULID).
+     */
+    append(opType: OpType, memoryId: string, payload: Record<string, unknown>): string;
+    /** Mark ops as sent (set sent_at = now). */
+    markSent(opIds: string[]): void;
+    /** Mark ops as applied locally. */
+    markApplied(opIds: string[]): void;
+    /** Return ops not yet sent to cloud (sent_at IS NULL). */
+    listPending(): WireOp[];
+    /** Return the max applied lamport_ts across all devices (for catch-up). */
+    maxAppliedLamport(): number;
+    /** Return the lexicographically largest op_id that has been applied (any device). */
+    maxAppliedOpId(): string | null;
+}
+//# sourceMappingURL=ops-log.d.ts.map

package/dist/sync/ops-log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ops-log.d.ts","sourceRoot":"","sources":["../../src/sync/ops-log.ts"],"names":[],"mappings":"AAEA,OAAO,QAAQ,MAAM,gBAAgB,CAAC;AAItC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAQjE;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAChB;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAMhC;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAOpF;AAED,qBAAa,SAAS;;IACpB,OAAO,CAAC,EAAE,CAAoB;IAC9B,OAAO,CAAC,QAAQ,CAAiB;IACjC,OAAO,CAAC,SAAS,CAAS;gBAEd,EAAE,EAAE,QAAQ,CAAC,QAAQ,EAAE,QAAQ,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM;IAM9E;;;;;;;OAOG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM;IAiDlF,4CAA4C;IAC5C,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI;IAS/B,mCAAmC;IACnC,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI;IAQlC,0DAA0D;IAC1D,WAAW,IAAI,MAAM,EAAE;IAmCvB,2EAA2E;IAC3E,iBAAiB,IAAI,MAAM;IAO3B,qFAAqF;IACrF,cAAc,IAAI,MAAM,GAAG,IAAI;CAiBhC"}

package/dist/sync/ops-log.js

@@ -0,0 +1,153 @@
+// src/sync/ops-log.ts
+import { createCipheriv, createDecipheriv, randomBytes } from 'node:crypto';
+import { monotonicFactory } from 'ulid';
+import { createLogger } from '../logger.js';
+import { opCanonicalBytes, signBytes } from './ed25519.js';
+const log = createLogger('sync:ops-log');
+const ulid = monotonicFactory();
+/** AES-256-GCM — NIST-approved, hardware-accelerated on most CPUs. */
+const ALGO = 'aes-256-gcm';
+/**
+ * Encrypt `plaintext` with a 256-bit master key.
+ * Returns { enc: Buffer, nonce: Buffer } where nonce is 12 bytes (GCM standard).
+ * The last 16 bytes of `enc` are the GCM auth tag.
+ */
+export function encryptPayload(plaintext, masterKey) {
+    if (masterKey.length !== 32)
+        throw new Error('masterKey must be 32 bytes');
+    const nonce = randomBytes(12);
+    const cipher = createCipheriv(ALGO, masterKey, nonce);
+    const enc = Buffer.concat([cipher.update(plaintext), cipher.final(), cipher.getAuthTag()]);
+    return { enc, nonce };
+}
+/**
+ * Decrypt an op payload.
+ * The last 16 bytes of `enc` are the GCM auth tag.
+ */
+export function decryptPayload(enc, nonce, masterKey) {
+    if (masterKey.length !== 32)
+        throw new Error('masterKey must be 32 bytes');
+    const tag = enc.subarray(enc.length - 16);
+    const ciphertext = enc.subarray(0, enc.length - 16);
+    const decipher = createDecipheriv(ALGO, masterKey, nonce);
+    decipher.setAuthTag(tag);
+    return Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+}
+export class OpsLogger {
+    db;
+    identity;
+    masterKey;
+    constructor(db, identity, masterKey) {
+        this.db = db;
+        this.identity = identity;
+        this.masterKey = masterKey;
+    }
+    /**
+     * Append one operation to the ops_log.
+     * - Increments the device Lamport clock.
+     * - Encrypts the JSON payload with the master key (AES-256-GCM).
+     * - Signs canonical bytes with the device private key.
+     * - Inserts the row; does NOT set sent_at (pending push).
+     * Returns the generated op_id (ULID).
+     */
+    append(opType, memoryId, payload) {
+        const opId = ulid();
+        const createdAt = Date.now();
+        // Lamport increment
+        const lamportTs = this.#nextLamport();
+        // Encrypt payload
+        const plaintext = Buffer.from(JSON.stringify(payload), 'utf8');
+        const { enc, nonce } = encryptPayload(plaintext, this.masterKey);
+        const payloadEncB64 = enc.toString('base64');
+        const nonceB64 = nonce.toString('base64');
+        // Sign canonical bytes
+        const canonical = opCanonicalBytes({
+            op_id: opId,
+            device_id: this.identity.device_id,
+            lamport_ts: lamportTs,
+            op_type: opType,
+            memory_id: memoryId,
+            payload_enc: payloadEncB64,
+            nonce: nonceB64,
+        });
+        const sigHex = signBytes(canonical, this.identity.privkey_hex);
+        // Persist — store raw bytes in BLOB columns
+        this.db
+            .prepare(`INSERT INTO ops_log
+           (op_id, device_id, lamport_ts, op_type, memory_id,
+            payload_enc, nonce, sig, applied, created_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, 0, ?)`)
+            .run(opId, this.identity.device_id, lamportTs, opType, memoryId, enc, // raw encrypted bytes
+        nonce, // raw nonce bytes
+        Buffer.from(sigHex, 'hex'), // raw sig bytes
+        createdAt);
+        log.debug('op appended', { opId, opType, memoryId, lamportTs });
+        return opId;
+    }
+    /** Mark ops as sent (set sent_at = now). */
+    markSent(opIds) {
+        if (opIds.length === 0)
+            return;
+        const now = Date.now();
+        const placeholders = opIds.map(() => '?').join(',');
+        this.db
+            .prepare(`UPDATE ops_log SET sent_at = ? WHERE op_id IN (${placeholders})`)
+            .run(now, ...opIds);
+    }
+    /** Mark ops as applied locally. */
+    markApplied(opIds) {
+        if (opIds.length === 0)
+            return;
+        const placeholders = opIds.map(() => '?').join(',');
+        this.db
+            .prepare(`UPDATE ops_log SET applied = 1 WHERE op_id IN (${placeholders})`)
+            .run(...opIds);
+    }
+    /** Return ops not yet sent to cloud (sent_at IS NULL). */
+    listPending() {
+        const rows = this.db
+            .prepare(`SELECT op_id, device_id, lamport_ts, op_type, memory_id,
+                payload_enc, nonce, sig, created_at
+         FROM ops_log
+         WHERE sent_at IS NULL
+         ORDER BY created_at ASC
+         LIMIT 200`)
+            .all();
+        return rows.map((r) => ({
+            op_id: r.op_id,
+            device_id: r.device_id,
+            lamport_ts: r.lamport_ts,
+            op_type: r.op_type,
+            memory_id: r.memory_id,
+            payload_enc: r.payload_enc.toString('base64'),
+            nonce: r.nonce.toString('base64'),
+            sig: r.sig.toString('hex'),
+            created_at: r.created_at,
+        }));
+    }
+    /** Return the max applied lamport_ts across all devices (for catch-up). */
+    maxAppliedLamport() {
+        const row = this.db
+            .prepare(`SELECT MAX(lamport_ts) as m FROM ops_log WHERE applied = 1`)
+            .get();
+        return row.m ?? 0;
+    }
+    /** Return the lexicographically largest op_id that has been applied (any device). */
+    maxAppliedOpId() {
+        const row = this.db
+            .prepare(`SELECT op_id FROM ops_log WHERE applied = 1 ORDER BY op_id DESC LIMIT 1`)
+            .get();
+        return row?.op_id ?? null;
+    }
+    #nextLamport() {
+        const row = this.db
+            .prepare(`SELECT lamport_ts FROM device_identity WHERE device_id = ?`)
+            .get(this.identity.device_id);
+        const next = (row?.lamport_ts ?? 0) + 1;
+        this.db
+            .prepare(`UPDATE device_identity SET lamport_ts = ? WHERE device_id = ?`)
+            .run(next, this.identity.device_id);
+        return next;
+    }
+}
+//# sourceMappingURL=ops-log.js.map

package/dist/sync/ops-log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ops-log.js","sourceRoot":"","sources":["../../src/sync/ops-log.ts"],"names":[],"mappings":"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"}

package/dist/sync/recovery-setup.d.ts

@@ -0,0 +1,26 @@
+export interface RecoverySetupInput {
+    /** The user's 32-byte master key (must be held in RAM — never written to disk) */
+    masterKey: Buffer;
+    /** Exactly 5 trusted email addresses */
+    trustedEmails: [string, string, string, string, string];
+    /** JWT for cloud API calls */
+    jwt: string;
+    /** Cloud API base URL, e.g. 'https://api.engram-mcp.com' */
+    cloudBaseUrl: string;
+}
+export interface RecoverySetupResult {
+    ok: true;
+    shardsStored: number;
+    /** The KWK, for in-memory ephemeral use only. NEVER log or persist this. */
+    kwk: Buffer;
+}
+export declare function setupRecoveryShards(input: RecoverySetupInput): Promise<RecoverySetupResult>;
+/**
+ * Decrypt the encrypted master key using the KWK reconstructed from Shamir shares.
+ * Called during the recovery restore flow on the client side.
+ *
+ * @param mkCiphertextHex - hex string: nonce (24 bytes) || ciphertext
+ * @param kwk             - 32-byte key-wrapping key (reconstructed from 3-of-5 shares)
+ */
+export declare function decryptMasterKey(mkCiphertextHex: string, kwk: Buffer): Promise<Buffer>;
+//# sourceMappingURL=recovery-setup.d.ts.map

package/dist/sync/recovery-setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recovery-setup.d.ts","sourceRoot":"","sources":["../../src/sync/recovery-setup.ts"],"names":[],"mappings":"AAsBA,MAAM,WAAW,kBAAkB;IACjC,kFAAkF;IAClF,SAAS,EAAE,MAAM,CAAC;IAClB,wCAAwC;IACxC,aAAa,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACxD,8BAA8B;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,4DAA4D;IAC5D,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,IAAI,CAAC;IACT,YAAY,EAAE,MAAM,CAAC;IACrB,4EAA4E;IAC5E,GAAG,EAAE,MAAM,CAAC;CACb;AA8BD,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,kBAAkB,GACxB,OAAO,CAAC,mBAAmB,CAAC,CAgE9B;AAED;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CAAC,eAAe,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAmB5F"}