Code Structure

The qib13 project is a self-contained, single-page web application. Its entire functionality—UI, styling, and logic—is encapsulated within the index.html file. This monolithic structure, while unconventional for larger projects, provides portability and simplifies deployment, allowing the tool to be run offline directly from the file. The README.md file provides high-level documentation, security analysis, and usage examples.

The JavaScript code within index.html is logically organized into several distinct components: a cryptographic random number generator (RNG), a core EncodingSystem class that defines the algebraic transformations, functions for generating and managing these systems, and a UI layer that handles user interaction and DOM manipulation.

File Organization

The project consists of a primary HTML file containing all code and a documentation file.

Sources: README.md, index.html

index.html - The Monolithic Application

This file is the heart of the project, containing three distinct types of code: HTML, CSS, and JavaScript.

HTML Structure

The user interface is defined using standard HTML elements and is organized into a tabbed layout. This allows the user to switch between the four main functionalities of the application.

• Tabs: The UI is divided into four tabs: "Generate Systems", "Generate Seed", "Recover Code", and "Batch Test".
• Inputs: Key inputs include text fields for the masterSeed, generatorCodeInput, and seedInput.
• Controls: Buttons trigger the main functions like generateSystems(), generateSeed(), and recoverGeneratorCode().
• Outputs: Results are displayed in designated div elements, such as generateResult and recoverResult.

This diagram shows the main components of the user interface defined in the HTML.

CSS Styling

All styling is contained within a <style> block in the <head> of the document. It uses basic CSS to create a clean, functional layout. Key features include:

• A flexbox-based container for the main layout.
• Styled classes for different states: .success, .error, .warning, .info.
• Styling for UI components like buttons, inputs, tabs, and progress bars.

Sources: index.html:5-83

JavaScript Logic

The application's core logic resides within a single <script> tag. It can be broken down into several key modules.

Global State and Initialization

The script maintains a global state for the application's core data.

• allSystems: An array that stores the generated EncodingSystem objects.
• currentNumSystems: The number of deviation systems to generate.
• currentMasterSeed: The seed string used to generate the systems.

An event listener on DOMContentLoaded initializes the application by generating a default set of systems and setting up other event listeners for UI elements.

Sources: index.html:183-186, 648-652

Cryptographic RNG Module

To ensure deterministic and reproducible generation of encoding systems, a custom cryptographically secure random number generator is implemented.

• CryptoSeededRandom Class: This class uses an HMAC-SHA256 based algorithm in counter mode. It is seeded with a string and can produce a deterministic sequence of random numbers.
• Fallback Implementations: For environments without the Web Crypto API, pure JavaScript implementations of sha256 and hmac are included. The code currently defaults to this fallback to maintain synchronous behavior.
• Methods: The key methods are next() which returns a float in [0,1), and nextInt(min, max) which returns an integer in the specified range without modulo bias.

The following diagram illustrates the structure of the RNG classes.

Core Encoding Logic (EncodingSystem Class)

This class encapsulates the logic for a single encoding/decoding system.

• Properties:
  • id: A unique identifier for the system.
  • type: Either 'original' or 'deviation'.
  • matrices: An object containing the parity-check matrices (P for original, P1 and P2 for deviation).
  • permutation: An array defining the permutation applied to the codeword.
  • inversePermutation: The inverse of the permutation, for decoding.
• Methods:
  • generateSeed(generatorCode): Encodes a 13-letter code into a 55-letter seed.
  • recoverGeneratorCode(seed): Attempts to decode a 55-letter seed back into a 13-letter code. It throws an error if parity checks fail.

The class diagram below shows the structure of EncodingSystem.

System Generation and Management

These functions create and manage the EncodingSystem instances.

• generateSystems(): The main function triggered by the user. It takes a masterSeed and a number of systems N, then generates 1 "original" system and N "deviation" systems.
• createOriginalSystem(id, seed): Creates an EncodingSystem of type original.
• createDeviationSystem(id, seed): Creates an EncodingSystem of type deviation.
• generateRandomMatrix(rows, cols, rng): Uses the seeded RNG to create a matrix with random integer elements [0-25].
• generateRandomPermutation(n, rng): Uses the Fisher-Yates shuffle algorithm with the seeded RNG to create a reproducible permutation.

The flow for generating systems is shown below.

UI Interaction and Application Flow

These functions connect the user interface to the core logic.

• generateSeed(): Reads the generator code and selected mode, chooses the appropriate EncodingSystem, calls its generateSeed method, and displays the result.
• recoverGeneratorCode(): Reads the seed and selected mode. In "Sequential" mode, it iterates through allSystems, calling recoverGeneratorCode on each until one succeeds. In other modes, it tries only the specified system(s).
• runBatchTest(): Runs a series of automated tests by generating random codes, encoding them with random systems, and then attempting sequential recovery to verify the integrity of the process.

The sequence diagram for recovering a generator code demonstrates this interaction.

Data Flow

The transformation of data from a generator code to a seed and back is the central process of the application.

Seed Generation Flow

This diagram shows how a 13-character generator code is encoded into a 55-character seed.

Code Recovery Flow

This diagram illustrates the reverse process: recovering the generator code from a seed.

Conclusion

The code structure of qib13 is a practical implementation of a monolithic single-page application. Despite all code residing in index.html, the JavaScript portion exhibits a clear, logical separation of concerns. It is organized into a cryptographic RNG for determinism, a powerful EncodingSystem class for the core algebraic logic, a set of functions for managing system generation, and a final layer for handling UI events. This modular design within a single file makes the code understandable and maintainable while preserving the project's goal of creating a simple, portable, and secure tool.