shogun-core 3.0.4 → 3.0.5

package/dist/types/storage/storage.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Storage implementation based on StorageMock
+ * Provides a unified storage interface that works in both browser and non-browser environments
+ * In browser environments, data is persisted to localStorage as a backup
+ */
+export declare class ShogunStorage {
+    private store;
+    private isTestMode;
+    private useLocalStorage;
+    /**
+     * Initializes storage and loads any existing keypair from localStorage if available
+     */
+    constructor();
+    /**
+     * Gets the stored keypair asynchronously
+     * @returns Promise resolving to the keypair or null if not found
+     */
+    getPair(): Promise<any>;
+    /**
+     * Gets the stored keypair synchronously
+     * @returns The keypair or null if not found
+     */
+    getPairSync(): any;
+    /**
+     * Stores a keypair both in memory and localStorage if available
+     * @param pair - The keypair to store
+     */
+    setPair(pair: any): Promise<void>;
+    /**
+     * Clears all stored data from both memory and localStorage
+     */
+    clearAll(): void;
+    /**
+     * Gets an item from storage
+     * @param key - The key to retrieve
+     * @returns The stored value, or null if not found
+     */
+    getItem(key: string): any;
+    /**
+     * Stores an item in both memory and localStorage if available
+     * @param key - The key to store under
+     * @param value - The value to store (must be JSON stringifiable)
+     */
+    setItem(key: string, value: any): void;
+    /**
+     * Removes an item from both memory and localStorage if available
+     * @param key - The key to remove
+     */
+    removeItem(key: string): void;
+}

package/dist/types/utils/errorHandler.d.ts

@@ -0,0 +1,119 @@
+import { LogLevel } from "../interfaces/common";
+/**
+ * Types of errors that can occur in the application
+ */
+export declare enum ErrorType {
+    AUTHENTICATION = "AuthenticationError",
+    AUTHORIZATION = "AuthorizationError",
+    VALIDATION = "ValidationError",
+    NETWORK = "NetworkError",
+    DATABASE = "DatabaseError",
+    WALLET = "WalletError",
+    STORAGE = "StorageError",
+    ENCRYPTION = "EncryptionError",
+    SIGNATURE = "SignatureError",
+    ENVIRONMENT = "EnvironmentError",
+    SECURITY = "SecurityError",
+    GUN = "GunError",
+    STEALTH = "StealthError",
+    WEBAUTHN = "WebAuthnError",
+    PLUGIN = "PluginError",
+    UNKNOWN = "UnknownError",
+    CONNECTOR = "ConnectorError",
+    GENERAL = "GeneralError",
+    CONTRACT = "ContractError",
+    BIP32 = "BIP32Error",
+    ETHEREUM = "EthereumError",
+    BITCOIN = "BitcoinError"
+}
+/**
+ * Standard interface for Shogun errors
+ */
+export interface ShogunError {
+    type: ErrorType;
+    code: string;
+    message: string;
+    originalError?: Error | unknown;
+    timestamp: number;
+}
+/**
+ * Wrapper to standardize errors
+ * @param type - Error type
+ * @param code - Error code
+ * @param message - Error message
+ * @param originalError - Original error
+ * @returns A structured error object
+ */
+export declare function createError(type: ErrorType, code: string, message: string, originalError?: Error | unknown): ShogunError;
+/**
+ * Centralized error handler
+ */
+export declare class ErrorHandler {
+    private static errors;
+    private static maxErrors;
+    private static listeners;
+    private static externalLogger;
+    /**
+     * Set an external logging service for production error monitoring
+     * @param logger - External logger function to send errors to a monitoring service
+     */
+    static setExternalLogger(logger: (error: ShogunError) => void): void;
+    /**
+     * Handles an error by logging it and notifying listeners
+     * @param error - The error to handle
+     */
+    static handleError(error: ShogunError): void;
+    /**
+     * Handles a raw error by converting it to ShogunError
+     * @param type - Error type
+     * @param code - Error code
+     * @param message - Error message
+     * @param originalError - Original error
+     * @param logLevel - Log level for the error
+     */
+    static handle(type: ErrorType, code: string, message: string, originalError?: Error | unknown, logLevel?: LogLevel): ShogunError;
+    /**
+     * Handles errors and throws them as standardized ShogunError objects
+     * @param type - Error type
+     * @param code - Error code
+     * @param message - Error message
+     * @param originalError - Original error
+     * @throws ShogunError
+     */
+    static handleAndThrow(type: ErrorType, code: string, message: string, originalError?: Error | unknown): never;
+    /**
+     * Retrieves the last N errors
+     * @param count - Number of errors to retrieve
+     * @returns List of most recent errors
+     */
+    static getRecentErrors(count?: number): ShogunError[];
+    /**
+     * Adds a listener for errors
+     * @param listener - Function that will be called when an error occurs
+     */
+    static addListener(listener: (error: ShogunError) => void): void;
+    /**
+     * Removes an error listener
+     * @param listener - Function to remove
+     */
+    static removeListener(listener: (error: ShogunError) => void): void;
+    /**
+     * Notifies all listeners of an error
+     * @param error - Error to notify
+     */
+    private static notifyListeners;
+    /**
+     * Helper function to format error messages from native errors
+     * @param error - Error to format
+     * @returns Formatted error message
+     */
+    static formatError(error: Error | unknown): string;
+    /**
+     * Error handling with retry logic
+     */
+    static withRetry<T>(fn: () => Promise<T>, errorType: ErrorType, errorCode: string, maxRetries?: number, retryDelay?: number): Promise<T>;
+    /**
+     * Clear all stored errors
+     */
+    static clearErrors(): void;
+}

package/dist/types/utils/eventEmitter.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Type for any event data
+ */
+export type EventData = Record<string, unknown>;
+/**
+ * Generic event listener type
+ */
+export type Listener<T = unknown> = (data: T) => void;
+/**
+ * Event type che può essere string o symbol per compatibilità con Node.js EventEmitter
+ */
+export type EventType = string | symbol;
+/**
+ * Simple event emitter implementation with generic event types
+ */
+export declare class EventEmitter<Events extends Record<string, unknown> = Record<string, unknown>> {
+    private events;
+    constructor();
+    /**
+     * Registers an event listener
+     */
+    on(event: EventType, listener: (data: unknown) => void): void;
+    /**
+     * Emits an event with arguments
+     */
+    emit(event: EventType, data?: unknown): boolean;
+    /**
+     * Removes an event listener
+     */
+    off(event: EventType, listener: (data: unknown) => void): void;
+    /**
+     * Registers a one-time event listener
+     */
+    once(event: EventType, listener: (data: unknown) => void): void;
+    /**
+     * Removes all listeners for an event or all events
+     */
+    removeAllListeners(event?: EventType): void;
+}

package/dist/types/utils/validation.d.ts

@@ -0,0 +1,27 @@
+import { OAuthProvider } from "../plugins/oauth/types";
+/**
+ * Valida uno username secondo le regole comuni
+ */
+export declare function validateUsername(username: string): boolean;
+/**
+ * Valida una email
+ */
+export declare function validateEmail(email: string): boolean;
+/**
+ * Valida un provider OAuth supportato
+ */
+export declare function validateProvider(provider: string): provider is OAuthProvider;
+/**
+ * Genera uno username uniforme a partire da provider e userInfo
+ * Esempio: google_utente, github_12345, nostr_pubkey, web3_0xabc...
+ */
+export declare function generateUsernameFromIdentity(provider: string, userInfo: {
+    id?: string;
+    email?: string;
+    name?: string;
+}): string;
+/**
+ * Genera una password deterministica sicura a partire da un salt
+ * Usare per OAuth, Web3, Nostr, ecc.
+ */
+export declare function generateDeterministicPassword(salt: string): string;

package/dist/utils/errorHandler.js

@@ -0,0 +1,241 @@
+/**
+ * Types of errors that can occur in the application
+ */
+export var ErrorType;
+(function (ErrorType) {
+    ErrorType["AUTHENTICATION"] = "AuthenticationError";
+    ErrorType["AUTHORIZATION"] = "AuthorizationError";
+    ErrorType["VALIDATION"] = "ValidationError";
+    ErrorType["NETWORK"] = "NetworkError";
+    ErrorType["DATABASE"] = "DatabaseError";
+    ErrorType["WALLET"] = "WalletError";
+    ErrorType["STORAGE"] = "StorageError";
+    ErrorType["ENCRYPTION"] = "EncryptionError";
+    ErrorType["SIGNATURE"] = "SignatureError";
+    ErrorType["ENVIRONMENT"] = "EnvironmentError";
+    ErrorType["SECURITY"] = "SecurityError";
+    ErrorType["GUN"] = "GunError";
+    ErrorType["STEALTH"] = "StealthError";
+    ErrorType["WEBAUTHN"] = "WebAuthnError";
+    ErrorType["PLUGIN"] = "PluginError";
+    ErrorType["UNKNOWN"] = "UnknownError";
+    ErrorType["CONNECTOR"] = "ConnectorError";
+    ErrorType["GENERAL"] = "GeneralError";
+    ErrorType["CONTRACT"] = "ContractError";
+    ErrorType["BIP32"] = "BIP32Error";
+    ErrorType["ETHEREUM"] = "EthereumError";
+    ErrorType["BITCOIN"] = "BitcoinError";
+})(ErrorType || (ErrorType = {}));
+/**
+ * Wrapper to standardize errors
+ * @param type - Error type
+ * @param code - Error code
+ * @param message - Error message
+ * @param originalError - Original error
+ * @returns A structured error object
+ */
+export function createError(type, code, message, originalError) {
+    return {
+        type,
+        code,
+        message,
+        originalError,
+        timestamp: Date.now(),
+    };
+}
+/**
+ * Centralized error handler
+ */
+export class ErrorHandler {
+    static errors = [];
+    static maxErrors = 100;
+    static listeners = [];
+    static externalLogger = null;
+    /**
+     * Set an external logging service for production error monitoring
+     * @param logger - External logger function to send errors to a monitoring service
+     */
+    static setExternalLogger(logger) {
+        this.externalLogger = logger;
+    }
+    /**
+     * Handles an error by logging it and notifying listeners
+     * @param error - The error to handle
+     */
+    static handleError(error) {
+        // Log essential errors only
+        if (error.type === ErrorType.AUTHENTICATION ||
+            error.type === ErrorType.AUTHORIZATION ||
+            error.type === ErrorType.SECURITY) {
+            // Ensure console.error is available and safe to use
+            if (typeof console !== "undefined" && console.error) {
+                console.error(`[${error.type}] ${error.code}: ${error.message}`);
+            }
+        }
+        // Store the error in memory
+        this.errors.push(error);
+        // Keep only the last maxErrors
+        if (this.errors.length > this.maxErrors) {
+            this.errors = this.errors.slice(-this.maxErrors);
+        }
+        // Send to external logger if set (for production monitoring)
+        if (this.externalLogger) {
+            try {
+                this.externalLogger(error);
+            }
+            catch (e) {
+                // Fallback logging for external logger errors
+                console.error("Failed to send error to external logger:", e);
+            }
+        }
+        // Notify all listeners
+        this.listeners.forEach((listener) => {
+            try {
+                listener(error);
+            }
+            catch (e) {
+                // Silent error to prevent infinite loops
+            }
+        });
+    }
+    /**
+     * Handles a raw error by converting it to ShogunError
+     * @param type - Error type
+     * @param code - Error code
+     * @param message - Error message
+     * @param originalError - Original error
+     * @param logLevel - Log level for the error
+     */
+    static handle(type, code, message, originalError, logLevel = "error") {
+        // Create a formatted error message (tests expect the plain message)
+        const finalMessage = message;
+        // Log the error
+        switch (logLevel) {
+            case "debug":
+                console.log(`[${type}] ${code}: ${finalMessage}`);
+                break;
+            case "warn":
+                console.log(`[${type}] ${code}: ${finalMessage}`);
+                break;
+            case "info":
+                console.log(`[${type}] ${code}: ${finalMessage}`);
+                break;
+            case "error":
+            default:
+                console.log(`[${type}] ${code}: ${finalMessage}`);
+                break;
+        }
+        const error = createError(type, code, finalMessage, originalError);
+        this.handleError(error);
+        return error;
+    }
+    /**
+     * Handles errors and throws them as standardized ShogunError objects
+     * @param type - Error type
+     * @param code - Error code
+     * @param message - Error message
+     * @param originalError - Original error
+     * @throws ShogunError
+     */
+    static handleAndThrow(type, code, message, originalError) {
+        const error = this.handle(type, code, message, originalError);
+        throw error;
+    }
+    /**
+     * Retrieves the last N errors
+     * @param count - Number of errors to retrieve
+     * @returns List of most recent errors
+     */
+    static getRecentErrors(count = 10) {
+        return this.errors.slice(-Math.min(count, this.errors.length));
+    }
+    /**
+     * Adds a listener for errors
+     * @param listener - Function that will be called when an error occurs
+     */
+    static addListener(listener) {
+        this.listeners.push(listener);
+    }
+    /**
+     * Removes an error listener
+     * @param listener - Function to remove
+     */
+    static removeListener(listener) {
+        const index = this.listeners.indexOf(listener);
+        if (index !== -1) {
+            this.listeners.splice(index, 1);
+        }
+    }
+    /**
+     * Notifies all listeners of an error
+     * @param error - Error to notify
+     */
+    static notifyListeners(error) {
+        for (const listener of this.listeners) {
+            try {
+                listener(error);
+            }
+            catch (listenerError) {
+                console.error(`Error in error listener: ${listenerError}`);
+            }
+        }
+    }
+    /**
+     * Helper function to format error messages from native errors
+     * @param error - Error to format
+     * @returns Formatted error message
+     */
+    static formatError(error) {
+        if (!error) {
+            return "Unknown error";
+        }
+        if (error instanceof Error) {
+            return `${error.name}: ${error.message}`;
+        }
+        if (typeof error === "string") {
+            return error;
+        }
+        if (typeof error === "object") {
+            try {
+                return JSON.stringify(error);
+            }
+            catch (e) {
+                return `Object: ${Object.prototype.toString.call(error)}`;
+            }
+        }
+        return String(error);
+    }
+    /**
+     * Error handling with retry logic
+     */
+    static async withRetry(fn, errorType, errorCode, maxRetries = 3, retryDelay = 1000) {
+        let lastError;
+        for (let attempt = 1; attempt <= maxRetries; attempt++) {
+            try {
+                return await fn();
+            }
+            catch (error) {
+                lastError = error;
+                const delay = retryDelay * attempt;
+                if (attempt < maxRetries) {
+                    console.log(`Retrying operation after ${delay}ms (attempt ${attempt}/${maxRetries})`);
+                    await new Promise((resolve) => setTimeout(resolve, delay));
+                }
+            }
+        }
+        // If we got here, all retries failed.
+        // Log the failure and rethrow the last error message for test expectations compatibility.
+        this.handle(errorType, errorCode, `Operation failed after ${maxRetries} attempts`, lastError);
+        // Prefer the original error message if available
+        if (lastError instanceof Error) {
+            throw new Error(lastError.message);
+        }
+        throw new Error(this.formatError(lastError));
+    }
+    /**
+     * Clear all stored errors
+     */
+    static clearErrors() {
+        this.errors = [];
+    }
+}

package/dist/utils/eventEmitter.js

@@ -0,0 +1,76 @@
+/**
+ * Simple event emitter implementation with generic event types
+ */
+export class EventEmitter {
+    events;
+    constructor() {
+        this.events = new Map();
+    }
+    /**
+     * Registers an event listener
+     */
+    on(event, listener) {
+        if (!this.events.has(event)) {
+            this.events.set(event, []);
+        }
+        this.events.get(event)?.push(listener);
+    }
+    /**
+     * Emits an event with arguments
+     */
+    emit(event, data) {
+        if (!this.events.has(event))
+            return false;
+        const listeners = this.events.get(event) || [];
+        listeners.forEach((listener) => {
+            try {
+                listener(data);
+            }
+            catch (error) {
+                // Ensure error is properly formatted for console.error and pass Error instance
+                const err = error instanceof Error ? error : new Error(String(error));
+                console.error(`Error in event listener for ${String(event)}:`, err);
+            }
+        });
+        return true;
+    }
+    /**
+     * Removes an event listener
+     */
+    off(event, listener) {
+        if (!this.events.has(event))
+            return;
+        const listeners = this.events.get(event) || [];
+        const index = listeners.indexOf(listener);
+        if (index !== -1) {
+            listeners.splice(index, 1);
+            if (listeners.length === 0) {
+                this.events.delete(event);
+            }
+            else {
+                this.events.set(event, listeners);
+            }
+        }
+    }
+    /**
+     * Registers a one-time event listener
+     */
+    once(event, listener) {
+        const onceWrapper = (data) => {
+            listener(data);
+            this.off(event, onceWrapper);
+        };
+        this.on(event, onceWrapper);
+    }
+    /**
+     * Removes all listeners for an event or all events
+     */
+    removeAllListeners(event) {
+        if (event) {
+            this.events.delete(event);
+        }
+        else {
+            this.events.clear();
+        }
+    }
+}

package/dist/utils/validation.js

@@ -0,0 +1,72 @@
+// Utility di validazione e generazione credenziali per ShogunCore
+// --- VALIDAZIONE ---
+/**
+ * Valida uno username secondo le regole comuni
+ */
+export function validateUsername(username) {
+    if (!username || typeof username !== "string")
+        return false;
+    if (username.length < 3 || username.length > 64)
+        return false;
+    if (!/^[a-zA-Z0-9._-]+$/.test(username))
+        return false;
+    return true;
+}
+/**
+ * Valida una email
+ */
+export function validateEmail(email) {
+    if (!email || typeof email !== "string")
+        return false;
+    // Regex semplice per email
+    return /^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(email);
+}
+/**
+ * Valida un provider OAuth supportato
+ */
+export function validateProvider(provider) {
+    return ["google", "github", "discord", "twitter", "custom"].includes(provider);
+}
+// --- GENERAZIONE USERNAME ---
+/**
+ * Genera uno username uniforme a partire da provider e userInfo
+ * Esempio: google_utente, github_12345, nostr_pubkey, web3_0xabc...
+ */
+export function generateUsernameFromIdentity(provider, userInfo) {
+    if (provider === "web3" && userInfo.id) {
+        return `web3_${userInfo.id.toLowerCase()}`;
+    }
+    if (provider === "nostr" && userInfo.id) {
+        return `nostr_${userInfo.id}`;
+    }
+    if (provider === "webauthn" && userInfo.id) {
+        return `webauthn_${userInfo.id}`;
+    }
+    if (userInfo.email && validateEmail(userInfo.email)) {
+        return `${provider}_${userInfo.email.split("@")[0]}`;
+    }
+    if (userInfo.name) {
+        return `${provider}_${userInfo.name.replace(/\s+/g, "_")}`;
+    }
+    if (userInfo.id) {
+        return `${provider}_${userInfo.id}`;
+    }
+    return `${provider}_user`;
+}
+// --- GENERAZIONE PASSWORD DETERMINISTICA ---
+import { ethers } from "ethers";
+/**
+ * Genera una password deterministica sicura a partire da un salt
+ * Usare per OAuth, Web3, Nostr, ecc.
+ */
+export function generateDeterministicPassword(salt) {
+    try {
+        // Restituisce una stringa hex di 32 caratteri
+        return ethers.keccak256(ethers.toUtf8Bytes(salt)).slice(2, 34);
+    }
+    catch (error) {
+        // Fallback in case ethers is not available
+        console.warn("ethers not available, using fallback password generation");
+        return Buffer.from(salt).toString("hex").slice(0, 32);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shogun-core",
-  "version": "3.0.4",
+  "version": "3.0.5",
   "description": "SHOGUN CORE - Core library for Shogun Ecosystem",
   "main": "./dist/index.js",
   "module": "./dist/index.js",