@chainlesschain/personal-data-hub 0.1.0

package/lib/bridges/index.js

@@ -0,0 +1,44 @@
+/**
+ * Production bridges — wire the hub's pluggable sinks to ChainlessChain's
+ * existing LLM / KG / RAG infrastructure.
+ *
+ * These adapters use dependency injection (caller supplies addEntity /
+ * addRelation / chat / addDocument) so the hub package stays decoupled
+ * from cc's module system (cli is ESM, desktop main is CJS, hub is CJS).
+ *
+ * Typical wiring in desktop-app-vue/src/main:
+ *
+ *   const llmManager = require("./llm/llm-manager").getInstance();
+ *   const { addEntity, addRelation } = require("../../../packages/cli/src/lib/knowledge-graph");
+ *   const bm25 = ...;
+ *   const {
+ *     CcLLMAdapter, CcKgSink, CcRagSink
+ *   } = require("@chainlesschain/personal-data-hub/bridges");
+ *
+ *   const llm = new CcLLMAdapter({
+ *     chat: (m, o) => llmManager.chat(m, o),
+ *     getActiveProvider: () => llmManager.getActiveProvider(),
+ *     getActiveModel: () => llmManager.getActiveModel(),
+ *   });
+ *   const kgSink = new CcKgSink({ addEntity, addRelation, db });
+ *   const ragSink = new CcRagSink({ bm25 });
+ *
+ *   const registry = new AdapterRegistry({
+ *     vault, kgSink: kgSink.write.bind(kgSink), ragSink: ragSink.write.bind(ragSink),
+ *   });
+ *   const engine = new AnalysisEngine({ vault, llm });
+ */
+
+"use strict";
+
+const { CcLLMAdapter, LOCAL_PROVIDERS } = require("./cc-llm-adapter");
+const { CcKgSink, HUB_TO_CC_TYPE } = require("./cc-kg-sink");
+const { CcRagSink } = require("./cc-rag-sink");
+
+module.exports = {
+  CcLLMAdapter,
+  LOCAL_PROVIDERS,
+  CcKgSink,
+  HUB_TO_CC_TYPE,
+  CcRagSink,
+};

package/lib/constants.js

@@ -0,0 +1,92 @@
+/**
+ * UnifiedSchema enums + constants
+ *
+ * Source of truth for valid subtypes / source.capturedBy / etc.
+ * Mirrors §5 of docs/design/Personal_Data_Hub_Architecture.md
+ */
+
+"use strict";
+
+const ENTITY_TYPES = Object.freeze({
+  PERSON: "person",
+  EVENT: "event",
+  PLACE: "place",
+  ITEM: "item",
+  TOPIC: "topic",
+});
+
+const PERSON_SUBTYPES = Object.freeze({
+  SELF: "self",
+  CONTACT: "contact",
+  MERCHANT: "merchant",
+  AI_AGENT: "ai-agent",
+  UNKNOWN: "unknown",
+});
+
+const EVENT_SUBTYPES = Object.freeze({
+  // Communication
+  MESSAGE: "message",
+  AI_MESSAGE: "ai-message",
+  CALL: "call",
+  POST: "post",
+  INTERACTION: "interaction",
+
+  // Commerce
+  ORDER: "order",
+  PAYMENT: "payment",
+  TRANSFER: "transfer",
+  REFUND: "refund",
+  INCOME: "income",
+  INVESTMENT: "investment",
+  REDENVELOPE: "redenvelope",
+  UTILITY: "utility",
+  CANCELLED: "cancelled",
+
+  // Movement
+  VISIT: "visit",
+  TRIP: "trip",
+
+  // Content
+  BROWSE: "browse",
+  LIKE: "like",
+  MEDIA: "media",
+
+  // Special
+  AI_IMAGE_GENERATION: "ai-image-generation",
+
+  OTHER: "other",
+});
+
+const ITEM_SUBTYPES = Object.freeze({
+  PRODUCT: "product",
+  MEDIA: "media",
+  LINK: "link",
+  DOCUMENT: "document",
+  OTHER: "other",
+});
+
+const CAPTURED_BY = Object.freeze({
+  EXPORT: "export",
+  API: "api",
+  SQLITE: "sqlite",
+  ACCESSIBILITY: "accessibility",
+  OCR: "ocr",
+  MANUAL: "manual",
+});
+
+const AMOUNT_DIRECTIONS = Object.freeze({
+  IN: "in",
+  OUT: "out",
+});
+
+const SCHEMA_VERSION = "0.1.0";
+
+module.exports = {
+  ENTITY_TYPES,
+  PERSON_SUBTYPES,
+  EVENT_SUBTYPES,
+  ITEM_SUBTYPES,
+  CAPTURED_BY,
+  AMOUNT_DIRECTIONS,
+  SCHEMA_VERSION,
+};

package/lib/ids.js

@@ -0,0 +1,103 @@
+/**
+ * Entity ID generation — RFC 9562 UUID v7
+ *
+ * v7 chosen for time-ordered IDs — first 48 bits are unix timestamp ms,
+ * so IDs sort chronologically. This gives:
+ *   - cheap "events by time window" range queries on the id column
+ *   - SQLite B-tree locality for sequential inserts (less page splits)
+ *   - debuggability ("which one came first" without joining on occurredAt)
+ *
+ * Mirrors design doc §5.1: "id 用 UUID v7：含时间序，方便分页 / 按时间窗扫描".
+ *
+ * Hand-rolled (no `uuid` dep) because the repo currently ships uuid@9 which
+ * lacks v7. Algorithm follows RFC 9562 §5.7. ~30 LOC. No external state.
+ */
+
+"use strict";
+
+const { randomBytes } = require("node:crypto");
+
+/**
+ * Generate a UUID v7.
+ *
+ * Layout (16 bytes):
+ *   bytes 0-5: 48-bit unix_ts_ms (big-endian)
+ *   byte  6:   0111 xxxx       (version 7 + 4 rand_a bits)
+ *   byte  7:   xxxx xxxx       (8 more rand_a bits)
+ *   byte  8:   10xx xxxx       (variant + 6 rand_b bits)
+ *   bytes 9-15: 7 rand_b bytes
+ */
+function newId() {
+  const buf = Buffer.alloc(16);
+  const ts = Date.now(); // up to ~52-bit safe integer, well within 48-bit ms range until year 10895
+
+  // Split ts to avoid bit-shift precision loss above 32 bits.
+  // Top 16 bits live in tsHi; bottom 32 bits in tsLo.
+  const tsHi = Math.floor(ts / 0x100000000);
+  const tsLo = ts >>> 0;
+
+  buf[0] = (tsHi >>> 8) & 0xff;
+  buf[1] = tsHi & 0xff;
+  buf[2] = (tsLo >>> 24) & 0xff;
+  buf[3] = (tsLo >>> 16) & 0xff;
+  buf[4] = (tsLo >>> 8) & 0xff;
+  buf[5] = tsLo & 0xff;
+
+  const r = randomBytes(10);
+  buf[6] = 0x70 | (r[0] & 0x0f); // version 7
+  buf[7] = r[1];
+  buf[8] = 0x80 | (r[2] & 0x3f); // variant 10xxxxxx
+  buf[9] = r[3];
+  buf[10] = r[4];
+  buf[11] = r[5];
+  buf[12] = r[6];
+  buf[13] = r[7];
+  buf[14] = r[8];
+  buf[15] = r[9];
+
+  const hex = buf.toString("hex");
+  return (
+    hex.slice(0, 8) +
+    "-" +
+    hex.slice(8, 12) +
+    "-" +
+    hex.slice(12, 16) +
+    "-" +
+    hex.slice(16, 20) +
+    "-" +
+    hex.slice(20, 32)
+  );
+}
+
+/**
+ * Generate a deterministic ID for a given (adapter, originalId) pair.
+ * Used when an adapter wants stable IDs across re-ingests of the same row.
+ *
+ * NOTE: v0 prototype uses a random v7. Adapters that need dedup use
+ * (source.adapter, source.originalId) lookup, not id equality.
+ * v1 may switch to v5 (name-based) if deterministic IDs become necessary.
+ */
+function newIdForSource(_adapter, _originalId) {
+  return newId();
+}
+
+/**
+ * Extract the millisecond timestamp embedded in a UUID v7.
+ * Returns null for non-v7 UUIDs.
+ */
+function timestampFromId(id) {
+  if (typeof id !== "string" || id.length !== 36) return null;
+  if (id.charAt(14) !== "7") return null;
+  // First 48 bits = chars 0..7 (32 bits) + chars 9..12 (16 bits)
+  const hi = parseInt(id.slice(0, 8), 16);
+  const lo = parseInt(id.slice(9, 13), 16);
+  if (!Number.isFinite(hi) || !Number.isFinite(lo)) return null;
+  const ms = hi * 0x10000 + lo;
+  return ms;
+}
+
+module.exports = {
+  newId,
+  newIdForSource,
+  timestampFromId,
+};

package/lib/index.js

@@ -0,0 +1,141 @@
+/**
+ * @chainlesschain/personal-data-hub
+ *
+ * UnifiedSchema, validators, SQLCipher LocalVault, AdapterRegistry, and
+ * the natural-language AnalysisEngine for the Personal Data Hub middleware.
+ *
+ * Phase 0 (landed): constants / ids / schemas / batch
+ * Phase 1 (landed): vault / migrations / key-providers
+ * Phase 2 (landed): adapter-spec / kg-derive / rag-derive / registry / mock-adapter
+ * Phase 3 (this):   query-parser / prompt-builder / llm-client / analysis
+ *
+ * See docs/design/Personal_Data_Hub_Architecture.md.
+ */
+
+"use strict";
+
+const constants = require("./constants");
+const ids = require("./ids");
+const schemas = require("./schemas");
+const batch = require("./batch");
+const migrations = require("./migrations");
+const keyProviders = require("./key-providers");
+const { LocalVault } = require("./vault");
+const adapterSpec = require("./adapter-spec");
+const kgDerive = require("./kg-derive");
+const ragDerive = require("./rag-derive");
+const { AdapterRegistry, DEFAULT_BATCH_SIZE } = require("./registry");
+const { MockAdapter } = require("./mock-adapter");
+const queryParser = require("./query-parser");
+const promptBuilder = require("./prompt-builder");
+const { MockLLMClient, OllamaClient } = require("./llm-client");
+const { AnalysisEngine, DEFAULT_MAX_FACTS, DEFAULT_MAX_QUERY_LIMIT } = require("./analysis");
+const bridges = require("./bridges");
+const emailImapAdapter = require("./adapters/email-imap");
+
+module.exports = {
+  // Constants / enums
+  ...constants,
+
+  // ID generation
+  newId: ids.newId,
+  newIdForSource: ids.newIdForSource,
+  timestampFromId: ids.timestampFromId,
+
+  // Per-entity validators
+  validate: schemas.validate,
+  validatePerson: schemas.validatePerson,
+  validateEvent: schemas.validateEvent,
+  validatePlace: schemas.validatePlace,
+  validateItem: schemas.validateItem,
+  validateTopic: schemas.validateTopic,
+
+  // Batch helpers
+  emptyBatch: batch.emptyBatch,
+  mergeBatches: batch.mergeBatches,
+  validateBatch: batch.validateBatch,
+  partitionBatch: batch.partitionBatch,
+
+  // Migrations
+  MIGRATIONS: migrations.MIGRATIONS,
+  TARGET_SCHEMA_VERSION: migrations.TARGET_VERSION,
+  applyMigrations: migrations.applyMigrations,
+  getSchemaVersion: migrations.getSchemaVersion,
+
+  // Key providers
+  KEY_HEX_LEN: keyProviders.KEY_HEX_LEN,
+  isValidKeyHex: keyProviders.isValidKeyHex,
+  generateKeyHex: keyProviders.generateKeyHex,
+  InMemoryKeyProvider: keyProviders.InMemoryKeyProvider,
+  FileKeyProvider: keyProviders.FileKeyProvider,
+
+  // Vault
+  LocalVault,
+
+  // Adapter contract
+  SENSITIVITY_LEVELS: adapterSpec.SENSITIVITY_LEVELS,
+  assertAdapter: adapterSpec.assertAdapter,
+
+  // KG + RAG derivation
+  triple: kgDerive.triple,
+  deriveEventTriples: kgDerive.deriveEventTriples,
+  derivePersonTriples: kgDerive.derivePersonTriples,
+  derivePlaceTriples: kgDerive.derivePlaceTriples,
+  deriveItemTriples: kgDerive.deriveItemTriples,
+  deriveTopicTriples: kgDerive.deriveTopicTriples,
+  deriveBatchTriples: kgDerive.deriveBatchTriples,
+  deriveEntityTriples: kgDerive.deriveEntityTriples,
+  eventToRagDoc: ragDerive.eventToRagDoc,
+  personToRagDoc: ragDerive.personToRagDoc,
+  placeToRagDoc: ragDerive.placeToRagDoc,
+  itemToRagDoc: ragDerive.itemToRagDoc,
+  topicToRagDoc: ragDerive.topicToRagDoc,
+  entityToRagDoc: ragDerive.entityToRagDoc,
+  deriveBatchDocs: ragDerive.deriveBatchDocs,
+
+  // Registry + reference adapter
+  AdapterRegistry,
+  DEFAULT_BATCH_SIZE,
+  MockAdapter,
+
+  // Query parser
+  parseQuery: queryParser.parseQuery,
+  parseTimeWindow: queryParser.parseTimeWindow,
+  parseFilters: queryParser.parseFilters,
+  parseIntent: queryParser.parseIntent,
+
+  // Prompt builder
+  DEFAULT_SYSTEM_PROMPT: promptBuilder.DEFAULT_SYSTEM_PROMPT,
+  buildPrompt: promptBuilder.buildPrompt,
+  summarizeFact: promptBuilder.summarizeFact,
+  parseCitations: promptBuilder.parseCitations,
+  validateCitations: promptBuilder.validateCitations,
+
+  // LLM clients (pluggable; production wires CcLLMAdapter)
+  MockLLMClient,
+  OllamaClient,
+
+  // Analysis engine
+  AnalysisEngine,
+  DEFAULT_MAX_FACTS,
+  DEFAULT_MAX_QUERY_LIMIT,
+
+  // Bridges to existing cc infrastructure (LLM / KG / RAG)
+  CcLLMAdapter: bridges.CcLLMAdapter,
+  CcKgSink: bridges.CcKgSink,
+  CcRagSink: bridges.CcRagSink,
+  HUB_TO_CC_TYPE: bridges.HUB_TO_CC_TYPE,
+  LOCAL_PROVIDERS: bridges.LOCAL_PROVIDERS,
+
+  // Phase 5.1 — first real production adapter (IMAP email)
+  EmailAdapter: emailImapAdapter.EmailAdapter,
+  EMAIL_PROVIDERS: emailImapAdapter.EMAIL_PROVIDERS,
+  resolveEmailProvider: emailImapAdapter.resolveEmailProvider,
+  parseEmailWatermark: emailImapAdapter.parseWatermark,
+  formatEmailWatermark: emailImapAdapter.formatWatermark,
+  ImapSession: emailImapAdapter.ImapSession,
+  ImapAuthFailedError: emailImapAdapter.ImapAuthFailedError,
+  ImapConnectionFailedError: emailImapAdapter.ImapConnectionFailedError,
+  ImapMailboxNotFoundError: emailImapAdapter.ImapMailboxNotFoundError,
+  parseRawEmail: emailImapAdapter.parseRawEmail,
+};

package/lib/key-providers.js

@@ -0,0 +1,146 @@
+/**
+ * Master-key storage providers.
+ *
+ * The vault doesn't care WHERE the master key lives — just that something
+ * implements get(name) / set(name, key) / del(name) for hex-encoded 32-byte
+ * keys. This package ships two providers for dev / testing:
+ *
+ *   - InMemoryKeyProvider — RAM only, lost on process exit (tests)
+ *   - FileKeyProvider     — stores hex blobs under <dir>/<name>.key with
+ *                            0600 perms (single-user dev box, or fallback
+ *                            when no platform keystore is available)
+ *
+ * Production integrations live OUTSIDE this package and conform to the
+ * KeyProvider interface:
+ *   - Windows DPAPI                (electron main process, win)
+ *   - macOS Keychain               (electron main process, mac)
+ *   - Linux libsecret              (electron main process, linux)
+ *   - Android Keystore (TEE/StrongBox) (Android app, native bridge)
+ *   - iOS Keychain                 (iOS app, native bridge)
+ *
+ * Plus an optional U-Key / SIMKey second-layer wrap (out of scope here).
+ *
+ * KeyProvider contract:
+ *   get(name: string): Promise<string|null>   // hex or null if missing
+ *   set(name: string, hexKey: string): Promise<void>
+ *   del(name: string): Promise<void>
+ *   has(name: string): Promise<boolean>
+ *
+ * Key naming convention recommended:
+ *   "vault:<vault-id>"      master key for a vault
+ *   "vault:<vault-id>:prev" pre-rotation key, kept for emergency recovery
+ *   "adapter:<name>:cookie" per-adapter cookie blobs (later phases)
+ */
+
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const crypto = require("node:crypto");
+
+const KEY_HEX_LEN = 64; // 32 bytes = 64 hex chars
+
+function isValidKeyHex(hex) {
+  return typeof hex === "string" && hex.length === KEY_HEX_LEN && /^[0-9a-fA-F]+$/.test(hex);
+}
+
+/** Generate a fresh random 32-byte master key, returned hex-encoded. */
+function generateKeyHex() {
+  return crypto.randomBytes(32).toString("hex");
+}
+
+// ─── InMemoryKeyProvider ─────────────────────────────────────────────────
+
+class InMemoryKeyProvider {
+  constructor() {
+    this._keys = new Map();
+  }
+  async get(name) {
+    return this._keys.has(name) ? this._keys.get(name) : null;
+  }
+  async set(name, hex) {
+    if (!isValidKeyHex(hex)) {
+      throw new Error("InMemoryKeyProvider.set: hex must be 64 lowercase/uppercase hex chars");
+    }
+    this._keys.set(name, hex);
+  }
+  async del(name) {
+    this._keys.delete(name);
+  }
+  async has(name) {
+    return this._keys.has(name);
+  }
+}
+
+// ─── FileKeyProvider ─────────────────────────────────────────────────────
+
+/**
+ * Stores each key as a separate file at <dir>/<safe-name>.key with 0600
+ * permissions. POSIX-only protection; on Windows the perms request becomes
+ * a no-op (Windows file ACLs aren't expressible via POSIX mode bits without
+ * additional libraries). This is FINE for dev / tests — production setups
+ * should plug in DPAPI/Keychain via a custom KeyProvider.
+ *
+ * Name sanitization: any char outside [A-Za-z0-9_.-] is replaced with "_"
+ * to keep the filesystem happy. Colons in canonical names ("vault:abc")
+ * become underscores ("vault_abc.key"). Originally-distinct names that
+ * collide after sanitization will overwrite each other — callers should
+ * avoid collisions or use a different provider.
+ */
+class FileKeyProvider {
+  constructor(dir) {
+    if (typeof dir !== "string" || dir.length === 0) {
+      throw new Error("FileKeyProvider: dir must be a non-empty path");
+    }
+    this.dir = dir;
+    fs.mkdirSync(this.dir, { recursive: true });
+  }
+
+  _pathFor(name) {
+    const safe = String(name).replace(/[^A-Za-z0-9_.-]/g, "_");
+    return path.join(this.dir, safe + ".key");
+  }
+
+  async get(name) {
+    const p = this._pathFor(name);
+    if (!fs.existsSync(p)) return null;
+    const buf = fs.readFileSync(p, "utf8").trim();
+    if (!isValidKeyHex(buf)) {
+      // Stored file corrupt — fail loudly instead of silently returning null
+      // so the user knows their vault key is gone and can act.
+      throw new Error(`FileKeyProvider: stored key at ${p} is not valid hex`);
+    }
+    return buf;
+  }
+
+  async set(name, hex) {
+    if (!isValidKeyHex(hex)) {
+      throw new Error("FileKeyProvider.set: hex must be 64 hex chars (32 bytes)");
+    }
+    const p = this._pathFor(name);
+    // mode 0600: rw for owner only. On Windows this is ignored by Node.
+    fs.writeFileSync(p, hex, { encoding: "utf8", mode: 0o600 });
+    try {
+      fs.chmodSync(p, 0o600);
+    } catch (_err) {
+      // Windows — fs.chmod silently ignores most mode bits. Not fatal.
+    }
+  }
+
+  async del(name) {
+    const p = this._pathFor(name);
+    if (fs.existsSync(p)) fs.unlinkSync(p);
+  }
+
+  async has(name) {
+    return fs.existsSync(this._pathFor(name));
+  }
+}
+
+module.exports = {
+  KEY_HEX_LEN,
+  isValidKeyHex,
+  generateKeyHex,
+  InMemoryKeyProvider,
+  FileKeyProvider,
+};