mem-os-python 1.6.27__py3-none-any.whl

memos/_js/sync.js

@@ -0,0 +1,389 @@
+/**
+ * Encrypted cross-machine sync (bundle format v2).
+ *
+ * Export memories to an encrypted bundle file, move it to another machine
+ * (via cloud drive, USB, etc.), and import it there. The bundle is encrypted
+ * with AES-256-GCM; the storage medium never sees plaintext.
+ *
+ * ## Threat model (v2)
+ *
+ * - The sync bundle may be stored on untrusted storage (cloud drives, USB
+ *   sticks, email). EVERYTHING about each record — id, content, type,
+ *   tags, timestamps, namespace, metadata — is encrypted client-side
+ *   before writing the bundle. Each record gets a fresh random nonce.
+ * - Bundle metadata (`version`, `exportedAt`, `salt`, `recordCount`) is
+ *   plaintext but AUTHENTICATED: it is bound into every record's
+ *   AES-GCM additional authenticated data (AAD). Tampering with it
+ *   fails decryption.
+ * - The encryption key is derived from a user passphrase via PBKDF2
+ *   (100k iterations, SHA-256) or read directly from a key file. The key
+ *   never leaves the user's devices.
+ * - An attacker with the bundle but not the key learns only: the bundle
+ *   version, export timestamp, salt, record count, and per-record
+ *   ciphertext sizes. They do NOT learn IDs, content, types, tags,
+ *   timestamps, or any other memory field.
+ * - This does NOT protect against an attacker who obtains the passphrase
+ *   or key file. Choose a strong passphrase.
+ * - This does NOT hide access patterns (when you sync, how many records).
+ *
+ * ## Conflict semantics
+ *
+ * - `skip-existing` (default): records with IDs already in the local store
+ *   are skipped. New records are imported with their original IDs and
+ *   timestamps.
+ * - `last-write-wins`: if a record exists locally, the version with the
+ *   newer `updatedAt` wins and replaces the local copy (same ID,
+ *   incoming timestamps preserved). On equal timestamps the local copy
+ *   is kept (deterministic tiebreak).
+ * - Content-identical records are never duplicated: if any local record
+ *   already has the same content hash, the incoming record is skipped.
+ *
+ * ## Local-first
+ *
+ * The local SQLite database remains the source of truth. Sync is additive:
+ * export writes a snapshot, import merges into the local store. Import
+ * never deletes records except replacing the single conflicting record
+ * under `last-write-wins`.
+ *
+ * ## Transport
+ *
+ * Transport is manual: you move the bundle file yourself (cloud drive,
+ * USB stick, `scp`, …). There is no network sync backend — the bundle
+ * file IS the transport, and the encryption above is what makes that safe.
+ *
+ * @module @memos/sync
+ */
+import { createCipheriv, createDecipheriv, createHash, pbkdf2Sync, randomBytes, } from "node:crypto";
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+const SYNC_VERSION = 2;
+const PBKDF2_ITERATIONS = 100_000;
+const KEY_LENGTH = 32; // AES-256
+const NONCE_LENGTH = 12; // GCM standard
+const SALT_LENGTH = 16;
+const MEMORY_TYPES = [
+    "fact",
+    "preference",
+    "context",
+    "relationship",
+    "entity",
+    "custom",
+];
+/**
+ * Derive a 32-byte AES key from a passphrase using PBKDF2.
+ */
+export function deriveKey(passphrase, salt) {
+    return pbkdf2Sync(passphrase, salt, PBKDF2_ITERATIONS, KEY_LENGTH, "sha256");
+}
+/**
+ * Build the AES-GCM additional authenticated data for a bundle.
+ * Binds the plaintext bundle metadata to every record's ciphertext so
+ * any tampering with version/exportedAt/salt/recordCount fails auth.
+ * Key order is fixed so encrypt and decrypt compute identical bytes.
+ */
+export function buildAAD(bundle) {
+    return Buffer.from(JSON.stringify({
+        v: bundle.version,
+        exportedAt: bundle.exportedAt,
+        salt: bundle.salt,
+        recordCount: bundle.recordCount,
+    }), "utf-8");
+}
+/**
+ * Resolve the raw encryption key from a passphrase or key buffer.
+ * Raw-key length errors use a constant message (never derived from key
+ * material — see the CodeQL js/clear-text-logging note in v1).
+ */
+function resolveKey(keyOrPassphrase, salt) {
+    if (typeof keyOrPassphrase === "string") {
+        return deriveKey(keyOrPassphrase, salt);
+    }
+    if (keyOrPassphrase.length !== KEY_LENGTH) {
+        throw new Error(`raw key must be ${KEY_LENGTH} bytes`);
+    }
+    return keyOrPassphrase;
+}
+/**
+ * Encrypt a plaintext string with AES-256-GCM.
+ * `aad`, when given, is authenticated but not encrypted.
+ * Returns { nonce, ciphertext, tag } as base64 strings.
+ */
+export function encryptRecord(plaintext, key, aad) {
+    const nonce = randomBytes(NONCE_LENGTH);
+    const cipher = createCipheriv("aes-256-gcm", key, nonce);
+    if (aad)
+        cipher.setAAD(aad);
+    const ciphertext = Buffer.concat([
+        cipher.update(plaintext, "utf-8"),
+        cipher.final(),
+    ]);
+    const tag = cipher.getAuthTag();
+    return {
+        nonce: nonce.toString("base64"),
+        ciphertext: ciphertext.toString("base64"),
+        tag: tag.toString("base64"),
+    };
+}
+/**
+ * Decrypt a record. Throws if the key is wrong, data is tampered,
+ * or the AAD does not match.
+ */
+export function decryptRecord(encrypted, key, aad) {
+    const nonce = Buffer.from(encrypted.nonce, "base64");
+    const ciphertext = Buffer.from(encrypted.ciphertext, "base64");
+    const tag = Buffer.from(encrypted.tag, "base64");
+    const decipher = createDecipheriv("aes-256-gcm", key, nonce);
+    if (aad)
+        decipher.setAAD(aad);
+    decipher.setAuthTag(tag);
+    const plaintext = Buffer.concat([
+        decipher.update(ciphertext),
+        decipher.final(),
+    ]);
+    return plaintext.toString("utf-8");
+}
+/**
+ * Content hash for dedup: SHA-256 over the record's content.
+ */
+export function contentHash(content) {
+    return createHash("sha256").update(content, "utf-8").digest("hex");
+}
+/** Validate a decrypted record's shape; throws on mismatch. */
+function validateSyncRecord(data) {
+    if (!data || typeof data !== "object") {
+        throw new Error("bundle contains a malformed record");
+    }
+    const r = data;
+    if (typeof r.id !== "string" || !r.id) {
+        throw new Error("bundle record has an invalid id");
+    }
+    if (typeof r.content !== "string") {
+        throw new Error(`bundle record ${r.id} has invalid content`);
+    }
+    if (typeof r.type !== "string" ||
+        !MEMORY_TYPES.includes(r.type)) {
+        throw new Error(`bundle record ${r.id} has invalid type`);
+    }
+    if (typeof r.createdAt !== "number" || typeof r.updatedAt !== "number") {
+        throw new Error(`bundle record ${r.id} has invalid timestamps`);
+    }
+    return {
+        id: r.id,
+        content: r.content,
+        summary: typeof r.summary === "string" ? r.summary : undefined,
+        type: r.type,
+        tags: Array.isArray(r.tags)
+            ? r.tags.filter((t) => typeof t === "string")
+            : [],
+        importance: typeof r.importance === "number" ? r.importance : 0.5,
+        createdAt: r.createdAt,
+        updatedAt: r.updatedAt,
+        namespace: typeof r.namespace === "string" ? r.namespace : "default",
+        metadata: r.metadata && typeof r.metadata === "object"
+            ? r.metadata
+            : {},
+        source: typeof r.source === "string" ? r.source : undefined,
+        provenance: typeof r.provenance === "string"
+            ? r.provenance
+            : undefined,
+        pool: r.pool === "note" || r.pool === "procedure" ? r.pool : "event",
+        expiresAt: typeof r.expiresAt === "number" ? r.expiresAt : null,
+        validFrom: typeof r.validFrom === "number" ? r.validFrom : null,
+        validTo: typeof r.validTo === "number" ? r.validTo : null,
+        harness: typeof r.harness === "string" ? r.harness : undefined,
+    };
+}
+/**
+ * Create an encrypted sync bundle (v2) from memory records.
+ *
+ * Every record field is encrypted; only the bundle envelope
+ * (version/exportedAt/salt/recordCount) is plaintext, and it is
+ * authenticated via GCM AAD.
+ */
+export function createBundle(records, keyOrPassphrase) {
+    const salt = randomBytes(SALT_LENGTH);
+    const key = resolveKey(keyOrPassphrase, salt);
+    const exportedAt = new Date().toISOString();
+    const aad = buildAAD({
+        version: SYNC_VERSION,
+        exportedAt,
+        salt: salt.toString("base64"),
+        recordCount: records.length,
+    });
+    const encryptedRecords = records.map((r) => {
+        const plaintext = JSON.stringify({
+            id: r.id,
+            content: r.content,
+            summary: r.summary,
+            type: r.type,
+            tags: r.tags,
+            importance: r.importance,
+            createdAt: r.createdAt,
+            updatedAt: r.updatedAt,
+            namespace: r.namespace,
+            metadata: r.metadata,
+            source: r.source,
+            provenance: r.provenance,
+            pool: r.pool,
+            expiresAt: r.expiresAt ?? null,
+            validFrom: r.validFrom ?? null,
+            validTo: r.validTo ?? null,
+            harness: r.harness,
+        });
+        const { nonce, ciphertext, tag } = encryptRecord(plaintext, key, aad);
+        return { nonce, ciphertext, tag };
+    });
+    return {
+        version: SYNC_VERSION,
+        exportedAt,
+        salt: salt.toString("base64"),
+        recordCount: records.length,
+        records: encryptedRecords,
+    };
+}
+/**
+ * Decrypt all records in a bundle. Returns validated SyncRecords with
+ * their original IDs and timestamps.
+ *
+ * Rejects v1 bundles outright: v1 left record IDs and timestamps in
+ * plaintext and cannot be upgraded safely — re-export from the source
+ * machine with the current memos.
+ */
+export function decryptBundle(bundle, keyOrPassphrase) {
+    if (bundle.version === 1) {
+        throw new Error("unsupported bundle version 1: v1 bundles expose record IDs and " +
+            "timestamps in plaintext and cannot be imported. Re-export from the " +
+            "source machine with the current memos version.");
+    }
+    if (bundle.version !== SYNC_VERSION) {
+        throw new Error(`unsupported bundle version: ${bundle.version}`);
+    }
+    if (!Array.isArray(bundle.records) ||
+        bundle.recordCount !== bundle.records.length) {
+        throw new Error("bundle metadata mismatch: recordCount does not match records");
+    }
+    const salt = Buffer.from(bundle.salt, "base64");
+    const key = resolveKey(keyOrPassphrase, salt);
+    const aad = buildAAD(bundle);
+    return bundle.records.map((r) => {
+        const plaintext = decryptRecord({ nonce: r.nonce, ciphertext: r.ciphertext, tag: r.tag }, key, aad);
+        return validateSyncRecord(JSON.parse(plaintext));
+    });
+}
+/**
+ * Write a bundle to a file (JSON).
+ */
+export function writeBundle(path, bundle) {
+    writeFileSync(path, JSON.stringify(bundle, null, 2), "utf-8");
+}
+/**
+ * Read a bundle from a file. Validates the envelope shape only —
+ * decryption (which authenticates the envelope) happens in
+ * `decryptBundle`.
+ */
+export function readBundle(path) {
+    if (!existsSync(path)) {
+        throw new Error(`bundle file not found: ${path}`);
+    }
+    const data = JSON.parse(readFileSync(path, "utf-8"));
+    if (typeof data.version !== "number" ||
+        typeof data.exportedAt !== "string" ||
+        typeof data.salt !== "string" ||
+        typeof data.recordCount !== "number" ||
+        !Array.isArray(data.records)) {
+        throw new Error("invalid sync bundle format");
+    }
+    return data;
+}
+/**
+ * Merge decrypted records into a MemOS instance, preserving original
+ * IDs and timestamps.
+ *
+ * - Content-identical records (by SHA-256 of content) are never
+ *   duplicated: skipped when any local record already has the hash.
+ * - `skip-existing`: IDs already present are skipped.
+ * - `last-write-wins`: when the incoming `updatedAt` is newer than the
+ *   local one, the local record is replaced (same ID, incoming
+ *   timestamps preserved). Equal timestamps keep the local copy.
+ */
+export async function importRecords(memos, records, strategy) {
+    const result = {
+        imported: 0,
+        skipped: 0,
+        updated: 0,
+        errors: [],
+    };
+    const graph = await memos.getGraph();
+    const nodes = graph.nodes ?? [];
+    const updatedAtById = new Map();
+    const hashes = new Set();
+    for (const n of nodes) {
+        updatedAtById.set(n.id, n.updatedAt ?? 0);
+        hashes.add(contentHash(n.content));
+    }
+    for (const r of records) {
+        try {
+            // Content-hash dedup first: identical content is never duplicated,
+            // regardless of ID or strategy.
+            if (hashes.has(contentHash(r.content))) {
+                result.skipped++;
+                continue;
+            }
+            const existingUpdatedAt = updatedAtById.get(r.id);
+            if (existingUpdatedAt === undefined) {
+                await memos.importRecord(r);
+                updatedAtById.set(r.id, r.updatedAt);
+                hashes.add(contentHash(r.content));
+                result.imported++;
+                continue;
+            }
+            if (strategy === "last-write-wins" && r.updatedAt > existingUpdatedAt) {
+                await memos.forget(r.id);
+                await memos.importRecord(r);
+                updatedAtById.set(r.id, r.updatedAt);
+                hashes.add(contentHash(r.content));
+                result.updated++;
+            }
+            else {
+                result.skipped++;
+            }
+        }
+        catch (err) {
+            result.errors.push(`${r.id}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    return result;
+}
+/**
+ * Resolve the sync key from CLI options.
+ * Priority: --key-file > --key > MEMOS_SYNC_KEY env var.
+ * When none is provided, throws — the CLI prompts interactively on a TTY.
+ */
+/**
+ * Resolve the sync key from CLI options.
+ * Priority: --passphrase-file > --passphrase > MEMOS_SYNC_KEY env var.
+ * When none is provided, throws — the CLI prompts interactively on a TTY.
+ *
+ * Note: the flag is --passphrase (not --key) because --key is already the
+ * global at-rest database encryption key in the CLI.
+ */
+export function resolveSyncKey(opts) {
+    if (opts.passphraseFile) {
+        const keyData = readFileSync(opts.passphraseFile);
+        // Allow both raw 32-byte keys and hex-encoded keys
+        const hex = keyData.toString("utf-8").trim();
+        if (/^[0-9a-fA-F]{64}$/.test(hex)) {
+            return Buffer.from(hex, "hex");
+        }
+        if (keyData.length === KEY_LENGTH) {
+            return keyData;
+        }
+        throw new Error(`key file must contain a 32-byte raw key or 64-char hex string, got ${keyData.length} bytes`);
+    }
+    if (opts.passphrase)
+        return opts.passphrase;
+    const envKey = process.env.MEMOS_SYNC_KEY;
+    if (envKey)
+        return envKey;
+    throw new Error("sync key required: use --passphrase <passphrase>, --passphrase-file <path>, or MEMOS_SYNC_KEY env var");
+}
+//# sourceMappingURL=sync.js.map

memos/_js/sync.js.map

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

memos/_js/tamper-log.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Tamper-evident mutation log.
+ *
+ * Every memory mutation (store / import / update / forget) appends one
+ * entry to an append-only, hash-chained log stored alongside the nodes
+ * in the same database. `verifyTamperLog()` recomputes the chain and —
+ * with the deep check — cross-checks each node's current full state
+ * against the latest log entry, so it detects:
+ *
+ * - edited, deleted, or reordered log rows (chain linkage breaks),
+ * - nodes edited/deleted directly in the DB without a log entry
+ *   (state-hash mismatch / missing-entry mismatch),
+ * - nodes resurrected after a `forget` entry.
+ *
+ * Honest threat model: the log is tamper-*evident*, not tamper-*proof*.
+ * An attacker with full write access to the database file can rewrite
+ * the entire chain from genesis and the log alone cannot tell. What
+ * stops that is an externally anchored checkpoint: `memos log
+ * checkpoint` prints the tip hash; write it down (paper, another
+ * machine, a signed commit) and `memos log verify --expect <hash>`
+ * later proves the chain still ends where you left it. Without an
+ * external anchor, a full-chain rewrite is undetectable — by anyone,
+ * with any local-only scheme.
+ */
+import type { MemoryNode, StorageAdapter, TamperOp } from "./types.js";
+/** Fixed `prevHash` for the first entry — a domain-separated constant. */
+export declare const GENESIS_PREV: string;
+export declare function sha256hex(s: string): string;
+/**
+ * Canonical JSON: object keys sorted recursively, arrays in order.
+ * Two equal states always serialize to the same string regardless of
+ * insertion order — required for a stable hash.
+ */
+export declare function canonicalJson(value: unknown): string;
+/**
+ * Hash of a node's full mutable state at mutation time. Covers content,
+ * summary, type, tags (sorted), importance, namespace, metadata,
+ * provenance/source, validity window, TTL, and creation/update
+ * timestamps — everything a mutation could change. Deliberately excludes
+ * `accessCount`/`lastAccessed`: reads bump those without a log entry,
+ * so hashing them would false-positive on every retrieval.
+ */
+export declare function nodeHash(node: MemoryNode): string;
+/**
+ * Hash of one log entry. The chain position `seq` is bound into the
+ * hash, so an entry cannot be replayed at a different position without
+ * invalidating it. Canonical field order and a versioned prefix make
+ * the serialization unambiguous — no JSON key-ordering games.
+ */
+export declare function entryHash(e: {
+    seq: number;
+    ts: number;
+    op: TamperOp;
+    nodeId: string;
+    nodeHash: string;
+    prevHash: string;
+}): string;
+/**
+ * Append one mutation to the log. Fail-open: when the storage adapter
+ * doesn't implement the log, or the write fails, the mutation itself
+ * is never blocked — the log is evidence, not a gate. The adapter
+ * assigns the chain position atomically (tip lookup, seq allocation,
+ * hash, insert in one transaction).
+ */
+export declare function appendTamperEntry(storage: StorageAdapter, op: TamperOp, node: MemoryNode, ts?: number): Promise<void>;
+export interface TamperVerifyIssue {
+    kind: "broken_chain" | "content_mismatch" | "deleted_without_log" | "resurrected" | "tip_mismatch";
+    seq?: number;
+    nodeId?: string;
+    detail: string;
+}
+export interface TamperVerifyResult {
+    ok: boolean;
+    supported: boolean;
+    entriesChecked: number;
+    /** Nodes that exist but predate the log (no entries) — informational. */
+    unloggedNodes: number;
+    /**
+     * Entries written by the first-day content-only format (v1). Their
+     * chain linkage is verified and their content cross-checked, but
+     * they predate full-state hashing — informational.
+     */
+    legacyEntries: number;
+    issues: TamperVerifyIssue[];
+    tipHash: string | null;
+}
+/**
+ * Verify the log: chain integrity (seq continuity, prev-hash linkage,
+ * entry-hash recomputation) plus a deep cross-check of every node's
+ * current content against its latest log entry.
+ *
+ * `expectTip` anchors the chain to an externally recorded checkpoint:
+ * verification fails unless the current tip hash equals it.
+ */
+export declare function verifyTamperLog(storage: StorageAdapter, opts?: {
+    expectTip?: string;
+}): Promise<TamperVerifyResult>;
+//# sourceMappingURL=tamper-log.d.ts.map

memos/_js/tamper-log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tamper-log.d.ts","sourceRoot":"","sources":["../src/tamper-log.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,KAAK,EACV,UAAU,EAEV,cAAc,EAEd,QAAQ,EACT,MAAM,YAAY,CAAC;AAEpB,0EAA0E;AAC1E,eAAO,MAAM,YAAY,QAEiD,CAAC;AAE3E,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE3C;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAapD;AAED;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAiCjD;AA+BD;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,QAAQ,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB,GAAG,MAAM,CAYT;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,cAAc,EACvB,EAAE,EAAE,QAAQ,EACZ,IAAI,EAAE,UAAU,EAChB,EAAE,GAAE,MAAmB,GACtB,OAAO,CAAC,IAAI,CAAC,CAYf;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EACA,cAAc,GACd,kBAAkB,GAClB,qBAAqB,GACrB,aAAa,GACb,cAAc,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,OAAO,CAAC;IACZ,SAAS,EAAE,OAAO,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,yEAAyE;IACzE,aAAa,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,iBAAiB,EAAE,CAAC;IAC5B,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED;;;;;;;GAOG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,cAAc,EACvB,IAAI,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GAChC,OAAO,CAAC,kBAAkB,CAAC,CA8K7B"}