shogun-core 3.3.4 → 3.3.5

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

@@ -1,224 +1,313 @@
 /**
- * SHIP-06: Ephemeral P2P Messaging Interface
+ * SHIP-06: Secure Vault 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
+ * @title ISHIP_06 - 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 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!)
+ * 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
  *
- * - 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)
+ * - ISHIP_00: Identity and authentication layer
+ * - GunDB: P2P storage
+ * - SEA: Cryptography (AES-256-GCM)
  *
  * ## Inspiration
  *
- * Based on Bugoff (https://github.com/draeder/bugoff)
- * Simplified for Gun relay instead of WebRTC
+ * Based on Gunsafe (https://github.com/draeder/gunsafe)
+ * Adapted for Shogun ecosystem with SHIP-00 integration
  */
-import type { SEAPair } from "./ISHIP_00";
+import type { ISHIP_00 } from "./ISHIP_00";
+/**
+ * @notice Vault record structure
+ */
+export interface VaultRecord {
+    name: string;
+    data: any;
+    created: number;
+    updated: number;
+    deleted: boolean;
+    metadata?: RecordMetadata;
+}
+/**
+ * @notice Encrypted record (stored in GunDB)
+ */
+export interface EncryptedRecord {
+    data: string;
+    created: string;
+    updated: string;
+    deleted: boolean;
+    metadata?: string;
+}
+/**
+ * @notice Record metadata
+ */
+export interface RecordMetadata {
+    type?: string;
+    description?: string;
+    tags?: string[];
+    expiresAt?: number;
+    [key: string]: any;
+}
+/**
+ * @notice Vault operation result
+ */
+export interface VaultResult {
+    success: boolean;
+    error?: string;
+    recordName?: string;
+    recordCount?: number;
+}
+/**
+ * @notice Vault statistics
+ */
+export interface VaultStats {
+    totalRecords: number;
+    activeRecords: number;
+    deletedRecords: number;
+    totalSize: number;
+    created: number;
+    lastModified: number;
+    recordsByType?: Record<string, number>;
+}
 /**
- * @notice Ephemeral message structure
+ * @notice Options for retrieving records
  */
-export interface EphemeralMessage {
-    from: string;
-    fromPubKey: string;
-    content: string;
-    timestamp: number;
-    type: "broadcast" | "direct";
+export interface GetOptions {
+    includeDeleted?: boolean;
+    decrypt?: boolean;
 }
 /**
- * @notice Encrypted message data (internal)
+ * @notice Options for listing records
  */
-export interface EncryptedMessageData {
-    content: string;
-    fromPubKey: string;
-    timestamp: string;
-    type: "broadcast" | "direct";
+export interface ListOptions {
+    includeDeleted?: boolean;
+    filterByTag?: string;
+    filterByType?: string;
+    sortBy?: "name" | "created" | "updated";
+    sortDesc?: boolean;
 }
 /**
- * @notice Peer information
+ * @notice Options for importing vault
  */
-export interface PeerInfo {
-    address: string;
-    pubKey?: string;
-    epub?: string;
-    connectedAt: number;
+export interface ImportOptions {
+    merge?: boolean;
+    overwrite?: boolean;
+    skipDeleted?: boolean;
 }
 /**
- * @title ISHIP_06 - Ephemeral P2P Messaging
- * @notice Main interface for ephemeral messaging system
- * @dev Can work standalone (array of peers) OR with ISHIP_00 identity
+ * @notice Options for exporting vault
+ */
+export interface ExportOptions {
+    includeDeleted?: boolean;
+    pretty?: boolean;
+    filterByTag?: string;
+    filterByType?: string;
+}
+/**
+ * @title ISHIP_07 - Secure Vault
+ * @notice Main interface for secure encrypted vault
+ * @dev Depends on ISHIP_00 for all identity and encryption operations
  *
- * Constructor patterns:
+ * Constructor pattern:
  * ```typescript
- * // Standalone mode (no authentication)
- * class EphemeralMessaging implements ISHIP_06 {
- *     constructor(
- *         peers: string[],           // Gun relay peers
- *         roomId: string,
- *         config?: { debug?: boolean }
- *     ) {}
- * }
- *
- * // Identity mode (with SHIP-00)
- * class EphemeralMessaging implements ISHIP_06 {
- *     constructor(
- *         identity: ISHIP_00,        // Authenticated identity
- *         roomId: string,
- *         config?: EphemeralConfig
- *     ) {}
+ * class SecureVault implements ISHIP_07 {
+ *     constructor(private identity: ISHIP_00) {}
  * }
  * ```
  */
 export interface ISHIP_06 {
     /**
-     * @notice Connect to ephemeral swarm
-     * @dev Joins WebTorrent swarm and establishes P2P connections
-     *
-     * Flow:
-     * 1. Hash room ID with SHA-256 for swarm identifier
-     * 2. Join WebTorrent swarm with hashed ID
-     * 3. Listen for peer connections
-     * 4. Exchange SEA public keys with peers
-     * 5. Establish encrypted channels
-     */
-    connect(): Promise<void>;
-    /**
-     * @notice Disconnect from swarm
-     * @dev Closes all P2P connections and leaves swarm
-     */
-    disconnect(): void;
-    /**
-     * @notice Check if connected to swarm
-     * @return True if connected
+     * @notice Get the identity provider
+     * @dev Returns the ISHIP_00 instance used for identity operations
+     * @return Identity provider instance
      */
-    isConnected(): boolean;
+    getIdentity(): ISHIP_00;
     /**
-     * @notice Get swarm identifier (SHA-256 hash of room ID)
-     * @return Hashed swarm identifier
+     * @notice Initialize vault
+     * @dev Sets up vault node structure in user's Gun space
+     *
+     * Prerequisites:
+     * - User must be authenticated (via ISHIP_00)
+     *
+     * Flow:
+     * 1. Verify user authentication
+     * 2. Create vault node structure
+     * 3. Initialize metadata
      */
-    getSwarmId(): string;
+    initialize(): Promise<void>;
     /**
-     * @notice Get own peer address in swarm
-     * @return Peer address
+     * @notice Check if vault is initialized
+     * @return True if vault is initialized
      */
-    getAddress(): string;
+    isInitialized(): boolean;
     /**
-     * @notice Send broadcast message to all peers in swarm
-     * @dev Message is encrypted with each peer's public key
-     * @param message Plain text message content
+     * @notice Store encrypted record in vault
+     * @dev Encrypts data with SEA and stores in user's vault node
+     * @param name Record name/key (must be unique)
+     * @param data Data to encrypt and store (any type)
+     * @param metadata Optional metadata
+     * @return Operation result
      *
      * Prerequisites:
-     * - Must be connected to swarm
-     * - User must be authenticated (via ISHIP_00)
+     * - Vault must be initialized
+     * - User must be authenticated
      *
      * Flow:
-     * 1. Get all connected peers
-     * 2. For each peer:
-     *    a. Derive shared secret (ECDH)
-     *    b. Encrypt message
-     *    c. Send via WebRTC data channel
+     * 1. Validate record name
+     * 2. Encrypt data with SEA
+     * 3. Encrypt metadata if provided
+     * 4. Store in gun.user().get('vault').get('records').get(name)
+     * 5. Update vault metadata
      */
-    sendBroadcast(message: string): Promise<void>;
+    put(name: string, data: any, metadata?: RecordMetadata): Promise<VaultResult>;
     /**
-     * @notice Send direct message to specific peer
-     * @dev Message encrypted only for target peer
-     * @param peerAddress Target peer address
-     * @param message Plain text message content
+     * @notice Retrieve and decrypt record from vault
+     * @dev Retrieves and decrypts record from user's vault node
+     * @param name Record name/key
+     * @param options Retrieval options
+     * @return Decrypted record or null if not found
      *
      * Prerequisites:
-     * - Must be connected to swarm
-     * - Target peer must be connected
-     * - User must be authenticated (via ISHIP_00)
+     * - Vault must be initialized
+     * - User must be authenticated
      *
      * Flow:
-     * 1. Get target peer's public key
-     * 2. Derive shared secret (ECDH)
-     * 3. Encrypt message
-     * 4. Send via WebRTC data channel
+     * 1. Retrieve encrypted record from Gun
+     * 2. Decrypt data with SEA
+     * 3. Decrypt metadata if present
+     * 4. Return decrypted record
      */
-    sendDirect(peerAddress: string, message: string): Promise<void>;
+    get(name: string, options?: GetOptions): Promise<VaultRecord | null>;
     /**
-     * @notice Listen for decrypted messages
-     * @dev Automatically decrypts received messages
-     * @param callback Called for each received message
+     * @notice Delete record from vault (soft delete)
+     * @dev Marks record as deleted without removing data
+     * @param name Record name/key (optional - deletes all if omitted)
+     * @return Operation result
      *
-     * Prerequisites:
-     * - Must be connected to swarm
+     * Soft Delete:
+     * - Record data remains encrypted in Gun
+     * - Marked as deleted (deleted: true)
+     * - Can be recovered before compaction
+     * - Not returned by default in list/get
+     */
+    delete(name?: string): Promise<VaultResult>;
+    /**
+     * @notice List all record names in vault
+     * @dev Returns array of record names matching criteria
+     * @param options List options
+     * @return Array of record names
      *
-     * Decryption flow:
-     * 1. Receive encrypted message via WebRTC
-     * 2. Retrieve sender's epub from message
-     * 3. Derive shared secret (ECDH)
-     * 4. Decrypt message content
-     * 5. Call callback with decrypted message
+     * Flow:
+     * 1. Retrieve all records from vault node
+     * 2. Apply filters (deleted, tags, type)
+     * 3. Sort if requested
+     * 4. Return record names
      */
-    onMessage(callback: (message: EphemeralMessage) => void): void;
+    list(options?: ListOptions): Promise<string[]>;
     /**
-     * @notice Listen for encrypted messages (debugging)
-     * @dev Raw encrypted messages before decryption
-     * @param callback Called for each encrypted message
+     * @notice Check if record exists
+     * @param name Record name/key
+     * @return True if record exists (and not deleted)
      */
-    onEncryptedMessage(callback: (address: string, data: any) => void): void;
+    exists(name: string): Promise<boolean>;
     /**
-     * @notice Listen for peer join events
-     * @dev Called when a new peer connects to swarm
-     * @param callback Called with peer address
+     * @notice Update existing record
+     * @dev Updates record data and timestamp
+     * @param name Record name/key
+     * @param data New data
+     * @return Operation result
+     *
+     * Flow:
+     * 1. Check if record exists
+     * 2. Encrypt new data
+     * 3. Update record with new data
+     * 4. Update timestamp
      */
-    onPeerSeen(callback: (address: string) => void): void;
+    update(name: string, data: any): Promise<VaultResult>;
     /**
-     * @notice Listen for peer leave events
-     * @dev Called when a peer disconnects from swarm
-     * @param callback Called with peer address
+     * @notice Export entire vault (encrypted)
+     * @dev Exports all vault records as encrypted JSON string
+     * @param password Optional additional encryption password
+     * @param options Export options
+     * @return Encrypted vault backup as string
+     *
+     * Flow:
+     * 1. Retrieve all records
+     * 2. Optionally filter records
+     * 3. Serialize to JSON
+     * 4. Optionally encrypt with additional password
+     * 5. Return as base64 string
+     */
+    export(password?: string, options?: ExportOptions): Promise<string>;
+    /**
+     * @notice Import vault from backup
+     * @dev Imports and decrypts vault backup
+     * @param backupData Exported vault data
+     * @param password Optional decryption password
+     * @param options Import options
+     * @return Operation result
+     *
+     * Flow:
+     * 1. Decode base64 backup
+     * 2. Decrypt with password if provided
+     * 3. Parse JSON
+     * 4. For each record:
+     *    - Check if exists (if merge mode)
+     *    - Import or skip based on options
+     * 5. Update vault metadata
      */
-    onPeerLeft(callback: (address: string) => void): void;
+    import(backupData: string, password?: string, options?: ImportOptions): Promise<VaultResult>;
     /**
-     * @notice Get list of connected peers
-     * @return Array of peer addresses
+     * @notice Get vault statistics
+     * @dev Returns statistics about vault contents
+     * @return Vault statistics
      */
-    getPeers(): string[];
+    getStats(): Promise<VaultStats>;
     /**
-     * @notice Get detailed peer information
-     * @param address Peer address
-     * @return Peer info or null if not found
+     * @notice Clear all records (soft delete all)
+     * @dev Marks all records as deleted
+     * @return Operation result
      */
-    getPeerInfo(address: string): PeerInfo | null;
+    clear(): Promise<VaultResult>;
     /**
-     * @notice Get current ephemeral SEA pair
-     * @dev New pair generated per session for perfect forward secrecy
-     * @return SEA key pair
+     * @notice Compact vault (remove deleted records permanently)
+     * @dev Permanently removes soft-deleted records
+     * @return Operation result
+     *
+     * ⚠️ WARNING:
+     * - This operation is irreversible
+     * - Deleted records cannot be recovered after compaction
      */
-    getEphemeralPair(): Promise<SEAPair>;
+    compact(): Promise<VaultResult>;
     /**
-     * @notice Manually set SEA pair (optional)
-     * @dev By default, SHIP-06 generates ephemeral pair automatically
-     * @param pair SEA key pair
+     * @notice Search records by content
+     * @dev Searches decrypted content (expensive operation)
+     * @param query Search query
+     * @return Array of matching record names
      */
-    setEphemeralPair(pair: SEAPair): Promise<void>;
+    search(query: string): Promise<string[]>;
 }
 /**
- * @notice Ephemeral messaging configuration
+ * @notice Vault configuration
  */
-export interface EphemeralConfig {
+export interface VaultConfig {
+    /**
+     * @notice Identity provider (SHIP-00 instance)
+     */
+    identity: ISHIP_00;
     /**
-     * @notice Room identifier (will be hashed)
+     * @notice Vault node name in Gun (default: "vault")
      */
-    roomId: string;
+    vaultNodeName?: string;
     /**
      * @notice Enable debug logging
      */
@@ -227,59 +316,60 @@ export interface EphemeralConfig {
      * @notice Operation timeout (ms)
      */
     timeout?: number;
+    /**
+     * @notice Enable automatic backup
+     */
+    autoBackup?: boolean;
+    /**
+     * @notice Backup interval (ms)
+     */
+    backupInterval?: number;
 }
 /**
- * @notice Event emitter interface for SHIP-06
+ * @notice Event emitter interface for SHIP-07
  */
-export interface ISHIP_06Events {
+export interface ISHIP_07Events {
     /**
-     * Emitted when connected to swarm
+     * Emitted when vault is initialized
      */
-    connected: () => void;
+    initialized: () => void;
     /**
-     * Emitted when disconnected from swarm
+     * Emitted when record is added
      */
-    disconnected: () => void;
+    recordAdded: (name: string) => void;
     /**
-     * Emitted when a peer joins
+     * Emitted when record is updated
      */
-    peerSeen: (address: string) => void;
+    recordUpdated: (name: string) => void;
     /**
-     * Emitted when a peer leaves
+     * Emitted when record is deleted
      */
-    peerLeft: (address: string) => void;
+    recordDeleted: (name: string) => void;
     /**
-     * Emitted when a message is received and decrypted
+     * Emitted when vault is exported
      */
-    message: (message: EphemeralMessage) => void;
+    exported: (size: number) => void;
     /**
-     * Emitted when an encrypted message is received (before decryption)
+     * Emitted when vault is imported
      */
-    encryptedMessage: (address: string, data: any) => void;
+    imported: (recordCount: number) => void;
     /**
      * Emitted on error
      */
     error: (error: Error) => void;
 }
 /**
- * Example of how to implement ISHIP_06 with ISHIP_00 dependency
+ * Example of how to implement ISHIP_07 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
- *     ) {
+ * 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');
  *         }
@@ -289,82 +379,144 @@ export interface ISHIP_06Events {
  *         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);
+ *     async initialize(): Promise<void> {
+ *         // Get Gun user node
+ *         const gun = this.identity.shogun.db.gun;
+ *         this.vaultNode = gun.user().get('vault').get('records');
  *
- *         // 5. Listen for events
- *         this.bugout.on('seen', (address: string) => {
- *             this.handlePeerSeen(address);
+ *         // Initialize vault metadata
+ *         await gun.user().get('vault').get('metadata').put({
+ *             version: '1.0.0',
+ *             created: Date.now().toString()
  *         });
  *
- *         this.bugout.on('decrypted', (address: string, pubkeys: any, message: string) => {
- *             this.handleMessage(address, pubkeys, message);
- *         });
+ *         this.initialized = true;
  *     }
  *
- *     disconnect(): void {
- *         if (this.bugout) {
- *             this.bugout.destroy();
- *         }
+ *     isInitialized(): boolean {
+ *         return this.initialized;
  *     }
  *
- *     async sendBroadcast(message: string): Promise<void> {
- *         if (!this.bugout) {
- *             throw new Error('Not connected to swarm');
+ *     async put(name: string, data: any, metadata?: RecordMetadata): Promise<VaultResult> {
+ *         if (!this.initialized) {
+ *             return { success: false, error: 'Vault not initialized' };
  *         }
  *
- *         this.bugout.send(message);
+ *         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 sendDirect(peerAddress: string, message: string): Promise<void> {
- *         if (!this.bugout) {
- *             throw new Error('Not connected to swarm');
+ *     async get(name: string, options?: GetOptions): Promise<VaultRecord | null> {
+ *         if (!this.initialized) {
+ *             return null;
  *         }
  *
- *         this.bugout.send(peerAddress, message);
+ *         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;
+ *         }
  *     }
  *
- *     onMessage(callback: (message: EphemeralMessage) => void): void {
- *         this.messageCallbacks.push(callback);
+ *     async delete(name?: string): Promise<VaultResult> {
+ *         // Implementation here
+ *         return { success: true };
  *     }
  *
- *     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));
+ *     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 ephemeral = new EphemeralMessaging(identity, 'my-room');
- * await ephemeral.connect();
+ * const vault = new SecureVault(identity);
+ * await vault.initialize();
  *
- * ephemeral.onMessage((msg) => {
- *     console.log(`${msg.from}: ${msg.content}`);
+ * // Store encrypted data
+ * await vault.put('my-password', 'super_secret', {
+ *     type: 'password',
+ *     description: 'GitHub password'
  * });
  *
- * await ephemeral.sendBroadcast('Hello everyone!');
+ * // Retrieve decrypted data
+ * const record = await vault.get('my-password');
+ * console.log('Password:', record?.data);
  * ```
  */