shogun-core 3.1.0 → 3.2.0

package/dist/ship/interfaces/ISHIP_01.js

@@ -0,0 +1,71 @@
+"use strict";
+/**
+ * Shogun Messaging Protocol Interface
+ *
+ * @title ISHIP_01 - Decentralized Encrypted Messaging
+ * @notice Interface for decentralized encrypted messaging on GunDB
+ *
+ * ## Abstract
+ *
+ * This standard defines an interface for decentralized messaging that allows:
+ * - Username/password authentication
+ * - Public key publication on GunDB
+ * - End-to-end encrypted message sending (ECDH)
+ * - Real-time message reception
+ * - Decentralized message history
+ *
+ * ## Specification
+ *
+ * Based on:
+ * - 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
+ *
+ * ```typescript
+ * class SecureMessagingApp implements ISHIP_01 {
+ *     private shogun: ShogunCore;
+ *
+ *     constructor(config: MessagingConfig) {
+ *         this.shogun = new ShogunCore(config);
+ *     }
+ *
+ *     async signup(username: string, password: string): Promise<SignupResult> {
+ *         const result = await this.shogun.signUp(username, password);
+ *         return {
+ *             success: result.success,
+ *             userPub: result.pub,
+ *             derivedAddress: this.pubKeyToAddress(result.pub || "")
+ *         };
+ *     }
+ *
+ *     async sendMessage(recipientUsername: string, message: string): Promise<SendMessageResult> {
+ *         // 1. Get recipient's epub
+ *         const recipientKey = await this.getRecipientPublicKey(recipientUsername);
+ *
+ *         // 2. Encrypt with ECDH
+ *         const encrypted = await this.shogun.db.crypto.encFor(
+ *             message,
+ *             this.shogun.db.user.is, // sender
+ *             { epub: recipientKey.epub } // receiver
+ *         );
+ *
+ *         // 3. Save to GunDB
+ *         await this.shogun.db.user.get('messages/...').put({
+ *             content: encrypted,
+ *             from: this.shogun.db.user.is.pub,
+ *             to: recipientUsername,
+ *             timestamp: Date.now().toString()
+ *         });
+ *
+ *         return { success: true, messageId: '...' };
+ *     }
+ * }
+ * ```
+ */

package/dist/{gundb → src/gundb}/db.js

@@ -1085,8 +1085,8 @@ class DataBase {
                 username: username,
                 userPub: userPub,
                 epub: epub,
-                registeredAt: Date.now(),
-                lastSeen: Date.now(),
+                registeredAt: Date.now().toString(),
+                lastSeen: Date.now().toString(),
             };
             const ack = await this.node
                 .get("users")

package/dist/{index.js → src/index.js}

@@ -17,7 +17,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.autoQuickStart = exports.AutoQuickStart = exports.createSimpleAPI = exports.quickStart = exports.QuickStart = exports.SimpleGunAPI = exports.DataBase = exports.GunErrors = exports.derive = exports.crypto = exports.RxJS = exports.SEA = exports.ShogunCore = exports.Gun = void 0;
+exports.autoQuickStart = exports.AutoQuickStart = exports.createSimpleAPI = exports.quickStart = exports.QuickStart = exports.SimpleGunAPI = exports.DataBase = exports.GunErrors = exports.derive = exports.crypto = exports.RxJS = exports.SEA = exports.ShogunCore = exports.Gun = exports.MessengerCLI = exports.SHIP_01 = void 0;
 const core_1 = require("./core");
 Object.defineProperty(exports, "ShogunCore", { enumerable: true, get: function () { return core_1.ShogunCore; } });
 const db_1 = require("./gundb/db");
@@ -41,5 +41,10 @@ exports.Gun = db_3.default;
 __exportStar(require("./utils/errorHandler"), exports);
 __exportStar(require("./plugins"), exports);
 __exportStar(require("./interfaces/shogun"), exports);
-// Export simplified configuration
 __exportStar(require("./config/simplified-config"), exports);
+var SHIP_01_1 = require("../ship/implementation/SHIP_01");
+Object.defineProperty(exports, "SHIP_01", { enumerable: true, get: function () { return SHIP_01_1.SHIP_01; } });
+// Export MessengerCLI only in Node.js environment (not browser)
+// This prevents "readline is not a function" errors in browser builds
+var messenger_cli_1 = require("../ship/examples/messenger-cli");
+Object.defineProperty(exports, "MessengerCLI", { enumerable: true, get: function () { return messenger_cli_1.MessengerCLI; } });

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

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

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

@@ -0,0 +1,108 @@
+/**
+ * Esempio Pratico: Messaggistica Decentralizzata con Shogun Core
+ *
+ * Questo esempio mostra come creare un sistema di messaggistica sicuro usando:
+ * - Shogun Core per autenticazione (username/password)
+ * - GunDB per storage decentralizzato P2P
+ * - SEA (Security, Encryption, Authorization) per crittografia
+ *
+ * Vantaggi:
+ * ✅ Completamente decentralizzato (no server centrale)
+ * ✅ Zero costi (no blockchain, no gas fees)
+ * ✅ Real-time messaging
+ * ✅ Offline-first
+ * ✅ End-to-end encryption
+ *
+ * Note sull'ERC7627:
+ * L'EIP era un template concettuale. Questo esempio implementa
+ * solo la parte GunDB/Shogun Core senza interazione blockchain.
+ * La funzione deriveEthereumAddress() rimane come utility per derivare
+ * un address Ethereum dalla chiave GunDB se necessario in futuro.
+ */
+import type { ISHIP_01, SignupResult, AuthResult, SendMessageResult, DecryptedMessage, OperationResult } from "../interfaces/ISHIP_01";
+import { ShogunCoreConfig } from "../../src/interfaces/shogun";
+import { ISEAPair } from "../../src/types/shogun";
+/**
+ * Classe per messaggistica sicura con Shogun Core
+ * Implementa l'interfaccia ISHIP_01
+ * Usa solo GunDB per storage decentralizzato (no blockchain)
+ */
+declare class SHIP_01 implements ISHIP_01 {
+    private shogun;
+    constructor(shogunConfig: ShogunCoreConfig);
+    /**
+     * Registra un nuovo utente
+     */
+    signup(username: string, password: string): Promise<SignupResult>;
+    /**
+     * Login con username e password
+     */
+    login(username: string, password: string): Promise<AuthResult>;
+    /**
+     * Login con SEA Key Pair
+     *
+     * Autenticazione diretta usando un key pair esportato.
+     * Utile per:
+     * - Recupero account senza password
+     * - Portabilità tra dispositivi
+     * - Backup dell'identità
+     */
+    loginWithPair(seaPair: ISEAPair): Promise<AuthResult>;
+    /**
+     * Logout
+     */
+    logout(): void;
+    /**
+     * Verifica se l'utente è autenticato
+     */
+    isLoggedIn(): boolean;
+    /**
+     * Salva la chiave pubblica dell'utente su GunDB
+     * Questo permette ad altri di trovare la tua chiave per criptare messaggi
+     */
+    publishPublicKey(): Promise<OperationResult>;
+    /**
+     * Invia un messaggio crittografato a un altro utente
+     */
+    sendMessage(recipientUsername: string, message: string): Promise<SendMessageResult>;
+    /**
+     * Ottiene la chiave pubblica di un utente da GunDB
+     */
+    private getRecipientPublicKey;
+    /**
+     * Ascolta messaggi crittografati in arrivo su GunDB
+     */
+    listenForMessages(onMessage: (message: DecryptedMessage) => void): Promise<void>;
+    /**
+     * Decripta un messaggio usando SEA.secret + SEA.decrypt (ECDH)
+     */
+    private decryptMessage;
+    /**
+     * Ottiene la chiave pubblica di un utente dalla sua pub key
+     */
+    private getPublicKeyByPub;
+    /**
+     * Recupera lo storico dei messaggi crittografati con un utente
+     */
+    getMessageHistory(withUsername: string): Promise<Array<{
+        from: string;
+        to: string;
+        content: string;
+        timestamp: number;
+    }>>;
+    /**
+     * Converte la chiave pubblica di GunDB in address Ethereum
+     * Usa la chiave privata SEA come seed per derivazione deterministica
+     *
+     * Questo garantisce che:
+     * - Stesso SEA pair → stesso address Ethereum
+     * - Derivazione cryptografica sicura
+     * - Identità unificata tra GunDB e blockchain
+     */
+    deriveEthereumAddress(publicKey?: string): Promise<string>;
+    /**
+     * Genera ID messaggio univoco
+     */
+    private generateMessageId;
+}
+export { SHIP_01 };

package/dist/types/ship/interfaces/ISHIP_01.d.ts

@@ -0,0 +1,305 @@
+/**
+ * Shogun Messaging Protocol Interface
+ *
+ * @title ISHIP_01 - Decentralized Encrypted Messaging
+ * @notice Interface for decentralized encrypted messaging on GunDB
+ *
+ * ## Abstract
+ *
+ * This standard defines an interface for decentralized messaging that allows:
+ * - Username/password authentication
+ * - Public key publication on GunDB
+ * - End-to-end encrypted message sending (ECDH)
+ * - Real-time message reception
+ * - Decentralized message history
+ *
+ * ## Specification
+ *
+ * Based on:
+ * - GunDB for P2P storage
+ * - SEA (Security, Encryption, Authorization) for cryptography
+ * - ECDH (Elliptic Curve Diffie-Hellman) for key agreement
+ */
+/**
+ * @notice Authentication result
+ */
+export interface AuthResult {
+    success: boolean;
+    userPub?: string;
+    derivedAddress?: string;
+    error?: string;
+}
+/**
+ * @notice Signup result
+ */
+export interface SignupResult {
+    success: boolean;
+    userPub?: string;
+    derivedAddress?: string;
+    error?: string;
+}
+/**
+ * @notice Message structure
+ */
+export interface Message {
+    from: string;
+    to: string;
+    content: string;
+    timestamp: string;
+    messageId: string;
+}
+/**
+ * @notice Decrypted message structure (for UI)
+ */
+export interface DecryptedMessage {
+    from: string;
+    content: string;
+    timestamp: number;
+}
+/**
+ * @notice User public key
+ */
+export interface UserPublicKey {
+    pub: string;
+    epub: string;
+    algorithm: string;
+    timestamp: string;
+}
+/**
+ * @notice Operation result
+ */
+export interface OperationResult {
+    success: boolean;
+    error?: string;
+}
+/**
+ * @notice Send message result
+ */
+export interface SendMessageResult extends OperationResult {
+    messageId?: string;
+}
+/**
+ * @title ISHIP_01 - Decentralized Messaging
+ * @notice Main interface for the messaging system
+ */
+export interface ISHIP_01 {
+    /**
+     * @notice Register a new user
+     * @param username Desired username
+     * @param password Password
+     * @return Result with userPub and derivedAddress
+     */
+    signup(username: string, password: string): Promise<SignupResult>;
+    /**
+     * @notice Login with username and password
+     * @param username Username
+     * @param password Password
+     * @return Result with userPub and derivedAddress
+     */
+    login(username: string, password: string): Promise<AuthResult>;
+    /**
+     * @notice Logout current user
+     */
+    logout(): void;
+    /**
+     * @notice Check if user is authenticated
+     * @return True if authenticated
+     */
+    isLoggedIn(): boolean;
+    /**
+     * @notice Publish public key on GunDB
+     * @dev Allows others to find your key to encrypt messages
+     * @return Operation result
+     */
+    publishPublicKey(): Promise<OperationResult>;
+    /**
+     * @notice Send encrypted message
+     * @dev Uses ECDH to derive shared secret, then AES-GCM for encryption
+     * @param recipientUsername Recipient's username
+     * @param message Plain text message content
+     * @return Result with messageId
+     *
+     * Flow:
+     * 1. Retrieve recipient's epub from GunDB
+     * 2. SEA.secret(recipient.epub, sender.pair) → shared_secret
+     * 3. SEA.encrypt(message, shared_secret) → encrypted
+     * 4. Save encrypted on GunDB
+     */
+    sendMessage(recipientUsername: string, message: string): Promise<SendMessageResult>;
+    /**
+     * @notice Listen for incoming messages in real-time
+     * @dev Automatically decrypts received messages
+     * @param onMessage Callback called for each message
+     *
+     * Decryption flow:
+     * 1. Receive encrypted message from GunDB
+     * 2. Retrieve sender's epub
+     * 3. SEA.secret(sender.epub, receiver.pair) → shared_secret
+     * 4. SEA.decrypt(encrypted, shared_secret) → message
+     * 5. Call callback with decrypted message
+     */
+    listenForMessages(onMessage: (message: DecryptedMessage) => void): Promise<void>;
+    /**
+     * @notice Retrieve message history with a user
+     * @dev Decrypts all messages in history
+     * @param withUsername Username of the other user
+     * @return Array of decrypted messages sorted by timestamp
+     */
+    getMessageHistory(withUsername: string): Promise<Array<{
+        from: string;
+        to: string;
+        content: string;
+        timestamp: number;
+    }>>;
+}
+/**
+ * @notice Interface for GunDB → Ethereum identity conversion
+ */
+export interface IAddressDerivation {
+    /**
+     * @notice Convert GunDB public key to Ethereum address
+     * @param publicKey Public key in base64 format (GunDB)
+     * @return Ethereum address with checksum
+     *
+     * Process:
+     * 1. Decode from base64 (GunDB format)
+     * 2. Convert to bytes
+     * 3. keccak256(bytes)
+     * 4. Take last 20 bytes
+     * 5. Apply EIP-55 checksum
+     */
+    pubKeyToAddress(publicKey: string): string;
+}
+/**
+ * @notice Messaging system configuration
+ */
+export interface MessagingConfig {
+    /**
+     * @notice GunDB peers
+     */
+    peers: string[];
+    /**
+     * @notice Application scope
+     */
+    scope: string;
+    /**
+     * @notice Operation timeout (ms)
+     */
+    timeout?: number;
+    /**
+     * @notice Enable debug logging
+     */
+    debug?: boolean;
+}
+/**
+ * @notice Cryptographic functions provided by Shogun Core
+ * @dev Wrapper for GunDB SEA
+ */
+export interface ISEACrypto {
+    /**
+     * @notice Encrypt data for a recipient (ECDH)
+     * @param data Data to encrypt
+     * @param senderPair Sender's key pair
+     * @param receiverEpub Recipient's encryption public key
+     * @return Encrypted data
+     */
+    encFor(data: any, senderPair: {
+        pub: string;
+        priv: string;
+        epub: string;
+        epriv: string;
+    }, receiverEpub: {
+        epub: string;
+    }): Promise<string>;
+    /**
+     * @notice Decrypt data from a sender (ECDH)
+     * @param encryptedData Encrypted data
+     * @param senderEpub Sender's encryption public key
+     * @param receiverPair Recipient's key pair
+     * @return Decrypted data
+     */
+    decFrom(encryptedData: string, senderEpub: {
+        epub: string;
+    }, receiverPair: {
+        pub: string;
+        priv: string;
+        epub: string;
+        epriv: string;
+    }): Promise<any>;
+    /**
+     * @notice Derive shared secret between two parties (ECDH)
+     * @param epub Other party's encryption public key
+     * @param pair Own key pair
+     * @return Shared secret
+     */
+    secret(epub: string, pair: {
+        pub: string;
+        priv: string;
+        epub: string;
+        epriv: string;
+    }): Promise<string>;
+    /**
+     * @notice Encrypt with symmetric key
+     * @param data Data to encrypt
+     * @param key Symmetric key
+     * @return Encrypted data
+     */
+    encrypt(data: any, key: string): Promise<string>;
+    /**
+     * @notice Decrypt with symmetric key
+     * @param encryptedData Encrypted data
+     * @param key Symmetric key
+     * @return Decrypted data
+     */
+    decrypt(encryptedData: string, key: string): Promise<any>;
+    /**
+     * @notice Hash text with SHA-256
+     * @param text Text to hash
+     * @return Hash
+     */
+    hashText(text: string): Promise<string>;
+}
+/**
+ * Example of how to implement ISHIP_01
+ *
+ * ```typescript
+ * class SecureMessagingApp implements ISHIP_01 {
+ *     private shogun: ShogunCore;
+ *
+ *     constructor(config: MessagingConfig) {
+ *         this.shogun = new ShogunCore(config);
+ *     }
+ *
+ *     async signup(username: string, password: string): Promise<SignupResult> {
+ *         const result = await this.shogun.signUp(username, password);
+ *         return {
+ *             success: result.success,
+ *             userPub: result.pub,
+ *             derivedAddress: this.pubKeyToAddress(result.pub || "")
+ *         };
+ *     }
+ *
+ *     async sendMessage(recipientUsername: string, message: string): Promise<SendMessageResult> {
+ *         // 1. Get recipient's epub
+ *         const recipientKey = await this.getRecipientPublicKey(recipientUsername);
+ *
+ *         // 2. Encrypt with ECDH
+ *         const encrypted = await this.shogun.db.crypto.encFor(
+ *             message,
+ *             this.shogun.db.user.is, // sender
+ *             { epub: recipientKey.epub } // receiver
+ *         );
+ *
+ *         // 3. Save to GunDB
+ *         await this.shogun.db.user.get('messages/...').put({
+ *             content: encrypted,
+ *             from: this.shogun.db.user.is.pub,
+ *             to: recipientUsername,
+ *             timestamp: Date.now().toString()
+ *         });
+ *
+ *         return { success: true, messageId: '...' };
+ *     }
+ * }
+ * ```
+ */

package/dist/types/{index.d.ts → src/index.d.ts}

@@ -7,7 +7,10 @@ import Gun from "./gundb/db";
 export * from "./utils/errorHandler";
 export * from "./plugins";
 export * from "./interfaces/shogun";
-export type * from "./interfaces/plugin";
 export * from "./config/simplified-config";
+export type * from "./interfaces/plugin";
+export { SHIP_01 } from "../ship/implementation/SHIP_01";
+export type { ISHIP_01 } from "../ship/interfaces/ISHIP_01";
+export { MessengerCLI } from "../ship/examples/messenger-cli";
 export type { IGunUserInstance, IGunInstance, GunDataEventData, GunPeerEventData, DeriveOptions, TypedGunOperationResult, TypedAuthResult, };
 export { Gun, ShogunCore, SEA, RxJS, crypto, derive, GunErrors, DataBase, SimpleGunAPI, QuickStart, quickStart, createSimpleAPI, AutoQuickStart, autoQuickStart, };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shogun-core",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "description": "SHOGUN CORE - Core library for Shogun Ecosystem",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -82,6 +82,7 @@
     "stream-browserify": "^3.0.0",
     "ts-jest": "^29.3.2",
     "ts-loader": "^9.5.1",
+    "tsx": "^4.20.6",
     "typedoc": "^0.27.9",
     "typescript": "^5.3.3",
     "util": "^0.12.5",