@mnemosyne_os/sdk 1.0.0

package/dist/index.js

@@ -0,0 +1,479 @@
+// src/client.ts
+import WebSocket from "ws";
+
+// src/manifest.ts
+import { z } from "zod";
+import { readFileSync } from "fs";
+import { resolve } from "path";
+var VALID_SCOPES = [
+  "vault:read:DEV",
+  "vault:write:DEV",
+  "vault:read:SOCIAL",
+  "vault:write:SOCIAL",
+  "vault:read:PERSONAL",
+  "vault:write:PERSONAL",
+  "vault:read:FINANCE",
+  "vault:write:FINANCE",
+  "vault:read:COOK",
+  "vault:write:COOK",
+  "share:request",
+  "share:grant"
+];
+var VALID_INTENTS = ["INGEST", "QUERY", "CORRELATE", "FORGET"];
+var VALID_VAULTS = ["DEV", "SOCIAL", "PERSONAL", "FINANCE", "COOK"];
+var SEMVER_RE = /^\d+\.\d+\.\d+/;
+var APP_ID_RE = /^[a-z0-9][a-z0-9_-]{1,63}$/;
+var AppManifestSchema = z.object({
+  id: z.string().regex(APP_ID_RE, {
+    message: "id must be lowercase alphanumeric with hyphens/underscores, 2-64 chars"
+  }),
+  name: z.string().min(2).max(64),
+  version: z.string().regex(SEMVER_RE, { message: "version must be SemVer (e.g. 1.0.0)" }),
+  author: z.string().max(64).optional(),
+  mnemosyne_sdk: z.string().regex(/^\^?\d+\.\d+\.\d+/, {
+    message: "mnemosyne_sdk must be a SemVer range (e.g. ^1.0.0)"
+  }),
+  scopes: z.array(z.enum(VALID_SCOPES)).min(1, {
+    message: "At least one scope required \u2014 apps with no scopes have no access"
+  }),
+  vaults: z.array(z.enum(VALID_VAULTS)).min(1),
+  intents: z.array(z.enum(VALID_INTENTS)).min(1),
+  max_chronicle_size_kb: z.number().int().min(1).max(1024).optional().default(64),
+  requires_consent: z.boolean().optional().default(false),
+  description: z.string().max(256).optional()
+}).strict();
+function loadManifest(pathOrManifest) {
+  if (typeof pathOrManifest === "string") {
+    const absPath = resolve(pathOrManifest);
+    let raw;
+    try {
+      raw = JSON.parse(readFileSync(absPath, "utf-8"));
+    } catch {
+      throw new Error(`[MnemoSDK] Cannot read manifest at: ${absPath}`);
+    }
+    return parseManifest(raw);
+  }
+  return parseManifest(pathOrManifest);
+}
+function parseManifest(raw) {
+  const result = AppManifestSchema.safeParse(raw);
+  if (!result.success) {
+    const issues = result.error.issues.map((i) => `  \u2022 ${i.path.join(".")}: ${i.message}`).join("\n");
+    throw new Error(`[MnemoSDK] Invalid app.manifest.json:
+${issues}`);
+  }
+  return result.data;
+}
+function assertScope(manifest, scope) {
+  if (!manifest.scopes.includes(scope)) {
+    throw new Error(
+      `[MnemoSDK] Scope "${scope}" not declared in manifest for app "${manifest.id}". Add it to manifest.scopes to request this permission.`
+    );
+  }
+}
+function assertVault(manifest, vault) {
+  if (!manifest.vaults.includes(vault)) {
+    throw new Error(
+      `[MnemoSDK] Vault "${vault}" not in manifest.vaults for app "${manifest.id}".`
+    );
+  }
+}
+
+// src/jwt.ts
+import { createHmac, randomBytes, timingSafeEqual } from "crypto";
+function b64url(input) {
+  const buf = typeof input === "string" ? Buffer.from(input, "utf8") : input;
+  return buf.toString("base64url");
+}
+function parseB64url(input) {
+  return Buffer.from(input, "base64url").toString("utf8");
+}
+var HEADER = b64url(JSON.stringify({ alg: "HS256", typ: "JWT" }));
+function signToken(payload, secret) {
+  const payloadB64 = b64url(JSON.stringify(payload));
+  const data = `${HEADER}.${payloadB64}`;
+  const sig = createHmac("sha256", secret).update(data).digest();
+  return `${data}.${b64url(sig)}`;
+}
+function verifyToken(token, secret) {
+  const parts = token.split(".");
+  if (parts.length !== 3) {
+    return { valid: false, reason: "MALFORMED_TOKEN" };
+  }
+  const [headerB64, payloadB64, sigB64] = parts;
+  const data = `${headerB64}.${payloadB64}`;
+  const expectedSig = createHmac("sha256", secret).update(data).digest();
+  const actualSig = Buffer.from(sigB64, "base64url");
+  if (expectedSig.length !== actualSig.length || !timingSafeEqual(expectedSig, actualSig)) {
+    return { valid: false, reason: "INVALID_SIGNATURE" };
+  }
+  let payload;
+  try {
+    payload = JSON.parse(parseB64url(payloadB64));
+  } catch {
+    return { valid: false, reason: "MALFORMED_PAYLOAD" };
+  }
+  const now = Math.floor(Date.now() / 1e3);
+  if (payload.exp < now) {
+    return { valid: false, reason: "TOKEN_EXPIRED" };
+  }
+  return { valid: true, payload };
+}
+function generateAppToken(appId, scopes, secret, ttlMs = 24 * 60 * 60 * 1e3) {
+  const iat = Math.floor(Date.now() / 1e3);
+  const exp = Math.floor((Date.now() + ttlMs) / 1e3);
+  const payload = {
+    sub: appId,
+    iat,
+    exp,
+    scopes,
+    jti: randomBytes(16).toString("hex")
+  };
+  return {
+    token: signToken(payload, secret),
+    expiresAt: exp * 1e3
+  };
+}
+function generateSecret() {
+  return randomBytes(32).toString("hex");
+}
+
+// src/client.ts
+var MnemoClient = class _MnemoClient {
+  manifest;
+  options;
+  ws = null;
+  token = null;
+  connected = false;
+  pending = /* @__PURE__ */ new Map();
+  handlers = /* @__PURE__ */ new Map();
+  // ── Static factory ──────────────────────────────────────────────────────────
+  /**
+   * Crée et connecte un client Mnemosyne.
+   * @throws si le manifest est invalide ou la connexion échoue
+   */
+  static async connect(options) {
+    const client = new _MnemoClient(options);
+    await client._connect();
+    return client;
+  }
+  constructor(options) {
+    this.manifest = loadManifest(options.manifest);
+    this.options = {
+      appId: options.appId,
+      manifest: options.manifest,
+      transport: options.transport ?? "auto",
+      wsPort: options.wsPort ?? 7799,
+      token: options.token ?? "",
+      timeoutMs: options.timeoutMs ?? 3e4
+    };
+    if (this.options.appId !== this.manifest.id) {
+      throw new Error(
+        `[MnemoSDK] appId "${this.options.appId}" does not match manifest.id "${this.manifest.id}"`
+      );
+    }
+  }
+  // ── Connection ──────────────────────────────────────────────────────────────
+  async _connect() {
+    const transport = this._resolveTransport();
+    if (transport === "ws") {
+      await this._connectWs();
+    } else {
+      this._connectIpc();
+    }
+    if (!this.options.token) {
+      const reg = await this._register();
+      this.token = reg.token;
+    } else {
+      this.token = this.options.token;
+    }
+    this.connected = true;
+    this._emit("connected", { appId: this.manifest.id });
+    console.log(`[MnemoSDK] \u2713 Connected as "${this.manifest.id}" via ${transport}`);
+  }
+  _resolveTransport() {
+    if (this.options.transport === "ipc") return "ipc";
+    if (this.options.transport === "ws") return "ws";
+    const hasIpc = typeof globalThis !== "undefined" && typeof globalThis["window"] !== "undefined" && typeof globalThis["window"]["mnemosyne"] !== "undefined";
+    return hasIpc ? "ipc" : "ws";
+  }
+  _connectWs() {
+    return new Promise((resolve2, reject) => {
+      const url = `ws://localhost:${this.options.wsPort}`;
+      this.ws = new WebSocket(url);
+      const timeout = setTimeout(() => {
+        this.ws?.terminate();
+        reject(new Error(`[MnemoSDK] Connection timeout to ${url}`));
+      }, this.options.timeoutMs);
+      this.ws.on("open", () => {
+        clearTimeout(timeout);
+        resolve2();
+      });
+      this.ws.on("message", (raw) => {
+        try {
+          const msg = JSON.parse(raw.toString());
+          if ("id" in msg) {
+            this._handleRpcResponse(msg);
+          } else if ("type" in msg) {
+            this._handleEvent(msg);
+          }
+        } catch {
+        }
+      });
+      this.ws.on("error", (err) => {
+        this._emit("error", { message: err.message });
+      });
+      this.ws.on("close", () => {
+        this.connected = false;
+        this._emit("disconnected", {});
+        for (const [, p] of this.pending) {
+          clearTimeout(p.timer);
+          p.reject(new Error("[MnemoSDK] WebSocket disconnected"));
+        }
+        this.pending.clear();
+      });
+    });
+  }
+  _connectIpc() {
+    this.connected = true;
+  }
+  // ── RPC layer ───────────────────────────────────────────────────────────────
+  async _rpc(method, params) {
+    if (!this.connected && method !== "sdk.register") {
+      throw new Error("[MnemoSDK] Client not connected. Call MnemoClient.connect() first.");
+    }
+    if (this._resolveTransport() === "ipc") {
+      return this._rpcIpc(method, params);
+    }
+    return this._rpcWs(method, params);
+  }
+  _rpcWs(method, params) {
+    return new Promise((resolve2, reject) => {
+      if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+        return reject(new Error("[MnemoSDK] WebSocket not open"));
+      }
+      const id = Math.random().toString(36).slice(2);
+      const req = { id, method, params, ...this.token ? { token: this.token } : {} };
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error(`[MnemoSDK] RPC timeout: ${method}`));
+      }, this.options.timeoutMs);
+      this.pending.set(id, {
+        resolve: (v) => resolve2(v),
+        reject,
+        timer
+      });
+      this.ws.send(JSON.stringify(req));
+    });
+  }
+  async _rpcIpc(method, params) {
+    const mnemo = globalThis["window"];
+    if (!mnemo?.mnemosyne) {
+      throw new Error("[MnemoSDK] IPC transport: window.mnemosyne not available");
+    }
+    const ipcMap = {
+      "sdk.register": "registerApp",
+      "sdk.ingest": "sendPulse",
+      "sdk.query": "sendPulse",
+      "sdk.correlate": "sendPulse",
+      "sdk.share": "requestCrossAppShare",
+      "sdk.nft.validate": "validateNFTLicense",
+      "sdk.graph.query": "queryNeuralGraph"
+    };
+    const ipcMethod = ipcMap[method];
+    if (!ipcMethod || !mnemo.mnemosyne[ipcMethod]) {
+      throw new Error(`[MnemoSDK] IPC method not found for: ${method}`);
+    }
+    return mnemo.mnemosyne[ipcMethod](params);
+  }
+  _handleRpcResponse(msg) {
+    const p = this.pending.get(msg.id);
+    if (!p) return;
+    clearTimeout(p.timer);
+    this.pending.delete(msg.id);
+    if (msg.error) {
+      p.reject(new Error(msg.error));
+    } else {
+      p.resolve(msg.result);
+    }
+  }
+  _handleEvent(event) {
+    this._emit(event.type, event.data);
+  }
+  // ── Auth ────────────────────────────────────────────────────────────────────
+  async _register() {
+    return this._rpc("sdk.register", {
+      manifest: this.manifest
+    });
+  }
+  /**
+   * Renouvelle le token JWT avant expiration.
+   * Appelé automatiquement si le token expire dans moins de 5 minutes.
+   */
+  async renewToken() {
+    const reg = await this._register();
+    this.token = reg.token;
+    console.log(`[MnemoSDK] Token renewed for "${this.manifest.id}", expires: ${new Date(reg.expiresAt).toISOString()}`);
+  }
+  // ── Public API ──────────────────────────────────────────────────────────────
+  /**
+   * Ingère du contenu dans le vault Mnemosyne.
+   * Isolé par source_app_id — seule ton app peut lire ce qu'elle écrit.
+   */
+  async ingest(payload) {
+    assertScope(this.manifest, `vault:write:${payload.vault}`);
+    assertVault(this.manifest, payload.vault);
+    if (!this.manifest.intents.includes("INGEST")) {
+      throw new Error('[MnemoSDK] Intent "INGEST" not declared in manifest');
+    }
+    const maxBytes = (this.manifest.max_chronicle_size_kb ?? 64) * 1024;
+    if (new TextEncoder().encode(payload.content).length > maxBytes) {
+      throw new Error(`[MnemoSDK] Content exceeds max_chronicle_size_kb (${this.manifest.max_chronicle_size_kb}KB)`);
+    }
+    return this._rpc("sdk.ingest", {
+      appId: this.manifest.id,
+      ...payload
+    });
+  }
+  /**
+   * Requête sémantique — retourne uniquement les chronicles de ton app (source_app_id isolation).
+   */
+  async query(text, options = {}) {
+    const vault = options.vault ?? this.manifest.vaults[0];
+    assertScope(this.manifest, `vault:read:${vault}`);
+    if (!this.manifest.intents.includes("QUERY")) {
+      throw new Error('[MnemoSDK] Intent "QUERY" not declared in manifest');
+    }
+    return this._rpc("sdk.query", {
+      appId: this.manifest.id,
+      text,
+      vault,
+      limit: options.limit ?? 10,
+      threshold: options.threshold ?? 0
+    });
+  }
+  /**
+   * Demande un accès aux chronicles d'une autre app.
+   * Déclenche un popup de consentement utilisateur dans Mnemosyne OS.
+   * Timeout : 60s par défaut (configurable).
+   */
+  async requestShare(request) {
+    assertScope(this.manifest, "share:request");
+    return this._rpc("sdk.share", {
+      requestingAppId: this.manifest.id,
+      fromAppId: request.fromAppId,
+      reason: request.reason,
+      timeoutMs: request.timeoutMs ?? 6e4
+    });
+  }
+  // ── Events ──────────────────────────────────────────────────────────────────
+  on(type, handler) {
+    if (!this.handlers.has(type)) {
+      this.handlers.set(type, /* @__PURE__ */ new Set());
+    }
+    this.handlers.get(type).add(handler);
+    return () => this.handlers.get(type)?.delete(handler);
+  }
+  _emit(type, data) {
+    const set = this.handlers.get(type);
+    if (!set) return;
+    const event = { type, data, timestamp: Date.now() };
+    for (const h of set) h(event);
+  }
+  // ── Lifecycle ───────────────────────────────────────────────────────────────
+  /**
+   * Ferme proprement la connexion.
+   * Attend la résolution de tous les RPC en cours.
+   */
+  async disconnect() {
+    this.connected = false;
+    if (this.ws) {
+      this.ws.close(1e3, "Client disconnect");
+      this.ws = null;
+    }
+    for (const [, p] of this.pending) {
+      clearTimeout(p.timer);
+      p.reject(new Error("[MnemoSDK] Client disconnected"));
+    }
+    this.pending.clear();
+    console.log(`[MnemoSDK] Disconnected: "${this.manifest.id}"`);
+  }
+  get isConnected() {
+    return this.connected;
+  }
+  get appId() {
+    return this.manifest.id;
+  }
+  get appManifest() {
+    return { ...this.manifest };
+  }
+  /** Inspecte le token actuel (décodé, sans vérification) */
+  get tokenInfo() {
+    if (!this.token) return null;
+    try {
+      const [, payloadB64] = this.token.split(".");
+      if (!payloadB64) return null;
+      return JSON.parse(Buffer.from(payloadB64, "base64url").toString("utf8"));
+    } catch {
+      return null;
+    }
+  }
+};
+
+// src/constants.ts
+var MNEMOSYNE_METHODS = {
+  // ── Auth ──────────────────────────────────────────────────────────────────
+  /** Enregistre l'app, valide le manifest, retourne un JWT 24h */
+  REGISTER: "sdk.register",
+  // ── Vault ─────────────────────────────────────────────────────────────────
+  /** Ingère du contenu dans le vault (vectorisation incluse) */
+  INGEST: "sdk.ingest",
+  /** Requête sémantique — résultats filtrés par source_app_id */
+  QUERY: "sdk.query",
+  /** Trouve les connexions causales entre deux contenus */
+  CORRELATE: "sdk.correlate",
+  /** Supprime un chronicle par ID (scope vault:write requis) */
+  FORGET: "sdk.forget",
+  // ── Cross-App ─────────────────────────────────────────────────────────────
+  /** Demande d'accès aux chronicles d'une autre app (popup consentement) */
+  SHARE: "sdk.share",
+  // ── NFT Licence ───────────────────────────────────────────────────────────
+  /**
+   * Vérifie qu'un wallet possède le NFT de licence de cette app.
+   * Requiert le scope `nft:validate` dans le manifest.
+   * Cache TTL 5 min côté OS pour ne pas spam la blockchain.
+   */
+  NFT_VALIDATE: "sdk.nft.validate",
+  // ── NeuralGraph ───────────────────────────────────────────────────────────
+  /**
+   * Requête le NeuralGraph — retourne les nœuds et arêtes proches du texte.
+   * Requiert le scope `neural:graph:read` dans le manifest.
+   */
+  GRAPH_QUERY: "sdk.graph.query"
+};
+var MNEMOSYNE_WS_PORT = 7799;
+var MNEMOSYNE_WS_HOST = "127.0.0.1";
+var MNEMOSYNE_TOKEN_TTL_S = 24 * 60 * 60;
+var MNEMOSYNE_NFT_CACHE_TTL_MS = 5 * 60 * 1e3;
+var MNEMOSYNE_CHAINS = {
+  BASE: { id: 8453, name: "Base", rpc: "https://mainnet.base.org" },
+  POLYGON: { id: 137, name: "Polygon", rpc: "https://polygon-rpc.com" },
+  BASE_SEPOLIA: { id: 84532, name: "Base Sepolia (testnet)", rpc: "https://sepolia.base.org" }
+};
+export {
+  AppManifestSchema,
+  MNEMOSYNE_CHAINS,
+  MNEMOSYNE_METHODS,
+  MNEMOSYNE_NFT_CACHE_TTL_MS,
+  MNEMOSYNE_TOKEN_TTL_S,
+  MNEMOSYNE_WS_HOST,
+  MNEMOSYNE_WS_PORT,
+  MnemoClient,
+  assertScope,
+  assertVault,
+  generateAppToken,
+  generateSecret,
+  loadManifest,
+  parseManifest,
+  verifyToken
+};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@mnemosyne_os/sdk",
+  "version": "1.0.0",
+  "description": "Official SDK for building Layer 2 apps on Mnemosyne OS — connects to the local AI memory runtime via WebSocket or Electron IPC.",
+  "keywords": ["mnemosyne", "ai", "memory", "vector", "sdk", "sovereign", "layer2", "local-ai", "electron"],
+  "author": {
+    "name": "Tony Trochet",
+    "email": "tony@xpacegems.com",
+    "url": "https://www.linkedin.com/in/tony-t-19544650/"
+  },
+  "license": "MIT",
+  "homepage": "https://github.com/yaka0007/Mnemosyne-Neural-OS",
+  "repository": { "type": "git", "url": "https://github.com/yaka0007/Mnemosyne-Neural-OS.git" },
+  "bugs": { "url": "https://github.com/yaka0007/Mnemosyne-Neural-OS/issues" },
+  "publishConfig": { "access": "public", "registry": "https://registry.npmjs.org/" },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": ["dist", "README.md"],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "dev": "tsup src/index.ts --format esm,cjs --dts --watch",
+    "typecheck": "tsc --noEmit",
+    "release": "npm run typecheck && npm run build && npm publish --access public",
+    "release:patch": "npm run typecheck && npm run build && npm version patch --no-git-tag-version && npm publish --access public",
+    "release:minor": "npm run typecheck && npm run build && npm version minor --no-git-tag-version && npm publish --access public",
+    "release:major": "npm run typecheck && npm run build && npm version major --no-git-tag-version && npm publish --access public"
+  },
+  "dependencies": {
+    "zod": "^3.22.4",
+    "ws": "^8.16.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@types/ws": "^8.5.10",
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.0"
+  },
+  "peerDependencies": {},
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}