shogun-core 5.2.0 → 5.2.1

package/dist/types/gundb/api.d.ts

@@ -0,0 +1,185 @@
+/**
+ * Simplified API layer focused on valuable helper methods.
+ * Provides quick-start initialization and high-level convenience methods.
+ *
+ * For basic operations (get, put, set, remove, auth), use DataBase directly.
+ * This class provides:
+ * - Quick initialization helpers (QuickStart, AutoQuickStart)
+ * - Array/Object conversion utilities for GunDB
+ * - High-level user data helpers (profile, settings, collections)
+ */
+import { DataBase } from "./db";
+/**
+ * Simple API wrapper that provides high-level helper methods.
+ * For basic operations, use the DataBase instance directly via the `database` property.
+ */
+export declare class SimpleGunAPI {
+    private db;
+    /**
+     * Create a new SimpleGunAPI instance.
+     * @param db The DataBase instance to use.
+     */
+    constructor(db: DataBase);
+    /**
+     * Get direct access to the DataBase instance for full control.
+     * Use this for basic operations like get, put, set, remove, login, etc.
+     */
+    get database(): DataBase;
+    /**
+     * Convert an array to an indexed object for GunDB storage.
+     * GunDB doesn't store arrays natively, so this converts them to objects indexed by ID.
+     * Example: [{id: '1', ...}, {id: '2', ...}] => { "1": {...}, "2": {...} }
+     * @param arr The array to convert (each item must have an 'id' property).
+     * @returns The indexed object suitable for GunDB storage.
+     */
+    arrayToIndexedObject<T extends {
+        id: string | number;
+    }>(arr: T[]): Record<string, T>;
+    /**
+     * Convert an indexed object back to an array.
+     * Reverses the arrayToIndexedObject conversion.
+     * Example: { "1": {...}, "2": {...} } => [{id: '1', ...}, {id: '2', ...}]
+     * @param indexedObj The indexed object to convert.
+     * @returns The array of items.
+     */
+    indexedObjectToArray<T>(indexedObj: Record<string, T> | null): T[];
+    /**
+     * @deprecated This method is unreliable with GunDB. Use direct GunDB operations instead.
+     * Store an array at a global path by converting it to an indexed object.
+     * @param path The global path to store the array at
+     * @param arr The array to store (each item must have an 'id' property)
+     * @returns True if successful, false otherwise
+     */
+    putArray<T extends {
+        id: string | number;
+    }>(path: string, arr: T[]): Promise<boolean>;
+    /**
+     * @deprecated This method is unreliable with GunDB. Use direct GunDB operations instead.
+     * Retrieve an array from a global path by converting from indexed object.
+     * @param path The global path to retrieve the array from
+     * @returns The array of items, or empty array on error
+     */
+    getArray<T>(path: string): Promise<T[]>;
+    /**
+     * Get all user data (returns user's entire data tree).
+     * Requires user to be logged in.
+     * @returns The complete user data tree, or null if not logged in or on error.
+     */
+    getAllUserData(): Promise<Record<string, unknown> | null>;
+    /**
+     * Update user profile with common fields.
+     * Provides a standardized location for user profile data.
+     * @param profileData Profile data to save (name, email, bio, avatar, etc.)
+     * @returns True if successful, false otherwise.
+     */
+    updateProfile(profileData: {
+        name?: string;
+        email?: string;
+        bio?: string;
+        avatar?: string;
+        [key: string]: unknown;
+    }): Promise<boolean>;
+    /**
+     * Get user profile data.
+     * @returns The user profile data, or null if not found or not logged in.
+     */
+    getProfile(): Promise<Record<string, unknown> | null>;
+    /**
+     * Save user settings.
+     * Provides a standardized location for application settings.
+     * @param settings Settings object to save.
+     * @returns True if successful, false otherwise.
+     */
+    saveSettings(settings: Record<string, unknown>): Promise<boolean>;
+    /**
+     * Get user settings.
+     * @returns The user settings, or null if not found or not logged in.
+     */
+    getSettings(): Promise<Record<string, unknown> | null>;
+    /**
+     * Save user preferences.
+     * Provides a standardized location for user preferences (distinct from settings).
+     * @param preferences Preferences object to save.
+     * @returns True if successful, false otherwise.
+     */
+    savePreferences(preferences: Record<string, unknown>): Promise<boolean>;
+    /**
+     * Get user preferences.
+     * @returns The user preferences, or null if not found or not logged in.
+     */
+    getPreferences(): Promise<Record<string, unknown> | null>;
+    /**
+     * Create a user collection with initial items.
+     * Provides a standardized location for user collections.
+     * @param collectionName The name of the collection.
+     * @param items The initial items for the collection.
+     * @returns True if successful, false otherwise.
+     */
+    createCollection<T = unknown>(collectionName: string, items: Record<string, T>): Promise<boolean>;
+    /**
+     * Add an item to a user collection.
+     * @param collectionName The name of the collection.
+     * @param itemId The ID of the item to add.
+     * @param item The item data.
+     * @returns True if successful, false otherwise.
+     */
+    addToCollection<T = unknown>(collectionName: string, itemId: string, item: T): Promise<boolean>;
+    /**
+     * Get a user collection.
+     * @param collectionName The name of the collection.
+     * @returns The collection data, or null if not found or not logged in.
+     */
+    getCollection(collectionName: string): Promise<Record<string, unknown> | null>;
+    /**
+     * Remove an item from a user collection.
+     * @param collectionName The name of the collection.
+     * @param itemId The ID of the item to remove.
+     * @returns True if successful, false otherwise.
+     */
+    removeFromCollection(collectionName: string, itemId: string): Promise<boolean>;
+}
+/**
+ * Factory function to create a simple API instance
+ */
+export declare function createSimpleAPI(db: DataBase): SimpleGunAPI;
+/**
+ * Quick start helper - creates a simple API with minimal configuration
+ */
+export declare class QuickStart {
+    private db;
+    private simpleAPI;
+    constructor(gunInstance: any, appScope?: string);
+    init(): Promise<void>;
+    get api(): SimpleGunAPI;
+    get database(): DataBase;
+}
+/**
+ * Auto Quick Start helper - creates a simple API with automatic Gun instance creation
+ * No need to pass a Gun instance, it creates one automatically
+ */
+export declare class AutoQuickStart {
+    private db;
+    private simpleAPI;
+    private gunInstance;
+    constructor(config?: {
+        peers?: string[];
+        appScope?: string;
+        [key: string]: any;
+    });
+    init(): Promise<void>;
+    get api(): SimpleGunAPI;
+    get database(): DataBase;
+    get gun(): any;
+}
+/**
+ * Global helper for quick setup
+ */
+export declare function quickStart(gunInstance: any, appScope?: string): QuickStart;
+/**
+ * Global helper for auto quick setup - creates Gun instance automatically
+ */
+export declare function autoQuickStart(config?: {
+    peers?: string[];
+    appScope?: string;
+    [key: string]: any;
+}): AutoQuickStart;

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

@@ -0,0 +1,95 @@
+/**
+ * Cryptographic utilities for GunDB integration.
+ * Based on GunDB's SEA (Security, Encryption, Authorization) module.
+ * @see https://github.com/amark/gun/wiki/Snippets
+ */
+import { ISEAPair } from "gun";
+/**
+ * Checks if a string is a valid GunDB hash
+ * @param str - String to check
+ * @returns True if string matches GunDB hash format (44 chars ending with =)
+ */
+export declare function isHash(str: string): boolean;
+/**
+ * Encrypts data with Gun.SEA
+ * @param data Data to encrypt
+ * @param key Encryption key
+ * @returns Promise that resolves with the encrypted data
+ */
+export declare function encrypt(data: any, key: string): Promise<string>;
+/**
+ * Decrypts data with Gun.SEA
+ * @param encryptedData Encrypted data
+ * @param key Decryption key
+ * @returns Promise that resolves with the decrypted data
+ */
+export declare function decrypt(encryptedData: string, key: string): Promise<string | any>;
+/**
+ * Encrypts data from a sender to a receiver using their public keys
+ * @param data - Data to encrypt
+ * @param sender - Sender's key pair
+ * @param receiver - Receiver's public encryption key
+ * @returns Promise resolving to encrypted data
+ */
+export declare function encFor(data: any, sender: ISEAPair, receiver: {
+    epub: string;
+}): Promise<any>;
+/**
+ * Decrypts data from a sender using receiver's private key
+ * @param data - Data to decrypt
+ * @param sender - Sender's public encryption key
+ * @param receiver - Receiver's key pair
+ * @returns Promise resolving to decrypted data
+ */
+export declare function decFrom(data: any, sender: {
+    epub: string;
+}, receiver: ISEAPair): Promise<any>;
+/**
+ * Creates a SHA-256 hash of text
+ * @param text - Text to hash
+ * @returns Promise resolving to hash string
+ */
+export declare function hashText(text: string): Promise<any>;
+/**
+ * Creates a hash of an object by stringifying it first
+ * @param obj - Object to hash
+ * @returns Promise resolving to hash and original stringified data
+ */
+export declare function hashObj(obj: any): Promise<{
+    hash: any;
+    hashed: string;
+}>;
+/**
+ * Generates a shared secret between two parties
+ * @param epub - Public encryption key
+ * @param pair - Key pair
+ * @returns Promise resolving to shared secret
+ */
+export declare function secret(epub: string, pair: ISEAPair): Promise<string>;
+/**
+ * Creates a short hash using PBKDF2
+ * @param text - Text to hash
+ * @param salt - Salt for hashing
+ * @returns Promise resolving to hex-encoded hash
+ */
+export declare function getShortHash(text: string, salt?: string): Promise<any>;
+/**
+ * Converts unsafe characters in hash to URL-safe versions
+ * @param unsafe - String containing unsafe characters
+ * @returns URL-safe string with encoded characters
+ */
+export declare function safeHash(unsafe: string): any;
+/**
+ * Converts URL-safe characters back to original hash characters
+ * @param safe - URL-safe string
+ * @returns Original string with decoded characters
+ */
+export declare function unsafeHash(safe: string): any;
+/**
+ * Safely parses JSON with fallback to default value
+ * @param input - String to parse as JSON
+ * @param def - Default value if parsing fails
+ * @returns Parsed object or default value
+ */
+export declare function safeJSONParse(input: any, def?: any): any;
+export declare function randomUUID(): string;

package/dist/types/gundb/db.d.ts

@@ -0,0 +1,397 @@
+/**
+ * GunDB class with enhanced features:
+ * - Dynamic peer linking
+ * - Support for remove/unset operations
+ * - Direct authentication through Gun.user()
+ */
+import type { UserInfo, AuthCallback, EventData, EventListener } from "./types";
+import type { IGunUserInstance, IGunChain, IGunInstance, ISEAPair, GunMessagePut } from "gun/types";
+import type { AuthResult, SignUpResult } from "../interfaces/shogun";
+import Gun from "gun/gun";
+import SEA from "gun/sea";
+import "gun/lib/then";
+import "gun/lib/radix";
+import "gun/lib/radisk";
+import "gun/lib/store";
+import "gun/lib/rindexed";
+import "gun/lib/webrtc";
+import derive, { DeriveOptions } from "./derive";
+import { GunDataEventData, GunPeerEventData } from "../interfaces/events";
+import { RxJS } from "./rxjs";
+import * as GunErrors from "./errors";
+import * as crypto from "./crypto";
+declare class DataBase {
+    gun: IGunInstance;
+    user: IGunUserInstance | null;
+    crypto: typeof crypto;
+    sea: typeof SEA;
+    node: IGunChain<any, any, any, any>;
+    core: any;
+    private readonly onAuthCallbacks;
+    private readonly eventEmitter;
+    private _rxjs?;
+    private _cryptoIdentityManager?;
+    constructor(gun: IGunInstance, appScope?: string, core?: any);
+    /**
+     * Initialize the GunInstance asynchronously
+     * This method should be called after construction to perform async operations
+     */
+    initialize(appScope?: string): void;
+    private subscribeToAuthEvents;
+    private notifyAuthListeners;
+    /**
+     * Adds a new peer to the network
+     * @param peer URL of the peer to add
+     */
+    addPeer(peer: string): void;
+    /**
+     * Removes a peer from the network
+     * @param peer URL of the peer to remove
+     */
+    removePeer(peer: string): void;
+    /**
+     * Gets the list of currently connected peers
+     * @returns Array of peer URLs
+     */
+    getCurrentPeers(): string[];
+    /**
+     * Gets the list of all configured peers (connected and disconnected)
+     * @returns Array of peer URLs
+     */
+    getAllConfiguredPeers(): string[];
+    /**
+     * Gets detailed information about all peers
+     * @returns Object with peer information
+     */
+    getPeerInfo(): {
+        [peer: string]: {
+            connected: boolean;
+            status: string;
+        };
+    };
+    /**
+     * Reconnects to a specific peer
+     * @param peer URL of the peer to reconnect
+     */
+    reconnectToPeer(peer: string): void;
+    /**
+     * Clears all peers and optionally adds new ones
+     * @param newPeers Optional array of new peers to add
+     */
+    resetPeers(newPeers?: string[]): void;
+    /**
+     * Registers an authentication callback
+     * @param callback Function to call on auth events
+     * @returns Function to unsubscribe the callback
+     */
+    onAuth(callback: AuthCallback): () => void;
+    /**
+     * Helper method to navigate to a nested path by splitting and chaining .get() calls
+     * @param node Starting Gun node
+     * @param path Path string (e.g., "test/data/marco")
+     * @returns Gun node at the specified path
+     */
+    private navigateToPath;
+    /**
+     * Gets the Gun instance
+     * @returns Gun instance
+     */
+    getGun(): IGunInstance;
+    /**
+     * Gets the current user
+     * @returns Current user object or null
+     */
+    getCurrentUser(): UserInfo | null;
+    /**
+     * Gets the current user instance
+     * @returns User instance
+     */
+    getUser(): IGunUserInstance;
+    /**
+     * Gets a node at the specified path
+     * @param path Path to the node
+     * @returns Gun node
+     */
+    get(path: string): IGunChain<any, any>;
+    /**
+     * Gets data at the specified path (one-time read)
+     * @param path Path to get the data from
+     * @returns Promise resolving to the data
+     */
+    getData(path: string): Promise<any>;
+    /**
+     * Puts data at the specified path
+     * @param path Path to store data
+     * @param data Data to store
+     * @returns Promise resolving to operation result
+     */
+    put(path: string, data: any): Promise<GunMessagePut>;
+    /**
+     * Sets data at the specified path
+     * @param path Path to store data
+     * @param data Data to store
+     * @returns Promise resolving to operation result
+     */
+    set(path: string, data: any): Promise<GunMessagePut>;
+    /**
+     * Removes data at the specified path
+     * @param path Path to remove
+     * @returns Promise resolving to operation result
+     */
+    remove(path: string): Promise<GunMessagePut>;
+    /**
+     * Checks if a user is currently logged in
+     * @returns True if logged in
+     */
+    isLoggedIn(): boolean;
+    /**
+     * Attempts to restore user session from local storage
+     * @returns Promise resolving to session restoration result
+     */
+    restoreSession(): {
+        success: boolean;
+        userPub?: string;
+        error?: string;
+    };
+    logout(): void;
+    /**
+     * Accesses the RxJS module for reactive programming
+     * @returns GunRxJS instance
+     */
+    rx(): RxJS;
+    /**
+     * Validates password strength according to security requirements
+     */
+    private validatePasswordStrength;
+    /**
+     * Validates signup credentials with enhanced security
+     */
+    private validateSignupCredentials;
+    /**
+     * Creates a new user in Gun
+     */
+    private createNewUser;
+    /**
+     * Authenticates user after creation
+     */
+    private authenticateNewUser;
+    /**
+     * Signs up a new user using direct Gun authentication
+     * @param username Username
+     * @param password Password
+     * @param pair Optional SEA pair for Web3 login
+     * @returns Promise resolving to signup result
+     */
+    signUp(username: string, password: string, pair?: ISEAPair | null): Promise<SignUpResult>;
+    /**
+     * Creates a new user in Gun with pair-based authentication (for Web3/plugins)
+     */
+    private createNewUserWithPair;
+    private runPostAuthOnAuthResult;
+    /**
+     * Sets up comprehensive user tracking system for agile user lookup
+     * Creates multiple indexes for efficient user discovery
+     */
+    private setupComprehensiveUserTracking;
+    /**
+     * Creates alias index following GunDB pattern: ~@alias -> userPub
+     */
+    private createAliasIndex;
+    /**
+     * Creates username mapping: usernames/alias -> userPub
+     */
+    private createUsernameMapping;
+    /**
+     * Creates user registry: users/userPub -> user data
+     */
+    private createUserRegistry;
+    /**
+     * Creates reverse lookup: userPub -> alias
+     */
+    private createReverseLookup;
+    /**
+     * Creates epub index: epubKeys/epub -> userPub
+     */
+    private createEpubIndex;
+    /**
+     * Creates user metadata in user's own node
+     */
+    private createUserMetadata;
+    /**
+     * Gets user information by alias using the comprehensive tracking system
+     * @param alias Username/alias to lookup
+     * @returns Promise resolving to user information or null if not found
+     */
+    getUserByAlias(alias: string): Promise<{
+        userPub: string;
+        epub: string | null;
+        username: string;
+        registeredAt: number;
+        lastSeen: number;
+    } | null>;
+    /**
+     * Gets user information by public key
+     * @param userPub User's public key
+     * @returns Promise resolving to user information or null if not found
+     */
+    getUserDataByPub(userPub: string): Promise<{
+        userPub: string;
+        epub: string | null;
+        username: string;
+        registeredAt: number;
+        lastSeen: number;
+    } | null>;
+    /**
+     * Gets user public key by encryption public key (epub)
+     * @param epub User's encryption public key
+     * @returns Promise resolving to user public key or null if not found
+     */
+    getUserPubByEpub(epub: string): Promise<string | null>;
+    /**
+     * Gets user alias by public key
+     * @param userPub User's public key
+     * @returns Promise resolving to user alias or null if not found
+     */
+    getUserAliasByPub(userPub: string): Promise<string | null>;
+    /**
+     * Gets all registered users (for admin purposes)
+     * @returns Promise resolving to array of user information
+     */
+    getAllRegisteredUsers(): Promise<Array<{
+        userPub: string;
+        epub: string | null;
+        username: string;
+        registeredAt: number;
+        lastSeen: number;
+    }>>;
+    /**
+     * Updates user's last seen timestamp
+     * @param userPub User's public key
+     */
+    updateUserLastSeen(userPub: string): Promise<void>;
+    /**
+     * Performs authentication with Gun
+     */
+    private performAuthentication;
+    /**
+     * Builds login result object
+     */
+    private buildLoginResult;
+    /**
+     * Performs login with username and password
+     * @param username Username
+     * @param password Password
+     * @param pair SEA pair (optional)
+     * @returns Promise resolving to AuthResult object
+     */
+    login(username: string, password: string, pair?: ISEAPair | null): Promise<AuthResult>;
+    /**
+     * Performs login with GunDB pair directly
+     * @param username Username
+     * @param pair SEA pair
+     * @returns Promise resolving to AuthResult object
+     */
+    loginWithPair(username: string, pair: ISEAPair): Promise<AuthResult>;
+    private saveCredentials;
+    /**
+     * Sets up security questions and password hint
+     * @param username Username
+     * @param password Current password
+     * @param hint Password hint
+     * @param securityQuestions Array of security questions
+     * @param securityAnswers Array of answers to security questions
+     * @returns Promise resolving with the operation result
+     */
+    setPasswordHintWithSecurity(username: string, password: string, hint: string, securityQuestions: string[], securityAnswers: string[]): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    /**
+     * Recovers password hint using security question answers
+     * @param username Username
+     * @param securityAnswers Array of answers to security questions
+     * @returns Promise resolving with the password hint
+     */
+    forgotPassword(username: string, securityAnswers: string[]): Promise<{
+        success: boolean;
+        hint?: string;
+        error?: string;
+    }>;
+    static Errors: typeof GunErrors;
+    /**
+     * Adds an event listener
+     * @param event Event name
+     * @param listener Event listener function
+     */
+    on(event: string | symbol, listener: EventListener): void;
+    /**
+     * Removes an event listener
+     * @param event Event name
+     * @param listener Event listener function
+     */
+    off(event: string | symbol, listener: EventListener): void;
+    /**
+     * Adds a one-time event listener
+     * @param event Event name
+     * @param listener Event listener function
+     */
+    once(event: string | symbol, listener: EventListener): void;
+    /**
+     * Emits an event
+     * @param event Event name
+     * @param data Event data
+     */
+    emit(event: string | symbol, data?: EventData): boolean;
+    /**
+     * Recall user session
+     */
+    recall(options?: {
+        sessionStorage?: boolean;
+    }): void;
+    /**
+     * Leave user session
+     */
+    leave(): void;
+    /**
+     * Set user data
+     */
+    setUserData(data: any): void;
+    /**
+     * Set password hint
+     */
+    setPasswordHint(hint: string): void;
+    /**
+     * Get password hint
+     */
+    getPasswordHint(): string | null;
+    /**
+     * Save session to storage
+     */
+    saveSession(session: any): void;
+    /**
+     * Load session from storage
+     */
+    loadSession(): any;
+    /**
+     * Clear session
+     */
+    clearSession(): void;
+    /**
+     * Get app scope
+     */
+    getAppScope(): string;
+    /**
+     * Get user public key
+     */
+    getUserPub(): string | null;
+    /**
+     * Check if user is authenticated
+     */
+    isAuthenticated(): boolean;
+}
+declare const createGun: (config: any) => IGunInstance<any>;
+export { Gun, DataBase, SEA, RxJS, crypto, GunErrors, derive, createGun };
+export default Gun;
+export type { IGunUserInstance, IGunInstance, IGunChain } from "gun/types";
+export type { GunDataEventData, GunPeerEventData };
+export type { DeriveOptions };

package/dist/types/gundb/derive.d.ts

@@ -0,0 +1,21 @@
+export interface DeriveOptions {
+    includeSecp256k1Bitcoin?: boolean;
+    includeSecp256k1Ethereum?: boolean;
+    includeP256?: boolean;
+}
+export default function (pwd: any, extra: any, options?: DeriveOptions): Promise<{
+    pub: string;
+    priv: string;
+    epub: string;
+    epriv: string;
+    secp256k1Bitcoin: {
+        privateKey: string;
+        publicKey: string;
+        address: string;
+    };
+    secp256k1Ethereum: {
+        privateKey: string;
+        publicKey: string;
+        address: string;
+    };
+}>;