shogun-core 3.2.2 → 3.3.0

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

@@ -0,0 +1,295 @@
+/**
+ * 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
+ * );
+ * ```
+ */
+/**
+ * @notice Dual stealth keys (viewing + spending)
+ */
+export interface StealthKeys {
+    viewingKey: {
+        publicKey: string;
+        privateKey: string;
+    };
+    spendingKey: {
+        publicKey: string;
+        privateKey: string;
+    };
+}
+/**
+ * @notice Ephemeral key pair for stealth generation
+ */
+export interface EphemeralKeyPair {
+    publicKey: string;
+    privateKey: string;
+}
+/**
+ * @notice Stealth address generation result
+ */
+export interface StealthAddressResult {
+    success: boolean;
+    stealthAddress?: string;
+    ephemeralPublicKey?: string;
+    viewTag?: string;
+    error?: string;
+}
+/**
+ * @notice Stealth metadata for announcements (ERC-5564)
+ */
+export interface StealthMetadata {
+    ephemeralPublicKey: string;
+    viewTag: string;
+    stealthAddress: string;
+    createdAt: number;
+}
+/**
+ * @notice Announced stealth payment data
+ */
+export interface AnnouncedStealth {
+    stealthAddress: string;
+    ephemeralPublicKey: string;
+    viewTag: string;
+    schemeId: number;
+    announcer: string;
+    txHash?: string;
+}
+/**
+ * @notice Scanned stealth address that belongs to user
+ */
+export interface OwnedStealthAddress {
+    stealthAddress: string;
+    ephemeralPublicKey: string;
+    privateKey: string;
+    wallet: any;
+    metadata: StealthMetadata;
+}
+/**
+ * @notice Configuration for SHIP-03
+ */
+export interface SHIP_03_Config {
+    /** Enable ERC-5564 compatibility mode */
+    erc5564Compatible?: boolean;
+    /** Default scheme ID for ERC-5564 */
+    defaultSchemeId?: number;
+    /** Enable view tag optimization */
+    enableViewTag?: boolean;
+    /** Auto-scan for stealth addresses */
+    autoScan?: boolean;
+}
+/**
+ * @title ISHIP_03 - Dual-Key Stealth Addresses
+ * @notice Main interface for privacy-preserving stealth addresses
+ */
+export interface ISHIP_03 {
+    /**
+     * @notice Initialize the stealth address system
+     * @dev Must be called after SHIP-02 initialization
+     * @returns Promise that resolves when initialization is complete
+     */
+    initialize(): Promise<void>;
+    /**
+     * @notice Check if system is initialized
+     * @returns True if initialized, false otherwise
+     */
+    isInitialized(): boolean;
+    /**
+     * @notice Get or generate user's stealth keys (viewing + spending)
+     * @dev Keys are deterministically derived from SHIP-00 identity
+     * @returns Promise resolving to StealthKeys
+     */
+    getStealthKeys(): Promise<StealthKeys>;
+    /**
+     * @notice Get public stealth keys by username (alias)
+     * @param username User's alias/username
+     * @returns Promise resolving to public keys or null
+     */
+    getPublicStealthKeysByUsername(username: string): Promise<{
+        viewingPublicKey: string;
+        spendingPublicKey: string;
+    } | null>;
+    /**
+     * @notice Get public stealth keys for another user by Gun public key
+     * @param userPub User's SHIP-00 public key
+     * @returns Promise resolving to public keys or null
+     */
+    getPublicStealthKeys(userPub: string): Promise<{
+        viewingPublicKey: string;
+        spendingPublicKey: string;
+    } | null>;
+    /**
+     * @notice Search directory for users with published stealth keys
+     * @returns Promise resolving to array of users with stealth keys
+     */
+    searchStealthDirectory(): Promise<Array<{
+        username?: string;
+        gunPub: string;
+        viewingPublicKey: string;
+        spendingPublicKey: string;
+        timestamp?: number;
+    }>>;
+    /**
+     * @notice Export stealth keys (encrypted)
+     * @returns Promise resolving to encrypted keys JSON
+     */
+    exportStealthKeys(): Promise<string>;
+    /**
+     * @notice Import stealth keys (encrypted)
+     * @param encryptedKeys Encrypted keys JSON
+     * @returns Promise that resolves when import is complete
+     */
+    importStealthKeys(encryptedKeys: string): Promise<void>;
+    /**
+     * @notice Publish public stealth keys to Gun network
+     * @dev Makes your stealth keys discoverable by others
+     * @returns Promise that resolves when keys are published
+     */
+    publishStealthKeys(): Promise<void>;
+    /**
+     * @notice Generate ephemeral key pair for stealth address creation
+     * @returns Promise resolving to EphemeralKeyPair
+     */
+    generateEphemeralKeyPair(): Promise<EphemeralKeyPair>;
+    /**
+     * @notice Generate stealth address for a recipient
+     * @param recipientViewingKey Recipient's viewing public key
+     * @param recipientSpendingKey Recipient's spending public key
+     * @param ephemeralPrivateKey Optional ephemeral key (auto-generated if not provided)
+     * @returns Promise resolving to StealthAddressResult
+     */
+    generateStealthAddress(recipientViewingKey: string, recipientSpendingKey: string, ephemeralPrivateKey?: string): Promise<StealthAddressResult>;
+    /**
+     * @notice Generate multiple stealth addresses (batch)
+     * @param recipients Array of recipient key pairs
+     * @param ephemeralPrivateKey Optional shared ephemeral key
+     * @returns Promise resolving to array of results
+     */
+    generateMultipleStealthAddresses(recipients: Array<{
+        viewingKey: string;
+        spendingKey: string;
+    }>, ephemeralPrivateKey?: string): Promise<StealthAddressResult[]>;
+    /**
+     * @notice Open/unlock a stealth address to derive private key
+     * @param stealthAddress The stealth address to open
+     * @param ephemeralPublicKey Ephemeral public key from announcement
+     * @returns Promise resolving to wallet with stealth private key
+     */
+    openStealthAddress(stealthAddress: string, ephemeralPublicKey: string): Promise<any>;
+    /**
+     * @notice Check if a stealth address belongs to user
+     * @param stealthAddress Address to check
+     * @param ephemeralPublicKey Ephemeral public key from announcement
+     * @returns Promise resolving to boolean
+     */
+    isStealthAddressMine(stealthAddress: string, ephemeralPublicKey: string): Promise<boolean>;
+    /**
+     * @notice Get private key for owned stealth address
+     * @param stealthAddress The stealth address
+     * @param ephemeralPublicKey Ephemeral public key from announcement
+     * @returns Promise resolving to private key hex string
+     */
+    getStealthPrivateKey(stealthAddress: string, ephemeralPublicKey: string): Promise<string>;
+    /**
+     * @notice Scan announced stealth addresses for ownership
+     * @param announcements Array of announced stealth data
+     * @returns Promise resolving to owned stealth addresses
+     */
+    scanStealthAddresses(announcements: AnnouncedStealth[]): Promise<OwnedStealthAddress[]>;
+    /**
+     * @notice Quick scan using view tags (optimization)
+     * @param announcements Array with view tags
+     * @returns Promise resolving to potentially owned addresses (need full verification)
+     */
+    quickScanWithViewTags(announcements: AnnouncedStealth[]): Promise<AnnouncedStealth[]>;
+    /**
+     * @notice Create ERC-5564 announcement metadata
+     * @param stealthAddress Generated stealth address
+     * @param ephemeralPublicKey Ephemeral public key
+     * @returns StealthMetadata object
+     */
+    createAnnouncementMetadata(stealthAddress: string, ephemeralPublicKey: string): StealthMetadata;
+    /**
+     * @notice Parse announcement from transaction data
+     * @param txData Transaction data or logs
+     * @returns Promise resolving to AnnouncedStealth or null
+     */
+    parseAnnouncement(txData: any): Promise<AnnouncedStealth | null>;
+    /**
+     * @notice Get all owned stealth addresses
+     * @returns Promise resolving to array of owned stealth addresses
+     */
+    getAllOwnedStealthAddresses(): Promise<OwnedStealthAddress[]>;
+    /**
+     * @notice Clear cache and reset state
+     * @returns Promise that resolves when cleared
+     */
+    clearCache(): Promise<void>;
+    /**
+     * @notice Verify stealth address was correctly generated
+     * @param stealthAddress Address to verify
+     * @param ephemeralPublicKey Ephemeral key used
+     * @param spendingPublicKey Spending public key
+     * @returns Promise resolving to boolean
+     */
+    verifyStealthAddress(stealthAddress: string, ephemeralPublicKey: string, spendingPublicKey: string): Promise<boolean>;
+}
+export type SHIP_03_Events = {
+    stealthKeysGenerated: (keys: StealthKeys) => void;
+    stealthAddressGenerated: (result: StealthAddressResult) => void;
+    stealthAddressOpened: (wallet: any) => void;
+    stealthAddressScanned: (owned: OwnedStealthAddress[]) => void;
+    error: (error: Error) => void;
+};

package/dist/types/src/gundb/db.d.ts

@@ -29,7 +29,12 @@ declare class DataBase {
     private readonly onAuthCallbacks;
     private readonly eventEmitter;
     private _rxjs?;
-    constructor(gun: IGunInstance, appScope?: string);
+    private disableAutoRecall;
+    private silent;
+    constructor(gun: IGunInstance, appScope?: string, options?: {
+        disableAutoRecall?: boolean;
+        silent?: boolean;
+    });
     /**
      * Initialize the GunInstance asynchronously
      * This method should be called after construction to perform async operations
@@ -329,7 +334,9 @@ declare class DataBase {
     /**
      * Recall user session
      */
-    recall(): void;
+    recall(options?: {
+        sessionStorage?: boolean;
+    }): void;
     /**
      * Leave user session
      */
@@ -371,7 +378,7 @@ declare class DataBase {
      */
     isAuthenticated(): boolean;
 }
-declare const createGun: (config: any) => IGunInstance<any>;
+declare const createGun: (config: any, silent?: boolean) => IGunInstance<any>;
 export { Gun, DataBase, SEA, RxJS, crypto, GunErrors, derive, createGun };
 export default Gun;
 export type { IGunUserInstance, IGunInstance, IGunChain } from "gun/types";

package/dist/types/src/index.d.ts

@@ -9,8 +9,15 @@ export * from "./plugins";
 export * from "./interfaces/shogun";
 export * from "./config/simplified-config";
 export type * from "./interfaces/plugin";
+export { SHIP_00 } from "../ship/implementation/SHIP_00";
+export type { ISHIP_00 } from "../ship/interfaces/ISHIP_00";
 export { SHIP_01 } from "../ship/implementation/SHIP_01";
 export type { ISHIP_01 } from "../ship/interfaces/ISHIP_01";
+export { SHIP_02 } from "../ship/implementation/SHIP_02";
+export type { ISHIP_02 } from "../ship/interfaces/ISHIP_02";
+export { SHIP_03 } from "../ship/implementation/SHIP_03";
+export type { ISHIP_03 } from "../ship/interfaces/ISHIP_03";
 export { MessengerCLI } from "../ship/examples/messenger-cli";
+export { WalletCLI } from "../ship/examples/wallet-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/dist/types/src/interfaces/shogun.d.ts

@@ -185,6 +185,8 @@ export interface ShogunCoreConfig {
     plugins?: {
         autoRegister?: ShogunPlugin[];
     };
+    disableAutoRecall?: boolean;
+    silent?: boolean;
 }
 export interface ShogunEvents {
     error: (data: {

package/dist/types/src/storage/storage.d.ts

@@ -7,10 +7,11 @@ export declare class ShogunStorage {
     private store;
     private isTestMode;
     private useLocalStorage;
+    private silent;
     /**
      * Initializes storage and loads any existing keypair from localStorage if available
      */
-    constructor();
+    constructor(silent?: boolean);
     /**
      * Gets the stored keypair asynchronously
      * @returns Promise resolving to the keypair or null if not found

package/package.json

@@ -1,18 +1,18 @@
 {
   "name": "shogun-core",
-  "version": "3.2.2",
+  "version": "3.3.0",
   "description": "SHOGUN CORE - Core library for Shogun Ecosystem",
-  "main": "./dist/index.js",
-  "module": "./dist/index.js",
-  "types": "./dist/types/index.d.ts",
+  "main": "./dist/src/index.js",
+  "module": "./dist/src/index.js",
+  "types": "./dist/types/src/index.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/types/index.d.ts",
-      "import": "./dist/index.js",
-      "require": "./dist/index.js",
+      "types": "./dist/types/src/index.d.ts",
+      "import": "./dist/src/index.js",
+      "require": "./dist/src/index.js",
       "browser": "./dist/browser/shogun-core.js",
-      "default": "./dist/index.js",
-      "node": "./dist/index.js"
+      "default": "./dist/src/index.js",
+      "node": "./dist/src/index.js"
     }
   },
   "files": [
@@ -23,6 +23,13 @@
     "build:cjs": "tsc",
     "build:browser": "webpack --config webpack.config.cjs",
     "dev": "tsc --watch",
+    "identity": "tsx ship/examples/identity-cli.ts",
+    "messenger": "tsx ship/examples/messenger-cli.ts",
+    "wallet": "tsx ship/examples/wallet-cli.ts",
+    "stealth": "tsx ship/examples/stealth-cli.ts",
+    "storage": "tsx ship/examples/storage-cli.ts",
+    "ephemeral": "tsx ship/examples/ephemeral-cli.ts",
+    "vault": "tsx ship/examples/vault-cli.ts",
     "format": "prettier --write \"src/**/*.ts\"",
     "docs": "yarn typedoc --options typedoc.json",
     "prebuild": "rimraf dist",
@@ -44,22 +51,29 @@
   "author": "Scobru",
   "license": "MIT",
   "dependencies": {
+    "@fluidkey/stealth-account-kit": "^1.1.0",
     "@noble/curves": "^1.9.1",
+    "@scure/bip32": "^2.0.1",
     "assert": "^2.1.0",
     "base64url": "^3.0.1",
     "buffer": "^6.0.3",
+    "bugoff": "^0.0.9",
     "constants-browserify": "^1.0.0",
     "crypto-browserify": "^3.12.0",
     "ethers": "^6.13.5",
+    "form-data": "^4.0.4",
     "gun": "git+https://github.com/amark/gun.git",
     "keccak256": "^1.0.6",
     "nostr-tools": "^2.15.0",
     "qs": "^6.14.0",
     "rxjs": "^7.8.2",
+    "shogun-ipfs": "file:../shogun-ipfs",
     "ts-node": "^10.9.2",
     "url": "^0.11.4",
     "uuid": "^11.1.0",
     "vm-browserify": "^1.1.2",
+    "webtorrent": "^1.9.7",
+    "wrtc": "^0.4.7",
     "ws": "^8.18.3"
   },
   "devDependencies": {