shogun-core 5.2.0 → 5.2.2

package/dist/types/interfaces/plugin.d.ts

@@ -0,0 +1,162 @@
+import { ShogunCore } from "../core";
+import { PluginCategory } from "./shogun";
+/**
+ * Interfaccia di base per tutti i plugin di ShogunCore
+ */
+export interface ShogunPlugin {
+    /** Nome univoco del plugin */
+    name: string;
+    /** Versione del plugin */
+    version: string;
+    /** Descrizione opzionale del plugin */
+    description?: string;
+    /** Categoria del plugin (opzionale) */
+    _category?: PluginCategory;
+    /**
+     * Metodo opzionale per inizializzare il plugin
+     * @param core Istanza di ShogunCore
+     */
+    initialize(core: ShogunCore): void;
+    /**
+     * Metodo opzionale per distruggere il plugin e liberare risorse
+     */
+    destroy?(): void;
+}
+/**
+ * Interfaccia per la gestione dei plugin in ShogunCore
+ */
+export interface PluginManager {
+    /**
+     * Registra un nuovo plugin
+     * @param plugin Il plugin da registrare
+     */
+    register(plugin: ShogunPlugin): void;
+    /**
+     * Cancella la registrazione di un plugin
+     * @param pluginName Nome del plugin da cancellare
+     */
+    unregister(pluginName: string): void;
+    /**
+     * Recupera un plugin registrato per nome
+     * @param name Nome del plugin
+     * @returns Il plugin richiesto o undefined se non trovato
+     * @template T Tipo del plugin o dell'interfaccia pubblica del plugin
+     */
+    getPlugin<T = ShogunPlugin>(name: string): T | undefined;
+    /**
+     * Verifica se un plugin è registrato
+     * @param name Nome del plugin da verificare
+     * @returns true se il plugin è registrato, false altrimenti
+     */
+    hasPlugin(name: string): boolean;
+    /**
+     * Ottiene tutti i plugin di una determinata categoria
+     * @param category Categoria di plugin da filtrare
+     * @returns Array di plugin della categoria specificata
+     */
+    getPluginsByCategory(category: PluginCategory): ShogunPlugin[];
+    /**
+     * Ottiene informazioni su tutti i plugin registrati
+     * @returns Array di oggetti con informazioni sui plugin
+     */
+    getPluginsInfo(): Array<{
+        name: string;
+        version: string;
+        category?: PluginCategory;
+        description?: string;
+    }>;
+    /**
+     * Ottiene il numero totale di plugin registrati
+     * @returns Numero di plugin registrati
+     */
+    getPluginCount(): number;
+    /**
+     * Verifica se tutti i plugin sono inizializzati correttamente
+     * @returns Oggetto con stato di inizializzazione per ogni plugin
+     */
+    getPluginsInitializationStatus(): Record<string, {
+        initialized: boolean;
+        error?: string;
+    }>;
+    /**
+     * Valida l'integrità del sistema di plugin
+     * @returns Oggetto con risultati della validazione
+     */
+    validatePluginSystem(): {
+        totalPlugins: number;
+        initializedPlugins: number;
+        failedPlugins: string[];
+        warnings: string[];
+    };
+    /**
+     * Tenta di reinizializzare i plugin falliti
+     * @returns Oggetto con risultati della reinizializzazione
+     */
+    reinitializeFailedPlugins(): {
+        success: string[];
+        failed: Array<{
+            name: string;
+            error: string;
+        }>;
+    };
+    /**
+     * Verifica la compatibilità dei plugin con la versione corrente di ShogunCore
+     * @returns Oggetto con informazioni sulla compatibilità
+     */
+    checkPluginCompatibility(): {
+        compatible: Array<{
+            name: string;
+            version: string;
+        }>;
+        incompatible: Array<{
+            name: string;
+            version: string;
+            reason: string;
+        }>;
+        unknown: Array<{
+            name: string;
+            version: string;
+        }>;
+    };
+    /**
+     * Ottiene informazioni complete di debug sul sistema di plugin
+     * @returns Informazioni complete di debug del sistema di plugin
+     */
+    getPluginSystemDebugInfo(): {
+        shogunCoreVersion: string;
+        totalPlugins: number;
+        plugins: Array<{
+            name: string;
+            version: string;
+            category?: PluginCategory;
+            description?: string;
+            initialized: boolean;
+            error?: string;
+        }>;
+        initializationStatus: Record<string, {
+            initialized: boolean;
+            error?: string;
+        }>;
+        validation: {
+            totalPlugins: number;
+            initializedPlugins: number;
+            failedPlugins: string[];
+            warnings: string[];
+        };
+        compatibility: {
+            compatible: Array<{
+                name: string;
+                version: string;
+            }>;
+            incompatible: Array<{
+                name: string;
+                version: string;
+                reason: string;
+            }>;
+            unknown: Array<{
+                name: string;
+                version: string;
+            }>;
+        };
+    };
+}

package/dist/types/interfaces/shogun.d.ts

@@ -0,0 +1,208 @@
+import { IGunInstance, IGunUserInstance } from "gun/types";
+import { ISEAPair } from "gun";
+import { ethers } from "ethers";
+import { ShogunError } from "../utils/errorHandler";
+import { DataBase } from "../gundb/db";
+import { RxJS } from "../gundb/rxjs";
+import { ShogunPlugin, PluginManager } from "./plugin";
+import { ShogunStorage } from "../storage/storage";
+import { ShogunEventMap } from "./events";
+/**
+ * Standard plugin categories in ShogunCore
+ */
+export declare enum PluginCategory {
+    /** Authentication plugins (WebAuthn, MetaMask, Bitcoin) */
+    Authentication = "authentication",
+    /** Wallet management plugins */
+    Wallet = "wallet",
+    /** Privacy and anonymity plugins */
+    Privacy = "privacy",
+    /** Decentralized identity plugins */
+    Identity = "identity",
+    /** Other utility plugins */
+    Utility = "utility",
+    /** Messages plugins */
+    Messages = "messages",
+    /** Messaging plugins */
+    Other = "other"
+}
+/**
+ * Standard names for built-in plugins
+ */
+export declare enum CorePlugins {
+    /** WebAuthn plugin */
+    WebAuthn = "webauthn",
+    /** Ethereum plugin */
+    Web3 = "web3",
+    /** Bitcoin wallet plugin */
+    Nostr = "nostr",
+    /** Zero-Knowledge Proof plugin */
+    ZkProof = "zkproof"
+}
+export type AuthMethod = "password" | "webauthn" | "web3" | "nostr" | "zkproof" | "pair";
+export interface AuthEventData {
+    userPub?: string;
+    username?: string;
+    method: "password" | "webauthn" | "web3" | "nostr" | "zkproof" | "pair";
+    provider?: string;
+}
+export interface AuthResult {
+    success: boolean;
+    error?: string;
+    userPub?: string;
+    username?: string;
+    sessionToken?: string;
+    authMethod?: AuthMethod;
+    sea?: {
+        pub: string;
+        priv: string;
+        epub: string;
+        epriv: string;
+    };
+    redirectUrl?: string;
+    pendingAuth?: boolean;
+    message?: string;
+    provider?: string;
+    isNewUser?: boolean;
+    user?: {
+        userPub?: string;
+        username?: string;
+        email?: string;
+        name?: string;
+        picture?: string;
+    };
+}
+/**
+ * Sign up result interface
+ */
+export interface SignUpResult {
+    success: boolean;
+    userPub?: string;
+    username?: string;
+    pub?: string;
+    error?: string;
+    message?: string;
+    wallet?: any;
+    isNewUser?: boolean;
+    authMethod?: AuthMethod;
+    sessionToken?: string;
+    sea?: {
+        pub: string;
+        priv: string;
+        epub: string;
+        epriv: string;
+    };
+    seedPhrase?: string;
+    redirectUrl?: string;
+    pendingAuth?: boolean;
+    provider?: string;
+    user?: {
+        userPub?: string;
+        username?: string;
+        email?: string;
+        name?: string;
+        picture?: string;
+    };
+}
+export interface IShogunCore extends PluginManager {
+    gun: IGunInstance<any>;
+    _gun: IGunInstance<any>;
+    user: IGunUserInstance | null;
+    _user: IGunUserInstance | null;
+    db: DataBase;
+    rx: RxJS;
+    storage: ShogunStorage;
+    config: ShogunCoreConfig;
+    provider?: ethers.Provider;
+    signer?: ethers.Signer;
+    wallets?: Wallets;
+    pluginManager: any;
+    on<K extends keyof ShogunEventMap>(eventName: K, listener: ShogunEventMap[K] extends void ? () => void : (data: ShogunEventMap[K]) => void): this;
+    off<K extends keyof ShogunEventMap>(eventName: K, listener: ShogunEventMap[K] extends void ? () => void : (data: ShogunEventMap[K]) => void): this;
+    once<K extends keyof ShogunEventMap>(eventName: K, listener: ShogunEventMap[K] extends void ? () => void : (data: ShogunEventMap[K]) => void): this;
+    removeAllListeners(eventName?: string | symbol): this;
+    emit<K extends keyof ShogunEventMap>(eventName: K, data?: ShogunEventMap[K] extends void ? never : ShogunEventMap[K]): boolean;
+    getRecentErrors(count?: number): ShogunError[];
+    login(username: string, password: string, pair?: ISEAPair | null): Promise<AuthResult>;
+    loginWithPair(username: string, pair: ISEAPair): Promise<AuthResult>;
+    signUp(username: string, password?: string, pair?: ISEAPair | null): Promise<SignUpResult>;
+    getAuthenticationMethod(type: AuthMethod): any;
+    setAuthMethod(method: AuthMethod): void;
+    getAuthMethod(): AuthMethod | undefined;
+    getCurrentUser(): {
+        pub: string;
+        user?: any;
+    } | null;
+    getIsLoggedIn(): boolean;
+    logout(): void;
+    isLoggedIn(): boolean;
+    saveCredentials(credentials: any): Promise<void>;
+}
+/**
+ * WebAuthn configuration
+ */
+export interface WebauthnConfig {
+    /** Enable WebAuthn */
+    enabled?: boolean;
+    /** Relying party name */
+    rpName?: string;
+    /** Relying party ID */
+    rpId?: string;
+}
+/**
+ * Shogun SDK configuration
+ */
+export interface ShogunCoreConfig {
+    gunInstance?: IGunInstance<any>;
+    gunOptions?: any;
+    webauthn?: WebauthnConfig;
+    web3?: {
+        enabled?: boolean;
+    };
+    nostr?: {
+        enabled?: boolean;
+    };
+    zkproof?: {
+        enabled?: boolean;
+        defaultGroupId?: string;
+        deterministic?: boolean;
+        minEntropy?: number;
+    };
+    timeouts?: {
+        login?: number;
+        signup?: number;
+        operation?: number;
+    };
+    plugins?: {
+        autoRegister?: ShogunPlugin[];
+    };
+    disableAutoRecall?: boolean;
+    silent?: boolean;
+}
+export interface ShogunEvents {
+    error: (data: {
+        action: string;
+        message: string;
+    }) => void;
+    "auth:signup": (data: {
+        username: string;
+        userPub: string;
+    }) => void;
+    "auth:login": (data: {
+        username: string;
+        userPub: string;
+    }) => void;
+    "auth:logout": (data: Record<string, never>) => void;
+}
+export interface Wallets {
+    secp256k1Bitcoin: {
+        privateKey: string;
+        publicKey: string;
+        address: string;
+    };
+    secp256k1Ethereum: {
+        privateKey: string;
+        publicKey: string;
+        address: string;
+    };
+}

package/dist/types/managers/AuthManager.d.ts

@@ -0,0 +1,72 @@
+import { IShogunCore, AuthResult, SignUpResult, AuthMethod } from "../interfaces/shogun";
+import { ISEAPair } from "gun";
+/**
+ * Manages authentication operations for ShogunCore
+ */
+export declare class AuthManager {
+    private core;
+    private currentAuthMethod?;
+    constructor(core: IShogunCore);
+    /**
+     * Check if user is logged in
+     * @returns {boolean} True if user is logged in, false otherwise
+     * @description Verifies authentication status by checking GunInstance login state
+     * and presence of authentication credentials in storage
+     */
+    isLoggedIn(): boolean;
+    /**
+     * Perform user logout
+     * @description Logs out the current user from GunInstance and emits logout event.
+     * If user is not authenticated, the logout operation is ignored.
+     */
+    logout(): void;
+    /**
+     * Authenticate user with username and password
+     * @param username - Username
+     * @param password - User password
+     * @returns {Promise<AuthResult>} Promise with authentication result
+     * @description Attempts to log in user with provided credentials.
+     * Emits login event on success.
+     */
+    login(username: string, password: string, pair?: ISEAPair | null): Promise<AuthResult>;
+    /**
+     * Login with GunDB pair directly
+     * @param pair - GunDB SEA pair for authentication
+     * @returns {Promise<AuthResult>} Promise with authentication result
+     * @description Authenticates user using a GunDB pair directly.
+     * Emits login event on success.
+     */
+    loginWithPair(username: string, pair: ISEAPair): Promise<AuthResult>;
+    /**
+     * Register a new user with provided credentials
+     * @param username - Username
+     * @param password - Password
+     * @param email - Email (optional)
+     * @param pair - Pair of keys
+     * @returns {Promise<SignUpResult>} Registration result
+     * @description Creates a new user account with the provided credentials.
+     * Validates password requirements and emits signup event on success.
+     */
+    signUp(username: string, password?: string, pair?: ISEAPair | null): Promise<SignUpResult>;
+    /**
+     * Set the current authentication method
+     * This is used by plugins to indicate which authentication method was used
+     * @param method The authentication method used
+     */
+    setAuthMethod(method: AuthMethod): void;
+    /**
+     * Get the current authentication method
+     * @returns The current authentication method or undefined if not set
+     */
+    getAuthMethod(): AuthMethod | undefined;
+    /**
+     * Get an authentication method plugin by type
+     * @param type The type of authentication method
+     * @returns The authentication plugin or undefined if not available
+     * This is a more modern approach to accessing authentication methods
+     */
+    getAuthenticationMethod(type: AuthMethod): import("..").ShogunPlugin | {
+        login: (username: string, password: string) => Promise<AuthResult>;
+        signUp: (username: string, password: string, confirm?: string) => Promise<SignUpResult>;
+    } | undefined;
+}

package/dist/types/managers/CoreInitializer.d.ts

@@ -0,0 +1,40 @@
+import { IShogunCore, ShogunCoreConfig } from "../interfaces/shogun";
+/**
+ * Handles initialization of ShogunCore components
+ */
+export declare class CoreInitializer {
+    private core;
+    constructor(core: IShogunCore);
+    /**
+     * Initialize the Shogun SDK
+     * @param config - SDK Configuration object
+     * @description Creates a new instance of ShogunCore with the provided configuration.
+     * Initializes all required components including storage, event emitter, GunInstance connection,
+     * and plugin system.
+     */
+    initialize(config: ShogunCoreConfig): Promise<void>;
+    /**
+     * Initialize Gun instance
+     */
+    private initializeGun;
+    /**
+     * Initialize Gun user
+     */
+    private initializeGunUser;
+    /**
+     * Setup Gun event forwarding
+     */
+    private setupGunEventForwarding;
+    /**
+     * Setup wallet derivation
+     */
+    private setupWalletDerivation;
+    /**
+     * Register built-in plugins based on configuration
+     */
+    private registerBuiltinPlugins;
+    /**
+     * Initialize async components
+     */
+    private initializeDb;
+}

package/dist/types/managers/CryptoIdentityManager.d.ts

@@ -0,0 +1,102 @@
+/**
+ * CryptoIdentityManager - Gestisce la generazione e il salvataggio delle identità crypto
+ * dopo l'autenticazione SEA dell'utente
+ */
+import type { IShogunCore } from "../interfaces/shogun";
+import type { ISEAPair } from "gun/types";
+import type { JWKKeyPair, SignalUser } from "../crypto/types";
+import type { PGPKeyPair } from "../crypto/pgp";
+/**
+ * Interfaccia per le identità crypto generate
+ */
+export interface CryptoIdentities {
+    rsa?: JWKKeyPair;
+    aes?: JsonWebKey;
+    signal?: SignalUser;
+    pgp?: PGPKeyPair;
+    mls?: {
+        groupId: string;
+        memberId: string;
+    };
+    sframe?: {
+        keyId: number;
+    };
+    createdAt: number;
+    version: string;
+}
+/**
+ * Risultato dell'operazione di generazione identità
+ */
+export interface IdentityGenerationResult {
+    success: boolean;
+    identities?: CryptoIdentities;
+    error?: string;
+}
+/**
+ * Risultato dell'operazione di salvataggio identità
+ */
+export interface IdentitySaveResult {
+    success: boolean;
+    savedKeys: string[];
+    error?: string;
+}
+/**
+ * Risultato dell'operazione di recupero identità
+ */
+export interface IdentityRetrievalResult {
+    success: boolean;
+    identities?: CryptoIdentities;
+    error?: string;
+}
+/**
+ * Manager per la gestione delle identità crypto
+ * Genera automaticamente tutte le identità crypto disponibili dopo l'autenticazione SEA
+ */
+export declare class CryptoIdentityManager {
+    private core;
+    private pgpManager;
+    private mlsManager;
+    private sframeManager;
+    constructor(core: IShogunCore);
+    /**
+     * Genera tutte le identità crypto disponibili per un utente
+     * @param username - Nome utente
+     * @param seaPair - Coppia di chiavi SEA dell'utente
+     * @returns Promise con le identità generate
+     */
+    generateAllIdentities(username: string, seaPair: ISEAPair): Promise<IdentityGenerationResult>;
+    /**
+     * Cripta e salva le identità crypto su GunDB usando il SEA pair
+     * @param username - Nome utente
+     * @param identities - Identità crypto da salvare
+     * @param seaPair - Coppia di chiavi SEA per la crittografia
+     * @returns Promise con il risultato del salvataggio
+     */
+    saveIdentitiesToGun(username: string, identities: CryptoIdentities, seaPair: ISEAPair): Promise<IdentitySaveResult>;
+    /**
+     * Recupera e decripta le identità crypto da GunDB
+     * @param username - Nome utente
+     * @param seaPair - Coppia di chiavi SEA per la decrittografia
+     * @returns Promise con le identità recuperate
+     */
+    retrieveIdentitiesFromGun(username: string, seaPair: ISEAPair): Promise<IdentityRetrievalResult>;
+    /**
+     * Verifica se l'utente ha già delle identità crypto salvate
+     * @param username - Nome utente
+     * @returns Promise con il risultato della verifica
+     */
+    hasStoredIdentities(username: string): Promise<boolean>;
+    /**
+     * Processo completo: genera, salva e gestisce le identità crypto dopo l'autenticazione
+     * @param username - Nome utente
+     * @param seaPair - Coppia di chiavi SEA dell'utente
+     * @param forceRegenerate - Se true, rigenera anche se esistono già
+     * @returns Promise con il risultato del processo completo
+     */
+    setupCryptoIdentities(username: string, seaPair: ISEAPair, forceRegenerate?: boolean): Promise<IdentityGenerationResult & IdentitySaveResult>;
+    /**
+     * Ottiene le identità crypto dell'utente corrente
+     * @returns Promise con le identità dell'utente corrente
+     */
+    getCurrentUserIdentities(): Promise<IdentityRetrievalResult>;
+}

package/dist/types/managers/EventManager.d.ts

@@ -0,0 +1,49 @@
+import { ShogunEventEmitter, ShogunEventMap } from "../interfaces/events";
+/**
+ * Manages event operations for ShogunCore
+ */
+export declare class EventManager {
+    private eventEmitter;
+    constructor();
+    /**
+     * Emits an event through the core's event emitter.
+     * Plugins should use this method to emit events instead of accessing the private eventEmitter directly.
+     * @param eventName The name of the event to emit.
+     * @param data The data to pass with the event.
+     * @returns {boolean} Indicates if the event had listeners.
+     */
+    emit<K extends keyof ShogunEventMap>(eventName: K, data?: ShogunEventMap[K] extends void ? never : ShogunEventMap[K]): boolean;
+    /**
+     * Add an event listener
+     * @param eventName The name of the event to listen for
+     * @param listener The callback function to execute when the event is emitted
+     * @returns {this} Returns this instance for method chaining
+     */
+    on<K extends keyof ShogunEventMap>(eventName: K, listener: ShogunEventMap[K] extends void ? () => void : (data: ShogunEventMap[K]) => void): this;
+    /**
+     * Add a one-time event listener
+     * @param eventName The name of the event to listen for
+     * @param listener The callback function to execute when the event is emitted
+     * @returns {this} Returns this instance for method chaining
+     */
+    once<K extends keyof ShogunEventMap>(eventName: K, listener: ShogunEventMap[K] extends void ? () => void : (data: ShogunEventMap[K]) => void): this;
+    /**
+     * Remove an event listener
+     * @param eventName The name of the event to stop listening for
+     * @param listener The callback function to remove
+     * @returns {this} Returns this instance for method chaining
+     */
+    off<K extends keyof ShogunEventMap>(eventName: K, listener: ShogunEventMap[K] extends void ? () => void : (data: ShogunEventMap[K]) => void): this;
+    /**
+     * Remove all listeners for a specific event or all events
+     * @param eventName Optional. The name of the event to remove listeners for.
+     * If not provided, all listeners for all events are removed.
+     * @returns {this} Returns this instance for method chaining
+     */
+    removeAllListeners(eventName?: string | symbol): this;
+    /**
+     * Get the underlying event emitter instance
+     * @returns The ShogunEventEmitter instance
+     */
+    getEventEmitter(): ShogunEventEmitter;
+}