shogun-core 5.2.0 → 5.2.2

package/dist/types/plugins/zkproof/index.d.ts

@@ -0,0 +1,48 @@
+/**
+ * ZK-Proof Plugin for Shogun Core
+ *
+ * Provides Zero-Knowledge Proof authentication using Semaphore protocol
+ *
+ * Features:
+ * - Anonymous authentication without revealing identity
+ * - Multi-device support via trapdoor backup
+ * - Privacy-preserving group membership proofs
+ * - Compatible with Gun decentralized storage
+ *
+ * @example
+ * ```typescript
+ * // Initialize Shogun with ZK-Proof plugin
+ * const shogun = new ShogunCore({
+ *   peers: ['https://gun-manhattan.herokuapp.com/gun'],
+ *   zkproof: {
+ *     enabled: true,
+ *     defaultGroupId: 'my-app-users'
+ *   }
+ * });
+ *
+ * await shogun.initialize();
+ *
+ * // Get the plugin
+ * const zkPlugin = shogun.getPlugin<ZkProofPlugin>('zkproof');
+ *
+ * // Sign up with ZK-Proof
+ * const signupResult = await zkPlugin.signUp();
+ * if (signupResult.success) {
+ *   console.log('Trapdoor (save this!):', signupResult.seedPhrase);
+ *   console.log('Public commitment:', signupResult.username);
+ * }
+ *
+ * // Login with trapdoor
+ * const loginResult = await zkPlugin.login(trapdoor);
+ * if (loginResult.success) {
+ *   console.log('Logged in anonymously!');
+ * }
+ * ```
+ *
+ * @module zkproof
+ */
+export { ZkProofPlugin } from "./zkProofPlugin";
+export { ZkProofConnector } from "./zkProofConnector";
+export { ZkCredentials, CredentialType } from "./zkCredentials";
+export type { ZkIdentityData, ZkProofAuthResult, ZkProofGenerationOptions, ZkProofVerificationResult, ZkProofCredential, ZkProofConfig, ZkProofPluginInterface, SemaphoreProof, } from "./types";
+export type { CredentialClaim, VerifiableCredentialProof, CredentialVerificationResult, } from "./zkCredentials";

package/dist/types/plugins/zkproof/types.d.ts

@@ -0,0 +1,123 @@
+import { ISEAPair } from "gun";
+/**
+ * ZK-Proof identity data
+ */
+export interface ZkIdentityData {
+    /** Semaphore identity commitment (public) */
+    commitment: string;
+    /** Trapdoor (private - used for recovery/login) */
+    trapdoor?: string;
+    /** Nullifier (private) */
+    nullifier?: string;
+    /** Creation timestamp */
+    createdAt: number;
+}
+/**
+ * ZK-Proof authentication result
+ */
+export interface ZkProofAuthResult {
+    success: boolean;
+    commitment?: string;
+    userPub?: string;
+    error?: string;
+}
+/**
+ * ZK-Proof generation options
+ */
+export interface ZkProofGenerationOptions {
+    /** Group ID for Semaphore group */
+    groupId?: string;
+    /** Custom message to prove */
+    message?: string;
+    /** Scope for the proof */
+    scope?: string;
+}
+/**
+ * ZK-Proof verification result
+ */
+export interface ZkProofVerificationResult {
+    success: boolean;
+    verified: boolean;
+    commitment?: string;
+    error?: string;
+}
+/**
+ * ZK-Proof credential for Gun authentication
+ */
+export interface ZkProofCredential {
+    commitment: string;
+    gunPair: ISEAPair;
+    createdAt: number;
+}
+/**
+ * ZK-Proof plugin configuration
+ */
+export interface ZkProofConfig {
+    /** Default group ID */
+    defaultGroupId?: string;
+    /** Enable deterministic identity generation */
+    deterministic?: boolean;
+    /** Minimum entropy for identity generation */
+    minEntropy?: number;
+}
+/**
+ * ZK-Proof plugin interface
+ */
+export interface ZkProofPluginInterface {
+    /**
+     * Generate a new ZK identity
+     * @param seed - Optional seed for deterministic generation
+     * @returns ZK identity data with trapdoor for backup
+     */
+    generateIdentity(seed?: string): Promise<ZkIdentityData>;
+    /**
+     * Restore identity from trapdoor/seed phrase
+     * @param trapdoor - Trapdoor or seed phrase
+     * @returns ZK identity data
+     */
+    restoreIdentity(trapdoor: string): Promise<ZkIdentityData>;
+    /**
+     * Generate credentials for Gun authentication
+     * @param identityData - ZK identity data
+     * @returns Gun SEA pair
+     */
+    generateCredentials(identityData: ZkIdentityData): Promise<ISEAPair>;
+    /**
+     * Generate a zero-knowledge proof
+     * @param identityData - ZK identity data
+     * @param options - Proof generation options
+     * @returns Proof data
+     */
+    generateProof(identityData: ZkIdentityData, options?: ZkProofGenerationOptions): Promise<any>;
+    /**
+     * Verify a zero-knowledge proof
+     * @param proof - Proof data to verify
+     * @param treeDepth - Merkle tree depth (default: 20)
+     * @returns Verification result
+     */
+    verifyProof(proof: any, treeDepth?: number): Promise<ZkProofVerificationResult>;
+    /**
+     * Login with ZK proof
+     * @param trapdoor - User's trapdoor/seed phrase
+     * @returns Authentication result
+     */
+    login(trapdoor: string): Promise<ZkProofAuthResult>;
+    /**
+     * Sign up with new ZK identity
+     * @param seed - Optional seed for deterministic generation
+     * @returns Authentication result with trapdoor for backup
+     */
+    signUp(seed?: string): Promise<ZkProofAuthResult & {
+        trapdoor?: string;
+    }>;
+}
+/**
+ * Semaphore proof data structure
+ */
+export interface SemaphoreProof {
+    merkleTreeRoot: string;
+    nullifierHash: string;
+    signal: string;
+    externalNullifier: string;
+    proof: string[];
+}

package/dist/types/plugins/zkproof/zkCredentials.d.ts

@@ -0,0 +1,112 @@
+import { Identity } from "@semaphore-protocol/identity";
+/**
+ * Types of verifiable credentials
+ */
+export declare enum CredentialType {
+    AGE = "age",
+    CITIZENSHIP = "citizenship",
+    EDUCATION = "education",
+    INCOME = "income",
+    EMPLOYMENT = "employment",
+    HEALTH = "health",
+    CUSTOM = "custom"
+}
+/**
+ * Credential claim data
+ */
+export interface CredentialClaim {
+    /** Type of credential */
+    type: CredentialType;
+    /** Public claim statement */
+    claim: string;
+    /** Private data that proves the claim */
+    privateData: Record<string, any>;
+    /** Issuer of the credential (optional) */
+    issuer?: string;
+    /** Expiration timestamp (optional) */
+    expiresAt?: number;
+}
+/**
+ * Verifiable credential proof
+ */
+export interface VerifiableCredentialProof {
+    /** Type of credential being proved */
+    type: CredentialType;
+    /** Public claim statement */
+    claim: string;
+    /** ZK proof data */
+    proof: {
+        merkleTreeRoot: string;
+        nullifierHash: string;
+        signal: string;
+        externalNullifier: string;
+        proof: string[];
+    };
+    /** Credential hash (for verification) */
+    credentialHash: string;
+    /** Timestamp when proof was generated */
+    timestamp: number;
+}
+/**
+ * Credential verification result
+ */
+export interface CredentialVerificationResult {
+    verified: boolean;
+    type?: CredentialType;
+    claim?: string;
+    timestamp?: number;
+    error?: string;
+}
+/**
+ * ZK Credentials Manager
+ * Extends ZK-Proof functionality to support verifiable credentials
+ */
+export declare class ZkCredentials {
+    private groups;
+    /**
+     * Create a verifiable credential from private data
+     */
+    createCredential(identity: Identity, credentialData: CredentialClaim): {
+        credential: VerifiableCredentialProof;
+        credentialHash: string;
+    };
+    /**
+     * Prove an attribute about yourself without revealing the underlying data
+     */
+    proveAttribute(identity: Identity, credentialData: CredentialClaim, groupId?: string): Promise<VerifiableCredentialProof>;
+    /**
+     * Verify a credential proof
+     */
+    verifyCredential(proof: VerifiableCredentialProof, treeDepth?: number): Promise<CredentialVerificationResult>;
+    /**
+     * Create a group for credential holders
+     */
+    private getOrCreateGroup;
+    /**
+     * Add an identity to a credentials group
+     */
+    addToCredentialGroup(identity: Identity, groupId?: string): void;
+    /**
+     * Common credential proofs
+     */
+    /**
+     * Prove age without revealing exact birthdate
+     */
+    proveAge(identity: Identity, birthDate: Date, minimumAge: number): Promise<VerifiableCredentialProof>;
+    /**
+     * Prove citizenship without revealing country
+     */
+    proveCitizenship(identity: Identity, country: string, region?: string): Promise<VerifiableCredentialProof>;
+    /**
+     * Prove education without revealing institution
+     */
+    proveEducation(identity: Identity, degree: string, university: string, year: number): Promise<VerifiableCredentialProof>;
+    /**
+     * Prove income range without revealing exact amount
+     */
+    proveIncome(identity: Identity, amount: number, minimumRequired: number, currency?: string): Promise<VerifiableCredentialProof>;
+    /**
+     * Cleanup resources
+     */
+    cleanup(): void;
+}

package/dist/types/plugins/zkproof/zkProofConnector.d.ts

@@ -0,0 +1,46 @@
+import { ISEAPair } from "gun";
+import { ZkIdentityData, ZkProofGenerationOptions, ZkProofVerificationResult, ZkProofCredential, SemaphoreProof } from "./types";
+/**
+ * Connector for ZK-Proof operations using Semaphore protocol
+ */
+export declare class ZkProofConnector {
+    private identityCache;
+    private credentialCache;
+    private groups;
+    /**
+     * Generate a new Semaphore identity
+     */
+    generateIdentity(seed?: string): Promise<ZkIdentityData>;
+    /**
+     * Restore identity from trapdoor
+     */
+    restoreIdentity(trapdoor: string): Promise<ZkIdentityData>;
+    /**
+     * Generate Gun credentials from ZK identity
+     */
+    generateCredentials(identityData: ZkIdentityData): Promise<ISEAPair>;
+    /**
+     * Get or create a Semaphore group
+     */
+    private getOrCreateGroup;
+    /**
+     * Add identity to a group
+     */
+    addToGroup(commitment: string, groupId?: string): void;
+    /**
+     * Generate a Semaphore proof
+     */
+    generateProof(identityData: ZkIdentityData, options?: ZkProofGenerationOptions): Promise<SemaphoreProof>;
+    /**
+     * Verify a Semaphore proof
+     */
+    verifyProof(proof: SemaphoreProof, treeDepth?: number): Promise<ZkProofVerificationResult>;
+    /**
+     * Get cached credential by commitment
+     */
+    getCredential(commitment: string): ZkProofCredential | undefined;
+    /**
+     * Clear all caches
+     */
+    cleanup(): void;
+}

package/dist/types/plugins/zkproof/zkProofPlugin.d.ts

@@ -0,0 +1,76 @@
+import { BasePlugin } from "../base";
+import { ShogunCore } from "../../core";
+import { ZkIdentityData, ZkProofPluginInterface, ZkProofGenerationOptions, ZkProofVerificationResult, ZkProofConfig } from "./types";
+import { AuthResult, SignUpResult, PluginCategory } from "../../interfaces/shogun";
+import { ISEAPair } from "gun";
+/**
+ * Plugin for Zero-Knowledge Proof authentication using Semaphore protocol
+ *
+ * Features:
+ * - Anonymous authentication with ZK proofs
+ * - Multi-device support via trapdoor backup
+ * - Privacy-preserving identity management
+ * - Compatible with Gun decentralized storage
+ */
+export declare class ZkProofPlugin extends BasePlugin implements ZkProofPluginInterface {
+    name: string;
+    version: string;
+    description: string;
+    _category: PluginCategory;
+    private connector;
+    private config;
+    constructor(config?: ZkProofConfig);
+    /**
+     * Initialize the plugin
+     */
+    initialize(core: ShogunCore): void;
+    /**
+     * Clean up resources
+     */
+    destroy(): void;
+    /**
+     * Ensure connector is initialized
+     */
+    private assertConnector;
+    /**
+     * Generate a new ZK identity
+     */
+    generateIdentity(seed?: string): Promise<ZkIdentityData>;
+    /**
+     * Restore identity from trapdoor/seed phrase
+     */
+    restoreIdentity(trapdoor: string): Promise<ZkIdentityData>;
+    /**
+     * Generate credentials for Gun authentication
+     */
+    generateCredentials(identityData: ZkIdentityData): Promise<ISEAPair>;
+    /**
+     * Generate a zero-knowledge proof
+     */
+    generateProof(identityData: ZkIdentityData, options?: ZkProofGenerationOptions): Promise<any>;
+    /**
+     * Verify a zero-knowledge proof
+     */
+    verifyProof(proof: any, treeDepth?: number): Promise<ZkProofVerificationResult>;
+    /**
+     * Add identity to a group
+     */
+    addToGroup(commitment: string, groupId?: string): void;
+    /**
+     * Login with ZK proof
+     * @param trapdoor - User's trapdoor/seed phrase
+     * @returns Authentication result
+     */
+    login(trapdoor: string): Promise<AuthResult>;
+    /**
+     * Sign up with new ZK identity
+     * @param seed - Optional seed for deterministic generation
+     * @returns Authentication result with trapdoor for backup
+     */
+    signUp(seed?: string): Promise<SignUpResult>;
+    /**
+     * Check if ZK-Proof is available
+     */
+    isAvailable(): boolean;
+}
+export type { ZkProofPluginInterface } from "./types";

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

@@ -0,0 +1,51 @@
+/**
+ * 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;
+    private silent;
+    /**
+     * Initializes storage and loads any existing keypair from localStorage if available
+     */
+    constructor(silent?: boolean);
+    /**
+     * 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/seedPhrase.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Seed Phrase Utilities for Multi-Device Authentication
+ * Provides BIP39-compatible seed phrase generation and validation
+ */
+/**
+ * Generate a new 12-word BIP39 mnemonic seed phrase
+ * @returns {string} 12-word mnemonic seed phrase
+ */
+export declare function generateSeedPhrase(): string;
+/**
+ * Validate a BIP39 mnemonic seed phrase
+ * @param {string} mnemonic - The seed phrase to validate
+ * @returns {boolean} True if valid, false otherwise
+ */
+export declare function validateSeedPhrase(mnemonic: string): boolean;
+/**
+ * Derive a deterministic seed from mnemonic and username
+ * @param {string} mnemonic - The BIP39 mnemonic seed phrase
+ * @param {string} username - Username to include in derivation
+ * @returns {Uint8Array} 64-byte seed for key derivation
+ */
+export declare function mnemonicToSeed(mnemonic: string, username: string): Uint8Array;
+/**
+ * Convert seed to deterministic password for GunDB
+ * @param {Uint8Array} seed - The seed from mnemonic
+ * @returns {string} Hex-encoded password
+ */
+export declare function seedToPassword(seed: Uint8Array): string;
+/**
+ * Derive GunDB credentials from mnemonic
+ * @param {string} mnemonic - The BIP39 mnemonic
+ * @param {string} username - Username for derivation
+ * @returns {{password: string; seed: Uint8Array}} Credentials for GunDB
+ */
+export declare function deriveCredentialsFromMnemonic(mnemonic: string, username: string): {
+    password: string;
+    seed: Uint8Array;
+};
+/**
+ * Format seed phrase for display (with word numbers)
+ * @param {string} mnemonic - The seed phrase
+ * @returns {string} Formatted seed phrase with numbers
+ */
+export declare function formatSeedPhrase(mnemonic: string): string;
+/**
+ * Normalize and clean user input for seed phrase
+ * @param {string} input - User-provided seed phrase
+ * @returns {string} Normalized seed phrase
+ */
+export declare function normalizeSeedPhrase(input: string): string;

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

@@ -0,0 +1,27 @@
+/**
+ * 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
+ * @deprecated OAuth has been removed from Shogun Core
+ */
+export declare function validateProvider(provider: string): boolean;
+/**
+ * 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;