From 114cb73ef512cc4b6c31fc2f8e0a39aa1e5c000f Mon Sep 17 00:00:00 2001
From: "rabble (aider)" <evan@protest.net>
Date: Mon, 9 Dec 2024 22:40:07 +1300
Subject: [PATCH] docs: Add comments to explain purpose and functionality of
 source files

---
 src/client.ts         | 11 +++++++++++
 src/commands/add.ts   |  8 ++++++++
 src/commands/setup.ts |  8 +++++++-
 src/commands/start.ts |  8 ++++++++
 src/config/index.ts   |  8 +++++++-
 src/config/keys.ts    | 17 +++++++++++++++++
 6 files changed, 58 insertions(+), 2 deletions(-)

diff --git a/src/client.ts b/src/client.ts
index 0fcad60..0b0deca 100644
--- a/src/client.ts
+++ b/src/client.ts
@@ -1,3 +1,14 @@
+/**
+ * CLI client for interacting with nsecBunker
+ * Supports:
+ * - Signing events (NIP-46)
+ * - Creating new accounts
+ * - Managing authorization flows
+ * - Publishing to relays
+ * 
+ * Uses NDK for Nostr protocol interactions
+ */
+
 import "websocket-polyfill";
 import NDK, { NDKUser, NDKEvent, NDKPrivateKeySigner, NDKNip46Signer, NostrEvent } from '@nostr-dev-kit/ndk';
 import fs from 'fs';
diff --git a/src/commands/add.ts b/src/commands/add.ts
index 1b21200..1b19515 100644
--- a/src/commands/add.ts
+++ b/src/commands/add.ts
@@ -1,3 +1,11 @@
+/**
+ * Command to add a new encrypted nsec to the bunker
+ * Handles:
+ * - Prompting for passphrase and nsec
+ * - Encrypting and storing the nsec in config
+ * - Validation of provided nsec format
+ */
+
 import {nip19} from 'nostr-tools';
 import readline from 'readline';
 import { getCurrentConfig, saveCurrentConfig } from '../config/index.js';
diff --git a/src/commands/setup.ts b/src/commands/setup.ts
index e523255..2bc8ebb 100644
--- a/src/commands/setup.ts
+++ b/src/commands/setup.ts
@@ -1,3 +1,9 @@
+/**
+ * Initial setup command for nsecBunker
+ * Configures the first administrator npub that will have 
+ * remote control access to the bunker
+ */
+
 import readline from 'readline';
 import { getCurrentConfig, saveCurrentConfig } from '../config/index.js';
 
@@ -18,4 +24,4 @@ export async function setup(config: string) {
 
         console.log(`Administrator npub added!`);
     });
-}
\ No newline at end of file
+}
diff --git a/src/commands/start.ts b/src/commands/start.ts
index 0c7f835..121ae89 100644
--- a/src/commands/start.ts
+++ b/src/commands/start.ts
@@ -1,3 +1,11 @@
+/**
+ * Command to start the nsecBunker daemon
+ * Handles:
+ * - Loading and decrypting keys
+ * - Publishing NIP-89 announcements for configured domains
+ * - Starting the daemon process with loaded configuration
+ */
+
 import readline from 'readline';
 import { DomainConfig, IConfig, getCurrentConfig, saveCurrentConfig } from '../config/index.js';
 import { decryptNsec } from '../config/keys.js';
diff --git a/src/config/index.ts b/src/config/index.ts
index db819f6..deeda69 100644
--- a/src/config/index.ts
+++ b/src/config/index.ts
@@ -1,3 +1,9 @@
+/**
+ * Configuration management for nsecBunker
+ * Handles reading/writing config files and provides type definitions
+ * for the configuration schema
+ */
+
 import { readFileSync, writeFileSync } from 'fs';
 import { NDKPrivateKeySigner, NDKUserProfile } from '@nostr-dev-kit/ndk';
 import { IAdminOpts } from '../daemon/admin';
@@ -95,4 +101,4 @@ export function saveCurrentConfig(config: string, currentConfig: any) {
     }
 }
 
-export {getCurrentConfig};
\ No newline at end of file
+export {getCurrentConfig};
diff --git a/src/config/keys.ts b/src/config/keys.ts
index 38b5cdd..ca2d900 100644
--- a/src/config/keys.ts
+++ b/src/config/keys.ts
@@ -1,5 +1,15 @@
 import crypto from 'crypto';
 
+/**
+ * Encryption utilities for securely storing nsec (private keys)
+ */
+
+/**
+ * Encrypts an nsec using AES-256-CBC with a key derived from the passphrase
+ * @param nsec - The private key to encrypt
+ * @param passphrase - User provided passphrase to derive encryption key
+ * @returns Object containing initialization vector and encrypted data as hex strings
+ */
 export function encryptNsec(nsec: string, passphrase: string): { iv: string, data: string } {
     const algorithm = 'aes-256-cbc';
     const key = crypto.createHash('sha256').update(passphrase).digest();
@@ -14,6 +24,13 @@ export function encryptNsec(nsec: string, passphrase: string): { iv: string, dat
     };
 }
 
+/**
+ * Decrypts an encrypted nsec using the original passphrase
+ * @param iv - Initialization vector as hex string
+ * @param data - Encrypted data as hex string  
+ * @param passphrase - Original passphrase used for encryption
+ * @returns Decrypted nsec string
+ */
 export function decryptNsec(iv: string, data: string, passphrase: string): string {
     const algorithm = 'aes-256-cbc';
     const key = crypto.createHash('sha256').update(passphrase).digest();