@mnemosyne_os/sdk 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,443 @@
+import { z } from 'zod';
+
+/**
+ * @mnemosyne/sdk — Public Types
+ *
+ * Ce fichier est la surface publique du SDK.
+ * Toute modification ici constitue un changement de contrat API.
+ *
+ * [SDK][ZERO-TRUST][AUDIT-TRAIL]
+ */
+/** Scopes disponibles pour une app tierce */
+type MnemoScope = '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'
+/** Validation de licence NFT on-chain pour MnemoStore */
+ | 'nft:validate'
+/** Accès en lecture au NeuralGraph (nœuds, arêtes, clusters) */
+ | 'neural:graph:read'
+/** Requêtes LLM directes via le runtime Mnemosyne — scope premium */
+ | 'llm:query';
+/** Intents IPC autorisés */
+type MnemoIntent = 'INGEST' | 'QUERY' | 'CORRELATE' | 'FORGET';
+/** Vault cible */
+type MnemoVault = 'DEV' | 'SOCIAL' | 'PERSONAL' | 'FINANCE' | 'COOK';
+/** Types de spine */
+type SpineType = 'GIT' | 'ARCHITECTURE' | 'DECISION' | 'DEBUG' | 'FEATURE' | 'REDDIT_POST' | 'LINKEDIN_POST' | 'SOCIAL_NODE' | 'DOCUMENT' | 'NOTE' | 'CUSTOM';
+/** Manifest de l'application — fichier `app.manifest.json` */
+interface AppManifest {
+    /** Identifiant unique stable de l'app (snake_case recommandé) */
+    id: string;
+    /** Nom affiché à l'utilisateur */
+    name: string;
+    /** Version SemVer */
+    version: string;
+    /** Auteur ou organisation */
+    author?: string;
+    /** Version du SDK requise */
+    mnemosyne_sdk: string;
+    /** Scopes demandés — Zero-Trust : tout scope non listé est refusé */
+    scopes: MnemoScope[];
+    /** Vaults accessibles */
+    vaults: MnemoVault[];
+    /** Intents IPC autorisés */
+    intents: MnemoIntent[];
+    /** Taille maximale d'une chronicle (KB) — défaut 64KB */
+    max_chronicle_size_kb?: number;
+    /**
+     * Si true, chaque requête inter-app déclenche un popup de consentement utilisateur.
+     * Si false, le consentement est demandé une seule fois et mémorisé.
+     */
+    requires_consent?: boolean;
+    /** Description courte affichée dans le Synaptic Hub */
+    description?: string;
+}
+interface MnemoClientOptions {
+    /** Identifiant de l'app — doit correspondre à AppManifest.id */
+    appId: string;
+    /** Chemin vers app.manifest.json ou objet manifest inline */
+    manifest: string | AppManifest;
+    /**
+     * Transport à utiliser :
+     *   'ws'  → WebSocket local (app Node.js externe à Mnemosyne)
+     *   'ipc' → Electron IPC (app embarquée via PluginHub)
+     *   'auto' → Détecte automatiquement selon l'environnement (défaut)
+     */
+    transport?: 'ws' | 'ipc' | 'auto';
+    /** Port du WebSocket server Mnemosyne (défaut: 7799) */
+    wsPort?: number;
+    /** Token JWT d'authentification (obtenu via MnemoClient.register) */
+    token?: string;
+    /** Timeout des requêtes en ms (défaut: 30000) */
+    timeoutMs?: number;
+}
+interface IngestPayload {
+    /** Contenu textuel brut à vectoriser */
+    content: string;
+    /** Type de spine sémantique */
+    spineType: SpineType;
+    /** Vault de destination */
+    vault: MnemoVault;
+    /** Métadonnées optionnelles (non vectorisées, stockées as-is) */
+    metadata?: Record<string, unknown>;
+    /** Dimension des vecteurs (défaut: 512) */
+    dimension?: number;
+}
+interface IngestResult {
+    success: boolean;
+    chronicleId?: string;
+    error?: string;
+    /** Si true, le contenu a été nettoyé par l'AI-Firewall (injection détectée) */
+    sanitized?: boolean;
+}
+interface QueryOptions {
+    /** Nombre max de résultats (défaut: 10) */
+    limit?: number;
+    /** Vault à interroger (défaut: vault déclaré dans le manifest) */
+    vault?: MnemoVault;
+    /** Seuil de similarité minimum 0-1 (défaut: 0.0) */
+    threshold?: number;
+}
+interface Chronicle {
+    id: string;
+    content: string;
+    spineType: SpineType;
+    score: number;
+    timestamp: string;
+    source_app_id: string;
+}
+interface QueryResult {
+    success: boolean;
+    chronicles: Chronicle[];
+    error?: string;
+}
+interface ShareRequest {
+    /** App source dont on veut lire les vecteurs */
+    fromAppId: string;
+    /** Raison affichée à l'utilisateur dans le popup de consentement */
+    reason: string;
+    /** Timeout du consentement en ms (défaut: 60000) */
+    timeoutMs?: number;
+}
+interface ShareResult {
+    granted: boolean;
+    chronicles?: Chronicle[];
+    error?: string;
+}
+interface RegisterResult {
+    token: string;
+    expiresAt: number;
+    appId: string;
+}
+/**
+ * Paramètres pour valider une licence NFT.
+ * La validation se fait on-chain via le runtime Mnemosyne OS (pas directement dans le SDK).
+ */
+interface NFTLicenseParams {
+    /** Adresse du wallet à vérifier */
+    walletAddress: string;
+    /** Chain ID cible — voir MNEMOSYNE_CHAINS dans constants.ts */
+    chainId?: number;
+}
+/** Résultat de validation d'une licence NFT */
+interface NFTValidation {
+    /** true si le wallet possède le NFT de licence de cette app */
+    valid: boolean;
+    walletAddress: string;
+    appId: string;
+    /** Timestamp Unix ms de la vérification */
+    checkedAt: number;
+    /** Timestamp Unix ms d'expiration du cache OS (5 min) */
+    cacheExpiresAt?: number;
+}
+/** Un nœud dans le NeuralGraph */
+interface GraphNode {
+    id: string;
+    label: string;
+    spineType: SpineType;
+    weight: number;
+    timestamp: string;
+}
+/** Une arête dans le NeuralGraph */
+interface GraphEdge {
+    source: string;
+    target: string;
+    strength: number;
+    type: 'causal' | 'temporal' | 'semantic';
+}
+/** Résultat d'une requête sur le NeuralGraph */
+interface GraphQueryResult {
+    success: boolean;
+    nodes: GraphNode[];
+    edges: GraphEdge[];
+    centerNodeId?: string;
+    error?: string;
+}
+type MnemoEventType = 'connected' | 'disconnected' | 'error' | 'tamper-alert' | 'share-request' | 'nft-revoked';
+interface MnemoEvent<T = unknown> {
+    type: MnemoEventType;
+    data: T;
+    timestamp: number;
+}
+
+/**
+ * @mnemosyne/sdk — JWT HMAC-SHA256 Auth
+ *
+ * Génère et valide des tokens d'authentification pour les apps SDK.
+ * Utilise `node:crypto` — zéro dépendance externe.
+ *
+ * Format : base64url(header).base64url(payload).base64url(signature)
+ * Algorithme : HMAC-SHA256 (symétrique, secret partagé OS ↔ app)
+ *
+ * [SDK][SECURITY][AUTH]
+ */
+interface JwtPayload {
+    sub: string;
+    iat: number;
+    exp: number;
+    scopes: string[];
+    jti: string;
+}
+interface JwtVerifyResult {
+    valid: boolean;
+    payload?: JwtPayload;
+    reason?: string;
+}
+/**
+ * Vérifie un token JWT.
+ * Utilise `timingSafeEqual` pour éviter les timing attacks.
+ */
+declare function verifyToken(token: string, secret: string): JwtVerifyResult;
+/**
+ * Génère un token pour une app SDK.
+ * @param appId    Identifiant de l'app
+ * @param scopes   Scopes autorisés
+ * @param secret   Secret HMAC (32 bytes minimum)
+ * @param ttlMs    Durée de vie en ms (défaut: 24h)
+ */
+declare function generateAppToken(appId: string, scopes: string[], secret: string, ttlMs?: number): {
+    token: string;
+    expiresAt: number;
+};
+/**
+ * Génère un secret HMAC aléatoire (à stocker dans le keychain OS).
+ */
+declare function generateSecret(): string;
+
+/**
+ * @mnemosyne/sdk — MnemoClient
+ *
+ * Client principal du SDK. Dual transport : WebSocket (externe) + IPC Electron (embarqué).
+ * Authentification JWT HMAC-SHA256.
+ *
+ * Usage minimal :
+ * ```typescript
+ * import { MnemoClient } from '@mnemosyne/sdk';
+ * const client = await MnemoClient.connect({ appId: 'my-app', manifest: './app.manifest.json' });
+ * await client.ingest({ content: '...', spineType: 'REDDIT_POST', vault: 'SOCIAL' });
+ * ```
+ *
+ * [SDK][ZERO-TRUST][DUAL-TRANSPORT]
+ */
+
+type EventHandler<T = unknown> = (event: MnemoEvent<T>) => void;
+declare class MnemoClient {
+    private readonly manifest;
+    private readonly options;
+    private ws;
+    private token;
+    private connected;
+    private readonly pending;
+    private readonly handlers;
+    /**
+     * Crée et connecte un client Mnemosyne.
+     * @throws si le manifest est invalide ou la connexion échoue
+     */
+    static connect(options: MnemoClientOptions): Promise<MnemoClient>;
+    private constructor();
+    private _connect;
+    private _resolveTransport;
+    private _connectWs;
+    private _connectIpc;
+    private _rpc;
+    private _rpcWs;
+    private _rpcIpc;
+    private _handleRpcResponse;
+    private _handleEvent;
+    private _register;
+    /**
+     * Renouvelle le token JWT avant expiration.
+     * Appelé automatiquement si le token expire dans moins de 5 minutes.
+     */
+    renewToken(): Promise<void>;
+    /**
+     * Ingère du contenu dans le vault Mnemosyne.
+     * Isolé par source_app_id — seule ton app peut lire ce qu'elle écrit.
+     */
+    ingest(payload: IngestPayload): Promise<IngestResult>;
+    /**
+     * Requête sémantique — retourne uniquement les chronicles de ton app (source_app_id isolation).
+     */
+    query(text: string, options?: QueryOptions): Promise<QueryResult>;
+    /**
+     * 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).
+     */
+    requestShare(request: ShareRequest): Promise<ShareResult>;
+    on<T = unknown>(type: MnemoEventType, handler: EventHandler<T>): () => void;
+    private _emit;
+    /**
+     * Ferme proprement la connexion.
+     * Attend la résolution de tous les RPC en cours.
+     */
+    disconnect(): Promise<void>;
+    get isConnected(): boolean;
+    get appId(): string;
+    get appManifest(): AppManifest;
+    /** Inspecte le token actuel (décodé, sans vérification) */
+    get tokenInfo(): {
+        sub: string;
+        exp: number;
+        scopes: string[];
+    } | null;
+}
+
+/**
+ * @mnemosyne/sdk — AppManifest Validator
+ *
+ * Valide le fichier app.manifest.json avant toute connexion.
+ * Utilise Zod pour un parsing strict — aucun champ inconnu passé au serveur.
+ *
+ * [SDK][ZERO-TRUST][AUDIT-TRAIL]
+ */
+
+declare const VALID_SCOPES: readonly ["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"];
+declare const AppManifestSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    version: z.ZodString;
+    author: z.ZodOptional<z.ZodString>;
+    mnemosyne_sdk: z.ZodString;
+    scopes: z.ZodArray<z.ZodEnum<["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"]>, "many">;
+    vaults: z.ZodArray<z.ZodEnum<["DEV", "SOCIAL", "PERSONAL", "FINANCE", "COOK"]>, "many">;
+    intents: z.ZodArray<z.ZodEnum<["INGEST", "QUERY", "CORRELATE", "FORGET"]>, "many">;
+    max_chronicle_size_kb: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    requires_consent: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    description: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    id: string;
+    name: string;
+    version: string;
+    mnemosyne_sdk: string;
+    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")[];
+    vaults: ("DEV" | "SOCIAL" | "PERSONAL" | "FINANCE" | "COOK")[];
+    intents: ("INGEST" | "QUERY" | "CORRELATE" | "FORGET")[];
+    max_chronicle_size_kb: number;
+    requires_consent: boolean;
+    author?: string | undefined;
+    description?: string | undefined;
+}, {
+    id: string;
+    name: string;
+    version: string;
+    mnemosyne_sdk: string;
+    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")[];
+    vaults: ("DEV" | "SOCIAL" | "PERSONAL" | "FINANCE" | "COOK")[];
+    intents: ("INGEST" | "QUERY" | "CORRELATE" | "FORGET")[];
+    author?: string | undefined;
+    max_chronicle_size_kb?: number | undefined;
+    requires_consent?: boolean | undefined;
+    description?: string | undefined;
+}>;
+/**
+ * Charge et valide un manifest depuis le filesystem.
+ * @throws {Error} si le manifest est invalide ou introuvable
+ */
+declare function loadManifest(pathOrManifest: string | AppManifest): AppManifest;
+/**
+ * Parse et valide un objet manifest brut.
+ * @throws {Error} avec détail des violations Zod
+ */
+declare function parseManifest(raw: unknown): AppManifest;
+/**
+ * Vérifie qu'un scope est déclaré dans le manifest.
+ * Utilisé par MnemoClient avant chaque opération.
+ */
+declare function assertScope(manifest: AppManifest, scope: (typeof VALID_SCOPES)[number]): void;
+/**
+ * Vérifie qu'un vault est accessible selon le manifest.
+ */
+declare function assertVault(manifest: AppManifest, vault: string): void;
+
+/**
+ * @mnemosyne_os/sdk — Public Constants
+ *
+ * Expose les méthodes RPC disponibles sur le serveur SDK (ws://localhost:7799)
+ * et les constantes de l'écosystème Mnemosyne OS.
+ *
+ * [SDK][LAYER-2][ZERO-TRUST]
+ */
+/**
+ * Méthodes JSON-RPC exposées par le SDK WebSocket Server de Mnemosyne OS.
+ * Le serveur écoute sur ws://127.0.0.1:7799 (localhost uniquement).
+ *
+ * @example
+ * ```typescript
+ * import { MNEMOSYNE_METHODS } from '@mnemosyne_os/sdk';
+ * // Utilisation directe (sans MnemoClient) :
+ * ws.send(JSON.stringify({ id: '1', method: MNEMOSYNE_METHODS.REGISTER, params: { manifest } }));
+ * ```
+ */
+declare const MNEMOSYNE_METHODS: {
+    /** Enregistre l'app, valide le manifest, retourne un JWT 24h */
+    readonly REGISTER: "sdk.register";
+    /** Ingère du contenu dans le vault (vectorisation incluse) */
+    readonly INGEST: "sdk.ingest";
+    /** Requête sémantique — résultats filtrés par source_app_id */
+    readonly QUERY: "sdk.query";
+    /** Trouve les connexions causales entre deux contenus */
+    readonly CORRELATE: "sdk.correlate";
+    /** Supprime un chronicle par ID (scope vault:write requis) */
+    readonly FORGET: "sdk.forget";
+    /** Demande d'accès aux chronicles d'une autre app (popup consentement) */
+    readonly SHARE: "sdk.share";
+    /**
+     * 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.
+     */
+    readonly NFT_VALIDATE: "sdk.nft.validate";
+    /**
+     * Requête le NeuralGraph — retourne les nœuds et arêtes proches du texte.
+     * Requiert le scope `neural:graph:read` dans le manifest.
+     */
+    readonly GRAPH_QUERY: "sdk.graph.query";
+};
+type MnemoMethod = typeof MNEMOSYNE_METHODS[keyof typeof MNEMOSYNE_METHODS];
+/** Port par défaut du SDK WebSocket Server */
+declare const MNEMOSYNE_WS_PORT = 7799;
+/** Host du SDK WebSocket Server (localhost uniquement — sécurité Zero-Trust) */
+declare const MNEMOSYNE_WS_HOST = "127.0.0.1";
+/** Durée de validité d'un JWT SDK (en secondes) */
+declare const MNEMOSYNE_TOKEN_TTL_S: number;
+/** Durée du cache de validation NFT côté OS (en ms) */
+declare const MNEMOSYNE_NFT_CACHE_TTL_MS: number;
+declare const MNEMOSYNE_CHAINS: {
+    readonly BASE: {
+        readonly id: 8453;
+        readonly name: "Base";
+        readonly rpc: "https://mainnet.base.org";
+    };
+    readonly POLYGON: {
+        readonly id: 137;
+        readonly name: "Polygon";
+        readonly rpc: "https://polygon-rpc.com";
+    };
+    readonly BASE_SEPOLIA: {
+        readonly id: 84532;
+        readonly name: "Base Sepolia (testnet)";
+        readonly rpc: "https://sepolia.base.org";
+    };
+};
+type MnemoChain = keyof typeof MNEMOSYNE_CHAINS;
+
+export { type AppManifest, AppManifestSchema, type Chronicle, type GraphEdge, type GraphNode, type GraphQueryResult, type IngestPayload, type IngestResult, type JwtPayload, type JwtVerifyResult, MNEMOSYNE_CHAINS, MNEMOSYNE_METHODS, MNEMOSYNE_NFT_CACHE_TTL_MS, MNEMOSYNE_TOKEN_TTL_S, MNEMOSYNE_WS_HOST, MNEMOSYNE_WS_PORT, type MnemoChain, MnemoClient, type MnemoClientOptions, type MnemoEvent, type MnemoEventType, type MnemoIntent, type MnemoMethod, type MnemoScope, type MnemoVault, type NFTLicenseParams, type NFTValidation, type QueryOptions, type QueryResult, type RegisterResult, type ShareRequest, type ShareResult, type SpineType, assertScope, assertVault, generateAppToken, generateSecret, loadManifest, parseManifest, verifyToken };