shogun-core 5.2.0 → 5.2.2

package/dist/types/config/simplified-config.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Simplified configuration options to reduce complexity
+ * Provides sensible defaults and easy-to-use presets
+ */
+import { ShogunCoreConfig } from "../interfaces/shogun";
+/**
+ * Preset configurations for common use cases
+ */
+export declare const ShogunPresets: {
+    /**
+     * Minimal configuration for simple apps
+     */
+    minimal: () => ShogunCoreConfig;
+    /**
+     * Development configuration with local storage
+     */
+    development: () => ShogunCoreConfig;
+    /**
+     * Production configuration with multiple peers
+     */
+    production: (customPeers?: string[]) => ShogunCoreConfig;
+    /**
+     * Offline-first configuration
+     */
+    offline: () => ShogunCoreConfig;
+    /**
+     * Web3-enabled configuration
+     */
+    web3: () => ShogunCoreConfig;
+    /**
+     * WebAuthn-enabled configuration
+     */
+    webauthn: () => ShogunCoreConfig;
+};
+/**
+ * Configuration builder for custom setups
+ */
+export declare class ShogunConfigBuilder {
+    private config;
+    /**
+     * Set Gun options
+     */
+    gunOptions(options: any): this;
+    /**
+     * Add peers
+     */
+    peers(peerList: string[]): this;
+    /**
+     * Enable WebAuthn
+     */
+    enableWebAuthn(rpName?: string, rpId?: string): this;
+    /**
+     * Enable Web3
+     */
+    enableWeb3(): this;
+    /**
+     * Enable Nostr
+     */
+    enableNostr(): this;
+    /**
+     * Set timeouts
+     */
+    timeouts(timeouts: {
+        login?: number;
+        signup?: number;
+        operation?: number;
+    }): this;
+    /**
+     * Build the final configuration
+     */
+    build(): ShogunCoreConfig;
+}
+/**
+ * Helper functions for common configuration patterns
+ */
+export declare const ConfigHelpers: {
+    /**
+     * Create a configuration for a specific environment
+     */
+    forEnvironment(env: "development" | "production" | "test"): ShogunCoreConfig;
+    /**
+     * Create a configuration with custom peers
+     */
+    withPeers(peers: string[]): ShogunCoreConfig;
+    /**
+     * Create a configuration for a specific use case
+     */
+    forUseCase(useCase: "chat" | "social" | "gaming" | "finance"): ShogunCoreConfig;
+};
+/**
+ * Quick configuration functions
+ */
+export declare const QuickConfig: {
+    /**
+     * Minimal setup for quick testing
+     */
+    test: () => ShogunCoreConfig;
+    /**
+     * Standard setup for most apps
+     */
+    standard: () => ShogunCoreConfig;
+    /**
+     * Setup with WebAuthn for secure apps
+     */
+    secure: () => ShogunCoreConfig;
+    /**
+     * Setup with Web3 for crypto apps
+     */
+    crypto: () => ShogunCoreConfig;
+    /**
+     * Offline setup for local development
+     */
+    local: () => ShogunCoreConfig;
+};

package/dist/types/core.d.ts

@@ -0,0 +1,305 @@
+import { ShogunEventMap } from "./interfaces/events";
+import { ShogunError } from "./utils/errorHandler";
+import { ShogunStorage } from "./storage/storage";
+import { IShogunCore, ShogunCoreConfig, AuthResult, SignUpResult, PluginCategory, AuthMethod, Wallets } from "./interfaces/shogun";
+import { ethers } from "ethers";
+import { ShogunPlugin } from "./interfaces/plugin";
+import { ISEAPair, IGunInstance, IGunUserInstance } from "gun";
+import { DataBase, RxJS } from "./gundb";
+import { PluginManager } from "./managers/PluginManager";
+/**
+ * Main ShogunCore class - implements the IShogunCore interface
+ *
+ * This is the primary entry point for the Shogun SDK, providing access to:
+ * - Decentralized database (GunInstance)
+ * - Authentication methods (traditional, WebAuthn, MetaMask)
+ * - Plugin system for extensibility
+ * - RxJS integration for reactive programming
+ *
+ * @since 2.0.0
+ */
+export declare class ShogunCore implements IShogunCore {
+    static readonly API_VERSION = "^4.0.7";
+    db: DataBase;
+    storage: ShogunStorage;
+    provider?: ethers.Provider;
+    config: ShogunCoreConfig;
+    rx: RxJS;
+    _gun: IGunInstance<any>;
+    _user: IGunUserInstance | null;
+    wallets: Wallets | undefined;
+    pluginManager: PluginManager;
+    private authManager;
+    private eventManager;
+    private coreInitializer;
+    /**
+     * 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.
+     */
+    constructor(config: ShogunCoreConfig);
+    /**
+     * Access to the Gun instance
+     * @returns The Gun instance
+     */
+    get gun(): IGunInstance<any>;
+    /**
+     * Access to the current user
+     * @returns The current Gun user instance
+     */
+    get user(): IGunUserInstance | null;
+    /**
+     * Gets the current user information
+     * @returns Current user object or null
+     */
+    getCurrentUser(): {
+        pub: string;
+        user?: any;
+    } | null;
+    /**
+     * Registers a plugin with the Shogun SDK
+     * @param plugin Plugin instance to register
+     * @throws Error if a plugin with the same name is already registered
+     */
+    register(plugin: ShogunPlugin): void;
+    /**
+     * Unregisters a plugin from the Shogun SDK
+     * @param pluginName Name of the plugin to unregister
+     */
+    unregister(pluginName: string): void;
+    /**
+     * Retrieve a registered plugin by name
+     * @param name Name of the plugin
+     * @returns The requested plugin or undefined if not found
+     * @template T Type of the plugin or its public interface
+     */
+    getPlugin<T = ShogunPlugin>(name: string): T | undefined;
+    /**
+     * Get information about all registered plugins
+     * @returns Array of plugin information objects
+     */
+    getPluginsInfo(): Array<{
+        name: string;
+        version: string;
+        category?: PluginCategory;
+        description?: string;
+    }>;
+    /**
+     * Get the total number of registered plugins
+     * @returns Number of registered plugins
+     */
+    getPluginCount(): number;
+    /**
+     * Check if all plugins are properly initialized
+     * @returns Object with initialization status for each plugin
+     */
+    getPluginsInitializationStatus(): Record<string, {
+        initialized: boolean;
+        error?: string;
+    }>;
+    /**
+     * Validate plugin system integrity
+     * @returns Object with validation results
+     */
+    validatePluginSystem(): {
+        totalPlugins: number;
+        initializedPlugins: number;
+        failedPlugins: string[];
+        warnings: string[];
+    };
+    /**
+     * Attempt to reinitialize failed plugins
+     * @returns Object with reinitialization results
+     */
+    reinitializeFailedPlugins(): {
+        success: string[];
+        failed: Array<{
+            name: string;
+            error: string;
+        }>;
+    };
+    /**
+     * Check plugin compatibility with current ShogunCore version
+     * @returns Object with compatibility information
+     */
+    checkPluginCompatibility(): {
+        compatible: Array<{
+            name: string;
+            version: string;
+        }>;
+        incompatible: Array<{
+            name: string;
+            version: string;
+            reason: string;
+        }>;
+        unknown: Array<{
+            name: string;
+            version: string;
+        }>;
+    };
+    /**
+     * Get comprehensive debug information about the plugin system
+     * @returns Complete plugin system debug information
+     */
+    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;
+            }>;
+        };
+    };
+    /**
+     * Check if a plugin is registered
+     * @param name Name of the plugin to check
+     * @returns true if the plugin is registered, false otherwise
+     */
+    hasPlugin(name: string): boolean;
+    /**
+     * Get all plugins of a specific category
+     * @param category Category of plugins to filter
+     * @returns Array of plugins in the specified category
+     */
+    getPluginsByCategory(category: PluginCategory): ShogunPlugin[];
+    /**
+     * 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): ShogunPlugin | {
+        login: (username: string, password: string) => Promise<AuthResult>;
+        signUp: (username: string, password: string, confirm?: string) => Promise<SignUpResult>;
+    } | undefined;
+    /**
+     * Retrieve recent errors logged by the system
+     * @param count - Number of errors to retrieve (default: 10)
+     * @returns List of most recent errors
+     */
+    getRecentErrors(count?: number): ShogunError[];
+    /**
+     * 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>;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * Saves the current user credentials to storage
+     */
+    saveCredentials(credentials: any): Promise<void>;
+    getIsLoggedIn(): boolean;
+}
+export default ShogunCore;

package/dist/types/crypto/asymmetric.d.ts

@@ -0,0 +1,6 @@
+import { JWKKeyPair } from "./types";
+export declare const generateKeyPair: () => Promise<JWKKeyPair>;
+export declare const deserializePublicKey: (key: JsonWebKey | string) => Promise<CryptoKey>;
+export declare const deserializePrivateKey: (key: JsonWebKey | string) => Promise<CryptoKey>;
+export declare const encrypt: (message: string, publicKey: CryptoKey) => Promise<string>;
+export declare const decrypt: (encryptedMessage: string, privateKey: CryptoKey) => Promise<string>;

package/dist/types/crypto/double-ratchet.d.ts

@@ -0,0 +1,22 @@
+import { DoubleRatchetState, MessageEnvelope } from "./types";
+export declare const initializeDoubleRatchet: (sharedSecret: ArrayBuffer, isInitiator: boolean, remotePublicKey?: CryptoKey | null) => Promise<DoubleRatchetState>;
+export declare const doubleRatchetEncrypt: (state: DoubleRatchetState, plaintext: string) => Promise<MessageEnvelope>;
+export declare const doubleRatchetDecrypt: (state: DoubleRatchetState, messageEnvelope: MessageEnvelope) => Promise<string>;
+export declare const serializeDoubleRatchetState: (state: DoubleRatchetState) => Promise<string>;
+export declare const cleanupSkippedMessageKeys: (state: DoubleRatchetState, maxAge?: number) => void;
+export declare const demonstrateDoubleRatchet: () => Promise<{
+    success: boolean;
+    aliceState: string;
+    bobState: string;
+    conversation: {
+        from: string;
+        envelope: MessageEnvelope;
+    }[];
+    messagesExchanged: number;
+    demonstration: {
+        forwardSecrecy: boolean;
+        outOfOrderHandling: boolean;
+        dhRatcheting: boolean;
+        chainKeyUpdating: boolean;
+    };
+}>;

package/dist/types/crypto/file-encryption.d.ts

@@ -0,0 +1,19 @@
+import { EncryptedFilePackage, DecryptedFileResult } from "./types";
+export declare const encryptFile: (fileContent: string | ArrayBuffer | File, password: string, fileName?: string) => Promise<EncryptedFilePackage>;
+export declare const decryptFile: (encryptedPackage: EncryptedFilePackage, password: string) => Promise<DecryptedFileResult>;
+export declare const encryptTextFile: (textContent: string, password: string, fileName?: string) => Promise<EncryptedFilePackage>;
+export declare const decryptTextFile: (encryptedPackage: EncryptedFilePackage, password: string) => Promise<DecryptedFileResult & {
+    textContent: string;
+}>;
+export declare const encryptBinaryFile: (file: File, password: string) => Promise<EncryptedFilePackage>;
+export declare const decryptBinaryFile: (encryptedPackage: EncryptedFilePackage, password: string) => Promise<DecryptedFileResult & {
+    blob: Blob;
+}>;
+export declare const createSecureFileDownload: (data: ArrayBuffer | string | Blob, fileName: string, mimeType?: string) => void;
+export declare const parseEncryptedFilePackage: (file: File) => Promise<{
+    isValid: boolean;
+    package?: EncryptedFilePackage;
+    metadata?: any;
+    error?: string;
+}>;
+export declare const decryptUploadedFile: (encryptedFilePackage: File, password: string) => Promise<DecryptedFileResult>;

package/dist/types/crypto/hashing.d.ts

@@ -0,0 +1,9 @@
+export declare const randomString: (additionalSalt?: string) => string;
+export declare const sha256Hash: (input: any) => Promise<string>;
+export declare const sha512Hash: (input: any) => Promise<string>;
+export declare const sha3_512Hash: (input: any) => Promise<string>;
+export declare const bufferToHex: (buffer: ArrayBuffer) => string;
+export declare const hexToBuffer: (hex: string) => ArrayBuffer;
+export declare const concatArrayBuffers: (...buffers: ArrayBuffer[]) => ArrayBuffer;
+export declare const base64ToArrayBuffer: (base64: string) => ArrayBuffer;
+export declare const arrayBufferToBase64: (buffer: ArrayBuffer) => string;

package/dist/types/crypto/index.d.ts

@@ -0,0 +1,13 @@
+export * from "./symmetric";
+export * from "./asymmetric";
+export * from "./hashing";
+export * from "./file-encryption";
+export * from "./signal-protocol";
+export * from "./double-ratchet";
+export * from "./random-generation";
+export * from "./mls";
+export * from "./mls-codec";
+export * from "./sframe";
+export * from "./pgp";
+export * from "./types";
+export * from "./utils";

package/dist/types/crypto/mls-codec.d.ts

@@ -0,0 +1,39 @@
+/**
+ * MLS Message encoding/decoding utilities
+ *
+ * Since ts-mls doesn't export encode/decode functions from the main package,
+ * we'll use JSON serialization with Uint8Array and BigInt conversion for transmission.
+ * This works for KeyPackage, Welcome, Commit, and other MLS messages.
+ */
+/**
+ * Encode a KeyPackage to JSON string for transmission
+ */
+export declare function encodeKeyPackage(keyPackage: any): string;
+/**
+ * Decode JSON string back to a KeyPackage object
+ */
+export declare function decodeKeyPackage(encoded: string): any;
+/**
+ * Encode a Welcome message to JSON string for transmission
+ */
+export declare function encodeWelcome(welcome: any): string;
+/**
+ * Decode JSON string back to a Welcome object
+ */
+export declare function decodeWelcome(encoded: string): any;
+/**
+ * Encode a Commit message to JSON string for transmission
+ */
+export declare function encodeCommit(commit: any): string;
+/**
+ * Decode JSON string back to a Commit object
+ */
+export declare function decodeCommit(encoded: string): any;
+/**
+ * Encode a RatchetTree to JSON string for transmission
+ */
+export declare function encodeRatchetTree(ratchetTree: any): string;
+/**
+ * Decode JSON string back to a RatchetTree
+ */
+export declare function decodeRatchetTree(encoded: string): any;

package/dist/types/crypto/mls.d.ts

@@ -0,0 +1,130 @@
+/**
+ * MLS (Message Layer Security) Manager
+ * RFC 9420 implementation using ts-mls library
+ * Provides end-to-end encrypted group messaging with forward secrecy
+ */
+import { type PrivateKeyPackage, type KeyPackage, type Welcome } from "ts-mls";
+export interface MLSGroupInfo {
+    groupId: Uint8Array;
+    members: string[];
+    epoch: bigint;
+}
+export interface MLSMessageEnvelope {
+    groupId: Uint8Array;
+    ciphertext: Uint8Array;
+    timestamp: number;
+}
+export interface MLSKeyPackageBundle {
+    publicPackage: KeyPackage;
+    privatePackage: PrivateKeyPackage;
+    userId: string;
+}
+/**
+ * MLSManager wraps the ts-mls functional API with a class-based interface
+ * for easier state management in applications
+ */
+export declare class MLSManager {
+    private userId;
+    private cipherSuite;
+    private initialized;
+    private groups;
+    private keyPackage;
+    private credential;
+    constructor(userId: string);
+    /**
+     * Initialize the MLS client with a ciphersuite
+     */
+    initialize(): Promise<void>;
+    /**
+     * Generate a new key package for joining groups
+     */
+    generateKeyPackage(): Promise<MLSKeyPackageBundle>;
+    /**
+     * Get the current key package
+     */
+    getKeyPackage(): MLSKeyPackageBundle | null;
+    /**
+     * Create a new MLS group
+     */
+    createGroup(groupId: string): Promise<MLSGroupInfo>;
+    /**
+     * Add members to an existing group
+     */
+    addMembers(groupId: string, keyPackages: MLSKeyPackageBundle[]): Promise<{
+        welcome: Welcome;
+        ratchetTree: any;
+        commit: any;
+    }>;
+    /**
+     * Process a Welcome message to join an MLS group
+     *
+     * RFC 9420 Compliance:
+     * - Interior null nodes represent blank parent nodes (unmerged positions)
+     * - These nulls are REQUIRED for proper binary tree structure
+     * - Trailing nulls are stripped by sender (per RFC 9420 requirement)
+     * - ratchetTree parameter is optional; ts-mls can extract from Welcome extension
+     *
+     * @param welcome - The Welcome message from group creator
+     * @param ratchetTree - Optional ratchet tree (normally provided out-of-band)
+     */
+    processWelcome(welcome: Welcome, ratchetTree?: Uint8Array[]): Promise<MLSGroupInfo>;
+    /**
+     * Encrypt a message for a group
+     */
+    encryptMessage(groupId: string, plaintext: string): Promise<MLSMessageEnvelope>;
+    /**
+     * Decrypt a message from a group
+     */
+    decryptMessage(envelope: MLSMessageEnvelope): Promise<string>;
+    /**
+     * Update the group keys (key rotation)
+     */
+    updateKey(groupId: string): Promise<any>;
+    /**
+     * Process a commit message (key rotation, member changes)
+     *
+     * RFC 9420 Section 12.1.8:
+     * - Update commits (key rotation) → PrivateMessage
+     * - Add/Remove commits → PublicMessage (for existing group members)
+     *
+     * This implementation handles both types based on wireformat.
+     */
+    processCommit(groupId: string, commit: any): Promise<void>;
+    /**
+     * Remove members from a group
+     */
+    removeMembers(groupId: string, memberIndices: number[]): Promise<Uint8Array>;
+    /**
+     * Get list of groups
+     */
+    getGroups(): Promise<Uint8Array[]>;
+    /**
+     * Export group state for persistence
+     */
+    exportGroupState(groupId: string): Promise<any>;
+    /**
+     * Get user ID
+     */
+    getUserId(): string;
+    /**
+     * Get group information
+     */
+    getGroupKeyInfo(groupId: string): Promise<any>;
+    /**
+     * Clean up resources
+     */
+    destroy(): Promise<void>;
+    /**
+     * Extract member identities from group state
+     */
+    private extractMembersFromState;
+    /**
+     * Convert bytes to hex string
+     */
+    private bytesToHex;
+    /**
+     * Ensure the manager is initialized
+     */
+    private ensureInitialized;
+}
+export default MLSManager;