shogun-core 3.3.1 → 3.3.2

package/dist/ship/interfaces/ISHIP_07.js

@@ -0,0 +1,194 @@
+"use strict";
+/**
+ * SHIP-07: Secure Vault Interface
+ *
+ * @title ISHIP_07 - Secure Encrypted Vault
+ * @notice Interface for secure encrypted key-value storage on GunDB
+ * @dev This interface depends on ISHIP_00 for identity and encryption
+ *
+ * ## Abstract
+ *
+ * This standard defines an interface for secure vault storage that allows:
+ * - End-to-end encrypted key-value storage
+ * - Soft delete with recovery
+ * - Export/import for backup
+ * - Rich metadata support
+ * - Simple, secure, focused on storage only
+ *
+ * ## Dependencies
+ *
+ * - ISHIP_00: Identity and authentication layer
+ * - GunDB: P2P storage
+ * - SEA: Cryptography (AES-256-GCM)
+ *
+ * ## Inspiration
+ *
+ * Based on Gunsafe (https://github.com/draeder/gunsafe)
+ * Adapted for Shogun ecosystem with SHIP-00 integration
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+// ============================================================================
+// IMPLEMENTATION EXAMPLE
+// ============================================================================
+/**
+ * Example of how to implement ISHIP_07 with ISHIP_00 dependency
+ *
+ * ```typescript
+ * import { ISHIP_00 } from './ISHIP_00';
+ * import { ISHIP_07, VaultRecord, VaultResult } from './ISHIP_07';
+ *
+ * class SecureVault implements ISHIP_07 {
+ *     private vaultNode: any;
+ *     private initialized: boolean = false;
+ *
+ *     constructor(private identity: ISHIP_00) {
+ *         if (!identity.isLoggedIn()) {
+ *             throw new Error('User must be authenticated via SHIP-00');
+ *         }
+ *     }
+ *
+ *     getIdentity(): ISHIP_00 {
+ *         return this.identity;
+ *     }
+ *
+ *     async initialize(): Promise<void> {
+ *         // Get Gun user node
+ *         const gun = this.identity.shogun.db.gun;
+ *         this.vaultNode = gun.user().get('vault').get('records');
+ *
+ *         // Initialize vault metadata
+ *         await gun.user().get('vault').get('metadata').put({
+ *             version: '1.0.0',
+ *             created: Date.now().toString()
+ *         });
+ *
+ *         this.initialized = true;
+ *     }
+ *
+ *     isInitialized(): boolean {
+ *         return this.initialized;
+ *     }
+ *
+ *     async put(name: string, data: any, metadata?: RecordMetadata): Promise<VaultResult> {
+ *         if (!this.initialized) {
+ *             return { success: false, error: 'Vault not initialized' };
+ *         }
+ *
+ *         try {
+ *             // Get SEA crypto
+ *             const crypto = this.identity.shogun.db.crypto;
+ *             const pair = this.identity.getKeyPair();
+ *
+ *             if (!pair) {
+ *                 return { success: false, error: 'Cannot access key pair' };
+ *             }
+ *
+ *             // Encrypt data
+ *             const encryptedData = await crypto.encrypt(
+ *                 JSON.stringify(data),
+ *                 pair.epriv
+ *             );
+ *
+ *             // Encrypt metadata if provided
+ *             const encryptedMetadata = metadata
+ *                 ? await crypto.encrypt(JSON.stringify(metadata), pair.epriv)
+ *                 : undefined;
+ *
+ *             // Store in vault
+ *             const record = {
+ *                 data: encryptedData,
+ *                 created: Date.now().toString(),
+ *                 updated: Date.now().toString(),
+ *                 deleted: false,
+ *                 metadata: encryptedMetadata
+ *             };
+ *
+ *             await this.vaultNode.get(name).put(record);
+ *
+ *             return { success: true, recordName: name };
+ *         } catch (error: any) {
+ *             return { success: false, error: error.message };
+ *         }
+ *     }
+ *
+ *     async get(name: string, options?: GetOptions): Promise<VaultRecord | null> {
+ *         if (!this.initialized) {
+ *             return null;
+ *         }
+ *
+ *         try {
+ *             // Retrieve from vault
+ *             const encryptedRecord = await this.vaultNode.get(name).then();
+ *
+ *             if (!encryptedRecord || !encryptedRecord.data) {
+ *                 return null;
+ *             }
+ *
+ *             // Skip if deleted (unless includeDeleted)
+ *             if (encryptedRecord.deleted && !options?.includeDeleted) {
+ *                 return null;
+ *             }
+ *
+ *             // Decrypt data
+ *             const crypto = this.identity.shogun.db.crypto;
+ *             const pair = this.identity.getKeyPair();
+ *
+ *             if (!pair) {
+ *                 return null;
+ *             }
+ *
+ *             const decryptedData = await crypto.decrypt(
+ *                 encryptedRecord.data,
+ *                 pair.epriv
+ *             );
+ *
+ *             // Decrypt metadata if present
+ *             const decryptedMetadata = encryptedRecord.metadata
+ *                 ? JSON.parse(await crypto.decrypt(encryptedRecord.metadata, pair.epriv))
+ *                 : undefined;
+ *
+ *             return {
+ *                 name,
+ *                 data: JSON.parse(decryptedData),
+ *                 created: parseInt(encryptedRecord.created),
+ *                 updated: parseInt(encryptedRecord.updated),
+ *                 deleted: encryptedRecord.deleted,
+ *                 metadata: decryptedMetadata
+ *             };
+ *         } catch (error) {
+ *             console.error('Error retrieving record:', error);
+ *             return null;
+ *         }
+ *     }
+ *
+ *     async delete(name?: string): Promise<VaultResult> {
+ *         // Implementation here
+ *         return { success: true };
+ *     }
+ *
+ *     async list(options?: ListOptions): Promise<string[]> {
+ *         // Implementation here
+ *         return [];
+ *     }
+ *
+ *     // ... implement other methods
+ * }
+ *
+ * // Usage
+ * const identity = new SHIP_00(config);
+ * await identity.login('alice', 'password123');
+ *
+ * const vault = new SecureVault(identity);
+ * await vault.initialize();
+ *
+ * // Store encrypted data
+ * await vault.put('my-password', 'super_secret', {
+ *     type: 'password',
+ *     description: 'GitHub password'
+ * });
+ *
+ * // Retrieve decrypted data
+ * const record = await vault.get('my-password');
+ * console.log('Password:', record?.data);
+ * ```
+ */

package/dist/types/ship/examples/ephemeral-cli.d.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env tsx
+/**
+ * SHIP-06 Ephemeral Chat - STANDALONE
+ *
+ * NO login/password required!
+ *
+ * Usage:
+ *   tsx ship/examples/ephemeral-cli.ts <nickname> <room>
+ *
+ * Example:
+ *   tsx ship/examples/ephemeral-cli.ts alice test-room
+ */
+export {};

package/dist/types/ship/examples/identity-cli.d.ts

@@ -0,0 +1,40 @@
+#!/usr/bin/env tsx
+/**
+ * SHIP-00 Identity CLI Example
+ *
+ * Interactive CLI demonstrating SHIP-00 identity and authentication
+ *
+ * Usage:
+ *   yarn identity <username> <password>
+ *
+ * Features:
+ * - User signup and login
+ * - Login with keypair (multi-device)
+ * - Public key publication
+ * - User discovery and lookup
+ * - Key pair export/import
+ * - Ethereum address derivation
+ */
+declare class IdentityCLI {
+    private identity;
+    private rl;
+    private username;
+    private running;
+    constructor();
+    login(username: string, password: string): Promise<boolean>;
+    loginWithKeypair(): Promise<void>;
+    exportKeypair(): Promise<void>;
+    showCurrentUser(): Promise<void>;
+    showPublicKey(): Promise<void>;
+    lookupUser(): Promise<void>;
+    lookupByPublicKey(): Promise<void>;
+    showMenu(): Promise<void>;
+    deriveAddress(): Promise<void>;
+    publishPublicKey(): Promise<void>;
+    logout(): Promise<void>;
+    private printHeader;
+    prompt(question: string): Promise<string>;
+    cleanup(): void;
+    start(username?: string, password?: string): Promise<void>;
+}
+export { IdentityCLI };

package/dist/types/ship/examples/messenger-cli.d.ts

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+/**
+ * Shogun Chat - CLI Interface
+ *
+ * End-to-end encrypted decentralized chat
+ * Simple and functional CLI interface
+ */
+export declare class MessengerCLI {
+    private identity;
+    private messaging;
+    private rl;
+    private currentUser;
+    private recipient;
+    private derivedAddress;
+    private isAuthenticated;
+    private channelToken;
+    private currentChannel;
+    constructor();
+    private setupHandlers;
+    private withTimeout;
+    login(username: string, password: string): Promise<boolean>;
+    private sendMessage;
+    private onMessageReceived;
+    private onChannelMessageReceived;
+    private exportKeyPair;
+    private importKeyPair;
+    private loginWithPair;
+    private wipeAllMessages;
+    private handleCommand;
+    private joinChannel;
+    private leaveChannel;
+    private showHelp;
+    private showStatus;
+    private showHeader;
+    private updatePrompt;
+    start(): Promise<void>;
+}

package/dist/types/ship/examples/stealth-cli.d.ts

@@ -0,0 +1,31 @@
+#!/usr/bin/env tsx
+/**
+ * SHIP-03 Stealth Address CLI Example
+ *
+ * Demonstrates dual-key stealth addresses with Fluidkey integration
+ *
+ * Usage:
+ *   yarn stealth <username> <password>
+ */
+declare class StealthCLI {
+    private identity;
+    private eth;
+    private stealth;
+    private rl;
+    constructor();
+    login(username: string, password: string): Promise<boolean>;
+    register(username: string, password: string): Promise<boolean>;
+    showStealthKeys(): Promise<void>;
+    generateStealthAddress(): Promise<void>;
+    openStealthAddress(): Promise<void>;
+    batchGenerateStealthAddresses(): Promise<void>;
+    scanForStealthPayments(): Promise<void>;
+    showMenu(): Promise<void>;
+    lookupUserKeys(): Promise<void>;
+    exportKeys(): Promise<void>;
+    publishKeys(): Promise<void>;
+    showWalletInfo(): Promise<void>;
+    prompt(question: string): Promise<string>;
+    close(): void;
+}
+export { StealthCLI };

package/dist/types/ship/examples/storage-cli.d.ts

@@ -0,0 +1,48 @@
+#!/usr/bin/env tsx
+/**
+ * SHIP-05 Storage CLI Example
+ *
+ * Interactive CLI demonstrating SHIP-05 encrypted file storage on IPFS
+ *
+ * Usage:
+ *   yarn storage <username> <password>
+ *
+ * Features:
+ * - Encrypted file upload to IPFS (uses SEA from SHIP-00)
+ * - Multiple IPFS services (Pinata, IPFS Client, Custom Gateway)
+ * - File download and decryption
+ * - File metadata management
+ * - Storage statistics
+ */
+declare class StorageCLI {
+    private identity;
+    private storage;
+    private rl;
+    private username;
+    private running;
+    private ipfsService;
+    private ipfsConfig;
+    private configFile;
+    constructor();
+    login(username: string, password: string): Promise<boolean>;
+    configureIPFS(): Promise<void>;
+    configurePinata(): Promise<void>;
+    configureIPFSClient(): Promise<void>;
+    configureCustomGateway(): Promise<void>;
+    saveIPFSConfig(): void;
+    loadIPFSConfig(): boolean;
+    uploadFile(): Promise<void>;
+    downloadFile(): Promise<void>;
+    viewUserFiles(): Promise<void>;
+    deleteFile(): Promise<void>;
+    showStorageStats(): Promise<void>;
+    testEncryption(): Promise<void>;
+    showMenu(): Promise<void>;
+    reconfigureIPFS(): Promise<void>;
+    logout(): Promise<void>;
+    private printHeader;
+    prompt(question: string): Promise<string>;
+    cleanup(): void;
+    start(username?: string, password?: string): Promise<void>;
+}
+export { StorageCLI };

package/dist/types/ship/examples/vault-cli.d.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env tsx
+/**
+ * SHIP-07 Secure Vault CLI Example
+ *
+ * Test secure encrypted vault with SHIP-07
+ *
+ * Usage:
+ *   tsx ship/examples/vault-cli.ts <username> <password>
+ *
+ * Example:
+ *   tsx ship/examples/vault-cli.ts alice pass123
+ */
+export {};

package/dist/types/ship/examples/wallet-cli.d.ts

@@ -0,0 +1,131 @@
+/**
+ * SHIP-02 Example: Ethereum Wallet CLI
+ *
+ * Interactive CLI demonstrating SHIP-02 HD wallet derivation
+ * Built on top of SHIP-00 identity
+ *
+ * Usage:
+ *   yarn wallet <username> <password>
+ *
+ * Features:
+ * - Derive Ethereum addresses from identity (no mnemonics!)
+ * - BIP-44 HD wallet support
+ * - Sign transactions and messages
+ * - Export/import address book
+ * - Gun persistence
+ *
+ * Note: For stealth addresses, use `yarn stealth` (SHIP-03)
+ */
+declare class WalletCLI {
+    private identity;
+    private wallet;
+    private rl;
+    private username;
+    private running;
+    constructor(username: string, password: string);
+    /**
+     * Start the CLI
+     */
+    start(password: string): Promise<void>;
+    /**
+     * Authenticate user with SHIP-00
+     */
+    private authenticate;
+    /**
+     * Initialize SHIP-02 wallet
+     */
+    private initializeWallet;
+    /**
+     * Main menu loop
+     */
+    private mainMenu;
+    /**
+     * View all addresses
+     */
+    private viewAddresses;
+    /**
+     * Derive new address with custom index
+     */
+    private deriveNewAddress;
+    /**
+     * Derive BIP-44 address with custom parameters
+     */
+    private deriveBIP44Address;
+    /**
+     * Derive multiple addresses at once
+     */
+    private deriveMultipleAddresses;
+    /**
+     * Import address book
+     */
+    private importAddressBook;
+    /**
+     * Export encrypted wallet data
+     */
+    private exportWalletData;
+    /**
+     * Sync with Gun database
+     */
+    private syncWithGun;
+    /**
+     * View/Export mnemonic
+     */
+    private viewExportMnemonic;
+    /**
+     * Verify addresses match MetaMask
+     */
+    private verifyMetaMaskAddresses;
+    /**
+     * Sign message
+     */
+    private signMessage;
+    /**
+     * Sign transaction
+     */
+    private signTransaction;
+    /**
+     * Export address book
+     */
+    private exportAddressBook;
+    /**
+     * View master public key
+     */
+    private viewMasterPublicKey;
+    /**
+     * Create wallet using frontend API
+     */
+    private createWalletFrontendAPI;
+    /**
+     * Load all wallets using frontend API
+     */
+    private loadAllWallets;
+    /**
+     * View main wallet (derived from Gun keys)
+     */
+    private viewMainWallet;
+    /**
+     * Export all user data (complete backup)
+     */
+    private exportAllUserData;
+    /**
+     * Set RPC provider URL
+     */
+    private setRpcProvider;
+    /**
+     * Send transaction via RPC
+     */
+    private sendTransactionRPC;
+    /**
+     * Print header
+     */
+    private printHeader;
+    /**
+     * Prompt user for input
+     */
+    private prompt;
+    /**
+     * Cleanup and exit
+     */
+    private cleanup;
+}
+export { WalletCLI };

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

@@ -0,0 +1,113 @@
+/**
+ * SHIP-00: Decentralized Identity & Authentication Implementation
+ *
+ * Foundation layer for the Shogun ecosystem.
+ * Provides identity and authentication services for all other SHIPs.
+ *
+ * Based on:
+ * - Shogun Core API (see ../API.md)
+ * - GunDB for P2P identity storage
+ * - SEA for cryptographic operations
+ * - shogun-derive for address derivation
+ *
+ * Features:
+ * ✅ Username/password authentication
+ * ✅ SEA key pair management
+ * ✅ Public key publication and discovery
+ * ✅ User registry and lookup
+ * ✅ Blockchain address derivation
+ * ✅ Multi-device support (export/import)
+ */
+import type { ISHIP_00, SignupResult, AuthResult, OperationResult, SEAPair, UserIdentity, UserData, PublicKeyData } from "../interfaces/ISHIP_00";
+import { ShogunCoreConfig } from "../../src/interfaces/shogun";
+/**
+ * SHIP-00 Reference Implementation
+ *
+ * Uses Shogun Core as the underlying implementation.
+ * This class wraps Shogun Core APIs to provide the ISHIP_00 standard interface.
+ */
+declare class SHIP_00 implements ISHIP_00 {
+    private shogun;
+    static readonly NODES: {
+        readonly USERS: "users";
+        readonly PUBLIC_KEYS: "publicKeys";
+        readonly REGISTRY: "registry";
+    };
+    constructor(shogunConfig: ShogunCoreConfig);
+    /**
+     * Register new user
+     * Uses Shogun Core signUp method (see API.md)
+     */
+    signup(username: string, password: string): Promise<SignupResult>;
+    /**
+     * Login with username and password
+     * Uses Shogun Core login method (see API.md)
+     */
+    login(username: string, password: string): Promise<AuthResult>;
+    /**
+     * Login with SEA Key Pair
+     * Uses Shogun Core loginWithPair method (see API.md)
+     */
+    loginWithPair(seaPair: SEAPair): Promise<AuthResult>;
+    /**
+     * Logout
+     * Uses Shogun Core logout method (see API.md line 325)
+     */
+    logout(): void;
+    /**
+     * Check if user is logged in
+     * Uses Shogun Core isLoggedIn method (see API.md line 326)
+     */
+    isLoggedIn(): boolean;
+    /**
+     * Get underlying ShogunCore instance
+     * Provides access to Gun, SEA, and crypto utilities
+     */
+    getShogun(): any;
+    /**
+     * Publish public key on GunDB
+     * Makes user's public key discoverable by others
+     */
+    publishPublicKey(): Promise<OperationResult>;
+    /**
+     * Export current user's SEA key pair
+     * For backup and multi-device usage
+     * Uses Shogun Core exportPair method (see API.md line 354)
+     */
+    exportKeyPair(): SEAPair | null;
+    /**
+     * Get current user's key pair
+     * Alias for exportKeyPair()
+     */
+    getKeyPair(): SEAPair | null;
+    /**
+     * Get user information by username
+     * Uses Shogun Core getUserByAlias method (see API.md line 1141-1148)
+     */
+    getUserByAlias(username: string): Promise<UserData | null>;
+    /**
+     * Get user information by public key
+     * Uses Shogun Core getUserDataByPub method (see API.md line 1150-1152)
+     */
+    getUserByPub(userPub: string): Promise<UserData | null>;
+    /**
+     * Check if user exists
+     * Uses SimpleGunAPI userExists method (see API.md line 188)
+     */
+    userExists(username: string): Promise<boolean>;
+    /**
+     * Get public key by username
+     */
+    getPublicKey(username: string): Promise<PublicKeyData | null>;
+    /**
+     * Get current authenticated user info
+     * Uses Shogun Core getCurrentUser method (see API.md line 429)
+     */
+    getCurrentUser(): UserIdentity | null;
+    /**
+     * Derive Ethereum address from SEA keypair
+     * Uses shogun-derive package for deterministic derivation
+     */
+    deriveEthereumAddress(publicKey?: string): Promise<string>;
+}
+export { SHIP_00 };

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

@@ -0,0 +1,80 @@
+/**
+ * SHIP-01: Decentralized Encrypted Messaging Implementation
+ *
+ * Messaggistica decentralizzata E2E che dipende da SHIP-00 per l'identità.
+ *
+ * Dipendenze:
+ * - SHIP-00 (Identity & Authentication) - per gestione utenti e chiavi
+ * - GunDB - per storage decentralizzato P2P
+ * - SEA - per crittografia ECDH + AES-GCM
+ *
+ * Vantaggi dell'architettura modulare:
+ * ✅ Separazione delle responsabilità (Identity vs Messaging)
+ * ✅ Riusabilità di SHIP-00 in altre applicazioni
+ * ✅ Testing più semplice e isolato
+ * ✅ Manutenibilità migliorata
+ */
+import type { ISHIP_00 } from "../interfaces/ISHIP_00";
+import type { ISHIP_01, SendMessageResult, DecryptedMessage, MessageHistoryEntry } from "../interfaces/ISHIP_01";
+/**
+ * SHIP-01 Reference Implementation
+ *
+ * Questa implementazione dipende da ISHIP_00 per tutte le operazioni di identità.
+ * Si concentra esclusivamente sulla logica di messaggistica.
+ */
+declare class SHIP_01 implements ISHIP_01 {
+    private identity;
+    static readonly NODES: {
+        readonly MESSAGES: "messages";
+        readonly TOKEN_MESSAGES: "token_messages";
+    };
+    /**
+     * Constructor
+     * @param identity ISHIP_00 instance for identity operations
+     */
+    constructor(identity: ISHIP_00);
+    /**
+     * Get identity provider
+     */
+    getIdentity(): ISHIP_00;
+    /**
+     * Send encrypted message to a user
+     * Uses identity provider (SHIP-00) to get keys
+     */
+    sendMessage(recipientUsername: string, message: string): Promise<SendMessageResult>;
+    /**
+     * Listen for incoming encrypted messages
+     * Uses identity provider (SHIP-00) to decrypt messages
+     */
+    listenForMessages(onMessage: (message: DecryptedMessage) => void): Promise<void>;
+    /**
+     * Get message history with a user
+     * Uses identity provider (SHIP-00) to decrypt messages
+     */
+    getMessageHistory(withUsername: string): Promise<MessageHistoryEntry[]>;
+    /**
+     * Decrypt a message using ECDH
+     * Uses identity provider (SHIP-00) to get keys
+     */
+    private decryptMessage;
+    /**
+     * Get public key by pub key
+     * Uses identity provider internally
+     */
+    private getPublicKeyByPub;
+    /**
+     * Generate unique message ID
+     */
+    private generateMessageId;
+    /**
+     * Send message encrypted with shared token/password
+     * Useful for group chats, channels, broadcast messages
+     */
+    sendMessageWithToken(token: string, message: string, channel?: string): Promise<SendMessageResult>;
+    /**
+     * Listen for token-encrypted messages
+     * Automatically decrypts with provided token
+     */
+    listenForTokenMessages(token: string, onMessage: (message: any) => void, channel?: string): Promise<void>;
+}
+export { SHIP_01 };