Secure CLI Library Management System (LMS)

A highly secure, portable, and scalable Command Line Interface (CLI) Library Management System. Designed to handle >1,000,000 records with zero plaintext data at rest.

Features & Security

• Key Derivation
  Argon2id (Memory-hard, resistant to GPU cracking).
• Encryption
  AES-256-GCM (Authenticated encryption).
• Storage
  Indexed binary storage (index.bin and data.bin) with O(1) lookup performance.
• Memory Safety
  Strict memory wiping (Arrays.fill) for all cryptographic material before Garbage Collection.
• Concurrency
  Safe concurrent executions via FileChannel exclusive/shared locking.

Prerequisites

• Java 25 or higher.
• Maven 3.9+ (for building from source).

Dependency Table

Library Name	Version	Scope	Purpose / What it does
picocli	4.7.7	Main	Helps build the text-typing screen (CLI) so the computer can read and understand commands like lms add or lms init.
protobuf-java	4.35.0	Main	Shrinks and packs your book records into a very small, tight format before saving them to the computer's hard drive.
bcprov-jdk18on (Bouncy Castle)	1.84	Main	Provides the security tools needed to lock up your data safely using your password.
junit-jupiter-api	6.1.0	Test	Provides the basic rules and structure for writing automatic check-up code.
junit-jupiter-engine	6.1.0	Test	The main engine that runs and executes all the automatic check-up code to see if the program works.
jqwik	1.10.1	Test	Automatically invents hundreds of random fake book details to test if your program crashes under strange inputs.
jmh-core	1.37	Test	The core tool used to measure the exact speed and response time of your storage code.
jmh-generator-annprocess	1.37	Test	Helps process behind-the-scenes settings so the speed-measuring tool (JMH Core) can read your setup correctly.

Architecture

+-------------------------------------------------------+
|                        USER                           |
+-------------------------------------------------------+
                           |
                           v
+-------------------------------------------------------+
|                  COMMAND LAYER (CLI)                  |
|  - Init Command      - Borrow Command (Checkout)      |
|  - Add Command       - Return Command (Return)        |
|  - Search Command                                     |
+-------------------------------------------------------+
          |                               |
          v                               v
+------------------+             +----------------+
| RULES LAYER      |             | SECRET ENGINE  |
| (LibraryService) |             | (CryptoEngine) |
+------------------+             +----------------+
          |                               ^
          v                               |
+-------------------------------------------------------+
|               STORAGE LAYER (Storage)                 |
| (SecureFileStorageManager - Packs data and asks the   |
| Secret Engine to lock it up)                          |
+-------------------------------------------------------+
                           |
                           v
+-------------------------------------------------------+
|            DATABASE FILES ON THE COMPUTER             |
|  A folder named "storage/":                           |
|  - salt.bin (Random code to protect passwords)        |
|  - index.bin (Quick list notebook for fast finding)   |
|  - data.bin (Where books are stored and locked tight) |
+-------------------------------------------------------+

Installation

1. Clone the repository:

   git clone https://github.com/your-org/secure-cli-lms.git
   cd secure-cli-lms

2. Build the executable Fat JAR:

   mvn clean package

3. The executable will be located at target/secure-cli-lms-1.0.0-SNAPSHOT.jar.

Usage Guide

You can run the CLI using the java -jar command. For convenience, you can alias it:

alias lms="java -jar target/secure-cli-lms-1.0.0-SNAPSHOT.jar"

Initialize the Database

Generates the cryptographic salt and initializes the storage files.

lms init -p

Add a Book

Encrypts and appends a new book record to the database.

lms add -p --id "B001" --title "Effective Java" --author "Joshua Bloch" --isbn "978-0134685991" --year 2018

Search, Checkout, and Return

lms search -p --id "B001"
lms checkout -p --id "B001"
lms return -p --id "B001"

Available Commands

Once running, use the following commands in the prompt:

• lms init
  Creates a new storage folder on your computer and generates the random password-protection file (salt.bin).
• lms add
  Adds a new book to the library and immediately locks it tight using your password.
• lms checkout
  Borrows a book from the library after the program checks that the book exists and is not currently borrowed by anyone else.
• lms return
  Returns a book you have finished borrowing so that its status becomes available in the library again.
• lms search
  Searches for and views book data in the library very quickly using the quick list file (index.bin).

Development & Validation

This project enforces strict validation pipelines:

• Formatting: mvn spotless:check
• Static Analysis: mvn spotbugs:check
• Testing & Coverage: mvn test jacoco:check (Target: >= 85%)
• Documentation: mvn javadoc:javadoc (Strict HTML5 extraction)

Benchmark Results Table

Benchmark Name	Test Mode	Average Time (Score)	Error Margin	Time Unit
CryptoBenchmark.benchmarkChunkDecrypt	avgt (Average Time)	0.008	± 0.021	ms/op (Milliseconds per operation)
CryptoBenchmark.benchmarkKeyDerivation	avgt (Average Time)	371.996	± 138.252	ms/op (Milliseconds per operation)
StorageBenchmark.benchmarkIndexLookupAndDecrypt	avgt (Average Time)	0.395	± 0.537	ms/op (Milliseconds per operation)

Tested on Microsoft Windows 11 IoT Enterprise (Build 26200), LENOVO 2347B16 (Intel Core i5-3320M @ 2.60GHz), Java 25 (OpenJDK 25)

License

Distributed under the MIT License. See LICENSE for details.

Contributing

Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.