@merklevault/core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,303 @@
+import { EventEmitter } from 'node:events';
+
+/**
+ * @merklevault/core — Types publics du SDK
+ *
+ * Ces types constituent l'API publique du SDK.
+ * Toute modification est un breaking change.
+ */
+interface MerkleVaultOptions {
+    /** Chemin vers le dossier de donnees du vault */
+    dataDir: string;
+    /** Chemin vers le binaire Kubo/IPFS (optionnel, auto-detecte sinon) */
+    kuboBinaryPath?: string;
+    /** Port de l'API Kubo (defaut: 5101) */
+    kuboApiPort?: number;
+    /** Delai d'auto-lock en millisecondes (defaut: 15 min = 900000) */
+    autoLockMs?: number;
+    /** Desactiver l'auto-lock (defaut: false) */
+    disableAutoLock?: boolean;
+}
+interface FileNode {
+    id: number;
+    parentId: number | null;
+    name: string;
+    kind: 'file' | 'folder';
+    createdAt: number;
+    modifiedAt: number;
+    deletedAt: number | null;
+    currentVersionId: number | null;
+}
+interface FileVersion {
+    id: number;
+    nodeId: number;
+    cid: string;
+    sizeBytes: number;
+    sha256Plain: string | null;
+    createdAt: number;
+    encAlgo: string;
+    provider: 'local' | 'pinata';
+    pinataCid: string | null;
+    syncStatus: SyncStatusValue;
+}
+type SyncStatusValue = 'none' | 'pending' | 'syncing' | 'synced' | 'error';
+interface VaultInfo {
+    initialized: boolean;
+    unlocked: boolean;
+}
+interface CreateVaultResult {
+    /** Phrase de recuperation BIP39 (24 mots) — a afficher UNE SEULE FOIS */
+    mnemonic: string;
+}
+type CloudProvider = 'local' | 'pinata';
+interface PinataCredentials {
+    apiKey?: string;
+    secretApiKey?: string;
+    jwt?: string;
+    gateway?: string;
+}
+interface CloudConfig {
+    provider: CloudProvider;
+    active: boolean;
+    hasCredentials: boolean;
+    gateway: string | null;
+}
+interface SyncStatus {
+    total: number;
+    synced: number;
+    pending: number;
+    errors: number;
+    provider: CloudProvider;
+}
+interface AddFileResult {
+    node: FileNode;
+    version: FileVersion;
+    cid: string;
+}
+interface GetFileResult {
+    node: FileNode;
+    data: Buffer;
+    cid: string;
+    size: number;
+}
+interface FolderListing {
+    node: FileNode;
+    children: FileNode[];
+}
+interface DaemonStatus {
+    kuboReady: boolean;
+    kuboPid: number | null;
+    rootNode: FileNode;
+    ipfsOnline: boolean;
+    vaultInitialized: boolean;
+    vaultUnlocked: boolean;
+    cloudProvider: CloudProvider;
+    cloudActive: boolean;
+}
+type VaultEventType = 'vault:created' | 'vault:unlocked' | 'vault:locked' | 'file:added' | 'file:deleted' | 'file:renamed' | 'file:moved' | 'folder:created' | 'sync:started' | 'sync:progress' | 'sync:complete' | 'sync:error' | 'cloud:configured' | 'cloud:toggled' | 'kubo:ready' | 'kubo:crash' | 'error';
+interface VaultEvent {
+    type: VaultEventType;
+    data?: any;
+    timestamp: number;
+}
+
+/**
+ * @merklevault/core — Classe facade principale
+ *
+ * Encapsule toute la logique metier de MerkleVault :
+ *   - Gestion du vault (creation, deverrouillage, recovery)
+ *   - CRUD fichiers/dossiers sur IPFS (Kubo)
+ *   - Chiffrement E2E (XChaCha20-Poly1305 + Argon2id)
+ *   - Synchronisation cloud (Pinata)
+ *
+ * Usage :
+ *   import { MerkleVault } from '@merklevault/core';
+ *   const vault = new MerkleVault({ dataDir: './my-vault' });
+ *   await vault.start();
+ *   await vault.create({ password: 'secret' });
+ *   const file = await vault.addFile(buffer, { name: 'doc.pdf' });
+ */
+
+declare class MerkleVault extends EventEmitter {
+    private opts;
+    private kubo;
+    private db;
+    private store;
+    private kuboStore;
+    private syncProcessor;
+    private masterKey;
+    private lockTimer;
+    private started;
+    constructor(options: MerkleVaultOptions);
+    /**
+     * Demarre le vault : initialise la DB, lance Kubo, restaure la config cloud.
+     * Doit etre appele avant toute autre operation.
+     */
+    start(): Promise<void>;
+    /**
+     * Arrete le vault proprement : ferme Kubo, la DB, le sync processor.
+     */
+    stop(): Promise<void>;
+    /**
+     * Verifie que le vault est demarre, sinon throw.
+     */
+    private ensureStarted;
+    /**
+     * Verifie que le vault est deverrouille, sinon throw.
+     */
+    private ensureUnlocked;
+    /**
+     * Cree un nouveau vault avec un mot de passe.
+     * Retourne la phrase de recuperation BIP39 (24 mots).
+     *
+     * @param password - Mot de passe maitre (min 8 caracteres)
+     * @returns Phrase de recuperation a afficher UNE SEULE FOIS
+     */
+    create(password: string): Promise<CreateVaultResult>;
+    /**
+     * Deverrouille le vault avec le mot de passe.
+     *
+     * @param password - Mot de passe maitre
+     * @returns true si le deverrouillage a reussi
+     * @throws Si le mot de passe est invalide
+     */
+    unlock(password: string): boolean;
+    /**
+     * Verrouille le vault — efface la master key de la memoire.
+     */
+    lock(): void;
+    /**
+     * Recupere le vault via la phrase BIP39 et definit un nouveau mot de passe.
+     *
+     * @param mnemonic - Phrase de recuperation (24 mots)
+     * @param newPassword - Nouveau mot de passe
+     */
+    recover(mnemonic: string, newPassword: string): Promise<boolean>;
+    /**
+     * Change le mot de passe du vault sans re-chiffrer les fichiers.
+     *
+     * @param oldPassword - Ancien mot de passe
+     * @param newPassword - Nouveau mot de passe
+     */
+    changePassword(oldPassword: string, newPassword: string): Promise<boolean>;
+    /**
+     * Retourne l'etat du vault (initialise, deverrouille).
+     */
+    getVaultInfo(): VaultInfo;
+    /**
+     * Verifie si le vault est deverrouille.
+     */
+    isUnlocked(): boolean;
+    /**
+     * Ajoute un fichier au vault depuis un Buffer.
+     *
+     * @param data - Contenu du fichier
+     * @param options - Nom et dossier parent
+     * @returns Noeud cree, version et CID
+     */
+    addFile(data: Buffer, options: {
+        name: string;
+        parentId?: number;
+    }): Promise<AddFileResult>;
+    /**
+     * Ajoute un fichier depuis un chemin sur le disque.
+     *
+     * @param filePath - Chemin absolu du fichier
+     * @param options - Nom (optionnel, deduit du path) et dossier parent
+     */
+    addFileFromPath(filePath: string, options?: {
+        name?: string;
+        parentId?: number;
+    }): Promise<AddFileResult>;
+    /**
+     * Recupere le contenu dechiffre d'un fichier.
+     *
+     * @param nodeId - ID du noeud fichier
+     * @returns Contenu dechiffre + metadonnees
+     */
+    getFile(nodeId: number): Promise<GetFileResult>;
+    /**
+     * Liste le contenu d'un dossier.
+     *
+     * @param parentId - ID du dossier (undefined = racine)
+     */
+    listFolder(parentId?: number): FolderListing;
+    /**
+     * Recupere un noeud par son ID.
+     */
+    getNode(nodeId: number): FileNode | null;
+    /**
+     * Recupere le chemin complet d'un noeud (fil d'ariane).
+     */
+    getNodePath(nodeId: number): FileNode[];
+    /**
+     * Recupere le noeud racine.
+     */
+    getRootNode(): FileNode;
+    /**
+     * Cree un nouveau dossier.
+     *
+     * @param name - Nom du dossier
+     * @param parentId - ID du dossier parent (defaut: racine)
+     */
+    createFolder(name: string, parentId?: number): FileNode;
+    /**
+     * Renomme un noeud (fichier ou dossier).
+     */
+    rename(nodeId: number, newName: string): void;
+    /**
+     * Deplace un noeud vers un autre dossier.
+     */
+    move(nodeId: number, newParentId: number): void;
+    /**
+     * Supprime un noeud (soft delete → corbeille).
+     * Unpin de Pinata si le fichier y est synchronise.
+     */
+    delete(nodeId: number): Promise<void>;
+    /**
+     * Restaure un noeud depuis la corbeille.
+     */
+    restore(nodeId: number): void;
+    /**
+     * Liste les elements dans la corbeille.
+     */
+    listTrash(): FileNode[];
+    /**
+     * Recupere l'historique des versions d'un fichier.
+     */
+    getVersions(nodeId: number): FileVersion[];
+    /**
+     * Recherche dans le vault (FTS5).
+     */
+    search(query: string): FileNode[];
+    /**
+     * Configure les credentials Pinata et teste la connexion.
+     *
+     * @param credentials - JWT ou apiKey + secretApiKey
+     * @returns true si la connexion a reussi
+     */
+    configureCloud(credentials: PinataCredentials): Promise<boolean>;
+    /**
+     * Active ou desactive la synchronisation cloud.
+     */
+    toggleCloud(enabled: boolean): CloudProvider;
+    /**
+     * Retourne la configuration cloud actuelle.
+     */
+    getCloudConfig(): CloudConfig;
+    /**
+     * Retourne le statut de synchronisation.
+     */
+    getSyncStatus(): SyncStatus;
+    /**
+     * Retourne le statut global du vault.
+     */
+    getStatus(): Promise<DaemonStatus>;
+    private loadVaultConfig;
+    private saveVaultConfig;
+    private restoreCloudConfig;
+    private resetLockTimer;
+    private emitEvent;
+}
+
+export { type AddFileResult, type CloudConfig, type CloudProvider, type CreateVaultResult, type DaemonStatus, type FileNode, type FileVersion, type FolderListing, type GetFileResult, MerkleVault, type MerkleVaultOptions, type PinataCredentials, type SyncStatus, type SyncStatusValue, type VaultEvent, type VaultEventType, type VaultInfo };