shogun-core 3.2.3 → 3.3.0

package/dist/types/ship/implementation/SHIP_02.d.ts

@@ -0,0 +1,297 @@
+/**
+ * SHIP-02: Ethereum HD Wallet Implementation
+ *
+ * Full port of shogun-BIP44 with SHIP-00 derivation.
+ * Extends SHIP-00 to provide deterministic Ethereum address derivation.
+ *
+ * Based on:
+ * - SHIP-00 for identity foundation (replaces mnemonic dependency)
+ * - BIP-32 for hierarchical deterministic wallets
+ * - BIP-44 for multi-account hierarchy
+ * - Ethers.js for Ethereum operations
+ * - Gun/SEA for encrypted storage
+ *
+ * Features:
+ * ✅ Deterministic address derivation from SHIP-00 identity (no mnemonics needed)
+ * ✅ BIP-44 compliant HD wallet support
+ * ✅ Multiple address management
+ * ✅ Transaction signing
+ * ✅ Message signing and verification
+ * ✅ Gun persistence with encryption
+ * ✅ Export/import functionality
+ * ✅ Address book management
+ *
+ * Note: Stealth addresses moved to SHIP-03
+ */
+import type { ISHIP_00 } from "../interfaces/ISHIP_00";
+import type { ISHIP_02, DerivationResult, StealthAddressResult, SignatureResult, Transaction, AddressEntry, AddressBook, SHIP_02_Config, WalletInfo } from "../interfaces/ISHIP_02";
+import { ethers } from "ethers";
+/**
+ * SHIP-02 Reference Implementation
+ *
+ * Provides Ethereum address derivation on top of SHIP-00 identity.
+ * All addresses are deterministically derived from the user's SHIP-00 keypair.
+ */
+declare class SHIP_02 implements ISHIP_02 {
+    private identity;
+    private config;
+    private initialized;
+    static readonly NODES: {
+        readonly ADDRESS_BOOK: "addressbook";
+        readonly MNEMONIC: "mnemonic";
+        readonly WALLET_PATHS: "wallet_paths";
+    };
+    private masterSeed;
+    private mnemonic;
+    private hdWallet;
+    private addressCache;
+    private walletCache;
+    private nextIndex;
+    private persistToGun;
+    private provider;
+    private mainWallet;
+    private walletPaths;
+    constructor(identity: ISHIP_00, config?: SHIP_02_Config);
+    initialize(useMnemonic?: boolean): Promise<void>;
+    isInitialized(): boolean;
+    deriveEthereumAddress(path?: string): Promise<DerivationResult>;
+    deriveMultipleAddresses(count: number, startIndex?: number): Promise<DerivationResult[]>;
+    getPrimaryAddress(): Promise<string>;
+    deriveBIP44Address(coinType?: number, account?: number, change?: number, index?: number): Promise<DerivationResult>;
+    deriveMultipleAccounts(accountCount: number): Promise<DerivationResult[]>;
+    /**
+     * @deprecated Use SHIP-03 for dual-key stealth addresses
+     */
+    generateStealthAddress(recipientPublicKey?: string): Promise<StealthAddressResult>;
+    /**
+     * @deprecated Use SHIP-03 for stealth operations
+     */
+    deriveSharedSecret(publicKey: string): Promise<string>;
+    /**
+     * @deprecated Use SHIP-03 for stealth operations
+     */
+    isStealthAddress(address: string): Promise<boolean>;
+    getPrivateKeyForAddress(address: string): Promise<string>;
+    getPublicKeyForAddress(address: string): Promise<string>;
+    getPathForAddress(address: string): Promise<string | undefined>;
+    signTransaction(tx: Transaction, address: string): Promise<SignatureResult>;
+    /**
+     * Send transaction to Ethereum network
+     * Combines signing + broadcasting in one step
+     */
+    sendTransaction(tx: Transaction, address: string, waitForConfirmation?: boolean): Promise<{
+        success: boolean;
+        txHash?: string;
+        receipt?: ethers.TransactionReceipt;
+        error?: string;
+    }>;
+    signMessage(message: string | Uint8Array, address: string): Promise<string>;
+    verifySignature(message: string | Uint8Array, signature: string, address: string): Promise<boolean>;
+    getAllAddresses(): Promise<AddressEntry[]>;
+    getAddressByIndex(index: number): Promise<AddressEntry | undefined>;
+    setAddressLabel(address: string, label: string): Promise<void>;
+    exportAddressBook(): Promise<AddressBook>;
+    importAddressBook(addressBook: AddressBook): Promise<void>;
+    /**
+     * Enable persistence to Gun database
+     */
+    enableGunPersistence(): void;
+    /**
+     * Disable persistence to Gun database
+     */
+    disableGunPersistence(): void;
+    /**
+     * Save address book to Gun (private storage)
+     */
+    private saveAddressBookToGun;
+    /**
+     * Load address book from Gun
+     */
+    loadAddressBookFromGun(): Promise<AddressBook | null>;
+    /**
+     * Sync local cache with Gun storage
+     */
+    syncWithGun(): Promise<void>;
+    ownsAddress(address: string): Promise<boolean>;
+    getMasterPublicKey(): Promise<string>;
+    clearCache(): Promise<void>;
+    /**
+     * Generate new BIP-39 mnemonic (12 words)
+     * Compatible with MetaMask and other wallets
+     */
+    generateNewMnemonic(): string;
+    /**
+     * Get addresses that would be derived from a mnemonic (standard BIP-44)
+     * Useful to verify compatibility with MetaMask
+     */
+    getStandardBIP44Addresses(mnemonic: string, count?: number): string[];
+    /**
+     * Get current mnemonic (if using mnemonic mode)
+     */
+    getMnemonic(): Promise<string | null>;
+    /**
+     * Get user's master mnemonic from Gun or localStorage
+     * Used by createWallet/loadWallets for frontend compatibility
+     */
+    getUserMasterMnemonic(): Promise<string | null>;
+    /**
+     * Export mnemonic (encrypted)
+     */
+    exportMnemonic(): Promise<string | null>;
+    /**
+     * Import mnemonic and re-initialize wallet
+     */
+    importMnemonic(encryptedMnemonic: string): Promise<void>;
+    /**
+     * Save mnemonic to Gun (encrypted)
+     */
+    private saveMnemonicToGun;
+    /**
+     * Load mnemonic from Gun (encrypted)
+     */
+    private loadMnemonicFromGun;
+    /**
+     * Get storage identifier for current user
+     */
+    getStorageUserIdentifier(): string;
+    /**
+     * Encrypt sensitive data using SEA
+     */
+    encryptSensitiveData(text: string): Promise<string>;
+    /**
+     * Decrypt sensitive data using SEA
+     */
+    decryptSensitiveData(encryptedText: string): Promise<string | null>;
+    /**
+     * Export master seed (encrypted)
+     * SECURITY: Handle with extreme care!
+     */
+    exportMasterSeed(): Promise<string>;
+    /**
+     * Export all wallet data (encrypted)
+     */
+    exportWalletData(): Promise<string>;
+    /**
+     * Import wallet data (encrypted)
+     */
+    importWalletData(encryptedData: string): Promise<void>;
+    /**
+     * Ensure system is initialized
+     */
+    private ensureInitialized;
+    /**
+     * Derive master seed from SHIP-00 keypair
+     */
+    private deriveMasterSeed;
+    /**
+     * Build BIP-44 derivation path
+     */
+    private buildBIP44Path;
+    /**
+     * Set RPC provider URL
+     */
+    setRpcUrl(rpcUrl: string): Promise<void>;
+    /**
+     * Get current RPC provider
+     */
+    getProvider(): ethers.JsonRpcProvider | null;
+    /**
+     * Get signer (main wallet connected to provider)
+     */
+    getSigner(): ethers.Wallet;
+    /**
+     * Set custom signer
+     */
+    setSigner(signer: ethers.Wallet): Promise<void>;
+    /**
+     * Get main wallet (derived from Gun user keys, not BIP-44)
+     * This provides a consistent "main" wallet independent of HD derivation
+     */
+    getMainWallet(): ethers.Wallet;
+    /**
+     * Get main wallet credentials
+     */
+    getMainWalletCredentials(): {
+        address: string;
+        priv: string;
+    };
+    /**
+     * Create new wallet with auto-incremented index
+     * Frontend-friendly API that returns ready-to-use wallet object
+     */
+    createWallet(): Promise<WalletInfo>;
+    /**
+     * Load all wallets from stored paths
+     * Reconstructs wallet objects from mnemonic/seed and paths
+     */
+    loadWallets(): Promise<WalletInfo[]>;
+    /**
+     * Export wallet keys for all derived addresses
+     */
+    exportWalletKeys(): Promise<string>;
+    /**
+     * Export Gun SEA keypair
+     */
+    exportGunPair(): Promise<string>;
+    /**
+     * Export all user data (mnemonic, wallets, Gun pair)
+     */
+    exportAllUserData(): Promise<string>;
+    /**
+     * Import wallet keys and restore wallets
+     */
+    importWalletKeys(walletsData: string): Promise<number>;
+    /**
+     * Import Gun SEA keypair
+     * Note: This is a placeholder for compatibility
+     * SHIP-02 doesn't manage Gun keys directly (use SHIP-00 for that)
+     */
+    importGunPair(pairData: string): Promise<boolean>;
+    /**
+     * Import all user data from backup
+     */
+    importAllUserData(backupData: string, options?: {
+        importMnemonic?: boolean;
+        importWallets?: boolean;
+        importGunPair?: boolean;
+    }): Promise<{
+        success: boolean;
+        mnemonicImported?: boolean;
+        walletsImported?: number;
+        gunPairImported?: boolean;
+    }>;
+    /**
+     * Initialize wallet paths from Gun storage
+     */
+    initializeWalletPaths(): Promise<void>;
+    /**
+     * Save wallet paths to localStorage
+     */
+    saveWalletPathsToLocalStorage(): Promise<void>;
+    /**
+     * Load wallet paths from localStorage
+     */
+    loadWalletPathsFromLocalStorage(): Promise<void>;
+    /**
+     * Save wallet paths to Gun
+     */
+    private saveWalletPathsToGun;
+    /**
+     * Load wallet paths from Gun
+     */
+    private loadWalletPathsFromGun;
+    /**
+     * Generate deterministic private key from string seed
+     * Uses same algorithm as shogun-BIP44 for compatibility
+     */
+    private generatePrivateKeyFromString;
+    /**
+     * Initialize wallet paths and test encryption system
+     */
+    initializeWalletPathsAndTestEncryption(): Promise<void>;
+    /**
+     * Cleanup resources
+     */
+    cleanup(): Promise<void>;
+}
+export { SHIP_02 };

package/dist/types/ship/implementation/SHIP_03.d.ts

@@ -0,0 +1,127 @@
+/**
+ * SHIP-03: Dual-Key Stealth Address Implementation
+ *
+ * Full port of shogun-stealth-address with Fluidkey integration.
+ * Extends SHIP-00 and SHIP-02 to provide ERC-5564 compatible stealth addresses.
+ *
+ * Based on:
+ * - SHIP-00 for identity foundation
+ * - SHIP-02 for Ethereum operations
+ * - ERC-5564 for stealth address standard
+ * - Fluidkey Stealth Account Kit
+ * - @scure/bip32 for HD key derivation
+ *
+ * Features:
+ * ✅ Dual-key stealth (viewing + spending keys)
+ * ✅ ERC-5564 / Fluidkey compatible
+ * ✅ Deterministic derivation from SHIP-00
+ * ✅ View tag optimization for scanning
+ * ✅ Announcement metadata
+ * ✅ Batch generation
+ * ✅ Fluidkey generateStealthAddresses
+ * ✅ Fluidkey generateStealthPrivateKey
+ */
+import type { ISHIP_00 } from "../interfaces/ISHIP_00";
+import type { ISHIP_02 } from "../interfaces/ISHIP_02";
+import type { ISHIP_03, StealthKeys, EphemeralKeyPair, StealthAddressResult, StealthMetadata, AnnouncedStealth, OwnedStealthAddress, SHIP_03_Config } from "../interfaces/ISHIP_03";
+/**
+ * SHIP-03 Reference Implementation
+ *
+ * Full Fluidkey-compatible stealth address system derived from SHIP-00.
+ * All keys are deterministically derived from the user's SHIP-00 identity.
+ */
+declare class SHIP_03 implements ISHIP_03 {
+    private identity;
+    private eth;
+    private config;
+    private initialized;
+    static readonly NODES: {
+        readonly STEALTH_KEYS_PUBLIC: "stealth_keys_public";
+        readonly STEALTH_ANNOUNCEMENTS: "stealth_announcements";
+    };
+    private viewingKey;
+    private spendingKey;
+    private ownedStealthAddresses;
+    private announcementCache;
+    constructor(identity: ISHIP_00, eth: ISHIP_02, config?: SHIP_03_Config);
+    initialize(): Promise<void>;
+    isInitialized(): boolean;
+    getStealthKeys(): Promise<StealthKeys>;
+    /**
+     * Get public stealth keys by username (alias)
+     * Resolves username → Gun pub → stealth keys
+     */
+    getPublicStealthKeysByUsername(username: string): Promise<{
+        viewingPublicKey: string;
+        spendingPublicKey: string;
+    } | null>;
+    /**
+     * Get public stealth keys by Gun public key
+     */
+    getPublicStealthKeys(userPub: string): Promise<{
+        viewingPublicKey: string;
+        spendingPublicKey: string;
+    } | null>;
+    /**
+     * Search stealth keys in directory (all published keys)
+     * Returns list of users who have published stealth keys
+     */
+    searchStealthDirectory(): Promise<Array<{
+        username?: string;
+        gunPub: string;
+        viewingPublicKey: string;
+        spendingPublicKey: string;
+        timestamp?: number;
+    }>>;
+    exportStealthKeys(): Promise<string>;
+    importStealthKeys(encryptedKeys: string): Promise<void>;
+    generateEphemeralKeyPair(): Promise<EphemeralKeyPair>;
+    generateStealthAddress(recipientViewingKey: string, recipientSpendingKey: string, ephemeralPrivateKey?: string): Promise<StealthAddressResult>;
+    generateMultipleStealthAddresses(recipients: Array<{
+        viewingKey: string;
+        spendingKey: string;
+    }>, ephemeralPrivateKey?: string): Promise<StealthAddressResult[]>;
+    openStealthAddress(stealthAddress: string, ephemeralPublicKey: string): Promise<any>;
+    isStealthAddressMine(stealthAddress: string, ephemeralPublicKey: string): Promise<boolean>;
+    getStealthPrivateKey(stealthAddress: string, ephemeralPublicKey: string): Promise<string>;
+    scanStealthAddresses(announcements: AnnouncedStealth[]): Promise<OwnedStealthAddress[]>;
+    quickScanWithViewTags(announcements: AnnouncedStealth[]): Promise<AnnouncedStealth[]>;
+    createAnnouncementMetadata(stealthAddress: string, ephemeralPublicKey: string): StealthMetadata;
+    parseAnnouncement(txData: any): Promise<AnnouncedStealth | null>;
+    getAllOwnedStealthAddresses(): Promise<OwnedStealthAddress[]>;
+    clearCache(): Promise<void>;
+    verifyStealthAddress(stealthAddress: string, ephemeralPublicKey: string, spendingPublicKey: string): Promise<boolean>;
+    /**
+     * Ensure system is initialized
+     */
+    private ensureInitialized;
+    /**
+     * Derive stealth keys deterministically from SHIP-00 identity
+     *
+     * Uses simple deterministic derivation instead of Fluidkey's generateKeysFromSignature
+     * because it requires specific EIP-712 signature format.
+     *
+     * We use Fluidkey only for:
+     * - generateStealthAddresses (address generation)
+     * - generateStealthPrivateKey (opening addresses)
+     */
+    private deriveStealthKeysFromIdentity;
+    /**
+     * Publish public stealth keys to Gun for others to use (PUBLIC METHOD)
+     */
+    publishStealthKeys(): Promise<void>;
+    /**
+     * Compute view tag for quick scanning
+     */
+    private computeViewTag;
+    /**
+     * Fallback method to open stealth address (manual ECDH computation)
+     * Used when Fluidkey is not available or fails
+     */
+    private openStealthAddressFallback;
+    /**
+     * Add two private keys using modular arithmetic (secp256k1)
+     */
+    private addPrivateKeys;
+}
+export { SHIP_03 };