shogun-core 3.3.1 → 3.3.2

package/dist/ship/interfaces/ISHIP_00.js

@@ -0,0 +1,135 @@
+"use strict";
+/**
+ * SHIP-00: Decentralized Identity & Authentication Interface
+ *
+ * @title ISHIP_00 - Identity Foundation
+ * @notice Base interface for decentralized identity in Shogun ecosystem
+ *
+ * ## Abstract
+ *
+ * This standard defines the foundational interface for identity that enables:
+ * - Username/password authentication with deterministic key generation
+ * - SEA key pair management (export, import, backup)
+ * - Public key publication and discovery on GunDB
+ * - User registry and lookup system
+ * - Blockchain address derivation (Ethereum, Bitcoin, etc.)
+ *
+ * ## Specification
+ *
+ * Based on:
+ * - GunDB for P2P identity storage
+ * - SEA (Security, Encryption, Authorization) for key management
+ * - Shogun Core DataBase API for authentication
+ * - BIP32-like derivation for blockchain addresses
+ *
+ * ## Usage
+ *
+ * SHIP-00 serves as the foundation for all other SHIPs:
+ * - SHIP-01 (Messaging) depends on SHIP-00 for identity
+ * - SHIP-02 (Address Derivation) extends SHIP-00
+ * - SHIP-03 (Multi-Modal Auth) extends SHIP-00
+ * - SHIP-04 (File Storage) uses SHIP-00 for ACL
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+// ============================================================================
+// IMPLEMENTATION EXAMPLE
+// ============================================================================
+/**
+ * Example of how to implement ISHIP_00
+ *
+ * ```typescript
+ * import { ShogunCore } from 'shogun-core';
+ * import { ISHIP_00, SEAPair, AuthResult, SignupResult } from './interfaces/ISHIP_00';
+ *
+ * class IdentityManager implements ISHIP_00 {
+ *     private shogun: ShogunCore;
+ *
+ *     constructor(config: IdentityConfig) {
+ *         this.shogun = new ShogunCore({
+ *             gunOptions: {
+ *                 peers: config.peers,
+ *                 radisk: config.radisk,
+ *                 localStorage: config.localStorage
+ *             },
+ *             scope: config.scope
+ *         });
+ *     }
+ *
+ *     async signup(username: string, password: string): Promise<SignupResult> {
+ *         // Use Shogun Core signUp method
+ *         const result = await this.shogun.signUp(username, password);
+ *
+ *         if (result.success) {
+ *             // Publish public key
+ *             await this.publishPublicKey();
+ *
+ *             // Derive Ethereum address
+ *             const derivedAddress = await this.deriveEthereumAddress(result.userPub);
+ *
+ *             return {
+ *                 success: true,
+ *                 userPub: result.userPub,
+ *                 username: username,
+ *                 derivedAddress: derivedAddress
+ *             };
+ *         }
+ *
+ *         return {
+ *             success: false,
+ *             error: result.error || 'Signup failed'
+ *         };
+ *     }
+ *
+ *     async login(username: string, password: string): Promise<AuthResult> {
+ *         // Use Shogun Core login method
+ *         const result = await this.shogun.login(username, password);
+ *
+ *         if (result.success) {
+ *             const derivedAddress = await this.deriveEthereumAddress(result.userPub);
+ *
+ *             return {
+ *                 success: true,
+ *                 userPub: result.userPub,
+ *                 username: username,
+ *                 derivedAddress: derivedAddress
+ *             };
+ *         }
+ *
+ *         return {
+ *             success: false,
+ *             error: result.error || 'Login failed'
+ *         };
+ *     }
+ *
+ *     exportKeyPair(): SEAPair | null {
+ *         if (!this.isLoggedIn()) return null;
+ *
+ *         const seaPair = (this.shogun.db.gun.user() as any)?._?.sea;
+ *         if (!seaPair) return null;
+ *
+ *         return {
+ *             pub: seaPair.pub,
+ *             priv: seaPair.priv,
+ *             epub: seaPair.epub,
+ *             epriv: seaPair.epriv
+ *         };
+ *     }
+ *
+ *     async getUserByAlias(username: string): Promise<UserData | null> {
+ *         // Use Shogun Core getUserByAlias method
+ *         return await this.shogun.db.getUserByAlias(username);
+ *     }
+ *
+ *     async deriveEthereumAddress(publicKey?: string): Promise<string> {
+ *         // Use shogun-derive package
+ *         const derived = await derive(seaPair.priv, null, {
+ *             includeSecp256k1Ethereum: true
+ *         });
+ *
+ *         return derived.secp256k1Ethereum.address;
+ *     }
+ *
+ *     // ... implement other methods
+ * }
+ * ```
+ */

package/dist/ship/interfaces/ISHIP_01.js

@@ -0,0 +1,128 @@
+"use strict";
+/**
+ * Shogun Messaging Protocol Interface
+ *
+ * @title ISHIP_01 - Decentralized Encrypted Messaging
+ * @notice Interface for decentralized encrypted messaging on GunDB
+ * @dev This interface depends on ISHIP_00 for identity and authentication
+ *
+ * ## Abstract
+ *
+ * This standard defines an interface for decentralized messaging that allows:
+ * - End-to-end encrypted message sending (ECDH)
+ * - Real-time message reception
+ * - Decentralized message history
+ *
+ * ## Dependencies
+ *
+ * - ISHIP_00: Identity and authentication layer
+ * - GunDB: P2P storage
+ * - SEA: Cryptography (ECDH + AES-GCM)
+ *
+ * ## Specification
+ *
+ * Based on:
+ * - SHIP-00 for identity management
+ * - GunDB for P2P storage
+ * - SEA (Security, Encryption, Authorization) for cryptography
+ * - ECDH (Elliptic Curve Diffie-Hellman) for key agreement
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+// ============================================================================
+// IMPLEMENTATION EXAMPLE
+// ============================================================================
+/**
+ * Example of how to implement ISHIP_01 with ISHIP_00 dependency
+ *
+ * ```typescript
+ * import { ISHIP_00 } from './ISHIP_00';
+ * import { ISHIP_01, DecryptedMessage, SendMessageResult } from './ISHIP_01';
+ *
+ * class SecureMessagingApp implements ISHIP_01 {
+ *     constructor(private identity: ISHIP_00) {
+ *         // Verify identity is authenticated
+ *         if (!identity.isLoggedIn()) {
+ *             throw new Error('User must be authenticated');
+ *         }
+ *     }
+ *
+ *     getIdentity(): ISHIP_00 {
+ *         return this.identity;
+ *     }
+ *
+ *     async sendMessage(recipientUsername: string, message: string): Promise<SendMessageResult> {
+ *         // 1. Get recipient's public key from identity provider
+ *         const recipientKey = await this.identity.getPublicKey(recipientUsername);
+ *         if (!recipientKey) {
+ *             return { success: false, error: 'Recipient not found' };
+ *         }
+ *
+ *         // 2. Get sender's key pair from identity provider
+ *         const senderPair = this.identity.getKeyPair();
+ *         if (!senderPair) {
+ *             return { success: false, error: 'Not authenticated' };
+ *         }
+ *
+ *         // 3. Encrypt with ECDH
+ *         const encrypted = await crypto.encFor(
+ *             message,
+ *             senderPair,
+ *             { epub: recipientKey.epub }
+ *         );
+ *
+ *         // 4. Save to GunDB
+ *         const messageId = generateId();
+ *         await gun.get('messages').get(messageId).put({
+ *             content: encrypted,
+ *             from: senderPair.pub,
+ *             to: recipientUsername,
+ *             timestamp: Date.now().toString()
+ *         });
+ *
+ *         return { success: true, messageId };
+ *     }
+ *
+ *     async listenForMessages(onMessage: (message: DecryptedMessage) => void): Promise<void> {
+ *         const currentUser = this.identity.getCurrentUser();
+ *         if (!currentUser) {
+ *             throw new Error('Not authenticated');
+ *         }
+ *
+ *         gun.get('messages').map().on(async (data, key) => {
+ *             if (data && data.to === currentUser.alias) {
+ *                 // Decrypt message
+ *                 const senderKey = await this.identity.getPublicKey(data.from);
+ *                 const receiverPair = this.identity.getKeyPair();
+ *
+ *                 if (senderKey && receiverPair) {
+ *                     const decrypted = await crypto.decFrom(
+ *                         data.content,
+ *                         { epub: senderKey.epub },
+ *                         receiverPair
+ *                     );
+ *
+ *                     onMessage({
+ *                         from: data.from,
+ *                         content: decrypted,
+ *                         timestamp: parseInt(data.timestamp)
+ *                     });
+ *                 }
+ *             }
+ *         });
+ *     }
+ *
+ *     async getMessageHistory(withUsername: string): Promise<MessageHistoryEntry[]> {
+ *         // Implementation here
+ *         return [];
+ *     }
+ * }
+ *
+ * // Usage
+ * const identity = new SHIP_00(config);
+ * await identity.login('alice', 'password123');
+ * await identity.publishPublicKey();
+ *
+ * const messaging = new SecureMessagingApp(identity);
+ * await messaging.sendMessage('bob', 'Hello Bob!');
+ * ```
+ */

package/dist/ship/interfaces/ISHIP_02.js

@@ -0,0 +1,57 @@
+"use strict";
+/**
+ * SHIP-02: Ethereum Address Derivation Interface
+ *
+ * @title ISHIP_02 - Deterministic Address Derivation
+ * @notice Interface for deriving Ethereum addresses from SHIP-00 identity
+ *
+ * ## Abstract
+ *
+ * This standard extends SHIP-00 to enable:
+ * - Deterministic Ethereum address derivation from identity keys
+ * - BIP-32/BIP-44 hierarchical deterministic (HD) wallet support
+ * - Stealth address generation for enhanced privacy
+ * - Multiple address management from single identity
+ * - Transaction signing with derived keys
+ *
+ * ## Specification
+ *
+ * Based on:
+ * - SHIP-00 for identity foundation
+ * - BIP-32 for hierarchical deterministic wallets
+ * - BIP-44 for multi-account hierarchy
+ * - Ethers.js for Ethereum operations
+ * - ECDH for stealth address generation
+ *
+ * ## Dependencies
+ *
+ * - SHIP-00: Identity and authentication foundation
+ * - ethers: Ethereum wallet and signing operations
+ *
+ * ## Usage
+ *
+ * SHIP-02 enables wallet functionality on top of SHIP-00 identity:
+ * ```typescript
+ * const identity = new SHIP_00({ gunOptions: { peers: ['...'] } });
+ * await identity.login('alice', 'password123');
+ *
+ * const addressDerivation = new SHIP_02(identity);
+ * await addressDerivation.initialize();
+ *
+ * const ethAddress = await addressDerivation.deriveEthereumAddress();
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SHIP_02_EventType = void 0;
+/**
+ * @notice Event types for SHIP-02 wallet operations
+ */
+var SHIP_02_EventType;
+(function (SHIP_02_EventType) {
+    SHIP_02_EventType["WALLET_CREATED"] = "walletCreated";
+    SHIP_02_EventType["ADDRESS_DERIVED"] = "addressDerived";
+    SHIP_02_EventType["TRANSACTION_SIGNED"] = "transactionSigned";
+    SHIP_02_EventType["MNEMONIC_GENERATED"] = "mnemonicGenerated";
+    SHIP_02_EventType["SYNC_COMPLETED"] = "syncCompleted";
+    SHIP_02_EventType["ERROR"] = "error";
+})(SHIP_02_EventType || (exports.SHIP_02_EventType = SHIP_02_EventType = {}));

package/dist/ship/interfaces/ISHIP_03.js

@@ -0,0 +1,61 @@
+"use strict";
+/**
+ * SHIP-03: Dual-Key Stealth Address Interface
+ *
+ * @title ISHIP_03 - Privacy-Preserving Stealth Addresses
+ * @notice Interface for ERC-5564 compatible stealth addresses
+ *
+ * ## Abstract
+ *
+ * This standard extends SHIP-00 and SHIP-02 to enable:
+ * - Dual-key stealth addresses (viewing + spending keys)
+ * - ERC-5564 / Fluidkey compatibility
+ * - Enhanced transaction privacy
+ * - Stealth address scanning and opening
+ * - Deterministic key derivation from SHIP-00 identity
+ *
+ * ## Specification
+ *
+ * Based on:
+ * - SHIP-00 for identity foundation
+ * - SHIP-02 for Ethereum address derivation
+ * - ERC-5564 for stealth address standard
+ * - Fluidkey Stealth Account Kit
+ * - ECDH for shared secret derivation
+ *
+ * ## Key Concepts
+ *
+ * **Viewing Key**: Used to scan blockchain for incoming stealth payments
+ * **Spending Key**: Used to spend funds received at stealth addresses
+ * **Ephemeral Key**: One-time key used by sender to generate stealth address
+ *
+ * ## Dependencies
+ *
+ * - SHIP-00: Identity and authentication foundation
+ * - SHIP-02: Ethereum wallet operations
+ * - @fluidkey/stealth-account-kit: ERC-5564 implementation
+ * - ethers: Ethereum operations
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * const identity = new SHIP_00({ gunOptions: { peers: ['...'] } });
+ * await identity.login('alice', 'password123');
+ *
+ * const eth = new SHIP_02(identity);
+ * await eth.initialize();
+ *
+ * const stealth = new SHIP_03(identity, eth);
+ * await stealth.initialize();
+ *
+ * // Get stealth keys (derived from SHIP-00 identity)
+ * const keys = await stealth.getStealthKeys();
+ *
+ * // Generate stealth address for recipient
+ * const stealthAddr = await stealth.generateStealthAddress(
+ *   recipientViewingKey,
+ *   recipientSpendingKey
+ * );
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/ship/interfaces/ISHIP_04.js

@@ -0,0 +1,62 @@
+"use strict";
+/**
+ * SHIP-04: Multi-Modal Authentication Interface
+ *
+ * @title ISHIP_04 - Alternative Authentication Methods
+ * @notice Interface for multi-modal authentication extending SHIP-00
+ *
+ * ## Abstract
+ *
+ * This standard extends SHIP-00 to provide multiple authentication methods:
+ * - OAuth (Google, GitHub, Discord, etc.)
+ * - WebAuthn/Passkeys (biometric authentication)
+ * - Nostr (decentralized social protocol)
+ * - Web3 (MetaMask, WalletConnect, etc.)
+ *
+ * ## Dependencies
+ *
+ * - SHIP-00: Base identity foundation
+ * - Shogun Core Plugins: OAuth, WebAuthn, Nostr, Web3
+ *
+ * ## Inclusive Hierarchy
+ *
+ * SHIP-04 extends SHIP-00 (✅ allowed):
+ * ```
+ * SHIP-04 (Multi-Modal Auth)
+ *    ↓ depends on
+ * SHIP-00 (Identity Foundation)
+ * ```
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * const identity = new SHIP_00(config);
+ * const multiAuth = new SHIP_04(identity);
+ *
+ * // Login with OAuth
+ * await multiAuth.loginWithOAuth('google');
+ *
+ * // Or WebAuthn
+ * await multiAuth.loginWithWebAuthn('alice');
+ *
+ * // Result is SHIP-00 compatible!
+ * const user = identity.getCurrentUser();
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuthMethod = void 0;
+// ============================================================================
+// CORE TYPES
+// ============================================================================
+/**
+ * Available authentication methods
+ * Exported as const enum to allow usage as both type and value
+ */
+var AuthMethod;
+(function (AuthMethod) {
+    AuthMethod["PASSWORD"] = "password";
+    AuthMethod["OAUTH"] = "oauth";
+    AuthMethod["WEBAUTHN"] = "webauthn";
+    AuthMethod["NOSTR"] = "nostr";
+    AuthMethod["WEB3"] = "web3";
+})(AuthMethod || (exports.AuthMethod = AuthMethod = {}));

package/dist/ship/interfaces/ISHIP_05.js

@@ -0,0 +1,59 @@
+"use strict";
+/**
+ * SHIP-05: Decentralized File Storage Interface
+ *
+ * @title ISHIP_05 - IPFS Storage with Relay Network
+ * @notice Interface for decentralized file storage with encryption
+ *
+ * ## Abstract
+ *
+ * This standard extends SHIP-00 to enable:
+ * - Encrypted file storage on IPFS
+ * - Relay network management for storage providers
+ * - On-chain subscription system for storage
+ * - Deterministic encryption from wallet signatures
+ * - File sharing with access control
+ *
+ * ## Specification
+ *
+ * Based on:
+ * - SHIP-00 for identity foundation
+ * - IPFS for decentralized storage
+ * - Smart contracts for relay payment system
+ * - Deterministic encryption from wallet signatures
+ *
+ * ## Dependencies
+ *
+ * - SHIP-00: Identity and authentication foundation
+ * - IPFS: Decentralized file storage
+ * - Ethereum: For relay subscription payments
+ * - shogun-ipfs: IPFS wrapper library
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * const identity = new SHIP_00({ gunOptions: { peers: ['...'] } });
+ * await identity.login('alice', 'password123');
+ *
+ * const storage = new SHIP_05(identity);
+ * await storage.initialize();
+ *
+ * // Upload encrypted file
+ * const result = await storage.uploadFile(file, { encrypt: true });
+ *
+ * // Download and decrypt
+ * const data = await storage.downloadFile(result.hash, { decrypt: true });
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SHIP_05_EventType = void 0;
+// ============================================================================
+// EVENTS
+// ============================================================================
+var SHIP_05_EventType;
+(function (SHIP_05_EventType) {
+    SHIP_05_EventType["FILE_UPLOADED"] = "fileUploaded";
+    SHIP_05_EventType["FILE_DOWNLOADED"] = "fileDownloaded";
+    SHIP_05_EventType["FILE_DELETED"] = "fileDeleted";
+    SHIP_05_EventType["ERROR"] = "error";
+})(SHIP_05_EventType || (exports.SHIP_05_EventType = SHIP_05_EventType = {}));

package/dist/ship/interfaces/ISHIP_06.js

@@ -0,0 +1,144 @@
+"use strict";
+/**
+ * SHIP-06: Ephemeral P2P Messaging Interface
+ *
+ * @title ISHIP_06 - Ephemeral P2P Messaging
+ * @notice Interface for ephemeral peer-to-peer messaging via Gun Relay
+ * @dev Can work standalone OR with ISHIP_00 for authenticated sessions
+ *
+ * ## Abstract
+ *
+ * This standard defines an interface for ephemeral P2P messaging that allows:
+ * - Relay-based connections via Gun network
+ * - End-to-end encrypted messages (no storage)
+ * - Broadcast and direct messaging
+ * - Deterministic room discovery (SHA-256)
+ * - Standalone mode (no authentication needed!)
+ *
+ * ## Dependencies
+ *
+ * - Gun: Relay-based P2P database
+ * - Gun SEA: Cryptography (ECDH + AES-GCM)
+ * - ISHIP_00 (OPTIONAL): For authenticated sessions
+ *
+ * ## Modes
+ *
+ * **Standalone**: new SHIP_06(gunPeers[], roomId)
+ * **With Identity**: new SHIP_06(ISHIP_00, roomId)
+ *
+ * ## Inspiration
+ *
+ * Based on Bugoff (https://github.com/draeder/bugoff)
+ * Simplified for Gun relay instead of WebRTC
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+// ============================================================================
+// IMPLEMENTATION EXAMPLE
+// ============================================================================
+/**
+ * Example of how to implement ISHIP_06 with ISHIP_00 dependency
+ *
+ * ```typescript
+ * import { ISHIP_00 } from './ISHIP_00';
+ * import { ISHIP_06, EphemeralMessage } from './ISHIP_06';
+ * import Bugout from 'bugout';
+ *
+ * class EphemeralMessaging implements ISHIP_06 {
+ *     private bugout: any;
+ *     private ephemeralPair: SEAPair | null = null;
+ *     private peers: Map<string, PeerInfo> = new Map();
+ *     private messageCallbacks: ((msg: EphemeralMessage) => void)[] = [];
+ *
+ *     constructor(
+ *         private identity: ISHIP_00,
+ *         private roomId: string,
+ *         private config?: EphemeralConfig
+ *     ) {
+ *         if (!identity.isLoggedIn()) {
+ *             throw new Error('User must be authenticated via SHIP-00');
+ *         }
+ *     }
+ *
+ *     getIdentity(): ISHIP_00 {
+ *         return this.identity;
+ *     }
+ *
+ *     async connect(): Promise<void> {
+ *         // 1. Generate ephemeral SEA pair
+ *         const crypto = this.identity.shogun.db.crypto;
+ *         this.ephemeralPair = await crypto.pair();
+ *
+ *         // 2. Hash room ID
+ *         const swarmId = await crypto.hashText(this.roomId);
+ *
+ *         // 3. Create Bugout swarm
+ *         this.bugout = new Bugout(swarmId, {
+ *             iceServers: this.config?.iceServers
+ *         });
+ *
+ *         // 4. Set SEA pair
+ *         await this.bugout.SEA(this.ephemeralPair);
+ *
+ *         // 5. Listen for events
+ *         this.bugout.on('seen', (address: string) => {
+ *             this.handlePeerSeen(address);
+ *         });
+ *
+ *         this.bugout.on('decrypted', (address: string, pubkeys: any, message: string) => {
+ *             this.handleMessage(address, pubkeys, message);
+ *         });
+ *     }
+ *
+ *     disconnect(): void {
+ *         if (this.bugout) {
+ *             this.bugout.destroy();
+ *         }
+ *     }
+ *
+ *     async sendBroadcast(message: string): Promise<void> {
+ *         if (!this.bugout) {
+ *             throw new Error('Not connected to swarm');
+ *         }
+ *
+ *         this.bugout.send(message);
+ *     }
+ *
+ *     async sendDirect(peerAddress: string, message: string): Promise<void> {
+ *         if (!this.bugout) {
+ *             throw new Error('Not connected to swarm');
+ *         }
+ *
+ *         this.bugout.send(peerAddress, message);
+ *     }
+ *
+ *     onMessage(callback: (message: EphemeralMessage) => void): void {
+ *         this.messageCallbacks.push(callback);
+ *     }
+ *
+ *     private handleMessage(address: string, pubkeys: any, content: string) {
+ *         const message: EphemeralMessage = {
+ *             from: address,
+ *             fromPubKey: pubkeys.pub,
+ *             content,
+ *             timestamp: Date.now(),
+ *             type: 'broadcast'
+ *         };
+ *
+ *         this.messageCallbacks.forEach(cb => cb(message));
+ *     }
+ * }
+ *
+ * // Usage
+ * const identity = new SHIP_00(config);
+ * await identity.login('alice', 'password123');
+ *
+ * const ephemeral = new EphemeralMessaging(identity, 'my-room');
+ * await ephemeral.connect();
+ *
+ * ephemeral.onMessage((msg) => {
+ *     console.log(`${msg.from}: ${msg.content}`);
+ * });
+ *
+ * await ephemeral.sendBroadcast('Hello everyone!');
+ * ```
+ */