update document

README.md

@@ -1,28 +1,38 @@
-# WiTTY: Web-based interactive TTY
-This program allows you to use terminal in the browser. Simply run the program and give it the command to execute when users connect via the browser. The main design goal of this tool is to help teaching courses that use Unix-like CLI environment. WiTTY has the following features that distinguish itself from other similar tools:
+<mark>**WiTTY: Web-based interactive TTY**<mark>
 
-1. It allows others to **view onging interactive sessions**. This is useful for providing live remote support and/or help (only use this after user authentication is implemented). 
+# Introduction
 
-   A challenge of this use case is that our home networks are almost always behind NAT, making it diffcult to run WiTTY as a publicly accessible server. Security is also a concern. It is generally safer to use WiTTY in a trusted environment.
+This program allows you to use terminal in the browser. Simply run the program and give it the command to execute when users connect via the browser. The design goal of this tool is to help teaching courses that use Unix-like CLI environment. WiTTY has the following features that distinguish itself from other similar tools:
 
-2. WiTTY allows users to **easily record, replay, and share console sessions** with just a few clicks. This make it a breeze to answer course-related questions, espeically with the source code. Instead of wall of text to describe their questions, students can just send a recorded session. 
+1. WiTTY allows users to **easily record, replay, and share console sessions** with just a few clicks. This make it a breeze to answer course-related questions. Instead of wall of text to describe their questions, students can just send a recorded session. 
+   
+2. It allows others to **view ongoing interactive sessions**. This is useful for providing live remote help. 
 
-   This repository contains a recorded session in the ```assets/extra``` directory ([M1NXZvHdvA8vSCKp_61e5d60f.scr](extra/M1NXZvHdvA8vSCKp_61e5d60f.scr)) that shows me upgrading pihole. Just put the file under the ```records``` directory, run the server, you should find the recording in the ```Recorded Session``` tab. 
+   >A challenge of this use case is that our home networks are almost always behind NAT, making it difficult to run WiTTY as a publicly accessible server. Security is also potentially a concern.
 
-3. More features are planned, suggestions are welcome.  
+3. Great attention has been paid to ensure the cleanses of the code. This, hopefully, provides a useful example of **Do as I say and as I do**. 
 
-You can use WiTTY to run any command line programs, such as ```bash```, ```htop```, ```vi```, ```ssh```. This following screenshot shows that three interactive session running ```zsh``` on macOS Monterey. <img src="extra/main.png" width="800px">
+# User Interface
 
-The following screenshot shows three recorded sessions. You can replay/download/delete them. 
-<img src="extra/view.png" width="800px">
+You can use WiTTY to run any command line programs, such as ```bash```, ```htop```, ```vi```, ```ssh```. This screenshot shows the main page of WiTTY after login. There are two tabs that list live and recorded sessions, respectively. You can click ```New Session``` to create a new interactive session. Click the <img src="assets/img/view.svg" width="16px"> icon of an interactive session opens a read-only view of that session. <img src="extra/main.png" width="640px">
+
+
+On the interactive terminal window, you can record an ongoing session. 
+
+<img src="extra/interactive.png" width="640px">
+
+This screenshot shows three recorded sessions, you can replay <img src="assets/img/play.svg" width="16px">, download <img src="assets/img/download.svg" width="16px">, rename <img src="assets/img/edit.svg" width="16px">, and delete <img src="assets/img/delete.svg" width="16px"> recorded session. 
+
+<img src="extra/view.png" width="640px">
 
 
 Here is a recorded session, where we domonstrate how to use the command line replay utility (in ```cmd/replay```) to replay another recorded session that sshes into a Raspberry Pi running 
-[pi-hole](https://pi-hole.net/). You can pause and seek the replay.
+[pi-hole](https://pi-hole.net/). You can fully control the playback using the progress bar.
 
 >The inception is strong with this one!
 
-<img src="extra/replay.gif?raw=true" width="800px">
+<img src="extra/replay.gif" width="550px">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
+
 
 <!-- 
 commands to create high quality gif from mkv/mp4 files
@@ -32,23 +42,23 @@ gifsicle -O3 .\output.gif -o replay.gif
 -->
 
 
-To use the program, you need to provide a TLS cert. You can request a free [Let's Encrypt](https://letsencrypt.org/) cert or use a self-signed cert. By default, WiTTY authenticate users with username and password. You can add a new user using ```witty adduser <username>```, and delete an existing user with ```witty deluser <username>```. It is also possible to disable user authentication with ```-n/-naked``` to the run command. For example, ```witty run -n zsh``` will run zsh without user authentication. 
-
 This program is written in the [go programming language](https://go.dev/), using the 
 [Gin web framework](https://github.com/gin-gonic/gin), [gorilla/websocket](https://github.com/gorilla/websocket), [pty](https://github.com/creack/pty), and the wonderful [xterm.js](https://xtermjs.org/)!
 The workflow is simple, the client will initiate a terminal 
 window (xterm.js) and create a websocket with the server, which relays the data between pty and xterm. You can customize the look and feel of the HTML pages by editing files under the ```assets``` directory.
 
+The program has been tested on Linux, WSL2, Raspberry Pi 3B (Debian), and MacOSX using Google Chrome, Firefox, and Safari.
+
 Most icons were provided by [fontawesome](https://fontawesome.com/) under this [license](https://fontawesome.com/license).
 
-## Installation
+# Installation
 
 1. Install the [go](https://go.dev/) compiler. __Make sure you have go 1.17 or higher.__ 
 2. Download the release and unzip it, or clone the repo
    
    ```git clone https://github.com/syssecfsu/witty.git```
 
-3. Go to the ```tls``` directory and create a self-signed cert
+3. WiTTY uses TLS to protect traffic. You can request a free [Let's Encrypt](https://letsencrypt.org/) cert or use a self-signed cert. Here is how to create a self-signed cert in the ```tls``` sub-directory:
    
    \# Generate a private key for a curve
 
@@ -66,26 +76,49 @@ Most icons were provided by [fontawesome](https://fontawesome.com/) under this [
    
    ```./witty adduser <username>```
 
-6. Start the server and give it the command to run. The server listens on 8080, for example:
+6. Start the server and give it the command to run. By default, the server listens on 8080 (you can override it with the ```-p/-port``` option):
    
    ```./witty run htop``` or
 
-   ```./witty run ssh <ssh_server_ip> -l <user_name>```
+   ```./witty run -p 9000 ssh <ssh_server_ip> -l <user_name>```
 
    If so desired, you can disable user authenticate with ```-n/-naked```, (not recommended) for example:
 
    ```./witty run -naked htop```    
 
-   You can also specify the port number WiTTY listens on with ```-p/port```. For example:
-
-   ```./witty run -p 9090 ssh 192.168.1.2```
-
-7. Connect to the server with your browser, using port 8080 or the one specified in step 6, for example
+7. Connect to the server with your browser at port 8080 or the one specified in step 6, for example
 
    ```https://<witty_server_ip>:8080```
 
-8. You can also replay the recorded sessions with witty. Set your terminal window to 120x36 before using this. 
+# User Authentication
 
-   ```./witty replay -w 500 records/<recorded file>.scr```
+WiTTY uses username/password based authentication. The user database is stored in ```user.db```. The passwords are salted with 64 bytes of random characters and then hashed using SHA256.  WiTTY has three sub-commands to manage ```user.db```. 
 
-The program has been tested on Linux, WSL2, Raspberry Pi 3B (Debian), and MacOSX using Google Chrome, Firefox, and Safari.
+   - ```witty adduser <username>```
+   - ```witty deluser <username>```
+   - ```witty listusers```
+
+They are pretty self-explanatory. Just follow the instructions on screen. Note that passwords must be 12 bytes or longer. The following screenshot shows the login screen:
+
+<img src="extra/login.png" width="320px">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
+
+
+# Recorded Sessions
+
+WiTTY provides two sub-commands to merge and replay recorded sessions. 
+
+   - ```witty replay -w <wait_time> <recorded_session>```
+   - ```witty merge -o <output_file> <record1> <record2> ...```
+
+Recorded sessions often have long delay between outputs. You can set wait_time to limit the maximum wait time between outputs, to speed up the replay. 
+
+You can also use ```witty merge``` to merge two or more recorded sessions. 
+
+The intended use case is to record a separate session for each individual task, rename and merge them into a final session for submission. 
+
+The following screenshot shows how to rename a recorded session, and combine them into the final session. 
+
+<img src="extra/rename.png" width="640px">
+
+
+<img src="extra/merge.png" width="550px">

term_conn/merge.go

@@ -4,6 +4,7 @@ import (
 	"encoding/json"
 	"log"
 	"os"
+	"strings"
 )
 
 func Merge(fnames []string, output string) {
@@ -34,5 +35,9 @@ func Merge(fnames []string, output string) {
 		return
 	}
 
+	if !strings.HasSuffix(output, ".scr") {
+		output += ".scr"
+	}
+
 	os.WriteFile(output, data, 0664)
 }

web/user.go

@@ -38,7 +38,6 @@ func addUser(username []byte, passwd []byte) {
 	file, err := os.ReadFile(userFileName)
 
 	if err != nil {
-		log.Println("Failed to read user.db file", err)
 		goto nonexist
 	}