shogun-core 5.2.0 → 5.2.1

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

@@ -0,0 +1,122 @@
+import { BaseConfig, BaseResult, BaseCacheEntry } from "../../interfaces/common";
+import { AuthResult, SignUpResult } from "../../interfaces/shogun";
+/**
+ * Result of connection attempt
+ */
+export interface ConnectionResult extends BaseResult {
+    address?: string;
+    username?: string;
+    randomPassword?: string;
+    extensionType?: "alby" | "nostr" | "manual";
+}
+/**
+ * Structure for credentials generated via Bitcoin wallet
+ */
+export interface NostrConnectorCredentials {
+    /** Generated username based on the address */
+    username: string;
+    /** Chiave GunDB derivata dalla signature */
+    key: any;
+    /** Original message signed by the user */
+    message: string;
+    /** Signature provided by the wallet */
+    signature: string;
+}
+/**
+ * Alby extension interface
+ */
+export interface AlbyProvider {
+    isAlby?: boolean;
+    enable: () => Promise<any>;
+    signMessage?: (message: string, address?: string) => Promise<string>;
+    getPublicKey?: () => Promise<string>;
+    getInfo?: () => Promise<any>;
+}
+/**
+ * Nostr extension interface
+ */
+export interface NostrProvider {
+    getPublicKey: () => Promise<string>;
+    signEvent: (event: any) => Promise<any>;
+    nip04: {
+        encrypt: (pubkey: string, plaintext: string) => Promise<string>;
+        decrypt: (pubkey: string, ciphertext: string) => Promise<string>;
+    };
+}
+/**
+ * Cache entry for signatures
+ */
+export interface SignatureCache extends BaseCacheEntry<string> {
+    signature: string;
+    address: string;
+}
+/**
+ * Bitcoin wallet configuration options
+ */
+export interface NostrConnectorConfig extends BaseConfig {
+    cacheDuration?: number;
+    network?: "mainnet" | "testnet";
+    useApi?: boolean;
+    apiUrl?: string;
+}
+/**
+ * Bitcoin Key pair interface
+ */
+export interface NostrConnectorKeyPair {
+    privateKey: string;
+    publicKey: string;
+    address: string;
+    type: "legacy" | "segwit" | "taproot" | "nostr";
+}
+/**
+ * Interface for the Bitcoin wallet plugin
+ */
+export interface NostrConnectorPluginInterface {
+    /**
+     * Check if any Bitcoin wallet is available in the browser
+     * @returns true if a wallet is available, false otherwise
+     */
+    isAvailable(): boolean;
+    /**
+     * Connect to a Bitcoin wallet
+     * @param type Type of wallet to connect to
+     * @returns Promise with the connection result
+     */
+    connectBitcoinWallet(type?: "alby" | "nostr" | "manual"): Promise<ConnectionResult>;
+    /**
+     * Generate credentials using a Bitcoin wallet
+     * @param address Bitcoin address
+     * @returns Promise with the generated credentials
+     */
+    generateCredentials(address: string, signature: string, message: string): Promise<NostrConnectorCredentials>;
+    /**
+     * Release resources and clean up event listeners
+     */
+    cleanup(): void;
+    /**
+     * Generate a password based on a signature
+     * @param signature Signature
+     * @returns Promise with the generated password
+     */
+    generatePassword(signature: string): Promise<string>;
+    /**
+     * Verify a signature
+     * @param message Signed message
+     * @param signature Signature to verify
+     * @param address The Bitcoin address that supposedly created the signature
+     * @returns Promise that resolves to true if the signature is valid
+     */
+    verifySignature(message: string, signature: string, address: string): Promise<boolean>;
+    /**
+     * Login with Bitcoin wallet
+     * @param address Bitcoin address
+     * @returns Promise with the operation result
+     */
+    login(address: string): Promise<AuthResult>;
+    /**
+     * Sign up with Nostr wallet
+     * @param address Nostr address
+     * @returns Promise with authentication result
+     */
+    signUp(address: string): Promise<SignUpResult>;
+}

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

@@ -0,0 +1,2 @@
+export * from "./smartWalletPlugin";
+export * from "./types";

package/dist/types/plugins/smartwallet/smartWalletPlugin.d.ts

@@ -0,0 +1,67 @@
+import { BasePlugin } from "../base";
+import { ShogunCore } from "../../core";
+import { SmartWalletPluginInterface, SmartWalletConfig, WalletCreateResult, WalletInfo, ExecutionResult, ProposalInfo, RecoveryRequest } from "./types";
+/**
+ * Smart Wallet Plugin for Shogun Core
+ * Provides integration with Smart Wallet contracts for account abstraction
+ */
+export declare class SmartWalletPlugin extends BasePlugin implements SmartWalletPluginInterface {
+    name: string;
+    version: string;
+    description: string;
+    private config;
+    private factoryContract;
+    private signer;
+    constructor(config?: SmartWalletConfig);
+    /**
+     * Initialize the plugin
+     */
+    initialize(core: ShogunCore): void;
+    /**
+     * Destroy the plugin and cleanup resources
+     */
+    destroy(): void;
+    /**
+     * Initialize provider and signer
+     */
+    private initProvider;
+    /**
+     * Set signer with private key or wallet instance
+     * This should be called after deriving the EOA from seed phrase
+     */
+    setSigner(privateKeyOrAddress: string): Promise<void>;
+    /**
+     * Connect to MetaMask or other injected provider
+     */
+    connectWallet(): Promise<void>;
+    /**
+     * Initialize factory contract
+     */
+    private initFactoryContract;
+    /**
+     * Ensure signer is available
+     */
+    private assertSigner;
+    /**
+     * Ensure factory is initialized
+     */
+    private assertFactory;
+    createWallet(owner: string, requiredSignatures?: number, requiredGuardians?: number): Promise<WalletCreateResult>;
+    createWalletWithGuardians(owner: string, guardians: string[], requiredSignatures?: number, requiredGuardians?: number): Promise<WalletCreateResult>;
+    getWalletInfo(walletAddress: string): Promise<WalletInfo | null>;
+    getOwnerWallets(ownerAddress: string): Promise<string[]>;
+    addSigner(walletAddress: string, signer: string): Promise<ExecutionResult>;
+    removeSigner(walletAddress: string, signer: string): Promise<ExecutionResult>;
+    setRequiredSignatures(walletAddress: string, required: number): Promise<ExecutionResult>;
+    addGuardian(walletAddress: string, guardian: string): Promise<ExecutionResult>;
+    removeGuardian(walletAddress: string, guardian: string): Promise<ExecutionResult>;
+    executeTransaction(walletAddress: string, target: string, data: string, value?: string): Promise<ExecutionResult>;
+    executeBatch(walletAddress: string, targets: string[], dataArray: string[], values: string[]): Promise<ExecutionResult>;
+    proposeExecution(walletAddress: string, target: string, data: string): Promise<ExecutionResult>;
+    approveProposal(walletAddress: string, proposalId: number): Promise<ExecutionResult>;
+    getProposalInfo(walletAddress: string, proposalId: number): Promise<ProposalInfo | null>;
+    initiateRecovery(walletAddress: string, newOwner: string): Promise<ExecutionResult>;
+    approveRecovery(walletAddress: string): Promise<ExecutionResult>;
+    executeRecovery(walletAddress: string): Promise<ExecutionResult>;
+    getRecoveryRequest(walletAddress: string): Promise<RecoveryRequest | null>;
+}

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

@@ -0,0 +1,80 @@
+/**
+ * Configuration options for SmartWallet plugin
+ */
+export interface SmartWalletConfig {
+    enabled?: boolean;
+    factoryAddress?: string;
+    defaultRequiredSignatures?: number;
+    defaultRequiredGuardians?: number;
+    privateKey?: string;
+}
+/**
+ * Result of wallet creation
+ */
+export interface WalletCreateResult {
+    success: boolean;
+    walletAddress?: string;
+    transactionHash?: string;
+    error?: string;
+}
+/**
+ * Wallet information
+ */
+export interface WalletInfo {
+    address: string;
+    owner: string;
+    isSigner: boolean;
+    requiredSignatures: number;
+    requiredGuardians: number;
+}
+/**
+ * Proposal information
+ */
+export interface ProposalInfo {
+    proposalId: number;
+    target: string;
+    proposer: string;
+    approvals: number;
+    executed: boolean;
+}
+/**
+ * Recovery request information
+ */
+export interface RecoveryRequest {
+    newOwner: string;
+    unlockTime: number;
+    approvals: number;
+}
+/**
+ * Transaction execution result
+ */
+export interface ExecutionResult {
+    success: boolean;
+    transactionHash?: string;
+    error?: string;
+}
+/**
+ * Interface for SmartWallet plugin
+ */
+export interface SmartWalletPluginInterface {
+    setSigner(privateKey: string): Promise<void>;
+    connectWallet(): Promise<void>;
+    createWallet(owner: string, requiredSignatures?: number, requiredGuardians?: number): Promise<WalletCreateResult>;
+    createWalletWithGuardians(owner: string, guardians: string[], requiredSignatures?: number, requiredGuardians?: number): Promise<WalletCreateResult>;
+    getWalletInfo(walletAddress: string): Promise<WalletInfo | null>;
+    getOwnerWallets(ownerAddress: string): Promise<string[]>;
+    addSigner(walletAddress: string, signer: string): Promise<ExecutionResult>;
+    removeSigner(walletAddress: string, signer: string): Promise<ExecutionResult>;
+    setRequiredSignatures(walletAddress: string, required: number): Promise<ExecutionResult>;
+    addGuardian(walletAddress: string, guardian: string): Promise<ExecutionResult>;
+    removeGuardian(walletAddress: string, guardian: string): Promise<ExecutionResult>;
+    executeTransaction(walletAddress: string, target: string, data: string, value?: string): Promise<ExecutionResult>;
+    executeBatch(walletAddress: string, targets: string[], dataArray: string[], values: string[]): Promise<ExecutionResult>;
+    proposeExecution(walletAddress: string, target: string, data: string): Promise<ExecutionResult>;
+    approveProposal(walletAddress: string, proposalId: number): Promise<ExecutionResult>;
+    getProposalInfo(walletAddress: string, proposalId: number): Promise<ProposalInfo | null>;
+    initiateRecovery(walletAddress: string, newOwner: string): Promise<ExecutionResult>;
+    approveRecovery(walletAddress: string): Promise<ExecutionResult>;
+    executeRecovery(walletAddress: string): Promise<ExecutionResult>;
+    getRecoveryRequest(walletAddress: string): Promise<RecoveryRequest | null>;
+}

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

@@ -0,0 +1,4 @@
+export * from "./web3ConnectorPlugin";
+export * from "./types";
+export * from "./web3Connector";
+export * from "./web3Signer";

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

@@ -0,0 +1,107 @@
+import { ISEAPair } from "gun";
+import { BaseConfig, BaseResult, BaseCacheEntry } from "../../interfaces/common";
+import { AuthResult, SignUpResult } from "../../interfaces/shogun";
+/**
+ * Result of connection attempt
+ */
+export interface ConnectionResult extends BaseResult {
+    address?: string;
+    username?: string;
+    randomPassword?: string;
+}
+/**
+ * Structure for credentials generated via MetaMask
+ */
+export interface Web3ConnectorCredentials {
+    /** Generated username based on the address */
+    username: string;
+    /** Generated password based on the signature */
+    password: string;
+    /** Original message signed by the user */
+    message: string;
+    /** Signature provided by MetaMask */
+    signature: string;
+}
+/**
+ * Ethereum provider interface
+ */
+export interface EthereumProvider {
+    request: (args: any) => Promise<any>;
+    isMetaMask?: boolean;
+    on?: (event: string, handler: (params: any) => void) => void;
+    removeListener?: (event: string, handler: (params: any) => void) => void;
+}
+/**
+ * Cache entry for signatures
+ */
+export interface SignatureCache extends BaseCacheEntry<string> {
+    signature: string;
+    address: string;
+}
+/**
+ * MetaMask configuration options
+ */
+export interface Web3Config extends BaseConfig {
+    cacheDuration?: number;
+}
+/**
+ * Interfaccia per il plugin MetaMask
+ */
+export interface Web3ConnectorPluginInterface {
+    /**
+     * Verifica se MetaMask è disponibile nel browser
+     * @returns true se MetaMask è disponibile, false altrimenti
+     */
+    isAvailable(): boolean;
+    /**
+     * Connette a MetaMask
+     * @returns Promise con il risultato della connessione
+     */
+    connectMetaMask(): Promise<ConnectionResult>;
+    /**
+     * Genera credenziali utilizzando MetaMask
+     * @param address Indirizzo Ethereum
+     * @returns Promise con le credenziali generate
+     */
+    generateCredentials(address: string): Promise<ISEAPair>;
+    /**
+     * Rilascia le risorse e pulisce gli event listener
+     */
+    cleanup(): void;
+    /**
+     * Imposta un provider personalizzato
+     * @param rpcUrl URL del provider RPC
+     * @param privateKey Chiave privata
+     */
+    setCustomProvider(rpcUrl: string, privateKey: string): void;
+    /**
+     * Ottiene il signer Ethereum
+     * @returns Promise con il signer
+     */
+    getSigner(): Promise<any>;
+    /**
+     * Genera una password basata su una firma
+     * @param signature Firma
+     * @returns Promise con la password generata
+     */
+    generatePassword(signature: string): Promise<string>;
+    /**
+     * Verifica una firma
+     * @param message Messaggio firmato
+     * @param signature Firma da verificare
+     * @returns Promise con l'indirizzo che ha generato la firma
+     */
+    verifySignature(message: string, signature: string): Promise<string>;
+    /**
+     * Login con MetaMask
+     * @param address Indirizzo Ethereum
+     * @returns Promise con il risultato dell'operazione
+     */
+    login(address: string): Promise<AuthResult>;
+    /**
+     * Sign up with Web3 wallet
+     * @param address Ethereum address
+     * @returns Promise with authentication result
+     */
+    signUp(address: string): Promise<SignUpResult>;
+}

package/dist/types/plugins/web3/web3Connector.d.ts

@@ -0,0 +1,129 @@
+/**
+ * The MetaMaskAuth class provides functionality for connecting, signing up, and logging in using MetaMask.
+ */
+import { ethers } from "ethers";
+import { EventEmitter } from "../../utils/eventEmitter";
+import { ConnectionResult, EthereumProvider, Web3Config } from "./types";
+import { ISEAPair } from "gun";
+declare global {
+    interface Window {
+        ethereum?: EthereumProvider;
+        Web3Connector?: typeof Web3Connector;
+        _ethereumProviders?: EthereumProvider[];
+    }
+}
+declare global {
+    namespace NodeJS {
+        interface Global {
+            web3Connector?: typeof Web3Connector;
+        }
+    }
+}
+/**
+ * Class for MetaMask connection
+ */
+declare class Web3Connector extends EventEmitter {
+    private readonly MESSAGE_TO_SIGN;
+    private readonly DEFAULT_CONFIG;
+    private readonly config;
+    private readonly signatureCache;
+    private provider;
+    private customProvider;
+    private customWallet;
+    constructor(config?: Partial<Web3Config>);
+    /**
+     * Initialize the provider synchronously with fallback mechanisms
+     * to handle conflicts between multiple wallet providers
+     */
+    private initProvider;
+    /**
+     * Get available Ethereum provider from multiple possible sources
+     */
+    private getAvailableEthereumProvider;
+    /**
+     * Initialize the BrowserProvider (async method for explicit calls)
+     */
+    setupProvider(): Promise<void>;
+    /**
+     * Setup MetaMask event listeners using BrowserProvider
+     */
+    private setupEventListeners;
+    /**
+     * Cleanup event listeners
+     */
+    cleanup(): void;
+    /**
+     * Get cached signature if valid
+     */
+    private getCachedSignature;
+    /**
+     * Cache signature
+     */
+    private cacheSignature;
+    /**
+     * Validates that the address is valid
+     */
+    private validateAddress;
+    /**
+     * Connects to MetaMask with retry logic using BrowserProvider
+     */
+    connectMetaMask(): Promise<ConnectionResult>;
+    /**
+     * Generates credentials for the given address
+     */
+    generateCredentials(address: string): Promise<ISEAPair>;
+    /**
+     * Generates credentials from a signature
+     */
+    private generateCredentialsFromSignature;
+    /**
+     * Generates fallback credentials (for testing/development)
+     */
+    private generateFallbackCredentials;
+    /**
+     * Checks if MetaMask is available
+     */
+    static isMetaMaskAvailable(): boolean;
+    /**
+     * Requests signature with timeout
+     */
+    private requestSignatureWithTimeout;
+    /**
+     * Checks if the connector is available
+     */
+    isAvailable(): boolean;
+    /**
+     * Sets a custom provider for testing/development
+     */
+    setCustomProvider(rpcUrl: string, privateKey: string): void;
+    /**
+     * Get active signer instance using BrowserProvider
+     */
+    getSigner(): Promise<ethers.Signer>;
+    /**
+     * Get active provider instance using BrowserProvider
+     */
+    getProvider(): Promise<ethers.JsonRpcProvider | ethers.BrowserProvider>;
+    /**
+     * Generate deterministic password from signature
+     * @param signature - Cryptographic signature
+     * @returns 64-character hex string
+     * @throws {Error} For invalid signature
+     */
+    generatePassword(signature: string): Promise<string>;
+    /**
+     * Verify message signature
+     * @param message - Original signed message
+     * @param signature - Cryptographic signature
+     * @returns Recovered Ethereum address
+     * @throws {Error} For invalid inputs
+     */
+    verifySignature(message: string, signature: string): Promise<string>;
+    /**
+     * Get browser-based Ethereum signer
+     * @returns Browser provider signer
+     * @throws {Error} If MetaMask not detected
+     */
+    getEthereumSigner(): Promise<ethers.Signer>;
+}
+export { Web3Connector };

package/dist/types/plugins/web3/web3ConnectorPlugin.d.ts

@@ -0,0 +1,160 @@
+import { BasePlugin } from "../base";
+import { ShogunCore } from "../../core";
+import { Web3SigningCredential } from "./web3Signer";
+import { ConnectionResult, Web3ConnectorPluginInterface } from "./types";
+import { ethers } from "ethers";
+import { AuthResult, SignUpResult } from "../../interfaces/shogun";
+import { ISEAPair } from "gun";
+/**
+ * Plugin per la gestione delle funzionalità Web3 in ShogunCore
+ */
+export declare class Web3ConnectorPlugin extends BasePlugin implements Web3ConnectorPluginInterface {
+    name: string;
+    version: string;
+    description: string;
+    private Web3;
+    private signer;
+    /**
+     * @inheritdoc
+     */
+    initialize(core: ShogunCore): void;
+    /**
+     * @inheritdoc
+     */
+    destroy(): void;
+    /**
+     * Assicura che il modulo Web3 sia inizializzato
+     * @private
+     */
+    private assertMetaMask;
+    /**
+     * Assicura che il signer sia inizializzato
+     * @private
+     */
+    private assertSigner;
+    /**
+     * @inheritdoc
+     */
+    isAvailable(): boolean;
+    /**
+     * @inheritdoc
+     */
+    connectMetaMask(): Promise<ConnectionResult>;
+    /**
+     * @inheritdoc
+     */
+    generateCredentials(address: string): Promise<ISEAPair>;
+    /**
+     * @inheritdoc
+     */
+    cleanup(): void;
+    /**
+     * @inheritdoc
+     */
+    setCustomProvider(rpcUrl: string, privateKey: string): void;
+    /**
+     * @inheritdoc
+     */
+    getSigner(): Promise<ethers.Signer>;
+    /**
+     * @inheritdoc
+     */
+    getProvider(): Promise<ethers.JsonRpcProvider | ethers.BrowserProvider>;
+    /**
+     * @inheritdoc
+     */
+    generatePassword(signature: string): Promise<string>;
+    /**
+     * @inheritdoc
+     */
+    verifySignature(message: string, signature: string): Promise<string>;
+    /**
+     * Creates a new Web3 signing credential
+     * CONSISTENT with normal Web3 approach
+     */
+    createSigningCredential(address: string): Promise<Web3SigningCredential>;
+    /**
+     * Creates an authenticator function for Web3 signing
+     */
+    createAuthenticator(address: string): (data: any) => Promise<string>;
+    /**
+     * Creates a derived key pair from Web3 credential
+     */
+    createDerivedKeyPair(address: string, extra?: string[]): Promise<{
+        pub: string;
+        priv: string;
+        epub: string;
+        epriv: string;
+    }>;
+    /**
+     * Signs data with derived keys after Web3 verification
+     */
+    signWithDerivedKeys(data: any, address: string, extra?: string[]): Promise<string>;
+    /**
+     * Get signing credential by address
+     */
+    getSigningCredential(address: string): Web3SigningCredential | undefined;
+    /**
+     * List all signing credentials
+     */
+    listSigningCredentials(): Web3SigningCredential[];
+    /**
+     * Remove a signing credential
+     */
+    removeSigningCredential(address: string): boolean;
+    /**
+     * Creates a Gun user from Web3 signing credential
+     * This ensures the SAME user is created as with normal approach
+     */
+    createGunUserFromSigningCredential(address: string): Promise<{
+        success: boolean;
+        userPub?: string;
+        error?: string;
+    }>;
+    /**
+     * Get the Gun user public key for a signing credential
+     */
+    getGunUserPubFromSigningCredential(address: string): Promise<string | undefined>;
+    /**
+     * Get the password (for consistency checking)
+     */
+    getPassword(address: string): string | undefined;
+    /**
+     * Verify consistency between oneshot and normal approaches
+     * This ensures both approaches create the same Gun user
+     */
+    verifyConsistency(address: string, expectedUserPub?: string): Promise<{
+        consistent: boolean;
+        actualUserPub?: string;
+        expectedUserPub?: string;
+    }>;
+    /**
+     * Complete oneshot workflow that creates the SAME Gun user as normal approach
+     * This is the recommended method for oneshot signing with full consistency
+     */
+    setupConsistentOneshotSigning(address: string): Promise<{
+        credential: Web3SigningCredential;
+        authenticator: (data: any) => Promise<string>;
+        gunUser: {
+            success: boolean;
+            userPub?: string;
+            error?: string;
+        };
+        username: string;
+        password: string;
+    }>;
+    /**
+     * Login con Web3
+     * @param address - Indirizzo Ethereum
+     * @returns {Promise<AuthResult>} Risultato dell'autenticazione
+     * @description Autentica l'utente usando le credenziali del wallet Web3 dopo la verifica della firma
+     */
+    login(address: string): Promise<AuthResult>;
+    /**
+     * Register new user with Web3 wallet
+     * @param address - Ethereum address
+     * @returns {Promise<SignUpResult>} Registration result
+     */
+    signUp(address: string): Promise<SignUpResult>;
+}
+export type { Web3ConnectorPluginInterface } from "./types";